Metadata-Version: 2.5
Name: agentic-dev-guardian
Version: 0.1.3
Summary: AI Developer Governance & Codebase Evaluator — A GraphRAG-powered multi-agent system featuring autonomous code evaluation, red-team testing, and dynamic LLM-narrated architectural documentation.
Project-URL: Homepage, https://github.com/SmayanKulkarni/Agentic-Dev-Guardian
Project-URL: Repository, https://github.com/SmayanKulkarni/Agentic-Dev-Guardian
Project-URL: Issues, https://github.com/SmayanKulkarni/Agentic-Dev-Guardian/issues
Project-URL: Changelog, https://github.com/SmayanKulkarni/Agentic-Dev-Guardian/releases
Author: Smayan Kulkarni
License: MIT
License-File: LICENSE
Keywords: agents,code-review,graphrag,langgraph,llm,mcp,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: fastembed>=0.3.0
Requires-Dist: groq>=0.9.0
Requires-Dist: kuzu>=0.11
Requires-Dist: langgraph>=0.2.0
Requires-Dist: mcp[cli]<2,>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: qdrant-client>=1.9.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: tree-sitter-python>=0.23.0
Requires-Dist: tree-sitter>=0.22.0
Requires-Dist: typer>=0.12.0
Provides-Extra: all
Requires-Dist: anthropic>=0.34; extra == 'all'
Requires-Dist: hatch-vcs>=0.4; extra == 'all'
Requires-Dist: langfuse>=2.40.0; extra == 'all'
Requires-Dist: matplotlib>=3.8; extra == 'all'
Requires-Dist: mypy>=1.8.0; extra == 'all'
Requires-Dist: networkx>=3.2; extra == 'all'
Requires-Dist: openai>=1.40; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: pyvis>=0.3; extra == 'all'
Requires-Dist: radon>=6; extra == 'all'
Requires-Dist: ruff>=0.5.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.34; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: hatch-vcs>=0.4; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == 'openai'
Provides-Extra: tracing
Requires-Dist: langfuse>=2.40.0; extra == 'tracing'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8; extra == 'viz'
Requires-Dist: networkx>=3.2; extra == 'viz'
Requires-Dist: pyvis>=0.3; extra == 'viz'
Requires-Dist: radon>=6; extra == 'viz'
Description-Content-Type: text/markdown

# Agentic Dev Guardian

