Field Guide: System Architecture

00: THE PROJECT

A small, inspectable robotics stack.

FieldWeaver compiles a natural language request into a strict, versioned MissionSpec. You review and approve that spec before the backend starts a deterministic 2D simulation. The model may propose only bounded mission fields or a known agent action. The simulator and safety filter keep final authority over motion.

Simulation software. The point-robot model is not a hardware controller, and the geometric safety checks are not a formal proof for real-world dynamics.

01: RUN WORKFLOW

Four steps, with a human review gate.

Each transition has a clear input and an observable result.

01OPERATORDescribe

Write the search objective and choose a built-in arena.

02COMPILERValidate

Build a bounded spec and show assumptions or questions.

03OPERATORApprove

Review the spec, then explicitly authorize the run.

04SIMULATORMeasure

Run a seeded trajectory and report calculated metrics.

View the system diagram source

flowchart LR
  Operator -->|mission text| UI[Next.js workbench]
  UI -->|compile request| API[FastAPI]
  API --> Compiler[Mission compiler]
  Compiler --> Schema[Strict MissionSpec validation]
  Schema -->|operator review| UI
  UI -->|approved spec and seed| API
  API --> Runner[Bounded run service]
  Runner --> Sim[Deterministic simulator]
  Sim --> Safety[Independent safety filter]
  Safety --> Sim
  Runner -->|event checkpoint only| Agent[Bounded agent decision]
  Sim --> Eval[Evaluator with hidden truth]
  Eval --> UI

02: SUBSYSTEM TOPOLOGY

Eight decoupled subsystems, strict boundaries.

Explore the components of the FieldWeaver architecture below. Click any node to inspect its inputs, outputs, deterministic invariants, and backend source files.

TOPOLOGY VISUALIZER8 SUBSYSTEM NODES ACTIVE

Select any node to inspect subsystem contracts, deterministic invariants, I/O schemas, and backend source files.

SUBSYSTEM CONTRACT

Deterministic Simulation Core

deterministicsimulation

10 Hz discrete-time physics engine using explicit Euler kinematics (dt=0.1s) and quadratic scalar plume dispersion.

Deterministic Invariants:

Seeded reproducibility across identical inputs
Strict separation of physics calculation from network and UI
Point-robot kinematic integration: x += v * dt

Input Contracts:

Validated MissionSpec
Scenario static obstacles
RNG seed integer

Output Contracts:

High-resolution trajectory frames (x, y, heading, scalar reading)
Final state metrics

03: LIFECYCLE STATE MACHINE

Seven lifecycle states with guard transitions.

FieldWeaver transitions through deterministic lifecycle states from docked idle to nominal convergence or bounded abort. Scrub through each state below to inspect its trigger conditions and safety invariants.

STATE MACHINE VISUALIZERACTIVE STATE: RUNNING

Explore the 7 deterministic lifecycle states governing mission compilation, safety gating, and run execution.

STATE SPECIFICATION

Autonomous Execution (10 Hz)

RUNNING

State Trigger:

Operator approves mission and clicks 'Run simulation'

System Behavior:

SimulationSession advances in 0.1s steps. Safety filter checks every velocity command before Euler integration.

Guard Conditions:

Approved specification locked
RNG seed initialized and scenario geometry loaded

Deterministic Safety Invariants:

Pre-step velocity scaling: 1.0 -> 0.6 -> 0.3 -> 0.0 m/s
Pairwise separation >= 0.35m, obstacle clearance >= 0.20m
Arena boundary margin >= 0.12m
Zero LLM calls in per-tick controller loop

Valid Next State Transitions:

04: SAFETY BOUNDARIES & CONTRACTS

The model suggests. The simulator decides.

01

Strict schema

Model output is parsed and checked against versioned Pydantic models. Unknown fields, unsupported actions, and out-of-range values are rejected.

02

Hard limits

Deterministic speed, separation, clearance, boundary, duration, and call budgets cannot be relaxed by model output.

03

Hidden source

Ground-truth source coordinates stay in the evaluator. Compiler prompts and event observations contain no truth coordinate.

04

Independent filter

Every proposed transition is checked before and after integration. Unsafe motion is scaled, stopped, or rejected.

The live model is not called during the per-tick controller loop. Agent calls happen only at bounded event checkpoints.

INVARIANT DIRECTORY7 of 7 CONTRACTS ACTIVE

Inspect deterministic limits enforced by Pydantic models, geometric validators, and the pre-step safety filter.

