codriver/README.md

codriver

A deterministic, local navigation daemon that emits turn directives ("Turn left") at the right moment. No LLM on the hot path. The LLM is a later, off-path layer that decides whether to speak and how to phrase; this repo is the dumb, fast substrate it sits on top of.

Target hardware: NVIDIA Jetson Orin Nano with bolt-on GPS (NMEA-over-UART, wrapped by gpsd) and IMU (I2C). Visual input and LLM co-driver are explicitly out of scope for the current milestone.

---

Scope (current milestone — "step 0")

In: Consume a pre-computed route, poll position, emit a maneuver string at a speed-adaptive lead time, detect going off-route and reroute.

Out (deferred): TTS, LLM phrasing/decision layer, IMU sensor fusion, visual input, rally pace-note generation, recce-run note authoring.

The deliverable of step 0 is: a process that prints "Turn left" (or the configured flavour) when the driver should turn, not too late, and recomputes the route when the driver deviates.

---

SWE-1 — Software Requirements

Requirements are tagged SWR-n for traceability into the SWE-2 architecture and later test cases (SWE-4/5/6).

Functional

• SWR-1 The system shall obtain a route from an origin to a destination as an ordered geometry (polyline) plus a sparse, ordered list of maneuvers.
• SWR-2 The system shall acquire the vehicle's current position, speed, and heading by polling a position source.
• SWR-3 The system shall project the current position onto the active route geometry, yielding distance-along-route and cross-track distance.
• SWR-4 The system shall identify the next not-yet-announced maneuver ahead of the current along-route position.
• SWR-5 The system shall compute a trigger distance as a function of current speed and a configured lead time (constant time to maneuver, not constant distance).
• SWR-6 The system shall emit exactly one directive string per maneuver, when the distance to that maneuver first falls within the trigger distance.
• SWR-7 The system shall detect an off-route condition when sustained cross-track distance exceeds a threshold (debounced over N consecutive fixes).
• SWR-8 On off-route, the system shall request a new route from current position to the unchanged destination and atomically replace the active route.
• SWR-9 The directive string content shall be configurable ("flavour"), so the phrasing layer is decoupled from the trigger logic.

Non-functional / constraints

• SWR-10 The decision path (acquire → match → decide → emit) shall contain no network call and no LLM invocation; route acquisition (incl. reroute) is the only component permitted to block on I/O and shall run off the decision path.
• SWR-11 The position source has no native subscribe/interrupt mechanism; the architecture shall treat polling as the normative interface.
• SWR-12 Routing shall be performable fully offline from a periodically-updated local dataset (no per-trip dependency on a cloud routing service).
• SWR-13 The route source shall be replaceable (local engine, cloud API, or recorded file) without change to the decision path.
• SWR-14 "Not too late": at the configured lead time, the directive shall be emitted with enough distance for the driver to act at the current speed.
• SWR-15 A single noisy position fix shall not by itself cause a reroute or a spurious/duplicate directive.

---

SWE-2 — Software Architectural Design

Layering

Two tiers. The decision tier is the hot loop: pure arithmetic over an in-memory route, runs at the position-source cadence (~1–10 Hz), never blocks on network. The planning tier is off-path: it produces a Route artifact and hands it to the decision tier through a single shared, atomically-swappable slot.

                      planning tier (slow, blocking I/O OK)
   ┌─────────────────────────────────────────────────────────┐
   │  RouteProvider ──► Route artifact ──►  ActiveRouteStore   │
   └───────────────────────────────────────────▲──────────────┘
                                                │ atomic swap
   ┌────────────────────────────────────────────┼─────────────┐
   │  PositionSource ─► StateStore ─► [ poll loop: MapMatcher   │
   │                                   ─► ManeuverTracker       │
   │                                   ─► TriggerPolicy         │
   │                                   ─► OffRouteMonitor ]     │
   │                                   ─► DirectiveEmitter ─►   │
   └────────────────────────────────── decision tier (fast) ───┘

Module decomposition

Each module below maps to a Python package/module. Interfaces are given as the contract; types reference the data model in the next section.

route_provider/ — route acquisition (planning tier)

• Responsibility: turn (origin, destination) into a normalized Route. Isolates all backend messiness (OSRM/Valhalla/Google/file) behind one contract.
• Interface:
  • RouteProvider.get_route(origin: LatLon, dest: LatLon) -> Route
