Metadata-Version: 2.4
Name: engramedb
Version: 1.0.1
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
License-File: LICENSE
Summary: Real-time Code-Native Graph Database Engine (Rust Core)
Author: Ghassen Saidi
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# engramedb

[![PyPI Version](https://img.shields.io/pypi/v/engramedb.svg)](https://pypi.org/project/engramedb/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**EngramDB** is a high-performance, real-time, code-native graph database engine written in **Rust** with native **PyO3** Python bindings.

Designed for AI agentic tools, MCP servers, code search engines, and static analysis tools, EngramDB compiles AST nodes, function calls, class inheritance, and file dependencies into an in-memory Compressed Sparse Row (CSR) graph for microsecond-latency impact analysis and graph querying.

---

## Key Features

- ⚡ **Ultra-Fast CSR Graph Traversal**: Bidirectional Compressed Sparse Row (CSR) call-graph indexing for sub-millisecond call-tree tracing and blast radius calculation.
- 🧵 **Thread-Safe Architecture**: Atomic concurrent reads (`read()`) and writes (`write()`) guarded by Rust's `Arc<RwLock<InnerEngineState>>`.
- 🔍 **Rich AST Metadata Indexing**: Stores nodes (functions, classes, files, folders, routes) with full signatures, docstrings, decorators, inheritance, imports, line ranges, and custom JSON payloads.
- 🛡️ **Blast Radius & Impact Analysis**: Instantly compute transitive caller/callee trees and impact scores for breaking change detection.
- 💾 **Zero-Copy Persistence**: Instant binary snapshot serialization and disk persistence (`rkyv` / `bincode`).
- 🐍 **Pre-compiled Python Wheels**: Available for Linux, macOS, and Windows across Python 3.10–3.13.

---

## Installation

```bash
pip install engramedb
```

---

## Quick Start

```python
import engramdb

# 1. Initialize engine with workspace storage path
engine = engramdb.PyMetadataEngine("/path/to/workspace")

# 2. Index AST Nodes & Relationships
engine.add_node(
    "services.py:create_sale",
    "Function",
    "create_sale",
    "services.py",
    _extra={
        "signature": "def create_sale(user, item_id):",
        "docstring": "Creates a new sales transaction.",
        "decorators": ["transaction.atomic"],
        "lines_start": 10,
        "lines_end": 25,
    }
)

engine.add_node("inventory.py:deduct_stock", "Function", "deduct_stock", "inventory.py")
engine.add_edge("services.py:create_sale", "inventory.py:deduct_stock", "calls")

# 3. Build Compressed Sparse Row (CSR) Graph
engine.build()

# 4. Blast Radius & Call Graph Analysis
impact = engine.blast_radius("inventory.py:deduct_stock", depth=3)
print(f"Affected nodes: {impact}")

# 5. Fast Keyword & Property Search
results = engine.search("create_sale")
```

---

## License

Distributed under the [MIT License](LICENSE).

