debug-agent-py 0.2.1__tar.gz

debug_agent_py-0.2.1/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: debug-agent-py
+Version: 0.2.1
+Summary: AI-powered runtime debugging agent for Python web applications
+Author-email: ggcode <noreply@ggcode.dev>
+License: MIT
+Project-URL: Homepage, https://github.com/topcheer/python-debug-agent
+Project-URL: Repository, https://github.com/topcheer/python-debug-agent
+Project-URL: Issues, https://github.com/topcheer/python-debug-agent/issues
+Keywords: debug,debugging,ai,llm,runtime,diagnostics,flask,fastapi,django,agent,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == "fastapi"
+Requires-Dist: starlette>=0.27; extra == "fastapi"
+Requires-Dist: uvicorn>=0.23; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: flask>=2.3; extra == "flask"
+Provides-Extra: django
+Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: dev
+Requires-Dist: fastapi; extra == "dev"
+Requires-Dist: uvicorn; extra == "dev"
+Requires-Dist: flask; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# Python Debug Agent
+
+An AI-powered runtime debugging agent that embeds directly into your Python web application. Add one dependency, configure an LLM key, and chat with your live app at `/agent` to inspect memory, threads, routes, HTTP requests, GC stats, and more.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install debug-agent[fastapi]
+```
+
+### 2. Integrate (FastAPI)
+
+```python
+from fastapi import FastAPI
+from debug_agent.middleware import create_fastapi_router
+
+app = FastAPI()
+
+# One line to integrate
+app.include_router(create_fastapi_router())
+```
+
+### 3. Configure LLM
+
+```bash
+export LLM_API_KEY=your-key
+export LLM_BASE_URL=https://api.openai.com/v1  # optional
+export LLM_MODEL=gpt-4o                         # optional
+```
+
+### 4. Run and open
+
+```
+http://localhost:8000/agent
+```
+
+## Framework Integrations
+
+### FastAPI / Starlette
+
+```python
+from debug_agent.middleware import create_fastapi_router
+app.include_router(create_fastapi_router())
+```
+
+### Flask
+
+```python
+from flask import Flask
+from debug_agent.middleware import create_flask_blueprint
+app = Flask(__name__)
+app.register_blueprint(create_flask_blueprint())
+```
+
+### Any ASGI App (Starlette Mount)
+
+```python
+from starlette.routing import Mount
+from debug_agent.middleware import create_starlette_app
+routes = [Mount("/agent", app=create_starlette_app())]
+```
+
+## Built-in Tools (18+)
+
+| Tool | Description |
+|------|-------------|
+| `get_gc_stats` | GC collection counts per generation |
+| `get_memory_summary` | RSS, object counts, top types |
+| `trigger_gc` | Force GC and show before/after |
+| `get_thread_summary` | Thread count, names, daemon status |
+| `get_thread_dump` | Stack traces for all threads |
+| `get_runtime_info` | Python version, platform, PID |
+| `get_memory_allocations` | tracemalloc top allocations |
+| `get_routes` | List all web routes/endpoints |
+| `get_middleware` | List registered middleware |
+| `get_installed_packages` | Installed pip packages |
+| `get_environment_variables` | Environment variables (masked secrets) |
+| `get_recent_requests` | HTTP request ring buffer |
+| `get_slow_requests` | Slowest requests sorted by duration |
+| `get_error_requests` | Error requests (4xx/5xx) |
+| `get_request_stats` | P50/P95/P99 latency, error rate |
+| `get_process_info` | PID, CPU time, container detection |
+| `get_system_info` | OS, CPU cores, load average |
+| `get_disk_usage` | Disk usage for working directory |
+
+## Custom Tools
+
+```python
+from debug_agent import debug_tool, ToolParam
+
+@debug_tool("check_db_pool", "Check database connection pool stats")
+def check_db_pool() -> dict:
+    return {"active": 5, "idle": 10, "max": 20}
+```
+
+That's it. The tool is auto-discovered and made available to the LLM.
+
+## Configuration
+
+| Env Var | Default | Description |
+|---------|---------|-------------|
+| `DEBUG_AGENT_ENABLED` | `true` | Enable/disable |
+| `DEBUG_AGENT_BASE_PATH` | `/agent` | URL path |
+| `LLM_BASE_URL` | `https://api.openai.com/v1` | LLM endpoint |
+| `LLM_API_KEY` | (required) | API key |
+| `LLM_MODEL` | `gpt-4o` | Model name |
+| `LLM_TEMPERATURE` | `0.3` | Sampling temp |
+| `LLM_MAX_TOOL_ROUNDS` | `10` | Max tool rounds |
+
+## Run the Demo
+
+```bash
+pip install -e ".[dev]"
+export LLM_API_KEY=your-key
+python demo/app.py
+# Open http://localhost:8000/agent
+```
+
+## License
+
+MIT

debug_agent_py-0.2.1/README.md

