django-agent-studio 0.1.0__py3-none-any.whl → 0.1.4__py3-none-any.whl

django_agent_studio/agents/dynamic.py

@@ -0,0 +1,376 @@
+"""
+DynamicAgentRuntime - An agent that loads its configuration from the database.
+
+This allows agents to be defined and modified via the AgentDefinition model
+without requiring code changes.
+
+Supports:
+- RAG (Retrieval Augmented Generation) for knowledge sources with inclusion_mode='rag'
+- Conversation-scoped memory via the 'remember' tool
+"""
+
+import json
+import logging
+from typing import Any, Optional
+from uuid import UUID
+
+from agent_runtime_core.registry import AgentRuntime
+from agent_runtime_core.interfaces import RunContext, RunResult, EventType
+from agent_runtime_core.agentic_loop import run_agentic_loop
+from django_agent_runtime.runtime.llm import get_llm_client_for_model, DEFAULT_MODEL
+from django_agent_runtime.models import AgentDefinition
+from django_agent_runtime.dynamic_tools.executor import DynamicToolExecutor
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Memory Tool Definition
+# =============================================================================
+
+MEMORY_TOOL_SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "remember",
+        "description": (
+            "Store information to remember for this conversation. Use this to remember "
+            "important facts about the user, their preferences, project details, or anything "
+            "that would be useful to recall in future messages within this conversation. "
+            "Examples: user's name, their goals, preferences, important context."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "key": {
+                    "type": "string",
+                    "description": (
+                        "A short, descriptive key for what you're remembering "
+                        "(e.g., 'user_name', 'project_goal', 'preferred_language')"
+                    ),
+                },
+                "value": {
+                    "type": "string",
+                    "description": "The information to remember",
+                },
+            },
+            "required": ["key", "value"],
+        },
+    },
+}
+
+
+class DynamicAgentRuntime(AgentRuntime):
+    """
+    An agent runtime that loads its configuration from an AgentDefinition.
+    
+    This allows agents to be created and modified via the database/API
+    without requiring code changes or deployments.
+    """
+    
+    def __init__(self, agent_definition: AgentDefinition):
+        self._definition = agent_definition
+        self._config: Optional[dict] = None
+    
+    @property
+    def key(self) -> str:
+        """Return the agent's slug as its key."""
+        return self._definition.slug
+    
+    @property
+    def config(self) -> dict:
+        """Get the effective configuration (cached)."""
+        if self._config is None:
+            self._config = self._definition.get_effective_config()
+        return self._config
+    
+    def refresh_config(self):
+        """Refresh the configuration from the database."""
+        self._definition.refresh_from_db()
+        self._config = None
+    
+    async def run(self, ctx: RunContext) -> RunResult:
+        """Execute the agent with the dynamic configuration and agentic loop."""
+        config = self.config
+
+        # Build the messages list
+        messages = []
+
+        # Add system prompt
+        system_prompt = config.get("system_prompt", "")
+
+        # Add knowledge that should always be included
+        knowledge_context = self._build_knowledge_context(config)
+        if knowledge_context:
+            system_prompt = f"{system_prompt}\n\n{knowledge_context}"
+
+        # Add RAG-retrieved knowledge based on user's query
+        rag_context = await self._retrieve_rag_knowledge(config, ctx)
+        if rag_context:
+            system_prompt = f"{system_prompt}\n\n{rag_context}"
+
+        # Add conversation memories (if we have a conversation_id and user)
+        memory_store = await self._get_memory_store(ctx)
+        if memory_store:
+            memory_context = await self._recall_memories(memory_store)
+            if memory_context:
+                system_prompt = f"{system_prompt}\n\n{memory_context}"
+
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+
+        # Add conversation history
+        messages.extend(ctx.input_messages)
+
+        # Build tool schemas - include memory tool
+        tools = self._build_tool_schemas(config)
+        tools.append(MEMORY_TOOL_SCHEMA)  # Add remember tool to all designed agents
+
+        tool_map = self._build_tool_map(config)  # Maps tool name to execution info
+
+        # Get model: params override > agent config > default
+        model = ctx.params.get("model") or config.get("model") or DEFAULT_MODEL
+        model_settings = config.get("model_settings", {})
+
+        # Get LLM client for the model (auto-detects provider)
+        llm = get_llm_client_for_model(model)
+
+        # Initialize tool executor for dynamic tools
+        tool_executor = DynamicToolExecutor()
+
+        # Create tool executor function for the agentic loop
+        async def execute_tool(tool_name: str, tool_args: dict) -> str:
+            # Handle the built-in remember tool
+            if tool_name == "remember":
+                return await self._execute_remember_tool(tool_args, memory_store)
+
+            return await self._execute_tool(
+                tool_name, tool_args, tool_map, tool_executor, ctx
+            )
+
+        try:
+            # Use the shared agentic loop
+            result = await run_agentic_loop(
+                llm=llm,
+                messages=messages,
+                tools=tools if tools else None,
+                execute_tool=execute_tool,
+                ctx=ctx,
+                model=model,
+                max_iterations=15,
+                **model_settings,
+            )
+
+            # Emit the final assistant message
+            if result.final_content:
+                await ctx.emit(EventType.ASSISTANT_MESSAGE, {"content": result.final_content})
+
+            return RunResult(
+                final_output={"response": result.final_content},
+                final_messages=result.messages,
+            )
+
+        except Exception as e:
+            logger.exception(f"Error in DynamicAgentRuntime for {self.key}")
+            await ctx.emit(EventType.RUN_FAILED, {"error": str(e)})
+            raise
+
+    async def _get_memory_store(self, ctx: RunContext) -> Optional["ConversationMemoryStore"]:
+        """
+        Get the memory store for this conversation, if available.
+
+        Returns None if we don't have the required context (user, conversation_id).
+        """
+        from django_agent_runtime.persistence.stores import ConversationMemoryStore
+
+        # Need both user and conversation_id for memory
+        user_id = ctx.metadata.get("user_id")
+        conversation_id = ctx.conversation_id
+
+        if not user_id or not conversation_id:
+            logger.debug(
+                f"Memory not available: user_id={user_id}, conversation_id={conversation_id}"
+            )
+            return None
+
+        try:
+            # Get the user object
+            from django.contrib.auth import get_user_model
+            from asgiref.sync import sync_to_async
+
+            User = get_user_model()
+            user = await sync_to_async(User.objects.get)(id=user_id)
+
+            return ConversationMemoryStore(user=user, conversation_id=conversation_id)
+        except Exception as e:
+            logger.warning(f"Failed to create memory store: {e}")
+            return None
+
+    async def _recall_memories(self, memory_store: "ConversationMemoryStore") -> str:
+        """
+        Recall all memories for this conversation and format for the prompt.
+        """
+        try:
+            memories = await memory_store.recall_all()
+            if memories:
+                logger.info(f"Recalled {len(memories)} memories for conversation")
+                return memory_store.format_for_prompt(memories)
+        except Exception as e:
+            logger.warning(f"Failed to recall memories: {e}")
+        return ""
+
+    async def _execute_remember_tool(
+        self,
+        args: dict,
+        memory_store: Optional["ConversationMemoryStore"],
+    ) -> str:
+        """Execute the remember tool to store a memory."""
+        if not memory_store:
+            return json.dumps({
+                "error": "Memory not available for this conversation",
+                "hint": "Memory requires a logged-in user and conversation context",
+            })
+
+        key = args.get("key", "").strip()
+        value = args.get("value", "").strip()
+
+        if not key:
+            return json.dumps({"error": "Missing required parameter: key"})
+        if not value:
+            return json.dumps({"error": "Missing required parameter: value"})
+
+        try:
+            await memory_store.remember(key, value, source="agent")
+            logger.info(f"Stored memory: {key}")
+            return json.dumps({
+                "success": True,
+                "message": f"Remembered: {key}",
+            })
+        except Exception as e:
+            logger.exception(f"Failed to store memory: {key}")
+            return json.dumps({"error": str(e)})
+    
+    def _build_knowledge_context(self, config: dict) -> str:
+        """Build context string from always-included knowledge sources."""
+        parts = []
+        for knowledge in config.get("knowledge", []):
+            if knowledge.get("inclusion_mode") == "always":
+                content = knowledge.get("content")
+                if content:
+                    name = knowledge.get("name", "Knowledge")
+                    parts.append(f"## {name}\n{content}")
+        return "\n\n".join(parts)
+
+    async def _retrieve_rag_knowledge(self, config: dict, ctx: RunContext) -> str:
+        """
+        Retrieve relevant knowledge using RAG for knowledge sources with inclusion_mode='rag'.
+
+        Args:
+            config: The agent's effective configuration
+            ctx: The run context containing user messages
+
+        Returns:
+            Formatted string of retrieved knowledge, or empty string if no RAG knowledge
+        """
+        # Check if there are any RAG knowledge sources
+        rag_knowledge = [
+            k for k in config.get("knowledge", [])
+            if k.get("inclusion_mode") == "rag" and k.get("rag", {}).get("status") == "indexed"
+        ]
+
+        if not rag_knowledge:
+            return ""
+
+        # Get the user's query from the last user message
+        user_query = ""
+        for msg in reversed(ctx.input_messages):
+            if msg.get("role") == "user":
+                user_query = msg.get("content", "")
+                break
+
+        if not user_query:
+            return ""
+
+        try:
+            from django_agent_runtime.rag import KnowledgeRetriever
+
+            retriever = KnowledgeRetriever()
+            rag_config = config.get("rag_config", {})
+
+            # Retrieve relevant knowledge
+            context = await retriever.retrieve_for_agent(
+                agent_id=str(self._definition.id),
+                query=user_query,
+                rag_config=rag_config,
+            )
+
+            return context
+
+        except Exception as e:
+            logger.warning(f"Error retrieving RAG knowledge: {e}")
+            return ""
+    
+    def _build_tool_schemas(self, config: dict) -> list:
+        """Build OpenAI-format tool schemas from config."""
+        schemas = []
+        for tool in config.get("tools", []):
+            # Skip the _meta field when building schema
+            schema = {
+                "type": tool.get("type", "function"),
+                "function": tool.get("function", {}),
+            }
+            schemas.append(schema)
+        return schemas
+
+    def _build_tool_map(self, config: dict) -> dict:
+        """Build a map of tool name to execution info."""
+        tool_map = {}
+        for tool in config.get("tools", []):
+            func_info = tool.get("function", {})
+            tool_name = func_info.get("name")
+            if tool_name:
+                # Get execution metadata from _meta field
+                meta = tool.get("_meta", {})
+                tool_map[tool_name] = {
+                    "function_path": meta.get("function_path"),
+                    "tool_id": meta.get("tool_id"),
+                    "is_dynamic": meta.get("is_dynamic", False),
+                }
+        return tool_map
+
+    async def _execute_tool(
+        self,
+        tool_name: str,
+        tool_args: dict,
+        tool_map: dict,
+        executor: "DynamicToolExecutor",
+        ctx: RunContext,
+    ) -> str:
+        """Execute a tool and return its result."""
+        tool_info = tool_map.get(tool_name, {})
+        function_path = tool_info.get("function_path")
+
+        if not function_path:
+            return json.dumps({"error": f"Tool '{tool_name}' has no function_path configured"})
+
+        try:
+            # Get user_id from context metadata if available
+            user_id = ctx.metadata.get("user_id")
+
+            # Execute the tool
+            result = await executor.execute(
+                function_path=function_path,
+                arguments=tool_args,
+                agent_run_id=ctx.run_id,
+                user_id=user_id,
+                tool_id=tool_info.get("tool_id"),
+            )
+
+            # Convert result to string if needed
+            if isinstance(result, str):
+                return result
+            return json.dumps(result)
+
+        except Exception as e:
+            logger.exception(f"Error executing tool {tool_name}")
+            return json.dumps({"error": str(e)})
+

