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

Vector index extension (Ladybug 0.18.x+)

With use_vector_index=True (the default), the store loads Ladybug's VECTOR extension on first use (INSTALL vector; LOAD vector;). INSTALL downloads it over the network the first time, then caches it under ~/.lbdb/extension/ — after that it works offline. Set use_vector_index=False to skip vector indexing entirely. (On Ladybug ≤ 0.16.x this was a core function, no download needed.)

OpenSSL 3 requirement

The VECTOR extension dynamically links OpenSSL 3. OpenSSL is not bundled with Ladybug (it's security-sensitive and needs its own update cadence), so it must be present on your system — install it yourself and keep it patched. If it's missing, LOAD vector fails and vector indexing is unavailable.

Windows

The extension links libssl-3-x64.dll and libcrypto-3-x64.dll; without them LOAD vector fails with error 126 ("The specified module could not be found"). Install with Chocolatey, elevated:

choco install openssl.light

This installs OpenSSL 3.x to C:\Program Files\OpenSSL, copies libssl-3-x64.dll / libcrypto-3-x64.dll into C:\Windows\System32, and appends C:\Program Files\OpenSSL\bin to the system PATH. Because the DLLs land in System32, LOAD vector then works in any shell with no further PATH setup.

Then verify in a new shell (so PATH updates):

where.exe libssl-3-x64.dll
where.exe libcrypto-3-x64.dll

Important notes:

• It must be OpenSSL 3.x. OpenSSL 4 renames the libraries to libssl-4-x64.dll / libcrypto-4-x64.dll, which do not satisfy the extension. Avoid "install latest OpenSSL" package sources — at the time of writing winget install ShiningLight.OpenSSL.Light ships 4.x and will not work.
• The names must be exactly libssl-3-x64.dll / libcrypto-3-x64.dll; builds shipping libssl-3.dll (no -x64) or libeay32.dll won't satisfy it either.
• libssl and libcrypto must be the same OpenSSL version.
• Run choco elevated — a non-admin choco install bootstraps Chocolatey into your user profile and can hang installing its vcredist140-x64 dependency.
• If a prior install is already recorded, choco install no-ops; choco uninstall openssl.light first (or use --force).
• A new shell is required after any PATH change; services, Docker, and some IDE-launched terminals may not inherit it.

macOS

brew install openssl@3

Apple's bundled /usr/bin/openssl is LibreSSL, not OpenSSL, and isn't a substitute. Homebrew's openssl@3 is keg-only, so if the extension still can't find it, expose the Homebrew lib directory (e.g. add $(brew --prefix openssl@3)/lib to DYLD_LIBRARY_PATH).

Linux

The distro provides OpenSSL 3 (libssl.so.3 / libcrypto.so.3) and it's usually already installed. If not:

Slim container images often omit it — install it in the image if you hit a load failure.

Offline / CI / proxied

Pre-download the extension once where the network is available (caches it for later offline LOAD):

python -c "import ladybug, tempfile, os; ladybug.Connection(ladybug.Database(os.path.join(tempfile.mkdtemp(), 'db'))).execute('INSTALL vector;')"

For Docker, run that during the image build (and ensure OpenSSL 3 is installed in the image), or copy the populated ~/.lbdb/extension/ into the image.

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.18.2
• llama-index-core >= 0.14.20
• For the vector index on Ladybug 0.18.x+: the downloadable VECTOR extension (see Vector index extension above) — needs network on first use, then cached under ~/.lbdb/extension/. It also requires OpenSSL 3 on the system (Windows needs libssl-3-x64.dll / libcrypto-3-x64.dll) — see the OpenSSL 3 requirement section.