sef 0.2.0__py3-none-any.whl

sef/__init__.py

@@ -0,0 +1,62 @@
+"""Public Pythonic entrypoint for SEF.
+
+Use this module for concise workflows:
+
+```python
+import sef
+
+outputs = (
+    sef.pipeline("quickstart")
+    .frames("demo_frames", frame_count=3)
+    .signals("demo_signals")
+    .analyze("sample_count")
+    .visualize("summary_text")
+    .run()
+)
+```
+
+Advanced users can still import stable lower-level contracts from
+``sef.core`` or ``sef.core``.
+"""
+
+from sef.api import (
+    OrchestratorFacade,
+    PipelineFacade,
+    analyzer,
+    cleaner,
+    default_registry,
+    frame_extractor,
+    from_config,
+    load_config,
+    normalize_config,
+    orchestrator,
+    pipeline,
+    processor,
+    register_user_plugin,
+    signal_extractor,
+    video,
+    visualizer,
+    webcam,
+)
+from sef.core import PipelineExecutionError
+
+__all__ = [
+    "OrchestratorFacade",
+    "PipelineFacade",
+    "PipelineExecutionError",
+    "analyzer",
+    "cleaner",
+    "default_registry",
+    "frame_extractor",
+    "from_config",
+    "load_config",
+    "normalize_config",
+    "orchestrator",
+    "pipeline",
+    "processor",
+    "register_user_plugin",
+    "signal_extractor",
+    "video",
+    "visualizer",
+    "webcam",
+]

sef/__main__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from sef.cli import main
+
+raise SystemExit(main())

sef/api/__init__.py

@@ -0,0 +1,27 @@
+"""High-level Pythonic SEF API."""
+
+from sef.api.config import load_config, normalize_config
+from sef.api.decorators import analyzer, cleaner, frame_extractor, processor, signal_extractor, visualizer
+from sef.api.orchestrator import OrchestratorFacade, orchestrator
+from sef.api.pipeline import PipelineFacade, from_config, pipeline, video, webcam
+from sef.api.registry import default_registry, register_user_plugin
+
+__all__ = [
+    "OrchestratorFacade",
+    "PipelineFacade",
+    "analyzer",
+    "cleaner",
+    "default_registry",
+    "frame_extractor",
+    "from_config",
+    "load_config",
+    "normalize_config",
+    "orchestrator",
+    "pipeline",
+    "processor",
+    "register_user_plugin",
+    "signal_extractor",
+    "video",
+    "visualizer",
+    "webcam",
+]