• Implementations (selected at config time):
  • route_provider/osrm.py — OsrmProvider: HTTP client to a local OSRM instance; normalizes legs[].steps[].maneuver + decoded geometry into the internal Route/Maneuver model. Primary backend.
  • route_provider/file.py — FileProvider: loads a pre-decoded route from disk. For desk testing and reproducible runs.
  • route_provider/google.py — GoogleProvider: optional online fallback.
• Satisfies: SWR-1, SWR-12, SWR-13. Normalization point also serves SWR-9's decoupling (maneuver semantics fixed here, phrasing fixed downstream).
• Note: Owns no routing algorithm. Preprocessing of OSM extracts (osrm-extract/partition/customize) is an operational step documented in ops/, not code in this repo.

position/ — position acquisition (decision tier, ingress)

• Responsibility: poll the position source, parse to a Fix, publish the freshest fix.
• Interface:
  • PositionSource.read() -> Fix (blocking until next fix; the GPS cadence is the loop clock)
• Implementations:
  • position/gpsd_source.py — GpsdSource: client of local gpsd; gpsd.next() as the blocking read. Primary.
  • position/nmea_source.py — NmeaSource: direct /dev/ttyUSB* NMEA parse (fallback if gpsd is undesired).
  • position/replay_source.py — ReplaySource: replays a recorded NMEA/fix log at wall-clock or accelerated rate. For desk testing without hardware.
• Satisfies: SWR-2, SWR-11.

state/ — shared state slots

• Responsibility: last-write-wins handoff between threads. Two slots: current vehicle Fix, and the ActiveRouteStore for the route.
• Interface:
  • StateStore.put(fix: Fix) / StateStore.latest() -> Fix | None
  • ActiveRouteStore.swap(route: Route) / ActiveRouteStore.current() -> Route | None
• Satisfies: SWR-8 (atomic swap), SWR-10 (decouples blocking planning tier from the non-blocking decision tier).

matching/ — map matching

• Responsibility: project a Fix onto the active Route polyline.
• Interface:
  • MapMatcher.match(fix: Fix, route: Route) -> MatchResult where MatchResult = {along_dist_m, cross_track_m, segment_index, snapped: LatLon}
• Step-0 algorithm: nearest-segment + perpendicular projection. No probabilistic HMM matching yet.
• Satisfies: SWR-3. Produces the cross-track value consumed by OffRouteMonitor for free.

maneuvers/ — maneuver tracking

• Responsibility: given along_dist, find the next not-yet-announced maneuver and the along-route distance to it; own the per-maneuver "announced" markers.
• Interface:
  • ManeuverTracker.next_pending(along_dist_m: float) -> tuple[Maneuver, float] | None
  • ManeuverTracker.mark_announced(maneuver_id) -> None
  • ManeuverTracker.reset() -> None (called on route swap)
• Satisfies: SWR-4, SWR-6 (exactly-once via markers).

trigger/ — trigger policy

• Responsibility: decide whether the next maneuver should fire now.
• Interface:
  • TriggerPolicy.should_fire(distance_to_maneuver_m: float, fix: Fix) -> bool
• Step-0 policy: trigger_distance = speed_mps * lead_time_s + reaction_buffer_m; fire when distance_to_maneuver <= trigger_distance.
• Config: lead_time_s, reaction_buffer_m. (A later second-stage early pre-announce — "in 300 meters…" — slots in here as an additional threshold without touching other modules.)
• Satisfies: SWR-5, SWR-14.

offroute/ — off-route monitor

• Responsibility: debounced off-route detection; request reroute.
• Interface:
  • OffRouteMonitor.update(match: MatchResult) -> OffRouteState (ON_ROUTE | OFF_ROUTE)
• Step-0 algorithm: cross_track_m > threshold_m sustained for N consecutive fixes (hysteresis on recovery). On transition to OFF_ROUTE, signals the planning tier to call RouteProvider.get_route(current, dest) and ActiveRouteStore.swap, then ManeuverTracker.reset.
• Config: threshold_m, confirm_fixes_n.
• Satisfies: SWR-7, SWR-8, SWR-15.

directive/ — directive emitter (decision tier, egress)

• Responsibility: render a Maneuver into the output string and emit it.
• Interface:
  • DirectiveEmitter.emit(maneuver: Maneuver, fix: Fix) -> None
  • Phrasebook.render(maneuver: Maneuver) -> str
