How projnanda/nandatown works
NandaTown is a local-first agent test harness with three execution modes: seeded Lab simulations, HTTP-based Track runs, and tests against an existing A2A endpoint in Path mode. The CLI and terminal UI initiate runs; each mode records observations that are evaluated into portable evidence bundles for reporting, verification, replay, and visualization. The README documents these product capabilities; source excerpts and the SOURCE INDEX support the main orchestration and evidence links, while some subsystem details remain unsampled.
Main entry points: cli.py CLI · nandatown/runner.py Track runner · sim/runner.py Lab runner · path_runner.py Path runner
Components 27
Front doors
- CLI
src/nandatown/cli.py - Terminal UI
src/nandatown/tui.py
Run modes
- Track runner
src/nandatown/runner.py - HTTP coordinator
src/nandatown/coordinator.py - Track database
src/nandatown/db.py - Participant client
src/nandatown/client.py - Participants
src/nandatown/participants - Lab runner
src/nandatown/sim/runner.py - Scenario spec
src/nandatown/sim/scenario.py - Path runner
src/nandatown/path_runner.py - Path profiles
src/nandatown/path_profiles.py - Track profiles
src/nandatown/profiles.py - Campaigns
src/nandatown/campaign.py - Layer comparison
src/nandatown/compare.py
Protocol and participants
- Simulation engine
src/nandatown/sim/engine.py - Protocol layers
src/nandatown/layers - A2A adapter
src/nandatown/a2a_adapter.py - A2A transport
src/nandatown/a2a_transport.py - Portable identity
src/nandatown/identity_portable.py
Evidence and analysis
- Run records
src/nandatown/records.py - Stage evaluator
src/nandatown/evaluator.py - Lab validators
src/nandatown/sim/validators.py - Evidence bundle
src/nandatown/bundle.py - Report
src/nandatown/report.py - Replay
src/nandatown/replay.py - Visualizer
src/nandatown/visualizer.py
Other components
- Engineer
Connections 33
- Engineer → CLI: invokes
README.md - Engineer → Terminal UI: opens
README.md - CLI → Track runner: starts runs
src/nandatown/cli.py - CLI → Lab runner: starts runs
src/nandatown/cli.py - CLI → Path runner: starts tests
src/nandatown/cli.py - CLI → Campaigns: runs campaigns
src/nandatown/cli.py - CLI → Layer comparison: compares layers
src/nandatown/cli.py - Track runner → HTTP coordinator: starts subprocess
src/nandatown/runner.py - HTTP coordinator → Track database: reads and writes
src/nandatown/coordinator.py - Participants → Participant client: uses
src/nandatown/participants/base.py - Participant client → HTTP coordinator: sends HTTP
README.md - Track runner → Track profiles: loads profile
src/nandatown/runner.py - Track runner → Participants: spawns
src/nandatown/runner.py - Track runner → Portable identity: uses grants
src/nandatown/runner.py - Lab runner → Scenario spec: runs scenario
src/nandatown/campaign.py - Lab runner → Simulation engine: executes simulation
README.md - Simulation engine → Protocol layers: resolves plugins
src/nandatown/sim/engine.py - Path runner → Path profiles: loads profile
src/nandatown/path_runner.py - Path runner → A2A adapter: tests endpoint
src/nandatown/path_runner.py - Path runner → A2A transport: uses transport
src/nandatown/path_runner.py - Track runner → Evidence bundle: writes bundle
src/nandatown/runner.py - Lab runner → Evidence bundle: writes bundle
README.md - Path runner → Evidence bundle: writes bundle
src/nandatown/path_runner.py - Evidence bundle → Run records: assembles records
src/nandatown/bundle.py - Track runner → Stage evaluator: evaluates events
src/nandatown/runner.py - Path runner → Stage evaluator: evaluates events
src/nandatown/path_runner.py - Lab runner → Lab validators: checks properties
README.md - Evidence bundle → Stage evaluator: replays evaluation
src/nandatown/bundle.py - CLI → Report: renders report
src/nandatown/cli.py - CLI → Replay: replays bundle
README.md - CLI → Visualizer: visualizes bundle
README.md - Campaigns → Lab runner: runs scenarios
src/nandatown/campaign.py - Layer comparison → Lab runner: compares runs
src/nandatown/compare.py