@@ -0,0 +1,123 @@
+# Python Debug Agent
+
+An AI-powered runtime debugging agent that embeds directly into your Python web application. Add one dependency, configure an LLM key, and chat with your live app at `/agent` to inspect memory, threads, routes, HTTP requests, GC stats, and more.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pip install debug-agent[fastapi]
+```
+
+### 2. Integrate (FastAPI)
+
+```python
+from fastapi import FastAPI
+from debug_agent.middleware import create_fastapi_router
+
+app = FastAPI()
+
+# One line to integrate
+app.include_router(create_fastapi_router())
+```
+
+### 3. Configure LLM
+
+```bash
+export LLM_API_KEY=your-key
+export LLM_BASE_URL=https://api.openai.com/v1  # optional
+export LLM_MODEL=gpt-4o                         # optional
+```
+
+### 4. Run and open
+
+```
+http://localhost:8000/agent
+```
+
+## Framework Integrations
+
+### FastAPI / Starlette
+
+```python
+from debug_agent.middleware import create_fastapi_router
+app.include_router(create_fastapi_router())
+```
+
+### Flask
+
+```python
+from flask import Flask
+from debug_agent.middleware import create_flask_blueprint
+app = Flask(__name__)
+app.register_blueprint(create_flask_blueprint())
+```
+
+### Any ASGI App (Starlette Mount)
+
+```python
+from starlette.routing import Mount
+from debug_agent.middleware import create_starlette_app
+routes = [Mount("/agent", app=create_starlette_app())]
+```
+
+## Built-in Tools (18+)
+
+| Tool | Description |
+|------|-------------|
+| `get_gc_stats` | GC collection counts per generation |
+| `get_memory_summary` | RSS, object counts, top types |
+| `trigger_gc` | Force GC and show before/after |
+| `get_thread_summary` | Thread count, names, daemon status |
+| `get_thread_dump` | Stack traces for all threads |
+| `get_runtime_info` | Python version, platform, PID |
+| `get_memory_allocations` | tracemalloc top allocations |
+| `get_routes` | List all web routes/endpoints |
+| `get_middleware` | List registered middleware |
+| `get_installed_packages` | Installed pip packages |
+| `get_environment_variables` | Environment variables (masked secrets) |
+| `get_recent_requests` | HTTP request ring buffer |
+| `get_slow_requests` | Slowest requests sorted by duration |
+| `get_error_requests` | Error requests (4xx/5xx) |
+| `get_request_stats` | P50/P95/P99 latency, error rate |
+| `get_process_info` | PID, CPU time, container detection |
+| `get_system_info` | OS, CPU cores, load average |
+| `get_disk_usage` | Disk usage for working directory |
+
+## Custom Tools
+
+```python
+from debug_agent import debug_tool, ToolParam
+
+@debug_tool("check_db_pool", "Check database connection pool stats")
+def check_db_pool() -> dict:
+    return {"active": 5, "idle": 10, "max": 20}
+```
+
+That's it. The tool is auto-discovered and made available to the LLM.
+
+## Configuration
+
+| Env Var | Default | Description |
+|---------|---------|-------------|
+| `DEBUG_AGENT_ENABLED` | `true` | Enable/disable |
+| `DEBUG_AGENT_BASE_PATH` | `/agent` | URL path |
+| `LLM_BASE_URL` | `https://api.openai.com/v1` | LLM endpoint |
+| `LLM_API_KEY` | (required) | API key |
+| `LLM_MODEL` | `gpt-4o` | Model name |
+| `LLM_TEMPERATURE` | `0.3` | Sampling temp |
+| `LLM_MAX_TOOL_ROUNDS` | `10` | Max tool rounds |
+
+## Run the Demo
+
+```bash
+pip install -e ".[dev]"
+export LLM_API_KEY=your-key
+python demo/app.py
+# Open http://localhost:8000/agent
+```
+
+## License
+
+MIT

debug_agent_py-0.2.1/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "debug-agent-py"
+version = "0.2.1"
+description = "AI-powered runtime debugging agent for Python web applications"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "ggcode", email = "noreply@ggcode.dev"}
+]
+keywords = ["debug", "debugging", "ai", "llm", "runtime", "diagnostics", "flask", "fastapi", "django", "agent", "observability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100", "starlette>=0.27", "uvicorn>=0.23"]
+flask = ["flask>=2.3"]
+django = ["django>=4.2"]
+dev = ["fastapi", "uvicorn", "flask", "pytest"]
+
+[project.urls]
+Homepage = "https://github.com/topcheer/python-debug-agent"
+Repository = "https://github.com/topcheer/python-debug-agent"
+Issues = "https://github.com/topcheer/python-debug-agent/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

debug_agent_py-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

debug_agent_py-0.2.1/src/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_py-0.2.1/src/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_py-0.2.1/src/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_py-0.2.1/src/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