daylight-left
How much daylight is left today, and which of your outdoor spots still fits before dark?
daylight-left is a tiny offline command-line tool. You keep a plain-text list of places you like to go (a trail loop, the community garden, an overlook) with how far away they are and how long you want there. It works out today's sunset for where you are, subtracts a 15-minute safety buffer, picks the spot that fits, tells you when to leave, and prints a short card. Then it tells you to close the laptop.
An open-weight model running locally (Gemma 3 1B, via llama.cpp) writes the one-line nudge at the bottom. Everything that has to be right, the sunset time, the minutes, the leave-by time, is computed in plain Python first. The model only writes the wording, and if it mentions any clock time that isn't in the facts it was given, the text is thrown away and a fixed line is used instead.
Built for the DEV Hacktoberfest Open-Source AI Challenge: Week 1, "Touch Grass".
Run it
python -m venv .venv && . .venv/bin/activate
pip install -e ".[llm]" # llama-cpp-python, CPU build is fine
# one-time model download (~806 MB), then it never needs the internet again
curl -L -o gemma-3-1b-it-Q4_K_M.gguf \
https://huggingface.co/ggml-org/gemma-3-1b-it-GGUF/resolve/main/gemma-3-1b-it-Q4_K_M.gguf
daylight-left --lat 42.50 --lon -90.66 --tz America/Chicago \
--spots examples/spots.txt --model gemma-3-1b-it-Q4_K_M.gguf
No model? Add --no-llm (or just leave --model off) and you get the same card with a fixed closing line. The tool itself has zero required dependencies.
spots.txt
# name | minutes away | minutes there | what you do there
Riverside trail loop | 10 | 45 | walk the loop and watch the maples turn
Community garden plot | 5 | 30 | pull the last tomatoes and mulch the beds
Real output
From logs/demo-run-gemma3-1b-2026-10-05.txt (8-CPU Linux box, no GPU, --now set so the run is reproducible):
DAYLIGHT LEFT Mon Oct 05 (America/Chicago)
sunrise 07:04 AM sunset 06:36 PM
you have 16 min of usable light (back 15 min before sunset)
GO: Block loop (0 min away, 15 min there)
stretch your legs before dinner
leave by 06:06 PM
Hey, it’s getting late – let’s go for a walk. We’ll be at the Block Loop by 06:06 PM.
Model timing on that run: load 1.0 s, generation 1.83 s, 33 tokens.
In two of the three demo runs Gemma 3 1B made up a time ("by 10:00 AM", "around 8 AM tomorrow"). The guard caught both and the card fell back to the fixed line. Those rejected outputs are kept in the log on purpose.
Tests
pip install -e ".[test]" && pytest -q
27 tests. The sunrise/sunset maths is checked against the independent astral library for five cities (Dubuque, Seattle, Quito, Sydney, Oslo) on both solstices and equinoxes plus Oct 5, to within two minutes. The hallucinated-time guard and the spot picker have their own tests.
How it works
daylight_left/sun.py: NOAA Solar Calculator equations (after Meeus, Astronomical Algorithms), pure Python, evaluated at the event time so it stays within about a minute.daylight_left/spots.py: parses your list and keeps the spots whose round trip plus stay fits the light left, longest stay first.daylight_left/llm.py: loads the GGUF with llama-cpp-python, asks for a two-sentence nudge from the computed facts, and rejects any output containing a clock time that isn't in those facts.daylight_left/cli.py: glues it together and prints the card.
Credits and licenses
- Code: MIT (see
LICENSE). - Model: Gemma 3 1B instruction-tuned, GGUF build from ggml-org/gemma-3-1b-it-GGUF, used under the Gemma Terms of Use. The model file is not in this repo.
- Runtime: llama.cpp (MIT) through llama-cpp-python (MIT).
- Also tried: SmolLM2-360M-Instruct (Apache-2.0). It just repeated the facts back verbatim (
logs/compare-smollm2-360m-2026-10-05.txt). - Test oracle: astral (Apache-2.0).
- Solar equations: NOAA Global Monitoring Laboratory solar calculator.
Built with AI coding assistance. All commits were made inside the challenge window (Oct 5 to 11, 2026); any commit after the deadline will be listed here.