CrossTraffic: An Open-Source Framework for Reproducible and Executable Transportation Analysis and Knowledge Management
CrossTraffic constrains LLM execution with a knowledge graph, achieving MAE<0.50 and F1=1.0 for invalid-input detection.
Key Findings
Methodology
CrossTraffic treats transportation standards as continuously deployable software. Its Rust Transportations Library is the authoritative computational core; PyO3 and WebAssembly provide cross-platform access; and a knowledge graph G=(V,E) encodes parameters, conditions, rules, and provenance. The Semantic Validator performs semantic mapping, context resolution, predicate evaluation, and rejection before execution. MCP exposes verified functions to LLMs, while RAG retrieves explanations rather than producing unverified numerical results.
Key Results
- In the five-segment River Falls Bypass case on WIS 35/WIS 65, the WASM Web Calculator and MCP-based LLM interface both produced overall LOS C. Overall follower density was 5.09 versus 5.05 fol/mi; small discrepancies were attributed mainly to floating-point differences.
- Knowledge-graph-constrained execution achieved near-zero error across multiple LLMs, with MAE<0.50 and more than 94% error reduction relative to context-only approaches. The result indicates that structured rules improve both numerical accuracy and methodological fidelity.
- A boundary-value and combinatorial stress generator produced N=1000 vectors, including 12.01-ft lanes, negative dimensions, excessive grades, and high-speed/tight-radius conflicts. The validator obtained TP=740, TN=260, FN=0, and F1=1.00.
Significance
The work addresses a persistent infrastructure problem: HCM and AASHTO knowledge is distributed across PDFs, proprietary tools, agency silos, and inconsistent implementations. CrossTraffic connects normative knowledge, computation, audit trails, and natural-language access in one open framework. For researchers, a shared core improves reproducibility and model comparison; for agencies and practitioners, traceable rules and portable interfaces reduce migration and collaboration costs. More broadly, it reframes transportation methodology as maintainable public software rather than static documentation or black-box functionality.
Technical Contribution
The central technical contribution is placing normative semantic validation before computation instead of relying on isolated procedural checks. Parameter, DesignRule, Condition, and Provenance nodes are connected through VALIDATES, REQUIRES, AFFECTS, and CITED_IN relations. Algorithm 1 maps input keys, retrieves context-specific ActiveRules, evaluates predicates, traverses citations on failure, and only then invokes the Rust core. Strong typing, test-driven development, CI regression tests, PyO3, WASM, and MCP create an auditable chain from standard to execution.
Novelty
Most transportation RAG and LLM systems retrieve documents or generate explanations without guaranteeing procedural validity. CrossTraffic’s distinctive innovation is an executable regulatory ontology: the graph determines which rules activate, whether an analytical request is admissible, and which authority supports a rejection. It therefore links semantic reasoning to a deterministic engineering kernel, rather than treating the knowledge graph as a passive metadata layer.
Limitations
- Evidence is concentrated on two-lane highway rules, selected HCM Seventh Edition and AASHTO constraints, and one corridor case. This does not establish generality for urban networks, signal control, transit, pedestrians, or large-scale multimodal systems.
- The paper reports aggregate accuracy and stress-test results but provides limited per-model, prompt, retriever, and rule-module ablations. A wrongly encoded standard could also become a systematic failure source, even when the validator behaves deterministically.
Future Work
Future work should add more HCM chapters, AASHTO standards, and research models under community review and version governance. Important evaluations include large-scale knowledge-graph queries, complex multimodal networks, real-time digital twins, and additional LLMs. The platform also needs uncertainty reporting, conflict resolution between standards, cost profiling, independent safety audits, and mechanisms for testing whether encoded rules remain faithful as manuals evolve.
AI Executive Summary
Transportation engineering depends on the Highway Capacity Manual, AASHTO standards, agency data, and specialized software. Yet the equations and procedures are often hidden in proprietary tools or scattered across PDFs. Updates propagate unevenly, and two platforms can produce different results for the same design. Large language models improve access to documentation, but they may omit steps, hallucinate requirements, or calculate an invalid workflow.
CrossTraffic proposes an open framework that treats transportation knowledge as deployable software. Its Rust Transportations Library stores the authoritative equations and data structures; PyO3 and WebAssembly expose the same logic to Python, browsers, and desktop clients. An ontology-driven graph represents Parameter, DesignRule, Condition, and Provenance entities. Before execution, the Semantic Validator maps inputs, resolves context, activates relevant rules, evaluates predicates, and returns cited errors. An MCP server lets LLMs call these verified functions, while RAG supplies explanations rather than unchecked numbers.
The experiments suggest a strong separation between language and computation. In the five-segment River Falls Bypass study, the WASM calculator and LLM interface both reported overall LOS C. Across multiple LLMs, constrained execution achieved MAE<0.50 and reduced error by more than 94% versus context-only approaches. In 1000 adversarial vectors, including 12.01-ft lanes and incompatible speed-radius pairs, the validator achieved F1=1.00 with zero false negatives. The current evidence is promising but narrow: more manuals, urban scenarios, live simulation, and independent rule audits are needed before broad safety-critical deployment.
Deep Analysis
Background
Transportation knowledge combines HCM empirical equations, AASHTO design standards, agency data, and simulation tools. Transportation Knowledge Networks improved document exchange; RAG and LLMs improved natural-language access; ontology-based knowledge management introduced machine-readable concepts and relations through standards such as RDF and OWL. However, most systems still exchange documents or data rather than executable procedures. CrossTraffic targets this gap by combining an open computational core, semantic rules, provenance, and multi-platform delivery.
Core Problem
Conventional tools treat lane width, grade, speed, and radius as generic numeric fields. They may miss contextual conditions, categorical conflicts, or physical incompatibilities. LLMs can explain HCM procedures but cannot inherently guarantee that a generated workflow follows every required step. The precise challenge is therefore pre-execution validation of meaning, applicability, provenance, and procedural legality while preserving identical results across interfaces.
Innovation
- ��Executable regulatory ontology: HCM Seventh Edition and AASHTO constraints become graph-linked executable rules rather than static prose.
- ��Layered architecture: the Rust kernel is the single computational source of truth; PyO3 and WASM provide portable bindings; web, desktop, Python, and SUMO reuse the same implementation.
- ��Semantic gate: Algorithm 1 maps parameters, resolves Conditions, retrieves ActiveRules, evaluates predicates, and returns cited 400 errors when constraints fail.
- ��Controlled agents: MCP exposes trusted functions to LLMs, while RAG supports explanation and retrieval without replacing deterministic computation.
Methodology
- ��Input: a JSON design vector I. FindParameterNode maps each key to a graph Parameter node and immediately flags unknown fields.
- ��Context: GetActiveRules uses FacilityType and other Conditions to construct Ractive, avoiding irrelevant checks.
- ��Rules: the graph includes SF-001 lane width 9–12 ft, SF-002 shoulder width 0–8 ft, SF-003 horizontal class 0–5, SF-004 passing type, and SF-005 R≥Rmin(Vdesign).
- ��Evaluation: Evaluate tests every active predicate. On failure, TraverseSource follows CITED_IN links to HCM or the AASHTO Green Book and returns a structured SemanticException; otherwise inputs are serialized into Rust structs and executed.
- ��Assurance: test-driven development, CI regression tests, Python/WASM bindings, and SUMO TraCI co-simulation check implementation consistency across environments.
Experiments
The paper reports four validation studies covering computational consistency, logical robustness, digital-twin-style co-simulation, and generative-AI reliability. The real-world case is WIS 35/WIS 65 along the River Falls Bypass in Wisconsin, analyzed under HCM Chapter 15 across five consecutive segments with mixed passing opportunities and superelevation adjustments. Adversarial testing used boundary-value analysis and combinatorial conflicts, generating N=1000 vectors containing 12.01-ft lanes, negative dimensions, excessive grades, and high-speed/tight-radius pairs. The study compares a deterministic WASM calculator with an MCP-connected LLM interface and uses MAE, LOS, confusion-matrix counts, and F1.
Results
The two interfaces agreed on overall LOS C across the five segments. Overall average speed was 5.09 for the WASM result and 5.05 for the LLM interface, with small segment-level differences attributed to floating-point execution. Knowledge-graph-constrained execution achieved MAE<0.50 across multiple LLMs and reduced numerical error by more than 94% against context-only approaches. In the 1000-vector stress test, TP=740, TN=260, FN=0, and F1=1.00, indicating no illegal design passed within the tested rule scope.
Applications
Transportation agencies can deploy the HCM Calculator for traceable roadway design and level-of-service analysis; researchers can call the Rust implementation from Python without reimplementing equations. WASM supports browser and desktop delivery, while SUMO export and TraCI connect standards-based analysis to microscopic simulation. MCP enables natural-language engineering assistance. Deployment requires authoritative source documents, maintained graph rules, regression tests, and expert review for consequential decisions.
Limitations & Outlook
The evidence is limited to a two-lane highway domain, selected HCM/AASHTO rules, and one corridor. Urban signals, transit, pedestrian systems, multimodal networks, and very large simulations remain untested. The paper does not fully isolate the effects of each LLM, prompt, retriever, or rule module, nor does it quantify graph-query and real-time simulation costs. A validator can also enforce incorrectly encoded standards with high confidence; version audits, conflict handling, and independent certification are therefore essential.
Plain Language Accessible to non-experts
Imagine a public kitchen that prepares road-design recipes. In the old system, every cook keeps a different copy of the recipe: one reads a PDF, another uses a secret appliance, and a third relies on memory. The same order can produce different results, and nobody can easily check which recipe was followed.
CrossTraffic creates one open recipe book. It records which ingredients are needed, when a recipe applies, what combinations are unsafe, and where every instruction came from. A customer can speak naturally, but the kitchen assistant does not simply guess. It first checks whether the road width is allowed, whether the road type matches, and whether a fast vehicle is being sent through an impossibly tight curve. If something fails, it explains the problem and points to the source.
The main cooking machine is written once in Rust. Web pages, desktop programs, Python, and chat tools are different serving windows connected to that same machine, so changing windows should not change the meal. The system can also send the result to a traffic simulator and observe vehicle behavior. In the study, two interfaces produced overall LOS C, and all 1000 deliberately troublesome tests were handled correctly. The idea is simple: let AI talk to people, but let a tested machine enforce the recipe.
ELI14 Explained like you're 14
Picture a racing game where you design a highway. You tell an AI, “Make the cars go really fast around a tiny curve.” A normal chatbot might confidently calculate something, even though the road would be dangerous in real life. CrossTraffic acts like a super-referee: it understands your request, then checks whether the move follows the game’s safety rules.
Its rulebook records things like lane width, shoulder width, road type, passing zones, and safe curve size. The AI can explain the rules and find the right page, but the final numbers must come from a tested calculator. Think of a player suggesting a move while the referee decides whether the move is legal.
The same calculator works in a browser, desktop app, Python program, or chat connection. Researchers tested it on five sections of the River Falls Bypass. The normal calculator and the chat interface both produced overall LOS C. Then they created 1000 troublemaking examples, including lanes that were 12.01 feet wide and cars moving too fast around tight curves. Every invalid case was caught in the reported test! Pretty impressive, right? The catch is that the system currently focuses mostly on two-lane highways. It still needs more lessons about city intersections, buses, walking, and other transportation problems.
Glossary
Knowledge Graph
A machine-readable network of entities and relations representing objects, conditions, rules, and sources. Unlike a simple document search, it supports contextual rule selection and structured reasoning.
CrossTraffic uses G=(V,E) to encode transportation parameters, constraints, dependencies, and provenance.
Semantic Validator
A component that checks whether an input is meaningful, applicable, and compliant with engineering rules before computation. It goes beyond type checking or simple numeric-range checks.
It performs semantic mapping, context resolution, predicate evaluation, and rejection.
Model Context Protocol (MCP)
An interface protocol that allows an LLM to call external tools and data in a structured way. It separates language interaction from deterministic engineering execution.
The MCP server exposes Transportations Library functions to agents such as Claude Desktop.
Retrieval-Augmented Generation (RAG)
A method that retrieves relevant passages before generating an answer. It improves explanation and citation but does not by itself guarantee valid calculations or procedures.
HCM documentation is embedded and retrieved through a vector store such as ChromaDB.
WebAssembly (WASM)
A portable compiled format that runs in browsers and other environments. It allows the same Rust computational logic to operate client-side without a native installation.
CrossTraffic uses WASM for its browser-based calculator.
Level of Service (LOS)
A categorical summary of traffic operating quality derived from analytical measures such as speed and follower density. The case study reports overall LOS C.
LOS is used to compare the WASM and LLM interfaces across five segments.
Open Questions Unanswered questions from this research
- 1 Can the ontology scale to urban signals, transit, pedestrians, and multimodal networks without contradictory rules? The present evaluation does not answer this because it focuses on a narrow two-lane highway scope.
- 2 How can communities detect incorrectly encoded or outdated standards? Strong deterministic validation does not prove that the graph itself is correct; provenance review, versioning, and independent certification are still needed.
Applications
Immediate Applications
Auditable HCM calculator
State agencies and consultants can deploy the WASM web or desktop calculator to run HCM Chapter 15 analyses consistently. Engineers receive results together with rule checks and source citations, reducing discrepancies caused by different software versions. The prerequisite is a maintained knowledge graph reviewed by transportation experts.
LLM engineering assistant
Research groups can connect an LLM through MCP so users ask natural-language questions, interpret HCM parameters, and invoke trusted computations. The system should be restricted to verified tools, documented retrieval sources, regression tests, and human review for safety-critical recommendations.
Long-term Vision
Open transportation science infrastructure
A community could add HCM chapters, AASHTO standards, research models, and simulators as versioned modules. Over time, this could support collaborative digital twins and cross-agency analysis, provided governance, licensing, rule review, interoperability testing, and safety certification mature alongside the software.
Abstract
Transportation engineering often relies on technical manuals and analytical tools for planning, design, and operations. However, the dissemination and management of these methodologies, such as those defined in the Highway Capacity Manual (HCM), remain fragmented. Computational procedures are often embedded within proprietary tools, updates are inconsistently propagated across platforms, and knowledge transfer is limited. These challenges hinder reproducibility, interoperability, and collaborative advancement in transportation analysis. This paper introduces CrossTraffic, an open-source framework that treats transportation methodologies and regulatory knowledge as continuously deployable and verifiable software infrastructure. CrossTraffic provides an executable computational core for transportation analysis with cross-platform access through standardized interfaces. An ontology-driven knowledge graph encodes engineering rules and provenance and serves as a semantic validation layer for analytical workflows. A conversational interface further connects large language models to this validated execution environment through structured tool invocation, enabling natural-language access while preventing procedurally invalid analyses. Experimental results show that knowledge-graph-constrained execution substantially improves numerical accuracy and methodological fidelity compared with context-only approaches, achieving near-zero numerical error (MAE<0.50) across multiple large language models and perfect detection of invalid analytical inputs in stress testing (F1~=~1.0). Its modular architecture supports the integration of additional transportation manuals and research models, providing a foundation for an open and collaborative transportation science ecosystem with a reproducible computational core. The system implementation is publicly available at https://github.com/crosstraffic.