sef/api/config.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+from sef.core.pipeline.PipelineConfigVersioning import normalize_pipeline_config
+from sef.core.pipeline.PipelineErrors import ConfigSchemaError
+
+_PIPELINE_STAGE_KEYS = frozenset(
+    {
+        "frame_extractor",
+        "frame_processors",
+        "frame_cleaners",
+        "signal_extractor",
+        "signal_cleaners",
+        "analyzers",
+        "visualizers",
+        "intermediate_frames",
+        "runtime",
+    }
+)
+_FRAME_SOURCE_CONFIG_KEYS = ("resize", "stride", "max_frames")
+_TRACKING_SIGNAL_EXTRACTORS = frozenset(
+    {
+        "opencv_tracker",
+        "opencv_stream_tracker",
+        "opencv_multi_tracker",
+    }
+)
+
+
+def load_config(path: str | Path) -> dict[str, Any]:
+    """
+    Load a SEF pipeline config from JSON or YAML and return the canonical schema.
+
+    The returned mapping is safe to pass to ``sef.from_config`` or
+    ``ConfigPipelineBuilder``. YAML support intentionally lives here instead of
+    in the execution core so the runtime remains independent from file formats.
+    """
+    config_path = Path(path)
+    raw_text = config_path.read_text(encoding="utf-8")
+    suffix = config_path.suffix.lower()
+    if suffix == ".json":
+        loaded = json.loads(raw_text)
+    elif suffix in {".yaml", ".yml"}:
+        loaded = _load_yaml(raw_text, config_path)
+    else:
+        raise ConfigSchemaError(
+            f"Unsupported config file extension '{config_path.suffix}'. Use .json, .yaml, or .yml.",
+            path=str(config_path),
+        )
+    return normalize_config(loaded)
+
+
+def normalize_config(config: Mapping[str, Any]) -> dict[str, Any]:
+    """
+    Normalize user-facing config shapes into the public SEF schema.
+
+    This is the single compatibility entry point for CLI, UI adapters, and
+    facade-based config execution. It accepts both a full top-level config and a
+    bare pipeline section, then applies public schema version normalization.
+    """
+    root = _ensure_root_config(config)
+    versioned = normalize_pipeline_config(root).source_config()
+    pipeline = dict(versioned["pipeline"])
+    _move_frame_source_options(pipeline)
+    _inject_frame_source_path(pipeline)
+    versioned["pipeline"] = pipeline
+    return versioned
+
+
+def _load_yaml(raw_text: str, config_path: Path) -> Any:
+    try:
+        import yaml
+    except ImportError as exc:  # pragma: no cover - exercised only in broken installs
+        raise ConfigSchemaError(
+            "YAML config loading requires PyYAML. Install SEF with its declared runtime dependencies.",
+            path=str(config_path),
+            cause=exc,
+        ) from exc
+
+    return yaml.safe_load(raw_text)
+
+
+def _ensure_root_config(config: Mapping[str, Any]) -> dict[str, Any]:
+    if not isinstance(config, Mapping):
+        raise ConfigSchemaError("'config' must be a mapping.", path="config")
+    root = dict(config)
+    if "pipeline" in root:
+        return root
+    if _PIPELINE_STAGE_KEYS.intersection(root):
+        return {"pipeline": root}
+    raise ConfigSchemaError("Missing required config section 'pipeline'.", path="pipeline")
+
+
+def _move_frame_source_options(pipeline: dict[str, Any]) -> None:
+    frame_extractor = pipeline.get("frame_extractor")
+    if not isinstance(frame_extractor, Mapping):
+        return
+
+    entry = dict(frame_extractor)
+    params = entry.get("params", {})
+    if not isinstance(params, Mapping):
+        return
+
+    normalized_params = dict(params)
+    source_config = normalized_params.get("config", {})
+    normalized_source_config = dict(source_config) if isinstance(source_config, Mapping) else {}
+
+    moved = False
+    for key in _FRAME_SOURCE_CONFIG_KEYS:
+        if key in normalized_params:
+            normalized_source_config[key] = normalized_params.pop(key)
+            moved = True
+
+    if moved:
+        normalized_params["config"] = normalized_source_config
+        entry["params"] = normalized_params
+        pipeline["frame_extractor"] = entry
+
+
+def _inject_frame_source_path(pipeline: dict[str, Any]) -> None:
+    frame_source_path = _frame_source_path(pipeline)
+    if frame_source_path is None:
+        return
+
+    signal_extractor = pipeline.get("signal_extractor")
+    if not isinstance(signal_extractor, Mapping):
+        return
+    extractor_name = str(signal_extractor.get("name", ""))
+    if extractor_name not in _TRACKING_SIGNAL_EXTRACTORS:
+        return
+
+    entry = dict(signal_extractor)
+    params = entry.get("params", {})
+    if not isinstance(params, Mapping):
+        return
+
+    normalized_params = dict(params)
+    extractor_config = normalized_params.get("config", {})
+    normalized_extractor_config = dict(extractor_config) if isinstance(extractor_config, Mapping) else {}
+    normalized_extractor_config.setdefault("source_path", frame_source_path)
+    normalized_params["config"] = normalized_extractor_config
+    entry["params"] = normalized_params
+    pipeline["signal_extractor"] = entry
+
+
+def _frame_source_path(pipeline: Mapping[str, Any]) -> str | None:
+    frame_extractor = pipeline.get("frame_extractor")
+    if not isinstance(frame_extractor, Mapping):
+        return None
+    params = frame_extractor.get("params", {})
+    if not isinstance(params, Mapping):
+        return None
+    raw_path = params.get("path")
+    if not isinstance(raw_path, str) or not raw_path:
+        return None
+    return raw_path

