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

debug_agent/__init__.py

@@ -0,0 +1,23 @@
+"""Debug Agent — AI-powered runtime debugging for Python applications."""
+
+from debug_agent.config import AgentConfig
+from debug_agent.tool_registry import debug_tool, ToolParam, registry
+from debug_agent.engine import DebugEngine, ChatCallback
+from debug_agent.chat_session import ChatSession
+from debug_agent.system_prompt_builder import SystemPromptBuilder
+from debug_agent.context_compressor import ContextCompressor, CompressionResult
+from debug_agent.llm_client import LLMClient, StreamHandler
+
+__version__ = "0.1.0"
+__all__ = [
+    "AgentConfig", "debug_tool", "ToolParam", "registry", "DebugEngine", "ChatCallback",
+    "ChatSession", "SystemPromptBuilder", "ContextCompressor", "CompressionResult",
+    "LLMClient", "StreamHandler", "setup",
+]
+
+
+def setup(config: AgentConfig | None = None) -> DebugEngine:
+    """Initialize the debug agent and return the engine instance."""
+    from debug_agent import inspectors  # noqa: F401 — triggers registration
+    cfg = config or AgentConfig.from_env()
+    return DebugEngine(cfg)

debug_agent/chat_session.py

@@ -0,0 +1,45 @@
+"""Chat session management with token tracking."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+
+class ChatSession:
+    """Manages conversation history and cumulative token usage."""
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        self.created_at = time.time()
+        self.messages: list[dict[str, Any]] = []
+        self.last_active_at = self.created_at
+
+        self.last_token_usage: dict | None = None
+        self.cumulative_prompt_tokens: int = 0
+        self.cumulative_completion_tokens: int = 0
+
+    def add_message(self, message: dict[str, Any]):
+        self.messages.append(message)
+        self.last_active_at = time.time()
+
+    def replace_messages(self, new_messages: list[dict[str, Any]]):
+        self.messages = new_messages
+        self.last_active_at = time.time()
+
+    def record_token_usage(self, usage: dict | None):
+        if not usage:
+            return
+        self.last_token_usage = usage
+        self.cumulative_prompt_tokens = usage.get("prompt_tokens", 0)
+        self.cumulative_completion_tokens += usage.get("completion_tokens", 0)
+
+    def get_current_context_tokens(self) -> int:
+        return self.cumulative_prompt_tokens
+
+    def clear(self):
+        self.messages = []
+        self.last_token_usage = None
+        self.cumulative_prompt_tokens = 0
+        self.cumulative_completion_tokens = 0
+        self.last_active_at = time.time()

debug_agent/config.py

@@ -0,0 +1,48 @@
+"""Configuration for Debug Agent."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+
+@dataclass
+class LLMConfig:
+    base_url: str = "https://open.bigmodel.cn/api/coding/paas/v4"
+    api_key: str = ""
+    model: str = "glm-5.2"
+    temperature: float = 0.3
+    max_tokens: int = 4096
+    max_tool_rounds: int = 25
+    timeout_seconds: int = 120
+    max_retries: int = 3
+    retry_base_delay_ms: int = 1000
+    retry_max_delay_ms: int = 30000
+    context_window_tokens: int = 100000
+
+
+@dataclass
+class AgentConfig:
+    enabled: bool = True
+    base_path: str = "/agent"
+    llm: LLMConfig = field(default_factory=LLMConfig)
+
+    @classmethod
+    def from_env(cls) -> AgentConfig:
+        return cls(
+            enabled=os.getenv("DEBUG_AGENT_ENABLED", "true").lower() == "true",
+            base_path=os.getenv("DEBUG_AGENT_BASE_PATH", "/agent"),
+            llm=LLMConfig(
+                base_url=os.getenv("LLM_BASE_URL", "https://open.bigmodel.cn/api/coding/paas/v4"),
+                api_key=os.getenv("LLM_API_KEY") or os.getenv("OPENAI_API_KEY", ""),
+                model=os.getenv("LLM_MODEL", "glm-5.2"),
+                temperature=float(os.getenv("LLM_TEMPERATURE", "0.3")),
+                max_tokens=int(os.getenv("LLM_MAX_TOKENS", "4096")),
+                max_tool_rounds=int(os.getenv("LLM_MAX_TOOL_ROUNDS", "25")),
+                timeout_seconds=int(os.getenv("LLM_TIMEOUT_SECONDS", "120")),
+                max_retries=int(os.getenv("LLM_MAX_RETRIES", "3")),
+                retry_base_delay_ms=int(os.getenv("LLM_RETRY_BASE_DELAY_MS", "1000")),
+                retry_max_delay_ms=int(os.getenv("LLM_RETRY_MAX_DELAY_MS", "30000")),
+                context_window_tokens=int(os.getenv("LLM_CONTEXT_WINDOW_TOKENS", "100000")),
+            ),
+        )

