django-agent-runtime 0.3.5__tar.gz → 0.3.11__tar.gz

{django_agent_runtime-0.3.5/django_agent_runtime.egg-info → django_agent_runtime-0.3.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-agent-runtime
-Version: 0.3.5
+Version: 0.3.11
 Summary: Production-grade AI agent runtime for Django - framework and model agnostic
 Author: Chris Barry
 License-Expression: MIT
@@ -37,8 +37,12 @@ Provides-Extra: litellm
 Requires-Dist: litellm>=1.0.0; extra == "litellm"
 Provides-Extra: langfuse
 Requires-Dist: langfuse>=2.0.0; extra == "langfuse"
+Provides-Extra: framework
+Requires-Dist: agent-runtime-framework>=0.1.0; extra == "framework"
+Provides-Extra: recommended
+Requires-Dist: django-agent-runtime[framework,openai,redis]; extra == "recommended"
 Provides-Extra: all
-Requires-Dist: django-agent-runtime[anthropic,langfuse,litellm,openai,redis]; extra == "all"
+Requires-Dist: django-agent-runtime[anthropic,framework,langfuse,litellm,openai,redis]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: pytest-django>=4.5; extra == "dev"
@@ -62,6 +66,13 @@ A production-ready Django app for AI agent execution. Provides everything you ne
 
 | Version | Date | Changes |
 |---------|------|---------|
+| **0.3.11** | 2025-01-19 | Add Full Stack Setup Guide for AI agents |
+| **0.3.10** | 2025-01-15 | SSE named events for addEventListener support, flexible registry path format |
+| **0.3.9** | 2025-01-14 | Add `[recommended]` and `[framework]` install extras |
+| **0.3.8** | 2025-01-14 | Add agent-frontend docs, agent framework options (OpenAI, Anthropic, LangGraph) |
+| **0.3.7** | 2025-01-13 | Fix auto-reload signal handler in threaded mode |
+| **0.3.6** | 2025-01-13 | Auto-reload for `runagent` in DEBUG mode (like Django's runserver) |
+| **0.3.5** | 2025-01-13 | Added Recent Updates changelog to README |
 | **0.3.4** | 2025-01-13 | Documentation updates for message history |
 | **0.3.3** | 2025-01-13 | Added `conversation.get_message_history()` for retrieving full message sequences |
 | **0.3.2** | 2025-01-13 | Event visibility system - filter events by `internal`/`debug`/`user` levels |
@@ -84,6 +95,13 @@ A production-ready Django app for AI agent execution. Provides everything you ne
 ```bash
 pip install django-agent-runtime
 
+# Recommended: Redis + OpenAI + agent-runtime-framework
+pip install django-agent-runtime[recommended]
+
+# Pick specific extras (comma-separated)
+pip install django-agent-runtime[openai,framework]
+pip install django-agent-runtime[redis,anthropic]
+
 # With LLM providers
 pip install django-agent-runtime[openai]
 pip install django-agent-runtime[anthropic]
@@ -91,6 +109,9 @@ pip install django-agent-runtime[anthropic]
 # With Redis support (recommended for production)
 pip install django-agent-runtime[redis]
 
+# With agent-runtime-framework for journey-based agents
+pip install django-agent-runtime[framework]
+
 # Everything
 pip install django-agent-runtime[all]
 ```
@@ -645,9 +666,55 @@ python manage.py runagent \
     --queue-poll-interval 1.0
 ```
 
+#### Auto-Reload (Development)
+
+In `DEBUG=True` mode, `runagent` automatically reloads when Python files change—just like Django's `runserver`:
+
+```bash
+# Auto-reload enabled by default in DEBUG mode
+python manage.py runagent
+
+# Disable auto-reload
+python manage.py runagent --noreload
+```
+
+**Note:** Auto-reload only works in single-process mode. Multi-process mode (`--processes > 1`) automatically disables auto-reload.
+
 ## Frontend Integration
 
-### JavaScript SSE Client
+### agent-frontend (Recommended)
+
+The easiest way to add a chat UI is with [agent-frontend](https://github.com/makemore/agent-frontend) - a zero-dependency, embeddable chat widget:
+
+```html
+<!-- Include the widget -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/makemore/agent-frontend@main/dist/chat-widget.css">
+<script src="https://cdn.jsdelivr.net/gh/makemore/agent-frontend@main/dist/chat-widget.js"></script>
+
+<!-- Initialize -->
+<script>
+  ChatWidget.init({
+    backendUrl: 'https://your-api.com',
+    agentKey: 'chat-agent',
+    title: 'Support Chat',
+    primaryColor: '#0066cc',
+  });
+</script>
+```
+
+Features:
+- **Zero dependencies** - Pure vanilla JavaScript
+- **SSE streaming** - Real-time token-by-token responses
+- **CSS isolated** - Won't conflict with your existing styles
+- **Dark mode** - Automatic based on system preferences
+- **Session management** - Anonymous sessions out of the box
+- **Demo flows** - Built-in auto-run mode for showcasing agent journeys
+
+See the [agent-frontend documentation](https://github.com/makemore/agent-frontend) for full configuration options.
+
+### Custom JavaScript SSE Client
+
+If you're building your own UI:
 
 ```javascript
 const eventSource = new EventSource('/api/agents/runs/550e8400.../events/');
@@ -675,29 +742,599 @@ eventSource.addEventListener('run.failed', (event) => {
 function useAgentRun(runId: string) {
     const [events, setEvents] = useState<AgentEvent[]>([]);
     const [status, setStatus] = useState<'running' | 'complete' | 'error'>('running');
-    
+
     useEffect(() => {
         const es = new EventSource(`/api/agents/runs/${runId}/events/`);
-        
+
         es.onmessage = (event) => {
             const data = JSON.parse(event.data);
             setEvents(prev => [...prev, data]);
-            
+
             if (data.type === 'run.succeeded') setStatus('complete');
             if (data.type === 'run.failed') setStatus('error');
         };
-        
+
         return () => es.close();
     }, [runId]);
-    
+
     return { events, status };
 }
 ```
 
+## Agent Framework Options
+
+django-agent-runtime is framework-agnostic. You can build agents using:
+
+### Option 1: Direct AgentRuntime (Simple)
+
+Best for simple agents or when you want full control:
+
+```python
+from django_agent_runtime.runtime.interfaces import AgentRuntime, RunContext, RunResult
+
+class MyAgent(AgentRuntime):
+    @property
+    def key(self) -> str:
+        return "my-agent"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        # Your agent logic here
+        ...
+```
+
+### Option 2: agent_runtime_framework (Journey-Based)
+
+Best for multi-step conversational flows with state management:
+
+```bash
+pip install agent_runtime_framework
+```
+
+```python
+from agent_runtime_framework.adapters import DjangoRuntimeAdapter
+from agent_runtime_framework import BaseJourneyState, BaseJourneyTools, ToolSchema
+from enum import Enum
+
+class QuoteStep(str, Enum):
+    WELCOME = "welcome"
+    COLLECT_INFO = "collect_info"
+    GENERATE_QUOTE = "generate_quote"
+    COMPLETE = "complete"
+
+class QuoteState(BaseJourneyState[QuoteStep]):
+    step: QuoteStep = QuoteStep.WELCOME
+    customer_name: str = ""
+    coverage_type: str = ""
+    # ... state fields
+
+class QuoteTools(BaseJourneyTools[QuoteState]):
+    async def save_customer_info(self, name: str, coverage: str) -> str:
+        self.state.customer_name = name
+        self.state.coverage_type = coverage
+        self.state.step = QuoteStep.GENERATE_QUOTE
+        await self._notify_state_change()
+        return f"Got it, {name}! Generating your {coverage} quote..."
+
+class QuoteAgent(DjangoRuntimeAdapter[QuoteState, QuoteTools, QuoteStep]):
+    @property
+    def key(self) -> str:
+        return "quote-agent"
+
+    def get_initial_state(self) -> QuoteState:
+        return QuoteState()
+
+    def get_system_prompt(self, state: QuoteState) -> str:
+        prompts = {
+            QuoteStep.WELCOME: "Welcome the user and ask what coverage they need.",
+            QuoteStep.COLLECT_INFO: "Collect customer name and coverage type.",
+            # ...
+        }
+        return prompts[state.step]
+
+    def get_tool_schemas(self, state: QuoteState) -> list[ToolSchema]:
+        # Return different tools based on current step
+        ...
+
+    def create_tools(self, state, ctx, backend_client) -> QuoteTools:
+        return QuoteTools(state=state)
+
+    async def execute_tool(self, tools, name: str, arguments: dict) -> str:
+        return await getattr(tools, name)(**arguments)
+
+# Register with django-agent-runtime
+from django_agent_runtime.runtime.registry import register_runtime
+register_runtime(QuoteAgent())
+```
+
+The adapter handles:
+- Converting Django's `RunContext` to framework's `AgentContext`
+- State persistence via Django's checkpoint system
+- Event emission through Django's event bus
+- Returning results in Django's `RunResult` format
+
+See [agent_runtime_framework](https://github.com/makemore/agent-runtime-framework) for full documentation.
+
+### Option 3: OpenAI Agents SDK
+
+Use OpenAI's official Agents SDK with django-agent-runtime:
+
+```python
+from django_agent_runtime.runtime.interfaces import AgentRuntime, RunContext, RunResult, EventType
+from agents import Agent, Runner
+
+class OpenAIAgentRuntime(AgentRuntime):
+    @property
+    def key(self) -> str:
+        return "openai-agent"
+
+    def __init__(self):
+        self.agent = Agent(
+            name="Assistant",
+            instructions="You are a helpful assistant.",
+            model="gpt-4o",
+        )
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        # Convert messages to OpenAI format
+        user_message = ctx.input_messages[-1]["content"]
+
+        # Run the OpenAI agent
+        result = await Runner.run(self.agent, user_message)
+
+        # Emit the response
+        await ctx.emit(EventType.ASSISTANT_MESSAGE, {
+            "content": result.final_output,
+        })
+
+        return RunResult(
+            final_output={"response": result.final_output},
+            final_messages=[{"role": "assistant", "content": result.final_output}],
+        )
+```
+
+### Option 4: Anthropic Claude with Tool Use
+
+Use Anthropic's Claude directly:
+
+```python
+from django_agent_runtime.runtime.interfaces import AgentRuntime, RunContext, RunResult, EventType
+import anthropic
+
+class ClaudeAgent(AgentRuntime):
+    @property
+    def key(self) -> str:
+        return "claude-agent"
+
+    def __init__(self):
+        self.client = anthropic.AsyncAnthropic()
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        messages = [
+            {"role": m["role"], "content": m["content"]}
+            for m in ctx.input_messages
+        ]
+
+        response = await self.client.messages.create(
+            model="claude-sonnet-4-20250514",
+            max_tokens=1024,
+            messages=messages,
+        )
+
+        content = response.content[0].text
+
+        await ctx.emit(EventType.ASSISTANT_MESSAGE, {"content": content})
+
+        return RunResult(
+            final_output={"response": content},
+            final_messages=[{"role": "assistant", "content": content}],
+        )
+```
+
+### Option 5: LangGraph
+
+Wrap LangGraph agents:
+
+```python
+from django_agent_runtime.runtime.interfaces import AgentRuntime, RunContext, RunResult, EventType
+from langgraph.graph import StateGraph
+
+class LangGraphRuntime(AgentRuntime):
+    @property
+    def key(self) -> str:
+        return "langgraph-agent"
+
+    def __init__(self):
+        self.graph = self._build_graph()
+
+    def _build_graph(self) -> StateGraph:
+        # Build your LangGraph here
+        ...
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        # Run the graph
+        result = await self.graph.ainvoke({
+            "messages": ctx.input_messages,
+        })
+
+        final_message = result["messages"][-1]
+        await ctx.emit(EventType.ASSISTANT_MESSAGE, {
+            "content": final_message.content,
+        })
+
+        return RunResult(
+            final_output={"response": final_message.content},
+            final_messages=result["messages"],
+        )
+```
+
 ## Related Packages
 
+- [agent-frontend](https://github.com/makemore/agent-frontend) - Zero-dependency embeddable chat widget for AI agents
+- [agent-runtime-framework](https://github.com/makemore/agent-runtime-framework) - Journey-based conversational agents with state management
 - [agent-runtime-core](https://pypi.org/project/agent-runtime-core/) - The framework-agnostic core library (used internally)
 
+---
+
+## Full Stack Setup Guide (For AI Agents)
+
+This guide explains how to set up the complete agent stack from scratch. It's designed to be followed by another AI agent or developer.
+
+### Package Overview
+
+| Package | Purpose | Install |
+|---------|---------|---------|
+| **django-agent-runtime** | Django app for agent execution, API, queues, events | `pip install django-agent-runtime[recommended]` |
+| **agent-runtime-core** | Core abstractions (tools, events, config) | Included with django-agent-runtime |
+| **agent-runtime-framework** | Journey-based agents with state management | Included with `[recommended]` or `[framework]` |
+| **@makemore/agent-frontend** | Embeddable chat widget (vanilla JS) | `npm install @makemore/agent-frontend` |
+
+### Step 1: Create Django Project
+
+```bash
+# Create project directory
+mkdir my_agent_project && cd my_agent_project
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install Django and agent runtime with recommended extras
+pip install django django-agent-runtime[recommended]
+
+# Create Django project
+django-admin startproject config .
+python manage.py startapp agents
+```
+
+### Step 2: Configure Django Settings
+
+```python
+# config/settings.py
+
+INSTALLED_APPS = [
+    'django.contrib.admin',
+    'django.contrib.auth',
+    'django.contrib.contenttypes',
+    'django.contrib.sessions',
+    'django.contrib.messages',
+    'django.contrib.staticfiles',
+    'rest_framework',
+    'django_agent_runtime',
+    'agents',
+]
+
+# Agent Runtime Configuration
+DJANGO_AGENT_RUNTIME = {
+    'QUEUE_BACKEND': 'postgres',
+    'EVENT_BUS_BACKEND': 'db',
+    'MODEL_PROVIDER': 'openai',
+    'DEFAULT_MODEL': 'gpt-4o',
+    'RUNTIME_REGISTRY': [
+        'agents.runtimes:register_agents',
+    ],
+}
+
+# Required for API
+REST_FRAMEWORK = {
+    'DEFAULT_AUTHENTICATION_CLASSES': [
+        'rest_framework.authentication.SessionAuthentication',
+    ],
+    'DEFAULT_PERMISSION_CLASSES': [
+        'rest_framework.permissions.AllowAny',  # For testing; tighten in production
+    ],
+}
+
+# CORS for frontend (install django-cors-headers)
+CORS_ALLOW_ALL_ORIGINS = True  # For development only
+```
+
+### Step 3: Create a Simple Agent
+
+```python
+# agents/runtimes.py
+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 HelloAgent(AgentRuntime):
+    """A simple agent that responds to messages."""
+
+    @property
+    def key(self) -> str:
+        return "hello-agent"
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        llm = get_llm_client()
+
+        # Add system message
+        messages = [
+            {"role": "system", "content": "You are a friendly assistant. Keep responses brief."},
+            *ctx.input_messages
+        ]
+
+        # Call LLM
+        response = await llm.generate(messages)
+        content = response.message.get("content", "")
+
+        # Emit for real-time streaming
+        await ctx.emit(EventType.ASSISTANT_MESSAGE, {
+            "content": content,
+            "role": "assistant",
+        })
+
+        return RunResult(
+            final_output={"response": content},
+            final_messages=[response.message],
+        )
+
+
+def register_agents():
+    """Called by django-agent-runtime on startup."""
+    register_runtime(HelloAgent())
+```
+
+### Step 4: Set Up API URLs
+
+```python
+# agents/urls.py
+from django.urls import path, include
+from rest_framework.routers import DefaultRouter
+from django_agent_runtime.api.views import (
+    BaseAgentRunViewSet,
+    BaseAgentConversationViewSet,
+    sync_event_stream,
+)
+
+router = DefaultRouter()
+router.register(r'conversations', BaseAgentConversationViewSet, basename='conversation')
+router.register(r'runs', BaseAgentRunViewSet, basename='run')
+
+urlpatterns = [
+    path('', include(router.urls)),
+    path('runs/<str:run_id>/events/', sync_event_stream, name='run-events'),
+]
+```
+
+```python
+# config/urls.py
+from django.contrib import admin
+from django.urls import path, include
+
+urlpatterns = [
+    path('admin/', admin.site.urls),
+    path('api/agents/', include('agents.urls')),
+]
+```
+
+### Step 5: Run Migrations and Start Services
+
+```bash
+# Set your OpenAI API key
+export OPENAI_API_KEY="sk-..."
+
+# Run migrations
+python manage.py migrate
+
+# Start Django server (terminal 1)
+python manage.py runserver
+
+# Start agent workers (terminal 2)
+python manage.py runagent
+```
+
+### Step 6: Test the API
+
+```bash
+# Create a conversation
+curl -X POST http://localhost:8000/api/agents/conversations/ \
+  -H "Content-Type: application/json" \
+  -d '{"agent_key": "hello-agent"}'
+
+# Response: {"id": "conv-uuid-here", ...}
+
+# Create a run (replace CONV_ID)
+curl -X POST http://localhost:8000/api/agents/runs/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "conversation_id": "CONV_ID",
+    "agent_key": "hello-agent",
+    "messages": [{"role": "user", "content": "Hello! What can you do?"}]
+  }'
+
+# Response: {"id": "run-uuid-here", "status": "queued", ...}
+
+# Stream events (replace RUN_ID)
+curl -N http://localhost:8000/api/agents/runs/RUN_ID/events/
+```
+
+### Step 7: Add Frontend to Next.js
+
+In your Next.js project:
+
+```bash
+npm install @makemore/agent-frontend
+```
+
+Create a chat component:
+
+```tsx
+// components/AgentChat.tsx
+'use client';
+
+import { useEffect } from 'react';
+
+export default function AgentChat() {
+  useEffect(() => {
+    // Import and initialize the widget
+    import('@makemore/agent-frontend/dist/chat-widget.js').then(() => {
+      // @ts-ignore
+      window.ChatWidget?.init({
+        backendUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000',
+        agentKey: 'hello-agent',
+        title: 'AI Assistant',
+        subtitle: 'Ask me anything!',
+        primaryColor: '#0066cc',
+        position: 'bottom-right',
+        apiEndpoints: {
+          conversations: '/api/agents/conversations/',
+          runs: '/api/agents/runs/',
+          events: '/api/agents/runs/{runId}/events/',
+        },
+      });
+    });
+
+    return () => {
+      // @ts-ignore
+      window.ChatWidget?.destroy?.();
+    };
+  }, []);
+
+  return null; // Widget renders itself
+}
+```
+
+Or use CDN in your layout:
+
+```tsx
+// app/layout.tsx
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <head>
+        <link
+          rel="stylesheet"
+          href="https://unpkg.com/@makemore/agent-frontend/dist/chat-widget.css"
+        />
+      </head>
+      <body>
+        {children}
+        <script src="https://unpkg.com/@makemore/agent-frontend/dist/chat-widget.js" />
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `
+              document.addEventListener('DOMContentLoaded', function() {
+                ChatWidget.init({
+                  backendUrl: '${process.env.NEXT_PUBLIC_API_URL || 'http://localhost:8000'}',
+                  agentKey: 'hello-agent',
+                  title: 'AI Assistant',
+                  primaryColor: '#0066cc',
+                });
+              });
+            `,
+          }}
+        />
+      </body>
+    </html>
+  );
+}
+```
+
+### Step 8: Configure CORS (Production)
+
+```bash
+pip install django-cors-headers
+```
+
+```python
+# config/settings.py
+INSTALLED_APPS = [
+    'corsheaders',
+    ...
+]
+
+MIDDLEWARE = [
+    'corsheaders.middleware.CorsMiddleware',
+    ...
+]
+
+CORS_ALLOWED_ORIGINS = [
+    'http://localhost:3000',  # Next.js dev
+    'https://your-frontend.com',
+]
+```
+
+### Complete File Structure
+
+```
+my_agent_project/
+├── config/
+│   ├── __init__.py
+│   ├── settings.py
+│   ├── urls.py
+│   └── wsgi.py
+├── agents/
+│   ├── __init__.py
+│   ├── runtimes.py      # Your agent implementations
+│   └── urls.py          # API routes
+├── manage.py
+└── requirements.txt
+
+# Next.js frontend (separate repo)
+my-frontend/
+├── app/
+│   └── layout.tsx       # Include chat widget here
+├── components/
+│   └── AgentChat.tsx    # Or as a component
+└── package.json
+```
+
+### Environment Variables
+
+**Django (.env):**
+```bash
+OPENAI_API_KEY=sk-...
+DATABASE_URL=postgres://...  # For production
+REDIS_URL=redis://...        # For production
+DEBUG=True
+```
+
+**Next.js (.env.local):**
+```bash
+NEXT_PUBLIC_API_URL=http://localhost:8000
+```
+
+### Quick Reference Commands
+
+```bash
+# Django
+python manage.py runserver          # Start API server
+python manage.py runagent           # Start agent workers
+python manage.py migrate            # Run migrations
+
+# Next.js
+npm run dev                         # Start frontend
+
+# Testing
+curl -X POST http://localhost:8000/api/agents/conversations/ \
+  -H "Content-Type: application/json" \
+  -d '{"agent_key": "hello-agent"}'
+```
+
+---
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.