Metadata-Version: 2.4
Name: llama-index-graph-stores-ladybug
Version: 0.3.3
Summary: llama-index Ladybug graph store integration
Author-email: Your Name <you@example.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: <4.0,>=3.10
Requires-Dist: ladybug>=0.16.1
Requires-Dist: llama-index-core<0.15,>=0.14.20
Provides-Extra: dev
Requires-Dist: black[jupyter]<=23.9.1,>=23.7.0; extra == 'dev'
Requires-Dist: codespell[toml]>=v2.2.6; extra == 'dev'
Requires-Dist: diff-cover>=9.2.0; extra == 'dev'
Requires-Dist: ipython==8.10.0; extra == 'dev'
Requires-Dist: jupyter<2,>=1.0.0; extra == 'dev'
Requires-Dist: mypy==0.991; extra == 'dev'
Requires-Dist: nbstripout>=0.9.0; extra == 'dev'
Requires-Dist: pre-commit==3.2.0; extra == 'dev'
Requires-Dist: pylint==2.15.10; extra == 'dev'
Requires-Dist: pytest-cov>=6.1.1; extra == 'dev'
Requires-Dist: pytest-mock>=3.11.1; extra == 'dev'
Requires-Dist: pytest>=8.4.0; extra == 'dev'
Requires-Dist: ruff==0.11.11; extra == 'dev'
Requires-Dist: types-deprecated>=0.1.0; extra == 'dev'
Requires-Dist: types-protobuf<5,>=4.24.0.4; extra == 'dev'
Requires-Dist: types-pyyaml<7,>=6.0.12.12; extra == 'dev'
Requires-Dist: types-redis==4.5.5.0; extra == 'dev'
Requires-Dist: types-requests==2.28.11.8; extra == 'dev'
Requires-Dist: types-setuptools==67.1.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# llama-index-ladybug

[LlamaIndex](https://www.llamaindex.ai/) graph store integration for [Ladybug](https://github.com/LadybugDB/ladybug) — an embedded graph database built for query speed and scalability. Ladybug is optimized for handling complex analytical workloads on very large databases and provides a set of retrieval features, such as full text search and vector indices.

The database was formerly known as [Kùzu](https://kuzudb.com/).

## Installation

```bash
uv pip install llama-index-graph-stores-ladybug
```

## Quick Start

### LadybugPropertyGraphStore — unstructured (default)

No schema required. All LLM-extracted entities are stored as Entity type and only relation types are Links and Mentions.

```python
from pathlib import Path
import ladybug as lb
from llama_index.graph_stores.ladybug import LadybugPropertyGraphStore
from llama_index.core import PropertyGraphIndex, SimpleDirectoryReader
from llama_index.embeddings.openai import OpenAIEmbedding
from llama_index.llms.openai import OpenAI

# Create a Ladybug database
Path("my_graph.ladybug").unlink(missing_ok=True)
db = lb.Database("my_graph.ladybug")

embed_model = OpenAIEmbedding(model_name="text-embedding-3-small")

graph_store = LadybugPropertyGraphStore(
    db,
    use_vector_index=True,
    embed_model=embed_model,
)

documents = SimpleDirectoryReader("./data").load_data()

index = PropertyGraphIndex.from_documents(
    documents,
    embed_model=embed_model,
    property_graph_store=graph_store,
    show_progress=True,
)

query_engine = index.as_query_engine()
response = query_engine.query("What are the main topics in these documents?")
print(response)
```

### LadybugPropertyGraphStore — structured schema

Pass a `relationship_schema` to guide the LLM towards your schema.

`strict_schema=False` (default) allows the graph to expand beyond the declared types — off-schema entities and relations are stored in overflow tables alongside the schema-defined ones.

`strict_schema=True` enforces the schema strictly — off-schema entities and relations are silently dropped at ingest.

```python
graph_store = LadybugPropertyGraphStore(
    db,
    relationship_schema=[
        ("PERSON", "WORKS_FOR", "ORGANIZATION"),
        ("PERSON", "KNOWS", "PERSON"),
    ],
    has_structured_schema=True,
    strict_schema=False,   # True to reject off-schema types entirely
    use_vector_index=True,
    embed_model=embed_model,
)
```

### LadybugGraphStore

```python
import ladybug as lb
from llama_index.graph_stores.ladybug import LadybugGraphStore
from llama_index.core import KnowledgeGraphIndex, StorageContext, SimpleDirectoryReader

db = lb.Database("my_graph.ladybug")
graph_store = LadybugGraphStore(db)
storage_context = StorageContext.from_defaults(graph_store=graph_store)

documents = SimpleDirectoryReader("./data").load_data()

index = KnowledgeGraphIndex.from_documents(
    documents,
    max_triplets_per_chunk=2,
    storage_context=storage_context,
)

query_engine = index.as_query_engine()
response = query_engine.query("What are the main topics in these documents?")
print(response)
```

## Features

- **Embedded** — no server required; the database is a local directory
- **Cypher queries** — full Cypher support via `structured_query()`
- **Vector index** — HNSW vector index on chunk nodes for similarity search, built into the graph store
- **Structured schemas** — optionally enforce entity/relation types for higher-quality triple extraction
- **Both graph store APIs** — supports both `PropertyGraphIndex` (`LadybugPropertyGraphStore`) and the legacy `KnowledgeGraphIndex` (`LadybugGraphStore`)

## Documentation

- [API Reference](docs/api/README.md)
- [Property Graph Notebook](docs/notebooks/property_graph_ladybug.ipynb)
- [GraphStore Notebook](docs/notebooks/LadybugGraphDemo.ipynb)

## Development

```bash
# Clone and set up
git clone https://github.com/stevereiner/llama-index-ladybug
cd llama-index-ladybug
uv sync --group dev

# Run tests
pytest

# Install pre-commit hooks (strips notebook outputs on commit)
pre-commit install
```

## Acknowledgements

Started from the Kuzu → Ladybug llama-index support port by [@adsharma](https://github.com/adsharma) ([PR #20232](https://github.com/run-llama/llama_index/pull/20232)) — a proposed LadybugDB (formerly Kùzu) integration into the upstream llama-index repo.

## Requirements

- Python 3.10+
- `ladybug >= 0.15.3`
- `llama-index-core >= 0.14.20`
