Metadata-Version: 2.4
Name: grounded-graph
Version: 0.4.1
Summary: Graph traversal and context queries over grounded-index metadata
Project-URL: Homepage, https://github.com/oldnordic/grounded-graph
Project-URL: Repository, https://github.com/oldnordic/grounded-graph
Project-URL: Bug Tracker, https://github.com/oldnordic/grounded-graph/issues
Project-URL: Changelog, https://github.com/oldnordic/grounded-graph/blob/main/CHANGELOG.md
Author: Luiz Spies
License: GPL-3.0-only
Keywords: cli,code-graph,context-queries,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
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 :: Libraries
Requires-Python: >=3.10
Requires-Dist: grounded-index>=0.5.0
Requires-Dist: sqlitegraph>=0.3.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# grounded-graph

![version](https://img.shields.io/badge/version-0.4.1-blue)

Graph traversal and context queries over code metadata. `grounded-graph` reads a
[`grounded-index`](https://github.com/oldnordic/grounded-index) SQLite database
and exposes call graphs, impact analysis, test discovery, and token-bounded
context packs for AI coding agents.

Two storage backends:

- **Pure-Python** (`--backend python`) — fast in-memory, no extra dependencies.
- **sqlitegraph** (`--backend sqlitegraph`) — file-backed Rust graph with HNSW
  semantic search and persistent indexes.

## Quick start

```bash
# 1. Index your project (produces .grounded-index.db)
grounded-index index .

# 2. Load the graph and check stats
grounded-graph index --backend python

# 3. Query
grounded-graph callers --symbol my_function
grounded-graph tests-for --symbol CustomerService
grounded-graph neighborhood --symbol my_function --depth 2 --budget 4000
```

## What it does

| Capability | Description |
|------------|-------------|
| **Call graph** | `callers`, `callees`, `impact`, `affected` with kind-filtered traversal |
| **Test mapping** | `tests-for` links tests to the symbols they exercise |
| **Shortest path** | `path --from A --to B` between any two symbols |
| **Context packs** | `neighborhood` returns priority-ranked, token-bounded symbol context |
| **Semantic search** | HNSW-backed similarity search over symbol embeddings (sqlitegraph only) |
| **Multi-kind edges** | Same node pair can carry `call`, `defines`, `imports`, and `tests` edges |

See [MANUAL.md](MANUAL.md) for full CLI documentation and [API.md](API.md) for the
Python API.

## Install

```bash
pip install grounded-graph
```

Requires Python >= 3.10.

## Version

Current version: **0.4.1**
