detstream 0.1.0__tar.gz

detstream-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 catherinepereira
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

detstream-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: detstream
+Version: 0.1.0
+Summary: Modular object detection for live video feeds
+Author: catherinepereira
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/catherinepereira/detstream
+Project-URL: Repository, https://github.com/catherinepereira/detstream
+Keywords: object-detection,video,streaming,yolo,computer-vision
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: opencv-python-headless>=4.9.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: yolo
+Requires-Dist: ultralytics>=8.3.0; extra == "yolo"
+Requires-Dist: torch>=2.2.0; extra == "yolo"
+Provides-Extra: youtube
+Requires-Dist: yt-dlp>=2026.03.17; extra == "youtube"
+Requires-Dist: deno>=2.8.0; extra == "youtube"
+Provides-Extra: supabase
+Requires-Dist: supabase>=2.4.0; extra == "supabase"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Dynamic: license-file
+
+# detstream
+
+Modular object detection framework for live video feeds.
+
+## Pipeline
+
+1. **Source**: Where frames come from. `youtube`, `stream` (RTSP/HLS/HTTP), `file` (a video
+  file or webcam device)
+2. **Detector**: What to look for. `yolo-world`, an open-vocabulary model prompted with a
+  word or phrase (`person`, `forklift`, `bird`). Bring your own by registering one (see Plugins).
+3. **Tracker**: When a detection counts as a sighting. Hysteresis and cooldown give you one
+  alert per sighting instead of one per frame, which is what keeps alerts from becoming spam.
+4. **Sinks**: Where alerts go. `console`, `supabase` (rows + thumbnails for a website),
+  `discord` (rich embeds).
+
+## Install
+
+```bash
+pip install detstream                          # core only
+pip install "detstream[yolo,youtube,supabase]" # for example, everything otterwatch uses
+```
+
+The core install pulls what every feed needs: `numpy`, `opencv-python-headless`
+(decoding and annotation), `pydantic` (config), `pyyaml`, and `httpx`.
+
+| Extra | Enables | Pulls in |
+| --- | --- | --- |
+| `yolo` | the `yolo-world` detector | `ultralytics>=8.3.0`, `torch>=2.2.0`. ultralytics fetches CLIP on first use of the detector |
+| `youtube` | the `youtube` source | `yt-dlp>=2026.03.17` and `deno>=2.8.0`, which ships the deno binary yt-dlp runs to solve YouTube's stream challenge |
+| `supabase` | the `supabase` sink | `supabase>=2.4.0` |
+
+## Run
+
+```bash
+detstream --config examples/otters.yaml
+```
+
+A config lists feeds and shared sink settings:
+
+```yaml
+feeds:
+  - id: monterey-otters
+    name: Monterey Sea Otters
+    source:   { type: youtube, url: "https://www.youtube.com/watch?v=abbR-Ttd-cA" }
+    detector: { type: yolo-world, prompt: otter swimming, confidence_threshold: 0.4 }
+    debounce: { enter_frames: 3, exit_frames: 5, cooldown_s: 120, sample_interval_s: 2 }
+    sinks: [console, supabase]
+sinks:
+  supabase: { bucket: thumbnails, detector_label: yolo-world, retention_hours: 3, thumbnail_width: 960 }
+```
+
+Credentials and webhook URLs are configured in `.env`: `DETSTREAM_SUPABASE_URL`, `DETSTREAM_SUPABASE_KEY`, and `DETSTREAM_DISCORD_WEBHOOK_URL`.
+
+## Plugins
+
+Built-in components register themselves on import. To add your own detector (an HF model, a
+cloud API, a fine-tuned ONNX, etc.), register a factory and declare an entry point:
+
+```python
+# mypkg/detector.py
+from detstream.detectors import detectors, Detection
+
+class MyDetector:
+    def detect(self, frame) -> Detection: ...
+
+@detectors.register("my-model")
+def _build(config: dict) -> MyDetector:
+    return MyDetector(**config)
+```
+
+```toml
+# mypkg/pyproject.toml
+[project.entry-points."detstream.detectors"]
+my-model = "mypkg.detector"
+```
+
+After `pip install`, reference it in config as `detector: { type: my-model, ... }`. detstream
+discovers it through the entry point with no change to detstream itself. The same pattern works
+for `detstream.sources` and `detstream.sinks`.
+
+## Layout
+
+```
+detstream/
+  registry.py     register + create + entry-point discovery
+  config.py       FeedConfig / AppConfig, loads YAML
+  runner.py       per-feed asyncio loop
+  state.py        SightingTracker: hysteresis + cooldown, no I/O
+  events.py       SightingStarted / SightingEnded
+  sources/        youtube, stream, file_device (+ shared reconnect base)
+  detectors/      yolo_world
+  sinks/          console, supabase, discord
+examples/         otters.yaml, eagles.yaml
+tests/            config, registry, sources, state, sinks, detectors
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

detstream-0.1.0/README.md

@@ -0,0 +1,99 @@
+# detstream
+
+Modular object detection framework for live video feeds.
+
+## Pipeline
+
+1. **Source**: Where frames come from. `youtube`, `stream` (RTSP/HLS/HTTP), `file` (a video
+  file or webcam device)
+2. **Detector**: What to look for. `yolo-world`, an open-vocabulary model prompted with a
+  word or phrase (`person`, `forklift`, `bird`). Bring your own by registering one (see Plugins).
+3. **Tracker**: When a detection counts as a sighting. Hysteresis and cooldown give you one
+  alert per sighting instead of one per frame, which is what keeps alerts from becoming spam.
+4. **Sinks**: Where alerts go. `console`, `supabase` (rows + thumbnails for a website),
+  `discord` (rich embeds).
+
+## Install
+
+```bash
+pip install detstream                          # core only
+pip install "detstream[yolo,youtube,supabase]" # for example, everything otterwatch uses
+```
+
+The core install pulls what every feed needs: `numpy`, `opencv-python-headless`
+(decoding and annotation), `pydantic` (config), `pyyaml`, and `httpx`.
+
+| Extra | Enables | Pulls in |
+| --- | --- | --- |
+| `yolo` | the `yolo-world` detector | `ultralytics>=8.3.0`, `torch>=2.2.0`. ultralytics fetches CLIP on first use of the detector |
+| `youtube` | the `youtube` source | `yt-dlp>=2026.03.17` and `deno>=2.8.0`, which ships the deno binary yt-dlp runs to solve YouTube's stream challenge |
+| `supabase` | the `supabase` sink | `supabase>=2.4.0` |
+
+## Run
+
+```bash
+detstream --config examples/otters.yaml
+```
+
+A config lists feeds and shared sink settings:
+
+```yaml
+feeds:
+  - id: monterey-otters
+    name: Monterey Sea Otters
+    source:   { type: youtube, url: "https://www.youtube.com/watch?v=abbR-Ttd-cA" }
+    detector: { type: yolo-world, prompt: otter swimming, confidence_threshold: 0.4 }
+    debounce: { enter_frames: 3, exit_frames: 5, cooldown_s: 120, sample_interval_s: 2 }
+    sinks: [console, supabase]
+sinks:
+  supabase: { bucket: thumbnails, detector_label: yolo-world, retention_hours: 3, thumbnail_width: 960 }
+```
+
+Credentials and webhook URLs are configured in `.env`: `DETSTREAM_SUPABASE_URL`, `DETSTREAM_SUPABASE_KEY`, and `DETSTREAM_DISCORD_WEBHOOK_URL`.
+
+## Plugins
+
+Built-in components register themselves on import. To add your own detector (an HF model, a
+cloud API, a fine-tuned ONNX, etc.), register a factory and declare an entry point:
+
+```python
+# mypkg/detector.py
+from detstream.detectors import detectors, Detection
+
+class MyDetector:
+    def detect(self, frame) -> Detection: ...
+
+@detectors.register("my-model")
+def _build(config: dict) -> MyDetector:
+    return MyDetector(**config)
+```
+
+```toml
+# mypkg/pyproject.toml
+[project.entry-points."detstream.detectors"]
+my-model = "mypkg.detector"
+```
+
+After `pip install`, reference it in config as `detector: { type: my-model, ... }`. detstream
+discovers it through the entry point with no change to detstream itself. The same pattern works
+for `detstream.sources` and `detstream.sinks`.
+
+## Layout
+
+```
+detstream/
+  registry.py     register + create + entry-point discovery
+  config.py       FeedConfig / AppConfig, loads YAML
+  runner.py       per-feed asyncio loop
+  state.py        SightingTracker: hysteresis + cooldown, no I/O
+  events.py       SightingStarted / SightingEnded
+  sources/        youtube, stream, file_device (+ shared reconnect base)
+  detectors/      yolo_world
+  sinks/          console, supabase, discord
+examples/         otters.yaml, eagles.yaml
+tests/            config, registry, sources, state, sinks, detectors
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