• Step-0 implementation: table-driven phrasebook (maneuver.type + modifier → string); emit = print() / write to stdout or a socket. TTS and the LLM phrasing layer subscribe here later; the seam is Phrasebook.
• Satisfies: SWR-6, SWR-9.

app/ — composition root

• Responsibility: wire modules from config, own the two threads (position poller, decision loop) and the planning-tier reroute worker, handle lifecycle.
• Interface: main() + config.py (dataclass-validated config: provider selection, lead time, thresholds, phrasebook flavour, source selection).
• Decision loop (pseudocode):

  fix = state.latest()
  route = active_route.current()
  m = matcher.match(fix, route)
  if offroute.update(m) == OFF_ROUTE:
      request_reroute(fix.pos, dest)        # hands off to planning tier
  pending = tracker.next_pending(m.along_dist_m)
  if pending:
      maneuver, dist = pending
      if trigger.should_fire(dist, fix):
          emitter.emit(maneuver, fix)
          tracker.mark_announced(maneuver.id)
  

• Satisfies: SWR-10 (keeps blocking reroute off this loop).

Data model (model/)

@dataclass(frozen=True)
class LatLon:
    lat: float
    lon: float

@dataclass(frozen=True)
class Fix:
    pos: LatLon
    speed_mps: float
    heading_deg: float | None      # may be unreliable at low speed
    t_monotonic: float
    valid: bool

@dataclass(frozen=True)
class Maneuver:
    id: int
    location: LatLon
    type: str                      # turn | keep | uturn | roundabout | arrive ...
    modifier: str | None           # left | right | slight_left ...
    entry_heading: float | None
    exit_heading: float | None
    road_name: str | None

@dataclass(frozen=True)
class Route:
    polyline: list[LatLon]         # dense shape points
    maneuvers: list[Maneuver]      # sparse, ordered along polyline
    destination: LatLon

Maneuver.type/modifier is the fixed internal vocabulary every provider normalizes to; the phrasebook and (later) the LLM phrasing layer key off it. This is the single contract that keeps backend messiness out of the rest of the system.

Concurrency model

Three threads, no shared mutable state except the two state/ slots (last-write-wins, guarded by a lock or an atomic reference):

1. Position poller — PositionSource.read() in a loop → StateStore.put.
2. Decision loop — reads both slots, runs the pipeline above at its cadence, emits directives. Never blocks on I/O.
3. Reroute worker — waits for an off-route signal, calls the (blocking) RouteProvider, swaps ActiveRouteStore. Keeps SWR-10 intact.

Traceability summary

Module	Requirements
route_provider	SWR-1, 9, 12, 13
position	SWR-2, 11
state	SWR-8, 10
matching	SWR-3
maneuvers	SWR-4, 6
trigger	SWR-5, 14
offroute	SWR-7, 8, 15
directive	SWR-6, 9
app	SWR-10

---

Repository layout

codriver/
├── README.md
├── pyproject.toml
├── codriver/
│   ├── app/            # composition root, config, main()
│   ├── model/          # LatLon, Fix, Maneuver, Route
│   ├── route_provider/ # osrm.py, file.py, google.py
│   ├── position/       # gpsd_source.py, nmea_source.py, replay_source.py
│   ├── state/          # StateStore, ActiveRouteStore
│   ├── matching/       # MapMatcher
│   ├── maneuvers/      # ManeuverTracker
│   ├── trigger/        # TriggerPolicy
│   ├── offroute/       # OffRouteMonitor
│   └── directive/      # DirectiveEmitter, Phrasebook
├── ops/                # OSM extract + OSRM preprocessing runbook (not app code)
└── tests/
    ├── fixtures/       # recorded NMEA logs, pre-decoded routes
    └── ...

---

Out of scope, but the seams are placed for them

• TTS — subscribes at DirectiveEmitter; today's emit is print().
• LLM co-driver — a gate before DirectiveEmitter.emit (decide whether to speak) and/or a Phrasebook implementation (decide phrasing). Off the hot path by construction.
• IMU fusion — a PositionSource decorator that fuses I2C accelerometer with GPS to stabilize heading/speed at low speed; the Fix contract is unchanged.
• Rally pace notes — a different RouteProvider (notes authored from a recce run) plus a richer Maneuver vocabulary; the decision tier is reused as-is.