django_agent_studio/migrations/0001_initial.py

@@ -0,0 +1,63 @@
+# Generated by Django 5.2.10 on 2026-01-23 14:27
+
+import django.db.models.deletion
+import uuid
+from django.conf import settings
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    initial = True
+
+    dependencies = [
+        ('django_agent_runtime', '0007_discoveredfunction_dynamictool_dynamictoolexecution'),
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='ToolApprovalRequest',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('proposed_name', models.CharField(max_length=100)),
+                ('proposed_description', models.TextField()),
+                ('proposed_is_safe', models.BooleanField(default=False)),
+                ('proposed_requires_confirmation', models.BooleanField(default=True)),
+                ('proposed_timeout_seconds', models.PositiveIntegerField(default=30)),
+                ('request_reason', models.TextField(help_text='Why this tool is needed')),
+                ('status', models.CharField(choices=[('pending', 'Pending Review'), ('approved', 'Approved'), ('rejected', 'Rejected'), ('cancelled', 'Cancelled by Requester')], default='pending', max_length=20)),
+                ('reviewed_at', models.DateTimeField(blank=True, null=True)),
+                ('review_notes', models.TextField(blank=True)),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('agent', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='tool_approval_requests', to='django_agent_runtime.agentdefinition')),
+                ('created_tool', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='approval_request', to='django_agent_runtime.dynamictool')),
+                ('discovered_function', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='approval_requests', to='django_agent_runtime.discoveredfunction')),
+                ('requester', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='tool_approval_requests', to=settings.AUTH_USER_MODEL)),
+                ('reviewed_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='tool_approval_reviews', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'Tool Approval Request',
+                'verbose_name_plural': 'Tool Approval Requests',
+                'ordering': ['-created_at'],
+            },
+        ),
+        migrations.CreateModel(
+            name='UserDynamicToolAccess',
+            fields=[
+                ('id', models.UUIDField(default=uuid.uuid4, editable=False, primary_key=True, serialize=False)),
+                ('access_level', models.CharField(choices=[('none', 'No Access'), ('viewer', 'Viewer (read-only)'), ('scanner', 'Scanner (can scan project)'), ('requester', 'Requester (needs approval)'), ('creator', 'Creator (can create tools)'), ('admin', 'Admin (full access)')], default='none', max_length=20)),
+                ('granted_at', models.DateTimeField(auto_now_add=True)),
+                ('updated_at', models.DateTimeField(auto_now=True)),
+                ('notes', models.TextField(blank=True, help_text='Reason for granting this access level')),
+                ('granted_by', models.ForeignKey(blank=True, null=True, on_delete=django.db.models.deletion.SET_NULL, related_name='dynamic_tool_access_grants_given', to=settings.AUTH_USER_MODEL)),
+                ('restricted_to_agents', models.ManyToManyField(blank=True, help_text='If set, access only applies to these agents', related_name='dynamic_tool_access_grants', to='django_agent_runtime.agentdefinition')),
+                ('user', models.OneToOneField(on_delete=django.db.models.deletion.CASCADE, related_name='dynamic_tool_access', to=settings.AUTH_USER_MODEL)),
+            ],
+            options={
+                'verbose_name': 'User Dynamic Tool Access',
+                'verbose_name_plural': 'User Dynamic Tool Access',
+            },
+        ),
+    ]

