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

debug_agent_py-0.3.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: debug-agent-py
+Version: 0.3.0
+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: 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"
+Requires-Dist: flask; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# Python Debug Agent
+
+[![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
+
+### 1. Install
+
+```bash
+pip install debug-agent-py
+```
+
+### 2. Integrate (Flask)
+
+```python
+from flask import Flask
+from debug_agent import setup_debug_agent
+
+app = Flask(__name__)
+
+# One line to integrate
+setup_debug_agent(app)
+```
+
+### 3. Configure LLM
+
+```bash
+export LLM_API_KEY=your-key
+export LLM_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4  # default
+export LLM_MODEL=glm-5.2                                          # default
+```
+
+Supports any OpenAI-compatible endpoint.
+
+### 4. Run and open
+
+```
+http://localhost:8000/agent
+```
+
+## Features
+
+- **Streaming AI responses** with real-time tool call badges (pending / success / error)
+- **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
+- **51 diagnostic tools** across **16 inspectors**
+- Works with Flask, FastAPI, and Django
+- Zero external dependencies (no Datadog, no Grafana, no APM)
+
+## Inspectors & Tools (51)
+
+### Memory Inspector
+| Tool | Description |
+|------|-------------|
+| `get_tracemalloc_stats` | Python tracemalloc top allocations by file/line |
+| `get_object_counts` | Count objects by type via gc |
+| `get_gc_stats` | gc.get_stats() generation details |
+| `get_ref_cycles` | Count reference cycles detected by gc |
+| `trigger_gc` | Force garbage collection |
+
+### Threads Inspector
+| Tool | Description |
+|------|-------------|
+| `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 |
+|------|-------------|
+| `get_loaded_modules` | List loaded Python modules (sys.modules) with versions |
+| `get_module_count` | Total loaded module count |
+| `get_installed_packages` | List installed packages from pip |
+
+### Async Tasks Inspector
+| Tool | Description |
+|------|-------------|
+| `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 |
+|------|-------------|
+| `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 the working directory |
+
+### Framework Inspector
+| Tool | Description |
+|------|-------------|
+| `get_routes` | List all registered web routes/endpoints |
+| `get_middleware` | List registered middleware |
+
+### HTTP Tracker Inspector
+| Tool | Description |
+|------|-------------|
+| `get_recent_requests` | Recent HTTP requests ring buffer |
+| `get_slow_requests` | Slowest requests by duration |
+| `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
+from debug_agent import debug_tool
+
+@debug_tool('check_redis', 'Check Redis connection')
+def check_redis():
+    return {'connected': True}
+```
+
+## Configuration
+
+| Env Var | Default | Description |
+|---------|---------|-------------|
+| `LLM_BASE_URL` | `https://open.bigmodel.cn/api/coding/paas/v4` | LLM endpoint |
+| `LLM_API_KEY` | (required) | API key |
+| `LLM_MODEL` | `glm-5.2` | Model name |
+| `LLM_MAX_TOOL_ROUNDS` | `25` | Max tool-calling rounds |
+| `LLM_CONTEXT_WINDOW_TOKENS` | `100000` | Context window size |
+
+## 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
+# Open http://localhost:8000/agent
+```
+
+## PyPI
+
+[![debug-agent-py](https://img.shields.io/pypi/v/debug-agent-py.svg)](https://pypi.org/project/debug-agent-py/)
+
+## License
+
+MIT

debug_agent_py-0.3.0/README.md

@@ -0,0 +1,226 @@
+# Python Debug Agent
+
+[![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
+
+### 1. Install
+
+```bash
+pip install debug-agent-py
+```
+
+### 2. Integrate (Flask)
+
+```python
+from flask import Flask
+from debug_agent import setup_debug_agent
+
+app = Flask(__name__)
+
+# One line to integrate
+setup_debug_agent(app)
+```
+
+### 3. Configure LLM
+
+```bash
+export LLM_API_KEY=your-key
+export LLM_BASE_URL=https://open.bigmodel.cn/api/coding/paas/v4  # default
+export LLM_MODEL=glm-5.2                                          # default
+```
+
+Supports any OpenAI-compatible endpoint.
+
+### 4. Run and open
+
+```
+http://localhost:8000/agent
+```
+
+## Features
+
+- **Streaming AI responses** with real-time tool call badges (pending / success / error)
+- **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
+- **51 diagnostic tools** across **16 inspectors**
+- Works with Flask, FastAPI, and Django
+- Zero external dependencies (no Datadog, no Grafana, no APM)
+
+## Inspectors & Tools (51)
+
+### Memory Inspector
+| Tool | Description |
+|------|-------------|
+| `get_tracemalloc_stats` | Python tracemalloc top allocations by file/line |
+| `get_object_counts` | Count objects by type via gc |
+| `get_gc_stats` | gc.get_stats() generation details |
+| `get_ref_cycles` | Count reference cycles detected by gc |
+| `trigger_gc` | Force garbage collection |
+
+### Threads Inspector
+| Tool | Description |
+|------|-------------|
+| `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 |
+|------|-------------|
+| `get_loaded_modules` | List loaded Python modules (sys.modules) with versions |
+| `get_module_count` | Total loaded module count |
+| `get_installed_packages` | List installed packages from pip |
+
+### Async Tasks Inspector
+| Tool | Description |
+|------|-------------|
+| `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 |
+|------|-------------|
+| `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 the working directory |
+
+### Framework Inspector
+| Tool | Description |
+|------|-------------|
+| `get_routes` | List all registered web routes/endpoints |
+| `get_middleware` | List registered middleware |
+
+### HTTP Tracker Inspector
+| Tool | Description |
+|------|-------------|
+| `get_recent_requests` | Recent HTTP requests ring buffer |
+| `get_slow_requests` | Slowest requests by duration |
+| `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
+from debug_agent import debug_tool
+
+@debug_tool('check_redis', 'Check Redis connection')
+def check_redis():
+    return {'connected': True}
+```
+
+## Configuration
+
+| Env Var | Default | Description |
+|---------|---------|-------------|
+| `LLM_BASE_URL` | `https://open.bigmodel.cn/api/coding/paas/v4` | LLM endpoint |
+| `LLM_API_KEY` | (required) | API key |
+| `LLM_MODEL` | `glm-5.2` | Model name |
+| `LLM_MAX_TOOL_ROUNDS` | `25` | Max tool-calling rounds |
+| `LLM_CONTEXT_WINDOW_TOKENS` | `100000` | Context window size |
+
+## 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
+# Open http://localhost:8000/agent
+```
+
+## PyPI
+
+[![debug-agent-py](https://img.shields.io/pypi/v/debug-agent-py.svg)](https://pypi.org/project/debug-agent-py/)
+
+## License
+
+MIT

{debug_agent_py-0.2.1 → 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.1"
+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.1 → 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,
 )