TransitGuard

A lineage-grounded transit-feed compliance and change-impact agent, built on DataHub.

TransitGuard turns a transit agency's GTFS feeds into a governed DataHub context graph, then runs an agent that answers the two questions behind an agency's funding eligibility: is this feed compliant with the federal funding mandate right now, and if it changes or breaks, what downstream products and which federal report go down with it?

Built for the Build with DataHub: The Agent Hackathon.

The problem: the FTA now requires fixed-route agencies that take federal money to publish a valid, current GTFS feed, tied to National Transit Database (NTD) reporting and grant eligibility. Free validators answer "is this feed well-formed against the spec." None map that to the funding mandate, and none can tell you what breaks downstream when a feed changes. A context-blind LLM asked those questions guesses, because it cannot see what is connected to what. TransitGuard gives it the graph. See Sources for the primary-source citations behind every compliance claim.

Public GTFS feeds become a governed DataHub context graph, an agent answers off that graph, a context-blind baseline shows the graph is load-bearing, and a human-confirmed write-back closes the loop.

"We want to rename the column stop_id in the failing clallam feed. Are we safe to ship, and are we NTD-compliant?"

• Context-blind (raw feed only): can't see the downstream or the compliance status, so it returns affected_datasets: [], ntd_certification: "unknown".
• Grounded by DataHub: traces stop_times to stg_stop_times to mart_departures to ntd_stop_export (and the departures dashboard), reports the feed is AT RISK with a failing GTFS-validation assertion, and returns the exact affected URNs (not safe to ship).

Prerequisites: uv, Docker, a JDK (for the validator jar), and an authenticated claude CLI (the agent runs on Claude Code, so no API key is needed).

# 1. Install deps (Python 3.11 is pinned)
uv sync

# 2. Bring up DataHub locally. NOTE: this repo maps GMS to host port 8090
#    (8080 was taken); the UI is on 9002 (login datahub/datahub).
DATAHUB_MAPPED_GMS_PORT=8090 uv run datahub docker quickstart

# 3. Ingest the demo feeds (clean / failing / stale) as DataHub datasets + lineage
uv run python -m src.entrypoints.ingest_feeds --gms http://localhost:8090

# 4. Build the derived warehouse chain for a feed (real dbt transforms + lineage)
uv run python -m src.entrypoints.build_derived_chain \
    --feed-id clallam --zip scratch/feeds/clallam.zip --gms http://localhost:8090

# 5. Validate + emit NTD compliance (assertions + tags)
uv run python -m src.entrypoints.validate_feeds --gms http://localhost:8090

# 6. Ask the impact agent (grounded by the DataHub MCP server via .mcp.json)
uv run python -m src.entrypoints.impact_agent --feed-id clallam \
    --change "rename column stop_id in stop_times"

# 7. Run the context-moat benchmark (grounded vs blind, per-bucket)
uv run python -m src.entrypoints.run_benchmark

# 8. On a confirmed finding, write a governance record back (human-confirmed).
#    --run-agent gets a fresh verdict; --dry-run writes a file instead of GMS.
uv run python -m src.entrypoints.govern --feed-id clallam --table stop_times \
    --change "rename column stop_id in stop_times" --run-agent --gms http://localhost:8090

The benchmark asks the agent the same questions twice, once grounded by the DataHub graph and once with only a raw-feed summary, and scores each against ground truth. The "blind" baseline is deliberately isolated (a throwaway working directory, no MCP, no repo access), so the only difference is the DataHub context. Results are reported per bucket rather than as one inflated number.

Scores are the fraction of ground-truth checks each mode got right (grounded = DataHub graph available, blind = same agent with the graph removed). In this run, the blind agent returned unknown on every question in three buckets (spec validity, downstream impact, compliance consequence), because it has no validator, no lineage, and no compliance metadata to work from, and unknown scores 0 against a definite ground truth. Those are exactly the buckets the graph makes answerable. Freshness is a deliberate +0.00: staleness is computable from the feed's own service dates, which the blind agent gets in its raw-feed summary, so the graph earns nothing there. Reporting it that way (instead of hiding it) is what keeps the benchmark honest rather than a strawman.

Per the hackathon's pre-existing-work policy, src/features/validation/validate.py adapts the canonical-validator wrapper from a pre-existing script (subprocess invocation, report parsing, service-date extraction). The deterministic validator itself is MobilityData's gtfs-validator (Apache-2.0), provided as a jar (not committed). Everything else is new work for this submission: the DataHub connector, the derived-chain lineage emission, the compliance/assertion mapping, the impact agent, and the benchmark.

Every compliance claim maps to a public primary source:

• The mandate: 88 FR 13503, "National Transit Database: Reporting Changes and Clarifications" (Federal Register 2023-04379, March 3, 2023), which adopted the GTFS weblink requirement for federally funded fixed-route reporters, under statutory authority 49 U.S.C. § 5334(k). https://www.federalregister.gov/documents/2023/03/03/2023-04379/national-transit-database-reporting-changes-and-clarifications
• RY2025/26 expansion: Federal Register 2024-25341 (docket FTA-2024-0013), which adds shapes.txt and an NTD P-50 agency_id crosswalk. https://www.federalregister.gov/documents/2024/10/31/2024-25341/national-transit-database-proposed-reporting-changes-and-clarifications-for-report-years-2025-and
• Live per-agency data: the NTD GTFS Weblinks table (2u7n-ub22 on data.transportation.gov, keyed on ntd_id), carrying each reporter's declared feed URL, certification flag, and validation date.
• Feed registry + validator: the Mobility Database and MobilityData's gtfs-validator (Apache-2.0), the source of the well-formedness posture used in the demo.

FTA monitors compliance by periodically checking that GTFS weblinks are viable and current, tied to NTD reporting and grant eligibility. Findings are framed as "at risk of NTD non-compliance / funding eligibility," never a dollar penalty.

Apache-2.0. See LICENSE.