SEF Core Documentation

This documentation describes the public SEF core contracts for users who build pipeline integrations, write plugins, expose APIs, or maintain UI adapters.

SEF core is the stable layer of the project. It owns pipeline orchestration, typed artifacts, plugin resolution, config versioning, streaming decisions, runtime errors, and UI-agnostic output contracts. Concrete implementations such as OpenCV extractors, YOLO pose components, Matplotlib visualizers, and Streamlit views are adapters around this core.

Documentation Map

• Overview: architecture and responsibility boundaries.
• Getting Started: a minimal runnable pipeline.
• Public API: stable import surfaces and compatibility rules.
• Configuration: versioned config schema reference.
• Registry: plugin registration, aliases, metadata, snapshots.
• Plugin Authoring: how to implement new components.
• Streaming Runtime: streaming contracts, planner, buffers.
• Error Handling: typed errors and handling patterns.
• Versioning: library, config, plugin, and deprecation policy.
• Examples: runnable example modules and expected outputs.
• Reference: Component Contracts
• Reference: Data and Artifacts
• Reference: Pipeline Runtime
• Reference: Error Model

The older single-page contract reference remains available at Public Contracts, but new documentation should link to the modular pages above.

Build the Documentation Site

Install the optional docs dependencies and run MkDocs from the repository root:

pip install -e ".[docs]"
mkdocs serve

The site navigation is defined in the repository-level mkdocs.yml.

Contract Scope

Public contracts are the names exported from public package initializers:

• library
• library.core
• library.core.artifacts
• library.core.events
• library.core.interfaces
• library.core.interfaces.pipeline
• library.core.pipeline
• library.core.plugins
• library.core.realtime
• library.core.visualization

External code should prefer package-level imports over direct module paths. Direct module paths may continue to work, but package exports define the supported public surface.

Maintainer Standard

Any public contract change should include:

1. a documentation update;
2. a focused test update;
3. an explicit compatibility decision;
4. migration guidance when existing configs or plugins are affected.