Module stage 

The Stage trait — the core user-implementable perception contract.

Stages are the primary extension point for adding perception capabilities to the pipeline. Each stage processes one frame at a time and produces structured output.

Design intent: one trait, composed pipelines

The library uses a single Stage trait for all stage types — detection, tracking, classification, scene analysis, etc. The abstraction stays minimal, and specialization happens by convention (which fields a stage populates), not by type hierarchy.

Instead, the pipeline composes stages linearly: earlier stages write fields into StageOutput that later stages read from StageContext::artifacts. Specialization happens by convention (which fields a stage populates), not by type hierarchy.

Supported model patterns

The single-trait design naturally supports several model architectures:

• Classical detector → tracker: a FrameAnalysis stage produces detections, then an Association stage consumes them and produces tracks.
• Joint detection+tracking: a single FrameAnalysis stage sets both detections and tracks in its StageOutput. No separate tracker stage is needed.
• Direct track emitter: a stage produces tracks without intermediate detections. Set detection_id to None on each TrackObservation.
• Richer observations: per-observation metadata (embeddings, features, model-specific scores) is stored in TrackObservation::metadata. Per-track metadata goes in Track::metadata. Per-frame shared data goes in StageOutput::artifacts.

What a stage should do

• Process a single frame and return structured results.
• Read upstream artifacts from StageContext::artifacts.
• Read temporal history from StageContext::temporal.
• Populate only the StageOutput fields it owns.
• Remain stateless across feeds — internal state is per-feed.

What a stage should NOT do

• Block on network I/O (manage async bridges internally).
• Mutate shared global state.
• Produce side-channel output bypassing StageOutput.
• Depend on stage execution order beyond what upstream artifacts provide.
• Accumulate unbounded internal state (use the temporal store instead).

Structs

StageCapabilities

Declares what artifact types a stage produces and consumes.

StageContext

Context provided to every stage invocation.

StageOutput

Output returned by a stage’s process() method.

StageOutputBuilder

Incremental builder for StageOutput.

Enums

StageCategory

Optional category hint for a perception stage.

Traits

Stage

The core user-implementable perception trait.