llama-index-graph-stores-ladybug 0.3.1

llama-index Ladybug graph store integration

llama-index-ladybug

LlamaIndex graph store integration for 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.

Installation

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.

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.

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

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
• Property Graph Notebook
• GraphStore Notebook

Development

# 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 (PR #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