Metadata-Version: 2.4
Name: dgat
Version: 1.0.0
Summary: Dependency Graph as a Tool - LLM-annotated code dependency analysis
Author: DGAT Contributors
License: MIT
Project-URL: Homepage, https://github.com/HyperKuvid-Labs/DGAT
Project-URL: Repository, https://github.com/HyperKuvid-Labs/DGAT
Project-URL: Issues, https://github.com/HyperKuvid-Labs/DGAT/issues
Keywords: dependency-graph,code-analysis,mcp,llm,tool
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.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

<div align="center">

# DGAT
### Dependency Graph as a Tool

*Point it at a codebase. Get a fully-described, LLM-annotated dependency graph — instantly.*

![C++](https://img.shields.io/badge/C%2B%2B-17-blue?style=flat-square&logo=cplusplus)
![Next.js](https://img.shields.io/badge/Next.js-14-black?style=flat-square&logo=nextdotjs)
![vLLM](https://img.shields.io/badge/LLM-vLLM%20%2F%20Qwen-orange?style=flat-square)
![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)

</div>

---

## What is this?

DGAT scans any codebase, uses a locally-hosted LLM to write natural-language descriptions for every file and every import relationship, then serves it all through an interactive three-panel UI. Think of it as a self-generating architectural map — no config files, no annotations, no manual work.

---

## Architecture

```mermaid
flowchart TD
    subgraph CLI ["dgat (C++17 backend)"]
        A[Walk directory tree] --> B[Fingerprint files\nXXH3-128]
        B --> C[Parse imports\ntree-sitter + regex fallback]
        C --> D[Describe files & edges\nvLLM HTTP API]
        D --> E[Build dependency graph\nDepNode + DepEdge]
        E --> F[Synthesise blueprint\ndgat_blueprint.md]
        F --> G[Persist state\nfile_tree.json · dep_graph.json]
    end

    subgraph Server ["--backend mode"]
        G --> H[HTTP server :8090\ncpp-httplib]
        H --> |GET /api/tree| I[File tree JSON]
        H --> |GET /api/dep-graph| J[Dep graph JSON]
        H --> |GET /api/blueprint| K[Blueprint markdown]
    end

    subgraph UI ["Next.js frontend"]
        I --> L[Explorer panel\nfile tree]
        K --> M[Blueprint tab\nrendered markdown]
        J --> N[Graph tab\nSigma.js WebGL]
        L & M & N --> O[Inspector panel\nnode · edge · dep details]
    end

    subgraph LLM ["Local vLLM"]
        D <--> P[Qwen/Qwen3.5-2B\nor any OpenAI-compat endpoint]
    end
```

---

## Demo

### 1. Start the vLLM server

Before running DGAT, bring up a local vLLM instance. DGAT uses it to generate descriptions for every file and dependency edge.

![vLLM server running with GPU stats and throughput metrics](images/vllm-server-running.png)

---

### 2. Run the scan

Point DGAT at your project. It walks the file tree, fingerprints every file, sends them to vLLM, and builds the dependency graph.

![DGAT CLI scan output showing tree build and description population](images/dgat-scan-cli.png)

Dependency extraction runs in parallel — here's the tail end where import relationships are resolved and edges are formed:

![DGAT CLI output showing dependency graph construction and import resolution](images/dgat-dep-graph-build.png)

---

### 3. Open the UI

Start the backend server and the frontend. Three panels: file explorer on the left, blueprint/graph in the middle, inspector on the right.

**Blueprint tab** — a synthesised architectural overview of the whole project, generated bottom-up from individual file descriptions:

![DGAT UI showing the Blueprint tab with the rendered software blueprint](images/ui-blueprint-panel.png)

**File inspector** — click any file in the explorer to see its description, dependencies, and metadata:

![DGAT UI showing file tree selection with description cards in the inspector panel](images/ui-file-inspector.png)

Select a file like `dep_graph.json` to see its role in the project explained inline:

![DGAT UI with dep_graph.json selected showing its description in the inspector](images/ui-dep-graph-file-selected.png)

---

### 4. Explore the dependency graph

Switch to the **Graph tab** for an interactive WebGL view of all import relationships. Node size reflects connectivity.

**Single node selected** — click any node to see a full LLM-generated analysis of that file, plus its outgoing/incoming edges at the bottom:

![DGAT graph view with dgat.cpp selected showing node analysis and edge detail](images/ui-graph-node-inspection.png)

**Two nodes selected** — click a second node to inspect the direct edge between them: the import statement, and a plain-English explanation of why one depends on the other:

![DGAT graph view with utils.ts and page.tsx selected showing edge relationship and import details](images/ui-graph-edge-inspection.png)

---

## Features

- **Multi-language import extraction** — TypeScript, JavaScript, Python, C/C++, Go, Java, Rust, C#, Ruby, PHP, Bash, and more. Tree-sitter grammars for precision, regex fallback for everything else.
- **LLM-annotated graph** — every file node and every dependency edge gets a concise description generated by a local model. No cloud, no API keys.
- **Project blueprint** — a synthesised `dgat_blueprint.md` built bottom-up from all file descriptions.
- **Incremental updates** — `dgat update` re-describes only files whose XXH3 fingerprint changed.
- **Static export** — embed the entire graph into a single self-contained HTML file. Share with anyone, no server required.
- **Live UI** — auto-refreshes every 30 s. Three-panel layout with file explorer, blueprint/graph tabs, and an inspector.

---

## Getting started

### Prerequisites

- C++17 compiler (GCC 11+ / Clang 14+)
- CMake 3.16+
- A running [vLLM](https://github.com/vllm-project/vllm) instance (or any OpenAI-compatible endpoint) on `localhost`
- Node.js 18+ / Bun (for the frontend)

### Build & install

```bash
git clone https://github.com/yourname/dgat
cd dgat
cmake -B build && cmake --build build -j$(nproc)

# or use the install script
bash install.sh
```

### Run

```bash
# full scan — builds tree, descriptions, dep graph, blueprint
./build/dgat /path/to/your/project

# start the API server (no re-scan)
./build/dgat --backend

# start the frontend
cd frontend && bun dev
# open http://localhost:3000
```

---

## CLI reference

| Command | Description |
|---|---|
| `dgat [path]` | Full scan of the target directory |
| `dgat --backend` | Load saved state, start API server |
| `dgat update` | Incremental re-scan (changed files only) |
| `--port <n>` | Override API server port (default: 8090) |

---

## Tech stack

| Layer | Tech |
|---|---|
| Backend | C++17 · cpp-httplib · nlohmann/json · inja · xxHash |
| Parsing | tree-sitter (C, C++, Python, TS, Go, Java, Rust, …) |
| LLM | vLLM · Qwen3.5-2B (any OpenAI-compat endpoint) |
| Frontend | Next.js 14 · TypeScript · Tailwind CSS · Sigma.js · shadcn/ui |

---

## Example output

The [`examples/dgat-self/`](examples/dgat-self/) folder contains the output DGAT produced when pointed at its own source tree — a blueprint, file tree, and dependency graph all generated by **Qwen3.5-2B** running locally via vLLM. Browse it to get a feel for the output format without running a scan yourself.

---

## .dgatignore

DGAT respects a `.dgatignore` file in the root of the scanned project. It works like `.gitignore` — one glob pattern per line — and tells DGAT which files and directories to skip during description and graph-building passes (files that match are still shown in the tree but their LLM descriptions and dependency edges are suppressed).

```
# .dgatignore example
node_modules/
*.lock
vendor/
```

Files already covered by `.gitignore` are automatically excluded from LLM processing regardless.

---

## Docs

- [Overview](docs/overview.md) — how DGAT works end to end
- [File Tree](docs/file-tree.md) — TreeNode structure, fields, and why each one exists
- [Dependency Graph](docs/dependency-graph.md) — DepNode, DepEdge, DepGraph, and how the graph is built
- [Incremental Updates](docs/incremental-updates.md) — how the diff mode works with XXH3 fingerprints
- [Import Extraction](docs/import-extraction.md) — tree-sitter parsing, regex fallbacks, and path resolution

---

> gonna scavenge some popular repos, and see how my thing behaves with it, and use my populated context for something useful.
