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

django_agent_runtime/conf.py

@@ -0,0 +1,241 @@
+"""
+Configuration management for django_agent_runtime.
+
+All settings are namespaced under DJANGO_AGENT_RUNTIME in Django settings.
+This module provides defaults and validation.
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from django.conf import settings
+
+
+@dataclass
+class AgentRuntimeSettings:
+    """
+    Settings for the Django Agent Runtime.
+
+    All settings can be overridden via DJANGO_AGENT_RUNTIME dict in Django settings.
+    """
+
+    # Queue configuration
+    QUEUE_BACKEND: str = "postgres"  # "postgres" | "redis_streams"
+    EVENT_BUS_BACKEND: str = "db"  # "redis" | "db"
+    REDIS_URL: Optional[str] = None
+
+    # Lease and timeout configuration
+    LEASE_TTL_SECONDS: int = 30
+    RUN_TIMEOUT_SECONDS: int = 900  # 15 minutes
+    STEP_TIMEOUT_SECONDS: int = 120  # 2 minutes per LLM/tool call
+    HEARTBEAT_INTERVAL_SECONDS: int = 10
+
+    # Retry configuration
+    DEFAULT_MAX_ATTEMPTS: int = 3
+    RETRY_BACKOFF_BASE: float = 2.0
+    RETRY_BACKOFF_MAX: int = 300  # 5 minutes max backoff
+
+    # Concurrency
+    DEFAULT_PROCESSES: int = 1
+    DEFAULT_CONCURRENCY: int = 10  # async tasks per process
+
+    # Streaming
+    ENABLE_SSE: bool = True
+    ENABLE_CHANNELS: bool = False  # Django Channels (optional)
+    SSE_KEEPALIVE_SECONDS: int = 15
+
+    # Event persistence
+    PERSIST_TOKEN_DELTAS: bool = False  # Token deltas go to Redis only by default
+    EVENT_TTL_SECONDS: int = 3600 * 6  # 6 hours in Redis
+
+    # LLM configuration
+    MODEL_PROVIDER: str = "openai"  # "openai" | "anthropic" | "litellm" | ...
+    LITELLM_ENABLED: bool = False
+    DEFAULT_MODEL: str = "gpt-4o"
+    
+    # API Keys - can be set here or via environment variables
+    # Priority: 1) Explicit setting here, 2) Environment variable
+    OPENAI_API_KEY: Optional[str] = None
+    ANTHROPIC_API_KEY: Optional[str] = None
+
+    # Tracing/observability
+    LANGFUSE_ENABLED: bool = False
+    LANGFUSE_PUBLIC_KEY: Optional[str] = None
+    LANGFUSE_SECRET_KEY: Optional[str] = None
+    LANGFUSE_HOST: Optional[str] = None
+
+    # Plugin discovery
+    RUNTIME_REGISTRY: list = field(default_factory=list)  # Dotted paths to register functions
+
+    # Authorization hooks (dotted paths to callables)
+    AUTHZ_HOOK: Optional[str] = None  # (user, action, run) -> bool
+    QUOTA_HOOK: Optional[str] = None  # (user, agent_key) -> bool
+
+    # Completion callback hook (dotted path to callable)
+    # Called when a run completes successfully: (run_id: str, output: dict) -> None
+    RUN_COMPLETED_HOOK: Optional[str] = None
+
+    # Model customization (for swappable models pattern)
+    RUN_MODEL: Optional[str] = None  # e.g., "myapp.MyAgentRun"
+    CONVERSATION_MODEL: Optional[str] = None
+
+    # Anonymous session model (optional)
+    # Set to your model path, e.g., "accounts.AnonymousSession"
+    # Model must have: token field, is_expired property
+    ANONYMOUS_SESSION_MODEL: Optional[str] = None
+
+    # Event visibility configuration
+    # Controls which events are shown to users in the UI
+    # Levels: "internal" (never shown), "debug" (shown in debug mode), "user" (always shown)
+    EVENT_VISIBILITY: dict = field(default_factory=lambda: {
+        # Lifecycle events
+        "run.started": "internal",
+        "run.heartbeat": "internal",
+        "run.succeeded": "internal",
+        "run.failed": "user",  # Always show errors
+        "run.cancelled": "user",
+        "run.timed_out": "user",
+        # Message events
+        "assistant.delta": "user",  # Token streaming
+        "assistant.message": "user",  # Complete messages
+        # Tool events
+        "tool.call": "debug",
+        "tool.result": "debug",
+        # State events
+        "state.checkpoint": "internal",
+        # Error events
+        "error": "user",  # Runtime errors always shown
+    })
+
+    # When True, 'debug' visibility events become visible to UI
+    DEBUG_MODE: bool = False
+
+    def __post_init__(self):
+        """Validate settings after initialization."""
+        valid_queue_backends = {"postgres", "redis_streams"}
+        if self.QUEUE_BACKEND not in valid_queue_backends:
+            raise ValueError(
+                f"QUEUE_BACKEND must be one of {valid_queue_backends}, got {self.QUEUE_BACKEND}"
+            )
+
+        valid_event_backends = {"redis", "db"}
+        if self.EVENT_BUS_BACKEND not in valid_event_backends:
+            raise ValueError(
+                f"EVENT_BUS_BACKEND must be one of {valid_event_backends}, got {self.EVENT_BUS_BACKEND}"
+            )
+
+        if self.QUEUE_BACKEND == "redis_streams" and not self.REDIS_URL:
+            raise ValueError("REDIS_URL is required when using redis_streams queue backend")
+
+        if self.EVENT_BUS_BACKEND == "redis" and not self.REDIS_URL:
+            raise ValueError("REDIS_URL is required when using redis event bus backend")
+    
+    def get_openai_api_key(self) -> Optional[str]:
+        """
+        Get OpenAI API key with fallback to environment variable.
+        
+        Priority:
+        1. OPENAI_API_KEY in DJANGO_AGENT_RUNTIME settings
+        2. OPENAI_API_KEY environment variable
+        
+        Returns:
+            API key string or None if not configured.
+        """
+        if self.OPENAI_API_KEY:
+            return self.OPENAI_API_KEY
+        return os.environ.get("OPENAI_API_KEY")
+    
+    def get_anthropic_api_key(self) -> Optional[str]:
+        """
+        Get Anthropic API key with fallback to environment variable.
+        
+        Priority:
+        1. ANTHROPIC_API_KEY in DJANGO_AGENT_RUNTIME settings
+        2. ANTHROPIC_API_KEY environment variable
+        
+        Returns:
+            API key string or None if not configured.
+        """
+        if self.ANTHROPIC_API_KEY:
+            return self.ANTHROPIC_API_KEY
+        return os.environ.get("ANTHROPIC_API_KEY")
+
+
+def get_settings() -> AgentRuntimeSettings:
+    """
+    Get the agent runtime settings, merging defaults with user overrides.
+
+    Returns:
+        AgentRuntimeSettings instance with all configuration.
+    """
+    user_settings = getattr(settings, "DJANGO_AGENT_RUNTIME", {})
+
+    # Build settings from defaults + overrides
+    return AgentRuntimeSettings(**user_settings)
+
+
+def get_hook(hook_path: Optional[str]) -> Optional[Callable]:
+    """
+    Import and return a hook function from a dotted path.
+
+    Args:
+        hook_path: Dotted path like "myapp.hooks.check_auth"
+
+    Returns:
+        The callable, or None if hook_path is None.
+    """
+    if not hook_path:
+        return None
+
+    from django.utils.module_loading import import_string
+
+    return import_string(hook_path)
+
+
+# Singleton instance (lazy-loaded)
+_settings_instance: Optional[AgentRuntimeSettings] = None
+
+
+def runtime_settings() -> AgentRuntimeSettings:
+    """Get the cached settings instance."""
+    global _settings_instance
+    if _settings_instance is None:
+        _settings_instance = get_settings()
+    return _settings_instance
+
+
+def reset_settings():
+    """Reset cached settings (useful for testing)."""
+    global _settings_instance
+    _settings_instance = None
+
+
+def get_event_visibility(event_type: str) -> tuple[str, bool]:
+    """
+    Get the visibility level and ui_visible flag for an event type.
+
+    Args:
+        event_type: The event type string (e.g., "run.started", "assistant.message")
+
+    Returns:
+        Tuple of (visibility_level, ui_visible)
+        - visibility_level: "internal", "debug", or "user"
+        - ui_visible: True if the event should be shown in UI
+    """
+    settings = runtime_settings()
+    visibility_map = settings.EVENT_VISIBILITY
+    debug_mode = settings.DEBUG_MODE
+
+    # Get visibility level from config, default to "user" for unknown events
+    visibility_level = visibility_map.get(event_type, "user")
+
+    # Determine if visible in UI
+    if visibility_level == "internal":
+        ui_visible = False
+    elif visibility_level == "debug":
+        ui_visible = debug_mode
+    else:  # "user"
+        ui_visible = True
+
+    return visibility_level, ui_visible

django_agent_runtime/examples/__init__.py

@@ -0,0 +1,10 @@
+"""
+Example agent runtimes demonstrating how to use django_agent_runtime.
+
+These examples show:
+- How to create a custom AgentRuntime
+- How to register runtimes
+- How to use the LLM client
+- How to emit events and checkpoints
+"""
+

django_agent_runtime/examples/langgraph_adapter.py

@@ -0,0 +1,164 @@
+"""
+LangGraph adapter for django_agent_runtime.
+
+This example shows how to integrate LangGraph agents with the runtime.
+LangGraph provides a powerful graph-based approach to building agents
+with state management, branching, and cycles.
+
+Requirements:
+    pip install langgraph langchain-openai
+
+Usage:
+    1. Add to RUNTIME_REGISTRY in settings:
+       'RUNTIME_REGISTRY': ['django_agent_runtime.examples.langgraph_adapter:register']
+
+    2. Create a run with agent_key="langgraph-agent"
+
+Example LangGraph agent structure:
+    - StateGraph with nodes for different agent steps
+    - Conditional edges for routing
+    - Checkpointing for state persistence
+"""
+
+from typing import Any, TypedDict, Annotated, Sequence
+import operator
+
+from django_agent_runtime.runtime.interfaces import (
+    AgentRuntime,
+    RunContext,
+    RunResult,
+    EventType,
+)
+from django_agent_runtime.runtime.registry import register_runtime
+
+
+class AgentState(TypedDict):
+    """State for the LangGraph agent."""
+    messages: Annotated[Sequence[dict], operator.add]
+    next_step: str
+    iteration: int
+
+
+class LangGraphRuntime(AgentRuntime):
+    """
+    Runtime adapter for LangGraph agents.
+
+    This adapter:
+    - Wraps a LangGraph StateGraph
+    - Emits events for each node execution
+    - Supports checkpointing via RunContext
+    - Handles cancellation between steps
+    """
+
+    MAX_ITERATIONS = 20
+
+    @property
+    def key(self) -> str:
+        return "langgraph-agent"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        """Execute the LangGraph agent."""
+        try:
+            from langgraph.graph import StateGraph, END
+            from langchain_openai import ChatOpenAI
+        except ImportError:
+            raise ImportError(
+                "LangGraph integration requires: pip install langgraph langchain-openai"
+            )
+
+        # Build the graph
+        graph = self._build_graph()
+        app = graph.compile()
+
+        # Initialize state
+        state: AgentState = {
+            "messages": ctx.input_messages,
+            "next_step": "agent",
+            "iteration": 0,
+        }
+
+        # Run the graph
+        total_usage = {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
+
+        async for event in app.astream(state):
+            # Check for cancellation
+            if ctx.cancelled():
+                await ctx.emit(EventType.RUN_CANCELLED, {"reason": "User requested"})
+                return RunResult()
+
+            # Emit step event
+            for node_name, node_output in event.items():
+                await ctx.emit(EventType.STEP_COMPLETED, {
+                    "node": node_name,
+                    "output": node_output,
+                })
+
+                # Checkpoint after each step
+                await ctx.checkpoint({
+                    "node": node_name,
+                    "state": node_output,
+                })
+
+                # Update state
+                if isinstance(node_output, dict):
+                    state.update(node_output)
+
+        # Extract final response
+        final_messages = state.get("messages", [])
+        final_output = {}
+
+        if final_messages:
+            last_message = final_messages[-1]
+            if isinstance(last_message, dict):
+                final_output = {"response": last_message.get("content", "")}
+                await ctx.emit(EventType.ASSISTANT_MESSAGE, last_message)
+
+        return RunResult(
+            final_output=final_output,
+            final_messages=final_messages,
+            usage=total_usage,
+        )
+
+    def _build_graph(self):
+        """Build the LangGraph StateGraph."""
+        from langgraph.graph import StateGraph, END
+        from langchain_openai import ChatOpenAI
+
+        # Create the LLM
+        llm = ChatOpenAI(model="gpt-4o", temperature=0)
+
+        # Define nodes
+        async def agent_node(state: AgentState) -> dict:
+            """Main agent node - calls the LLM."""
+            messages = state["messages"]
+            response = await llm.ainvoke(messages)
+
+            return {
+                "messages": [{"role": "assistant", "content": response.content}],
+                "next_step": "end",
+                "iteration": state["iteration"] + 1,
+            }
+
+        async def should_continue(state: AgentState) -> str:
+            """Determine if we should continue or end."""
+            if state["iteration"] >= self.MAX_ITERATIONS:
+                return "end"
+            return state.get("next_step", "end")
+
+        # Build graph
+        graph = StateGraph(AgentState)
+        graph.add_node("agent", agent_node)
+        graph.set_entry_point("agent")
+        graph.add_conditional_edges(
+            "agent",
+            should_continue,
+            {"end": END, "agent": "agent"},
+        )
+
+        return graph
+
+
+def register():
+    """Register the LangGraph runtime."""
+    register_runtime(LangGraphRuntime())
+

django_agent_runtime/examples/langgraph_tools.py

@@ -0,0 +1,179 @@
+"""
+LangGraph agent with tools example.
+
+This demonstrates a more complete LangGraph agent that:
+- Uses tools for external actions
+- Has a ReAct-style reasoning loop
+- Emits detailed events for UI streaming
+
+Requirements:
+    pip install langgraph langchain-openai langchain-core
+
+Usage:
+    1. Add to RUNTIME_REGISTRY in settings:
+       'RUNTIME_REGISTRY': ['django_agent_runtime.examples.langgraph_tools:register']
+
+    2. Create a run with agent_key="langgraph-tools-agent"
+"""
+
+from typing import Any, TypedDict, Annotated, Sequence, Literal
+import operator
+import json
+
+from django_agent_runtime.runtime.interfaces import (
+    AgentRuntime,
+    RunContext,
+    RunResult,
+    EventType,
+)
+from django_agent_runtime.runtime.registry import register_runtime
+
+
+class ToolsAgentState(TypedDict):
+    """State for the tools agent."""
+    messages: Annotated[Sequence[dict], operator.add]
+    tool_calls: list[dict]
+    iteration: int
+
+
+class LangGraphToolsRuntime(AgentRuntime):
+    """
+    LangGraph agent with tool calling capabilities.
+
+    Implements a ReAct-style loop:
+    1. Agent decides what to do
+    2. If tool call needed, execute tool
+    3. Feed result back to agent
+    4. Repeat until done
+    """
+
+    MAX_ITERATIONS = 10
+
+    @property
+    def key(self) -> str:
+        return "langgraph-tools-agent"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        """Execute the tools agent."""
+        try:
+            from langgraph.graph import StateGraph, END
+            from langchain_openai import ChatOpenAI
+            from langchain_core.messages import HumanMessage, AIMessage, ToolMessage
+        except ImportError:
+            raise ImportError(
+                "LangGraph tools integration requires: "
+                "pip install langgraph langchain-openai langchain-core"
+            )
+
+        # Define tools
+        tools = self._get_tools()
+
+        # Create LLM with tools
+        llm = ChatOpenAI(model="gpt-4o", temperature=0).bind_tools(tools)
+
+        # Build and compile graph
+        graph = self._build_graph(llm, tools, ctx)
+        app = graph.compile()
+
+        # Initialize state
+        state: ToolsAgentState = {
+            "messages": ctx.input_messages,
+            "tool_calls": [],
+            "iteration": 0,
+        }
+
+        # Run the graph
+        final_state = None
+        async for event in app.astream(state):
+            if ctx.cancelled():
+                return RunResult()
+
+            for node_name, node_output in event.items():
+                final_state = node_output
+                await ctx.checkpoint({"node": node_name, "iteration": state["iteration"]})
+
+        # Extract result
+        messages = final_state.get("messages", []) if final_state else []
+        final_content = ""
+        if messages:
+            last = messages[-1]
+            final_content = last.get("content", "") if isinstance(last, dict) else str(last)
+
+        await ctx.emit(EventType.ASSISTANT_MESSAGE, {
+            "role": "assistant",
+            "content": final_content,
+        })
+
+        return RunResult(
+            final_output={"response": final_content},
+            final_messages=messages,
+        )
+
+    def _get_tools(self) -> list:
+        """Define available tools."""
+        from langchain_core.tools import tool
+
+        @tool
+        def search(query: str) -> str:
+            """Search for information."""
+            # Mock search - replace with real implementation
+            return f"Search results for: {query}"
+
+        @tool
+        def calculate(expression: str) -> str:
+            """Evaluate a math expression."""
+            try:
+                result = eval(expression, {"__builtins__": {}}, {})
+                return str(result)
+            except Exception as e:
+                return f"Error: {e}"
+
+        return [search, calculate]
+
+    def _build_graph(self, llm, tools, ctx: RunContext):
+        """Build the ReAct-style graph."""
+        from langgraph.graph import StateGraph, END
+        from langchain_core.messages import ToolMessage
+
+        tool_map = {t.name: t for t in tools}
+
+        async def agent_node(state: ToolsAgentState) -> dict:
+            """Call the LLM."""
+            response = await llm.ainvoke(state["messages"])
+            tool_calls = getattr(response, "tool_calls", [])
+
+            return {
+                "messages": [response],
+                "tool_calls": tool_calls,
+                "iteration": state["iteration"] + 1,
+            }
+
+        async def tool_node(state: ToolsAgentState) -> dict:
+            """Execute tool calls."""
+            results = []
+            for tc in state["tool_calls"]:
+                tool = tool_map.get(tc["name"])
+                if tool:
+                    result = await tool.ainvoke(tc["args"])
+                    results.append(ToolMessage(content=str(result), tool_call_id=tc["id"]))
+            return {"messages": results, "tool_calls": []}
+
+        def should_continue(state: ToolsAgentState) -> Literal["tools", "end"]:
+            if state["iteration"] >= self.MAX_ITERATIONS:
+                return "end"
+            return "tools" if state["tool_calls"] else "end"
+
+        graph = StateGraph(ToolsAgentState)
+        graph.add_node("agent", agent_node)
+        graph.add_node("tools", tool_node)
+        graph.set_entry_point("agent")
+        graph.add_conditional_edges("agent", should_continue, {"tools": "tools", "end": END})
+        graph.add_edge("tools", "agent")
+
+        return graph
+
+
+def register():
+    """Register the LangGraph tools runtime."""
+    register_runtime(LangGraphToolsRuntime())
+

django_agent_runtime/examples/simple_chat.py

@@ -0,0 +1,69 @@
+"""
+Simple chat agent example.
+
+This demonstrates a basic agent that:
+- Takes user messages
+- Calls an LLM
+- Returns the response
+
+Usage:
+    1. Add to RUNTIME_REGISTRY in settings:
+       'RUNTIME_REGISTRY': ['django_agent_runtime.examples.simple_chat:register']
+
+    2. Create a run with agent_key="simple-chat"
+"""
+
+from django_agent_runtime.runtime.interfaces import (
+    AgentRuntime,
+    RunContext,
+    RunResult,
+    EventType,
+)
+from django_agent_runtime.runtime.registry import register_runtime
+from django_agent_runtime.runtime.llm import get_llm_client
+
+
+class SimpleChatRuntime(AgentRuntime):
+    """
+    A simple chat agent that forwards messages to an LLM.
+
+    This is the most basic agent - no tools, no state, just chat.
+    """
+
+    @property
+    def key(self) -> str:
+        return "simple-chat"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        """Execute the chat agent."""
+        # Get LLM client
+        llm = get_llm_client()
+
+        # Check for cancellation
+        if ctx.cancelled():
+            return RunResult()
+
+        # Call LLM
+        response = await llm.generate(
+            messages=ctx.input_messages,
+            **ctx.params,
+        )
+
+        # Emit the assistant message
+        await ctx.emit(EventType.ASSISTANT_MESSAGE, {
+            "content": response.message.get("content", ""),
+            "role": "assistant",
+        })
+
+        # Return result
+        return RunResult(
+            final_output={"response": response.message.get("content", "")},
+            final_messages=[response.message],
+            usage=response.usage,
+        )
+
+
+def register():
+    """Register the simple chat runtime."""
+    register_runtime(SimpleChatRuntime())
+