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

django_agent_runtime/__init__.py

@@ -0,0 +1,25 @@
+"""
+Django Agent Runtime - Production-grade AI agent execution for Django.
+
+Framework-agnostic • Model-agnostic • Production-grade concurrency
+
+This package provides:
+- AgentRun model for tracking agent executions
+- Queue adapters (Postgres, Redis Streams) for job distribution
+- Event bus for real-time streaming to UI
+- Plugin system for custom agent runtimes
+- LLM client abstraction (provider-agnostic)
+- Persistence layer (memory, conversations, tasks, preferences)
+- Optional integrations (LiteLLM, Langfuse)
+
+Usage:
+    1. Add 'django_agent_runtime' to INSTALLED_APPS
+    2. Configure DJANGO_AGENT_RUNTIME settings
+    3. Run migrations
+    4. Start workers: ./manage.py runagent
+"""
+
+__version__ = "0.3.0"
+
+default_app_config = "django_agent_runtime.apps.DjangoAgentRuntimeConfig"
+

django_agent_runtime/admin.py

@@ -0,0 +1,155 @@
+"""
+Django admin configuration for agent runtime models.
+"""
+
+from django.contrib import admin
+from django.utils.html import format_html
+
+from django_agent_runtime.models import (
+    AgentConversation,
+    AgentRun,
+    AgentEvent,
+    AgentCheckpoint,
+)
+
+
+@admin.register(AgentConversation)
+class AgentConversationAdmin(admin.ModelAdmin):
+    """Admin for AgentConversation."""
+
+    list_display = ["id", "agent_key", "user", "title", "created_at"]
+    list_filter = ["agent_key", "created_at"]
+    search_fields = ["id", "title", "user__email"]
+    readonly_fields = ["id", "created_at", "updated_at"]
+    raw_id_fields = ["user"]
+
+
+class AgentEventInline(admin.TabularInline):
+    """Inline for viewing events on a run."""
+
+    model = AgentEvent
+    extra = 0
+    readonly_fields = ["seq", "event_type", "payload", "timestamp"]
+    can_delete = False
+
+    def has_add_permission(self, request, obj=None):
+        return False
+
+
+class AgentCheckpointInline(admin.TabularInline):
+    """Inline for viewing checkpoints on a run."""
+
+    model = AgentCheckpoint
+    extra = 0
+    readonly_fields = ["seq", "state", "created_at"]
+    can_delete = False
+
+    def has_add_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(AgentRun)
+class AgentRunAdmin(admin.ModelAdmin):
+    """Admin for AgentRun."""
+
+    list_display = [
+        "id",
+        "agent_key",
+        "status_badge",
+        "attempt",
+        "conversation",
+        "created_at",
+        "duration",
+    ]
+    list_filter = ["status", "agent_key", "created_at"]
+    search_fields = ["id", "agent_key", "idempotency_key"]
+    readonly_fields = [
+        "id",
+        "status",
+        "attempt",
+        "lease_owner",
+        "lease_expires_at",
+        "created_at",
+        "started_at",
+        "finished_at",
+        "cancel_requested_at",
+    ]
+    raw_id_fields = ["conversation"]
+    inlines = [AgentEventInline, AgentCheckpointInline]
+
+    fieldsets = (
+        (None, {
+            "fields": ("id", "agent_key", "conversation", "status")
+        }),
+        ("Input/Output", {
+            "fields": ("input", "output", "error"),
+            "classes": ("collapse",),
+        }),
+        ("Execution", {
+            "fields": (
+                "attempt",
+                "max_attempts",
+                "lease_owner",
+                "lease_expires_at",
+                "cancel_requested_at",
+            ),
+        }),
+        ("Timestamps", {
+            "fields": ("created_at", "started_at", "finished_at"),
+        }),
+        ("Metadata", {
+            "fields": ("idempotency_key", "metadata"),
+            "classes": ("collapse",),
+        }),
+    )
+
+    def status_badge(self, obj):
+        """Display status as a colored badge."""
+        colors = {
+            "queued": "#6c757d",
+            "running": "#007bff",
+            "succeeded": "#28a745",
+            "failed": "#dc3545",
+            "cancelled": "#ffc107",
+            "timed_out": "#fd7e14",
+        }
+        color = colors.get(obj.status, "#6c757d")
+        return format_html(
+            '<span style="background-color: {}; color: white; padding: 2px 8px; '
+            'border-radius: 4px; font-size: 11px;">{}</span>',
+            color,
+            obj.status.upper(),
+        )
+    status_badge.short_description = "Status"
+
+    def duration(self, obj):
+        """Calculate run duration."""
+        if obj.started_at and obj.finished_at:
+            delta = obj.finished_at - obj.started_at
+            return f"{delta.total_seconds():.1f}s"
+        elif obj.started_at:
+            return "Running..."
+        return "-"
+    duration.short_description = "Duration"
+
+
+@admin.register(AgentEvent)
+class AgentEventAdmin(admin.ModelAdmin):
+    """Admin for AgentEvent."""
+
+    list_display = ["id", "run", "seq", "event_type", "timestamp"]
+    list_filter = ["event_type", "timestamp"]
+    search_fields = ["run__id", "event_type"]
+    readonly_fields = ["id", "run", "seq", "event_type", "payload", "timestamp"]
+    raw_id_fields = ["run"]
+
+
+@admin.register(AgentCheckpoint)
+class AgentCheckpointAdmin(admin.ModelAdmin):
+    """Admin for AgentCheckpoint."""
+
+    list_display = ["id", "run", "seq", "created_at"]
+    search_fields = ["run__id"]
+    readonly_fields = ["id", "run", "seq", "state", "created_at"]
+    raw_id_fields = ["run"]
+

