Skip to content

STUDENT_GUIDE.md

Latest commit

 

History

History
174 lines (116 loc) · 6.89 KB

STUDENT_GUIDE.md

File metadata and controls

174 lines (116 loc) · 6.89 KB
Raw

Student Guide

A practical walkthrough for taking this starter kit, running it, and extending it with the help of modern AI development tools.

1. Get Your WMATA API Key

The WMATA API is free — you just need to register.

  1. Go to https://developer.wmata.com and click Sign up
  2. Confirm your email and sign in
  3. Go to Products → Default Tier → click Subscribe Without this step, your key returns HTTP 401 on every call.
  4. Go to Profile (top-right). You'll see two keys: Primary and Secondary. Either works.
  5. Copy the Primary key.

The free tier limits: 10 calls/sec and 50,000 calls/day — plenty for development and class demos.

2. Configure the Project

# From the project root
cp .env.example .env

# Open .env in any editor and paste your key after the equals sign:
# WMATA_API_KEY=abc123def456...

The .env file is gitignored — it will never be committed to your repo. Check this with git status after editing — .env should not appear.

🚨 If you ever accidentally commit a key, regenerate it on the WMATA portal immediately. Both keys (Primary and Secondary) can be rotated.

3. Run It

uv sync                                   # install deps (first time only)
.venv/bin/streamlit run app/dashboard.py  # launch the dashboard

The app opens at http://localhost:8501. Pick a station from the left sidebar — try Metro Center (busiest), Friendship Heights (Red Line, near AU), or Pentagon City.

To run the test suite:

.venv/bin/python tests/run_tests.py

You should see 35/35 passed. If anything fails, the test output will tell you what's wrong (most often: stale fixture IDs, since WMATA occasionally renames bus routes).

4. Working With This Code Using AI Dev Tools

Modern AI coding assistants are excellent partners for extending this codebase. Here's how to get the most out of each.

Claude Code (Anthropic) — the deepest integration

This repo includes Claude skills in .claude/skills/. After installing Claude Code (https://claude.com/code), cd into the project directory and start a session:

cd "WMATA Open Data Demo Apps"
claude

Then try:

  • /wmata-add-endpoint — guides you through adding a new WMATA API endpoint to wmata/client.py with a matching L1 test
  • /wmata-add-feature — walks through adding a new dashboard feature (chart, panel, metric)
  • /wmata-deploy — interactive deployment walkthrough

Tips:

  • The skills are loaded automatically because they live in .claude/skills/ at the repo root.
  • Use /init once at the start to let Claude index the codebase.
  • Ask things like "add a tab showing on-time performance per line over the last hour" — Claude reads the existing tabs and follows the same pattern.

OpenAI Codex / ChatGPT (Codex CLI or chatgpt.com)

The Codex CLI (https://github.com/openai/codex) works on the same agentic principle as Claude Code. From the project root:

codex

Pre-flight tips:

  • Drop a short note in AGENTS.md at the repo root summarizing the architecture (Codex reads it on startup, similar to how Claude reads CLAUDE.md). The README is a fine source to summarize from.
  • For the web ChatGPT, you can attach the repo as a ZIP, or paste the most relevant files (wmata/client.py, app/dashboard.py, the test runner) into the conversation.
  • Codex tends to be more verbose — ask it for "minimal diff" when you want a small change.

GitHub Copilot — best in your IDE

For inline suggestions and chat in VS Code / JetBrains:

  1. Install the GitHub Copilot and Copilot Chat extensions
  2. Open the project folder in your IDE — Copilot indexes it automatically
  3. Use @workspace in chat to give it project-wide context: "@workspace add a metric showing average wait time across all stations"

Tips:

  • Copilot is strongest on inline completion as you type — start writing the function signature and let it draft the body.
  • Use Copilot Chat for refactors and explanations of unfamiliar code (/explain selected code).
  • It does not run code or browsers — pair it with a terminal you keep open for streamlit run and python tests/run_tests.py.

Perplexity Computer (browser-based agentic platform)

Perplexity's Computer lets an AI agent operate inside your browser tabs.

For this project:

  • Use Perplexity Computer to research WMATA data quirks ("does WMATA publish historical GTFS archives?") and have it summarize with sources.
  • Open the running dashboard in a Perplexity Computer tab and ask "explain what this dashboard is showing me" for a sanity-check before sharing with classmates.
  • Perplexity Computer is not a code editor — you'll still write code in your IDE / Claude Code / Codex. Think of it as a research-and-validation companion.

Cross-cutting advice

If you want to... Best tool
Plan a multi-step extension and have it implemented Claude Code or Codex CLI
Get inline autocomplete while typing GitHub Copilot
Explore unfamiliar code Copilot Chat or Claude Code
Research transit data, GTFS spec, BI patterns Perplexity Computer (sources cited)
Pair-program a tricky algorithm Claude Code (deeper reasoning)

The biggest leverage comes from treating these tools as collaborators that read the same code and docs you do. Keep the README and lessons_learned.md accurate — those become the agent's onboarding material.

5. Common Extensions

Add a new API endpoint

# wmata/client.py
def get_train_positions(api_key: str) -> list[dict]:
    """Live positions of every train currently in service."""
    data = _get(api_key, "/TrainPositions/TrainPositions",
                params={"contentType": "json"})
    return data.get("TrainPositions", []) if data else []

Then add a test in tests/run_tests.py and re-export from wmata/__init__.py.

Add a new dashboard tab

The pattern in app/dashboard.py is clear: each tab is its own block under with tab_X:. Copy the System tab as a template and replace the contents.

Capture historical data

Write a small script that polls every minute:

import time, sqlite3, os
from wmata import get_predictions

while True:
    rows = get_predictions(os.environ["WMATA_API_KEY"], "A01")
    # ... write to SQLite or DuckDB
    time.sleep(60)

Then build a "headway analysis" tab against your historical table.

6. Where to Get Help

  • API issues — check Research/wmata_api_overview.md for known quirks (the rail Min field is a string, weekends break jRouteDetails, etc.)
  • License questions — Research/wmata_license_compliance.md has the full breakdown
  • What was tried before — lessons_learned.md documents dead-ends and decisions session by session
  • Test failures — fixtures may have aged; the test runner prints the exact failing assertion

Welcome to the kit. Build something interesting.