django-agent-studio 0.1.5__py3-none-any.whl → 0.1.8__py3-none-any.whl

django_agent_studio/agents/builder.py

@@ -40,6 +40,7 @@ You have access to tools that allow you to:
 7. **Create multi-agent systems** by adding sub-agent tools
 8. **Switch between agents and systems** in the UI
 9. **Configure agent memory** (enable/disable the remember tool)
+10. **Manage agent specifications** (human-readable behavior descriptions)
 
 ## IMPORTANT: Tool Usage
 
@@ -116,6 +117,59 @@ Agents have a built-in memory system that allows them to remember facts about us
 - Support agents that benefit from knowing user history
 - Any agent where personalization improves the experience
 
+## Agent Specification (Spec)
+
+Every agent can have a **spec** - a human-readable description of its intended behavior, separate from the technical system prompt.
+
+**Why use a spec?**
+- **Human oversight**: Non-technical stakeholders can review and approve agent behavior
+- **Documentation**: Clear record of what the agent should and shouldn't do
+- **Builder context**: You can reference the spec when crafting the system prompt
+
+**What to include in a spec:**
+- Purpose: What is this agent for?
+- Capabilities: What can it do?
+- Constraints: What should it NOT do?
+- Tone/personality: How should it communicate?
+- Edge cases: How should it handle unusual situations?
+
+**Simple spec tools (per-agent):**
+- `get_agent_spec` - View the current agent's spec
+- `update_agent_spec` - Update the current agent's spec
+
+**Best practice:** When building an agent, start by writing or reviewing the spec, then craft the system prompt to implement that spec. This ensures alignment between intended and actual behavior.
+
+## Spec Document System (Advanced)
+
+For organizations managing multiple agents, there's a **Spec Document System** that provides:
+- **Document tree structure**: Organize specs hierarchically (e.g., "Company Agents" → "Support" → "Billing Agent")
+- **Agent linking**: Link any document to an agent - changes sync automatically to the agent's spec
+- **Version history**: Every change creates a new version with full history and rollback
+- **Unified view**: Render the entire document tree as a single markdown document for human review
+
+**Spec Document Tools:**
+- `list_spec_documents` - List all spec documents
+- `get_spec_document` - Get a document with its content
+- `create_spec_document` - Create a new document (root or child)
+- `update_spec_document` - Update content (auto-versions)
+- `link_spec_to_agent` - Link a document to an agent
+- `unlink_spec_from_agent` - Remove the link
+- `get_spec_document_history` - View version history
+- `restore_spec_document_version` - Rollback to a previous version
+- `delete_spec_document` - Delete a document (and children)
+- `render_full_spec` - Render all documents as one markdown file
+
+**Example structure:**
+```
+Company AI Agents (root document)
+├── Customer Support
+│   ├── Billing Support → linked to billing-agent
+│   └── Technical Support → linked to tech-agent
+├── Internal Tools
+│   └── HR Assistant → linked to hr-agent
+└── Guidelines (shared context for all agents)
+```
+
 When helping users:
 - Ask clarifying questions to understand what they want their agent to do
 - Suggest appropriate system prompts based on the agent's purpose
@@ -232,6 +286,34 @@ BUILDER_TOOLS = [
             },
         },
     },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_agent_spec",
+            "description": "Get the agent's specification - a human-readable description of the agent's intended behavior, capabilities, and constraints. The spec is separate from the technical system prompt and is meant for human oversight and documentation.",
+            "parameters": {
+                "type": "object",
+                "properties": {},
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "update_agent_spec",
+            "description": "Update the agent's specification. The spec should describe in plain English: what the agent does, what it should and shouldn't do, its personality/tone, and any important constraints. This is for human oversight - non-technical stakeholders can review and edit this.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "spec": {
+                        "type": "string",
+                        "description": "The agent specification in plain English. Describe the agent's purpose, capabilities, constraints, and expected behavior.",
+                    },
+                },
+                "required": ["spec"],
+            },
+        },
+    },
     {
         "type": "function",
         "function": {
@@ -280,6 +362,231 @@ BUILDER_TOOLS = [
             },
         },
     },