detstream-0.1.0/detstream/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("detstream")
+except PackageNotFoundError:
+    __version__ = "0.0.0"

detstream-0.1.0/detstream/__main__.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+import argparse
+import asyncio
+import logging
+import sys
+from .config import load_config
+from .runner import run
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="detstream")
+    parser.add_argument("--config", required=True, help="path to a YAML/JSON feed config")
+    args = parser.parse_args()
+
+    # Force line buffering so log lines appear as they happen
+    sys.stdout.reconfigure(line_buffering=True)
+    sys.stderr.reconfigure(line_buffering=True)
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+
+    app = load_config(args.config)
+    try:
+        asyncio.run(run(app))
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

detstream-0.1.0/detstream/annotate.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+import cv2
+import numpy as np
+from .detectors import Detection
+
+BOX_COLOR = (208, 147, 0)  # BGR (a mid blue)
+BOX_THICKNESS = 3
+
+
+# Draw the detection box and a confidence label onto a copy of the frame. Returns the
+# frame unchanged when there is no box, so it is safe to call on every sampled frame
+def annotate(frame: np.ndarray, detection: Detection, label: str = "") -> np.ndarray:
+    if detection.box is None:
+        return frame
+    out = frame.copy()
+    x1, y1, x2, y2 = (int(v) for v in detection.box)
+    cv2.rectangle(out, (x1, y1), (x2, y2), BOX_COLOR, BOX_THICKNESS)
+
+    text = f"{label} {detection.confidence:.0%}".strip()
+    (tw, th), _ = cv2.getTextSize(text, cv2.FONT_HERSHEY_SIMPLEX, 0.6, 2)
+    ty = max(y1, th + 6)
+    cv2.rectangle(out, (x1, ty - th - 6), (x1 + tw + 6, ty), BOX_COLOR, -1)
+    cv2.putText(
+        out, text, (x1 + 3, ty - 4), cv2.FONT_HERSHEY_SIMPLEX, 0.6, (255, 255, 255), 2
+    )
+    return out

