tailcam 1.8.3__py3-none-any.whl

tailcam/__init__.py

@@ -0,0 +1,3 @@
+"""TailCam — view any webcam from anywhere over Tailscale."""
+
+__version__ = "1.8.3"

tailcam/__main__.py

@@ -0,0 +1,4 @@
+from tailcam.cli import main
+
+if __name__ == "__main__":
+    main()

tailcam/activelearning/__init__.py

@@ -0,0 +1,20 @@
+"""Human-in-the-loop active learning.
+
+A labeling model watches frames from your cameras (or an existing dataset),
+keeps confident detections as machine labels, and sends only the uncertain
+frames to Label Studio for human review. Reviewed annotations sync back into
+the training dataset, which then fine-tunes the model of your choice — YOLO
+(the existing Ultralytics pipeline), Florence-2, or Qwen2.5-VL via Unsloth.
+
+Module map:
+
+- :mod:`annotations` — the canonical TailCam annotation format and converters
+  to/from Label Studio and per-model training formats.
+- :mod:`backends` — the labeling-model abstraction (built-in YOLO, trained/BYO
+  models, Ollama, Florence-2, Qwen2.5-VL) with availability reporting.
+- :mod:`florence` / :mod:`qwen` — the VLM backends (lazy heavy imports,
+  graceful degradation when torch/CUDA are missing).
+- :mod:`labelstudio` — Label Studio integration via the official Python SDK.
+- :mod:`service` — the ActiveLearningService loop: capture → infer → route →
+  review → sync → fine-tune.
+"""

tailcam/activelearning/annotations.py

