Inspiration
We decided to take an element from The Odyssey rather than basing the entire project on the general story. We narrowed our choices to creating an ai-prediction game based on the oracle from the story and creating a user guidance application based on Athenas guidance. We ultimately decided on the oracle game since we were fond of creating a project around something we both shared a passion for, basketball. We do not have much experience building projects, so picking an idea that appealed to us personally sounded more appealing, rather than building a project that might have a more broad audience, but would not appeal to us as much.
What it does
- Consult the Oracle: pick a game and a question (who wins, points/rebounds/assists/threes over a mark, or a triple-double). Tiresias answers with a cryptic prophecy and Athena explains the reasoning in plain English, citing the stats behind it.
- Agree or defy: each answer costs one libation (3 per day). Agreeing and being right earns 10 points; defying the Oracle and being right earns 25.
- Descend to the Underworld (replay mode): pick any past night from 2025-26 onward. The Oracle only sees data from before tip-off, and your answer is graded instantly against the real box score.
- The voyage home: climb from Castaway to Returned to Ithaca, earn badges, and spend points in the Treasury of Ithaca on titles, profile frames or an extra libation. The Hall of Heroes ranks mortals and tracks the Oracle's own record against them.
How we built it
Backend: FastAPI on Python with MongoDB Atlas, deployed on Render.
- Game schedules, rosters, player game logs and box scores come from
nba_api. - The Oracle's numbers are a small, explainable model. For a player stat, the line $L$ is the season average rounded to a half point, and the estimate leans on recent form:
$$\mu = 0.35\,\bar{x}{5} + 0.35\,\bar{x}{10} + 0.30\,\bar{x}_{\text{season}}, \qquad P(\text{over}) = 1 - \Phi!\left(\frac{L - \mu}{\sigma}\right)$$
where $\sigma$ is the player's own game-to-game spread (blended with his history against the opponent when there is one). Game winners use point differential, recent form and a home-court edge:
$$P(\text{home wins}) = \Phi!\left(\frac{R_{\text{home}} - R_{\text{away}} + 2.5}{12}\right)$$
- Google Gemini only writes the words. The pick, confidence and stats are fixed first, and Gemini voices Tiresias and Athena on top of them, so it can't invent stats or change the answer.
Frontend: React + TypeScript + Vite + Tailwind, deployed on Vercel. It has an Aegean-night theme, works at phone width, and has a mock mode so it could be built before the backend existed.
Teamwork: we built on two laptops in parallel, with a shared API contract as the single source of truth between frontend and backend.
Challenges we ran into
- NBA.com blocks cloud servers. Every request from our host hung until it timed out. We solved it by having a laptop sync NBA data into MongoDB, while the deployed server reads only from that cache. Replay mode works even with the laptop off.
- No peeking at the future. In replay mode, the Oracle had to use only games before the one being asked about. Every input is filtered by a cutoff date, and final scores stay hidden in the UI until you answer.
- AI that's down at the worst moment. Gemini's larger models were overloaded or over quota during testing. The Oracle tries fast models in order with a timeout, rejects any gambling language, and falls back to a written template so a prophecy always comes back. Prophecies are saved and shared, so asking again is instant.
- Paying points exactly once. Live predictions are graded by a background task, on page load, and instantly in replay mode. Grading and Treasury purchases are single atomic updates, so double clicks and overlapping graders can never pay twice.
What we learned
- A small, honest model that explains itself beats a black box. Athena citing "5 of his last 10 games" is more convincing than a bare percentage.
- Agree on the API contract first. It let the two halves be built separately and come together with very little friction.
- Plan for every external dependency to fail. Each one here (NBA.com, Gemini, free hosting) did, and every fallback ended up being used.
What's next
Smarter models (minutes, rest days, injuries), friend leagues, and more books of the Odyssey to voyage through.
