PyPI

Python local retrieval guide

Choose the flat or graph distribution, run hybrid retrieval, inspect traces, and persist a local Python database.

macOS arm64, CPython 3.10-3.14View the v0.1.0 source guide →

On this page

Install

Choose exactly one retrieval distribution. The graph distribution already contains flat retrieval. The embedding distribution is independent.

# Flat corpus
python -m pip install retrievalkit==0.1.0

# Graph-only and graph-scoped retrieval
python -m pip install retrievalkit-graph==0.1.0

# Optional local FP32 MiniLM provider
python -m pip install retrievalkit-embedding==0.1.0

The v0.1.0 wheels target macOS arm64 on CPython 3.10-3.14. Windows and Ubuntu source checks are portability evidence, not published wheel support.

Choose a database

RetrievalDatabase fits a flat collection.
GraphDatabase traverses relationships without embeddings.
GraphRetrievalDatabase scopes retrieval with application-supplied relationships.

Graph-only builders accept no metric, vector encoding, dimension, or embedding.

Build and search a flat corpus

from retrievalkit import Document, RetrievalDatabaseBuilder

builder = RetrievalDatabaseBuilder(
    corpus_id="project-notes",
    metric="dot_product",
    encoding="f32",
)
builder.upsert(
    Document(
        id="decision-swift",
        text="Apollo chose Swift for its Apple platform client.",
        metadata={"project": "apollo", "status": "approved"},
    ),
    embedding=[1.0, 0.0],
)
database = builder.build()

hits = database.retrieval.hybrid_search(
    "Why did we choose Swift?",
    [1.0, 0.0],
    alpha=0.6,
    where={"project": "apollo", "status": "approved"},
    limit=1,
)
print(hits[0]["document_id"])

The expected document ID is decision-swift. Rust infers dimension from the first embedding and owns canonical identity, validation, filtering, and ranking.

Scope with a graph

The graph answers where to search. Retrieval answers which eligible candidate ranks first.

selection = graph_retrieval_database.graph.query(
    seeds=[GraphNode("Project", "apollo")],
    traversals=[GraphTraversal("contains")],
)

hits = graph_retrieval_database.retrieval.hybrid_search(
    "Why did we choose Swift?",
    [1.0, 0.0],
    within=selection,
    where={"status": "approved"},
    alpha=0.6,
    limit=1,
)

RetrievalKit validates and traverses relationships supplied by the application. It does not extract or invent a graph.

Inspect a ranking trace

Hybrid hits retain each component of the fused result.

hit = hits[0]
print(hit["trace"]["vector_rank"])
print(hit["trace"]["keyword_rank"])
print(hit["trace"]["matched_terms"])
print(hit["trace"]["vector_score"])

Persist and reload

from pathlib import Path
from retrievalkit import RetrievalDatabase

snapshot = Path("project-notes.rk")
database.save(snapshot)
RetrievalDatabase.validate(snapshot)
reloaded = RetrievalDatabase.load(snapshot)

Use GraphRetrievalDatabase for a snapshot containing graph, corpus, retrieval indexes, and metadata together.

Run the source quickstart

PYTHON_BIN=python3 scripts/check-python-wrapper.sh
target/python-wrapper-check-venv-py*/bin/python \
  wrappers/python/examples/database_quickstart.py

Use scripts/check-python-graph-wrapper.sh for graph-only and graph-scoped examples.

Choose the database boundary

Three query paths

Compare the same job in Python. These are separate APIs, not modes hidden behind one query.

Hybrid vector + BM25

RetrievalDatabase

Rank the whole corpus with exact vector similarity and BM25.

Python

hits = retrieval_database.retrieval.hybrid_search(
    "What did we decide about offline sync?",
    query_embedding,
    alpha=0.6,
    limit=5,
)

Graph query alone

GraphDatabase

Select records by relationship. No embedding or retrieval ranker is involved.

Python

selection = graph_database.graph.query(
    seeds=[GraphNode("Notebook", "product-research")],
    traversals=[GraphTraversal("references")],
)

Graph + vector + BM25

GraphRetrievalDatabase

Select candidates with the graph, then rank only that scope with vector + BM25.

Python

selection = graph_retrieval_database.graph.query(
    seeds=[GraphNode("Project", "mobile-app")],
    traversals=[GraphTraversal("contains")],
)

hits = graph_retrieval_database.retrieval.hybrid_search(
    "Why is cold start slow on Android?",
    query_embedding,
    alpha=0.6,
    within=selection,
    limit=5,
)