autopilot/_docs/02_document/components/detection_client/description.md

Component — detection_client

Layer: Perception (data plane in) Status: forward-looking design (Rust)

1. Purpose

Bi-directional gRPC client to the external ../detections service. Streams frames out, receives bounding-box detections back. Same bboxes are reused by semantic_analyzer (Tier 2 ROI selection) and by telemetry_stream (operator overlay). This is the only component in autopilot that talks to ../detections.

2. Inputs

Input	Source	Cadence	Notes
Frame	frame_ingest	up to 30 fps	Skipped when ai_locked is set.
Tier-1 service config	startup config	once	gRPC endpoint, TLS settings, request budget, max concurrent streams.

3. Outputs

Output	Consumer	Shape
DetectionBatch	scan_controller, semantic_analyzer, telemetry_stream	{ frame_seq: u64, detections: Vec<Detection>, latency_ms, model_version }
Health metric	health aggregator	gRPC connection state, requests_in_flight, latency_p50/p99, errors_by_kind, model_version.

Detection mirrors the ../detections contract: { class_id, class_name, confidence, bbox_normalized, optional_mask_or_polyline, source_frame_seq }.

4. Key Responsibilities

• Maintain a single bi-directional gRPC stream to ../detections. Reconnect on stream loss with bounded exponential backoff.
• Frame budgeting: respect the Tier-1 ≤100 ms/frame target by dropping older in-flight frames if a new frame arrives before the previous response (configurable).
• Validate the response payload against the schema version the client was built against. Surface a hard error on schema mismatch; do not silently downcast.
• Tag each DetectionBatch with the source frame's monotonic timestamp so downstream consumers can compute end-to-end latency.

5. Internal State

• gRPC channel, stream handle, reconnect state.
• Sliding window of in-flight frame sequence numbers.
• Last-known model version (echoed by ../detections on each response or on stream init).

State is in-process only.

6. Failure Modes

Failure	Detection	Behaviour
../detections unreachable	gRPC connect error	Bounded exponential backoff; health → red after threshold; scan_controller continues but the detection_client health flag is red.
Mid-stream cancellation by server	stream error	Reopen stream; do not lose frames in flight (best-effort retry on the latest only).
Schema mismatch	response decode error	Hard error to the health aggregator; reject the response; alert.
Model version change at runtime	new model_version on the stream	Log it; if the change implies new classes, surface to scan_controller so per-class thresholds can be reloaded.
Consistent latency above budget	latency_p99 > 100 ms over a sliding window	Health → yellow; scan_controller may degrade to alternate-frame inference.

7. Dependencies

In-process: frame_ingest (input), scan_controller / semantic_analyzer / telemetry_stream (output).

External:

• ../detections gRPC service. Contract owner: ../_docs/03_detections.md. Bi-directional streaming.

8. Non-Functional Targets

Concern	Target
Per-frame round-trip latency	≤100 ms (Tier-1 NFR; mostly owned by ../detections, autopilot's call budget respects it)
Reconnect latency	≤2 s after ../detections returns
Throughput	up to 30 fps at 1080p
Backpressure	drop oldest in-flight rather than queue indefinitely

9. Open Questions

• Versioning strategy of the gRPC contract (covered in architecture.md §8 Q4).

10. References

• architecture.md §1, §3, §7.6.
• system-flows.md §F1.
• ../_docs/03_detections.md.
• data_model.md §Detection, §DetectionBatch.