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

debug_agent/inspectors/database.py

@@ -0,0 +1,129 @@
+"""Database inspector: SQLAlchemy engines, connection pools."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from debug_agent.tool_registry import debug_tool, ToolParam
+
+
+def _find_sqlalchemy_engines() -> list:
+    """Find SQLAlchemy Engine instances in loaded modules."""
+    engines = []
+    seen_ids = set()
+
+    # Try to find via SQLAlchemy's own registries first
+    try:
+        from sqlalchemy import inspect as sa_inspect
+        from sqlalchemy.engine import Engine
+    except ImportError:
+        return engines
+
+    for mod in list(sys.modules.values()):
+        if mod is None or mod.__name__.startswith("debug_agent"):
+            continue
+        for attr_name in dir(mod):
+            if attr_name.startswith("_"):
+                continue
+            try:
+                obj = getattr(mod, attr_name)
+                if isinstance(obj, Engine) and id(obj) not in seen_ids:
+                    seen_ids.add(id(obj))
+                    engines.append(obj)
+            except Exception:
+                continue
+
+    return engines
+
+
+@debug_tool(
+    "get_sqlalchemy_engines",
+    "Find SQLAlchemy engines and their connection pool status",
+)
+def get_sqlalchemy_engines() -> dict:
+    try:
+        from sqlalchemy import create_engine, inspect as sa_inspect
+        from sqlalchemy.pool import QueuePool, NullPool, StaticPool
+    except ImportError:
+        return {"error": "SQLAlchemy is not installed"}
+
+    engines = _find_sqlalchemy_engines()
+    if not engines:
+        return {"message": "No SQLAlchemy engines found in loaded modules"}
+
+    result = []
+    for engine in engines:
+        pool = engine.pool
+        pool_info: dict = {
+            "pool_type": type(pool).__name__,
+        }
+
+        if isinstance(pool, QueuePool):
+            pool_info["size"] = pool.size()
+            pool_info["checked_in"] = pool.checkedin()
+            pool_info["checked_out"] = pool.checkedout()
+            pool_info["overflow"] = pool.overflow()
+            pool_info["checked_out_total"] = pool.status()
+
+        url = str(engine.url)
+        # Mask password in URL
+        if "" in url:
+            parts = url.split("@")
+            if len(parts) >= 2:
+                cred = parts[0].split(":")
+                if len(cred) >= 3:
+                    cred[-1] = "***"
+                    parts[0] = ":".join(cred)
+                    url = "@".join(parts)
+
+        result.append({
+            "url": url,
+            "dialect": engine.dialect.name,
+            "driver": engine.driver,
+            "pool": pool_info,
+        })
+
+    return {"engine_count": len(result), "engines": result}
+
+
+@debug_tool(
+    "get_db_connections",
+    "Inspect database connection pools and active connections if available",
+)
+def get_db_connections() -> dict:
+    try:
+        from sqlalchemy.pool import QueuePool, SingletonThreadPool, StaticPool
+    except ImportError:
+        return {"error": "SQLAlchemy is not installed"}
+
+    engines = _find_sqlalchemy_engines()
+    if not engines:
+        return {"message": "No SQLAlchemy engines found"}
+
+    connections = []
+    for engine in engines:
+        pool = engine.pool
+        info: dict = {
+            "dialect": engine.dialect.name,
+            "pool_type": type(pool).__name__,
+        }
+
+        if hasattr(pool, "size"):
+            info["pool_size"] = pool.size()
+        if hasattr(pool, "checkedin"):
+            info["checked_in"] = pool.checkedin()
+        if hasattr(pool, "checkedout"):
+            info["checked_out"] = pool.checkedout()
+        if hasattr(pool, "overflow"):
+            info["overflow"] = pool.overflow()
+
+        # Try to get pool status string
+        try:
+            info["pool_status"] = pool.status()
+        except Exception:
+            pass
+
+        connections.append(info)
+
+    return {"total_engines": len(connections), "connection_pools": connections}

debug_agent/inspectors/framework.py

@@ -0,0 +1,133 @@
+"""Framework inspector: routes, middleware, dependency injection."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from debug_agent.tool_registry import debug_tool, ToolParam
+
+
+def _find_app():
+    """Find the main web framework app instance."""
+    # Try FastAPI / Starlette
+    try:
+        import fastapi
+        for obj in _walk_module_objects():
+            if isinstance(obj, fastapi.FastAPI):
+                return ("fastapi", obj)
+    except ImportError:
+        pass
+
+    # Try Flask
+    try:
+        import flask
+        for obj in _walk_module_objects():
+            if isinstance(obj, flask.Flask):
+                return ("flask", obj)
+    except ImportError:
+        pass
+
+    return (None, None)
+
+
+def _walk_module_objects():
+    """Walk loaded modules looking for app instances."""
+    seen = set()
+    for mod in list(sys.modules.values()):
+        if mod is None or mod.__name__.startswith("debug_agent"):
+            continue
+        for attr_name in dir(mod):
+            if attr_name.startswith("_"):
+                continue
+            try:
+                obj = getattr(mod, attr_name)
+                if id(obj) not in seen:
+                    seen.add(id(obj))
+                    yield obj
+            except Exception:
+                continue
+
+
+@debug_tool("get_routes", "List all registered web routes/endpoints with methods and paths")
+def get_routes() -> dict:
+    ftype, app = _find_app()
+    if not app:
+        return {"error": "No supported web framework app found"}
+
+    routes = []
+    if ftype == "fastapi":
+        for route in app.routes:
+            if hasattr(route, "methods") and hasattr(route, "path"):
+                routes.append({
+                    "path": route.path,
+                    "methods": list(route.methods or set()),
+                    "name": getattr(route, "name", ""),
+                    "endpoint": getattr(route, "endpoint", "").__name__ if hasattr(getattr(route, "endpoint", ""), "__name__") else "",
+                })
+    elif ftype == "flask":
+        for rule in app.url_map.iter_rules():
+            routes.append({
+                "path": str(rule),
+                "methods": sorted(rule.methods - {"HEAD", "OPTIONS"}),
+                "endpoint": rule.endpoint,
+            })
+
+    return {"framework": ftype, "route_count": len(routes), "routes": routes}
+
+
+@debug_tool("get_middleware", "List registered middleware (FastAPI/Starlette/FastAPI)")
+def get_middleware() -> dict:
+    ftype, app = _find_app()
+    if not app:
+        return {"error": "No supported web framework app found"}
+
+    middlewares = []
+    if ftype == "fastapi":
+        try:
+            mw_stack = app.user_middleware
+            middlewares = [str(m) for m in mw_stack]
+        except Exception:
+            pass
+    elif ftype == "flask":
+        middlewares = []  # Flask doesn't have middleware in the same way
+
+    return {"framework": ftype, "middlewares": middlewares}
+
+
+@debug_tool("get_installed_packages", "List installed Python packages")
+def get_installed_packages(prefix: str = ToolParam("Filter by prefix (empty = all)", required=False)) -> dict:
+    try:
+        import pkg_resources
+        pkgs = sorted(
+            [(p.project_name, p.version) for p in pkg_resources.working_set],
+            key=lambda x: x[0].lower(),
+        )
+        if prefix:
+            pkgs = [(n, v) for n, v in pkgs if n.lower().startswith(prefix.lower())]
+        return {"total": len(pkgs), "packages": [{"name": n, "version": v} for n, v in pkgs]}
+    except ImportError:
+        from importlib.metadata import distributions
+        pkgs = sorted(
+            [(d.metadata["Name"], d.version) for d in distributions()],
+            key=lambda x: x[0].lower(),
+        )
+        if prefix:
+            pkgs = [(n, v) for n, v in pkgs if n.lower().startswith(prefix.lower())]
+        return {"total": len(pkgs), "packages": [{"name": n, "version": v} for n, v in pkgs]}
+
+
+@debug_tool("get_environment_variables", "List environment variables (filtered)")
+def get_environment_variables(prefix: str = ToolParam("Filter by prefix (e.g. 'PATH')", required=False)) -> dict:
+    import os
+    env = dict(os.environ)
+    if prefix:
+        env = {k: v for k, v in env.items() if k.upper().startswith(prefix.upper())}
+    # Mask potential secrets
+    masked = {}
+    for k, v in env.items():
+        if any(s in k.upper() for s in ["KEY", "SECRET", "PASSWORD", "TOKEN", "CREDENTIAL"]):
+            masked[k] = "***masked***"
+        else:
+            masked[k] = v
+    return {"variables": masked, "count": len(masked)}

