dooers-workers 0.2.0__py3-none-any.whl

dooers/features/settings/broadcaster.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from ..registry import ConnectionRegistry, WebSocketProtocol
+    from .models import SettingsSchema
+
+logger = logging.getLogger(__name__)
+
+
+class SettingsBroadcaster:
+    """
+    Broadcasts settings changes to subscribed WebSocket connections.
+
+    Supports:
+    - Snapshot delivery on subscription
+    - Patch broadcast when settings are updated
+    """
+
+    def __init__(
+        self,
+        registry: ConnectionRegistry,
+        subscriptions: dict[str, set[str]],  # worker_id -> set of ws_ids
+    ) -> None:
+        self._registry = registry
+        self._subscriptions = subscriptions
+
+    async def broadcast_snapshot_to_ws(
+        self,
+        worker_id: str,
+        ws: WebSocketProtocol,
+        schema: SettingsSchema,
+        values: dict[str, Any],
+    ) -> None:
+        """Send a settings snapshot directly to a specific WebSocket connection."""
+        from ..protocol.frames import S2C_SettingsSnapshot, SettingsSnapshotPayload
+        from .models import SettingsField
+
+        # Merge defaults with stored values
+        fields_with_values: list[SettingsField] = []
+        for field in schema.fields:
+            field_copy = field.model_copy()
+            if field.id in values:
+                field_copy.value = values[field.id]
+            fields_with_values.append(field_copy)
+
+        message = S2C_SettingsSnapshot(
+            id=str(uuid4()),
+            payload=SettingsSnapshotPayload(
+                worker_id=worker_id,
+                fields=fields_with_values,
+                updated_at=datetime.now(UTC),
+            ),
+        )
+
+        try:
+            await ws.send_text(message.model_dump_json())
+        except Exception:
+            logger.warning("Failed to send settings snapshot")
+
+    async def broadcast_patch(
+        self,
+        worker_id: str,
+        field_id: str,
+        value: Any,
+        exclude_ws: WebSocketProtocol | None = None,
+    ) -> None:
+        """Broadcast a settings patch to all subscribers for a worker."""
+        from ..protocol.frames import S2C_SettingsPatch, SettingsPatchBroadcastPayload
+
+        subscriber_ws_ids = self._subscriptions.get(worker_id, set())
+        if not subscriber_ws_ids:
+            return
+
+        message = S2C_SettingsPatch(
+            id=str(uuid4()),
+            payload=SettingsPatchBroadcastPayload(
+                worker_id=worker_id,
+                field_id=field_id,
+                value=value,
+                updated_at=datetime.now(UTC),
+            ),
+        )
+        message_json = message.model_dump_json()
+
+        # Send to all connections for the worker except the one that made the change
+        connections = self._registry.get_connections(worker_id)
+        for ws in connections:
+            if ws is not exclude_ws:
+                try:
+                    await ws.send_text(message_json)
+                except Exception:
+                    logger.warning("Failed to send settings patch to subscriber")

dooers/features/settings/models.py

@@ -0,0 +1,72 @@
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, model_validator
+
+
+class SettingsFieldType(StrEnum):
+    """Supported field types for worker settings."""
+
+    TEXT = "text"
+    NUMBER = "number"
+    SELECT = "select"
+    CHECKBOX = "checkbox"
+    TEXTAREA = "textarea"
+    PASSWORD = "password"
+    EMAIL = "email"
+    DATE = "date"
+    IMAGE = "image"  # Display-only (QR codes, etc.)
+
+
+class SettingsSelectOption(BaseModel):
+    """Option for select fields."""
+
+    value: str
+    label: str
+
+
+class SettingsField(BaseModel):
+    """Definition of a single settings field."""
+
+    id: str
+    type: SettingsFieldType
+    label: str
+    required: bool = False
+    readonly: bool = False
+    value: Any = None  # Default value
+
+    # Type-specific options
+    placeholder: str | None = None
+    options: list[SettingsSelectOption] | None = None  # For select
+    min: int | float | None = None  # For number
+    max: int | float | None = None  # For number
+    rows: int | None = None  # For textarea
+    src: str | None = None  # For image (display URL)
+    width: int | None = None  # For image
+    height: int | None = None  # For image
+
+
+class SettingsSchema(BaseModel):
+    """Schema definition for worker settings."""
+
+    version: str = "1.0"
+    fields: list[SettingsField]
+
+    @model_validator(mode="after")
+    def validate_unique_ids(self) -> "SettingsSchema":
+        """Ensure all field IDs are unique."""
+        ids = [f.id for f in self.fields]
+        if len(ids) != len(set(ids)):
+            raise ValueError("Field IDs must be unique")
+        return self
+
+    def get_field(self, field_id: str) -> SettingsField | None:
+        """Get a field by its ID."""
+        for field in self.fields:
+            if field.id == field_id:
+                return field
+        return None
+
+    def get_defaults(self) -> dict[str, Any]:
+        """Get default values for all fields."""
+        return {f.id: f.value for f in self.fields}

