django-agent-runtime 0.3.6__py3-none-any.whl

django_agent_runtime/runtime/__init__.py

@@ -0,0 +1,23 @@
+"""
+Runtime module - core execution engine for agent runs.
+
+This module contains:
+- interfaces: Public API contracts (AgentRuntime, RunContext, etc.)
+- registry: Plugin discovery and registration
+- runner: Main execution loop with leasing, retries, cancellation
+"""
+
+from django_agent_runtime.runtime.interfaces import (
+    AgentRuntime,
+    RunContext,
+    RunResult,
+    EventType,
+)
+
+__all__ = [
+    "AgentRuntime",
+    "RunContext",
+    "RunResult",
+    "EventType",
+]
+

django_agent_runtime/runtime/events/__init__.py

@@ -0,0 +1,65 @@
+"""
+Event bus for streaming agent events to UI.
+
+Provides:
+- EventBus: Abstract async interface for event publishing/subscribing
+- SyncEventBus: Abstract sync interface for event publishing
+- DatabaseEventBus: Async database-backed event bus
+- SyncDatabaseEventBus: Sync database-backed event bus
+- RedisEventBus: Uses Redis pub/sub for real-time streaming
+"""
+
+from django_agent_runtime.runtime.events.base import EventBus, Event
+from django_agent_runtime.runtime.events.sync import SyncEventBus, SyncDatabaseEventBus
+
+__all__ = [
+    # Async
+    "EventBus",
+    "Event",
+    # Sync
+    "SyncEventBus",
+    "SyncDatabaseEventBus",
+    # Factory functions
+    "get_event_bus",
+    "get_sync_event_bus",
+]
+
+
+def get_event_bus(backend: str = "db", **kwargs) -> EventBus:
+    """
+    Factory function to get an async event bus instance.
+
+    Args:
+        backend: "db" or "redis"
+        **kwargs: Backend-specific configuration
+
+    Returns:
+        EventBus instance
+    """
+    if backend == "db":
+        from django_agent_runtime.runtime.events.db import DatabaseEventBus
+
+        return DatabaseEventBus(**kwargs)
+    elif backend == "redis":
+        from django_agent_runtime.runtime.events.redis import RedisEventBus
+
+        return RedisEventBus(**kwargs)
+    else:
+        raise ValueError(f"Unknown event bus backend: {backend}")
+
+
+def get_sync_event_bus(backend: str = "db", **kwargs) -> SyncEventBus:
+    """
+    Factory function to get a synchronous event bus instance.
+
+    Args:
+        backend: "db" (only db supported for sync)
+        **kwargs: Backend-specific configuration
+
+    Returns:
+        SyncEventBus instance
+    """
+    if backend == "db":
+        return SyncDatabaseEventBus(**kwargs)
+    else:
+        raise ValueError(f"Unknown or unsupported sync event bus backend: {backend}")

django_agent_runtime/runtime/events/base.py

