dooers-workers 0.2.0__py3-none-any.whl

dooers/__init__.py

@@ -0,0 +1,73 @@
+from dooers.broadcast import BroadcastManager
+from dooers.config import WorkerConfig
+from dooers.features.analytics import (
+    AnalyticsBatch,
+    AnalyticsCollector,
+    AnalyticsEvent,
+    AnalyticsEventPayload,
+    FeedbackData,
+    WorkerAnalytics,
+)
+from dooers.features.settings import (
+    SettingsBroadcaster,
+    SettingsField,
+    SettingsFieldType,
+    SettingsSchema,
+    SettingsSelectOption,
+    WorkerSettings,
+)
+from dooers.handlers.memory import WorkerMemory
+from dooers.handlers.request import WorkerRequest
+from dooers.handlers.response import WorkerResponse
+from dooers.persistence.base import Persistence
+from dooers.protocol.models import (
+    Actor,
+    ContentPart,
+    DocumentPart,
+    EventType,
+    ImagePart,
+    Run,
+    RunStatus,
+    TextPart,
+    Thread,
+    ThreadEvent,
+)
+from dooers.registry import ConnectionRegistry
+from dooers.server import WorkerServer
+
+__all__ = [
+    # Core
+    "WorkerConfig",
+    "WorkerServer",
+    "WorkerResponse",
+    "WorkerMemory",
+    "WorkerRequest",
+    "ConnectionRegistry",
+    "BroadcastManager",
+    "Persistence",
+    # Protocol models
+    "ContentPart",
+    "TextPart",
+    "ImagePart",
+    "DocumentPart",
+    "Thread",
+    "ThreadEvent",
+    "Run",
+    "RunStatus",
+    "Actor",
+    "EventType",
+    # Analytics
+    "AnalyticsEvent",
+    "AnalyticsEventPayload",
+    "AnalyticsBatch",
+    "AnalyticsCollector",
+    "FeedbackData",
+    "WorkerAnalytics",
+    # Settings
+    "SettingsFieldType",
+    "SettingsField",
+    "SettingsSelectOption",
+    "SettingsSchema",
+    "SettingsBroadcaster",
+    "WorkerSettings",
+]