django_agent_runtime/api/__init__.py

@@ -0,0 +1,26 @@
+"""
+API module for django_agent_runtime.
+
+Provides base ViewSets for agent runtime API. Inherit from these
+in your project and set your own permission_classes.
+
+Example:
+    from django_agent_runtime.api.views import BaseAgentRunViewSet
+    
+    class AgentRunViewSet(BaseAgentRunViewSet):
+        permission_classes = [IsAuthenticated]
+"""
+
+from django_agent_runtime.api.views import (
+    BaseAgentRunViewSet,
+    BaseAgentConversationViewSet,
+    sync_event_stream,
+    async_event_stream,
+)
+
+__all__ = [
+    "BaseAgentRunViewSet",
+    "BaseAgentConversationViewSet",
+    "sync_event_stream",
+    "async_event_stream",
+]

django_agent_runtime/api/permissions.py

@@ -0,0 +1,109 @@
+"""
+Custom permissions and authentication for agent runtime API.
+
+Supports both authenticated users and anonymous sessions via X-Anonymous-Token header.
+"""
+
+from rest_framework import permissions
+from rest_framework.authentication import BaseAuthentication
+
+from django_agent_runtime.conf import runtime_settings
+
+
+def _get_anonymous_session_model():
+    """
+    Get the anonymous session model if configured.
+
+    Returns None if anonymous sessions are not configured.
+    """
+    settings = runtime_settings()
+    model_path = settings.ANONYMOUS_SESSION_MODEL
+
+    if not model_path:
+        return None
+
+    try:
+        from django.apps import apps
+        app_label, model_name = model_path.rsplit('.', 1)
+        return apps.get_model(app_label, model_name)
+    except Exception:
+        return None
+
+
+class AnonymousSessionAuthentication(BaseAuthentication):
+    """
+    DRF Authentication class that authenticates via X-Anonymous-Token header.
+
+    This allows anonymous users to access the agent runtime API by providing
+    a valid anonymous session token.
+
+    To enable, set AGENT_RUNTIME["ANONYMOUS_SESSION_MODEL"] to your session model path,
+    e.g., "accounts.AnonymousSession". The model must have:
+    - A `token` field
+    - An `is_expired` property
+    """
+
+    def authenticate(self, request):
+        """
+        Authenticate the request using X-Anonymous-Token header.
+
+        Returns a tuple of (user, auth) where user is None for anonymous sessions
+        and auth is the AnonymousSession object.
+        """
+        token = request.headers.get('X-Anonymous-Token')
+        if not token:
+            token = request.query_params.get('anonymous_token')
+
+        if not token:
+            return None
+
+        AnonymousSession = _get_anonymous_session_model()
+        if not AnonymousSession:
+            return None
+
+        try:
+            session = AnonymousSession.objects.get(token=token)
+            if hasattr(session, 'is_expired') and session.is_expired:
+                return None
+
+            # Store the session on the request for later use
+            request.anonymous_session = session
+
+            # Return (None, session) - None user means anonymous
+            # The session is the "auth" object
+            return (None, session)
+        except Exception:
+            return None
+
+    def authenticate_header(self, request):
+        """Return a string to be used as the value of the WWW-Authenticate header."""
+        return 'X-Anonymous-Token'
+
+
+class IsAuthenticatedOrAnonymousSession(permissions.BasePermission):
+    """
+    Permission class that allows access if:
+    1. User is authenticated (via Token auth), OR
+    2. Request has a valid X-Anonymous-Token header
+    """
+    
+    def has_permission(self, request, view):
+        # Check if user is authenticated
+        if request.user and request.user.is_authenticated:
+            return True
+        
+        # Check if we have an anonymous session (set by AnonymousSessionAuthentication)
+        if hasattr(request, 'anonymous_session') and request.anonymous_session:
+            return True
+        
+        return False
+
+
+def get_anonymous_session(request):
+    """
+    Helper function to get the anonymous session from a request.
+    
+    Returns the AnonymousSession object if present, None otherwise.
+    """
+    return getattr(request, 'anonymous_session', None)
+

