AI

cht/agent/base.py

@@ -0,0 +1,38 @@
+"""
+Abstract base for agent providers.
+
+Each provider takes a user message + session context and yields response
+text chunks for streaming into the UI.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Iterator
+
+
+@dataclass
+class FrameRef:
+    id: str           # "F0001"
+    path: Path        # absolute path to JPEG
+    timestamp: float  # seconds into recording
+
+
+@dataclass
+class SessionContext:
+    session_dir: Path
+    frames: list[FrameRef]               # all captured frames so far
+    duration: float                       # current recording duration (seconds)
+    mentioned_frames: list[FrameRef] = field(default_factory=list)  # @-referenced in message
+
+
+class AgentProvider(ABC):
+    @abstractmethod
+    def stream(self, message: str, context: SessionContext) -> Iterator[str]:
+        """Yield response text chunks."""
+        ...
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        ...