debug_agent/inspectors/http_tracker.py

@@ -0,0 +1,93 @@
+"""HTTP request tracker: in-memory ring buffer for recent requests."""
+
+from __future__ import annotations
+
+import time
+import threading
+from collections import deque
+
+from debug_agent.tool_registry import debug_tool, ToolParam
+
+
+# Global ring buffer for request tracking
+_buffer_lock = threading.Lock()
+_request_buffer: deque = deque(maxlen=500)
+
+
+def record_request(method: str, path: str, status: int, duration_ms: float, client: str = ""):
+    """Record an HTTP request. Call this from your middleware."""
+    with _buffer_lock:
+        _request_buffer.append({
+            "timestamp": time.time(),
+            "method": method,
+            "path": path,
+            "status": status,
+            "duration_ms": round(duration_ms, 2),
+            "client": client,
+        })
+
+
+def _get_all() -> list[dict]:
+    with _buffer_lock:
+        return list(_request_buffer)
+
+
+@debug_tool("get_recent_requests", "Get recent HTTP requests from the in-memory ring buffer")
+def get_recent_requests(limit: int = ToolParam("Max results to return", required=False)) -> dict:
+    reqs = _get_all()
+    if limit:
+        reqs = reqs[-limit:]
+    return {"total": len(_request_buffer), "requests": list(reversed(reqs))}
+
+
+@debug_tool("get_slow_requests", "Get slowest HTTP requests sorted by duration")
+def get_slow_requests(threshold_ms: float = ToolParam("Minimum duration in ms", required=False)) -> dict:
+    reqs = _get_all()
+    if threshold_ms:
+        reqs = [r for r in reqs if r["duration_ms"] >= threshold_ms]
+    reqs.sort(key=lambda x: -x["duration_ms"])
+    return {"count": len(reqs), "requests": reqs[:20]}
+
+
+@debug_tool("get_error_requests", "Get all error requests (4xx/5xx status codes)")
+def get_error_requests() -> dict:
+    reqs = [r for r in _get_all() if r["status"] >= 400]
+    reqs.sort(key=lambda x: -x["duration_ms"])
+    return {"count": len(reqs), "requests": reqs}
+
+
+@debug_tool("get_request_stats", "Get HTTP request statistics: count, P50/P95/P99 latency, error rate")
+def get_request_stats() -> dict:
+    import math
+
+    reqs = _get_all()
+    if not reqs:
+        return {"message": "No requests recorded yet"}
+
+    durations = sorted([r["duration_ms"] for r in reqs])
+    n = len(durations)
+
+    def percentile(p: float) -> float:
+        idx = min(int(math.ceil(p * n)) - 1, n - 1)
+        return round(durations[idx], 2)
+
+    errors = sum(1 for r in reqs if r["status"] >= 400)
+
+    # Group by path
+    by_path: dict[str, int] = {}
+    for r in reqs:
+        by_path[r["path"]] = by_path.get(r["path"], 0) + 1
+
+    return {
+        "total_requests": n,
+        "error_count": errors,
+        "error_rate": f"{errors / n * 100:.1f}%",
+        "latency_ms": {
+            "min": durations[0],
+            "p50": percentile(0.5),
+            "p95": percentile(0.95),
+            "p99": percentile(0.99),
+            "max": durations[-1],
+        },
+        "top_paths": dict(sorted(by_path.items(), key=lambda x: -x[1])[:10]),
+    }