@@ -0,0 +1,135 @@
+"""
+Abstract base class for event bus implementations.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import AsyncIterator, Optional
+from uuid import UUID
+
+
+@dataclass
+class Event:
+    """
+    An event emitted by an agent runtime.
+
+    Events are the communication channel between workers and UI.
+
+    Visibility:
+        - ui_visible: Whether this event should be displayed in UI
+        - visibility_level: "internal", "debug", or "user"
+
+    The visibility is determined by the event type and configuration.
+    See conf.py EVENT_VISIBILITY for default mappings.
+    """
+
+    run_id: UUID
+    seq: int
+    event_type: str
+    payload: dict = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+    visibility_level: str = field(default="user")  # "internal", "debug", "user"
+    ui_visible: bool = field(default=True)  # Computed based on visibility_level and DEBUG_MODE
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for serialization."""
+        return {
+            "run_id": str(self.run_id),
+            "seq": self.seq,
+            "type": self.event_type,
+            "payload": self.payload,
+            "ts": self.timestamp.isoformat(),
+            "visibility_level": self.visibility_level,
+            "ui_visible": self.ui_visible,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Event":
+        """Create from dictionary."""
+        return cls(
+            run_id=UUID(data["run_id"]),
+            seq=data["seq"],
+            event_type=data["type"],
+            payload=data.get("payload", {}),
+            timestamp=datetime.fromisoformat(data["ts"]),
+            visibility_level=data.get("visibility_level", "user"),
+            ui_visible=data.get("ui_visible", True),
+        )
+
+
+class EventBus(ABC):
+    """
+    Abstract interface for event bus implementations.
+
+    Event buses handle:
+    - Publishing events from workers
+    - Subscribing to events for streaming to UI
+    - Persisting events for replay
+    """
+
+    @abstractmethod
+    async def publish(self, event: Event) -> None:
+        """
+        Publish an event.
+
+        Args:
+            event: Event to publish
+        """
+        ...
+
+    @abstractmethod
+    async def subscribe(
+        self,
+        run_id: UUID,
+        from_seq: int = 0,
+    ) -> AsyncIterator[Event]:
+        """
+        Subscribe to events for a run.
+
+        Args:
+            run_id: Run to subscribe to
+            from_seq: Start from this sequence number (for replay)
+
+        Yields:
+            Events as they arrive
+        """
+        ...
+
+    @abstractmethod
+    async def get_events(
+        self,
+        run_id: UUID,
+        from_seq: int = 0,
+        to_seq: Optional[int] = None,
+    ) -> list[Event]:
+        """
+        Get historical events for a run.
+
+        Args:
+            run_id: Run to get events for
+            from_seq: Start sequence (inclusive)
+            to_seq: End sequence (inclusive), None for all
+
+        Returns:
+            List of events
+        """
+        ...
+
+    @abstractmethod
+    async def get_next_seq(self, run_id: UUID) -> int:
+        """
+        Get the next sequence number for a run.
+
+        Args:
+            run_id: Run to get sequence for
+
+        Returns:
+            Next sequence number (0 if no events)
+        """
+        ...
+
+    async def close(self) -> None:
+        """Close any connections. Override if needed."""
+        pass
+

django_agent_runtime/runtime/events/db.py

@@ -0,0 +1,129 @@
+"""
+Database-backed event bus.
+
+Stores all events in the database. Simple but higher latency for streaming.
+Good for development and low-volume production.
+"""
+
+import asyncio
+from datetime import datetime, timezone
+from typing import AsyncIterator, Optional
+from uuid import UUID
+
+from asgiref.sync import sync_to_async
+from django.db.models import Max
+
+from django_agent_runtime.models import AgentEvent, AgentRun
+from django_agent_runtime.runtime.events.base import EventBus, Event
+
+
+class DatabaseEventBus(EventBus):
+    """
+    Database-backed event bus implementation.
+
+    All events are persisted to the AgentEvent table.
+    Streaming is implemented via polling.
+    """
+
+    def __init__(self, poll_interval: float = 0.5):
+        """
+        Initialize database event bus.
+
+        Args:
+            poll_interval: Seconds between polls when streaming
+        """
+        self.poll_interval = poll_interval
+
+    async def publish(self, event: Event) -> None:
+        """Publish event to database."""
+
+        @sync_to_async
+        def _publish():
+            AgentEvent.objects.create(
+                run_id=event.run_id,
+                seq=event.seq,
+                event_type=event.event_type,
+                payload=event.payload,
+            )
+
+        await _publish()
+
+    async def subscribe(
+        self,
+        run_id: UUID,
+        from_seq: int = 0,
+    ) -> AsyncIterator[Event]:
+        """Subscribe to events via polling."""
+        current_seq = from_seq
+
+        while True:
+            # Get new events
+            events = await self.get_events(run_id, from_seq=current_seq)
+
+            for event in events:
+                yield event
+                current_seq = event.seq + 1
+
+            # Check if run is complete
+            if await self._is_run_complete(run_id):
+                break
+
+            # Poll interval
+            await asyncio.sleep(self.poll_interval)
+
+    @sync_to_async
+    def _is_run_complete(self, run_id: UUID) -> bool:
+        """Check if run is in terminal state."""
+        try:
+            run = AgentRun.objects.get(id=run_id)
+            return run.is_terminal
+        except AgentRun.DoesNotExist:
+            return True
+
+    async def get_events(
+        self,
+        run_id: UUID,
+        from_seq: int = 0,
+        to_seq: Optional[int] = None,
+    ) -> list[Event]:
+        """Get events from database."""
+
+        @sync_to_async
+        def _get():
+            queryset = AgentEvent.objects.filter(
+                run_id=run_id,
+                seq__gte=from_seq,
+            )
+
+            if to_seq is not None:
+                queryset = queryset.filter(seq__lte=to_seq)
+
+            return [
+                Event(
+                    run_id=e.run_id,
+                    seq=e.seq,
+                    event_type=e.event_type,
+                    payload=e.payload,
+                    timestamp=e.timestamp,
+                )
+                for e in queryset.order_by("seq")
+            ]
+
+        return await _get()
+
+    async def get_next_seq(self, run_id: UUID) -> int:
+        """Get next sequence number."""
+
+        @sync_to_async
+        def _get_next():
+            result = AgentEvent.objects.filter(run_id=run_id).aggregate(
+                max_seq=Max("seq")
+            )
+            max_seq = result["max_seq"]
+            # Note: can't use `max_seq or -1` because 0 is falsy!
+            if max_seq is None:
+                return 0
+            return max_seq + 1
+
+        return await _get_next()
+

django_agent_runtime/runtime/events/redis.py

@@ -0,0 +1,228 @@
+"""
+Redis-backed event bus using pub/sub and streams.
+
+Real-time streaming with optional database persistence.
+Recommended for production with high event volume.
+"""
+
+import asyncio
+import json
+from datetime import datetime, timezone
+from typing import AsyncIterator, Optional
+from uuid import UUID
+
+from asgiref.sync import sync_to_async
+from django.db.models import Max
+
+from django_agent_runtime.models import AgentEvent, AgentRun
+from django_agent_runtime.runtime.events.base import EventBus, Event
+
+try:
+    import redis.asyncio as aioredis
+except ImportError:
+    aioredis = None
+
+
+class RedisEventBus(EventBus):
+    """
+    Redis-backed event bus implementation.
+
+    Uses Redis Streams for event storage and pub/sub for real-time notifications.
+    Optionally persists to database for durability.
+    """
+
+    STREAM_PREFIX = "agent_runtime:events:"
+    CHANNEL_PREFIX = "agent_runtime:notify:"
+
+    def __init__(
+        self,
+        redis_url: str,
+        persist_to_db: bool = True,
+        event_ttl_seconds: int = 3600 * 6,  # 6 hours
+        persist_token_deltas: bool = False,
+    ):
+        """
+        Initialize Redis event bus.
+
+        Args:
+            redis_url: Redis connection URL
+            persist_to_db: Whether to also persist events to database
+            event_ttl_seconds: TTL for events in Redis
+            persist_token_deltas: Whether to persist token delta events to DB
+        """
+        if aioredis is None:
+            raise ImportError("redis package is required for RedisEventBus")
+
+        self.redis_url = redis_url
+        self.persist_to_db = persist_to_db
+        self.event_ttl_seconds = event_ttl_seconds
+        self.persist_token_deltas = persist_token_deltas
+        self._redis: Optional[aioredis.Redis] = None
+
+    async def _get_redis(self) -> "aioredis.Redis":
+        """Get or create Redis connection."""
+        if self._redis is None:
+            self._redis = aioredis.from_url(self.redis_url)
+        return self._redis
+
+    def _stream_key(self, run_id: UUID) -> str:
+        """Get Redis stream key for a run."""
+        return f"{self.STREAM_PREFIX}{run_id}"
+
+    def _channel_key(self, run_id: UUID) -> str:
+        """Get Redis pub/sub channel for a run."""
+        return f"{self.CHANNEL_PREFIX}{run_id}"
+
+    async def publish(self, event: Event) -> None:
+        """Publish event to Redis and optionally database."""
+        redis = await self._get_redis()
+
+        # Add to stream
+        stream_key = self._stream_key(event.run_id)
+        await redis.xadd(
+            stream_key,
+            {"data": json.dumps(event.to_dict())},
+        )
+
+        # Set TTL on stream
+        await redis.expire(stream_key, self.event_ttl_seconds)
+
+        # Notify subscribers
+        channel_key = self._channel_key(event.run_id)
+        await redis.publish(channel_key, str(event.seq))
+
+        # Persist to database if configured
+        if self.persist_to_db:
+            # Skip token deltas unless configured
+            if event.event_type == "assistant.delta" and not self.persist_token_deltas:
+                return
+
+            await self._persist_to_db(event)
+
+    @sync_to_async
+    def _persist_to_db(self, event: Event) -> None:
+        """Persist event to database."""
+        AgentEvent.objects.create(
+            run_id=event.run_id,
+            seq=event.seq,
+            event_type=event.event_type,
+            payload=event.payload,
+        )
+
+    async def subscribe(
+        self,
+        run_id: UUID,
+        from_seq: int = 0,
+    ) -> AsyncIterator[Event]:
+        """Subscribe to events using pub/sub for notifications."""
+        redis = await self._get_redis()
+        pubsub = redis.pubsub()
+        channel_key = self._channel_key(run_id)
+
+        await pubsub.subscribe(channel_key)
+
+        try:
+            # First, get any existing events
+            events = await self.get_events(run_id, from_seq=from_seq)
+            current_seq = from_seq
+
+            for event in events:
+                yield event
+                current_seq = event.seq + 1
+
+            # Then listen for new events
+            while True:
+                # Check if run is complete
+                if await self._is_run_complete(run_id):
+                    # Get any final events
+                    final_events = await self.get_events(run_id, from_seq=current_seq)
+                    for event in final_events:
+                        yield event
+                    break
+
+                # Wait for notification with timeout
+                try:
+                    message = await asyncio.wait_for(
+                        pubsub.get_message(ignore_subscribe_messages=True),
+                        timeout=1.0,
+                    )
+                    if message:
+                        # Get new events
+                        new_events = await self.get_events(run_id, from_seq=current_seq)
+                        for event in new_events:
+                            yield event
+                            current_seq = event.seq + 1
+                except asyncio.TimeoutError:
+                    continue
+
+        finally:
+            await pubsub.unsubscribe(channel_key)
+            await pubsub.close()
+
+    @sync_to_async
+    def _is_run_complete(self, run_id: UUID) -> bool:
+        """Check if run is in terminal state."""
+        try:
+            run = AgentRun.objects.get(id=run_id)
+            return run.is_terminal
+        except AgentRun.DoesNotExist:
+            return True
+
+    async def get_events(
+        self,
+        run_id: UUID,
+        from_seq: int = 0,
+        to_seq: Optional[int] = None,
+    ) -> list[Event]:
+        """Get events from Redis stream."""
+        redis = await self._get_redis()
+        stream_key = self._stream_key(run_id)
+
+        # Read from stream
+        messages = await redis.xrange(stream_key)
+
+        events = []
+        for msg_id, data in messages:
+            event_data = json.loads(data[b"data"].decode())
+            event = Event.from_dict(event_data)
+
+            if event.seq < from_seq:
+                continue
+            if to_seq is not None and event.seq > to_seq:
+                continue
+
+            events.append(event)
+
+        return sorted(events, key=lambda e: e.seq)
+
+    async def get_next_seq(self, run_id: UUID) -> int:
+        """Get next sequence number from Redis or database."""
+        redis = await self._get_redis()
+        stream_key = self._stream_key(run_id)
+
+        # Check Redis stream
+        messages = await redis.xrevrange(stream_key, count=1)
+        if messages:
+            msg_id, data = messages[0]
+            event_data = json.loads(data[b"data"].decode())
+            return event_data["seq"] + 1
+
+        # Fall back to database
+        @sync_to_async
+        def _get_from_db():
+            result = AgentEvent.objects.filter(run_id=run_id).aggregate(
+                max_seq=Max("seq")
+            )
+            max_seq = result["max_seq"]
+            # Note: can't use `max_seq or -1` because 0 is falsy!
+            if max_seq is None:
+                return 0
+            return max_seq + 1
+
+        return await _get_from_db()
+
+    async def close(self) -> None:
+        """Close Redis connection."""
+        if self._redis:
+            await self._redis.close()
+            self._redis = None