dea-agents 0.1.0__tar.gz

dea_agents-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+node_modules/
+dist/
+coverage/
+*.log
+.DS_Store
+examples/**/node_modules/
+examples/**/__pycache__/
+*.pcap
+*.heapsnapshot
+.vhs-out/
+.lab-dea/
+.lab-dea/
+python/dist/
+python/**/__pycache__/
+python/*.egg-info/

dea_agents-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shreyas Sawant and DEA contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dea_agents-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: dea-agents
+Version: 0.1.0
+Summary: Debug Anything from Python agents: observe running processes (strace, py-spy, perf, lsof, tcpdump, gdb/lldb, heap snapshots) and get evidence-backed findings. Wraps the DEA CLI/MCP server; tool adapters for LangChain, LlamaIndex and CrewAI.
+Project-URL: Homepage, https://github.com/shreyassaw5394/dea
+Project-URL: Documentation, https://github.com/shreyassaw5394/dea/tree/main/docs
+Project-URL: Issues, https://github.com/shreyassaw5394/dea/issues
+Author: Shreyas Sawant
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,crewai,debugging,langchain,llamaindex,mcp,observability,perf,profiling,py-spy,strace
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.30; extra == 'crewai'
+Requires-Dist: pydantic>=2; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == 'langchain'
+Requires-Dist: pydantic>=2; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == 'llamaindex'
+Description-Content-Type: text/markdown
+
+# dea-agents (Python)
+
+**Debug Anything from Python.** Observe a running process, container or pod —
+syscalls, CPU profiles, thread stacks, sockets, packets, heap retainers — and
+get findings that cite evidence. This package wraps the
+[DEA](https://github.com/shreyassaw5394/dea) CLI (Node ≥ 22 required:
+`npx -y dea-agents` is used automatically) and ships tool adapters for
+LangChain, LlamaIndex and CrewAI.
+
+```bash
+pip install dea-agents                 # core (no deps)
+pip install 'dea-agents[langchain]'    # + LangChain StructuredTools
+pip install 'dea-agents[llamaindex]'   # + LlamaIndex FunctionTools
+pip install 'dea-agents[crewai]'       # + CrewAI BaseTools
+```
+
+## Plain Python
+
+```python
+from dea_agents import DEA
+
+dea = DEA()                       # uses `dea` if installed, else `npx -y dea-agents@latest`
+print(dea.readiness()["findings"])
+s = dea.attach(12345)             # pid, "my-container", "ns/pod", or a command
+before = dea.snapshot_memory(s)
+# ... exercise the target ...
+after = dea.snapshot_memory(s)
+diff = dea.diff_runs(s, before["run_id"], after["run_id"])
+for line in DEA.findings(diff):
+    print(line)                   # [high] heap_retainer: name=Array grew 2.0 KB → 50.1 MB (observed; e4,e1)
+dea.report(s, out="report.md")
+dea.detach(s)
+```
+
+Every call returns the DEA `ToolResult` dict (`ok`, `findings`, `evidence`,
+`limitations`, `suggested_next`, `artifacts`). `capture_traffic` needs
+`consent=True` — ask your user first.
+
+## LangChain
+
+```python
+from dea_agents.langchain import dea_tools
+from langgraph.prebuilt import create_react_agent
+
+agent = create_react_agent(llm, dea_tools())
+agent.invoke({"messages": [("user", "pid 12345 is slow — attach and tell me why, with evidence")]})
+```
+
+## LlamaIndex
+
+```python
+from dea_agents.llamaindex import dea_tools
+from llama_index.core.agent import ReActAgent
+
+agent = ReActAgent.from_tools(dea_tools(), llm=llm, verbose=True)
+```
+
+## CrewAI
+
+```python
+from dea_agents.crewai import dea_tools
+from crewai import Agent
+
+sre = Agent(role="SRE", goal="Diagnose the hung worker with evidence, never guess", tools=dea_tools(), llm=llm)
+```
+
+## Or just use MCP
+
+Any framework with MCP support (LangChain `langchain-mcp-adapters`, LlamaIndex
+`McpToolSpec`, CrewAI `MCPServerAdapter`, Claude Code, Codex, Cursor…) can run
+DEA directly: `{"command": "npx", "args": ["-y", "dea-agents@latest", "serve"]}`.
+Same 14 tools, same ToolResult, plus the guided prompts.
+
+## Safety
+
+DEA is read-only, never runs sudo, caps every tool at 60 s, redacts secrets in
+what it returns, and keeps raw artifacts under `~/.dea/sessions/`. See
+[docs/safety.md](https://github.com/shreyassaw5394/dea/blob/main/docs/safety.md).
+MIT.

dea_agents-0.1.0/README.md

@@ -0,0 +1,79 @@
+# dea-agents (Python)
+
+**Debug Anything from Python.** Observe a running process, container or pod —
+syscalls, CPU profiles, thread stacks, sockets, packets, heap retainers — and
+get findings that cite evidence. This package wraps the
+[DEA](https://github.com/shreyassaw5394/dea) CLI (Node ≥ 22 required:
+`npx -y dea-agents` is used automatically) and ships tool adapters for
+LangChain, LlamaIndex and CrewAI.
+
+```bash
+pip install dea-agents                 # core (no deps)
+pip install 'dea-agents[langchain]'    # + LangChain StructuredTools
+pip install 'dea-agents[llamaindex]'   # + LlamaIndex FunctionTools
+pip install 'dea-agents[crewai]'       # + CrewAI BaseTools
+```
+
+## Plain Python
+
+```python
+from dea_agents import DEA
+
+dea = DEA()                       # uses `dea` if installed, else `npx -y dea-agents@latest`
+print(dea.readiness()["findings"])
+s = dea.attach(12345)             # pid, "my-container", "ns/pod", or a command
+before = dea.snapshot_memory(s)
+# ... exercise the target ...
+after = dea.snapshot_memory(s)
+diff = dea.diff_runs(s, before["run_id"], after["run_id"])
+for line in DEA.findings(diff):
+    print(line)                   # [high] heap_retainer: name=Array grew 2.0 KB → 50.1 MB (observed; e4,e1)
+dea.report(s, out="report.md")
+dea.detach(s)
+```
+
+Every call returns the DEA `ToolResult` dict (`ok`, `findings`, `evidence`,
+`limitations`, `suggested_next`, `artifacts`). `capture_traffic` needs
+`consent=True` — ask your user first.
+
+## LangChain
+
+```python
+from dea_agents.langchain import dea_tools
+from langgraph.prebuilt import create_react_agent
+
+agent = create_react_agent(llm, dea_tools())
+agent.invoke({"messages": [("user", "pid 12345 is slow — attach and tell me why, with evidence")]})
+```
+
+## LlamaIndex
+
+```python
+from dea_agents.llamaindex import dea_tools
+from llama_index.core.agent import ReActAgent
+
+agent = ReActAgent.from_tools(dea_tools(), llm=llm, verbose=True)
+```
+
+## CrewAI
+
+```python
+from dea_agents.crewai import dea_tools
+from crewai import Agent
+
+sre = Agent(role="SRE", goal="Diagnose the hung worker with evidence, never guess", tools=dea_tools(), llm=llm)
+```
+
+## Or just use MCP
+
+Any framework with MCP support (LangChain `langchain-mcp-adapters`, LlamaIndex
+`McpToolSpec`, CrewAI `MCPServerAdapter`, Claude Code, Codex, Cursor…) can run
+DEA directly: `{"command": "npx", "args": ["-y", "dea-agents@latest", "serve"]}`.
+Same 14 tools, same ToolResult, plus the guided prompts.
+
+## Safety
+
+DEA is read-only, never runs sudo, caps every tool at 60 s, redacts secrets in
+what it returns, and keeps raw artifacts under `~/.dea/sessions/`. See
+[docs/safety.md](https://github.com/shreyassaw5394/dea/blob/main/docs/safety.md).
+MIT.

dea_agents-0.1.0/dea_agents/__init__.py

@@ -0,0 +1,152 @@
+"""dea-agents — Debug Anything from Python.
+
+Thin, dependency-free wrapper around the DEA CLI (``npx -y dea-agents``). Every
+method returns the DEA ``ToolResult`` dict: ``findings`` cite ``evidence`` ids,
+``limitations`` say what could not be observed, ``artifacts`` point at raw
+files under ``~/.dea/sessions/<id>/``.
+
+    from dea_agents import DEA
+    dea = DEA()
+    s = dea.attach(12345)
+    print(dea.profile_cpu(s, duration_s=10)["findings"])
+    dea.detach(s)
+
+Framework adapters: ``dea_agents.langchain``, ``dea_agents.llamaindex``,
+``dea_agents.crewai``. Agents that speak MCP can skip this package and run
+``npx -y dea-agents serve`` directly.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from typing import Any, Dict, List, Optional, Sequence
+
+__version__ = "0.1.0"
+__all__ = ["DEA", "DEAError", "TOOLS", "ToolResult"]
+
+ToolResult = Dict[str, Any]
+
+TOOLS: Dict[str, str] = {
+    "readiness": "OS, arch, which providers are usable, what is missing and how to install it, permission status. Call first.",
+    "attach": "Resolve a target (pid, container, pod, or a command to spawn) and open a session. Returns session_id.",
+    "detach": "Stop captures, write the report, keep artifacts.",
+    "list_processes": "ps-style list (pid, comm, cpu, mem, user, container) with optional substring filter.",
+    "trace_syscalls": "Linux strace for N seconds: top syscalls by time/count, slowest calls, error counts, blocked waits.",
+    "profile_cpu": "CPU profile (py-spy / perf / sample): top frames, hottest stacks, flamegraph.svg artifact.",
+    "dump_stacks": "Every thread's stack; flags lock waits and likely deadlocks.",
+    "inspect_sockets": "Listening ports, connections by remote, CLOSE_WAIT/TIME_WAIT pileups, fd count vs ulimit.",
+    "inspect_files": "Open fds by type, fd growth over a window, largest and deleted-but-open files.",
+    "capture_traffic": "tcpdump scoped to the target's ports (needs consent=True): per-remote bytes, RSTs, retransmits, DNS.",
+    "snapshot_memory": "RSS series; Node heap snapshot with top retainers; Python stacks with locals.",
+    "diff_runs": "Diff two prior runs (e.g. snapshot_memory#1 vs #2): what grew, appeared, disappeared.",
+    "container_info": "docker inspect/stats/top/logs, cgroup limits, OOM kills, restarts.",
+    "report": "Markdown report of the whole session.",
+}
+
+
+class DEAError(RuntimeError):
+    """Raised when the DEA CLI cannot be executed at all (Node/npx missing, bad JSON)."""
+
+
+class DEA:
+    """Client for the DEA CLI.
+
+    Args:
+        command: how to invoke DEA. Defaults to ``["npx", "-y", "dea-agents@latest"]``;
+            pass ``["dea"]`` if installed globally. ``DEA_COMMAND`` env var (shell-split) overrides.
+        timeout: subprocess timeout in seconds (DEA itself caps tools at 60 s).
+        raise_on_error: raise ``DEAError`` when ``ok`` is false instead of returning the result.
+    """
+
+    def __init__(self, command: Optional[Sequence[str]] = None, timeout: float = 120.0, raise_on_error: bool = False) -> None:
+        env_cmd = os.environ.get("DEA_COMMAND")
+        if command is None and env_cmd:
+            command = env_cmd.split()
+        if command is None:
+            command = ["dea"] if shutil.which("dea") else ["npx", "-y", "dea-agents@latest"]
+        self.command: List[str] = list(command)
+        self.timeout = timeout
+        self.raise_on_error = raise_on_error
+
+    # -- core ---------------------------------------------------------------
+
+    def call(self, tool: str, **args: Any) -> ToolResult:
+        """Call any DEA tool by name. Returns the ToolResult dict."""
+        if tool not in TOOLS:
+            raise DEAError(f"unknown tool {tool!r}; known: {', '.join(TOOLS)}")
+        argv = [*self.command, "call", tool, json.dumps({k: v for k, v in args.items() if v is not None})]
+        try:
+            proc = subprocess.run(argv, capture_output=True, text=True, timeout=self.timeout, check=False)
+        except FileNotFoundError as e:
+            raise DEAError(f"cannot run {argv[0]!r}: install Node.js >= 22 (https://nodejs.org) or set DEA_COMMAND") from e
+        except subprocess.TimeoutExpired as e:
+            raise DEAError(f"{tool} timed out after {self.timeout}s") from e
+        out = proc.stdout.strip()
+        start = out.find("{")
+        if start < 0:
+            raise DEAError(f"DEA produced no JSON for {tool}: {proc.stderr.strip()[:500]}")
+        try:
+            result: ToolResult = json.loads(out[start:])
+        except json.JSONDecodeError as e:
+            raise DEAError(f"bad JSON from DEA for {tool}: {e}") from e
+        if self.raise_on_error and not result.get("ok", False):
+            raise DEAError(result.get("error") or f"{tool} failed")
+        return result
+
+    # -- convenience --------------------------------------------------------
+
+    def readiness(self) -> ToolResult:
+        return self.call("readiness")
+
+    def list_processes(self, filter: Optional[str] = None, limit: int = 100) -> ToolResult:
+        return self.call("list_processes", filter=filter, limit=limit)
+
+    def attach(self, target: Any, kind: Optional[str] = None) -> str:
+        """Attach and return the session_id. Raises DEAError if attach failed."""
+        r = self.call("attach", target=str(target), kind=kind)
+        if not r.get("ok"):
+            raise DEAError(r.get("error") or "attach failed")
+        return str(r["session_id"])
+
+    def detach(self, session_id: str) -> ToolResult:
+        return self.call("detach", session_id=session_id)
+
+    def trace_syscalls(self, session_id: str, duration_s: int = 10, categories: Optional[Sequence[str]] = None) -> ToolResult:
+        return self.call("trace_syscalls", session_id=session_id, duration_s=duration_s, categories=list(categories) if categories else None)
+
+    def profile_cpu(self, session_id: str, duration_s: int = 15) -> ToolResult:
+        return self.call("profile_cpu", session_id=session_id, duration_s=duration_s)
+
+    def dump_stacks(self, session_id: str) -> ToolResult:
+        return self.call("dump_stacks", session_id=session_id)
+
+    def inspect_sockets(self, session_id: str) -> ToolResult:
+        return self.call("inspect_sockets", session_id=session_id)
+
+    def inspect_files(self, session_id: str, window_s: int = 3) -> ToolResult:
+        return self.call("inspect_files", session_id=session_id, window_s=window_s)
+
+    def capture_traffic(self, session_id: str, duration_s: int = 10, filter: Optional[str] = None, consent: bool = False) -> ToolResult:
+        """Requires consent=True — ask the user first; captures can contain secrets."""
+        return self.call("capture_traffic", session_id=session_id, duration_s=duration_s, filter=filter, consent=consent)
+
+    def snapshot_memory(self, session_id: str, heap: bool = True, window_s: int = 3) -> ToolResult:
+        return self.call("snapshot_memory", session_id=session_id, heap=heap, window_s=window_s)
+
+    def diff_runs(self, session_id: str, a: str, b: str) -> ToolResult:
+        return self.call("diff_runs", session_id=session_id, a=a, b=b)
+
+    def container_info(self, session_id: str) -> ToolResult:
+        return self.call("container_info", session_id=session_id)
+
+    def report(self, session_id: str, out: Optional[str] = None) -> ToolResult:
+        return self.call("report", session_id=session_id, out=out)
+
+    # -- helpers ------------------------------------------------------------
+
+    @staticmethod
+    def findings(result: ToolResult) -> List[str]:
+        """Human-readable finding lines with their evidence ids."""
+        return [f"[{f['severity']}] {f['summary']} ({f['confidence']}; {','.join(f['evidence_ids'])})" for f in result.get("findings", [])]

dea_agents-0.1.0/dea_agents/_specs.py

@@ -0,0 +1,41 @@
+"""Shared argument schemas for framework adapters (mirrors src/contracts.ts ToolArgs)."""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+SESSION = {"session_id": {"type": "string", "description": "session id from attach"}}
+
+SPECS: Dict[str, Dict[str, Any]] = {
+    "readiness": {},
+    "attach": {
+        "target": {"type": "string", "description": "pid, container name, k8s pod (ns/name) or a command line"},
+        "kind": {"type": "string", "enum": ["pid", "container", "pod", "command"], "description": "default: auto-detect"},
+    },
+    "detach": {**SESSION},
+    "list_processes": {"filter": {"type": "string"}, "limit": {"type": "integer", "default": 100}},
+    "trace_syscalls": {**SESSION, "duration_s": {"type": "integer", "default": 10, "maximum": 60}, "categories": {"type": "array", "items": {"type": "string", "enum": ["network", "file", "process", "signal", "memory", "all"]}}},
+    "profile_cpu": {**SESSION, "duration_s": {"type": "integer", "default": 15, "maximum": 60}},
+    "dump_stacks": {**SESSION},
+    "inspect_sockets": {**SESSION},
+    "inspect_files": {**SESSION, "window_s": {"type": "integer", "default": 3}},
+    "capture_traffic": {**SESSION, "duration_s": {"type": "integer", "default": 10, "maximum": 30}, "filter": {"type": "string"}, "consent": {"type": "boolean", "description": "REQUIRED true; ask the user first"}},
+    "snapshot_memory": {**SESSION, "heap": {"type": "boolean", "default": True}, "window_s": {"type": "integer", "default": 3}},
+    "diff_runs": {**SESSION, "a": {"type": "string", "description": "earlier run id, e.g. snapshot_memory#2"}, "b": {"type": "string", "description": "later run id"}},
+    "container_info": {**SESSION},
+    "report": {**SESSION, "out": {"type": "string", "description": "optional path to also write the markdown to"}},
+}
+
+REQUIRED: Dict[str, list] = {
+    "attach": ["target"],
+    "diff_runs": ["session_id", "a", "b"],
+    "capture_traffic": ["session_id", "consent"],
+}
+for _name, _spec in SPECS.items():
+    if "session_id" in _spec and _name not in REQUIRED:
+        REQUIRED[_name] = ["session_id"]
+REQUIRED.setdefault("readiness", [])
+REQUIRED.setdefault("list_processes", [])
+
+
+def json_schema(tool: str) -> Dict[str, Any]:
+    return {"type": "object", "properties": SPECS[tool], "required": REQUIRED.get(tool, [])}

dea_agents-0.1.0/dea_agents/crewai.py

@@ -0,0 +1,51 @@
+"""CrewAI tools for DEA.
+
+    from dea_agents.crewai import dea_tools
+    agent = Agent(role="SRE", goal="diagnose the slow API with evidence", tools=dea_tools(), ...)
+
+Requires ``pip install dea-agents[crewai]``.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, List, Optional, Type
+
+from . import DEA, TOOLS
+from ._specs import SPECS, REQUIRED
+
+try:
+    from crewai.tools import BaseTool
+    from pydantic import BaseModel, Field, create_model
+except ImportError as e:  # pragma: no cover
+    raise ImportError("pip install 'dea-agents[crewai]'") from e
+
+_PY = {"string": str, "integer": int, "boolean": bool, "array": List[str]}
+
+
+def _model(tool: str) -> Type[BaseModel]:
+    fields: dict = {}
+    for name, spec in SPECS[tool].items():
+        typ = _PY.get(spec.get("type", "string"), str)
+        required = name in REQUIRED.get(tool, [])
+        fields[name] = (typ if required else Optional[typ], Field(... if required else spec.get("default", None), description=spec.get("description", "")))
+    return create_model(f"Dea{tool.title().replace('_', '')}Args", **fields)  # type: ignore[call-overload]
+
+
+def dea_tools(client: Optional[DEA] = None, include: Optional[List[str]] = None) -> List["BaseTool"]:
+    dea = client or DEA()
+    out: List[BaseTool] = []
+    for tool_name, desc in TOOLS.items():
+        if include and tool_name not in include:
+            continue
+
+        class _Tool(BaseTool):
+            name: str = f"dea_{tool_name}"
+            description: str = desc + " Findings cite evidence ids; never state a cause without one."
+            args_schema: Type[BaseModel] = _model(tool_name)
+            _dea_tool: str = tool_name
+
+            def _run(self, **kwargs: Any) -> str:
+                return json.dumps(dea.call(self._dea_tool, **kwargs))
+
+        out.append(_Tool())
+    return out

dea_agents-0.1.0/dea_agents/langchain.py

@@ -0,0 +1,48 @@
+"""LangChain tools for DEA.
+
+    from dea_agents.langchain import dea_tools
+    tools = dea_tools()                 # 14 StructuredTools, one per DEA tool
+    agent = create_react_agent(llm, tools)
+
+Each tool returns the ToolResult as a JSON string. Requires ``pip install dea-agents[langchain]``.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, List, Optional, Type
+
+from . import DEA, TOOLS
+from ._specs import SPECS, REQUIRED
+
+try:
+    from langchain_core.tools import StructuredTool
+    from pydantic import BaseModel, Field, create_model
+except ImportError as e:  # pragma: no cover
+    raise ImportError("pip install 'dea-agents[langchain]'") from e
+
+_PY = {"string": str, "integer": int, "boolean": bool, "array": List[str]}
+
+
+def _model(tool: str) -> Type[BaseModel]:
+    fields: dict = {}
+    for name, spec in SPECS[tool].items():
+        typ = _PY.get(spec.get("type", "string"), str)
+        required = name in REQUIRED.get(tool, [])
+        default = ... if required else spec.get("default", None)
+        fields[name] = (typ if required else Optional[typ], Field(default, description=spec.get("description", "")))
+    return create_model(f"Dea{tool.title().replace('_', '')}Args", **fields)  # type: ignore[call-overload]
+
+
+def dea_tools(client: Optional[DEA] = None, include: Optional[List[str]] = None) -> List["StructuredTool"]:
+    """Build one LangChain StructuredTool per DEA tool."""
+    dea = client or DEA()
+    out: List[StructuredTool] = []
+    for name, desc in TOOLS.items():
+        if include and name not in include:
+            continue
+
+        def _run(_name: str = name, **kwargs: Any) -> str:
+            return json.dumps(dea.call(_name, **kwargs))
+
+        out.append(StructuredTool.from_function(func=_run, name=f"dea_{name}", description=desc + " Findings cite evidence ids; never state a cause without one.", args_schema=_model(name)))
+    return out

dea_agents-0.1.0/dea_agents/llamaindex.py

@@ -0,0 +1,33 @@
+"""LlamaIndex FunctionTools for DEA.
+
+    from dea_agents.llamaindex import dea_tools
+    agent = ReActAgent.from_tools(dea_tools(), llm=llm)
+
+Requires ``pip install dea-agents[llamaindex]``.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, List, Optional
+
+from . import DEA, TOOLS
+
+try:
+    from llama_index.core.tools import FunctionTool
+except ImportError as e:  # pragma: no cover
+    raise ImportError("pip install 'dea-agents[llamaindex]'") from e
+
+
+def dea_tools(client: Optional[DEA] = None, include: Optional[List[str]] = None) -> List["FunctionTool"]:
+    dea = client or DEA()
+    out: List[FunctionTool] = []
+    for name, desc in TOOLS.items():
+        if include and name not in include:
+            continue
+
+        def _run(_name: str = name, **kwargs: Any) -> str:
+            """Run a DEA tool. Pass arguments as keyword arguments (session_id, duration_s, ...)."""
+            return json.dumps(dea.call(_name, **kwargs))
+
+        out.append(FunctionTool.from_defaults(fn=_run, name=f"dea_{name}", description=desc + " Findings cite evidence ids."))
+    return out

dea_agents-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dea-agents"
+version = "0.1.0"
+description = "Debug Anything from Python agents: observe running processes (strace, py-spy, perf, lsof, tcpdump, gdb/lldb, heap snapshots) and get evidence-backed findings. Wraps the DEA CLI/MCP server; tool adapters for LangChain, LlamaIndex and CrewAI."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Shreyas Sawant" }]
+keywords = ["debugging", "observability", "profiling", "agents", "mcp", "langchain", "llamaindex", "crewai", "strace", "py-spy", "perf"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Software Development :: Debuggers",
+  "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.2", "pydantic>=2"]
+llamaindex = ["llama-index-core>=0.10"]
+crewai = ["crewai>=0.30", "pydantic>=2"]
+dev = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/shreyassaw5394/dea"
+Documentation = "https://github.com/shreyassaw5394/dea/tree/main/docs"
+Issues = "https://github.com/shreyassaw5394/dea/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["dea_agents"]

dea_agents-0.1.0/tests/test_client.py

@@ -0,0 +1,49 @@
+import json
+import subprocess
+import sys
+from unittest import mock
+
+import pytest
+
+from dea_agents import DEA, DEAError, TOOLS
+from dea_agents._specs import SPECS, REQUIRED, json_schema
+
+
+def test_specs_cover_every_tool():
+    assert set(SPECS) == set(TOOLS)
+    for t in TOOLS:
+        assert json_schema(t)["type"] == "object"
+    assert REQUIRED["capture_traffic"] == ["session_id", "consent"]
+
+
+def test_call_builds_json_args_and_parses_result():
+    fake = subprocess.CompletedProcess(args=[], returncode=0, stdout=json.dumps({"ok": True, "tool": "readiness", "findings": [], "evidence": []}), stderr="")
+    with mock.patch("subprocess.run", return_value=fake) as run:
+        r = DEA(command=["dea"]).call("trace_syscalls", session_id="s", duration_s=5, categories=None)
+    assert r["ok"] is True
+    argv = run.call_args[0][0]
+    assert argv[:3] == ["dea", "call", "trace_syscalls"]
+    assert json.loads(argv[3]) == {"session_id": "s", "duration_s": 5}
+
+
+def test_unknown_tool_rejected():
+    with pytest.raises(DEAError):
+        DEA(command=["dea"]).call("rm_rf")
+
+
+def test_attach_returns_session_id():
+    fake = subprocess.CompletedProcess(args=[], returncode=0, stdout=json.dumps({"ok": True, "session_id": "abc"}), stderr="")
+    with mock.patch("subprocess.run", return_value=fake):
+        assert DEA(command=["dea"]).attach(123) == "abc"
+
+
+def test_missing_node_gives_helpful_error():
+    with mock.patch("subprocess.run", side_effect=FileNotFoundError()):
+        with pytest.raises(DEAError, match="Node.js"):
+            DEA(command=["definitely-not-here"]).readiness()
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="not supported")
+def test_findings_formatter():
+    r = {"findings": [{"severity": "high", "summary": "x", "confidence": "observed", "evidence_ids": ["e1"]}]}
+    assert DEA.findings(r) == ["[high] x (observed; e1)"]