dooers/broadcast.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from dooers.protocol.frames import (
+    EventAppendPayload,
+    S2C_EventAppend,
+    S2C_ThreadUpsert,
+    ThreadUpsertPayload,
+)
+from dooers.protocol.models import Actor, ContentPart, Thread, ThreadEvent
+from dooers.protocol.parser import serialize_frame
+
+if TYPE_CHECKING:
+    from dooers.persistence.base import Persistence
+    from dooers.registry import ConnectionRegistry
+
+
+def _generate_id() -> str:
+    return str(uuid.uuid4())
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+class BroadcastManager:
+    """
+    Manages broadcasting events from backend to connected WebSocket clients.
+
+    Use this to push messages, notifications, or events from external systems
+    (webhooks, background jobs, etc.) to all connected users of a worker.
+    """
+
+    def __init__(
+        self,
+        registry: ConnectionRegistry,
+        persistence: Persistence,
+        subscriptions: dict[str, set[str]],  # worker_id -> set of subscribed thread_ids per connection
+    ) -> None:
+        self._registry = registry
+        self._persistence = persistence
+        self._subscriptions = subscriptions  # Shared with Router instances
+
+    async def send_event(
+        self,
+        worker_id: str,
+        thread_id: str,
+        content: list[ContentPart],
+        actor: Actor = "system",
+        user_id: str | None = None,
+        user_name: str | None = None,
+        user_email: str | None = None,
+    ) -> tuple[ThreadEvent, int]:
+        """
+        Create and broadcast an event from the backend to all connected clients.
+
+        Args:
+            worker_id: The worker instance to broadcast to
+            thread_id: The thread to add the event to
+            content: Message content (text, images, documents)
+            actor: Event actor (default: "system")
+            user_id: Optional user identifier
+            user_name: Optional display name
+            user_email: Optional email
+
+        Returns:
+            Tuple of (created event, number of connections notified)
+
+        Raises:
+            ValueError: If thread not found
+            PermissionError: If thread belongs to different worker
+        """
+        # Verify thread exists and belongs to worker
+        thread = await self._persistence.get_thread(thread_id)
+        if not thread:
+            raise ValueError(f"Thread {thread_id} not found")
+        if thread.worker_id != worker_id:
+            raise PermissionError(f"Thread {thread_id} belongs to different worker")
+
+        now = _now()
+
+        # Create the event
+        event = ThreadEvent(
+            id=_generate_id(),
+            thread_id=thread_id,
+            run_id=None,
+            type="message",
+            actor=actor,
+            user_id=user_id,
+            user_name=user_name,
+            user_email=user_email,
+            content=content,
+            data=None,
+            created_at=now,
+        )
+
+        # Persist
+        await self._persistence.create_event(event)
+
+        # Update thread timestamp
+        thread.last_event_at = now
+        thread.updated_at = now
+        await self._persistence.update_thread(thread)
+
+        # Broadcast to all connections for this worker
+        frame = S2C_EventAppend(
+            id=_generate_id(),
+            payload=EventAppendPayload(thread_id=thread_id, events=[event]),
+        )
+        message = serialize_frame(frame)
+        count = await self._registry.broadcast(worker_id, message)
+
+        return event, count
+
+    async def send_thread_update(
+        self,
+        worker_id: str,
+        thread: Thread,
+    ) -> int:
+        """
+        Broadcast a thread update to all connected clients.
+
+        Args:
+            worker_id: The worker instance to broadcast to
+            thread: The thread that was updated
+
+        Returns:
+            Number of connections notified
+        """
+        if thread.worker_id != worker_id:
+            raise PermissionError(f"Thread {thread.id} belongs to different worker")
+
+        frame = S2C_ThreadUpsert(
+            id=_generate_id(),
+            payload=ThreadUpsertPayload(thread=thread),
+        )
+        message = serialize_frame(frame)
+        return await self._registry.broadcast(worker_id, message)
+
+    async def create_thread_and_broadcast(
+        self,
+        worker_id: str,
+        user_id: str | None = None,
+        title: str | None = None,
+    ) -> tuple[Thread, int]:
+        """
+        Create a new thread and broadcast it to all connected clients.
+
+        Args:
+            worker_id: The worker instance
+            user_id: Optional user who owns the thread
+            title: Optional thread title
+
+        Returns:
+            Tuple of (created thread, number of connections notified)
+        """
+        now = _now()
+        thread = Thread(
+            id=_generate_id(),
+            worker_id=worker_id,
+            user_id=user_id,
+            title=title,
+            created_at=now,
+            updated_at=now,
+            last_event_at=now,
+        )
+
+        await self._persistence.create_thread(thread)
+
+        frame = S2C_ThreadUpsert(
+            id=_generate_id(),
+            payload=ThreadUpsertPayload(thread=thread),
+        )
+        message = serialize_frame(frame)
+        count = await self._registry.broadcast(worker_id, message)
+
+        return thread, count

dooers/config.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from dooers.features.settings.models import SettingsSchema
+
+
+@dataclass
+class WorkerConfig:
+    database_url: str
+    database_type: Literal["postgres", "sqlite"]
+    table_prefix: str = "worker_"
+    auto_migrate: bool = True
+
+    # Analytics (optional, defaults from settings.py)
+    analytics_enabled: bool = True
+    analytics_webhook_url: str | None = None  # Override default webhook URL
+    analytics_batch_size: int | None = None  # Override default
+    analytics_flush_interval: float | None = None  # Override default
+
+    # Settings
+    settings_schema: "SettingsSchema | None" = None

dooers/features/analytics/__init__.py