sef/api/decorators.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from sef.api.function_adapters import (
+    FunctionAnalyzer,
+    FunctionFrameExtractor,
+    FunctionFrameProcessor,
+    FunctionSignalCleaner,
+    FunctionSignalExtractor,
+    FunctionVisualizer,
+)
+from sef.api.registry import register_user_plugin
+from sef.core.plugins import PluginCategory, PluginRegistry
+
+
+def frame_extractor(
+    name: str | Callable[..., Any] | None = None,
+    *,
+    registry: PluginRegistry | None = None,
+):
+    """Register a function as a frame extractor."""
+    return _decorator(
+        name,
+        registry=registry,
+        category=PluginCategory.FRAME_EXTRACTOR,
+        factory_builder=lambda function: (lambda **params: FunctionFrameExtractor(function, params)),
+    )
+
+
+def signal_extractor(
+    name: str | Callable[..., Any] | None = None,
+    *,
+    registry: PluginRegistry | None = None,
+):
+    """Register a function as a signal extractor."""
+    return _decorator(
+        name,
+        registry=registry,
+        category=PluginCategory.SIGNAL_EXTRACTOR,
+        factory_builder=lambda function: (lambda **params: FunctionSignalExtractor(function, params)),
+    )
+
+
+def processor(
+    name: str | Callable[..., Any] | None = None,
+    *,
+    registry: PluginRegistry | None = None,
+    accepts_frame: bool = False,
+):
+    """Register a function as a single-frame processor."""
+    return _decorator(
+        name,
+        registry=registry,
+        category=PluginCategory.SINGLE_FRAME_PROCESSOR,
+        factory_builder=lambda function: (
+            lambda accepts_frame=accepts_frame, **params: FunctionFrameProcessor(
+                function,
+                params,
+                accepts_frame=bool(accepts_frame),
+            )
+        ),
+    )
+
+
+def cleaner(
+    name: str | Callable[..., Any] | None = None,
+    *,
+    registry: PluginRegistry | None = None,
+):
+    """Register a function as a signal cleaner."""
+    return _decorator(
+        name,
+        registry=registry,
+        category=PluginCategory.SIGNAL_CLEANER,
+        factory_builder=lambda function: (lambda **params: FunctionSignalCleaner(function, params)),
+    )
+
+
+def analyzer(
+    name: str | Callable[..., Any] | None = None,
+    *,
+    registry: PluginRegistry | None = None,
+):
+    """Register a function as an analyzer."""
+    return _decorator(
+        name,
+        registry=registry,
+        category=PluginCategory.ANALYZER,
+        factory_builder=lambda function: (lambda **params: FunctionAnalyzer(function, params)),
+    )
+
+
+def visualizer(
+    name: str | Callable[..., Any] | None = None,
+    *,
+    registry: PluginRegistry | None = None,
+):
+    """Register a function as a visualizer."""
+    return _decorator(
+        name,
+        registry=registry,
+        category=PluginCategory.VISUALIZER,
+        factory_builder=lambda function: (lambda **params: FunctionVisualizer(function, params)),
+    )
+
+
+def _decorator(
+    name: str | Callable[..., Any] | None,
+    *,
+    registry: PluginRegistry | None,
+    category: PluginCategory,
+    factory_builder: Callable[[Callable[..., Any]], Callable[..., Any]],
+):
+    if callable(name) and not isinstance(name, str):
+        function = name
+        _register(function.__name__, function, registry, category, factory_builder)
+        return function
+
+    def _wrap(function: Callable[..., Any]):
+        plugin_name = name or function.__name__
+        _register(str(plugin_name), function, registry, category, factory_builder)
+        return function
+
+    return _wrap
+
+
+def _register(
+    name: str,
+    function: Callable[..., Any],
+    registry: PluginRegistry | None,
+    category: PluginCategory,
+    factory_builder: Callable[[Callable[..., Any]], Callable[..., Any]],
+) -> None:
+    target = registry.register if registry is not None else register_user_plugin
+    target(
+        category,
+        name,
+        factory_builder(function),
+        f"Function plugin registered through @{category.value}.",
+        metadata={"source": "sef.decorator", "function": f"{function.__module__}.{function.__qualname__}"},
+    )

