Metadata-Version: 2.4
Name: sqlitegraph
Version: 0.4.1
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 :: Only
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 :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: ruff>=0.6 ; extra == 'dev'
Requires-Dist: mypy>=1.10 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'test'
Provides-Extra: dev
Provides-Extra: test
Summary: Embedded graph database with HNSW vector search — Python bindings to the sqlitegraph Rust crate.
Keywords: graph,database,sqlite,embedded,vector,hnsw
Author: Luiz Spies
License: GPL-3.0-only
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://docs.rs/sqlitegraph
Project-URL: Homepage, https://github.com/oldnordic/sqlitegraph
Project-URL: Repository, https://github.com/oldnordic/sqlitegraph

# sqlitegraph

Python bindings to the [`sqlitegraph`](https://crates.io/crates/sqlitegraph)
embedded graph database. Storage, graph algorithms, and HNSW vector search
run in a reviewed Rust core; this package is the Pythonic surface.

> Alpha — API subject to change before 1.0.

## Install

    pip install sqlitegraph

## Quick start

```python
from sqlitegraph import Graph

g = Graph.open_in_memory()
alice = g.add_node(kind="User", name="Alice", data={"age": 30})
order = g.add_node(kind="Order", name="Order-123")
g.add_edge(alice, order, "placed")

print(g.neighbors(alice))
```

## Query language

`Graph.query()` exposes the same Cypher-inspired language as the CLI:

```python
from sqlitegraph import Graph

g = Graph.open_in_memory()
alice = g.add_node(kind="User", name="Alice", data={"age": 30})
bob = g.add_node(kind="User", name="Bob", data={"age": 31})
g.add_edge(alice, bob, "KNOWS")

result = g.query("MATCH (a:User)-[:KNOWS]->(b:User) RETURN a.name, b.name")
print(result["results"])
```

Supported query features include node scans, edge traversal, multi-hop chains,
star/multi-pattern joins, variable-depth edges, `WHERE` with regex/numeric
operators and parentheses, `LIMIT`, `CREATE`, `SET`, `DELETE`, and HNSW vector
search through `CALL db.index.vector.queryNodes(...)`.

## Algorithms

```python
from sqlitegraph import Graph

g = Graph.open_in_memory()
a = g.add_node(kind="Page", name="A")
b = g.add_node(kind="Page", name="B")
c = g.add_node(kind="Page", name="C")
g.add_edge(a, b, "LINKS")
g.add_edge(b, c, "LINKS")
g.add_edge(c, a, "LINKS")

print(g.pagerank(iterations=20))
print(g.connected_components())
print(g.strongly_connected_components())
print(g.label_propagation(50))
print(g.find_cycles(10))
print(g.dominators(a))
```

`critical_path()` is also available for directed acyclic graphs and returns
`{"path": [...], "distance": float, "path_length": int}`.

## HNSW vector search

```python
from sqlitegraph import Graph

g = Graph.open_in_memory()
idx = g.create_hnsw_index("embeddings", dimension=3, metric="cosine")

idx.insert_vector([1.0, 0.8, 0.1], {"label": "graph databases"})
idx.insert_vector([0.1, 0.2, 1.0], {"label": "baking"})

print(idx.search([1.0, 0.9, 0.0], 1))
print(g.list_hnsw_indexes())

g.delete_hnsw_index("embeddings")
```

## Examples

The [`examples/`](./examples/) directory contains runnable scripts:

| Example | What it shows |
|---------|---------------|
| [`01_basic_crud.py`](./examples/01_basic_crud.py) | Nodes, edges, update, delete, query by kind/pattern, degrees |
| [`02_graph_algorithms.py`](./examples/02_graph_algorithms.py) | BFS, k-hop, shortest path, PageRank, Louvain & label-propagation communities, connected components (WCC), strongly-connected components (SCC), cycle search, dominator tree, critical path |
| [`03_vector_search.py`](./examples/03_vector_search.py) | HNSW index creation, insert, search, bulk insert, index listing |
| [`04_social_network.py`](./examples/04_social_network.py) | Realistic network: influencers (PageRank), communities, connection paths, mutual follows |
| [`05_file_backed.py`](./examples/05_file_backed.py) | Persistent `Graph.open(path)`, checkpoint, reopen, cleanup |
| [`06_hybrid_sqlite_hnsw_query.py`](./examples/06_hybrid_sqlite_hnsw_query.py) | sqlite3 application rows + sqlitegraph metadata + HNSW + `Graph.query()` expansion |

Run any example from the repo root:

```bash
cd sqlitegraph-py
source .venv/bin/activate
python examples/01_basic_crud.py
```