@@ -0,0 +1,230 @@
+"""Canonical annotation format + converters (Label Studio ⇄ TailCam ⇄ models).
+
+TailCam's internal region format is the one the annotation editor and YOLO
+export already use: normalized center/size boxes ``(cx, cy, w, h)`` in 0..1.
+Everything converts through :class:`FrameAnnotation` / :class:`AnnotatedFrame`
+so adding a new annotation source or training format only means one converter.
+
+Label Studio rectangles are percent-based top-left/size (``x, y, width,
+height`` in 0..100), so the conversions here are pure arithmetic — no image
+decoding required.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import asdict, dataclass, field
+
+# Annotation provenance values (who produced the label).
+SOURCE_MACHINE = "machine"
+SOURCE_HUMAN = "human"
+SOURCE_REVIEWED = "reviewed-machine"
+
+
+@dataclass
+class FrameAnnotation:
+    """One labeled region. Coordinates are normalized 0..1 center/size — the
+    same layout as SampleAnnotationRecord, so store writes are direct."""
+
+    label: str
+    cx: float
+    cy: float
+    w: float
+    h: float
+    confidence: float | None = None
+    source: str = SOURCE_MACHINE  # machine | human | reviewed-machine
+
+
+@dataclass
+class AnnotatedFrame:
+    """A frame plus everything the pipeline knows about it — the canonical
+    interchange record between capture, Label Studio, and training export."""
+
+    image_path: str
+    annotations: list[FrameAnnotation] = field(default_factory=list)
+    camera_id: str = ""  # camera source ("" for dataset-file frames)
+    source_video: str = ""  # originating video/recording path, if any
+    timestamp: float = 0.0
+    frame_number: int = 0
+    labeling_model: str = ""  # backend id that pre-labeled the frame
+    dataset_version: int = 1
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def clamp01(value: object) -> float:
+    try:
+        return min(1.0, max(0.0, float(value)))  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        return 0.0
+
+
+# -- Label Studio ------------------------------------------------------------
+
+# Value keys of a Label Studio rectangle result (percent of image size).
+_LS_FROM_NAME = "label"
+_LS_TO_NAME = "image"
+
+
+def label_config_xml(labels: list[str]) -> str:
+    """The default object-detection labeling config: multiple rectangles per
+    image, one class per rectangle. Extend by editing the project in Label
+    Studio (classification/keypoints/segmentation tags can be added alongside)."""
+    label_tags = "\n".join(
+        f'    <Label value="{_xml_escape(lb)}"/>' for lb in labels if lb.strip()
+    )
+    return (
+        "<View>\n"
+        f'  <Image name="{_LS_TO_NAME}" value="$image" zoom="true"/>\n'
+        f'  <RectangleLabels name="{_LS_FROM_NAME}" toName="{_LS_TO_NAME}">\n'
+        f"{label_tags}\n"
+        "  </RectangleLabels>\n"
+        "</View>"
+    )
+
+
+def _xml_escape(text: str) -> str:
+    return (
+        text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+def to_label_studio_predictions(
+    annotations: list[FrameAnnotation], model_id: str
+) -> dict:
+    """Build the ``predictions`` entry for a Label Studio task so the reviewer
+    starts from the model's boxes instead of a blank image."""
+    results = []
+    for i, a in enumerate(annotations):
+        x = clamp01(a.cx - a.w / 2) * 100.0
+        y = clamp01(a.cy - a.h / 2) * 100.0
+        results.append(
+            {
+                "id": f"pred-{i}",
+                "type": "rectanglelabels",
+                "from_name": _LS_FROM_NAME,
+                "to_name": _LS_TO_NAME,
+                "original_width": 100,
+                "original_height": 100,
+                "value": {
+                    "x": x,
+                    "y": y,
+                    "width": min(a.w * 100.0, 100.0 - x),
+                    "height": min(a.h * 100.0, 100.0 - y),
+                    "rotation": 0,
+                    "rectanglelabels": [a.label],
+                },
+                "score": a.confidence,
+            }
+        )
+    scores = [a.confidence for a in annotations if a.confidence is not None]
+    return {
+        "model_version": model_id,
+        "score": min(scores) if scores else None,
+        "result": results,
+    }
+
+
+def to_label_studio_task(frame: AnnotatedFrame, image_data: str, model_id: str) -> dict:
+    """One importable Label Studio task. ``image_data`` is what LS displays —
+    a data URI (uploaded inline, works with zero storage setup) or a served URL."""
+    task: dict = {
+        "data": {
+            "image": image_data,
+            "meta": {
+                "tailcam_image_path": frame.image_path,
+                "camera_id": frame.camera_id,
+                "source_video": frame.source_video,
+                "timestamp": frame.timestamp,
+                "frame_number": frame.frame_number,
+                "labeling_model": frame.labeling_model,
+            },
+        }
+    }
+    if frame.annotations:
+        task["predictions"] = [to_label_studio_predictions(frame.annotations, model_id)]
+    return task
+
+
+def from_label_studio_result(result: list[dict]) -> list[FrameAnnotation]:
+    """Convert one completed Label Studio annotation's ``result`` list into
+    canonical boxes. Non-rectangle regions (relations, classifications added by
+    a customized config) are skipped — they don't map to boxes."""
+    boxes: list[FrameAnnotation] = []
+    for item in result or []:
+        if item.get("type") != "rectanglelabels":
+            continue
+        value = item.get("value") or {}
+        labels = value.get("rectanglelabels") or []
+        if not labels:
+            continue
+        w = clamp01(float(value.get("width", 0)) / 100.0)
+        h = clamp01(float(value.get("height", 0)) / 100.0)
+        if w <= 0 or h <= 0:
+            continue
+        x = clamp01(float(value.get("x", 0)) / 100.0)
+        y = clamp01(float(value.get("y", 0)) / 100.0)
+        boxes.append(
+            FrameAnnotation(
+                label=str(labels[0]),
+                cx=clamp01(x + w / 2),
+                cy=clamp01(y + h / 2),
+                w=w,
+                h=h,
+                confidence=None,
+                source=SOURCE_HUMAN,
+            )
+        )
+    return boxes
+
+
+# -- model training formats ---------------------------------------------------
+
+
+def to_yolo_lines(annotations: list[FrameAnnotation], class_idx: dict[str, int]) -> list[str]:
+    """YOLO detection label lines: ``<class> cx cy w h`` (normalized)."""
+    return [
+        f"{class_idx[a.label]} {a.cx:.6f} {a.cy:.6f} {a.w:.6f} {a.h:.6f}"
+        for a in annotations
+        if a.label in class_idx
+    ]
+
+
+def to_florence_od_string(
+    annotations: list[FrameAnnotation], width: int = 1000, height: int = 1000
+) -> str:
+    """Florence-2 OD target string: ``label<loc_x1><loc_y1><loc_x2><loc_y2>…``
+    with coordinates binned to 0..999 (the model's location vocabulary)."""
+    parts: list[str] = []
+    for a in annotations:
+        x1 = int(clamp01(a.cx - a.w / 2) * (width - 1))
+        y1 = int(clamp01(a.cy - a.h / 2) * (height - 1))
+        x2 = int(clamp01(a.cx + a.w / 2) * (width - 1))
+        y2 = int(clamp01(a.cy + a.h / 2) * (height - 1))
+        parts.append(f"{a.label}<loc_{x1}><loc_{y1}><loc_{x2}><loc_{y2}>")
+    return "".join(parts)
+
+
+def to_qwen_json(annotations: list[FrameAnnotation], width: int, height: int) -> str:
+    """Qwen2.5-VL grounding target: a JSON list of absolute-pixel boxes, the
+    format its detection prompts are trained to emit."""
+    objects = [
+        {
+            "bbox_2d": [
+                int(clamp01(a.cx - a.w / 2) * width),
+                int(clamp01(a.cy - a.h / 2) * height),
+                int(clamp01(a.cx + a.w / 2) * width),
+                int(clamp01(a.cy + a.h / 2) * height),
+            ],
+            "label": a.label,
+        }
+        for a in annotations
+    ]
+    return json.dumps(objects)
+
+
+def now_ts() -> float:
+    return time.time()