Parameter	Category	Enforced Value	Enforcement Layer	Deterministic Veto Behavior
`maximum_speed`	Motion	0.10 to 0.60 m/s (default 0.50 m/s)	`SafetyFilter & integrate_state`	Velocity commands scaled down to ceiling; excess speed physically cannot integrate into state.
`minimum_robot_separation`	Separation	0.25 to 1.20 m (default 0.35 m)	`SafetyFilter pairwise distance check`	If distance between rovers < separation, velocities scaled progressively (1.0 -> 0.6 -> 0.3 -> 0.0).
`minimum_obstacle_clearance`	Arena	0.05 to 0.80 m (default 0.20 m)	`Region.clearance() evaluation`	Clearance violations trigger immediate velocity scaling or emergency stationary hold.
`boundary_margin`	Arena	0.12 m inside 10.0 x 10.0 m boundary	`validate_state() geometric boundary check`	Positions outside boundary margin [0.12, 9.88] m are rejected with arena_boundary intervention.
`formation_ring_radius`	Formation	0.80 to 2.50 m (default 1.50 m)	`Pydantic FormationSpec & feasibility validator`	Specs where separation > 2Rsin(pi/N)*0.95 are rejected at compile time before execution.
`max_replans`	Agent Budget	Hard ceiling of 2 replans per run	`Orchestration runner loop counter`	Subsequent replan checkpoints ignored; simulator continues under current plan.
`max_model_calls`	Agent Budget	Ceiling of 4 calls per run, 30s timeout	`BasetenDecisionProvider call limiter`	Excess calls blocked to prevent API budget exhaustion or latency stalls.

05: SIMULATION MODEL

Seeded motion in a bounded 2D arena.

World10 × 10 metre arena, built-in geometry and events

Robots3 to 8 holonomic point robots

Time stepExplicit Euler at 0.1 seconds

FieldSeeded scalar quadratic field with optional noise

EstimatorRegularized least-squares quadratic fit

DetoursPer-robot A* routes to exact assigned ring slots

The quadratic controller uses a fitted source estimate. The weighted-centroid baseline shares the same formation objective and safety checks, but uses a simpler estimator and no agent replans. Both are measured from their recorded trajectories.

06: PROVIDER MODES

Offline works without a key.

Offline mock

Deterministic rules compile the supported subset and provide bounded event decisions. The UI labels these responses as mock.

Live provider

Use the server's Baseten key or enter a key for Baseten, Meta, or Fireworks in the workbench. Browser-entered keys are kept in page memory and sent to the backend for live requests.

Automatic mode uses live inference when the backend key is configured. Forcing live mode without a key returns an explicit error instead of switching to mock.

07: API CONSOLE & REFERENCE

Small HTTP surface, explicit contracts.

Send a read-only request to the running backend and inspect its actual response.

Read-only endpoint

Backend status and the server default provider. No model call is made.

Run a read-only request to see the actual response.

For compile and run contracts, use the backend's interactive API reference at 127.0.0.1:8000/docs.

08: EVALUATION

Compare paired runs, including failures.

The reproducible snapshot covers seven scenarios over ten shared seeds. It reports controller outcomes, trajectory metrics, and seeded mock recovery without implying live model performance.

View the evaluation report

The report page reads the same checked-in JSON used by the evaluation script and offers the raw file for download.

09: LOCAL SETUP

Run the workbench on your machine.

Follow the setup steps and a guided offline run. Commands are for PowerShell on Windows.

SETUP · 1 / 6

Install prerequisites

Install Python 3.11 or newer and Node.js 20.9 or newer with npm. Open PowerShell at the repository root.

py -3 --version
node --version
npm --version

FIRST RUN · 1 / 5

Choose an arena and swarm

Open Mission, choose Open field and the Balanced ring preset. Keep seed 42 for a repeatable run.

The offline simulator runs with an empty BASETEN_API_KEY. Add the key only to the backend environment file if you want the Baseten server default, or enter a provider key in the workbench. Never add a key to a NEXT_PUBLIC_* variable.

Full setup and API guide

10: KNOWN LIMITS

What this build does not claim.

It does not control hardware or model complex robot dynamics.
It does not support multiple sources, physical mapping, manipulation, or team splitting.
Scene segmentation is disabled. Built-in scenarios are the supported path.
The API has no authentication or rate limiting and is intended for local development.
Evaluation uses ten fixed seeds per scenario and does not establish general reliability.
No live Baseten request was made for the recorded evaluation results.

Privacy policy Security notes MIT license

From mission textto a measured run.