allanmartinez/commute-copilot

Commute Copilot

An AI agent that answers the two questions I ask every morning before taking the MBTA:

1. When do I need to walk out the door to catch the next train?
2. Does the weather change the plan? Should I bring a jacket or an umbrella?

The agent started as the "Try it yourself" exercise in Allan_Martinez_Sep11_Lab.ipynb (From Single Agents to Multi-Agent Workflows, AI Industry Lab, Sep 11 2026). This repo turns the notebook into a reusable package with a web UI.

How it works

The agent uses three tools, all backed by free APIs that need no key:

Tool	API	Returns
get_departures	MBTA v3 /predictions	Next trains, with your walk time already subtracted ("LEAVE HOME BY 8:02 AM")
get_service_alerts	MBTA v3 /alerts	Active delays, shuttles and closures, most severe first
get_rain_outlook	Open-Meteo	Hourly temperature, feels-like temperature, rain chance and wind

There are two architectures, and you can switch between them in the UI:

• Single agent (Task 1). One ReAct agent holds all three tools and decides the order.
• 3-agent graph (Task 2). This is a LangGraph workflow. A transit_agent and a weather_agent run in parallel, and a tool-less advisor_agent makes the final call.

Guardrails

#	Guardrail	Prevents
1	Turn limit (recursion_limit = 2 * 4 + 1)	Endless ReAct loops
2	Per-run API budget (6 calls)	Runaway requests against public APIs
3	Output validation	Any clock time in the answer that never appeared in tool output is flagged
+	Honesty rule in prompts	Glossing over TOOL_ERROR / NO_DATA

What changed from the notebook

• Any subway station. Pick any MBTA subway line, station and walk time. The notebook was hard-coded to JFK/UMass.
• Web app. The Gradio chat UI remembers recent turns, so you can ask follow-up questions.
• Run details panel. After each answer it shows the ReAct trace, loop count, model calls, tokens, API budget use and the Guardrail 3 result.
• Accurate multi-agent cost accounting. Each specialist's internal messages are collected through graph state, so the true token total is reported without re-running the agents. The notebook had to re-run them to get this number.
• Prompt fix from the Task 2 write-up. Each specialist is told to ignore the half of the question it has no tool for. The advisor no longer pads its answer with "the weather report couldn't verify train schedules".
• Safe to run concurrently. The API budget is now an object created for each run instead of a global counter, so simultaneous users don't share one budget.
• Small upgrades. The forecast includes a feels-like temperature. Alerts are sorted most severe first. Free-tier 429s are retried. There's a CLI and offline unit tests.

Run it

pip install -r requirements.txt
export OPENROUTER_API_KEY=sk-or-...        # free key from openrouter.ai

python app.py                               # web UI at http://127.0.0.1:7860
python -m commute_copilot "When should I leave, and do I need a jacket?" --details
python -m commute_copilot "Next train to Oak Grove?" --line Orange --stop place-dwnxg --walk 5 --mode multi
python -m pytest -q                         # offline tests, no keys needed

The default model is openrouter/free, which is OpenRouter's free-model router. To use a different model, set COMMUTE_MODEL. The free tier allows about 20 requests per minute and 50 per day. A single-agent question uses 2 to 4 requests, and the 3-agent graph uses about 5.

Running it as a Hugging Face Space requires a PRO account, because Gradio Spaces need PRO. Create a Gradio Space, copy these files into it, and add this block to the top of its README:

---
title: Commute Copilot
sdk: gradio
sdk_version: 6.29.0
python_version: "3.12"
app_file: app.py
---

Then add OPENROUTER_API_KEY as a secret under Settings → Variables and secrets.

Layout

app.py                      Gradio UI (Space entry point)
commute_copilot/
  config.py                 station/line settings, MBTA lookups
  tools.py                  the three live-data tools
  guardrails.py             turn limit, API budget, invented-time check
  agents.py                 single agent + 3-agent LangGraph workflow
  metrics.py                ReAct loop / token counting, trace formatting
  __main__.py               CLI
tests/test_offline.py       guardrail, tool and metric tests (network mocked)
Allan_Martinez_Sep11_Lab.ipynb   the original lab notebook

Built by Allan Martinez with help from Claude Code.