README.md

metadata

title: HAWK ONE
emoji: 🏈
colorFrom: blue
colorTo: red
sdk: gradio
sdk_version: 4.44.1
python_version: '3.11'
app_file: app.py
pinned: false

HAWK ONE

A football film room built on one simulation engine with two rule profiles (NFL and college). Watch a play run, click a player, redraw his path or change his reaction time, and see what would have happened.

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

What it does

• Run play / Next play. Offensive and defensive coaches call the snap ("Coach decides") or you pick the calls. Next play carries the drive forward (down, distance, field position, hash spotting). The play auto-plays.
• Level switch. NFL or college reruns the play under that level's rules and hash width (catch, down by contact, pass interference, ineligible linemen downfield, hash marks).
• Player card. Click any player for height, weight, 40 time, top speed, separation from the nearest opponent over time, and speed over time.
• What-if. Drag the points on a player's path (add, remove, retime), or change a defender's or the QB's reaction time. Press Run what-if: the original and your version are replayed hundreds of times on the same random seeds, with a verdict, the numbers, a histogram, reasons, and a check of whether his body can run what you drew. Several edits at once are supported, with the credit split between them.
• Path Lab. The engine tries variations of one player's path and ranks them.
• Recorded plays. Load a tracking CSV (format in tracking.py) to inspect and annotate a real play. "Save this play as CSV" writes a sample.

Run locally

pip install -r requirements.txt
python app.py

Files

File	Role
app.py	Gradio app (single screen)
film.py	Film viewer (HTML/SVG/JS served in an iframe)
render.py	Result panels (verdict, numbers, credit split, Path Lab)
whatif.py	Paired Monte Carlo, feasibility, path suggestions
engine.py	Physics, collisions, blocking, coverage, rule hooks
coach.py	Play calling and the drive loop
attrs.py, playbook.py, formations.py	Player attributes, plays and calls, alignments
rules.py	NFL and NCAA rule profiles and rule functions
tracking.py	Tracking CSV import and export

Status and caveats

• The simulation is plausible but not fitted to league data. Use the direction and the reasons more than the exact yardage.
• What-if runs on simulated plays. Recorded plays can be inspected and annotated; running them through the engine needs an adapter that starts from recorded alignments.
• Rules marked "verify" in rules.py (game clock, pass interference flat vs capped, overtime, kickoffs, targeting) need confirmation against the current NFL and NCAA rulebooks.
• Engine, what-if maths, result panels and the viewer (including the iframe-to-page bridge) were run headlessly. The Gradio app itself still needs a first run in your environment.