README.md

metadata

title: TransitAgent 🚌
emoji: ✈️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.49.1
python_version: 3.12.12
app_file: app.py
pinned: false
short_description: Check Flights & Bay Area Transit Routes
tags:
  - track:backyard
  - sponsor:openbmb
  - achievement:offbrand
  - achievement:sharing

Social Media Post and Video: https://www.linkedin.com/posts/dean-byrne-02a28b191_transitagent-for-hugging-face-hackathon-ugcPost-7472117054389608448-SJRD/?utm_source=share&utm_medium=member_desktop&rcm=ACoAAC0RumIBxlIKTkKv5tF-hb2OU7TdZ19kxcQ

TransitAgent 🍄

Two LLM agents in one glow-in-the-dark, 80's-hacker app, switchable by tab:

• ✈️ FLIGHTS / SKYLINE (glow cyan) — a flight agent over the FlightRadar24 API, rendered on a transparent neon 3D globe.
• 🚉 BAY TRANSIT / BAYLINE (glow orange) — a Bay Area transit agent over the 511.org API, with route lines on the same globe.

Built for the HuggingFace hackathon.

[Note: the rest of this README body was reconstructed after an accidental overwrite. The frontmatter above is the part you asked me to fill in and is correct. The body below should be reviewed against the original before publishing — see the "Restoring this README" note at the end.]

What it does

Type a query in plain English, the LLM picks a tool, the matching API call runs, and the answer shows up on the globe. Examples:

• ✈️ flights from London to Dubai — both endpoints drawn as an arc on the globe.
• ✈️ arrivals into JFK — rings around JFK showing live inbound traffic.
• ✈️ departures from LAX — outbound tracks fanning out from LAX.
• 🚉 MUNI arrivals at Powell — nearby stops highlighted, predicted arrivals listed in the sidebar.

✈️ SKYLINE — flight agent

Powered by FlightRadar24's live API. Set FR24_API_TOKEN to use this tab.

tool	FR24 call it runs
flights_in_box	GET /api/live/flight-positions/full?bounds=...
flights_by_airline	GET /api/live/flight-positions/full?airline=...
flights_by_flight	GET /api/live/flight-positions/full?flight=...
flights_by_callsign	GET /api/live/flight-positions/full?callsign=...
flights_by_reg	GET /api/live/flight-positions/full?reg=...
flights_by_mil	GET /api/live/flight-positions/mil?bounds=...
flight_by_id	GET /api/flights/detail?flight_id=...
airports_in_box	GET /api/static/airports?bounds=...

Flow per query: plan (the LLM picks a tool + args) → act (the real FR24 call runs) → render (results placed on the globe + sidebar).

🚉 BAYLINE — Bay Area transit agent

Powered by 511.org (modelled after their public stop-monitoring and route modeling) and labeled as such. Set TRANSIT_511_API_KEY to use this tab.

Tracing the agent

The traces/ folder is created at runtime. Every query writes a JSONL trace of:

• the LLM's tool call + args
• the exact FR24 request URL
• the result count
• per-step latency

Use this to debug what the model is actually choosing.

Run it locally

git clone <this repo>
cd flight-globe-app
python -m venv .venv && . .venv/bin/activate    # Windows: .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# Put your keys in the environment (or a local .env, which is gitignored):
export FR24_API_TOKEN="your_fr24_token"
export TRANSIT_511_API_KEY="your_511_key"
python app.py        # -> http://127.0.0.1:7860

Locally the model runs on your GPU if you have one, otherwise CPU. (spaces is not needed locally — @spaces.GPU is a no-op off ZeroGPU.)

Deploying to a HuggingFace ZeroGPU Space

This Space is configured for ZeroGPU (dynamic GPU allocation). The relevant config is already in place:

• README.md front-matter: sdk: gradio, python_version: "3.12.12" (a ZeroGPU-supported Python), app_file: app.py.
• requirements.txt: spaces, torch==2.8.0 (ZeroGPU needs CUDA torch ≥ 2.8), transformers, accelerate.
• liquid.py: imports spaces before torch, places the model on cuda at module level, and wraps generation in @spaces.GPU.

1. Create the Space

1. https://huggingface.co/new-space → SDK: Gradio.
2. Hardware: ZeroGPU. This requires a PRO (personal) or Team/Enterprise plan — ZeroGPU isn't available on free accounts. (If you can't use ZeroGPU, pick CPU basic instead and change torch==2.8.0 → torch in requirements.txt; it'll run on CPU, just slower.)

2. Push the code (everything except .env)

git init && git add . && git commit -m "FLIGHTDECK"
git remote add origin https://huggingface.co/spaces/<your-username>/<space-name>
git push -u origin main

.env is gitignored, so your local keys won't be uploaded. First build pulls torch + transformers, so it takes a few minutes.

3. Add the keys as Space Secrets

Space → Settings → Variables and secrets → New secret (use Secret, not Variable, for the keys):

Name	Value	Required?
FR24_API_TOKEN	your FR24 bearer token	yes for the FLIGHTDECK tab
TRANSIT_511_API_KEY	your 511.org key	yes for the BAY TRANSIT tab
FR24_API_VERSION	v1	optional
LLM_REPO	openbmb/MiniCPM5-1B	optional (swap model)
ZEROGPU_DURATION	60	optional (max GPU seconds per call)
DISABLE_LLM	0	optional — 1 uses the regex planner only

Secrets are injected as environment variables; app.py reads them via os.environ, so no code changes are needed. The Space restarts on save.

4. Notes

• The first query attaches a GPU and loads the model; ZeroGPU has a daily GPU quota per account tier — see the ZeroGPU docs.
• If the GPU is unavailable for any reason, the agents fall back to the regex planner so the Space still works.
• If you see ... is not set, the secret name is case-sensitive — match the table exactly.

Local dev (optional)

If you want to run the Space code locally with real keys, copy the example file and edit it — your real .env is ignored by git and never uploaded:

Copy-Item .env.example .env
# edit .env and paste your real tokens
python app.py

How it works

1. Type a flight query in ASK THE FLIGHT AGENT, e.g. flights from London to Dubai, arrivals into JFK, departures from LAX.
2. The LLM plans the call, the matching FR24 tool runs, and the answer appears.
3. Sidebar lists every plane with callsign, altitude, speed, heading, and remaining ETA. ETA comes straight from FR24's eta field.

Notes

• The first query downloads the openbmb/MiniCPM5-1B weights from HuggingFace and caches them; subsequent runs reuse the cache.
• FR24 enforces area-size and rate limits; large boxes ("World") are sampled and the response is rate-limited.
• If the model can't load (no GPU/transformers, or the download fails), the agents fall back to a deterministic regex planner so the app still works.

---

Restoring this README — IMPORTANT

The body of this README (everything below the frontmatter) was reconstructed after an accidental overwrite and may not be byte-for-byte identical to the original. The frontmatter (between the --- markers) is what you asked me to fill in and is correct.

Before publishing, please verify the body against any of these sources if you have them:

• A backup of the project (Recycle Bin / File History / a previous git push)
• An earlier version of the README in this conversation
• The traces/ folder and the source files (app.py, agent.py, transit_agent.py) for the exact phrasing you used

If you have the original anywhere, replace the body section (everything below the closing ---) with the original and keep the frontmatter I added.