debug_agent/context_compressor.py

@@ -0,0 +1,157 @@
+"""Context compressor — summarizes older conversation rounds via LLM."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from debug_agent.chat_session import ChatSession
+from debug_agent.llm_client import LLMClient
+
+logger = logging.getLogger("debug_agent")
+
+
+class CompressionResult:
+    def __init__(self, original_tokens: int, compressed_tokens: int, removed_rounds: int, strategy: str):
+        self.original_tokens = original_tokens
+        self.compressed_tokens = compressed_tokens
+        self.removed_rounds = removed_rounds
+        self.strategy = strategy
+
+
+class ContextCompressor:
+    def __init__(self, llm: LLMClient, model: str, temperature: float, max_context_tokens: int, recent_rounds_to_keep: int = 3):
+        self.llm = llm
+        self.model = model
+        self.temperature = temperature
+        self.max_context_tokens = max_context_tokens
+        self.recent_rounds_to_keep = recent_rounds_to_keep
+
+    def needs_compression(self, current_tokens: int) -> bool:
+        return current_tokens > self.max_context_tokens * 0.75
+
+    def compress(self, session: ChatSession) -> CompressionResult | None:
+        original_tokens = session.get_current_context_tokens()
+        if not self.needs_compression(original_tokens):
+            return None
+
+        rounds = self._identify_rounds(session.messages)
+
+        keep_count = min(self.recent_rounds_to_keep, len(rounds) - 1)
+        if keep_count < 1:
+            return None
+
+        summarize_count = len(rounds) - keep_count
+
+        to_summarize = []
+        for i in range(summarize_count):
+            to_summarize.extend(rounds[i])
+
+        to_keep = []
+        for i in range(summarize_count, len(rounds)):
+            to_keep.extend(rounds[i])
+
+        try:
+            summary = self._summarize_with_llm(to_summarize)
+        except Exception as e:
+            logger.warning(f"LLM summarization failed: {e}")
+            summary = self._fallback_truncate(to_summarize)
+
+        compressed = [
+            {"role": "system", "content": f"[Previous conversation summary — {summarize_count} rounds compressed]\n\n{summary}"},
+            *to_keep,
+        ]
+        compressed_tokens = self._estimate_tokens(compressed)
+        session.replace_messages(compressed)
+
+        return CompressionResult(original_tokens, compressed_tokens, summarize_count, f"LLM summarized {summarize_count} rounds")
+
+    def _summarize_with_llm(self, old_messages: list[dict]) -> str:
+        conversation_text = ""
+        for msg in old_messages:
+            role = msg.get("role", "")
+            content = msg.get("content", "")
+            if role == "user":
+                conversation_text += f"[User] {content}\n\n"
+            elif role == "assistant":
+                if content:
+                    conversation_text += f"[Assistant] {content}\n\n"
+                for tc in msg.get("tool_calls", []):
+                    fn = tc.get("function", {})
+                    conversation_text += f"[Tool Call] {fn.get('name', '')}({fn.get('arguments', '')})\n\n"
+            elif role == "tool":
+                if len(content) > 2000:
+                    content = content[:2000] + "...[truncated]"
+                conversation_text += f"[Tool Result] {content}\n\n"
+
+        prompt = """You are a conversation summarizer for a Python debugging assistant.
+Summarize the KEY diagnostic findings from the conversation below concisely.
+
+Focus on preserving:
+- Problems investigated and their root causes (if found)
+- Key tool results: actual numbers, statuses, error messages, configuration values
+- Recommendations or fixes already suggested
+- Any unresolved issues or follow-up actions pending
+
+Rules:
+- Be concise but preserve ALL important data points
+- Use bullet points
+- Do NOT include full JSON dumps
+- Keep it under 600 words"""
+
+        response = self.llm.chat(
+            [
+                {"role": "system", "content": prompt},
+                {"role": "user", "content": f"Conversation to summarize:\n\n{conversation_text}"},
+            ],
+            tools=None,
+        )
+        return response["choices"][0]["message"]["content"]
+
+    def _fallback_truncate(self, messages: list[dict]) -> str:
+        sb = "Previous conversation summary (fallback):\n\n"
+        for msg in messages:
+            if msg.get("role") == "user" and msg.get("content"):
+                q = msg["content"][:100] + "..." if len(msg["content"]) > 100 else msg["content"]
+                sb += f"- User asked: {q}\n"
+            if msg.get("role") == "assistant" and msg.get("tool_calls"):
+                for tc in msg["tool_calls"]:
+                    sb += f"- Called tool: {tc.get('function', {}).get('name', '')}\n"
+        return sb
+
+    def _identify_rounds(self, messages: list[dict]) -> list[list[dict]]:
+        rounds = []
+        current = []
+        has_assistant = False
+
+        for msg in messages:
+            role = msg.get("role", "")
+            if role == "user":
+                if current:
+                    rounds.append(current)
+                    current = []
+                    has_assistant = False
+                current.append(msg)
+            elif role == "assistant":
+                if has_assistant:
+                    rounds.append(current)
+                    current = []
+                    has_assistant = False
+                current.append(msg)
+                has_assistant = True
+            else:
+                current.append(msg)
+
+        if current:
+            rounds.append(current)
+        return rounds
+
+    def _estimate_tokens(self, messages: list[dict]) -> int:
+        chars = 0
+        for msg in messages:
+            chars += len(msg.get("content", "") or "")
+            for tc in msg.get("tool_calls", []):
+                fn = tc.get("function", {})
+                chars += len(fn.get("name", "")) + len(fn.get("arguments", ""))
+        return chars // 4

debug_agent/engine.py

@@ -0,0 +1,180 @@
+"""Debug engine — the reasoning loop that connects LLM to tools.
+
+Spring-aligned: dynamic system prompt, ChatSession, ContextCompressor, real streaming.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from debug_agent.chat_session import ChatSession
+from debug_agent.config import AgentConfig
+from debug_agent.context_compressor import ContextCompressor
+from debug_agent.llm_client import LLMClient, StreamHandler
+from debug_agent.system_prompt_builder import SystemPromptBuilder
+from debug_agent.tool_registry import registry
+
+logger = logging.getLogger("debug_agent")
+
+
+class ChatCallback:
+    """Engine to UI streaming callback."""
+
+    def on_content(self, chunk: str): ...
+    def on_tool_start(self, tool_name: str, args: str): ...
+    def on_tool_result(self, tool_name: str, result: str): ...
+    def on_complete(self): ...
+    def on_error(self, message: str): ...
+    def on_context_compressed(self, original_tokens: int, compressed_tokens: int, removed_rounds: int): ...
+
+
+class _EngineStreamHandler(StreamHandler):
+    """StreamHandler implementation used internally by the engine."""
+
+    def __init__(self, cb: ChatCallback):
+        self._cb = cb
+        self.tool_calls: list[dict] = []
+        self.usage: dict | None = None
+        self.had_error = False
+        self.content = ""
+
+    def on_content(self, chunk: str):
+        self.content += chunk
+        self._cb.on_content(chunk)
+
+    def on_complete(self, tool_calls: list[dict], finish_reason: str | None, usage: dict | None):
+        self.tool_calls = tool_calls
+        self.usage = usage
+
+    def on_error(self, error: Exception):
+        self.had_error = True
+        self._cb.on_error(f"LLM API error: {error}")
+
+
+class DebugEngine:
+    """Orchestrates the LLM Tool reasoning loop."""
+
+    def __init__(self, config: AgentConfig):
+        self.config = config
+        self.llm = LLMClient(config.llm)
+        self.tools = registry
+        self._sessions: dict[str, ChatSession] = {}
+
+        self.prompt_builder = SystemPromptBuilder(registry)
+        self.system_prompt = self.prompt_builder.build()
+        self.context_compressor = ContextCompressor(
+            self.llm, config.llm.model, config.llm.temperature, config.llm.context_window_tokens,
+        )
+
+    def chat(self, message: str, session_id: str = "default", callback: ChatCallback | None = None):
+        """Process a user message with streaming via callback."""
+        if callback is None:
+            callback = ChatCallback()
+
+        session = self._get_or_create_session(session_id)
+        session.add_message({"role": "user", "content": message})
+        self._run_tool_loop(session, callback)
+
+    def clear_session(self, session_id: str = "default"):
+        session = self._sessions.get(session_id)
+        if session:
+            session.clear()
+
+    def _get_or_create_session(self, session_id: str) -> ChatSession:
+        if session_id not in self._sessions:
+            self._sessions[session_id] = ChatSession(session_id)
+        return self._sessions[session_id]
+
+    # ==================== Core Tool-Calling Loop ====================
+
+    def _run_tool_loop(self, session: ChatSession, cb: ChatCallback):
+        max_rounds = self.config.llm.max_tool_rounds
+
+        for round_num in range(max_rounds):
+            # Context compression check
+            if round_num > 0 and self.context_compressor.needs_compression(session.get_current_context_tokens()):
+                result = self.context_compressor.compress(session)
+                if result:
+                    cb.on_content(
+                        f"\n\n> [Context auto-compressed: {result.original_tokens}"
+                        f" -> ~{result.compressed_tokens} tokens ({result.strategy})]\n\n"
+                    )
+                    cb.on_context_compressed(result.original_tokens, result.compressed_tokens, result.removed_rounds)
+
+            messages = [{"role": "system", "content": self.system_prompt}] + session.messages
+            tool_schemas = self.tools.all_schemas()
+
+            handler = _EngineStreamHandler(cb)
+            self.llm.chat_stream_raw(messages, tool_schemas, "auto", handler)
+
+            if handler.had_error:
+                return
+
+            if handler.usage:
+                session.record_token_usage(handler.usage)
+
+            if not handler.tool_calls:
+                # If empty content after tool calls, prompt LLM to summarize
+                if not handler.content.strip() and round_num > 0:
+                    session.add_message({
+                        "role": "user",
+                        "content": (
+                            "Based on all the diagnostic data you've gathered from the tools above, "
+                            "please provide a comprehensive analysis of the findings and "
+                            "actionable recommendations."
+                        ),
+                    })
+                    messages = [{"role": "system", "content": self.system_prompt}] + session.messages
+                    summarize_handler = _EngineStreamHandler(cb)
+                    self.llm.chat_stream_raw(messages, [], "none", summarize_handler)
+                    session.add_message({"role": "assistant", "content": summarize_handler.content})
+                else:
+                    session.add_message({"role": "assistant", "content": handler.content})
+                cb.on_complete()
+                return
+
+            # Execute tool calls
+            session.add_message({
+                "role": "assistant",
+                "content": handler.content,
+                "tool_calls": handler.tool_calls,
+            })
+
+            for tc in handler.tool_calls:
+                tool_name = tc["function"]["name"]
+                try:
+                    args = json.loads(tc["function"]["arguments"] or "{}")
+                except json.JSONDecodeError:
+                    args = {}
+
+                cb.on_tool_start(tool_name, tc["function"]["arguments"])
+
+                result = self.tools.execute(tool_name, args)
+                result_str = json.dumps(result, default=str, ensure_ascii=False)
+                if len(result_str) > 12000:
+                    result_str = result_str[:12000]
+
+                cb.on_tool_result(tool_name, result_str)
+                session.add_message({
+                    "role": "tool",
+                    "tool_call_id": tc["id"],
+                    "content": result_str,
+                })
+
+        # Max rounds - force final summary
+        final_messages = [{"role": "system", "content": self.system_prompt}] + session.messages
+        final_messages.append({
+            "role": "system",
+            "content": (
+                "You have reached the maximum number of tool-calling rounds. "
+                "Based on all the diagnostic data you have gathered so far, "
+                "provide a comprehensive analysis and actionable recommendations NOW. "
+                "Do not attempt to call more tools."
+            ),
+        })
+
+        handler = _EngineStreamHandler(cb)
+        self.llm.chat_stream_raw(final_messages, [], "none", handler)
+        cb.on_complete()