dooers/features/settings/worker_settings.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..persistence.base import Persistence
+    from .broadcaster import SettingsBroadcaster
+    from .models import SettingsSchema
+
+
+class WorkerSettings:
+    """
+    Handler API for dynamic settings.
+
+    Provides methods for getting and setting worker-level configuration.
+    Passed as the fifth parameter to handler functions.
+    """
+
+    def __init__(
+        self,
+        worker_id: str,
+        schema: SettingsSchema,
+        persistence: Persistence,
+        broadcaster: SettingsBroadcaster,
+    ) -> None:
+        self._worker_id = worker_id
+        self._schema = schema
+        self._persistence = persistence
+        self._broadcaster = broadcaster
+
+    async def get(self, field_id: str) -> Any:
+        """
+        Get a single field value.
+
+        Args:
+            field_id: The field ID to get
+
+        Returns:
+            The field value (stored or default)
+
+        Raises:
+            KeyError: If field_id doesn't exist in schema
+        """
+        field = self._schema.get_field(field_id)
+        if not field:
+            raise KeyError(f"Unknown field: {field_id}")
+
+        values = await self._persistence.get_settings(self._worker_id)
+        return values.get(field_id, field.value)
+
+    async def get_all(self) -> dict[str, Any]:
+        """
+        Get all field values as a dict.
+
+        Returns:
+            Dict mapping field_id to value (stored values merged with defaults)
+        """
+        defaults = self._schema.get_defaults()
+        stored = await self._persistence.get_settings(self._worker_id)
+        return {**defaults, **stored}
+
+    async def set(self, field_id: str, value: Any) -> None:
+        """
+        Update a field value and broadcast to subscribers.
+
+        Args:
+            field_id: The field ID to update
+            value: The new value
+
+        Raises:
+            KeyError: If field_id doesn't exist in schema
+            ValueError: If field is readonly
+        """
+        self._validate_field(field_id, value)
+        await self._persistence.update_setting(self._worker_id, field_id, value)
+        await self._broadcaster.broadcast_patch(self._worker_id, field_id, value)
+
+    def _validate_field(self, field_id: str, value: Any) -> None:
+        """Validate that a field exists and can be set."""
+        field = self._schema.get_field(field_id)
+        if not field:
+            raise KeyError(f"Unknown field: {field_id}")
+        if field.readonly:
+            raise ValueError(f"Field '{field_id}' is readonly")
+        # Additional type validation can be added here in the future

dooers/handlers/__init__.py

@@ -0,0 +1,16 @@
+from dooers.features.analytics.worker_analytics import WorkerAnalytics
+from dooers.features.settings.worker_settings import WorkerSettings
+from dooers.handlers.memory import WorkerMemory
+from dooers.handlers.request import WorkerRequest
+from dooers.handlers.response import WorkerEvent, WorkerResponse
+from dooers.handlers.router import Router
+
+__all__ = [
+    "WorkerResponse",
+    "WorkerEvent",
+    "WorkerRequest",
+    "WorkerMemory",
+    "WorkerAnalytics",
+    "WorkerSettings",
+    "Router",
+]

dooers/handlers/memory.py

