django-agent-studio 0.2.6__tar.gz

django_agent_studio-0.2.6/LICENSE

@@ -0,0 +1,83 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor:             Chris Barry
+Licensed Work:        django-agent-studio
+                      The Licensed Work is (c) 2025 Chris Barry
+Additional Use Grant: You may use the Licensed Work for non-production purposes,
+                      including development, testing, and evaluation. Production
+                      use requires a commercial license from the Licensor.
+Change Date:          2029-01-24
+Change License:       MIT
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+

django_agent_studio-0.2.6/PKG-INFO

@@ -0,0 +1,509 @@
+Metadata-Version: 2.4
+Name: django-agent-studio
+Version: 0.2.6
+Summary: Visual agent builder and management studio for Django - build custom GPTs with a two-pane interface
+Author: Chris Barry
+License: Business Source License 1.1
+        
+        License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+        "Business Source License" is a trademark of MariaDB Corporation Ab.
+        
+        Parameters
+        
+        Licensor:             Chris Barry
+        Licensed Work:        django-agent-studio
+                              The Licensed Work is (c) 2025 Chris Barry
+        Additional Use Grant: You may use the Licensed Work for non-production purposes,
+                              including development, testing, and evaluation. Production
+                              use requires a commercial license from the Licensor.
+        Change Date:          2029-01-24
+        Change License:       MIT
+        
+        Terms
+        
+        The Licensor hereby grants you the right to copy, modify, create derivative
+        works, redistribute, and make non-production use of the Licensed Work. The
+        Licensor may make an Additional Use Grant, above, permitting limited production
+        use.
+        
+        Effective on the Change Date, or the fourth anniversary of the first publicly
+        available distribution of a specific version of the Licensed Work under this
+        License, whichever comes first, the Licensor hereby grants you rights under
+        the terms of the Change License, and the rights granted in the paragraph above
+        terminate.
+        
+        If your use of the Licensed Work does not comply with the requirements
+        currently in effect as described in this License, you must purchase a
+        commercial license from the Licensor, its affiliated entities, or authorized
+        resellers, or you must refrain from using the Licensed Work.
+        
+        All copies of the original and modified Licensed Work, and derivative works
+        of the Licensed Work, are subject to this License. This License applies
+        separately for each version of the Licensed Work and the Change Date may vary
+        for each version of the Licensed Work released by Licensor.
+        
+        You must conspicuously display this License on each original or modified copy
+        of the Licensed Work. If you receive the Licensed Work in original or
+        modified form from a third party, the terms and conditions set forth in this
+        License apply to your use of that work.
+        
+        Any use of the Licensed Work in violation of this License will automatically
+        terminate your rights under this License for the current and all other
+        versions of the Licensed Work.
+        
+        This License does not grant you any right in any trademark or logo of
+        Licensor or its affiliates (provided that you may use a trademark or logo of
+        Licensor as expressly required by this License).
+        
+        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+        AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+        TITLE.
+        
+        MariaDB hereby grants you permission to use this License's text to license
+        your works, and to refer to it using the trademark "Business Source License",
+        as long as you comply with the Covenants of Licensor below.
+        
+        Covenants of Licensor
+        
+        In consideration of the right to use this License's text and the "Business
+        Source License" name and trademark, Licensor covenants to MariaDB, and to all
+        other recipients of the licensed work to be provided by Licensor:
+        
+        1. To specify as the Change License the GPL Version 2.0 or any later version,
+           or a license that is compatible with GPL Version 2.0 or a later version,
+           where "compatible" means that software provided under the Change License can
+           be included in a program with software provided under GPL Version 2.0 or a
+           later version. Licensor may specify additional Change Licenses without
+           limitation.
+        
+        2. To either: (a) specify an additional grant of rights to use that does not
+           impose any additional restriction on the right granted in this License, as
+           the Additional Use Grant; or (b) insert the text "None".
+        
+        3. To specify a Change Date.
+        
+        4. Not to modify this License in any other way.
+        
+        
+Project-URL: Homepage, https://github.com/makemore/django-agent-studio
+Project-URL: Documentation, https://github.com/makemore/django-agent-studio#readme
+Project-URL: Repository, https://github.com/makemore/django-agent-studio
+Keywords: django,ai,agent,llm,gpt,builder,studio
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django>=4.2
+Requires-Dist: djangorestframework>=3.14
+Requires-Dist: django-agent-runtime>=0.3.12
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-django>=4.5; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: license-file
+
+# Django Agent Studio
+
+A visual agent builder and management interface for Django applications. Create, customize, and test AI agents through a conversational interface or REST API.
+
+## Recent Updates
+
+| Version | Date | Changes |
+|---------|------|---------|
+| **0.2.0** | 2026-01-28 | **Multi-Agent Systems** - System management UI, shared memory configuration, memory privacy controls, builder tools for managing agent systems |
+| **0.1.9** | 2026-01-27 | Spec documents migration, improved builder agent |
+| **0.1.0** | 2026-01-25 | Initial release with builder interface, dynamic tools, knowledge management |
+
+## Features
+
+### 🤖 Agent Builder Interface
+
+A two-pane interface for building agents:
+- **Left pane**: Test your agent in real-time
+- **Right pane**: Conversational builder agent that helps you configure your agent
+
+The builder agent can:
+- Create new agents
+- Update system prompts, models, and settings
+- Add/remove tools and knowledge sources
+- Scan your Django project for functions to use as tools
+- Manage RAG (Retrieval-Augmented Generation) configuration
+
+### 🔧 Dynamic Tool Discovery
+
+Automatically discover functions in your Django project that can be used as agent tools:
+
+```python
+# Functions like this are automatically discovered
+def get_customer_orders(customer_id: int, limit: int = 10) -> list[dict]:
+    """
+    Fetch recent orders for a customer.
+    
+    Args:
+        customer_id: The customer's ID
+        limit: Maximum number of orders to return
+    
+    Returns:
+        List of order dictionaries
+    """
+    return Order.objects.filter(customer_id=customer_id)[:limit]
+```
+
+The scanner extracts:
+- Function signatures and parameters
+- Type hints and docstrings
+- Whether functions are async
+- Side effect detection (writes, deletes, etc.)
+
+### 📚 Knowledge Management
+
+Add context to your agents through multiple knowledge types:
+- **Text**: Direct text content
+- **URL**: Web pages (fetched and indexed)
+- **File**: Uploaded documents
+- **Dynamic**: Generated at runtime via callbacks
+
+Knowledge can be:
+- Always included in context
+- Included via RAG similarity search
+- Included on-demand when relevant
+
+### 🔐 Permission System
+
+Fine-grained access control for dynamic tool operations:
+
+| Level | Capabilities |
+|-------|-------------|
+| **None** | No access to dynamic tools |
+| **Viewer** | View discovered functions and existing tools |
+| **Scanner** | Scan project for functions |
+| **Requester** | Request tool creation (needs admin approval) |
+| **Creator** | Create tools directly |
+| **Admin** | Full access including approving requests |
+
+### ✅ Approval Workflow
+
+For organizations requiring oversight:
+1. Users with "Requester" access submit tool creation requests
+2. Admins review proposed tool configurations
+3. Admins can approve (with optional modifications) or reject
+4. Approved tools are automatically created and marked as verified
+
+### 📝 Version Control
+
+- **Agent Versions**: Create and manage multiple versions of an agent
+- **Revisions**: Automatic snapshots after every change
+- **Restore**: Roll back to any previous revision
+
+## Installation
+
+```bash
+pip install django-agent-studio
+```
+
+Add to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    'django_agent_runtime',  # Required dependency
+    'django_agent_studio',
+]
+```
+
+Include the URLs:
+
+```python
+# urls.py
+from django.urls import path, include
+
+urlpatterns = [
+    # ...
+    path('studio/', include('django_agent_studio.urls')),
+    path('api/agent-runtime/', include('django_agent_runtime.api.urls')),
+]
+```
+
+Run migrations:
+
+```bash
+python manage.py migrate
+```
+
+## Usage
+
+### Web Interface
+
+Navigate to `/studio/` to access the agent builder interface.
+
+### REST API
+
+#### Agents
+
+```http
+# List your agents
+GET /studio/api/agents/
+
+# Create an agent
+POST /studio/api/agents/
+{
+    "name": "Customer Support Bot",
+    "description": "Helps customers with orders and returns"
+}
+
+# Get agent details
+GET /studio/api/agents/{id}/
+
+# Get full agent schema (for debugging/export)
+GET /studio/api/agents/{id}/full-schema/
+
+# Update agent schema
+PUT /studio/api/agents/{id}/full-schema/
+```
+
+#### Versions
+
+```http
+# List versions
+GET /studio/api/agents/{id}/versions/
+
+# Create a new version
+POST /studio/api/agents/{id}/versions/
+
+# Activate a version
+POST /studio/api/agents/{id}/versions/{version_id}/activate/
+```
+
+#### Tools
+
+```http
+# List agent tools
+GET /studio/api/agents/{id}/tools/
+
+# Add a tool
+POST /studio/api/agents/{id}/tools/
+
+# List dynamic tools
+GET /studio/api/agents/{id}/dynamic-tools/
+
+# Toggle dynamic tool active status
+POST /studio/api/agents/{id}/dynamic-tools/{tool_id}/toggle/
+```
+
+#### Knowledge
+
+```http
+# List knowledge sources
+GET /studio/api/agents/{id}/knowledge/
+
+# Add knowledge
+POST /studio/api/agents/{id}/knowledge/
+{
+    "name": "Product FAQ",
+    "knowledge_type": "text",
+    "content": "Q: How do I return an item?...",
+    "inclusion_mode": "always"
+}
+```
+
+#### Dynamic Tool Discovery
+
+```http
+# Scan project for functions
+POST /studio/api/agents/{id}/scan-project/
+{
+    "include_private": false,
+    "include_tests": false,
+    "app_filter": "myapp"
+}
+
+# List discovered functions
+GET /studio/api/discovered-functions/
+
+# Generate tools from functions
+POST /studio/api/agents/{id}/generate-tools/
+{
+    "function_ids": ["uuid1", "uuid2"],
+    "requires_confirmation": true
+}
+```
+
+#### Approval Workflow
+
+```http
+# List approval requests
+GET /studio/api/tool-approval-requests/
+
+# Review a request (admin only)
+POST /studio/api/tool-approval-requests/{id}/review/
+{
+    "action": "approve",  # or "reject"
+    "review_notes": "Looks good!",
+    "override_name": "custom_tool_name"  # optional
+}
+
+# Cancel your own request
+POST /studio/api/tool-approval-requests/{id}/cancel/
+```
+
+#### Permission Management
+
+```http
+# Get your access level
+GET /studio/api/dynamic-tool-access/me/
+
+# Grant access (admin only)
+POST /studio/api/dynamic-tool-access/grant/
+{
+    "user_id": 123,
+    "access_level": "creator",
+    "restricted_to_agent_ids": ["uuid1"],  # optional
+    "notes": "Granted for project X"
+}
+
+# Revoke access (admin only)
+POST /studio/api/dynamic-tool-access/revoke/
+{
+    "user_id": 123
+}
+```
+
+#### Templates
+
+```http
+# List public template agents
+GET /studio/api/templates/
+
+# Fork a template
+POST /studio/api/agents/{id}/fork/
+```
+
+## Builder Agent
+
+The builder agent (`agent-builder`) is a special agent that helps users create and configure other agents through conversation. It has access to tools for:
+
+- `create_agent` - Create a new agent
+- `get_current_config` - View current agent configuration
+- `update_system_prompt` - Update the agent's personality/instructions
+- `update_agent_name` - Change name and description
+- `update_model_settings` - Change LLM model and parameters
+- `add_knowledge` - Add knowledge sources
+- `remove_knowledge` - Remove knowledge sources
+- `scan_project_for_tools` - Discover functions in the codebase
+- `list_discovered_functions` - Browse discovered functions
+- `get_function_details` - Get details about a specific function
+- `add_tool_from_function` - Add a function as a tool
+- `list_agent_tools` - List all tools on the agent
+- `remove_tool` - Remove a tool
+- `list_revisions` - View revision history
+- `get_revision` - Get a specific revision
+- `restore_revision` - Restore to a previous state
+- `index_knowledge` - Index knowledge for RAG
+- `get_rag_status` - Check RAG indexing status
+- `preview_rag_search` - Test RAG search queries
+- `update_rag_config` - Configure RAG settings
+
+## Multi-Agent Systems
+
+Django Agent Studio supports building multi-agent systems where agents can invoke other agents as tools. This enables powerful patterns like routers, specialists, and hierarchical agent teams.
+
+### Overview
+
+Multi-agent systems use the "agent-as-tool" pattern from `agent-runtime-core`:
+
+- **Router Pattern**: A main agent routes requests to specialist agents
+- **Delegation**: Sub-agents run and return results to the parent
+- **Handoff**: Control transfers completely to a sub-agent
+
+For full documentation, see:
+- [agent-runtime-core Multi-Agent Systems](https://github.com/makemore/agent-runtime-core#multi-agent-systems)
+- [django-agent-runtime Multi-Agent Systems](https://github.com/makemore/django-agent-runtime#multi-agent-systems)
+
+### Using Multi-Agent with Studio Agents
+
+Studio-created agents can be used as sub-agents in code-defined router agents:
+
+```python
+from django_agent_studio.runtime import StudioAgentRuntime
+from agent_runtime_core.multi_agent import AgentTool, InvocationMode, ContextMode
+
+# Load a studio-created agent
+billing_agent = StudioAgentRuntime.from_agent_id("uuid-of-billing-agent")
+
+# Wrap it as a tool
+billing_tool = AgentTool(
+    agent=billing_agent,
+    name="billing_specialist",
+    description="Handles billing questions and refunds",
+    invocation_mode=InvocationMode.DELEGATE,
+)
+
+# Use in a router agent
+class RouterAgent(AgentRuntime):
+    def __init__(self):
+        self.agent_tools = [billing_tool]
+
+    async def run(self, ctx: RunContext) -> RunResult:
+        # Register and use agent tools...
+        pass
+```
+
+### Key Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **AgentTool** | Wraps any agent to be callable as a tool |
+| **DELEGATE mode** | Sub-agent returns result to parent (parent continues) |
+| **HANDOFF mode** | Control transfers to sub-agent (parent exits) |
+| **Context modes** | FULL (all history), SUMMARY, or MESSAGE_ONLY |
+
+### Events
+
+Multi-agent invocations emit events for observability:
+
+- `sub_agent.start` - Sub-agent invocation started
+- `sub_agent.end` - Sub-agent completed
+- Events include `parent_run_id` and `sub_agent_run_id` for tracing
+
+## Configuration
+
+Configure via Django settings or environment variables:
+
+```python
+AGENT_RUNTIME = {
+    # Default model for new agents
+    'DEFAULT_MODEL': 'gpt-4o',
+    
+    # RAG settings
+    'RAG_EMBEDDING_MODEL': 'text-embedding-3-small',
+    'RAG_CHUNK_SIZE': 500,
+    'RAG_CHUNK_OVERLAP': 50,
+}
+```
+
+## Dependencies
+
+- `django-agent-runtime` - Core agent runtime
+- `agent-runtime-core` - Agent execution framework
+- `agent-frontend` - Chat widget for the UI
+
+## License
+
+MIT
+