Sky Quest: A Night-Sky Planner Where the Small Model Never Gets to Guess

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

The first star table my coding agent wrote for this project was wrong.

It wasn't obviously wrong. The star names were right and the numbers looked believable. I only found out because I checked every entry against the Hipparcos catalog, and most of them didn't match. I replaced them with the catalog values, and all 27 stars now pass the check.

That became the rule for the whole project:code supplies the facts, and the AI is only allowed to put them into words.

Sky Quest is an offline night-sky planner. You give it a place, a night and what you're doing, and it works out what is above you, when to step outside, and what is worth finding. Then it makes a one-page printable card, so the screen is part of your evening for about a minute, at home, and the rest happens outside.

It runs as a small local web app on your own laptop. You pick an activity, enter coordinates, and get a card:

-Stay in one place (a room, a terrace). Example user:Juvia, stuck in her cozy room with a broken telescope, looking through a window by naked eye and reading the card against the clock on her wall.

• Walk nearby. Example user: Lucy, who wanders quietly near home and wants a relaxed checklist.
• Run with stops.Example user: Natsu, an evening runner with a pocket card and one line per stop, each calculated for that stop's own place and time. -Ride in a car(as a passenger). Not built yet; it's marked "coming soon" in the app.

Each card has a depth setting (Casual, Explorer or Deep Dive), so a casual user sees five picks and not fifteen. It works at any latitude and longitude: Polaris shows up high in the north, low near the equator, and not at all in the southern hemisphere, and the card says which one applies instead of assuming where you live.

I checked the engine against Stellarium at one time on one night. The Moon, Jupiter and Saturn agreed within about 2 degrees (1.9, 1.2 and 2.1), which is well inside what you can judge by eye. I also compared the card's ISS result with a visible-passes listing for the same night. That's a single check, not a full survey, and I want to repeat it on more nights.
I took the printed card outside once and compared it with the real sky.
Demo:

To try it: python app.py, open http://127.0.0.1:8765, pick an activity, enter coordinates, and print the card. Setup steps are in the README.

I turned Wi-Fi off, loaded the local app, and generated a card. Everything the card needs is calculated on the laptop from saved data files.

Code

github:https://github.com/jef4450/sky-quest.git

How I Built It

Skyfield does the astronomy. Positions of the Moon, Jupiter, Saturn, 27 bright stars, Polaris and ISS passes are calculated offline from saved data files. A scorer ranks 15-minute slots and picks the best window to go out, and a ranking function chooses the best few objects for each card.

Gemma only writes the words. A local Gemma 3 1B model, through Ollama on my laptop, turns the calculated facts into a short introduction in a persona style. After it writes, a grounding check compares every object, direction and time in its text with the facts. If it mentions something that isn't in the facts, the app retries once. If it fails again, the card uses a plain sentence built straight from the facts, and the failure goes to a log. On my laptop the 1B model does sometimes fail the check, so the fallback is a real part of the product and not a rare edge case.

I verified the star data. A script compares each star's coordinates and brightness with the Hipparcos catalog. My first table failed most entries, and the corrected one passes 27 out of 27. One of my own specs was wrong too: it treated Hadar as one of the four Southern Cross stars, which it isn't. That's why the Southern Cross guide now depends on Acrux, Mimosa and Gacrux.

The cards are plain, printable HTML. Large type, empty tick boxes, A4 print styles, no external assets, and no tick box for anything below the horizon. Natsu's card calculates each stop at that stop's own coordinates and time, and it never shows the whole night's best window, because that would be misleading for an evening run. A small script prints every card to PDF in headless Chrome and counts the pages: all nine mode and depth combinations print on one page.

The app stays local. It binds only to 127.0.0.1, works offline, and keeps coordinates out of the cards, the facts panel and the logs. A status bar shows whether Ollama, the model and the data files are ready, and warns when the ISS data is old. There are 82 automated tests.

What went wrong.

• Lucy's card first ran past one A4 page. I assumed the layout was the problem, but the real cause was the fallback: when the model's text failed the grounding check twice, the fallback dropped the whole facts block into the card's intro. I fixed that, capped each card to the best picks, and added the page-count script.
• Natsu's card showed the whole night's best window (2:28 AM) next to evening stops. I removed it and calculated each stop on its own.
• Juvia's hourly rows used to repeat the same lines and list things below the horizon. They now show only visible objects, each once at its best time.
• DevRelay wouldn't connect in VS Code at first because my config used single backslashes in a JSON path, which is invalid.
• With Wi-Fi off, the local page wouldn't load in my main browser even though the server answered. It worked after [what you changed, for example "I used a private window"].

What's next. Car mode, an offline audio guide so the phone can stay in a pocket, a "best night this week" card, and a real sky map. None of these are built yet.

How I built it. I specified, reviewed and tested each step, and the code was written with GitHub Copilot's Agent mode.

Why Does Open Innovation Matter?

• It works offline. I turned Wi-Fi off and generated a card.
• My location stays on my machine. Coordinates are only inputs to a local calculation. They never go to a server, and the app never prints them.
• It costs nothing to run. There's no API key and there are no usage fees. The model runs on a laptop.
• I could check the model. Because Gemma runs locally, I could log every mistake and put a check around it. A closed API would have given me less to measure.

Prize Categories

• Best Use of Gemma. Gemma 3 1B runs locally through Ollama to write the card wording, inside a grounding check. -Best Use of GitHub Copilot. I built the project in GitHub Copilot's Agent mode in VS Code, and reviewed and tested what it wrote.