Gridiron Genie: an NFL matchup room powered by Databricks Genie Agent
Track B (Creative Thinking) entry for the Genie-Powered App Challenge, built and deployed on Databricks Free Edition.
The Week 1 slate: pick a matchup room.
The premise
You're an NFL analyst. A coach needs a Week 1 scouting report. You have 15 minutes before the next practice and he wants some data-driven insights to share with the team.
Gridiron Genie is a matchup room built on Databricks Apps where every user-facing analytical finding comes through Genie. Pick any of the 16 Week 1 matchups and the agent researches a full scouting brief, planning its own investigation, writing its own SQL, and generating its own charts. Drill deeper in Genie chat, and when you find something that matters, add it to the game report: Genie writes a new drill-down section using the brief conversation's earlier research as context, and the app appends it to the existing report. Print the finished report for the coach.
What can you ask? Whole-team and position-group edges, run-direction and pass-depth splits, red-zone and third-down performance, which players carry recent usage into the contest, exact season totals, and follow-ups on any of it, scoped to the matchup room you're in. Most answers come back in EPA (expected points added, the change in expected points a play produces) alongside success rates and sample counts.
Architecture
The architecture in three layers: what happens when you ask a question (top), how the data was built (middle), and the Databricks services underneath (bottom).
One Databricks Automation Bundle manages the catalog and schemas, three Lakeflow Jobs, the Genie Agent definition, and the app as one versioned deployment.
- Ingest (Bronze): 32 nflverse release assets — schedules, play-by-play, weekly player stats, rosters, snap counts — loaded idempotently into 13 raw tables with provenance columns (source URL, load time, SHA-256).
- Conform (Silver): a 10-table contract covering matchups and teams, player identities, plays, team and player production, weekly snaps, rosters, depth charts, and Next Gen Stats enrichment.
- Curate (Gold): 7 views built for the agent, not for dashboards.
- Reason (Genie): one source-controlled Genie space over those 7 views, queried through two different APIs.
- Experience (Apps): a React app on Databricks Apps that routes every finding through the agent.
The data layer is the prompt
Each column in the seven Gold views has a Unity Catalog comment written to help Genie interpret the data correctly. The Gold build fails if any comment is missing. This metadata works alongside the source-controlled Genie instructions, example SQL, and knowledge-store configuration to provide a consistent semantic layer.
For example, when Genie reports a player’s yards per carry and qualifying attempts by run direction, it retrieves those values from the curated run-direction view. The schema defines what qualifies as a carry, how direction is categorized, and how missing data should be interpreted. Genie generates the explanation, but the data model determines what the numbers mean.
Curating and evaluating the Genie Agent
The Genie space is generated from source-controlled Python, including deterministic identifiers, ordered configuration, one instruction block, and twelve example SQL queries. As a result, changes to the space are reproducible and reviewable in Git.
We measured performance with Genie benchmark evaluations. The original five-question benchmark improved from 3/5 to 5/5. The failures showed that the agent was misreading the schema so we added better column comments, better example SQL queries and tighter instructions. After these updates, we expanded the suite to eleven questions, the final evaluation scored 11/11, showing that the added context had improved the agent's understanding across the whole data contract, not just on the questions we had previously fixed.
The most useful lesson: examples can outweigh prose when they conflict. In this project, when an example SQL query contradicted a written instruction, Genie followed the example. A red-zone example phrased "in this game" silently pinned one suggested question to the wrong game because the example, not the instruction block, won the routing. Renaming the example and interpolating team names fixed it.
Two workflows, one Genie Agent
The app talks to the same curated space through two APIs:
- Genie chat (/api/ask) uses the Conversation API for focused questions and follow-ups, returning the answer, generated SQL, and supporting results.
- Agent research (/api/brief) uses the Agent Mode API (Beta) to conduct a multi-query investigation from a single request. It streams its progress, SQL queries, findings, visualization references, and final report over server-sent events (SSE).
When Agent Mode generates a chart, the app retrieves the chart image through a separate backend endpoint and sends it to the browser.
POST /api/2.0/genie/agents/{space_id}/responsesAccept: text/event-streamContent-Type: application/json{ "input": [ { "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "..." }] } ], "enable_viz": true}Follow-ups reuse the returned conversation_id, which is what powers the app's best feature: add to game report. A chat finding is sent as a follow-up in the brief's own conversation; Genie writes a new drill-down section using its earlier research as context, and the app appends it to the existing report. This turns chat from a separate question-and-answer panel into a collaborative game-planning workflow.
The agent plans the investigation, runs its own SQL, and charts what it finds.
The app renders shapes, not questions
The client inspects each Genie result's shape: if the rows carry run-direction or pass-depth members, the answer renders as a 2.5D football field with team-colored lanes, count-up deltas, and sample sizes. Everything else falls back to Genie's prose plus the SQL-receipted table. Because the renderer responds to the returned data, an unanticipated question can still produce the field visualization when its result matches a supported shape.
When the answer has spatial shape, the app renders it as a 2.5D field
The printed game report: the analyst’s ad-hoc drill-down, written by Genie.
Built-in governance and auditability
Genie requests run under the app’s service principal, so users receive access through the application rather than direct permissions on the SQL warehouse. The Genie Agent is configured with seven registered Gold views, while Unity Catalog governs access to the underlying data.
Databricks records Genie API activity in system.access.audit, providing a platform-level trail for space changes, evaluation activity, and API requests without requiring a custom audit-log implementation. These records capture operational events and response status — not complete conversations, generated SQL, or the agent’s internal reasoning.
SELECT event_time, action_name, request_params, response.status_codeFROM system.access.audit WHERE service_name = 'aibiGenie' AND event_date >= current_date() - INTERVAL 30 DAYS ORDER BY event_time DESC
On Free Edition, that query surfaced this project's space updates, benchmark runs, and agent responses.
A deployment issue exposed an important grant behavior: CREATE OR REPLACE VIEW wipes per-view grants on every rebuild. When a service principal should read every current and future view in a dedicated schema, grant SELECT at the schema level, or the app goes blank the next time a job rebuilds the views.
Practical lessons learned
- Invest in the data layer first. Curated views, clear metric definitions, and complete Unity Catalog comments gave Genie a stronger foundation than prompt changes alone.
- Run benchmarks after every space change. Our original five-question suite improved from 3/5 to 5/5. We then expanded it to eleven questions and reached 11/11, making the suite our primary regression check.
- Example SQL had a stronger influence than written instructions when the two conflicted. Keep examples narrowly scoped, name them clearly, and test the behavior they encourage.
- The Agent Mode API (Beta) worked in Databricks Free Edition for multi-query research, streamed progress, generated SQL, visualization references, and conversation-aware follow-ups.
- Give app service principals schema-level SELECT on dedicated schemas; per-view grants vanish when CREATE OR REPLACE VIEW rebuilds a view.
- Preserve conversation context when moving between features. Reusing the brief’s conversation_id allowed chat findings to become report sections without repeating the original research or rebuilding the report.
- Manage the Genie space like application code. Deterministic generation, source-controlled configuration, bundle deployment, and repeatable evaluations made changes reviewable and reduced drift between development and the deployed agent.
See it in action
- Demo video: https://youtu.be/qocXsQ7khaw
- The app runs on Databricks Apps inside my Free Edition workspace (Apps require workspace login, so the video is the tour).
Gridiron Genie is a fan-built demo. It is not affiliated with or endorsed by the NFL or any team; marks belong to their owners. Data provided by nflverse under the CC-BY-4.0 license. Product icons in the architecture diagram via the community databricks-architecture-icons project.
Gridiron Genie is an NFL matchup room built on Databricks Free Edition where a Genie Agent does all the analysis: one prompt researches a full scouting brief (Agent Mode API, Beta), ad-hoc questions render as 2.5D field graphics, findings append to the agent's own report, and the finished game ...
Announcements
