RetrievalKit is one local retrieval engine for Swift, Python, TypeScript/Node, and Kotlin apps. Use it for exact vector and BM25 hybrid retrieval, graph-only search with no embeddings, or graph-scoped retrieval that ranks only the records related to the user's context. One Rust core, native APIs, and no retrieval server. The browser/WebAssembly retrieval and independent embedding packages run in dedicated Workers and both join the v0.1.0 release inventory. The live local website Q&A orchestration and browser SLM remain application layers rather than SDK packages.
Public docs · Swift guide · Python guide · TypeScript guide · Kotlin guide · Run from source · See validated benchmarks
RetrievalKit v0.1.0 is published as a preview. The commands below install the qualified initial packages. Platform limits are part of the support contract; in particular, Android remains a packaging-qualified arm64-v8a preview with no live-device inference or performance qualification.
| SDK | Intended public install | Publication status | Qualified initial target |
|---|---|---|---|
| Swift | .package(url: "https://github.com/gungorbasa/RetrievalKit.git", from: "0.1.0") |
Published preview | macOS 14+ arm64; iOS 15+ arm64 device and simulator |
| Python | python -m pip install retrievalkit-graph==0.1.0 |
Published preview | macOS arm64; CPython 3.10–3.14 |
| Node.js | npm install @gungorbasa/retrievalkit-graph@0.1.0 |
Published preview | macOS arm64; Node.js 22.13+ or 24 LTS |
| Browser | npm install @gungorbasa/retrievalkit-browser@0.1.0 |
Published preview | Dedicated Worker; portable and SIMD128 WASM tiers |
| Kotlin/JVM | implementation("io.github.gungorbasa:retrievalkit-graph:0.1.0") |
Published preview | macOS arm64 native library; build with JDK 17, run bytecode on Java 11+ |
| Android | implementation("io.github.gungorbasa:retrievalkit-graph-android:0.1.0") |
Published preview | Packaging qualified for Android API 24+ arm64-v8a; live-device inference and performance unqualified |
The public identities and trusted publishers are configured, and v0.1.0 is
available from all four distribution channels. For Swift, add one package and select RetrievalKit for a flat
corpus, RetrievalKitGraph for relationships plus retrieval, or both. For
Python, Node, and Kotlin, choose exactly one native distribution in a process:
graph-enabled packages already include base retrieval.
The checked-in source quickstarts remain available for contributors and unsupported source targets.
Choose the smallest product that matches the question. The three paths share the same canonical corpus and Rust-owned correctness guarantees, but you do not have to configure capabilities you do not use.
| Query path | Use | What it does |
|---|---|---|
| Retrieval search | RetrievalDatabase |
Exact vector, BM25 text, or hybrid ranking over a flat corpus |
| Graph search | GraphDatabase |
Traverses relationships and projects stable candidates with no retrieval configuration or embeddings |
| Graph-scoped retrieval | GraphRetrievalDatabase |
Uses a graph query to choose candidates, then runs exact vector, BM25 text, or hybrid ranking inside that scope |
Within either retrieval-capable product, the query inputs select the ranking
mode: pass an embedding for vector-only search, text for BM25-only search, or
both with alpha for hybrid search. Metadata filters are hard constraints and
work with every retrieval variation.
Graph search is a complete standalone path. If you only need to follow
relationships, match graph fields, or project related records, build a
GraphDatabase; no embedding model or vector index is involved.
Imagine a workspace with notes from many teams and projects. Someone opens Project Apollo and asks:
Why did we choose Swift?
RetrievalKit can use three kinds of evidence without turning them into three different products:
- The Apollo relationship selects notes that belong to that project.
- A metadata rule can require
status = approved. - Semantic similarity and BM25 keyword evidence rank the remaining notes.
The result is the Apollo architecture decision—not an unrelated note that happens to mention Swift.
Graph scope is not a separate result engine or a third scoring signal. It chooses the candidate neighborhood; the same hybrid ranker then orders those candidates. Relationships are supplied by your application. RetrievalKit does not automatically extract or invent a graph.
Hybrid search should be the normal default when a user types a query: vector similarity catches paraphrases while BM25 preserves exact names and terms. Choose vector-only when there is no useful query text—such as finding records similar to another record—or when keyword overlap should intentionally have no effect.
Graph scope and metadata filters solve different problems. A graph answers “what is related to this record?” A filter answers “which records satisfy this rule?” They can be used together, or the graph can be queried on its own.
Indexing, graph traversal, filtering, ranking, trace construction, and persistence all run in the shared Rust core. The language wrappers provide idiomatic APIs over the same ownership model and correctness guarantees.
Embeddings are caller-provided. To keep the complete ingestion and query flow private, use a local embedding provider such as a Core ML model through EmbeddingKit. If your application sends text to a remote embedding service, that embedding step is not local or private, even though RetrievalKit still indexes and searches locally.
The canonical guides use the same Project Apollo data and explain what to choose, when, and why:
- Swift guide — retrieval-only search, graph-only traversal, graph-scoped retrieval, traces, persistence, and local embeddings.
- Python guide — all three query paths with Pythonic builders, checked-in examples, lifecycle, and packaging.
- TypeScript guide — asynchronous Node.js builders and typed N-API values on macOS arm64.
- Kotlin guide — Kotlin/JVM and Android arm64-v8a builders over a typed JNI boundary.
The complete programs are checked into the repository and are exercised by the wrapper validation scripts, so the documentation stays tied to executable examples.
Choose the graph-enabled distribution when relationships are meaningful to
your product. It includes both GraphDatabase for graph-only search and
GraphRetrievalDatabase for graph-scoped retrieval; the latter also includes
exact vector, BM25, hybrid ranking, filters, traces, and persistence. Choose
the base distribution for flat corpora that do not need traversal.
| SDK | Capability | Status |
|---|---|---|
Swift RetrievalKit |
Base corpus and retrieval | Published preview |
Swift RetrievalKitGraph |
Graph aggregate with retrieval | Published preview |
Swift EmbeddingKit |
Local Core ML embedding integration | Published preview |
Swift RetrievalKitPipeline |
Chunk → embed → index → search orchestration | Published preview |
Python retrievalkit |
Base corpus and retrieval | Published preview |
Python retrievalkit-graph |
Graph aggregate with retrieval | Published preview |
Python retrievalkit-embedding |
Local FP32 MiniLM embedding integration | Published preview |
TypeScript @gungorbasa/retrievalkit |
Base corpus and retrieval; selected npm identity | Published preview |
TypeScript @gungorbasa/retrievalkit-graph |
Graph aggregate with retrieval; selected npm identity | Published preview |
TypeScript @gungorbasa/retrievalkit-embedding |
Local FP32 MiniLM embedding integration | Published preview |
Browser @gungorbasa/retrievalkit-browser |
Worker-owned base, graph, and graph-scoped WASM retrieval | Published preview |
Browser @gungorbasa/retrievalkit-browser-embedding |
Worker-owned local FP32 MiniLM embedding | Published preview |
Kotlin/JVM io.github.gungorbasa:retrievalkit |
Base corpus and retrieval | Published preview |
Kotlin/JVM io.github.gungorbasa:retrievalkit-graph |
Graph aggregate with retrieval | Published preview |
Kotlin/JVM io.github.gungorbasa:retrievalkit-embedding |
Local FP32 MiniLM embedding integration | Published preview |
Android io.github.gungorbasa:retrievalkit-android |
Base AAR for arm64-v8a | Published preview; live-device unqualified |
Android io.github.gungorbasa:retrievalkit-graph-android |
Graph aggregate AAR for arm64-v8a | Published preview; live-device unqualified |
Android io.github.gungorbasa:retrievalkit-embedding-android |
Local FP32 MiniLM embedding AAR for arm64-v8a | Published preview; live-device inference unqualified |
Python, Node, and Kotlin base and graph native aggregates are mutually exclusive within one process. Their graph-enabled distributions already contain the base native retrieval capabilities. Node loaders enforce this with a process-global guard; JVM and Android applications must depend on exactly one artifact.
Android API 24+ arm64-v8a is an explicit v0.1.0 preview. Cross-compilation, AAR packaging, closed inventory, ABI/architecture, JVM/JNI-contract, and fresh consumer dependency-resolution/compilation checks remain release gates. No physical Android device was available, so live-device model acquisition, inference, lifecycle, memory, thermal behavior, offline restart, compatibility, and performance are unqualified and deferred. That missing evidence does not block v0.1.0, and RetrievalKit does not claim production readiness, device compatibility, or Android performance beyond the existing evidence.
Swift uses one package and one graph-capable native aggregate. Add the package
once, then select RetrievalKit, RetrievalKitGraph, or both products.
RetrievalKitGraphFFI contains the shared base and graph entry points, so a
Swift application never links competing native aggregates. Selecting only
RetrievalKit keeps graph APIs out of the Swift target, although SwiftPM still
downloads the graph-capable binary.
GraphRetrievalDatabase is the complete graph-scoped search product.
GraphDatabase is available for applications that need only traversal and
candidate projection, with no retrieval configuration or embeddings.
For a source checkout, start at the repository root. Each quickstart below checks its required toolchain before compiling and runs a checked-in example; none publishes or downloads a RetrievalKit package from a public registry.
The initial wheel target is macOS arm64 with CPython 3.10-3.14. Install Rust and a supported Python interpreter, then build the graph-enabled wrapper once:
PYTHON_BIN=python3 scripts/check-python-graph-wrapper.shRun graph-only search with no embeddings:
target/python-graph-wrapper-check-venv-py*/bin/python \
wrappers/python-graph/examples/graph_quickstart.pyExpected output includes: graph-only=retrieval.
Or run graph-scoped hybrid retrieval:
target/python-graph-wrapper-check-venv-py*/bin/python \
wrappers/python-graph/examples/graph_retrieval_quickstart.pyExpected output: graph-hybrid=decision-swift.
The initial Node target is macOS arm64 with Node.js 22.13+ LTS or Node.js 24 LTS. Install Rust and a supported Node.js LTS release, then run:
cd wrappers/typescript
npm ci
npm run preflight
npm run build
node graph/examples/graph-retrieval.mjsThe printed result contains documentId: 'local'.
The initial Kotlin/JVM native package runs on macOS arm64. Building requires Rust and JDK 17; the produced bytecode can run on Java 11+. On macOS, select an installed JDK 17 and run:
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
export PATH="$JAVA_HOME/bin:$PATH"
cd wrappers/kotlin
./scripts/preflight.sh jvm
./scripts/build-native.sh jvm
./gradlew :example-retrieval:runExpected output includes:
kotlin: Kotlin calls the local Rust retrieval core. (1.0).
Run the Swift graph-enabled Apollo example:
scripts/build-xcframework.sh --macos-only --graph
scripts/run-swift-quickstart.sh graph-retrievalExpected output: graph-hybrid=decision-swift.
See the Python guide or Swift guide for complete code, retrieval-only commands, semantic-only variations, persistence, and trace inspection.
The TypeScript guide and Kotlin guide include native build, package-content, local-install, and Android AAR commands.
These are historical observations authorized by the frozen
Phase 6 claim register,
not measurements of the current checkout. They apply to RetrievalKit revision
9c784d2f11b91bb907150aa1b6046880ff89fde6, were reported on 2026-07-21,
and expire on 2027-07-21. Retrieval timings exclude embedding generation.
On the frozen exact F32, 384-dimensional, top-10 benchmark, RetrievalKit revision
9c784d2 delivered the following P50 unfiltered retrieval ratios versus
sqlite-vec 0.1.9 on an Apple M1 Max running macOS 26.5.2. Each lane used 100
measured queries after 20 warmups; embedding was excluded.
| Corpus | sqlite-vec / RetrievalKit P50 | Observation |
|---|---|---|
| 10K | 7.17× | RetrievalKit lower latency |
| 25K | 7.60× | RetrievalKit lower latency |
| 50K | 7.29× | RetrievalKit lower latency |
With the same frozen filter enabled, the P50 retrieval ratios were 10.38× at
10K, 9.08× at 25K, and 8.43× at 50K versus sqlite-vec 0.1.9. This was the
same Apple M1 Max exact F32 workload at revision 9c784d2; embedding was
excluded.
RetrievalKit exact F32 and sqlite-vec 0.1.9 both passed the frozen Phase 5
identity, filtering, deletion, determinism, and reload gates at 10K, 25K, and
50K. This result is scoped to the frozen workload and is not proof for every
possible input.
These ratios describe one exact-search workload, not universal competitor superiority. See the methodology and Mac evidence report.
Across the frozen 296-query HotpotQA linked-abstracts test comparison, graph-scoped weighted-I8 retrieval increased NDCG@10 from 0.858036 to 0.927909 versus whole-corpus weighted-I8 retrieval. There were 121 wins, 157 ties, and 18 losses. This is a scoped quality result, not a universal graph winner or a latency claim.
On the same frozen 296-query weighted-I8 comparison, Recall@10 increased from 0.871622 to 0.957770 and complete-evidence recall@10 increased from 0.743243 to 0.922297. Sixteen queries lost on each recall measure; those losses are part of the result.
The frozen candidate stage reduced the mean per-query candidate set by 972.65× while retaining 96.79% candidate recall and 94.26% candidate complete evidence across 296 valid graph queries, with zero empty scopes. Candidate reduction is not a retrieval-latency speedup and retention was not perfect.
The workload contains 12,670 chunks. Full details are in the retrieval-quality evidence.
On a physical iPhone 17 Pro Max (iPhone18,2, V54AP), the supported 10K,
25K, and 50K F32/I8 product workflows passed. All six graph-free
candidate-to-baseline median-session P95 ratios were at or below the frozen
1.03 gate. Query/prepare evidence used iOS 26.5.1 (23F81); remaining lifecycle
evidence used iOS 26.5.2 (23F84). This is supported-workload qualification for
that device, with embedding excluded, not a claim about other hardware.
V1 targets fewer than 50K chunks. The 100K Phase 4b stress workload remains
not_run_device_safety, produced zero accepted stress artifacts, and is not
eligible for support, performance, latency, quality, product, or marketing
claims.
See the physical-device evidence report and Phase 6 validation result.
- V1 is designed for local indexes with fewer than 50K chunks.
- Initial binary qualification focuses on arm64 Apple platforms: macOS 14+ and iOS 15+, including the arm64 iOS Simulator. The initial Node target is macOS arm64; Android API 24+ arm64-v8a ships as an explicit preview with live-device inference, compatibility, and performance unqualified.
- Browser/WebAssembly retrieval and browser embedding are implemented, desktop-qualified in source, and included as separate v0.1.0 npm packages. The retrieval tarball carries portable and SIMD128 WASM tiers; persistence, threaded WASM, Safari, Firefox, and physical mobile browsers remain outside the qualified release surface.
- RetrievalKit is licensed under Apache License 2.0, with company attribution in NOTICE.
- Installation is available through SwiftPM, PyPI, npm, and Maven Central for the qualified preview targets.
- Benchmark evidence supports scoped observations, not a universal competitor claim.
- Public SwiftPM, PyPI, npm, and Maven publication completed from the signed release revision and exact authorized artifacts.
- Swift guide
- Python guide
- TypeScript guide
- Kotlin guide
- Product specification
- Capability-separated architecture
- Swift wrapper API/build reference
- Swift graph wrapper API/build reference
- Python wrapper API/build reference
- Python graph wrapper API/build reference
- TypeScript wrapper API/build reference
- Kotlin/JVM and Android API/build reference
- Release process
- Changelog
- Contributing
- Security policy
RetrievalKit v0.1.0 is a published preview.