RetrievalKit Graph for Python

retrievalkit-graph is RetrievalKit with graph capabilities included. The aggregate Python distribution supports graph-only databases and complete graph-scoped semantic or hybrid retrieval. It mirrors the RetrievalKitGraph Swift package; the smaller base retrievalkit distribution remains graph-free.

For a human-readable Project Apollo walkthrough and decision guide, start with the canonical Python guide.

Install this distribution instead of retrievalkit in a graph-enabled process:

cd wrappers/python-graph
maturin develop
python examples/graph_quickstart.py
python examples/graph_retrieval_quickstart.py

graph_quickstart.py is graph-only. graph_retrieval_quickstart.py shows the combined graph-plus-retrieval database. The base distribution's examples/database_quickstart.py covers retrieval without graph code.

The combined builder keeps graph schema and retrieval configuration explicit:

from retrievalkit_graph import (
    GraphNode,
    GraphRecordNode,
    GraphRelationship,
    GraphRetrievalDatabaseBuilder,
    GraphSchema,
    GraphTraversal,
)

schema = GraphSchema(
    record_nodes=[GraphRecordNode("Topic", "Topic", ["title"])],
    relationships=[
        GraphRelationship(
            "related_to",
            "Topic",
            "Topic",
            "related_id",
            "optional_one",
        )
    ],
)
builder = GraphRetrievalDatabaseBuilder(
    corpus_id="topics",
    graph=schema,
)
builder.upsert(
    {
        "id": "alpha",
        "record_type": "Topic",
        "fields": {"title": "Alpha"},
        "content": "Graph retrieval",
        "metadata": {"tenant": "blue"},
    },
    embedding=embedding,
)
database = builder.build()

selection = database.graph.query(
    seeds=[GraphNode("Topic", "alpha")],
    traversals=[GraphTraversal("related_to", max_hops=2)],
)
projection = database.graph.project_candidates(
    selection,
    where={"tenant": "blue"},
)
hits = database.retrieval.semantic_search(
    query_embedding,
    within=selection,
    where={"tenant": "blue"},
)
hybrid_hits = database.retrieval.hybrid_search(
    "graph retrieval",
    query_embedding,
    within=selection,
    where={"tenant": "blue"},
    alpha=0.6,
)

GraphDatabaseBuilder(corpus_id=..., schema=...) builds graph-only state and accepts capability-neutral records through upsert(record), with no embedding parameter. GraphRetrievalDatabaseBuilder accepts the same simple record plus an optional direct embedding=. Graph-only records may arrive before the first searchable record; Rust queues them, infers dimension from the first embedding, and derives hidden chunk identity from record content. Combined databases deliberately expose database.graph and database.retrieval query namespaces so graph traversal and semantic/hybrid retrieval remain separate capabilities.

The older RecordInput/public chunk-key and nested embedding-map methods remain available as an advanced compatibility surface.

Graph queries are deterministic and bounded by GraphQueryLimits. Selections are tied to the corpus generation that produced them and can scope semantic or hybrid retrieval through within=. Metadata filtering is supported by both retrieval methods through where=. database.graph.project_candidates(selection, where=...) materializes stable GraphChunkIdentity(record_id, chunk_key) values in lexical order. Rust owns the generation/corpus checks, metadata-filter intersection, and the reported source-node and before/after candidate counts. Hybrid alpha is query-time: 1 is vector-only, 0 is BM25-only, and the default is 0.6. Every retrieval hit includes effective metadata. Hybrid traces expose alpha, source ranks, normalized scores, and matched terms; graph scope only constrains the candidate set.

Databases and selections support close() and context managers. Graph queries also support cooperative cancellation and second-based timeouts. Rust performs schema validation, graph traversal, filtering, ranking, persistence, and hydration; the Python layer only converts typed inputs and results. Graph query requests, selections, candidate projections, and retrieval results cross PyO3 as typed values without JSON. Cold schema and ingestion remain JSON-based.

Because both packages embed native RetrievalKit core symbols, import either retrievalkit or retrievalkit_graph in one process, not both.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for gungorbasa from gravatar.com gungorbasa

License

Apache-2.0

Requires

Python <3.15, >=3.10

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

retrievalkit_graph-0.1.0-cp314-cp314-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

retrievalkit_graph-0.1.0-cp313-cp313-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

retrievalkit_graph-0.1.0-cp312-cp312-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

retrievalkit_graph-0.1.0-cp311-cp311-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

retrievalkit_graph-0.1.0-cp310-cp310-macosx_11_0_arm64.whl (1.4 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file retrievalkit_graph-0.1.0-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for retrievalkit_graph-0.1.0-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1b59ae0c68e96bd81def089a880d57316992a73bec886cdef48af060ffd8862b
MD5 282cdfeb30fe3c3c78eccbbfd58791c6
BLAKE2b-256 66f379d9a3f0b40ea823ffac32a042d0b3beb60e9e001be12cd165663e0ca834

See more details on using hashes here.

Provenance

The following attestation bundles were made for retrievalkit_graph-0.1.0-cp314-cp314-macosx_11_0_arm64.whl:

Publisher: publish-release.yml on gungorbasa/RetrievalKit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file retrievalkit_graph-0.1.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for retrievalkit_graph-0.1.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7c6ee2128ad856324ba2b0b52ea4f8cf84bea2a2d02e204bcd6918a3c11472c0
MD5 51001f887051239ed99546787a153355
BLAKE2b-256 59ea926d9928f653d72f38dd06ac477c48e5b9cfdbbaad1b85f567819ace92cf

See more details on using hashes here.

Provenance

The following attestation bundles were made for retrievalkit_graph-0.1.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: publish-release.yml on gungorbasa/RetrievalKit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file retrievalkit_graph-0.1.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for retrievalkit_graph-0.1.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f195217852ed624a8e8562fbf53ebe9ca69e4e2cb3a495843268df5102078541
MD5 4a964e16732bacdc916295a609732b8c
BLAKE2b-256 4a8e62a33d5b751eeabb498778303a5a4e92badac556661b461f60ca5cd7281f

See more details on using hashes here.

Provenance

The following attestation bundles were made for retrievalkit_graph-0.1.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: publish-release.yml on gungorbasa/RetrievalKit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file retrievalkit_graph-0.1.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for retrievalkit_graph-0.1.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9d5fd3cd0a6b9203b5f4120448c7d774622476bda26e0b9d8b76ff77e3c099ce
MD5 70ae4b5c40b2482741780c0d3e81b7d9
BLAKE2b-256 3c9d8f1142d9d1bdbb5be945e859ec91a1893aed1ef88a5a9b122bd8c9d723d4

See more details on using hashes here.

Provenance

The following attestation bundles were made for retrievalkit_graph-0.1.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: publish-release.yml on gungorbasa/RetrievalKit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file retrievalkit_graph-0.1.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for retrievalkit_graph-0.1.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 3db50bbb24995cca2fafa200c21c895ae7b2269e295b5fec28cff23254bbc761
MD5 75db0a7ccb82ee553217c87984f32e64
BLAKE2b-256 bfd3f3b388e378579b136c54f9b6abdc0c3a73f4fcfd23cc5a1c4bb87624c759

See more details on using hashes here.

Provenance

The following attestation bundles were made for retrievalkit_graph-0.1.0-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: publish-release.yml on gungorbasa/RetrievalKit

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

5 files

Pre-release

0.0.0a0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page