debug-agent-py 0.2.1__py3-none-any.whl

debug_agent/system_prompt_builder.py

@@ -0,0 +1,101 @@
+"""Dynamic system prompt builder — generates prompt from registered tools."""
+
+from __future__ import annotations
+
+from debug_agent.tool_registry import registry
+
+CATEGORY_MAP = {
+    "heap": "Memory & GC",
+    "gc": "Memory & GC",
+    "memory": "Memory & GC",
+    "tracemalloc": "Memory & GC",
+    "object_count": "Memory & GC",
+    "ref_cycle": "Memory & GC",
+    "process": "Process Info",
+    "runtime": "Runtime Info",
+    "thread": "Threads",
+    "system": "System Info",
+    "cpu": "System Info",
+    "disk": "System Info",
+    "uptime": "System Info",
+    "routes": "Framework",
+    "middleware": "Framework",
+    "recent": "HTTP Requests",
+    "slow": "HTTP Requests",
+    "error": "HTTP Requests",
+    "request": "HTTP Requests",
+    "module": "Modules",
+    "import": "Modules",
+    "environment": "Environment & Config",
+    "installed": "Dependencies",
+    "sqlalchemy": "Database",
+    "db_": "Database",
+    "async": "Async Tasks",
+    "event_loop": "Async Tasks",
+    "package": "Dependencies",
+}
+
+
+class SystemPromptBuilder:
+    """Builds system prompt dynamically from registered tools."""
+
+    def __init__(self, tool_registry=registry):
+        self.registry = tool_registry
+
+    def build(self) -> str:
+        categories = self._categorize_tools()
+
+        sb = "You are an expert Python runtime debugging assistant.\n"
+        sb += "You are running INSIDE the developer's Python application and have direct access\n"
+        sb += "to its runtime state through diagnostic tools.\n\n"
+        sb += "## Your Capabilities\n"
+        sb += "You can call tools to inspect the live application. Here are ALL available tools,\n"
+        sb += "grouped by category:\n\n"
+
+        for category in sorted(categories.keys()):
+            tools = categories[category]
+            sb += f"**{category}**\n"
+            for tool in tools:
+                sb += f"- `{tool['name']}`: {self._truncate(tool['description'])}\n"
+            sb += "\n"
+
+        sb += "## Workflow\n"
+        sb += "1. Understand the developer's problem description\n"
+        sb += "2. Proactively call the most relevant tools to gather diagnostic data\n"
+        sb += "3. Analyze the collected data to identify root causes\n"
+        sb += "4. Provide clear, actionable solutions with data evidence\n\n"
+        sb += "## Guidelines\n"
+        sb += "- Be proactive: gather data with tools before answering\n"
+        sb += "- Always present data in a readable format (tables, bullet points)\n"
+        sb += "- Respond in the same language the developer uses\n"
+        sb += "- When you find a problem, explain the root cause and give concrete fix suggestions\n"
+        sb += "- You can call multiple tools in parallel if they are independent\n"
+
+        return sb
+
+    def _categorize_tools(self) -> dict[str, list[dict]]:
+        categories: dict[str, list[dict]] = {}
+        for schema in self.registry.all_schemas():
+            fn = schema["function"]
+            name = fn["name"]
+            desc = fn["description"]
+            category = self._extract_category(name)
+            if category not in categories:
+                categories[category] = []
+            categories[category].append({"name": name, "description": desc})
+        return categories
+
+    def _extract_category(self, tool_name: str) -> str:
+        name_lower = tool_name.lower()
+        for keyword, category in CATEGORY_MAP.items():
+            if keyword in name_lower:
+                return category
+        return "Other Tools"
+
+    def _truncate(self, desc: str) -> str:
+        if not desc:
+            return ""
+        period = desc.find(".")
+        if 0 < period < 150:
+            return desc[: period + 1]
+        return desc[:120] + "..." if len(desc) > 120 else desc

debug_agent/tool_registry.py

@@ -0,0 +1,121 @@
+"""Tool framework: decorator-based registration and execution."""
+
+from __future__ import annotations
+
+import inspect as pyinspect
+import json
+import typing
+from dataclasses import dataclass, field
+from typing import Any, Callable, get_type_hints
+
+
+@dataclass
+class ToolParam:
+    """Metadata for a tool parameter."""
+    description: str = ""
+    required: bool = True
+    default: Any = None
+
+
+@dataclass
+class ToolDefinition:
+    name: str
+    description: str
+    func: Callable
+    params: dict[str, ToolParam] = field(default_factory=dict)
+
+    def schema(self) -> dict:
+        """Generate OpenAI function-calling schema."""
+        hints = get_type_hints(self.func)
+        sig = pyinspect.signature(self.func)
+        properties = {}
+        required = []
+
+        for pname, param in sig.parameters.items():
+            if pname == "ctx":
+                continue
+            ptype = hints.get(pname, str)
+            json_type = _python_type_to_json(ptype)
+            tp = self.params.get(pname)
+            desc = tp.description if tp else ""
+            properties[pname] = {"type": json_type, "description": desc}
+
+            if param.default is pyinspect.Parameter.empty and (not tp or tp.required):
+                required.append(pname)
+
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": {
+                    "type": "object",
+                    "properties": properties,
+                    "required": required,
+                },
+            },
+        }
+
+    def execute(self, **kwargs) -> Any:
+        """Call the underlying function."""
+        return self.func(**kwargs)
+
+
+def _python_type_to_json(ptype) -> str:
+    mapping = {int: "integer", float: "number", bool: "boolean", str: "string", list: "array", dict: "object"}
+    return mapping.get(ptype, "string")
+
+
+class ToolRegistry:
+    """Global registry for debug tools."""
+
+    def __init__(self):
+        self._tools: dict[str, ToolDefinition] = {}
+
+    def register(self, tool: ToolDefinition):
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> ToolDefinition | None:
+        return self._tools.get(name)
+
+    def all_schemas(self) -> list[dict]:
+        return [t.schema() for t in self._tools.values()]
+
+    def execute(self, name: str, args: dict) -> Any:
+        tool = self._tools.get(name)
+        if not tool:
+            return {"error": f"Unknown tool: {name}"}
+        try:
+            result = tool.execute(**args)
+            return result
+        except Exception as e:
+            return {"error": str(e)}
+
+    def names(self) -> list[str]:
+        return list(self._tools.keys())
+
+
+# Global singleton
+registry = ToolRegistry()
+
+
+def debug_tool(name: str, description: str, params: dict[str, ToolParam] | None = None):
+    """Decorate a function to register it as a debug tool.
+
+    Usage:
+        @debug_tool("get_memory", "Get memory stats", {"detailed": ToolParam("Include details", required=False)})
+        def get_memory(detailed: bool = False) -> dict:
+            ...
+    """
+
+    def decorator(func: Callable) -> Callable:
+        tool = ToolDefinition(
+            name=name,
+            description=description,
+            func=func,
+            params=params or {},
+        )
+        registry.register(tool)
+        return func
+
+    return decorator