django_agent_studio/models/__init__.py

@@ -0,0 +1,18 @@
+"""
+Models for Django Agent Studio.
+
+Includes permission and approval workflow models for dynamic tools.
+"""
+
+from django_agent_studio.models.permissions import (
+    DynamicToolAccessLevel,
+    UserDynamicToolAccess,
+    ToolApprovalRequest,
+)
+
+__all__ = [
+    'DynamicToolAccessLevel',
+    'UserDynamicToolAccess',
+    'ToolApprovalRequest',
+]
+

django_agent_studio/models/permissions.py

@@ -0,0 +1,191 @@
+"""
+Permission models for Dynamic Tool access control.
+
+Provides:
+- Access levels for dynamic tool operations
+- Per-user access assignments
+- Approval workflow for tool creation requests
+"""
+
+import uuid
+from django.conf import settings
+from django.db import models
+
+
+class DynamicToolAccessLevel(models.TextChoices):
+    """
+    Access levels for dynamic tool operations.
+    
+    Ordered from least to most privileged:
+    - NONE: No access to dynamic tools
+    - VIEWER: Can view discovered functions and existing tools
+    - SCANNER: Can scan project for functions
+    - REQUESTER: Can request tool creation (needs admin approval)
+    - CREATOR: Can create tools directly (no approval needed)
+    - ADMIN: Full access including approving requests and managing permissions
+    """
+    NONE = 'none', 'No Access'
+    VIEWER = 'viewer', 'Viewer (read-only)'
+    SCANNER = 'scanner', 'Scanner (can scan project)'
+    REQUESTER = 'requester', 'Requester (needs approval)'
+    CREATOR = 'creator', 'Creator (can create tools)'
+    ADMIN = 'admin', 'Admin (full access)'
+
+
+# Define the hierarchy for permission checks
+ACCESS_LEVEL_HIERARCHY = {
+    DynamicToolAccessLevel.NONE: 0,
+    DynamicToolAccessLevel.VIEWER: 1,
+    DynamicToolAccessLevel.SCANNER: 2,
+    DynamicToolAccessLevel.REQUESTER: 3,
+    DynamicToolAccessLevel.CREATOR: 4,
+    DynamicToolAccessLevel.ADMIN: 5,
+}
+
+
+class UserDynamicToolAccess(models.Model):
+    """
+    Per-user access level for dynamic tools.
+    
+    If a user doesn't have a record, they default to NONE access
+    unless they're a superuser (who always have ADMIN access).
+    """
+    
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    
+    user = models.OneToOneField(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name='dynamic_tool_access',
+    )
+    
+    access_level = models.CharField(
+        max_length=20,
+        choices=DynamicToolAccessLevel.choices,
+        default=DynamicToolAccessLevel.NONE,
+    )
+    
+    # Optional: restrict to specific agents
+    # If empty, access applies to all agents user can access
+    restricted_to_agents = models.ManyToManyField(
+        'django_agent_runtime.AgentDefinition',
+        blank=True,
+        related_name='dynamic_tool_access_grants',
+        help_text='If set, access only applies to these agents',
+    )
+    
+    # Audit fields
+    granted_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name='dynamic_tool_access_grants_given',
+    )
+    granted_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    
+    notes = models.TextField(
+        blank=True,
+        help_text='Reason for granting this access level',
+    )
+    
+    class Meta:
+        verbose_name = 'User Dynamic Tool Access'
+        verbose_name_plural = 'User Dynamic Tool Access'
+    
+    def __str__(self):
+        return f"{self.user} - {self.get_access_level_display()}"
+    
+    def has_level(self, required_level: str) -> bool:
+        """Check if user has at least the required access level."""
+        user_rank = ACCESS_LEVEL_HIERARCHY.get(self.access_level, 0)
+        required_rank = ACCESS_LEVEL_HIERARCHY.get(required_level, 0)
+        return user_rank >= required_rank
+
+
+class ToolApprovalRequest(models.Model):
+    """
+    Request for tool creation that requires admin approval.
+    
+    Created when a user with REQUESTER access level wants to create a tool.
+    """
+    
+    class Status(models.TextChoices):
+        PENDING = 'pending', 'Pending Review'
+        APPROVED = 'approved', 'Approved'
+        REJECTED = 'rejected', 'Rejected'
+        CANCELLED = 'cancelled', 'Cancelled by Requester'
+    
+    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
+    
+    # The agent this tool would be added to
+    agent = models.ForeignKey(
+        'django_agent_runtime.AgentDefinition',
+        on_delete=models.CASCADE,
+        related_name='tool_approval_requests',
+    )
+    
+    # The discovered function to convert to a tool
+    discovered_function = models.ForeignKey(
+        'django_agent_runtime.DiscoveredFunction',
+        on_delete=models.CASCADE,
+        related_name='approval_requests',
+    )
+    
+    # Requester's proposed configuration
+    proposed_name = models.CharField(max_length=100)
+    proposed_description = models.TextField()
+    proposed_is_safe = models.BooleanField(default=False)
+    proposed_requires_confirmation = models.BooleanField(default=True)
+    proposed_timeout_seconds = models.PositiveIntegerField(default=30)
+    
+    # Request metadata
+    requester = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.CASCADE,
+        related_name='tool_approval_requests',
+    )
+    request_reason = models.TextField(
+        help_text='Why this tool is needed',
+    )
+    
+    # Status
+    status = models.CharField(
+        max_length=20,
+        choices=Status.choices,
+        default=Status.PENDING,
+    )
+    
+    # Review metadata
+    reviewed_by = models.ForeignKey(
+        settings.AUTH_USER_MODEL,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name='tool_approval_reviews',
+    )
+    reviewed_at = models.DateTimeField(null=True, blank=True)
+    review_notes = models.TextField(blank=True)
+    
+    # If approved, link to the created tool
+    created_tool = models.ForeignKey(
+        'django_agent_runtime.DynamicTool',
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name='approval_request',
+    )
+    
+    # Timestamps
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    
+    class Meta:
+        verbose_name = 'Tool Approval Request'
+        verbose_name_plural = 'Tool Approval Requests'
+        ordering = ['-created_at']
+    
+    def __str__(self):
+        return f"{self.proposed_name} - {self.get_status_display()}"
+

django_agent_studio/services/__init__.py

@@ -0,0 +1,14 @@
+"""
+Services for Django Agent Studio.
+"""
+
+from django_agent_studio.services.permissions import (
+    DynamicToolPermissionService,
+    get_permission_service,
+)
+
+__all__ = [
+    'DynamicToolPermissionService',
+    'get_permission_service',
+]
+