voxagent 0.1.0__py3-none-any.whl

voxagent/session/model.py

@@ -0,0 +1,109 @@
+"""Session model for voxagent."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from voxagent.types.messages import Message
+
+
+class Session(BaseModel):
+    """Represents a conversation session."""
+
+    id: str = Field(..., description="Unique session ID (UUID)")
+    key: str = Field(..., description="Session key for resolution")
+    messages: list[Message] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def add_message(self, message: Message) -> None:
+        """Add a message and update timestamp."""
+        self.messages.append(message)
+        self.updated_at = datetime.now(timezone.utc)
+
+    def get_messages(self, limit: int | None = None) -> list[Message]:
+        """Get messages, optionally limited to last N."""
+        if limit is None:
+            return list(self.messages)
+        return list(self.messages[-limit:])
+
+    def clear_messages(self) -> None:
+        """Clear all messages."""
+        self.messages.clear()
+        self.updated_at = datetime.now(timezone.utc)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to dictionary."""
+        return {
+            "id": self.id,
+            "key": self.key,
+            "messages": [m.model_dump() for m in self.messages],
+            "created_at": self.created_at.isoformat(),
+            "updated_at": self.updated_at.isoformat(),
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Session:
+        """Deserialize from dictionary."""
+        messages = [Message(**m) for m in data.get("messages", [])]
+        created_at = data.get("created_at")
+        updated_at = data.get("updated_at")
+
+        if isinstance(created_at, str):
+            created_at = datetime.fromisoformat(created_at)
+        if isinstance(updated_at, str):
+            updated_at = datetime.fromisoformat(updated_at)
+
+        return cls(
+            id=data["id"],
+            key=data["key"],
+            messages=messages,
+            created_at=created_at or datetime.now(timezone.utc),
+            updated_at=updated_at or datetime.now(timezone.utc),
+            metadata=data.get("metadata", {}),
+        )
+
+    @classmethod
+    def create(cls, key: str, **kwargs: Any) -> Session:
+        """Create a new session with generated ID."""
+        return cls(
+            id=str(uuid.uuid4()),
+            key=key,
+            **kwargs,
+        )
+
+
+def resolve_session_key(
+    user_id: str | None = None,
+    channel: str | None = None,
+    thread_id: str | None = None,
+) -> str:
+    """Generate a session key from components.
+
+    Examples:
+        resolve_session_key(user_id="u123") -> "user:u123"
+        resolve_session_key(channel="general") -> "channel:general"
+        resolve_session_key(user_id="u123", channel="general") -> "user:u123:channel:general"
+    """
+    parts = []
+
+    if user_id and user_id.strip():
+        parts.append(f"user:{user_id}")
+    if channel and channel.strip():
+        parts.append(f"channel:{channel}")
+    if thread_id and thread_id.strip():
+        parts.append(f"thread:{thread_id}")
+
+    if not parts:
+        raise ValueError("At least one of user_id, channel, or thread_id must be provided")
+
+    return ":".join(parts)
+

voxagent/session/storage.py

@@ -0,0 +1,184 @@
+"""Session storage backends for voxagent."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from voxagent.session.model import Session
+
+
+class SessionStorage(ABC):
+    """Abstract base class for session storage backends."""
+
+    @abstractmethod
+    async def load(self, session_key: str) -> "Session | None":
+        """Load a session by key. Returns None if not found."""
+
+    @abstractmethod
+    async def save(self, session: "Session") -> None:
+        """Save a session."""
+
+    @abstractmethod
+    async def delete(self, session_key: str) -> bool:
+        """Delete a session. Returns True if deleted, False if not found."""
+
+    @abstractmethod
+    async def list_keys(self) -> list[str]:
+        """List all session keys."""
+
+    @abstractmethod
+    async def exists(self, session_key: str) -> bool:
+        """Check if a session exists."""
+
+
+class InMemorySessionStorage(SessionStorage):
+    """In-memory storage for testing."""
+
+    def __init__(self) -> None:
+        self._sessions: dict[str, "Session"] = {}
+
+    async def load(self, session_key: str) -> "Session | None":
+        return self._sessions.get(session_key)
+
+    async def save(self, session: "Session") -> None:
+        self._sessions[session.key] = session
+
+    async def delete(self, session_key: str) -> bool:
+        if session_key in self._sessions:
+            del self._sessions[session_key]
+            return True
+        return False
+
+    async def list_keys(self) -> list[str]:
+        return list(self._sessions.keys())
+
+    async def exists(self, session_key: str) -> bool:
+        return session_key in self._sessions
+
+
+class FileSessionStorage(SessionStorage):
+    """File-based storage using JSONL format."""
+
+    def __init__(self, base_dir: Path | str) -> None:
+        self.base_dir = Path(base_dir)
+        self.base_dir.mkdir(parents=True, exist_ok=True)
+        # Map sanitized filename stems to original keys
+        self._key_map: dict[str, str] = {}
+
+    def _sanitize_key(self, session_key: str) -> str:
+        """Sanitize key for filesystem safety."""
+        return session_key.replace(":", "_").replace("/", "_").replace("\\", "_")
+
+    def _get_session_path(self, session_key: str) -> Path:
+        """Get file path for a session key."""
+        safe_key = self._sanitize_key(session_key)
+        return self.base_dir / f"{safe_key}.jsonl"
+
+    async def load(self, session_key: str) -> "Session | None":
+        from voxagent.session.model import Session
+
+        path = self._get_session_path(session_key)
+        if not path.exists():
+            return None
+
+        with open(path, "r", encoding="utf-8") as f:
+            lines = f.readlines()
+
+        if not lines:
+            return None
+
+        # First line is session metadata
+        metadata = json.loads(lines[0])
+
+        # Remaining lines are messages
+        messages_data = []
+        for line in lines[1:]:
+            if line.strip():
+                msg_data = json.loads(line)
+                messages_data.append(msg_data)
+
+        return Session.from_dict({
+            "id": metadata["id"],
+            "key": metadata["key"],
+            "messages": messages_data,
+            "created_at": metadata.get("created_at"),
+            "updated_at": metadata.get("updated_at"),
+            "metadata": metadata.get("metadata", {}),
+        })
+
+    async def save(self, session: "Session") -> None:
+        path = self._get_session_path(session.key)
+
+        # Ensure directory exists
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Atomic write: write to temp file, then rename
+        fd, temp_path = tempfile.mkstemp(
+            dir=self.base_dir,
+            prefix=".tmp_",
+            suffix=".jsonl",
+        )
+
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                # First line: session metadata
+                metadata = {
+                    "id": session.id,
+                    "key": session.key,
+                    "created_at": session.created_at.isoformat(),
+                    "updated_at": session.updated_at.isoformat(),
+                    "metadata": session.metadata,
+                }
+                f.write(json.dumps(metadata) + "\n")
+
+                # Remaining lines: one message per line
+                for msg in session.messages:
+                    f.write(json.dumps(msg.model_dump()) + "\n")
+
+            # Atomic rename
+            Path(temp_path).rename(path)
+        except Exception:
+            # Clean up temp file on error
+            if os.path.exists(temp_path):
+                os.unlink(temp_path)
+            raise
+
+    async def delete(self, session_key: str) -> bool:
+        path = self._get_session_path(session_key)
+        if path.exists():
+            path.unlink()
+            return True
+        return False
+
+    async def list_keys(self) -> list[str]:
+        keys = []
+        for path in self.base_dir.glob("*.jsonl"):
+            if not path.name.startswith(".tmp_"):
+                # Read the key from the file metadata
+                try:
+                    with open(path, "r", encoding="utf-8") as f:
+                        first_line = f.readline()
+                        if first_line.strip():
+                            metadata = json.loads(first_line)
+                            keys.append(metadata["key"])
+                except (json.JSONDecodeError, KeyError, OSError):
+                    # Skip corrupted files
+                    pass
+        return keys
+
+    async def exists(self, session_key: str) -> bool:
+        return self._get_session_path(session_key).exists()
+
+
+__all__ = [
+    "FileSessionStorage",
+    "InMemorySessionStorage",
+    "SessionStorage",
+]
+

voxagent/streaming/__init__.py

@@ -0,0 +1,52 @@
+"""Event streaming infrastructure.
+
+This subpackage provides:
+- StreamResult wrapper for streaming responses
+- Event emitter for typed events
+- Lifecycle events (RUN_START, RUN_END, etc.)
+- Tool events (TOOL_START, TOOL_OUTPUT, TOOL_END)
+- Typed event data models
+"""
+
+from voxagent.streaming.emitter import (
+    EventCallback,
+    EventEmitter,
+    StreamEvent,
+    WildcardCallback,
+)
+from voxagent.streaming.events import (
+    AssistantEndEvent,
+    AssistantStartEvent,
+    BaseEvent,
+    CompactionEndEvent,
+    CompactionStartEvent,
+    RunEndEvent,
+    RunErrorEvent,
+    RunStartEvent,
+    StreamEventData,
+    TextDeltaEvent,
+    ToolEndEvent,
+    ToolOutputEvent,
+    ToolStartEvent,
+)
+
+__all__ = [
+    "AssistantEndEvent",
+    "AssistantStartEvent",
+    "BaseEvent",
+    "CompactionEndEvent",
+    "CompactionStartEvent",
+    "EventCallback",
+    "EventEmitter",
+    "RunEndEvent",
+    "RunErrorEvent",
+    "RunStartEvent",
+    "StreamEvent",
+    "StreamEventData",
+    "TextDeltaEvent",
+    "ToolEndEvent",
+    "ToolOutputEvent",
+    "ToolStartEvent",
+    "WildcardCallback",
+]
+

voxagent/streaming/emitter.py

@@ -0,0 +1,286 @@
+"""Event emitter for streaming events.
+
+Provides typed event emission for the agent lifecycle including
+run, inference, tool, and context compaction events.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import threading
+from collections.abc import Awaitable
+from enum import Enum
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+class StreamEvent(str, Enum):
+    """Stream event types for the agent lifecycle.
+
+    Based on algorithm specification from agent_algorithm.md.
+    """
+
+    # Lifecycle events
+    RUN_START = "run_start"
+    RUN_END = "run_end"
+    RUN_ERROR = "run_error"
+
+    # Inference events
+    ASSISTANT_START = "assistant_start"
+    TEXT_DELTA = "text_delta"
+    ASSISTANT_END = "assistant_end"
+
+    # Tool events
+    TOOL_START = "tool_start"
+    TOOL_OUTPUT = "tool_output"
+    TOOL_END = "tool_end"
+
+    # Context events
+    COMPACTION_START = "compaction_start"
+    COMPACTION_END = "compaction_end"
+
+
+# Type aliases for callbacks
+EventCallback = Callable[[Any], None] | Callable[[Any], Awaitable[None]]
+WildcardCallback = (
+    Callable[[StreamEvent | str, Any], None]
+    | Callable[[StreamEvent | str, Any], Awaitable[None]]
+)
+
+
+class EventEmitter:
+    """Event emitter for typed streaming events.
+
+    Thread-safe event emitter supporting both sync and async callbacks.
+    Supports wildcard listeners that receive all events.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the event emitter with empty listener storage."""
+        self._listeners: dict[StreamEvent | str, list[EventCallback]] = {}
+        self._once_callbacks: set[EventCallback] = set()
+        self._wildcard_listeners: list[WildcardCallback] = []
+        self._lock = threading.Lock()
+
+    def on(
+        self, event_type: StreamEvent | str, callback: EventCallback
+    ) -> Callable[[], None]:
+        """Register a callback for an event type.
+
+        Args:
+            event_type: The event type to listen for.
+            callback: The callback function to invoke when event is emitted.
+
+        Returns:
+            An unsubscribe function that removes this callback.
+        """
+        with self._lock:
+            if event_type not in self._listeners:
+                self._listeners[event_type] = []
+            self._listeners[event_type].append(callback)
+
+        def unsubscribe() -> None:
+            self.off(event_type, callback)
+
+        return unsubscribe
+
+    def off(self, event_type: StreamEvent | str, callback: EventCallback) -> None:
+        """Unregister a callback for an event type.
+
+        Args:
+            event_type: The event type to unregister from.
+            callback: The callback to remove.
+        """
+        with self._lock:
+            if event_type in self._listeners:
+                try:
+                    self._listeners[event_type].remove(callback)
+                except ValueError:
+                    pass  # Callback was not registered
+            # Also remove from once callbacks if present
+            self._once_callbacks.discard(callback)
+
+    def once(
+        self, event_type: StreamEvent | str, callback: EventCallback
+    ) -> Callable[[], None]:
+        """Register a one-time callback that auto-removes after first call.
+
+        Args:
+            event_type: The event type to listen for.
+            callback: The callback function to invoke once.
+
+        Returns:
+            An unsubscribe function that removes this callback.
+        """
+        with self._lock:
+            if event_type not in self._listeners:
+                self._listeners[event_type] = []
+            self._listeners[event_type].append(callback)
+            self._once_callbacks.add(callback)
+
+        def unsubscribe() -> None:
+            self.off(event_type, callback)
+
+        return unsubscribe
+
+    def emit(self, event_type: StreamEvent | str, data: Any = None) -> None:
+        """Emit an event synchronously to all registered listeners.
+
+        Exceptions in callbacks are caught and logged, but do not prevent
+        other callbacks from being called.
+
+        Args:
+            event_type: The event type to emit.
+            data: Optional data payload to pass to callbacks.
+        """
+        # Get a snapshot of callbacks to call
+        with self._lock:
+            callbacks = list(self._listeners.get(event_type, []))
+            wildcard_callbacks = list(self._wildcard_listeners)
+            once_callbacks = self._once_callbacks.copy()
+
+        # Call specific event callbacks
+        for callback in callbacks:
+            try:
+                callback(data)
+            except Exception:
+                logger.exception(
+                    "Exception in event callback for %s", event_type
+                )
+
+            # Remove if it was a once callback
+            if callback in once_callbacks:
+                self.off(event_type, callback)
+
+        # Call wildcard callbacks
+        for callback in wildcard_callbacks:
+            try:
+                callback(event_type, data)
+            except Exception:
+                logger.exception(
+                    "Exception in wildcard callback for %s", event_type
+                )
+
+    async def emit_async(
+        self, event_type: StreamEvent | str, data: Any = None
+    ) -> None:
+        """Emit an event asynchronously, awaiting async callbacks.
+
+        Handles both sync and async callbacks. Exceptions in callbacks are
+        caught and logged, but do not prevent other callbacks from being called.
+
+        Args:
+            event_type: The event type to emit.
+            data: Optional data payload to pass to callbacks.
+        """
+        # Get a snapshot of callbacks to call
+        with self._lock:
+            callbacks = list(self._listeners.get(event_type, []))
+            wildcard_callbacks = list(self._wildcard_listeners)
+            once_callbacks = self._once_callbacks.copy()
+
+        # Call specific event callbacks
+        for callback in callbacks:
+            try:
+                result = callback(data)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception:
+                logger.exception(
+                    "Exception in async event callback for %s", event_type
+                )
+
+            # Remove if it was a once callback
+            if callback in once_callbacks:
+                self.off(event_type, callback)
+
+        # Call wildcard callbacks
+        for callback in wildcard_callbacks:
+            try:
+                result = callback(event_type, data)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception:
+                logger.exception(
+                    "Exception in async wildcard callback for %s", event_type
+                )
+
+    def on_any(self, callback: WildcardCallback) -> Callable[[], None]:
+        """Register a wildcard callback that receives all events.
+
+        Args:
+            callback: The callback function receiving (event_type, data).
+
+        Returns:
+            An unsubscribe function that removes this callback.
+        """
+        with self._lock:
+            self._wildcard_listeners.append(callback)
+
+        def unsubscribe() -> None:
+            self.off_any(callback)
+
+        return unsubscribe
+
+    def off_any(self, callback: WildcardCallback) -> None:
+        """Unregister a wildcard callback.
+
+        Args:
+            callback: The wildcard callback to remove.
+        """
+        with self._lock:
+            try:
+                self._wildcard_listeners.remove(callback)
+            except ValueError:
+                pass  # Callback was not registered
+
+    def clear(self, event_type: StreamEvent | str | None = None) -> None:
+        """Clear all listeners, or listeners for a specific event.
+
+        Args:
+            event_type: If provided, clear only listeners for this event.
+                       If None, clear all listeners including wildcards.
+        """
+        with self._lock:
+            if event_type is None:
+                self._listeners.clear()
+                self._once_callbacks.clear()
+                self._wildcard_listeners.clear()
+            else:
+                if event_type in self._listeners:
+                    # Remove any once callbacks for this event
+                    for cb in self._listeners[event_type]:
+                        self._once_callbacks.discard(cb)
+                    del self._listeners[event_type]
+
+    def listener_count(self, event_type: StreamEvent | str | None = None) -> int:
+        """Return the number of listeners for an event type.
+
+        Args:
+            event_type: The event type to count listeners for.
+                       If None, returns total count of all listeners.
+
+        Returns:
+            The number of listeners registered for the event type.
+        """
+        with self._lock:
+            if event_type is None:
+                total = sum(len(cbs) for cbs in self._listeners.values())
+                total += len(self._wildcard_listeners)
+                return total
+            return len(self._listeners.get(event_type, []))
+
+    def has_listeners(self, event_type: StreamEvent | str) -> bool:
+        """Return True if the event type has any listeners.
+
+        Args:
+            event_type: The event type to check.
+
+        Returns:
+            True if there are listeners for this event type.
+        """
+        with self._lock:
+            return len(self._listeners.get(event_type, [])) > 0
+