# What ANTAR is, and what it is not

One page, so nobody has to guess. If anything elsewhere in this repository reads as a
bigger claim than what is below, this page is the correct one.

---

## Built and working

You can run all of this yourself, today, with no hardware.

| Thing | Where | What it does |
|---|---|---|
| Road simulator | `simulation/antar-sim.html` | The full detection loop, running in your browser. Open it and press a scenario button. |
| Detection logic | inside the simulator, ported to `backend/antar/detector.py` | Arrival windows, concurrent tracking, corroboration, confidence, dispatch decision. This is real code making real decisions from the events it is given. |
| 3D pod explorer | `pod/index.html` | An interactive model of the **proposed** pod. A drawing you can rotate, not a photograph. |
| Control-room backend | `backend/` | Optional. FastAPI, WebSocket, SQLite, incident lifecycle, alert fan-out, pod health and re-pairing, field-ingestion API. 51 automated tests. |
| Pod failure and re-pairing | `backend/`, and the detector itself | A pod can be taken offline; the pair re-forms across a longer gap and the alert threshold rises from 0.66 to 0.82. Not visible on the live link — see [docs/control-room.md](docs/control-room.md). |
| Replay harness | `backend/tools/replay.py` | Re-runs the detector over traffic it has not seen and prints the results quoted below. |

## Simulated

Everything the detector reacts to is generated by a traffic model:

- Vehicles, their speeds, lengths and signatures.
- The crash and the legal turn-off.
- Pod-to-pod relay, the tower hand-off, and transmission latencies.
- The hospital, the highway patrol and the local responders. **No real person or service is
  contacted, ever.** Telegram alerts, if configured, go to your own chat.
- Pod heartbeats, battery levels and signal strength.

The detector is never told which scenario is running. It receives only pod events. That
separation is the point of the demo, and it is worth checking if you are sceptical.

## Measured (in simulation)

From `python tools/replay.py` inside `backend/` — 20 traffic seeds per scenario, with all
pods healthy and again with one pod dark, 120 runs:

- **120/120** ended in the expected decision.
- Incident: dispatched every time. Confidence 0.83–0.89 healthy, 0.84–0.97 re-paired.
- Legal turn-off: dismissed every time. Confidence peaked at 0.53 healthy and 0.63
  re-paired, against a dispatch threshold of 0.66.
- Time from the vehicle stopping to the alert: **67 s median, 100 s worst** with healthy
  pods; **199 s median** when re-paired across a wider gap.

`--seeds 40` runs a larger 240-run sweep. These are properties of the model, not of any
road.

## Not built

- **No pod exists.** Nothing has been manufactured, assembled or mounted on a pole.
- **No firmware exists.** Not a line.
- **No sensor has been selected.** The detector needs a passage time, a speed, a length and
  a repeatable signature. An ultrasonic pair (shown in the 3D model), a magnetometer or
  inductive loop, and radar are all candidates. None has been tested.
- **No radio range has been measured**, so the pod-to-pod relay distance is an assumption.
- **No field data.** Not one real vehicle, pass or crash.
- **No emergency-service integration.** No agreement, interface or conversation with any
  hospital, police unit or ambulance service.
- **No costed bill of materials.** ₹2,500 per pod is a design target, not a quote.
- **No weatherproofing, certification or road-authority approval.**
- **No security hardening.** The backend API has no operator authentication and its storage
  is ephemeral. It is demo-grade.

## Known weaknesses

Worth saying out loud, because they would come up in review anyway.

- A non-crash blockage — livestock, a breakdown, waterlogging, a procession — produces the
  same evidence as a crash. ANTAR would dispatch.
- A crash that leaves the carriageway clear produces no evidence, and ANTAR would miss it.
  The system detects blockage, and infers a crash from it.
- Very light traffic weakens the corroboration signal. With too few vehicles behind, there
  is nothing to testify.
- When a pod is dark and the segment is longer, the margin between a turn-off and a crash
  narrows (0.63 against a 0.66 threshold in the replay). That is why confidence drops a
  tier in that state.
- Thresholds and weights are tuned against the model. Real road data would move them.

## The honest summary

The hard part of this problem is telling a crash apart from an ordinary turn-off when both
look identical at the moment of absence. ANTAR answers that with corroboration from the
traffic behind, and the answer works consistently in simulation. Everything physical
remains a design.