+    # Spec Document tools
+    {
+        "type": "function",
+        "function": {
+            "name": "list_spec_documents",
+            "description": "List all spec documents, optionally filtered. Returns the document tree structure.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "root_only": {
+                        "type": "boolean",
+                        "description": "If true, only return root documents (no parent). Default: false",
+                    },
+                    "linked_only": {
+                        "type": "boolean",
+                        "description": "If true, only return documents linked to agents. Default: false",
+                    },
+                },
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_spec_document",
+            "description": "Get a spec document by ID, including its content and metadata.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "document_id": {
+                        "type": "string",
+                        "description": "The UUID of the document to retrieve",
+                    },
+                    "include_children": {
+                        "type": "boolean",
+                        "description": "If true, include all descendant documents. Default: false",
+                    },
+                    "render_as_markdown": {
+                        "type": "boolean",
+                        "description": "If true, render the document tree as a single markdown document. Default: false",
+                    },
+                },
+                "required": ["document_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "create_spec_document",
+            "description": "Create a new spec document. Can be a root document or a child of an existing document.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "title": {
+                        "type": "string",
+                        "description": "Document title",
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "Markdown content of the document",
+                    },
+                    "parent_id": {
+                        "type": "string",
+                        "description": "Optional: UUID of parent document. If not provided, creates a root document.",
+                    },
+                    "linked_agent_id": {
+                        "type": "string",
+                        "description": "Optional: UUID of agent to link this document to. The document content will sync to the agent's spec.",
+                    },
+                    "order": {
+                        "type": "integer",
+                        "description": "Optional: Order among siblings. Default: 0",
+                    },
+                },
+                "required": ["title"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "update_spec_document",
+            "description": "Update a spec document's content or metadata. Creates a new version automatically.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "document_id": {
+                        "type": "string",
+                        "description": "The UUID of the document to update",
+                    },
+                    "title": {
+                        "type": "string",
+                        "description": "New title (optional)",
+                    },
+                    "content": {
+                        "type": "string",
+                        "description": "New markdown content (optional)",
+                    },
+                    "order": {
+                        "type": "integer",
+                        "description": "New order among siblings (optional)",
+                    },
+                },
+                "required": ["document_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "link_spec_to_agent",
+            "description": "Link a spec document to an agent. The document's content will sync to the agent's spec field.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "document_id": {
+                        "type": "string",
+                        "description": "The UUID of the document",
+                    },
+                    "agent_id": {
+                        "type": "string",
+                        "description": "The UUID of the agent to link to. Use 'current' for the agent being edited.",
+                    },
+                },
+                "required": ["document_id", "agent_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "unlink_spec_from_agent",
+            "description": "Remove the link between a spec document and its agent.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "document_id": {
+                        "type": "string",
+                        "description": "The UUID of the document to unlink",
+                    },
+                },
+                "required": ["document_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "get_spec_document_history",
+            "description": "Get the version history of a spec document.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "document_id": {
+                        "type": "string",
+                        "description": "The UUID of the document",
+                    },
+                    "limit": {
+                        "type": "integer",
+                        "description": "Maximum number of versions to return. Default: 10",
+                    },
+                },
+                "required": ["document_id"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "restore_spec_document_version",
+            "description": "Restore a spec document to a previous version. Creates a new version with the restored content.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "document_id": {
+                        "type": "string",
+                        "description": "The UUID of the document",
+                    },
+                    "version_number": {
+                        "type": "integer",
+                        "description": "The version number to restore to",
+                    },
+                },
+                "required": ["document_id", "version_number"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "delete_spec_document",
+            "description": "Delete a spec document. If it has children, they will also be deleted.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "document_id": {
+                        "type": "string",
+                        "description": "The UUID of the document to delete",
+                    },
+                    "confirm": {
+                        "type": "boolean",
+                        "description": "Must be true to confirm deletion",
+                    },
+                },
+                "required": ["document_id", "confirm"],
+            },
+        },
+    },
+    {
+        "type": "function",
+        "function": {
+            "name": "render_full_spec",
+            "description": "Render all spec documents (or a subtree) as a single unified markdown document for human review.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "root_document_id": {
+                        "type": "string",
+                        "description": "Optional: Start from this document. If not provided, renders all root documents.",
+                    },
+                },
+            },
+        },
+    },
     {
         "type": "function",
         "function": {
@@ -943,6 +1250,23 @@ Knowledge: {len(config.get('knowledge', []))} sources
                 await create_revision(agent, comment=f"Renamed from '{old_name}' to '{agent.name}'")
                 return {"success": True, "message": "Agent name updated"}
 
+            elif tool_name == "get_agent_spec":
+                return {
+                    "spec": agent.spec or "",
+                    "has_spec": bool(agent.spec),
+                    "message": "The agent spec describes intended behavior in plain English, separate from the technical system prompt.",
+                }
+
+            elif tool_name == "update_agent_spec":
+                agent.spec = args["spec"]
+                await sync_to_async(agent.save)()
+                await create_revision(agent, comment="Updated agent specification")
+                return {
+                    "success": True,
+                    "message": "Agent specification updated",
+                    "spec_preview": agent.spec[:200] + "..." if len(agent.spec) > 200 else agent.spec,
+                }
+
             elif tool_name == "update_model_settings":
                 if version:
                     changes = []
@@ -984,6 +1308,37 @@ Knowledge: {len(config.get('knowledge', []))} sources
                     }
                 return {"error": "No active version found"}
 
+            # Spec Document tools
+            elif tool_name == "list_spec_documents":
+                return await self._list_spec_documents(agent, args, ctx)
+
+            elif tool_name == "get_spec_document":
+                return await self._get_spec_document(agent, args, ctx)
+
+            elif tool_name == "create_spec_document":
+                return await self._create_spec_document(agent, args, ctx)
+
+            elif tool_name == "update_spec_document":
+                return await self._update_spec_document(agent, args, ctx)
+
+            elif tool_name == "link_spec_to_agent":
+                return await self._link_spec_to_agent(agent, args, ctx)
+
+            elif tool_name == "unlink_spec_from_agent":
+                return await self._unlink_spec_from_agent(agent, args, ctx)
+
+            elif tool_name == "get_spec_document_history":
+                return await self._get_spec_document_history(agent, args, ctx)
+
+            elif tool_name == "restore_spec_document_version":
+                return await self._restore_spec_document_version(agent, args, ctx)
+
+            elif tool_name == "delete_spec_document":
+                return await self._delete_spec_document(agent, args, ctx)
+
+            elif tool_name == "render_full_spec":
+                return await self._render_full_spec(agent, args, ctx)
+
             elif tool_name == "add_knowledge":
                 inclusion_mode = args.get("inclusion_mode", "always")
                 knowledge = await sync_to_async(AgentKnowledge.objects.create)(
@@ -1992,3 +2347,385 @@ Knowledge: {len(config.get('knowledge', []))} sources
         except Exception as e:
             logger.exception("Error getting system details")
             return {"error": str(e)}
+
+    # ==================== Spec Document Methods ====================
+
+    async def _list_spec_documents(self, agent, args: dict, ctx: RunContext) -> dict:
+        """List spec documents with optional filtering."""
+        from django_agent_runtime.models import SpecDocument
+
+        try:
+            root_only = args.get("root_only", False)
+            linked_only = args.get("linked_only", False)
+
+            if root_only:
+                docs = await sync_to_async(list)(
+                    SpecDocument.objects.filter(parent__isnull=True)
+                    .select_related("linked_agent")
+                    .order_by("order", "title")
+                )
+            else:
+                docs = await sync_to_async(list)(
+                    SpecDocument.objects.all()
+                    .select_related("linked_agent", "parent")
+                    .order_by("parent_id", "order", "title")
+                )
+
+            if linked_only:
+                docs = [d for d in docs if d.linked_agent_id]
+
+            def format_doc(doc):
+                result = {
+                    "id": str(doc.id),
+                    "title": doc.title,
+                    "parent_id": str(doc.parent_id) if doc.parent_id else None,
+                    "order": doc.order,
+                    "current_version": doc.current_version,
+                    "has_content": bool(doc.content),
+                    "content_preview": doc.content[:100] + "..." if len(doc.content) > 100 else doc.content,
+                }
+                if doc.linked_agent:
+                    result["linked_agent"] = {
+                        "id": str(doc.linked_agent.id),
+                        "slug": doc.linked_agent.slug,
+                        "name": doc.linked_agent.name,
+                    }
+                return result
+
+            return {
+                "documents": [format_doc(d) for d in docs],
+                "count": len(docs),
+            }
+        except Exception as e:
+            logger.exception("Error listing spec documents")
+            return {"error": str(e)}
+
+    async def _get_spec_document(self, agent, args: dict, ctx: RunContext) -> dict:
+        """Get a spec document by ID."""
+        from django_agent_runtime.models import SpecDocument
+
+        try:
+            doc_id = args["document_id"]
+            include_children = args.get("include_children", False)
+            render_markdown = args.get("render_as_markdown", False)
+
+            doc = await sync_to_async(
+                SpecDocument.objects.select_related("linked_agent", "parent").get
+            )(id=doc_id)
+
+            result = {
+                "id": str(doc.id),
+                "title": doc.title,
+                "content": doc.content,
+                "parent_id": str(doc.parent_id) if doc.parent_id else None,
+                "order": doc.order,
+                "current_version": doc.current_version,
+                "full_path": await sync_to_async(doc.get_full_path)(),
+                "created_at": doc.created_at.isoformat(),
+                "updated_at": doc.updated_at.isoformat(),
+            }
+
+            if doc.linked_agent:
+                result["linked_agent"] = {
+                    "id": str(doc.linked_agent.id),
+                    "slug": doc.linked_agent.slug,
+                    "name": doc.linked_agent.name,
+                }
+
+            if include_children:
+                descendants = await sync_to_async(doc.get_descendants)()
+                result["children"] = [
+                    {
+                        "id": str(d.id),
+                        "title": d.title,
+                        "parent_id": str(d.parent_id) if d.parent_id else None,
+                        "has_content": bool(d.content),
+                        "linked_agent_slug": d.linked_agent.slug if d.linked_agent else None,
+                    }
+                    for d in descendants
+                ]
+
+            if render_markdown:
+                result["rendered_markdown"] = await sync_to_async(doc.render_tree_as_markdown)()
+
+            return result
+        except SpecDocument.DoesNotExist:
+            return {"error": f"Document not found: {args.get('document_id')}"}
+        except Exception as e:
+            logger.exception("Error getting spec document")
+            return {"error": str(e)}
+
+    async def _create_spec_document(self, agent, args: dict, ctx: RunContext) -> dict:
+        """Create a new spec document."""
+        from django_agent_runtime.models import SpecDocument, AgentDefinition
+
+        try:
+            title = args["title"]
+            content = args.get("content", "")
+            parent_id = args.get("parent_id")
+            linked_agent_id = args.get("linked_agent_id")
+            order = args.get("order", 0)
+
+            # Get parent if specified
+            parent = None
+            if parent_id:
+                parent = await sync_to_async(SpecDocument.objects.get)(id=parent_id)
+
+            # Get linked agent if specified
+            linked_agent = None
+            if linked_agent_id:
+                linked_agent = await sync_to_async(AgentDefinition.objects.get)(id=linked_agent_id)
+
+            # Create document
+            doc = await sync_to_async(SpecDocument.objects.create)(
+                title=title,
+                content=content,
+                parent=parent,
+                linked_agent=linked_agent,
+                order=order,
+                owner=ctx.user if ctx.user and ctx.user.is_authenticated else None,
+            )
+
+            return {
+                "success": True,
+                "message": f"Created spec document: {title}",
+                "document_id": str(doc.id),
+                "version": doc.current_version,
+                "linked_agent": linked_agent.slug if linked_agent else None,
+            }
+        except SpecDocument.DoesNotExist:
+            return {"error": f"Parent document not found: {parent_id}"}
+        except AgentDefinition.DoesNotExist:
+            return {"error": f"Agent not found: {linked_agent_id}"}
+        except Exception as e:
+            logger.exception("Error creating spec document")
+            return {"error": str(e)}
+
+    async def _update_spec_document(self, agent, args: dict, ctx: RunContext) -> dict:
+        """Update a spec document."""
+        from django_agent_runtime.models import SpecDocument
+
+        try:
+            doc_id = args["document_id"]
+            doc = await sync_to_async(SpecDocument.objects.get)(id=doc_id)
+
+            changes = []
+            if "title" in args:
+                doc.title = args["title"]
+                changes.append("title")
+            if "content" in args:
+                doc.content = args["content"]
+                changes.append("content")
+            if "order" in args:
+                doc.order = args["order"]
+                changes.append("order")
+
+            if changes:
+                await sync_to_async(doc.save)()
+                return {
+                    "success": True,
+                    "message": f"Updated spec document: {', '.join(changes)}",
+                    "document_id": str(doc.id),
+                    "new_version": doc.current_version,
+                }
+            else:
+                return {"message": "No changes specified"}
+        except SpecDocument.DoesNotExist:
+            return {"error": f"Document not found: {args.get('document_id')}"}
+        except Exception as e:
+            logger.exception("Error updating spec document")
+            return {"error": str(e)}
+
+    async def _link_spec_to_agent(self, agent, args: dict, ctx: RunContext) -> dict:
+        """Link a spec document to an agent."""
+        from django_agent_runtime.models import SpecDocument, AgentDefinition
+
+        try:
+            doc_id = args["document_id"]
+            agent_id = args["agent_id"]
+
+            doc = await sync_to_async(SpecDocument.objects.get)(id=doc_id)
+
+            # Handle 'current' as the agent being edited
+            if agent_id == "current":
+                target_agent = agent
+            else:
+                target_agent = await sync_to_async(AgentDefinition.objects.get)(id=agent_id)
+
+            doc.linked_agent = target_agent
+            await sync_to_async(doc.save)()
+
+            return {
+                "success": True,
+                "message": f"Linked document '{doc.title}' to agent '{target_agent.name}'",
+                "document_id": str(doc.id),
+                "agent_id": str(target_agent.id),
+                "agent_slug": target_agent.slug,
+            }
+        except SpecDocument.DoesNotExist:
+            return {"error": f"Document not found: {args.get('document_id')}"}
+        except AgentDefinition.DoesNotExist:
+            return {"error": f"Agent not found: {args.get('agent_id')}"}
+        except Exception as e:
+            logger.exception("Error linking spec to agent")
+            return {"error": str(e)}
+
+    async def _unlink_spec_from_agent(self, agent, args: dict, ctx: RunContext) -> dict:
+        """Unlink a spec document from its agent."""
+        from django_agent_runtime.models import SpecDocument
+
+        try:
+            doc_id = args["document_id"]
+            doc = await sync_to_async(
+                SpecDocument.objects.select_related("linked_agent").get
+            )(id=doc_id)
+
+            if not doc.linked_agent:
+                return {"message": "Document is not linked to any agent"}
+
+            old_agent_name = doc.linked_agent.name
+            doc.linked_agent = None
+            await sync_to_async(doc.save)()
+
+            return {
+                "success": True,
+                "message": f"Unlinked document '{doc.title}' from agent '{old_agent_name}'",
+                "document_id": str(doc.id),
+            }
+        except SpecDocument.DoesNotExist:
+            return {"error": f"Document not found: {args.get('document_id')}"}
+        except Exception as e:
+            logger.exception("Error unlinking spec from agent")
+            return {"error": str(e)}
+
+    async def _get_spec_document_history(self, agent, args: dict, ctx: RunContext) -> dict:
+        """Get version history of a spec document."""
+        from django_agent_runtime.models import SpecDocument, SpecDocumentVersion
+
+        try:
+            doc_id = args["document_id"]
+            limit = args.get("limit", 10)
+
+            doc = await sync_to_async(SpecDocument.objects.get)(id=doc_id)
+            versions = await sync_to_async(list)(
+                doc.versions.all()[:limit]
+            )
+
+            return {
+                "document_id": str(doc.id),
+                "document_title": doc.title,
+                "current_version": doc.current_version,
+                "versions": [
+                    {
+                        "version_number": v.version_number,
+                        "title": v.title,
+                        "content_preview": v.content[:100] + "..." if len(v.content) > 100 else v.content,
+                        "created_at": v.created_at.isoformat(),
+                        "change_summary": v.change_summary or "",
+                    }
+                    for v in versions
+                ],
+            }
+        except SpecDocument.DoesNotExist:
+            return {"error": f"Document not found: {args.get('document_id')}"}
+        except Exception as e:
+            logger.exception("Error getting spec document history")
+            return {"error": str(e)}
+
+    async def _restore_spec_document_version(self, agent, args: dict, ctx: RunContext) -> dict:
+        """Restore a spec document to a previous version."""
+        from django_agent_runtime.models import SpecDocument, SpecDocumentVersion
+
+        try:
+            doc_id = args["document_id"]
+            version_number = args["version_number"]
+
+            doc = await sync_to_async(SpecDocument.objects.get)(id=doc_id)
+            version = await sync_to_async(doc.versions.get)(version_number=version_number)
+
+            # Restore creates a new version
+            await sync_to_async(version.restore)()
+
+            # Refresh doc to get new version number
+            await sync_to_async(doc.refresh_from_db)()
+
+            return {
+                "success": True,
+                "message": f"Restored document to version {version_number}",
+                "document_id": str(doc.id),
+                "restored_from_version": version_number,
+                "new_version": doc.current_version,
+            }
+        except SpecDocument.DoesNotExist:
+            return {"error": f"Document not found: {args.get('document_id')}"}
+        except SpecDocumentVersion.DoesNotExist:
+            return {"error": f"Version not found: {args.get('version_number')}"}
+        except Exception as e:
+            logger.exception("Error restoring spec document version")
+            return {"error": str(e)}
+
+    async def _delete_spec_document(self, agent, args: dict, ctx: RunContext) -> dict:
+        """Delete a spec document."""
+        from django_agent_runtime.models import SpecDocument
+
+        try:
+            doc_id = args["document_id"]
+            confirm = args.get("confirm", False)
+
+            if not confirm:
+                return {"error": "Must set confirm=true to delete a document"}
+
+            doc = await sync_to_async(SpecDocument.objects.get)(id=doc_id)
+            title = doc.title
+
+            # Count children that will be deleted
+            children_count = await sync_to_async(doc.children.count)()
+
+            await sync_to_async(doc.delete)()
+
+            return {
+                "success": True,
+                "message": f"Deleted document '{title}'" + (f" and {children_count} children" if children_count else ""),
+                "deleted_children": children_count,
+            }
+        except SpecDocument.DoesNotExist:
+            return {"error": f"Document not found: {args.get('document_id')}"}
+        except Exception as e:
+            logger.exception("Error deleting spec document")
+            return {"error": str(e)}
+
+    async def _render_full_spec(self, agent, args: dict, ctx: RunContext) -> dict:
+        """Render all spec documents as a single markdown document."""
+        from django_agent_runtime.models import SpecDocument
+
+        try:
+            root_id = args.get("root_document_id")
+
+            if root_id:
+                # Render from specific root
+                doc = await sync_to_async(SpecDocument.objects.get)(id=root_id)
+                markdown = await sync_to_async(doc.render_tree_as_markdown)()
+                return {
+                    "markdown": markdown,
+                    "root_document": doc.title,
+                }
+            else:
+                # Render all root documents
+                roots = await sync_to_async(list)(
+                    SpecDocument.objects.filter(parent__isnull=True).order_by("order", "title")
+                )
+
+                parts = []
+                for root in roots:
+                    parts.append(await sync_to_async(root.render_tree_as_markdown)())
+
+                return {
+                    "markdown": "\n\n---\n\n".join(parts),
+                    "root_count": len(roots),
+                    "roots": [{"id": str(r.id), "title": r.title} for r in roots],
+                }
+        except SpecDocument.DoesNotExist:
+            return {"error": f"Document not found: {args.get('root_document_id')}"}
+        except Exception as e:
+            logger.exception("Error rendering full spec")
+            return {"error": str(e)}