tailcam/activelearning/backends.py

@@ -0,0 +1,270 @@
+"""Labeling-model abstraction for the active learning pipeline.
+
+Every model that can watch frames — the built-in YOLO detector, a trained/BYO
+model from the registry, Ollama, Florence-2, Qwen2.5-VL — is wrapped in a
+:class:`LabelingBackend` so the pipeline itself never cares which one runs.
+Backends report their own availability (missing package, missing GPU, wrong
+OS) as human-readable text instead of raising, so the UI can explain what's
+supported on this machine.
+
+Backend ids are stable strings persisted in config:
+
+- ``builtin`` — the plug-and-play object detector.
+- ``model:<id>`` — a trained/BYO *detection* model from the registry.
+- ``ollama`` — the Ollama vision analyzer (whole-frame label, no boxes).
+- ``florence2`` — Florence-2 open-vocabulary detection (see :mod:`florence`).
+- ``qwen2.5-vl`` — Qwen2.5-VL detection via transformers (see :mod:`qwen`).
+
+New models plug in by adding a backend class here (or its own module) and one
+entry in :func:`list_labeling_backends` — the pipeline and UI pick it up.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+import numpy as np
+
+from tailcam.ai.analyzer import Detection, OllamaAnalyzer
+from tailcam.ai.detector import BuiltinDetector
+from tailcam.logging_setup import get_logger
+from tailcam.persistence.store import Store
+
+log = get_logger(__name__)
+
+
+@dataclass
+class BackendInfo:
+    """What the UI needs to render a model choice: can it run here, and if
+    not, what would make it work."""
+
+    id: str
+    name: str
+    kind: str  # "detector" | "vlm" | "classifier"
+    available: bool
+    detail: str = ""  # availability note ("ready", or what's missing)
+    boxes: bool = True  # produces bounding boxes (vs whole-frame labels)
+
+
+@dataclass
+class FinetuneInfo:
+    """One fine-tunable model target and whether this machine can train it."""
+
+    id: str
+    name: str
+    available: bool
+    detail: str = ""
+
+
+class LabelingBackend(Protocol):
+    """What the active learning loop needs from any labeling model."""
+
+    def info(self) -> BackendInfo: ...
+
+    def predict(self, image: np.ndarray) -> list[Detection] | None:
+        """Detections for one frame, or None when inference failed."""
+        ...
+
+
+# -- existing TailCam models ---------------------------------------------------
+
+
+class BuiltinBackend:
+    """The zero-setup object detector (80 COCO classes)."""
+
+    def __init__(self, detector: BuiltinDetector) -> None:
+        self._detector = detector
+
+    def info(self) -> BackendInfo:
+        s = self._detector.status()
+        detail = "ready" if s.status == "ready" else (s.detail or s.error or s.status)
+        return BackendInfo(
+            id="builtin",
+            name=f"Built-in detector ({s.model or 'YOLO'})",
+            kind="detector",
+            available=s.status != "error",
+            detail=detail,
+        )
+
+    def predict(self, image: np.ndarray) -> list[Detection] | None:
+        self._detector.ensure_ready()
+        return self._detector.detect(image)
+
+
+class RegistryModelBackend:
+    """A trained / bring-your-own detection model from the model registry."""
+
+    def __init__(self, store: Store, model_id: int, min_conf: float = 0.05) -> None:
+        self._store = store
+        self.model_id = model_id
+        self._min_conf = min_conf
+        # Lazily-built LocalDetector (imported on first use; torch is optional).
+        self._detector: Any = None
+
+    def info(self) -> BackendInfo:
+        record = self._store.get_model(self.model_id)
+        bid = f"model:{self.model_id}"
+        if record is None:
+            return BackendInfo(
+                id=bid, name=f"model #{self.model_id}", kind="detector",
+                available=False, detail="model no longer exists",
+            )
+        if record.task != "detection":
+            return BackendInfo(
+                id=bid, name=record.name, kind="detector", available=False,
+                detail="classification model — pick a detection model for boxes",
+            )
+        if not record.path:
+            return BackendInfo(
+                id=bid, name=record.name, kind="detector", available=False,
+                detail="no weights yet — train it first",
+            )
+        return BackendInfo(
+            id=bid, name=record.name, kind="detector", available=True, detail="ready"
+        )
+
+    def predict(self, image: np.ndarray) -> list[Detection] | None:
+        if self._detector is None:
+            from tailcam.training.inference import LocalDetector
+
+            record = self._store.get_model(self.model_id)
+            if record is None or not record.path:
+                return None
+            # A deliberately low floor so *uncertain* boxes still surface —
+            # the active-learning threshold does the actual routing.
+            self._detector = LocalDetector(record.path, conf=self._min_conf)
+        return self._detector.detect(image)
+
+
+class OllamaBackend:
+    """The Ollama vision analyzer. Classification-only: the frame's label is
+    reported as one full-frame region so it flows through the same routing."""
+
+    def __init__(self, analyzer: OllamaAnalyzer) -> None:
+        self._analyzer = analyzer
+
+    def info(self) -> BackendInfo:
+        enabled = self._analyzer.enabled
+        return BackendInfo(
+            id="ollama",
+            name=f"Ollama ({self._analyzer.config.model})",
+            kind="classifier",
+            available=enabled,
+            detail="ready" if enabled else "enable AI analysis and start Ollama first",
+            boxes=False,
+        )
+
+    def predict(self, image: np.ndarray) -> list[Detection] | None:
+        result = self._analyzer.analyze(image)
+        if result is None:
+            return None
+        if result.label == "nothing":
+            return []
+        return [
+            Detection(
+                label=result.label, confidence=result.confidence,
+                cx=0.5, cy=0.5, w=1.0, h=1.0,
+            )
+        ]
+
+
+# -- registry -------------------------------------------------------------------
+
+
+def build_labeling_backend(
+    backend_id: str,
+    store: Store,
+    detector: BuiltinDetector,
+    analyzer: OllamaAnalyzer,
+) -> LabelingBackend | None:
+    """Instantiate the backend a config string names, or None if unknown."""
+    if backend_id == "builtin":
+        return BuiltinBackend(detector)
+    if backend_id == "ollama":
+        return OllamaBackend(analyzer)
+    if backend_id == "florence2":
+        from tailcam.activelearning.florence import Florence2Backend
+
+        return Florence2Backend()
+    if backend_id == "qwen2.5-vl":
+        from tailcam.activelearning.qwen import QwenVLBackend
+
+        return QwenVLBackend()
+    if backend_id.startswith("model:"):
+        try:
+            model_id = int(backend_id.split(":", 1)[1])
+        except ValueError:
+            return None
+        return RegistryModelBackend(store, model_id)
+    return None
+
+
+def list_labeling_backends(
+    store: Store, detector: BuiltinDetector, analyzer: OllamaAnalyzer
+) -> list[BackendInfo]:
+    """Everything the labeling-model selector can offer, with availability."""
+    from tailcam.activelearning.florence import Florence2Backend
+    from tailcam.activelearning.qwen import QwenVLBackend
+
+    infos = [BuiltinBackend(detector).info()]
+    for record in store.list_models():
+        if record.task == "detection" and record.id is not None:
+            infos.append(RegistryModelBackend(store, record.id).info())
+    infos.append(OllamaBackend(analyzer).info())
+    infos.append(Florence2Backend().info())
+    infos.append(QwenVLBackend().info())
+    return infos
+
+
+def list_finetune_backends(store: Store) -> list[FinetuneInfo]:
+    """Fine-tune targets with per-machine availability (GPU, packages, OS)."""
+    from tailcam.activelearning.florence import florence_finetune_support
+    from tailcam.activelearning.qwen import qwen_finetune_support
+    from tailcam.training.engine import engine_available, torch_device
+
+    yolo_ok = engine_available()
+    device = torch_device()
+    infos = [
+        FinetuneInfo(
+            id="yolo",
+            name="TailCam YOLO (Ultralytics)",
+            available=yolo_ok,
+            detail=(
+                f"ready · device: {device}" if yolo_ok
+                else "install the training engine: pip install 'tailcam[training]'"
+            ),
+        )
+    ]
+    fl_ok, fl_detail = florence_finetune_support()
+    infos.append(FinetuneInfo(id="florence2", name="Florence-2", available=fl_ok,
+                              detail=fl_detail))
+    qw_ok, qw_detail = qwen_finetune_support()
+    infos.append(FinetuneInfo(id="qwen2.5-vl", name="Qwen2.5-VL (Unsloth)",
+                              available=qw_ok, detail=qw_detail))
+    return infos
+
+
+def platform_summary() -> dict:
+    """OS + accelerator facts for the UI's capability notes."""
+    from tailcam.training.engine import torch_device
+
+    device = torch_device()
+    return {
+        "os": {"darwin": "macos", "win32": "windows"}.get(sys.platform, "linux"),
+        "device": device,
+        "cuda": device == "cuda",
+        "mps": device == "mps",
+    }
+
+
+def model_classes(store: Store, model_id: int) -> list[str]:
+    record = store.get_model(model_id)
+    if record is None:
+        return []
+    try:
+        return list(json.loads(record.classes_json) or [])
+    except (ValueError, TypeError):
+        return []