Metadata-Version: 2.4
Name: llama-index-graph-stores-synapcores
Version: 0.1.0
Summary: LlamaIndex property graph store integration for SynapCores — for GraphRAG.
Project-URL: Homepage, https://synapcores.com
Project-URL: Repository, https://github.com/SynapCores/synapcores-llamaindex
Project-URL: Issues, https://github.com/SynapCores/synapcores-llamaindex/issues
Project-URL: Documentation, https://docs.synapcores.com
Author-email: SynapCores <hello@synapcores.com>
License: MIT
Keywords: ai-native-database,cypher,graph-store,graphrag,llama-index,synapcores
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: llama-index-core<0.13.0,>=0.10.0
Requires-Dist: pydantic>=2.0
Requires-Dist: synapcores>=0.5.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# llama-index-graph-stores-synapcores

LlamaIndex property graph store integration for [SynapCores](https://synapcores.com). Use it as the backend for `PropertyGraphIndex` and GraphRAG workflows.

```bash
pip install llama-index llama-index-graph-stores-synapcores
```

## Quickstart

```python
from llama_index.core import PropertyGraphIndex
from llama_index.core.readers import SimpleDirectoryReader
from llama_index.graph_stores.synapcores import SynapCoresPropertyGraphStore

# 1. docker run -p 8080:8080 -e AIDB_ACCEPT_LICENSE=1 synapcores/community:latest
graph_store = SynapCoresPropertyGraphStore(
    uri="http://localhost:8080",
    graph_name="my_kb",
    embedding_dim=1536,
)

docs = SimpleDirectoryReader("./data").load_data()
index = PropertyGraphIndex.from_documents(
    docs,
    property_graph_store=graph_store,
)

retriever = index.as_retriever()
for node in retriever.retrieve("Who founded Acme and when?"):
    print(node.text)
```

## Configuration

| Argument | Default | Env fallback |
|---|---|---|
| `uri` | `http://localhost:8080` | `SYNAPCORES_URI` |
| `database` | `default` | `SYNAPCORES_DATABASE` |
| `auth_token` | `None` | `SYNAPCORES_AUTH_TOKEN` |
| `graph_name` | `llama_graph` | — |
| `embedding_dim` | `1536` | — |
| `overwrite` | `False` | — |

`graph_name` tags every node + relation so multiple logical graphs can coexist in one engine without colliding.

## Storage model

| LlamaIndex type | Cypher label | Notes |
|---|---|---|
| `EntityNode` (name + type, e.g. "PERSON Alice") | `:Entity {id, name, label, properties_json, graph_name, embedding?}` | Embedding stored when provided |
| `ChunkNode` (source text) | `:Chunk {id, text, label, properties_json, graph_name, embedding?}` | |
| `Relation` (typed edge with properties) | `[:RELATION {label, properties_json, graph_name}]` | `label` is the relation type — preserved as a property so filtering by type doesn't need to parse the edge label |

Free-form properties are JSON-serialized into a single `properties_json` field on each node/relation. Round-tripping is reliable across every engine version (>=v1.7.0.2-ce) the package supports.

## What works in v0.1.0

- `upsert_nodes`, `upsert_relations` — bulk MERGE
- `get`, `get_triplets` — filtered fetch by id / name / property
- `get_rel_map(graph_nodes, depth=2, limit=30, ignore_rels=…)` — depth-bounded BFS expansion, the load-bearing GraphRAG retrieval primitive
- `structured_query(cypher, param_map)` — pass-through Cypher with named-bind translation (`$entity` → `$1`)
- `vector_query(VectorStoreQuery)` — cosine similarity over Chunk-node embeddings (client-side; see Performance below)
- `delete(entity_names, relation_names, properties, ids)` — selective delete; refuses to wipe the entire graph without at least one selector
- `aupsert_nodes`, `aupsert_relations`, `aget_*`, `astructured_query`, `avector_query` — async via `asyncio.to_thread`

## Performance

`vector_query` in v0.1.0 pulls every Chunk's embedding and scores client-side — O(N) in chunk count, fine for graphs up to ~thousands of chunks. The v0.2.0 path stores chunk embeddings in a parallel SQL table with HNSW for sub-linear lookup. Native `get_rel_map` via variable-length path matches (`MATCH p = (a)-[*1..N]-(b)`) is also queued for v0.2.0 — current path is single-hop Cypher in a Python BFS.

## Engine requirements

- `synapcores/community:v1.7.0.2-ce` or newer (needs Cypher on `/v1/query/execute` — fixed in #223)

## License

MIT