debug_agent/inspectors/__init__.py

@@ -0,0 +1,13 @@
+"""All built-in inspectors are auto-registered when this package is imported."""
+
+from debug_agent.inspectors import (  # noqa: F401
+    async_tasks,
+    database,
+    framework,
+    http_tracker,
+    memory,
+    modules,
+    runtime,
+    system,
+    threads,
+)

debug_agent/inspectors/async_tasks.py

@@ -0,0 +1,108 @@
+"""Async task inspector: pending asyncio tasks and event loop details."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Any
+
+from debug_agent.tool_registry import debug_tool, ToolParam
+
+
+def _get_running_loop() -> asyncio.AbstractEventLoop | None:
+    """Try to get the currently running event loop."""
+    try:
+        return asyncio.get_running_loop()
+    except RuntimeError:
+        # No running loop in this thread
+        pass
+    try:
+        return asyncio.get_event_loop()
+    except RuntimeError:
+        return None
+
+
+@debug_tool(
+    "get_async_tasks",
+    "List pending asyncio tasks if running in async mode",
+)
+def get_async_tasks() -> dict:
+    loop = _get_running_loop()
+    if loop is None:
+        return {
+            "message": "No running asyncio event loop found. The app may be using synchronous mode.",
+            "has_running_loop": False,
+        }
+
+    try:
+        all_tasks = asyncio.all_tasks(loop=loop)
+    except RuntimeError:
+        return {"error": "Could not enumerate asyncio tasks"}
+
+    tasks_info = []
+    for task in all_tasks:
+        coro = task.get_coro() if hasattr(task, "get_coro") else None
+        tasks_info.append({
+            "name": task.get_name() if hasattr(task, "get_name") else str(task),
+            "done": task.done(),
+            "cancelled": task.cancelled(),
+            "coroutine": str(coro) if coro else None,
+            "stack_repr": repr(task),
+        })
+
+    return {
+        "has_running_loop": True,
+        "total_tasks": len(all_tasks),
+        "pending_tasks": sum(1 for t in all_tasks if not t.done()),
+        "done_tasks": sum(1 for t in all_tasks if t.done()),
+        "tasks": tasks_info[:50],
+    }
+
+
+@debug_tool(
+    "get_event_loop_info",
+    "Get asyncio event loop details: type, running state, debug mode",
+)
+def get_event_loop_info() -> dict:
+    loop = _get_running_loop()
+    if loop is None:
+        return {
+            "message": "No running asyncio event loop found",
+            "has_running_loop": False,
+        }
+
+    info = {
+        "has_running_loop": True,
+        "loop_type": type(loop).__name__,
+        "is_running": loop.is_running(),
+        "is_closed": loop.is_closed(),
+        "debug_mode": loop.get_debug(),
+    }
+
+    # Try to get additional details
+    try:
+        info["time"] = loop.time()
+    except Exception:
+        pass
+
+    # Async generator count
+    try:
+        info["async_generator_count"] = len(loop._asyncgens) if hasattr(loop, "_asyncgens") else 0
+    except Exception:
+        pass
+
+    # Check for uvloop
+    try:
+        import uvloop
+        info["using_uvloop"] = isinstance(loop, uvloop.Loop)
+    except ImportError:
+        info["using_uvloop"] = False
+
+    # Task count
+    try:
+        all_tasks = asyncio.all_tasks(loop=loop)
+        info["active_task_count"] = len(all_tasks)
+    except RuntimeError:
+        info["active_task_count"] = 0
+
+    return info