sef/api/function_adapters.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from sef.core.artifacts.buffer.FrameBuffer import FrameBuffer
+from sef.core.artifacts.Frame import Frame
+from sef.core.interfaces.IAnalyzer import IAnalyzer
+from sef.core.interfaces.IData import IData
+from sef.core.interfaces.IFrameExtractor import IFrameExtractor
+from sef.core.interfaces.ISignal import ISignal
+from sef.core.interfaces.ISignalCleaner import ISignalCleaner
+from sef.core.interfaces.ISignalExtractor import ISignalExtractor
+from sef.core.interfaces.ISingleFrameProcessor import ISingleFrameProcessor
+from sef.core.interfaces.IVisualizer import IVisualizer
+from sef.core.visualization.VisualArtifact import VisualArtifact
+from sef.core.visualization.VisualizationContext import VisualizationContext
+
+
+class FunctionFrameExtractor(IFrameExtractor):
+    """Adapt a plain callable into an ``IFrameExtractor`` plugin."""
+
+    def __init__(self, function: Callable[..., FrameBuffer], params: dict[str, Any], config: dict[str, Any] | None = None) -> None:
+        super().__init__(config)
+        self._function = function
+        self._params = dict(params)
+
+    def extract(self) -> FrameBuffer:
+        return self._function(**self._params)
+
+
+class FunctionSignalExtractor(ISignalExtractor):
+    """Adapt a plain callable into an ``ISignalExtractor`` plugin."""
+
+    def __init__(self, function: Callable[..., ISignal], params: dict[str, Any], config: dict[str, Any] | None = None) -> None:
+        super().__init__(config)
+        self._function = function
+        self._params = dict(params)
+
+    def extract(self, buffer: FrameBuffer) -> ISignal:
+        return self._function(buffer, **self._params)
+
+
+class FunctionSignalCleaner(ISignalCleaner):
+    """Adapt a plain callable into an ``ISignalCleaner`` plugin."""
+
+    def __init__(self, function: Callable[..., ISignal], params: dict[str, Any], config: dict[str, Any] | None = None) -> None:
+        super().__init__(config)
+        self._function = function
+        self._params = dict(params)
+
+    def clean(self, signal: ISignal) -> ISignal:
+        return self._function(signal, **self._params)
+
+
+class FunctionAnalyzer(IAnalyzer):
+    """Adapt a plain callable into an ``IAnalyzer`` plugin."""
+
+    def __init__(self, function: Callable[..., IData], params: dict[str, Any], config: dict[str, Any] | None = None) -> None:
+        super().__init__(config)
+        self._function = function
+        self._params = dict(params)
+
+    def analyze(self, signal: ISignal) -> IData:
+        return self._function(signal, **self._params)
+
+
+class FunctionVisualizer(IVisualizer):
+    """Adapt a plain callable into an ``IVisualizer`` plugin."""
+
+    def __init__(
+        self,
+        function: Callable[..., VisualArtifact | tuple[VisualArtifact, ...] | list[VisualArtifact]],
+        params: dict[str, Any],
+        config: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(config)
+        self._function = function
+        self._params = dict(params)
+        self._accepts_context = "context" in inspect.signature(function).parameters
+
+    def render(
+        self,
+        data: IData,
+        context: VisualizationContext | None = None,
+    ) -> tuple[VisualArtifact, ...]:
+        if self._accepts_context:
+            result = self._function(data, context=context, **self._params)
+        else:
+            result = self._function(data, **self._params)
+        if isinstance(result, VisualArtifact):
+            return (result,)
+        return tuple(result)
+
+
+class FunctionFrameProcessor(ISingleFrameProcessor):
+    """
+    Adapt a plain callable into a single-frame processor.
+
+    By default the callable receives the frame image and may return either a
+    new image array or a complete ``Frame``. Set ``accepts_frame=True`` when
+    the callable needs access to indexes, timestamps, or metadata.
+    """
+
+    def __init__(
+        self,
+        function: Callable[..., Any],
+        params: dict[str, Any],
+        *,
+        accepts_frame: bool = False,
+        config: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(config)
+        self._function = function
+        self._params = dict(params)
+        self._accepts_frame = accepts_frame
+
+    def process(self, frame: Frame) -> Frame:
+        source = frame if self._accepts_frame else frame.image
+        result = self._function(source, **self._params)
+        if isinstance(result, Frame):
+            return result
+        return Frame(
+            image=result,
+            index=frame.index,
+            timestamp_seconds=frame.timestamp_seconds,
+            metadata=dict(frame.metadata),
+        )