django_agent_runtime/api/serializers.py

@@ -0,0 +1,114 @@
+"""
+DRF serializers for agent runtime API.
+"""
+
+from rest_framework import serializers
+
+from django_agent_runtime.models import AgentRun, AgentConversation, AgentEvent
+
+
+class AgentConversationSerializer(serializers.ModelSerializer):
+    """Serializer for AgentConversation."""
+
+    class Meta:
+        model = AgentConversation
+        fields = [
+            "id",
+            "agent_key",
+            "title",
+            "metadata",
+            "created_at",
+            "updated_at",
+        ]
+        read_only_fields = ["id", "created_at", "updated_at"]
+
+
+class AgentRunSerializer(serializers.ModelSerializer):
+    """Serializer for AgentRun."""
+
+    class Meta:
+        model = AgentRun
+        fields = [
+            "id",
+            "conversation_id",
+            "agent_key",
+            "status",
+            "input",
+            "output",
+            "error",
+            "attempt",
+            "max_attempts",
+            "idempotency_key",
+            "created_at",
+            "started_at",
+            "finished_at",
+            "metadata",
+        ]
+        read_only_fields = [
+            "id",
+            "status",
+            "output",
+            "error",
+            "attempt",
+            "created_at",
+            "started_at",
+            "finished_at",
+        ]
+
+
+class AgentRunCreateSerializer(serializers.Serializer):
+    """Serializer for creating a new agent run."""
+
+    agent_key = serializers.CharField(max_length=100)
+    conversation_id = serializers.UUIDField(required=False, allow_null=True)
+    messages = serializers.ListField(
+        child=serializers.DictField(),
+        required=True,
+        help_text="List of messages in the conversation",
+    )
+    params = serializers.DictField(
+        required=False,
+        default=dict,
+        help_text="Additional parameters for the agent",
+    )
+    max_attempts = serializers.IntegerField(
+        required=False,
+        default=3,
+        min_value=1,
+        max_value=10,
+    )
+    idempotency_key = serializers.CharField(
+        required=False,
+        allow_null=True,
+        max_length=255,
+    )
+    metadata = serializers.DictField(
+        required=False,
+        default=dict,
+    )
+
+
+class AgentEventSerializer(serializers.ModelSerializer):
+    """Serializer for AgentEvent."""
+
+    class Meta:
+        model = AgentEvent
+        fields = [
+            "id",
+            "run_id",
+            "seq",
+            "event_type",
+            "payload",
+            "timestamp",
+        ]
+        read_only_fields = fields
+
+
+class AgentRunDetailSerializer(AgentRunSerializer):
+    """Detailed serializer for AgentRun with events."""
+
+    events = AgentEventSerializer(many=True, read_only=True)
+
+    class Meta(AgentRunSerializer.Meta):
+        fields = AgentRunSerializer.Meta.fields + ["events"]
+