@@ -0,0 +1,12 @@
+from .collector import AnalyticsCollector
+from .models import AnalyticsBatch, AnalyticsEvent, AnalyticsEventPayload, FeedbackData
+from .worker_analytics import WorkerAnalytics
+
+__all__ = [
+    "AnalyticsCollector",
+    "AnalyticsBatch",
+    "AnalyticsEvent",
+    "AnalyticsEventPayload",
+    "FeedbackData",
+    "WorkerAnalytics",
+]

dooers/features/analytics/collector.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+from uuid import uuid4
+
+import httpx
+
+from .models import AnalyticsBatch, AnalyticsEvent, AnalyticsEventPayload
+
+if TYPE_CHECKING:
+    from ..registry import ConnectionRegistry
+
+logger = logging.getLogger(__name__)
+
+
+class AnalyticsCollector:
+    """
+    Collects analytics events, broadcasts to subscribers, and batches for webhook delivery.
+
+    Features:
+    - Real-time broadcast to analytics subscribers
+    - Batched webhook delivery (configurable size and interval)
+    - Background flush task for time-based batching
+    """
+
+    def __init__(
+        self,
+        webhook_url: str,
+        registry: ConnectionRegistry,
+        subscriptions: dict[str, set[str]],  # worker_id -> set of ws_ids
+        batch_size: int = 10,
+        flush_interval: float = 5.0,
+    ) -> None:
+        self._webhook_url = webhook_url
+        self._registry = registry
+        self._subscriptions = subscriptions
+        self._batch_size = batch_size
+        self._flush_interval = flush_interval
+        self._buffer: list[AnalyticsEventPayload] = []
+        self._lock = asyncio.Lock()
+        self._flush_task: asyncio.Task[None] | None = None
+        self._http_client: httpx.AsyncClient | None = None
+        self._running = False
+
+    async def start(self) -> None:
+        """Start the background flush task and HTTP client."""
+        if self._running:
+            return
+        self._running = True
+        self._http_client = httpx.AsyncClient(timeout=30.0)
+        self._flush_task = asyncio.create_task(self._flush_loop())
+
+    async def stop(self) -> None:
+        """Stop the background task and flush remaining events."""
+        self._running = False
+        if self._flush_task:
+            self._flush_task.cancel()
+            try:
+                await self._flush_task
+            except asyncio.CancelledError:
+                pass
+            self._flush_task = None
+
+        try:
+            # Flush any remaining events
+            await self._flush()
+        finally:
+            # Always close HTTP client
+            if self._http_client:
+                await self._http_client.aclose()
+                self._http_client = None
+
+    async def track(
+        self,
+        event: str,
+        worker_id: str,
+        thread_id: str | None = None,
+        user_id: str | None = None,
+        run_id: str | None = None,
+        event_id: str | None = None,
+        data: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Track an analytics event.
+
+        Immediately broadcasts to analytics subscribers and adds to batch buffer.
+        """
+        payload = AnalyticsEventPayload(
+            event=event,
+            timestamp=datetime.now(UTC),
+            worker_id=worker_id,
+            thread_id=thread_id,
+            user_id=user_id,
+            run_id=run_id,
+            event_id=event_id,
+            data=data,
+        )
+
+        # Broadcast to analytics subscribers immediately
+        await self._broadcast(worker_id, payload)
+
+        # Add to batch buffer
+        async with self._lock:
+            self._buffer.append(payload)
+            if len(self._buffer) >= self._batch_size:
+                await self._flush_locked()
+
+    async def feedback(
+        self,
+        feedback_type: str,
+        target_type: str,
+        target_id: str,
+        worker_id: str,
+        thread_id: str | None = None,
+        user_id: str | None = None,
+        reason: str | None = None,
+    ) -> None:
+        """Record a feedback event (like or dislike)."""
+        event = AnalyticsEvent.FEEDBACK_LIKE if feedback_type == "like" else AnalyticsEvent.FEEDBACK_DISLIKE
+        await self.track(
+            event=event.value,
+            worker_id=worker_id,
+            thread_id=thread_id,
+            user_id=user_id,
+            data={
+                "target_type": target_type,
+                "target_id": target_id,
+                "reason": reason,
+            },
+        )
+
+    async def _broadcast(self, worker_id: str, payload: AnalyticsEventPayload) -> None:
+        """Broadcast an analytics event to all subscribers for a worker."""
+        from ..protocol.frames import S2C_AnalyticsEvent
+
+        subscriber_ws_ids = self._subscriptions.get(worker_id, set())
+        if not subscriber_ws_ids:
+            return
+
+        message = S2C_AnalyticsEvent(
+            id=str(uuid4()),
+            payload=payload,
+        )
+        message_json = message.model_dump_json()
+
+        # Send to all subscribed connections
+        # subscriber_ws_ids contains the ws_id from Router, which we use to track subscriptions
+        # We need to send to all connections since we can't map ws_id back to ws objects
+        # The subscription dict tracks which ws_ids are subscribed, but we broadcast to all
+        # connections for the worker - this is acceptable for real-time analytics
+        connections = self._registry.get_connections(worker_id)
+        for ws in connections:
+            try:
+                await ws.send_text(message_json)
+            except Exception:
+                logger.warning("Failed to send analytics event to subscriber")
+
+    async def _flush(self) -> None:
+        """Flush the buffer, acquiring lock first."""
+        async with self._lock:
+            await self._flush_locked()
+
+    async def _flush_locked(self) -> None:
+        """Flush the buffer (must be called with lock held)."""
+        if not self._buffer:
+            return
+
+        # Group events by worker_id for separate batches
+        events_by_worker: dict[str, list[AnalyticsEventPayload]] = {}
+        for event in self._buffer:
+            if event.worker_id not in events_by_worker:
+                events_by_worker[event.worker_id] = []
+            events_by_worker[event.worker_id].append(event)
+
+        self._buffer.clear()
+
+        # Send batches per worker
+        for worker_id, events in events_by_worker.items():
+            batch = AnalyticsBatch(
+                batch_id=str(uuid4()),
+                worker_id=worker_id,
+                events=events,
+                sent_at=datetime.now(UTC),
+            )
+            await self._send_to_webhook(batch)
+
+    async def _send_to_webhook(self, batch: AnalyticsBatch) -> None:
+        """Send a batch to the webhook endpoint (fire and forget with retry)."""
+        if not self._http_client:
+            return
+
+        try:
+            response = await self._http_client.post(
+                self._webhook_url,
+                json=batch.model_dump(mode="json"),
+                headers={"Content-Type": "application/json"},
+            )
+            if response.status_code >= 400:
+                logger.warning(
+                    "Analytics webhook returned %d: %s",
+                    response.status_code,
+                    response.text[:200],
+                )
+        except httpx.RequestError as e:
+            logger.warning("Failed to send analytics batch: %s", e)
+
+    async def _flush_loop(self) -> None:
+        """Background task that flushes every flush_interval seconds."""
+        while self._running:
+            try:
+                await asyncio.sleep(self._flush_interval)
+                await self._flush()
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.exception("Error in analytics flush loop: %s", e)

dooers/features/analytics/models.py

@@ -0,0 +1,50 @@
+from datetime import datetime
+from enum import StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+
+class AnalyticsEvent(StrEnum):
+    """Built-in analytics event types."""
+
+    # Automatic events
+    THREAD_CREATED = "thread.created"
+    MESSAGE_C2S = "message.c2s"
+    MESSAGE_S2C = "message.s2c"
+    TOOL_CALLED = "tool.called"
+    ERROR_OCCURRED = "error.occurred"
+
+    # Feedback events
+    FEEDBACK_LIKE = "feedback.like"
+    FEEDBACK_DISLIKE = "feedback.dislike"
+
+
+class AnalyticsEventPayload(BaseModel):
+    """Payload for an analytics event."""
+
+    event: str  # AnalyticsEvent value or custom string
+    timestamp: datetime
+    worker_id: str
+    thread_id: str | None = None
+    user_id: str | None = None
+    run_id: str | None = None
+    event_id: str | None = None
+    data: dict[str, Any] | None = None
+
+
+class FeedbackData(BaseModel):
+    """Feedback targeting information."""
+
+    target_type: Literal["event", "run", "thread"]
+    target_id: str
+    reason: str | None = None
+
+
+class AnalyticsBatch(BaseModel):
+    """Batch of analytics events for webhook delivery."""
+
+    batch_id: str
+    worker_id: str
+    events: list[AnalyticsEventPayload]
+    sent_at: datetime

dooers/features/analytics/worker_analytics.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .collector import AnalyticsCollector
+
+
+class WorkerAnalytics:
+    """
+    Handler API for analytics tracking.
+
+    Provides methods for tracking custom events and recording feedback.
+    Passed as the fourth parameter to handler functions.
+    """
+
+    def __init__(
+        self,
+        worker_id: str,
+        thread_id: str,
+        user_id: str | None,
+        run_id: str | None,
+        collector: AnalyticsCollector,
+    ) -> None:
+        self._worker_id = worker_id
+        self._thread_id = thread_id
+        self._user_id = user_id
+        self._run_id = run_id
+        self._collector = collector
+
+    async def track(self, event: str, data: dict[str, Any] | None = None) -> None:
+        """
+        Track a custom analytics event.
+
+        Args:
+            event: Event name (e.g., "llm.called", "search.performed")
+            data: Optional event-specific data
+        """
+        await self._collector.track(
+            event=event,
+            worker_id=self._worker_id,
+            thread_id=self._thread_id,
+            user_id=self._user_id,
+            run_id=self._run_id,
+            data=data,
+        )
+
+    async def like(
+        self,
+        target_type: str,
+        target_id: str,
+        reason: str | None = None,
+    ) -> None:
+        """
+        Record a like (positive feedback).
+
+        Useful for external sources like WhatsApp where users can't
+        interact with the dashboard directly.
+
+        Args:
+            target_type: Type of target ("event", "run", or "thread")
+            target_id: ID of the target
+            reason: Optional reason for the feedback
+        """
+        await self._collector.feedback(
+            feedback_type="like",
+            target_type=target_type,
+            target_id=target_id,
+            worker_id=self._worker_id,
+            thread_id=self._thread_id,
+            user_id=self._user_id,
+            reason=reason,
+        )
+
+    async def dislike(
+        self,
+        target_type: str,
+        target_id: str,
+        reason: str | None = None,
+    ) -> None:
+        """
+        Record a dislike (negative feedback).
+
+        Useful for external sources like WhatsApp where users can't
+        interact with the dashboard directly.
+
+        Args:
+            target_type: Type of target ("event", "run", or "thread")
+            target_id: ID of the target
+            reason: Optional reason for the feedback
+        """
+        await self._collector.feedback(
+            feedback_type="dislike",
+            target_type=target_type,
+            target_id=target_id,
+            worker_id=self._worker_id,
+            thread_id=self._thread_id,
+            user_id=self._user_id,
+            reason=reason,
+        )

dooers/features/settings/__init__.py

@@ -0,0 +1,12 @@
+from .broadcaster import SettingsBroadcaster
+from .models import SettingsField, SettingsFieldType, SettingsSchema, SettingsSelectOption
+from .worker_settings import WorkerSettings
+
+__all__ = [
+    "SettingsBroadcaster",
+    "SettingsField",
+    "SettingsFieldType",
+    "SettingsSchema",
+    "SettingsSelectOption",
+    "WorkerSettings",
+]