debug-agent-py 0.2.2__tar.gz → 0.3.0__tar.gz

{debug_agent_py-0.2.2 → debug_agent_py-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: debug-agent-py
-Version: 0.2.2
+Version: 0.3.0
 Summary: AI-powered runtime debugging agent for Python web applications
 Author-email: ggcode <noreply@ggcode.dev>
 License: MIT
@@ -29,6 +29,20 @@ Provides-Extra: flask
 Requires-Dist: flask>=2.3; extra == "flask"
 Provides-Extra: django
 Requires-Dist: django>=4.2; extra == "django"
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy>=2.0; extra == "sqlalchemy"
+Requires-Dist: flask-sqlalchemy>=3.0; extra == "sqlalchemy"
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == "redis"
+Provides-Extra: celery
+Requires-Dist: celery>=5.3; extra == "celery"
+Provides-Extra: demo
+Requires-Dist: flask>=2.3; extra == "demo"
+Requires-Dist: sqlalchemy>=2.0; extra == "demo"
+Requires-Dist: flask-sqlalchemy>=3.0; extra == "demo"
+Requires-Dist: redis>=5.0; extra == "demo"
+Requires-Dist: celery>=5.3; extra == "demo"
+Requires-Dist: gunicorn>=21.2; extra == "demo"
 Provides-Extra: dev
 Requires-Dist: fastapi; extra == "dev"
 Requires-Dist: uvicorn; extra == "dev"
@@ -37,7 +51,11 @@ 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, GC, modules, database connections, routes, HTTP requests, and more.
+[![debug-agent-py](https://img.shields.io/pypi/v/debug-agent-py.svg)](https://pypi.org/project/debug-agent-py/)
+![Tools](https://img.shields.io/badge/tools-51-blue)
+![Inspectors](https://img.shields.io/badge/inspectors-16-green)
+
+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, GC, modules, database connections, Redis, Django models/URLs, Celery tasks, Flask extensions, Jinja2 templates, signals, routes, HTTP requests, and more — **51 diagnostic tools across 16 inspectors**.
 
 ## Quick Start
 
@@ -81,10 +99,11 @@ http://localhost:8000/agent
 - **Context compression** — automatically summarizes old conversation when token limit is approached
 - **Dark-themed chat UI** with full markdown rendering (tables, code blocks, lists)
 - **Max tool rounds** (25) with forced final summary when limit is reached
-- **34 diagnostic tools** across 10 inspectors
+- **51 diagnostic tools** across **16 inspectors**
 - Works with Flask, FastAPI, and Django
+- Zero external dependencies (no Datadog, no Grafana, no APM)
 
-## Inspectors & Tools (34)
+## Inspectors & Tools (51)
 
 ### Memory Inspector
 | Tool | Description |
@@ -101,12 +120,14 @@ http://localhost:8000/agent
 | `get_thread_info` | List all threads with name, daemon, alive status |
 | `get_thread_count` | Active thread count |
 | `get_thread_summary` | Thread state distribution |
+| `get_thread_stacks` | Current frame/stack for all threads |
 
 ### Database Inspector
 | Tool | Description |
 |------|-------------|
 | `get_sqlalchemy_engines` | Find SQLAlchemy engines and pool status |
 | `get_db_connections` | Inspect database connection pools |
+| `get_db_pool_config` | Pool configuration: size, timeout, recycle settings |
 
 ### Modules Inspector
 | Tool | Description |
@@ -120,6 +141,7 @@ http://localhost:8000/agent
 |------|-------------|
 | `get_async_tasks` | List pending asyncio tasks |
 | `get_event_loop_info` | Event loop details: type, running state |
+| `get_pending_callbacks` | List scheduled callbacks on the event loop |
 
 ### Runtime Inspector
 | Tool | Description |
@@ -127,13 +149,14 @@ http://localhost:8000/agent
 | `get_memory_info` | Process memory info (RSS, VMS, shared) |
 | `get_cpu_usage` | CPU usage percentage |
 | `get_python_info` | Python version, implementation, executable path |
+| `get_open_fds` | Open file descriptor count and limits |
 
 ### System Inspector
 | Tool | Description |
 |------|-------------|
 | `get_system_info` | Hostname, platform, CPU cores, disk |
 | `get_environment_variables` | Environment variables (masked secrets) |
-| `get_disk_usage` | Disk usage for working directory |
+| `get_disk_usage` | Disk usage for the working directory |
 
 ### Framework Inspector
 | Tool | Description |
@@ -149,6 +172,54 @@ http://localhost:8000/agent
 | `get_error_requests` | Error requests (4xx/5xx) |
 | `get_request_stats` | P50/P95/P99 latency, error rate |
 
+### Redis Inspector
+| Tool | Description |
+|------|-------------|
+| `get_redis_info` | Redis server info: memory, clients, persistence |
+| `get_redis_keys` | Scan Redis keyspace with pattern matching |
+| `get_redis_config` | Redis runtime configuration (CONFIG GET) |
+| `get_redis_slowlog` | Redis slow query log entries |
+
+### Django Inspector
+| Tool | Description |
+|------|-------------|
+| `get_django_models` | List Django models with app label, table name, field count |
+| `get_django_urls` | List all URL patterns with view names and namespaces |
+| `get_django_settings` | Key Django settings (DBs, INSTALLED_APPS, MIDDLEWARE) |
+| `get_django_migrations` | Migration status per app: applied vs pending |
+
+### Celery Inspector
+| Tool | Description |
+|------|-------------|
+| `get_celery_tasks` | List registered Celery tasks with routing info |
+| `get_celery_workers` | Active Celery workers with pool and concurrency |
+| `get_celery_queues` | Queue depth and message stats per queue |
+
+### Flask Extensions Inspector
+| Tool | Description |
+|------|-------------|
+| `get_flask_extensions` | List registered Flask extensions and their bindings |
+| `get_flask_blueprints` | List Flask blueprints with URL prefixes and routes |
+| `get_flask_config` | Flask configuration object values (secrets masked) |
+
+### Jinja2 Inspector
+| Tool | Description |
+|------|-------------|
+| `get_jinja_templates` | List loaded Jinja2 templates with loader paths |
+| `get_jinja_filters` | List registered Jinja2 filters, tests, and globals |
+
+### Signals Inspector
+| Tool | Description |
+|------|-------------|
+| `get_signal_handlers` | List Python signal handlers registered via signal module |
+| `get_django_signals` | List Django signal receivers connected to senders |
+
+### WSGI/ASGI Inspector
+| Tool | Description |
+|------|-------------|
+| `get_wsgi_info` | WSGI server details (Gunicorn/uWSGI workers, config) |
+| `get_asgi_apps` | List ASGI application scope and middleware chain |
+
 ## Custom Tools
 
 ```python
@@ -171,6 +242,26 @@ def check_redis():
 
 ## Run the Demo
 
+The demo uses **Flask** + **redis-py** + **SQLAlchemy** + **Celery**. Start Redis with Docker Compose first:
+
+### Docker Compose
+
+```yaml
+# docker-compose.yml
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    command: redis-server --save 60 1 --loglevel warning
+```
+
+```bash
+docker compose up -d
+```
+
+### Start the app
+
 ```bash
 export LLM_API_KEY=your-key
 cd demo && python app.py

{debug_agent_py-0.2.2 → debug_agent_py-0.3.0}/README.md

@@ -1,6 +1,10 @@
 # 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, GC, modules, database connections, routes, HTTP requests, and more.
+[![debug-agent-py](https://img.shields.io/pypi/v/debug-agent-py.svg)](https://pypi.org/project/debug-agent-py/)
+![Tools](https://img.shields.io/badge/tools-51-blue)
+![Inspectors](https://img.shields.io/badge/inspectors-16-green)
+
+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, GC, modules, database connections, Redis, Django models/URLs, Celery tasks, Flask extensions, Jinja2 templates, signals, routes, HTTP requests, and more — **51 diagnostic tools across 16 inspectors**.
 
 ## Quick Start
 
@@ -44,10 +48,11 @@ http://localhost:8000/agent
 - **Context compression** — automatically summarizes old conversation when token limit is approached
 - **Dark-themed chat UI** with full markdown rendering (tables, code blocks, lists)
 - **Max tool rounds** (25) with forced final summary when limit is reached
-- **34 diagnostic tools** across 10 inspectors
+- **51 diagnostic tools** across **16 inspectors**
 - Works with Flask, FastAPI, and Django
+- Zero external dependencies (no Datadog, no Grafana, no APM)
 
-## Inspectors & Tools (34)
+## Inspectors & Tools (51)
 
 ### Memory Inspector
 | Tool | Description |
@@ -64,12 +69,14 @@ http://localhost:8000/agent
 | `get_thread_info` | List all threads with name, daemon, alive status |
 | `get_thread_count` | Active thread count |
 | `get_thread_summary` | Thread state distribution |
+| `get_thread_stacks` | Current frame/stack for all threads |
 
 ### Database Inspector
 | Tool | Description |
 |------|-------------|
 | `get_sqlalchemy_engines` | Find SQLAlchemy engines and pool status |
 | `get_db_connections` | Inspect database connection pools |
+| `get_db_pool_config` | Pool configuration: size, timeout, recycle settings |
 
 ### Modules Inspector
 | Tool | Description |
@@ -83,6 +90,7 @@ http://localhost:8000/agent
 |------|-------------|
 | `get_async_tasks` | List pending asyncio tasks |
 | `get_event_loop_info` | Event loop details: type, running state |
+| `get_pending_callbacks` | List scheduled callbacks on the event loop |
 
 ### Runtime Inspector
 | Tool | Description |
@@ -90,13 +98,14 @@ http://localhost:8000/agent
 | `get_memory_info` | Process memory info (RSS, VMS, shared) |
 | `get_cpu_usage` | CPU usage percentage |
 | `get_python_info` | Python version, implementation, executable path |
+| `get_open_fds` | Open file descriptor count and limits |
 
 ### System Inspector
 | Tool | Description |
 |------|-------------|
 | `get_system_info` | Hostname, platform, CPU cores, disk |
 | `get_environment_variables` | Environment variables (masked secrets) |
-| `get_disk_usage` | Disk usage for working directory |
+| `get_disk_usage` | Disk usage for the working directory |
 
 ### Framework Inspector
 | Tool | Description |
@@ -112,6 +121,54 @@ http://localhost:8000/agent
 | `get_error_requests` | Error requests (4xx/5xx) |
 | `get_request_stats` | P50/P95/P99 latency, error rate |
 
+### Redis Inspector
+| Tool | Description |
+|------|-------------|
+| `get_redis_info` | Redis server info: memory, clients, persistence |
+| `get_redis_keys` | Scan Redis keyspace with pattern matching |
+| `get_redis_config` | Redis runtime configuration (CONFIG GET) |
+| `get_redis_slowlog` | Redis slow query log entries |
+
+### Django Inspector
+| Tool | Description |
+|------|-------------|
+| `get_django_models` | List Django models with app label, table name, field count |
+| `get_django_urls` | List all URL patterns with view names and namespaces |
+| `get_django_settings` | Key Django settings (DBs, INSTALLED_APPS, MIDDLEWARE) |
+| `get_django_migrations` | Migration status per app: applied vs pending |
+
+### Celery Inspector
+| Tool | Description |
+|------|-------------|
+| `get_celery_tasks` | List registered Celery tasks with routing info |
+| `get_celery_workers` | Active Celery workers with pool and concurrency |
+| `get_celery_queues` | Queue depth and message stats per queue |
+
+### Flask Extensions Inspector
+| Tool | Description |
+|------|-------------|
+| `get_flask_extensions` | List registered Flask extensions and their bindings |
+| `get_flask_blueprints` | List Flask blueprints with URL prefixes and routes |
+| `get_flask_config` | Flask configuration object values (secrets masked) |
+
+### Jinja2 Inspector
+| Tool | Description |
+|------|-------------|
+| `get_jinja_templates` | List loaded Jinja2 templates with loader paths |
+| `get_jinja_filters` | List registered Jinja2 filters, tests, and globals |
+
+### Signals Inspector
+| Tool | Description |
+|------|-------------|
+| `get_signal_handlers` | List Python signal handlers registered via signal module |
+| `get_django_signals` | List Django signal receivers connected to senders |
+
+### WSGI/ASGI Inspector
+| Tool | Description |
+|------|-------------|
+| `get_wsgi_info` | WSGI server details (Gunicorn/uWSGI workers, config) |
+| `get_asgi_apps` | List ASGI application scope and middleware chain |
+
 ## Custom Tools
 
 ```python
@@ -134,6 +191,26 @@ def check_redis():
 
 ## Run the Demo
 
+The demo uses **Flask** + **redis-py** + **SQLAlchemy** + **Celery**. Start Redis with Docker Compose first:
+
+### Docker Compose
+
+```yaml
+# docker-compose.yml
+services:
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    command: redis-server --save 60 1 --loglevel warning
+```
+
+```bash
+docker compose up -d
+```
+
+### Start the app
+
 ```bash
 export LLM_API_KEY=your-key
 cd demo && python app.py

{debug_agent_py-0.2.2 → debug_agent_py-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "debug-agent-py"
-version = "0.2.2"
+version = "0.3.0"
 description = "AI-powered runtime debugging agent for Python web applications"
 readme = "README.md"
 license = {text = "MIT"}
@@ -33,6 +33,10 @@ dependencies = [
 fastapi = ["fastapi>=0.100", "starlette>=0.27", "uvicorn>=0.23"]
 flask = ["flask>=2.3"]
 django = ["django>=4.2"]
+sqlalchemy = ["sqlalchemy>=2.0", "flask-sqlalchemy>=3.0"]
+redis = ["redis>=5.0"]
+celery = ["celery>=5.3"]
+demo = ["flask>=2.3", "sqlalchemy>=2.0", "flask-sqlalchemy>=3.0", "redis>=5.0", "celery>=5.3", "gunicorn>=21.2"]
 dev = ["fastapi", "uvicorn", "flask", "pytest"]
 
 [project.urls]

{debug_agent_py-0.2.2 → debug_agent_py-0.3.0}/src/debug_agent/inspectors/__init__.py

@@ -2,12 +2,18 @@
 
 from debug_agent.inspectors import (  # noqa: F401
     async_tasks,
+    celery,
     database,
+    django,
+    flask_ext,
     framework,
     http_tracker,
+    jinja2,
     memory,
     modules,
+    redis,
     runtime,
+    signals,
     system,
     threads,
 )

debug_agent_py-0.3.0/src/debug_agent/inspectors/celery.py

@@ -0,0 +1,231 @@
+"""Celery inspector: registered tasks, queue stats, and worker stats.
+
+Register a Celery app at runtime so the inspectors can reach it:
+
+    from debug_agent.inspectors.celery import register_celery_app
+    register_celery_app("default", celery_app)
+
+All tools degrade gracefully when Celery is not installed or no app is
+registered. Inspector calls (queue/worker stats) require a running broker.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from debug_agent.tool_registry import debug_tool, ToolParam
+
+
+# ─── Registration mechanism ──────────────────────────────────────────────────
+
+_registered_celery_apps: dict[str, Any] = {}
+
+
+def register_celery_app(name: str, app: Any) -> None:
+    """Register a Celery app under a name so the inspectors can find it."""
+    _registered_celery_apps[name] = app
+
+
+def _celery_available() -> bool:
+    try:
+        import celery  # noqa: F401
+        return True
+    except ImportError:
+        return False
+
+
+def _ensure_apps() -> dict[str, Any] | None:
+    if not _celery_available():
+        return None
+    return _registered_celery_apps
+
+
+# ─── Tools ───────────────────────────────────────────────────────────────────
+
+
+@debug_tool(
+    "get_celery_tasks",
+    "List registered Celery tasks (name, module, bound) for each registered Celery app",
+)
+def get_celery_tasks() -> dict:
+    apps = _ensure_apps()
+    if apps is None:
+        return {"error": "Celery is not installed"}
+
+    if not apps:
+        return {
+            "message": "No Celery apps registered. Call register_celery_app(name, app) to register one.",
+            "registered_count": 0,
+        }
+
+    result = []
+    for name, app in apps.items():
+        tasks: list[dict[str, Any]] = []
+        try:
+            task_iter = app.tasks.items()
+        except Exception as exc:
+            result.append({"name": name, "error": f"Could not enumerate tasks: {exc}"})
+            continue
+
+        for task_name, task in task_iter:
+            # Skip Celery's own internal tasks (celery.*) unless the user cares.
+            if task_name.startswith("celery."):
+                continue
+            tasks.append({
+                "name": task_name,
+                "module": getattr(getattr(task, "run", None), "__module__", None)
+                or getattr(task, "__module__", None),
+                "bound": bool(getattr(task, "bound", False)),
+            })
+
+        result.append({
+            "name": name,
+            "task_count": len(tasks),
+            "tasks": tasks,
+        })
+
+    return {"registered_count": len(apps), "apps": result}
+
+
+@debug_tool(
+    "get_celery_queues",
+    "Get Celery queue stats (active, reserved, scheduled counts per queue) via the inspector",
+)
+def get_celery_queues() -> dict:
+    apps = _ensure_apps()
+    if apps is None:
+        return {"error": "Celery is not installed"}
+
+    if not apps:
+        return {
+            "message": "No Celery apps registered. Call register_celery_app(name, app) to register one.",
+            "registered_count": 0,
+        }
+
+    result = []
+    for name, app in apps.items():
+        try:
+            inspect = app.control.inspect()
+        except Exception as exc:
+            result.append({"name": name, "error": f"Could not create inspector: {exc}"})
+            continue
+
+        active = _safe_inspect(inspect.active)
+        reserved = _safe_inspect(inspect.reserved)
+        scheduled = _safe_inspect(inspect.scheduled)
+
+        per_queue: dict[str, dict[str, int]] = {}
+        for payload_name, payload in (
+            ("active", active),
+            ("reserved", reserved),
+            ("scheduled", scheduled),
+        ):
+            if not isinstance(payload, dict):
+                continue
+            for _worker, entries in payload.items():
+                for entry in entries or []:
+                    delivery = entry.get("delivery") if isinstance(entry, dict) else None
+                    queue = None
+                    if isinstance(delivery, dict):
+                        queue = delivery.get("routing_key") or delivery.get("queue")
+                    queue = queue or "default"
+                    bucket = per_queue.setdefault(queue, {"active": 0, "reserved": 0, "scheduled": 0})
+                    bucket[payload_name] += 1
+
+        totals = {
+            "active": sum(v["active"] for v in per_queue.values()),
+            "reserved": sum(v["reserved"] for v in per_queue.values()),
+            "scheduled": sum(v["scheduled"] for v in per_queue.values()),
+        }
+
+        result.append({
+            "name": name,
+            "queue_count": len(per_queue),
+            "totals": totals,
+            "queues": per_queue,
+        })
+
+    return {"registered_count": len(apps), "apps": result}
+
+
+def _safe_inspect(func) -> Any:
+    """Call a celery inspect method, returning an error dict on failure."""
+    try:
+        return func()
+    except Exception as exc:
+        return {"_error": str(exc)}
+
+
+@debug_tool(
+    "get_celery_workers",
+    "Get Celery worker stats (active, processed, pool info) via the inspector",
+)
+def get_celery_workers() -> dict:
+    apps = _ensure_apps()
+    if apps is None:
+        return {"error": "Celery is not installed"}
+
+    if not apps:
+        return {
+            "message": "No Celery apps registered. Call register_celery_app(name, app) to register one.",
+            "registered_count": 0,
+        }
+
+    result = []
+    for name, app in apps.items():
+        try:
+            inspect = app.control.inspect()
+        except Exception as exc:
+            result.append({"name": name, "error": f"Could not create inspector: {exc}"})
+            continue
+
+        stats = _safe_inspect(inspect.stats)
+        active = _safe_inspect(inspect.active)
+        ping = _safe_inspect(inspect.ping)
+
+        workers: list[dict[str, Any]] = []
+        if isinstance(stats, dict):
+            for worker_name, worker_stats in stats.items():
+                pool = worker_stats.get("pool", {}) if isinstance(worker_stats, dict) else {}
+                broker = worker_stats.get("broker", {}) if isinstance(worker_stats, dict) else {}
+                rusage = worker_stats.get("rusage", {}) if isinstance(worker_stats, dict) else {}
+                active_list = active.get(worker_name, []) if isinstance(active, dict) else []
+                total_processed = 0
+                if isinstance(worker_stats, dict):
+                    total_processed = sum(
+                        int(v) for v in (worker_stats.get("total", {}) or {}).values()
+                    )
+                workers.append({
+                    "worker": worker_name,
+                    "active_count": len(active_list) if isinstance(active_list, list) else 0,
+                    "processed_total": total_processed,
+                    "pool": {
+                        "implementation": pool.get("implementation") if isinstance(pool, dict) else None,
+                        "max_concurrency": pool.get("max-concurrency") if isinstance(pool, dict) else None,
+                        "processes": pool.get("processes") if isinstance(pool, dict) else None,
+                    },
+                    "broker": {
+                        "transport": broker.get("transport") if isinstance(broker, dict) else None,
+                        "name": broker.get("name") if isinstance(broker, dict) else None,
+                    },
+                    "uptime": worker_stats.get("uptime") if isinstance(worker_stats, dict) else None,
+                    "rusage": _summarise_rusage(rusage),
+                })
+
+        reachable = list(ping.keys()) if isinstance(ping, dict) else []
+
+        result.append({
+            "name": name,
+            "worker_count": len(workers),
+            "reachable_workers": reachable,
+            "workers": workers,
+        })
+
+    return {"registered_count": len(apps), "apps": result}
+
+
+def _summarise_rusage(rusage: Any) -> dict[str, Any]:
+    if not isinstance(rusage, dict):
+        return {}
+    keys = ("utime", "stime", "maxrss", "idrss", "isrss", "ixrss", "minflt", "majflt", "nvcsw", "nivcsw")
+    return {k: rusage.get(k) for k in keys if k in rusage}