detstream-0.1.0/detstream/config.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+import os
+import re
+from pathlib import Path
+import yaml
+from pydantic import BaseModel, Field, field_validator
+
+_ENV_REF = re.compile(r"\$\{(\w+)\}")
+
+
+class ComponentConfig(BaseModel):
+    type: str
+    # Everything else is the component's own config sub-block, passed through to its
+    # factory. Sources/detectors vary by type, so the schema is intentionally open
+    model_config = {"extra": "allow"}
+
+    def options(self) -> dict:
+        return self.model_dump(exclude={"type"})
+
+
+class DebounceConfig(BaseModel):
+    sample_interval_s: float = 2.0
+    enter_frames: int = 3
+    exit_frames: int = 5
+    cooldown_s: float = 120.0
+
+
+class FeedConfig(BaseModel):
+    id: str
+    name: str
+    source: ComponentConfig
+    detector: ComponentConfig
+    debounce: DebounceConfig = Field(default_factory=DebounceConfig)
+    sinks: list[str] = Field(default_factory=lambda: ["console"])
+
+
+class AppConfig(BaseModel):
+    feeds: list[FeedConfig]
+    # Shared sink settings keyed by sink name, e.g. {"supabase": {...}, "discord": {...}}.
+    # A feed enables a sink by listing its name, the settings come from here
+    sinks: dict[str, dict] = Field(default_factory=dict)
+
+    # A `sinks:` block with everything commented out parses as None
+    @field_validator("sinks", mode="before")
+    @classmethod
+    def _none_sinks_to_empty(cls, v):
+        return v or {}
+
+
+def _expand_env(value):
+    if isinstance(value, str):
+        return _ENV_REF.sub(lambda m: os.environ.get(m.group(1), ""), value)
+    if isinstance(value, dict):
+        return {k: _expand_env(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [_expand_env(v) for v in value]
+    return value
+
+
+def _load_dotenv(path: Path) -> None:
+    env_file = path.parent / ".env"
+    if not env_file.exists():
+        return
+    for line in env_file.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.removeprefix("export ").strip()
+        value = value.strip()
+        if value and value[0] in "'\"":
+            # Quoted value: everything up to the matching quote is literal
+            quote = value[0]
+            end = value.find(quote, 1)
+            value = value[1:end] if end != -1 else value[1:]
+        else:
+            # Unquoted: an inline ` # comment` is not part of the value
+            value = value.split(" #", 1)[0].strip()
+        os.environ.setdefault(key, value)
+
+
+def load_config(path: str | Path) -> AppConfig:
+    path = Path(path)
+    _load_dotenv(path)
+    data = _expand_env(yaml.safe_load(path.read_text()))
+    return AppConfig(**data)

detstream-0.1.0/detstream/detectors/__init__.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Protocol
+import numpy as np
+from ..registry import Registry
+
+
+@dataclass
+class Detection:
+    present: bool
+    confidence: float
+    box: tuple[float, float, float, float] | None = None
+
+
+class Detector(Protocol):
+    def detect(self, frame: np.ndarray) -> Detection: ...
+
+
+detectors: Registry[Detector] = Registry("detstream.detectors")
+
+# Import built-ins so they self-register
+# A deployment that did not install the yolo extra can still use a plugin detector without importing ultralytics
+try:
+    from . import yolo_world  # noqa: F401
+except ImportError:
+    pass

detstream-0.1.0/detstream/detectors/yolo_world.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+import numpy as np
+from . import Detection, detectors
+
+
+# Open-vocabulary detector prompted with a class name
+class YoloWorldDetector:
+    def __init__(self, prompt: str, confidence_threshold: float, weights: str = ""):
+        from ultralytics import YOLO
+
+        self.prompt = prompt
+        self.threshold = confidence_threshold
+        self.model = YOLO(weights or "yolov8s-world.pt")
+        self.model.set_classes([prompt])
+
+    def detect(self, frame: np.ndarray) -> Detection:
+        results = self.model.predict(frame, conf=0.01, verbose=False)
+        best = 0.0
+        box = None
+        for r in results:
+            if r.boxes is None or len(r.boxes) == 0:
+                continue
+            top = int(r.boxes.conf.argmax())
+            conf = float(r.boxes.conf[top])
+            if conf > best:
+                best = conf
+                box = tuple(r.boxes.xyxy[top].cpu().tolist())
+        return Detection(present=best >= self.threshold, confidence=best, box=box)
+
+
+@detectors.register("yolo-world")
+def _build(config: dict) -> YoloWorldDetector:
+    return YoloWorldDetector(
+        prompt=config.get("prompt", "object"),
+        confidence_threshold=config.get("confidence_threshold", 0.4),
+        weights=config.get("weights", ""),
+    )

detstream-0.1.0/detstream/events.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+from dataclasses import dataclass
+import numpy as np
+
+
+@dataclass
+class SightingStarted:
+    feed_id: str
+    confidence: float
+
+
+@dataclass
+class SightingEnded:
+    feed_id: str
+    peak_confidence: float
+    # The peak-confidence frame, annotated, captured over the sighting's life. The
+    # thumbnail is uploaded from this so it matches the stored peak confidence
+    peak_frame: np.ndarray | None = None

detstream-0.1.0/detstream/registry.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+import logging
+from importlib.metadata import entry_points
+from typing import Callable, Generic, TypeVar
+
+log = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+# A factory takes the component's config sub-block (a plain dict) and returns an
+# instance. Built-ins register a factory under a name, config selects by that name
+Factory = Callable[[dict], T]
+
+
+class Registry(Generic[T]):
+    def __init__(self, entry_point_group: str):
+        self._factories: dict[str, Factory[T]] = {}
+        self._group = entry_point_group
+        self._loaded_entry_points = False
+
+    def register(self, name: str) -> Callable[[Factory[T]], Factory[T]]:
+        def decorator(factory: Factory[T]) -> Factory[T]:
+            if name in self._factories:
+                raise ValueError(f"{name!r} is already registered in {self._group}")
+            self._factories[name] = factory
+            return factory
+
+        return decorator
+
+    def create(self, name: str, config: dict) -> T:
+        if name not in self._factories:
+            self._load_entry_points()
+        try:
+            factory = self._factories[name]
+        except KeyError:
+            known = ", ".join(sorted(self._factories)) or "(none)"
+            raise ValueError(f"unknown {self._group} {name!r}; known: {known}") from None
+        return factory(config)
+
+    # Discover plugins declared by installed packages under this group. A plugin's
+    # entry point points at a callable that registers its factories on import, so
+    # loading the module is enough. The value is called if it is callable
+    def _load_entry_points(self) -> None:
+        if self._loaded_entry_points:
+            return
+        self._loaded_entry_points = True
+        for ep in entry_points(group=self._group):
+            try:
+                obj = ep.load()
+                if callable(obj):
+                    obj()
+            except Exception as e:
+                log.warning("failed to load plugin %r in %s: %s", ep.name, self._group, e)

detstream-0.1.0/detstream/runner.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+import asyncio
+import logging
+import os
+from .annotate import annotate
+from .config import AppConfig, FeedConfig
+from .detectors import Detector, detectors
+from .events import SightingStarted
+from .sinks import Sink, sinks as sink_registry
+from .sources import sources as source_registry
+from .state import SightingTracker
+
+log = logging.getLogger(__name__)
+
+
+def build_sinks(feed: FeedConfig, app: AppConfig) -> list[Sink]:
+    built: list[Sink] = []
+    for name in feed.sinks:
+        config = app.sinks.get(name, {})
+        built.append(sink_registry.create(name, config))
+    return built
+
+
+# Restart backoff for a feed whose watch loop crashed
+FEED_RESTART_BACKOFF_S = (5.0, 15.0, 30.0, 60.0)
+
+
+async def _dispatch(sinks: list[Sink], call) -> None:
+    # One sink failing (a network blip on the supabase POST) must not stop the others or
+    # kill the feed, so each call is awaited independently and its error logged
+    results = await asyncio.gather(*(call(s) for s in sinks), return_exceptions=True)
+    for sink, result in zip(sinks, results):
+        if isinstance(result, Exception):
+            log.warning("sink %s failed: %s", type(sink).__name__, result)
+
+
+async def watch_feed(feed: FeedConfig, detector: Detector, sinks: list[Sink]) -> None:
+    tracker = SightingTracker(
+        feed_id=feed.id,
+        enter_frames=feed.debounce.enter_frames,
+        exit_frames=feed.debounce.exit_frames,
+        cooldown_s=feed.debounce.cooldown_s,
+    )
+    loop = asyncio.get_running_loop()
+    source = source_registry.create(
+        feed.source.type,
+        {**feed.source.options(), "interval_s": feed.debounce.sample_interval_s},
+    )
+    async for _ts, frame in source.frames():
+        det = await asyncio.to_thread(detector.detect, frame)
+        # Annotate before the tracker captures the frame, so the saved thumbnail shows
+        # the detection box
+        annotated = annotate(frame, det, feed.name) if det.present else frame
+        event = tracker.update(det.present, det.confidence, annotated, loop.time())
+        if event is None:
+            continue
+        if isinstance(event, SightingStarted):
+            await _dispatch(sinks, lambda s: s.on_sighting_start(event, feed.name))
+        else:
+            await _dispatch(sinks, lambda s: s.on_sighting_end(event))
+
+
+async def supervise_feed(feed: FeedConfig, detector: Detector, sinks: list[Sink]) -> None:
+    attempt = 0
+    while True:
+        try:
+            await watch_feed(feed, detector, sinks)
+            return
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            backoff = FEED_RESTART_BACKOFF_S[min(attempt, len(FEED_RESTART_BACKOFF_S) - 1)]
+            log.exception("feed %s crashed: %s; restarting in %ss", feed.id, e, backoff)
+            attempt += 1
+            await asyncio.sleep(backoff)
+
+
+CLEANUP_INTERVAL_S = float(os.environ.get("DETSTREAM_CLEANUP_INTERVAL_S", str(60 * 60)))
+
+
+# Run each sink's cleanup() on an interval (hourly by default)
+async def cleanup_loop(sinks: list[Sink]) -> None:
+    targets = [s for s in sinks if hasattr(s, "cleanup")]
+    if not targets:
+        return
+    while True:
+        await asyncio.sleep(CLEANUP_INTERVAL_S)
+        for sink in targets:
+            try:
+                await asyncio.to_thread(sink.cleanup)
+            except Exception as e:
+                log.warning("cleanup failed for %s: %s", type(sink).__name__, e)
+
+
+async def run(app: AppConfig) -> None:
+    if not app.feeds:
+        log.error("no feeds configured")
+        return
+
+    tasks = []
+    all_sinks: list[Sink] = []
+    for feed in app.feeds:
+        detector = detectors.create(feed.detector.type, feed.detector.options())
+        sinks = build_sinks(feed, app)
+        all_sinks.extend(sinks)
+        log.info("watching %s with %d sink(s)", feed.id, len(sinks))
+        tasks.append(asyncio.create_task(supervise_feed(feed, detector, sinks)))
+
+    # Dedupe sinks of the same type so cleanup runs once
+    unique_sinks = list({type(s): s for s in all_sinks}.values())
+    tasks.append(asyncio.create_task(cleanup_loop(unique_sinks)))
+
+    try:
+        await asyncio.gather(*tasks)
+    except asyncio.CancelledError:
+        for t in tasks:
+            t.cancel()
+        raise

detstream-0.1.0/detstream/sinks/__init__.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+from typing import Protocol
+from ..events import SightingEnded, SightingStarted
+from ..registry import Registry
+
+
+class Sink(Protocol):
+    async def on_sighting_start(self, event: SightingStarted, feed_name: str) -> None: ...
+    async def on_sighting_end(self, event: SightingEnded) -> None: ...
+
+
+sinks: Registry[Sink] = Registry("detstream.sinks")
+
+# console has no optional deps. The others self-register but their factories import their
+# client libraries lazily, so a deployment only pays for the sinks it enables
+from . import console  # noqa: E402,F401
+
+try:
+    from . import supabase  # noqa: F401
+except ImportError:
+    pass
+try:
+    from . import discord  # noqa: F401
+except ImportError:
+    pass