[![PyPI](https://img.shields.io/pypi/v/agentic-dev-guardian.svg)](https://pypi.org/project/agentic-dev-guardian/)
[![Python](https://img.shields.io/pypi/pyversions/agentic-dev-guardian.svg)](https://pypi.org/project/agentic-dev-guardian/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/SmayanKulkarni/Agentic-Dev-Guardian/blob/main/LICENSE)

> Index your codebase into a knowledge graph, then let agents use it to review PRs, red-team risky functions, triage incidents, plan refactors, and write architecture docs.

**Install:** `pip install agentic-dev-guardian` · **Command:** `dev-guardian` · [Source](https://github.com/SmayanKulkarni/Agentic-Dev-Guardian) · [Issues](https://github.com/SmayanKulkarni/Agentic-Dev-Guardian/issues)

---

## Why

Hand a model a diff and it sees the diff. It misses the twelve callers of the function you
changed, the subclass overriding it, and the module importing it for a side effect.

Guardian indexes your repository into a call, import, and inheritance graph first. Agents
then query that graph for the neighbourhood around each change, so a verdict rests on what
your code references instead of on whatever fit in the context window.

Reach for it when you want:

- **A PR gate that knows the blast radius.** `evaluate` sends a diff through a Mixture-of-Agents pipeline and returns `approve / remediate / reject` with the impacted call graph attached.
- **Hardening before anyone files a PR.** `audit` ranks functions by fan-out and red-teams the worst offenders.
- **On-call help that reads the graph.** `incident --trace` turns a stack trace into a hotfix blueprint using the call graph around the failing frame.
- **Migrations someone else plans.** `refactor` translates "migrate Pydantic v1 to v2" into Cypher, finds every affected entity, and emits a validated blueprint.
- **Docs that track the code.** `docs` narrates the live graph into a `GUARDIAN_WIKI.md`.
- **The same tools in your editor.** `serve` exposes them over MCP to Cursor, Claude Desktop, or Windsurf.

---

## Quickstart

You need Python 3.11+. Nothing else — the graph and vector stores are embedded and run
inside the Guardian process.

```bash
pip install agentic-dev-guardian          # or: uvx --from agentic-dev-guardian dev-guardian --help

export GUARDIAN_PROVIDER=groq             # groq | anthropic | openai | ollama | local | huggingface
export GUARDIAN_GROQ_API_KEY=...          # groq key; anthropic/openai use ANTHROPIC_API_KEY / OPENAI_API_KEY instead

dev-guardian index /path/to/your/repo     # add --skip-vectors on RAM-constrained machines
dev-guardian evaluate my_feature.diff --repo /path/to/your/repo
```

Extras: `pip install "agentic-dev-guardian[anthropic]"` (also `openai`, `viz`, `tracing`, `all`).

> **Upgrading from a Docker-backed install:** the embedded stores do not read
> the old container volumes. Re-run `dev-guardian index <path>` once per
> repository, then remove the leftovers with
> `docker rm -f guardian-memgraph guardian-qdrant`. Guardian no longer manages
> any containers.

Working from a checkout:

```bash
git clone https://github.com/SmayanKulkarni/Agentic-Dev-Guardian.git
cd Agentic-Dev-Guardian/backend
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

---

## How It Works

Guardian runs in two stages.

1. **Index.** Tree-sitter parses the codebase. Kùzu stores the structural edges
   (`IMPORTS`, `CALLS`, `INHERITS_FROM`) and Qdrant stores the semantic index, both under
   `<repo>/.guardian/`.
2. **Act.** LangGraph pipelines query that graph to evaluate PRs, audit risky functions,
   triage incidents, plan refactors, or write architecture docs.

---

## Commands

| CLI Command | What It Does |
|---|---|
| `dev-guardian index <path>` | Parse & ingest a codebase into the embedded stores (streaming, memory-safe) |
| `dev-guardian evaluate <diff>` | Run a PR diff through the MoA Gatekeeper + Red Team pipeline |
| `dev-guardian audit <path>` | Find the highest blast-radius functions and red-team them |
| `dev-guardian incident --trace "..."` | Turn a production stack trace into a targeted hotfix blueprint |
| `dev-guardian refactor --pattern "..."` | Build a migration blueprint from a pattern or plain English |
| `dev-guardian docs <path>` | Write a live `GUARDIAN_WIKI.md` from the AST graph |
| `dev-guardian serve` | Start the MCP Server for IDE integration (Cursor, Claude Desktop, Windsurf) |
| `dev-guardian mcp-config` | Print your IDE's MCP JSON block (`--client vscode\|codex\|cursor\|...`) |
| `dev-guardian version` | Print the installed version |

---

## Architecture

| Layer | Technology |
|---|---|
| **AST Parsing** | Tree-sitter with a custom Python walker |
| **Knowledge Graph** | Kùzu (embedded, file-backed under `<repo>/.guardian/kuzu`), holding `ASTNode` relationships (`IMPORTS`, `CALLS`, `INHERITS_FROM`) |
| **Semantic Index** | Qdrant embedded (`<repo>/.guardian/qdrant`) + FastEmbed (ONNX; `--skip-vectors` for RAM-constrained systems) |
| **Hybrid Retrieval** | `HybridRetriever`, fusing Cypher graph results with Qdrant vector search |
| **Agent Orchestration** | LangGraph typed state graphs (`GuardianState`, `SREState`, `RefactorState`) |
| **LLM Engine** | Groq (`llama-3.3-70b-versatile`) by default; also Anthropic, OpenAI, Ollama, or any OpenAI-compatible endpoint |
| **LLMOps & Tracing** | A local SQLite call log always; Langfuse behind the `[tracing]` extra |
| **IDE Integration** | MCP Server over `stdio` or streamable HTTP |

---

## Data Handling

Guardian ships your source code to a third-party LLM provider. Know that before you point
it at anything sensitive.

**What leaves your machine:** the PR diff verbatim, plus the GraphRAG context retrieved
from your indexed codebase (function bodies, structural relations). Both go into the prompt
as-is.

**Where it goes:** to whichever provider `GUARDIAN_PROVIDER` names, so `groq` by default,
or `anthropic` or `openai`. Choosing `ollama` or `local` keeps the calls on your own
infrastructure, though the prompts assume a 70B-class model. Smaller local models lose the
most ground on Red Team test generation, Remediation diffs, and text-to-Cypher.

**What stays local:** the Kùzu AST graph, the Qdrant index, and every deterministic
node, meaning `IncidentTriager`, `RefactorPlanner`, `BlueprintValidator`, and the
supervisor's routing logic. Blast-radius and impact analysis run on your own graph with no
LLM in the loop.

**`--clearance` is not a privacy control.** It scopes how much of the graph a Cypher query
pulls back (`clearance_level <= $cl`). Whatever it does retrieve still reaches the provider,
and the PR diff skips the check.

---

## Agent Pipelines

### PR Evaluation (`evaluate`)
`Gatekeeper → Red Team → Remediation → Decision`

Reads a `.diff` file, pulls GraphRAG context for it, then runs a Mixture-of-Agents pipeline
that lands on `approve`, `remediate`, or `reject`.

### Proactive Audit (`audit`)
`Kùzu (blast-radius query) → Gatekeeper → Red Team → Markdown Report`

Ranks functions by outgoing calls, red-teams the top N without waiting for a PR, and writes
a severity-ranked `guardian_audit.md`.

### Incident Response (`incident`)
`IncidentTriager → SandboxReproducer → HotfixScribe`

Parses a raw stack trace, asks Kùzu for the call graph around the failing function,
tries to reproduce the failure, and drafts a hotfix blueprint.

### Self-Healing Refactor (`refactor`)
`PatternTranslator → RefactorPlanner → MigrationScribe → BlueprintValidator`

Takes a registered pattern such as `migrate-pydantic-v1-to-v2`, or free-form English.
Translates the intent into Cypher, finds every affected entity, and produces a validated
migration blueprint.

### Docs Generation (`docs`)
`StructureExplainer → ADRGenerator → WikiBuilder`

Queries IMPORTS, CALLS, and INHERITS_FROM edges from the live graph, narrates them into
readable section summaries, and assembles a full `GUARDIAN_WIKI.md`.

---

## Providers & Configuration

You choose the provider. Guardian never guesses from whichever key happens to sit in your
environment. `GUARDIAN_PROVIDER` picks the backend and `GUARDIAN_MODEL` overrides that
backend's default model. A missing key for the provider you selected fails the run instead
of falling back to another one.

| Provider | Key | Notes |
|----------|-----|-------|
| `groq` (default) | `GROQ_API_KEY` | `llama-3.3-70b-versatile` |
| `anthropic` | `ANTHROPIC_API_KEY` | structured output via forced tool-use; needs the `[anthropic]` extra |
| `openai` | `OPENAI_API_KEY` | cloud only; needs the `[openai]` extra |
| `ollama` | none | `http://localhost:11434/v1`, defaults to `qwen3:8b` |
| `local` | none | any OpenAI-compatible engine; set `GUARDIAN_LOCAL_BASE_URL` |
| `huggingface` | `HF_TOKEN` | Inference Providers router |

Running a local or self-hosted model? Set `GUARDIAN_CONTEXT_TOKENS` to that model's real
context size, and `GUARDIAN_TPM` if your endpoint meters you. Guardian cannot infer either
one.

Environment variables win over everything. Dotenv files exist for convenience and load in
ascending priority: `~/.config/guardian/.env`, then `backend/.env`, then `./.env`. Every
setting answers to a `GUARDIAN_`-prefixed name as well as its plain vendor name, and
Guardian writes no configuration of its own.

---

## MCP Integration

`dev-guardian serve` starts a stdio MCP server. It exposes 4 bootstrap tools at startup to
keep your IDE's context window lean:

- `query_guardian_graph` runs semantic and structural search over the indexed codebase
- `list_capabilities` reports what else you can load
- `equip_capability` and `unequip_capability` load and unload a domain's tools on demand

Everything heavier arrives just in time. `equip_capability("pr_governance")` adds
`evaluate_pr_diff`, `codebase_intelligence` adds `impact_analysis`, `index_codebase`,
`audit_codebase` and `generate_architecture_docs`, and `incident_response` and
`self_healing` bring their own. Every CLI command has an MCP equivalent; there is no
infrastructure command left to run. The server fires
`notifications/tools/list_changed` on each swap, so a client that caches the tool list for
a session picks the new tools up on its next refresh rather than right away.

### Why MCP over CLI

The CLI is fire-and-forget. You write code, save a diff, switch to terminal, run `dev-guardian evaluate diff.patch`, parse the markdown output, and switch back. Each run costs context: initialization overhead, format conversion, re-parsing.

MCP stays in session. Your agent (Claude, in Cursor or Claude Desktop) calls Guardian's tools directly. No round-trip through markdown. No manual parsing. A diff already open in your IDE? Pass it straight to `evaluate_pr_diff`. Stack trace in a comment? Copy it to `incident_response`. Results land in-chat, structured.

Token savings add up on multi-turn work. One session, persistent context, batch operations, caching on repeated queries. On a typical PR audit, MCP uses 30% fewer tokens than CLI + conversation.

Generate the exact block for your install, filled in with your resolved settings:

```bash
dev-guardian mcp-config                    # Claude Code / Claude Desktop
dev-guardian mcp-config --client vscode    # .vscode/mcp.json
dev-guardian mcp-config --client codex     # ~/.codex/config.toml
```

```json
{
  "mcpServers": {
    "guardian": {
      "command": "uvx",
      "args": ["--from", "agentic-dev-guardian", "dev-guardian", "serve"],
      "env": { "GUARDIAN_PROVIDER": "groq", "GUARDIAN_GROQ_API_KEY": "<your-api-key>" }
    }
  }
}
```

`--client` takes `claude`, `cursor`, `windsurf`, `antigravity`, `claude-desktop`, `vscode`,
or `codex`. The shapes are not interchangeable: VS Code keys servers under `servers` and
Codex reads TOML, while the rest use Claude Desktop's `mcpServers`. The printed comment
line names the file to paste into, and goes to stderr so you can redirect the block itself.

Guardian runs its own agent pipeline inside the server process against `GUARDIAN_PROVIDER`,
so `evaluate_pr_diff` behaves the same in every client — it does not borrow the editor's
model and does not need the editor to spawn sub-agents. It does need its own key, or
`GUARDIAN_PROVIDER=ollama` for a fully local run.

Index at least one repository before you point an IDE at the server.

### Clients that ignore `tools/list_changed`

JIT equipping assumes your client refreshes its tool list when the server notifies it. If
yours does not, equipped tools never become visible. Set `GUARDIAN_PRELOAD_CLUSTERS=all` in
the server's `env` block to register every cluster at startup instead — a fuller context
window in exchange for tools that are there from the first message. A comma-separated list
(`pr_governance,codebase_intelligence`) preloads only those.

### Serving over HTTP

Run one Guardian on the machine holding the indexed codebase and connect from elsewhere, or
from several clients, using the streamable-HTTP transport instead of stdio:

```bash
dev-guardian serve --transport streamable-http --port 8000   # endpoint: /mcp
```

It binds to `127.0.0.1` and stays there on purpose. Guardian carries no authentication of
its own and its tools read your indexed codebase, so anything past loopback belongs behind
a reverse proxy that authenticates. Equipped capabilities live in process-global state, so
treat an HTTP server as single-user rather than multi-tenant.

### Optional tracing

Langfuse is an extra, not a dependency. Leave it out and every `@observe` span becomes a
no-op while Guardian runs as usual. The local SQLite call log in `harness/logger.py` keeps
recording either way.

```bash
pip install "agentic-dev-guardian[tracing]"
export LANGFUSE_PUBLIC_KEY=... LANGFUSE_SECRET_KEY=...
```

`GUARDIAN_LANGFUSE_*` / `LANGFUSE_*` in `backend/.env` also work — `core/tracing.py`
copies whatever `GuardianSettings` resolved into `os.environ` (real exported env vars
still win) before Langfuse's own SDK reads it. Langfuse ignores `GuardianSettings`
entirely and reads `os.environ` directly, so without that copy step a `.env`-only
setup silently no-ops every trace with an auth error nobody sees.

---

## Repository Map

```
backend/src/dev_guardian/
├── core/                # Config (Pydantic Settings) + structured logging (structlog)
├── parsers/             # Tree-sitter AST parser + ASTNode/ASTEdge data models
├── graphrag/            # Kùzu client, Qdrant client, vector manager, hybrid retriever
├── agents/              # LangGraph nodes, typed state definitions, graph builders
├── capability_clusters/ # Tool groupings (codebase_intelligence, pr_governance, ...)
├── harness/             # Prompt YAML loading + local SQLite LLM call log
├── prompts/             # Versioned prompt templates
├── skills/              # Agent personas (graphrag_engineer, red_team_tester, ...)
├── docs/                # structure_explainer.py, adr_generator.py, wiki_builder.py
├── cli.py               # Typer CLI entry point (`dev-guardian` command)
└── mcp_server.py        # MCP Server with JIT tool loading for IDE integration
```

The repo also carries `frontend/` (dashboard UI), `evaluation/` (benchmark datasets and
scripts), and `.agents/` (memory, skills, logs). The PyPI wheel ships none of them. It
contains `backend/src/dev_guardian` and nothing else.

---

## License

MIT. See [LICENSE](https://github.com/SmayanKulkarni/Agentic-Dev-Guardian/blob/main/LICENSE).