debug_agent/inspectors/memory.py

@@ -0,0 +1,117 @@
+"""Memory profiler inspector: tracemalloc, object counts, GC details, reference cycles."""
+
+from __future__ import annotations
+
+import gc
+import tracemalloc
+from collections import Counter
+from typing import Any
+
+from debug_agent.tool_registry import debug_tool, ToolParam
+
+
+@debug_tool(
+    "get_tracemalloc_stats",
+    "Get Python tracemalloc statistics: top allocations by file/line, traced memory",
+)
+def get_tracemalloc_stats(limit: int = ToolParam("Max number of top allocations to return", required=False)) -> dict:
+    if not tracemalloc.is_tracing():
+        try:
+            tracemalloc.start(10)
+        except RuntimeError:
+            return {"error": "tracemalloc could not be started"}
+
+    snapshot = tracemalloc.take_snapshot()
+    top = snapshot.statistics("lineno")
+    current, peak = tracemalloc.get_traced_memory()
+
+    allocations = []
+    n = limit if limit and limit > 0 else 20
+    for stat in top[:n]:
+        frame = stat.traceback[0]
+        allocations.append({
+            "file": frame.filename,
+            "line": frame.lineno,
+            "size_kb": round(stat.size / 1024, 2),
+            "count": stat.count,
+        })
+
+    return {
+        "traced_memory_mb": round(current / 1024 / 1024, 2),
+        "peak_memory_mb": round(peak / 1024 / 1024, 2),
+        "top_allocations": allocations,
+        "total_traced_blocks": sum(s.count for s in top),
+    }
+
+
+@debug_tool(
+    "get_object_counts",
+    "Count live Python objects by type via gc.get_objects() summary",
+)
+def get_object_counts(limit: int = ToolParam("Max number of type entries to return", required=False)) -> dict:
+    all_objects = gc.get_objects()
+    type_counter: Counter = Counter()
+    for obj in all_objects:
+        type_counter[type(obj).__name__] += 1
+
+    n = limit if limit and limit > 0 else 20
+    top_types = type_counter.most_common(n)
+    return {
+        "total_objects": len(all_objects),
+        "unique_types": len(type_counter),
+        "top_types": {t: c for t, c in top_types},
+    }
+
+
+@debug_tool(
+    "get_gc_stats",
+    "Get garbage collector statistics: collections, collected, and uncollectable counts per generation",
+)
+def get_gc_stats() -> dict:
+    stats = gc.get_stats()
+    threshold = gc.get_threshold()
+    return {
+        "generations": [
+            {
+                "generation": i,
+                "collections": s["collections"],
+                "collected": s["collected"],
+                "uncollectable": s["uncollectable"],
+            }
+            for i, s in enumerate(stats)
+        ],
+        "thresholds": {"gen0": threshold[0], "gen1": threshold[1], "gen2": threshold[2]},
+        "current_counts": {"gen0": gc.get_count()[0], "gen1": gc.get_count()[1], "gen2": gc.get_count()[2]},
+        "garbage_list_size": len(gc.garbage),
+        "debug_flags": gc.get_debug(),
+    }
+
+
+@debug_tool(
+    "get_ref_cycles",
+    "Count reference cycles detected by the garbage collector",
+)
+def get_ref_cycles() -> dict:
+    # Save current debug flags
+    old_flags = gc.get_debug()
+    gc.set_debug(gc.DEBUG_SAVEALL)
+
+    before = len(gc.get_objects())
+    collected = gc.collect()
+    after = len(gc.get_objects())
+
+    # Analyze what was collected (stored in gc.garbage when DEBUG_SAVEALL)
+    cycle_types: Counter = Counter()
+    for obj in gc.garbage:
+        cycle_types[type(obj).__name__] += 1
+
+    # Restore
+    gc.set_debug(old_flags)
+    gc.garbage.clear()
+
+    return {
+        "objects_collected": collected,
+        "objects_freed": before - after,
+        "reference_cycle_types": dict(cycle_types.most_common(15)),
+        "total_cycles_found": sum(cycle_types.values()),
+    }

