Metadata-Version: 2.4
Name: rocksgraph
Version: 0.2.3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Summary: Embeddable, ACID-compliant property graph database with Gremlin traversals and integrated HNSW vector search.
Keywords: graph-database,vector-search,gremlin,embedded,rocksdb,hnsw
Author-email: Austin Han <austinhan1024@gmail.com>
License: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# RocksGraph for Python

[![CI](https://github.com/ThouAreAwesome/RocksGraph/actions/workflows/ci.yml/badge.svg)](https://github.com/ThouAreAwesome/RocksGraph/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/rocksgraph.svg)](https://pypi.org/project/rocksgraph/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://pypi.org/project/rocksgraph/)
[![License: Apache 2.0 / MIT](https://img.shields.io/badge/License-Apache_2.0_|_MIT-blue.svg)](https://github.com/ThouAreAwesome/RocksGraph/blob/main/rocksgraph/LICENSE-APACHE)

**RocksGraph** is an embeddable, ACID-compliant property graph database with Gremlin query language and integrated HNSW vector search, compiled directly to native code via PyO3.

It runs in-process inside your Python application without external server daemons, JVM runtimes, or network overhead.

```
  ┌──────────────────────────────────────────────────────────┐
  │                 Gremlin Traversal Engine                 │
  │  • Lazy streaming engine   • Multi-hop path traversals   │
  ├──────────────────────────────────────────────────────────┤
  │                 Graph Consistency Layer                  │
  │  • Snapshot ReadSession    • ACID TxnSession (OCC / RYOW)│
  ├────────────────────────────┬─────────────────────────────┤
  │     Graph Data Storage     │     Vector Index Engine     │
  │  • Vertices, Edges, Props  │  • In-Memory HNSW Graph     │
  │  • Schema & Type Metadata  │  • Quantization algorithms  │
  │                            └─────────────────────────────┤
  │  • Write-Ahead Log (WAL) — crash recovery & consistency  │
  └──────────────────────────────────────────────────────────┘
```

---

## Key Features

- **In-Process & Zero-Config**: Runs directly within your Rust or Python process. Zero daemon management or cluster orchestration.
- **Unified Graph + Vector Search**: Combine relationship traversal and vector similarity search in a single declarative query pipeline.
- **ACID Transactions**: Snapshot Isolation with Optimistic Concurrency Control (OCC), Write-Ahead Logging (WAL), and Read-Your-Own-Writes (RYOW).
- **Streaming Query Engine**: Stream-based, lazy-iterator query processing with early `.limit()` termination and index pushdown.
- **High-Throughput Ingestion**: Dedicated `BulkLoader` for direct offline storage file generation and instant atomic DB ingestion.
- **Polyglot**: First-class Rust native crate and high-performance Python bindings via PyO3.

```bash
pip install rocksgraph
```

---

## 30-Second Quickstart

```python
from rocksgraph import Graph, Vector

# 1. Open a persistent embedded database
graph = Graph("./my_graph_db")

# 2. Write graph vertices, edges, and vector embeddings in an ACID transaction
with graph.begin() as txn:
    txn.g().addV("person").property("id", 1).property("name", "Alice").property("emb", Vector([0.9, 0.1, 0.0])).next()
    txn.g().addV("person").property("id", 2).property("name", "Bob").property("emb", Vector([0.1, 0.9, 0.0])).next()
    txn.g().addE("knows").from_(1).to(2).property("since", 2022).next()

# 3. Query via point-in-time snapshot
snap = graph.read()

# Graph traversal: Who does Alice know?
friends = snap.g().V(1).out("knows").values("name").to_list()
print("Friends of Alice:", friends)  # ['Bob']

# Vector Search: Find closest person to query embedding.
# No index declared here, so this runs an exact brute-force scan, not HNSW —
# see the Getting Started guide for when/how to declare a vector index.
nearest = snap.g().V().nearest("emb", Vector([1.0, 0.0, 0.0]), 1).values("name").to_list()
print("Nearest neighbor:", nearest)  # ['Alice']

# Clean shutdown
graph.close()
```

---

## Pythonic Architecture & Idioms

### 1. Context Manager Lifecycle
`TxnSession` and `SchemaSession` implement Python's context manager protocol (`with` statement):
- Automatically commits on normal block exit.
- Automatically rolls back and aborts staged changes if an exception is raised.

```python
# Auto-rolls back on exception without corrupting database state
try:
    with graph.begin() as txn:
        txn.g().addV("account").property("id", 42).property("balance", 100).next()
        raise RuntimeError("Something failed!")
except RuntimeError:
    pass  # Transaction was cleanly aborted
```

### 2. First-Class Type Wrappers
- **`Vector(list[float])`**: Continuous dense vector embedding wrapper for similarity queries and property assignments.
- **`Int64(int)`**: Explicit 64-bit integer type marker for vertex IDs.
- **`DistanceMetric` / `Quantization`**: Enums for configuring HNSW indexes (`DistanceMetric.Cosine`, `DistanceMetric.DotProduct`, `DistanceMetric.L2`, `Quantization.F16`, `Quantization.F32`).

### 3. Session Model
```
Graph(path)
  ├── .read()             ──► ReadSession     (Lock-free point-in-time snapshot reads)
  ├── .begin()            ──► TxnSession      (ACID transactional writes with RYOW)
  ├── .open_schema()      ──► SchemaSession   (Atomic DDL — labels, types, vector indexes)
  ├── .open_bulk_loader() ──► BulkLoader      (High-throughput offline SST file ingestion)
  └── .index_manager()    ──► IndexManager    (Vector index maintenance — rebuild, save)
```

### 4. Exception Hierarchy
All RocksGraph exceptions inherit from `rocksgraph.StoreError`:
- **`TransactionError`**: OCC optimistic commit conflict (retry recommended).
- **`SchemaError`**: Strict schema validation violations or undeclared properties.
- **`IntegrityError`**: Duplicate entity or key conflicts.
- **`QueryError`**: Invalid traversal syntax or query planner constraints.
- **`VectorError`**: Vector dimension mismatch or index configuration error.
- **`StorageError`**: Low-level storage and I/O failures.

---

## Topic Guides & Documentation

Full documentation and guides are available in the repository docs and GitHub Wiki:

| Guide                                                                                                    | Description                                                                                                        |
| :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| 🚀 [**Getting Started**](https://github.com/ThouAreAwesome/RocksGraph/wiki/getting_started)               | 5-minute end-to-end walkthrough in Rust & Python.                                                                  |
| 📐 [**Data Model & Types**](https://github.com/ThouAreAwesome/RocksGraph/wiki/data_model)                 | Graph primitives, property types, identifier policies, and reserved keys.                                          |
| 🔍 [**Vector Search Deep Dive**](https://github.com/ThouAreAwesome/RocksGraph/wiki/vector_search)         | HNSW parameters, quantization (`F16`), memory limits, and query primitives (`nearest`, `similarity`, `neighbors`). |
| 🗺️ [**Gremlin Step Reference**](https://github.com/ThouAreAwesome/RocksGraph/wiki/step_reference)         | Comprehensive step-by-step reference for all traversal steps and type transitions.                                 |
| 📋 [**Schema Management & DDL**](https://github.com/ThouAreAwesome/RocksGraph/wiki/schema_management)     | Strict vs Auto schema modes, `SchemaSession`, and dynamic vector index management.                                 |
| 🔒 [**Transactions & Concurrency**](https://github.com/ThouAreAwesome/RocksGraph/wiki/concurrency_and_tx) | OCC conflict handling, Snapshot Isolation, and session lifecycles.                                                 |
| ⚡ [**Bulk Loading & SST Ingest**](https://github.com/ThouAreAwesome/RocksGraph/wiki/bulk_loading)        | High-throughput offline SST file generation and instant atomic DB loading.                                         |
| 🏎️ [**Performance Tuning**](https://github.com/ThouAreAwesome/RocksGraph/wiki/performance)                | Batching strategies, memory sizing formulas, and query optimization patterns.                                      |
| 📊 [**Benchmarks**](https://github.com/ThouAreAwesome/RocksGraph/wiki/benchmarks)                         | Measured write (bulk load, transactional OCC) and read throughput/latency across dataset scales.                   |

For the Rust crate, see the [main repository README](https://github.com/ThouAreAwesome/RocksGraph/tree/main/rocksgraph).

---

## Project Status

**Maturity**: RocksGraph is pre-1.0 software, currently at v0.2.3. The core engine — ACID transactions, Gremlin traversal, integrated HNSW vector search — is functional and covered by an extensive test suite: unit tests, property-based (`proptest`) round-trip tests for the bulk loader and the bytecode wire format, and fuzz testing on the wire-format decoder. It's a young project, though: the public API isn't frozen yet, and the on-disk format — while unchanged in practice since v0.1.0 — isn't formally guaranteed stable until 1.0.0. Good fit for side projects, prototypes, and anywhere you control the blast radius of a bad upgrade. Not yet the right choice if you need a storage-format stability guarantee today.

| Version | Stability                                                                             |
| ------- | ------------------------------------------------------------------------------------- |
| 0.2.x   | API may change. On-disk format may change. Not for production data you can't rebuild. |
| 0.3.x   | (planned) API stable. On-disk format stable.                                          |
| 1.0.0   | (planned) Full backward compatibility for both API and storage.                       |

**Maintenance**: Actively maintained. Issues responded to within a week. Releases when there's something worth shipping, not on a schedule. If that changes, it'll be reflected here.

**Roadmap** (directional, not a fixed schedule):
- v0.2.x (current): the API keeps growing based on real usage — more Gremlin traversal steps, additional vector search capabilities, and LLM/framework integrations may all land here before anything is locked down.
- Toward 0.3.x: once that feedback has shaped the surface, freeze the public API and the on-disk format.
- Toward 1.0.0: formalize the on-disk format guarantee with a documented migration policy for any future breaking change.

---

## License

Dual-licensed under Apache 2.0 and MIT licenses.