@@ -0,0 +1,105 @@
+from typing import TYPE_CHECKING, Any, Literal
+
+from dooers.protocol.models import ThreadEvent
+
+if TYPE_CHECKING:
+    from dooers.persistence.base import Persistence
+
+HistoryFormat = Literal["openai", "anthropic", "google", "cohere", "voyage"]
+
+
+class WorkerMemory:
+    def __init__(self, thread_id: str, persistence: "Persistence"):
+        self._thread_id = thread_id
+        self._persistence = persistence
+
+    async def get_history_raw(self, limit: int = 50) -> list[ThreadEvent]:
+        """
+        Get raw conversation history as ThreadEvent objects.
+
+        Args:
+            limit: Maximum number of events to return
+
+        Returns:
+            List of ThreadEvent objects
+        """
+        return await self._persistence.get_events(
+            thread_id=self._thread_id,
+            after_event_id=None,
+            limit=limit,
+        )
+
+    async def get_history(
+        self,
+        limit: int = 50,
+        format: HistoryFormat = "openai",
+    ) -> list[dict[str, Any]]:
+        """
+        Get conversation history formatted for LLM APIs.
+
+        Args:
+            limit: Maximum number of events to return
+            format: Output format - 'openai', 'anthropic', 'google', 'cohere', 'voyage'
+
+        Returns:
+            List of message dicts in the specified format
+
+        Format examples:
+            openai:    {"role": "user/assistant", "content": "..."}
+            anthropic: {"role": "user/assistant", "content": "..."}
+            google:    {"role": "user/model", "parts": [{"text": "..."}]}
+            cohere:    {"role": "USER/CHATBOT", "message": "..."}
+            voyage:    {"role": "user/assistant", "content": "..."}
+        """
+        events = await self.get_history_raw(limit)
+        messages: list[dict[str, Any]] = []
+
+        for event in events:
+            if event.type != "message" or not event.content:
+                continue
+
+            # Extract text from content parts
+            text = " ".join(part.text for part in event.content if hasattr(part, "text"))
+            if not text:
+                continue
+
+            is_user = event.actor == "user"
+            message = self._format_message(text, is_user, format)
+            messages.append(message)
+
+        return messages
+
+    def _format_message(
+        self,
+        text: str,
+        is_user: bool,
+        format: HistoryFormat,
+    ) -> dict[str, Any]:
+        """Format a single message for the specified provider."""
+        match format:
+            case "openai" | "voyage":
+                return {
+                    "role": "user" if is_user else "assistant",
+                    "content": text,
+                }
+            case "anthropic":
+                return {
+                    "role": "user" if is_user else "assistant",
+                    "content": text,
+                }
+            case "google":
+                return {
+                    "role": "user" if is_user else "model",
+                    "parts": [{"text": text}],
+                }
+            case "cohere":
+                return {
+                    "role": "USER" if is_user else "CHATBOT",
+                    "message": text,
+                }
+            case _:
+                # Default to OpenAI format
+                return {
+                    "role": "user" if is_user else "assistant",
+                    "content": text,
+                }

dooers/handlers/request.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+from dooers.protocol.models import ContentPart
+
+
+@dataclass
+class WorkerRequest:
+    message: str
+    content: list[ContentPart]
+    thread_id: str
+    event_id: str
+    user_id: str | None

dooers/handlers/response.py

@@ -0,0 +1,66 @@
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass
+class WorkerEvent:
+    response_type: str
+    data: dict
+
+
+class WorkerResponse:
+    def text(self, text: str) -> WorkerEvent:
+        return WorkerEvent(
+            response_type="text",
+            data={"text": text},
+        )
+
+    def image(
+        self,
+        url: str,
+        mime_type: str | None = None,
+        alt: str | None = None,
+    ) -> WorkerEvent:
+        return WorkerEvent(
+            response_type="image",
+            data={"url": url, "mime_type": mime_type, "alt": alt},
+        )
+
+    def document(
+        self,
+        url: str,
+        filename: str,
+        mime_type: str,
+    ) -> WorkerEvent:
+        return WorkerEvent(
+            response_type="document",
+            data={"url": url, "filename": filename, "mime_type": mime_type},
+        )
+
+    def tool_call(self, name: str, args: dict) -> WorkerEvent:
+        return WorkerEvent(
+            response_type="tool_call",
+            data={"name": name, "args": args},
+        )
+
+    def tool_result(self, name: str, result: dict) -> WorkerEvent:
+        return WorkerEvent(
+            response_type="tool_result",
+            data={"name": name, "result": result},
+        )
+
+    def run_start(self, agent_id: str | None = None) -> WorkerEvent:
+        return WorkerEvent(
+            response_type="run_start",
+            data={"agent_id": agent_id},
+        )
+
+    def run_end(
+        self,
+        status: Literal["succeeded", "failed"] = "succeeded",
+        error: str | None = None,
+    ) -> WorkerEvent:
+        return WorkerEvent(
+            response_type="run_end",
+            data={"status": status, "error": error},
+        )