debug_agent/inspectors/modules.py

@@ -0,0 +1,129 @@
+"""Module inspector: loaded modules, import stats, module details."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+from debug_agent.tool_registry import debug_tool, ToolParam
+
+
+@debug_tool(
+    "get_loaded_modules",
+    "List loaded Python modules (sys.modules) with their versions",
+)
+def get_loaded_modules(prefix: str = ToolParam("Filter by module name prefix (empty = all)", required=False)) -> dict:
+    results = []
+    for name in sorted(sys.modules.keys()):
+        if prefix and not name.lower().startswith(prefix.lower()):
+            continue
+        mod = sys.modules.get(name)
+        if mod is None:
+            results.append({"name": name, "version": None, "loaded": False})
+            continue
+
+        version = getattr(mod, "__version__", None)
+        if not version:
+            # Try importlib.metadata for installed packages
+            try:
+                from importlib.metadata import version as get_version
+                # Handle submodules by taking the top-level package
+                top_pkg = name.split(".")[0]
+                version = get_version(top_pkg)
+            except Exception:
+                version = None
+
+        results.append({"name": name, "version": version, "file": getattr(mod, "__file__", None)})
+
+    return {"total": len(results), "modules": results}
+
+
+@debug_tool(
+    "get_import_stats",
+    "Get module import statistics: total count, largest modules by file size",
+)
+def get_import_stats() -> dict:
+    import os
+
+    module_sizes = []
+    total = 0
+    builtin_count = 0
+
+    for name, mod in sys.modules.items():
+        if mod is None:
+            continue
+        total += 1
+        filepath = getattr(mod, "__file__", None)
+        if filepath and os.path.isfile(filepath):
+            try:
+                size = os.path.getsize(filepath)
+                module_sizes.append((name, size, filepath))
+            except OSError:
+                pass
+        else:
+            builtin_count += 1
+
+    module_sizes.sort(key=lambda x: -x[1])
+    largest = [
+        {"name": name, "size_kb": round(size / 1024, 2), "file": filepath}
+        for name, size, filepath in module_sizes[:20]
+    ]
+
+    return {
+        "total_modules": total,
+        "builtin_or_builtin_like": builtin_count,
+        "with_file_path": len(module_sizes),
+        "largest_modules": largest,
+    }
+
+
+@debug_tool(
+    "get_module_detail",
+    "Get detailed information about a specific loaded module",
+)
+def get_module_detail(module_name: str = ToolParam("The module name to inspect (e.g. 'flask', 'debug_agent.engine')")) -> dict:
+    mod = sys.modules.get(module_name)
+    if mod is None:
+        return {"error": f"Module '{module_name}' is not loaded"}
+
+    import os
+    filepath = getattr(mod, "__file__", None)
+    file_size = None
+    if filepath and os.path.isfile(filepath):
+        try:
+            file_size = os.path.getsize(filepath)
+        except OSError:
+            pass
+
+    version = getattr(mod, "__version__", None)
+    if not version:
+        try:
+            from importlib.metadata import version as get_version
+            version = get_version(module_name.split(".")[0])
+        except Exception:
+            pass
+
+    # Get public attributes
+    public_attrs = []
+    for attr in sorted(dir(mod)):
+        if attr.startswith("_"):
+            continue
+        try:
+            obj = getattr(mod, attr)
+            public_attrs.append({
+                "name": attr,
+                "type": type(obj).__name__,
+            })
+        except Exception:
+            continue
+
+    return {
+        "name": module_name,
+        "file": filepath,
+        "file_size_bytes": file_size,
+        "version": version,
+        "package": getattr(mod, "__package__", None),
+        "spec": str(getattr(mod, "__spec__", None)),
+        "public_attribute_count": len(public_attrs),
+        "public_attributes": public_attrs[:50],
+    }