Search locally.
Keep the evidence.

API example

# Python: choose base or graph; embedding is optional
python -m pip install retrievalkit==0.1.0
python -m pip install retrievalkit-graph==0.1.0
python -m pip install retrievalkit-embedding==0.1.0

# Node.js: choose base or graph; embedding is optional
npm install @gungorbasa/retrievalkit@0.1.0
npm install @gungorbasa/retrievalkit-graph@0.1.0
npm install @gungorbasa/retrievalkit-embedding@0.1.0

# Browser: two independent Worker packages
npm install @gungorbasa/retrievalkit-browser@0.1.0
npm install @gungorbasa/retrievalkit-browser-embedding@0.1.0

// Package.swift
.package(
  url: "https://github.com/gungorbasa/RetrievalKit.git",
  from: "0.1.0"
)

// build.gradle.kts — JVM
implementation("io.github.gungorbasa:retrievalkit-graph:0.1.0")
implementation("io.github.gungorbasa:retrievalkit-embedding:0.1.0")

// build.gradle.kts — Android
implementation("io.github.gungorbasa:retrievalkit-graph-android:0.1.0")
implementation("io.github.gungorbasa:retrievalkit-embedding-android:0.1.0")

Run from source

git clone https://github.com/gungorbasa/RetrievalKit.git
cd RetrievalKit

API example

import RetrievalKit

@main
struct ApolloSearch {
  static func main() async throws {
    let builder = try RetrievalDatabase.Builder(
      corpusID: "apollo",
      encoding: .f32
    )
    try await builder.upsert(
      Document(
        id: "decision-swift",
        text: "Apollo chose Swift for its Apple client."
      ),
      embedding: [1, 0]
    )
    let database = try await builder.build()
    let hits = try await database.search(
      text: "Why did we choose Swift?",
      embedding: [1, 0],
      alpha: 0.6,
      limit: 1
    )
    print(hits[0].documentID)
  }
}

// Build first:
// scripts/build-xcframework.sh --macos-only

Run from source

scripts/build-xcframework.sh --macos-only
scripts/run-swift-quickstart.sh base-retrieval

API example

import { RetrievalDatabaseBuilder }
  from "@gungorbasa/retrievalkit";

const builder = new RetrievalDatabaseBuilder({
  corpusId: "apollo"
});
await builder.add([{
  id: "decision-swift",
  text: "Apollo chose Swift.",
  embedding: new Float32Array([1, 0, 0])
}]);

const database = await builder.build();
try {
  const hits = await database.search({
    mode: "hybrid",
    text: "Why Swift?",
    embedding: new Float32Array([1, 0, 0]),
    alpha: 0.6
  });
  console.log(hits[0]?.documentId);
} finally {
  await database.close();
}

Run from source

cd wrappers/typescript
npm ci
npm run preflight
npm run build
node base/examples/retrieval.mjs

API example

import { RetrievalKitBrowser }
  from "@gungorbasa/retrievalkit-browser";
import { BrowserEmbedder }
  from "@gungorbasa/retrievalkit-browser-embedding";

const kit = await RetrievalKitBrowser.create({
  worker: () => new Worker(
    new URL("./retrievalkit.worker.js", import.meta.url),
    { type: "module" },
  ),
});

const embedder = await BrowserEmbedder.load({
  worker: () => new Worker(
    new URL("./embedding.worker.js", import.meta.url),
    { type: "module" },
  ),
  execution: "auto",
});

API example

import ai.retrievalkit.Document
import ai.retrievalkit.RetrievalDatabase
import ai.retrievalkit.VectorEncoding

fun main() {
    RetrievalDatabase.Builder(
        "apollo",
        encoding = VectorEncoding.F32,
    ).use { builder ->
        builder.upsert(
            Document("decision-swift", "Apollo chose Swift."),
            floatArrayOf(1f, 0f),
        )
        builder.build().use { database ->
            val hits = database.search(
                text = "Why Swift?",
                embedding = floatArrayOf(1f, 0f),
                alpha = 0.6f,
                limit = 1,
            )
            println(hits.first().documentId)
        }
    }
}

Run from source

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:run

API example

from retrievalkit_graph import (
    GraphDatabaseBuilder,
    GraphRecordNode,
    GraphSchema,
)

builder = GraphDatabaseBuilder(
    corpus_id="topics",
    schema=GraphSchema(
        record_nodes=[
            GraphRecordNode("Topic", "Topic", ["title"])
        ]
    ),
)
builder.upsert({
    "id": "retrieval",
    "record_type": "Topic",
    "fields": {"title": "Local retrieval"},
})
database = builder.build()

selection = database.graph.query_equals(
    node_type="Topic",
    field="title",
    values="Local retrieval",
)
print(selection.matches[0]["node"]["record_id"])

Run from source

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

API example

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

schema = GraphSchema(
    record_nodes=[
        GraphRecordNode("Project", "Project", ["title"]),
        GraphRecordNode("Note", "Note", ["title"]),
    ],
    relationships=[
        GraphRelationship(
            "contains", "Project", "Note", "note_ids", "many"
        )
    ],
)
builder = GraphRetrievalDatabaseBuilder(
    corpus_id="project-notes",
    graph=schema,
    encoding="f32",
)
builder.upsert({
    "id": "apollo",
    "record_type": "Project",
    "fields": {
        "title": "Project Apollo",
        "note_ids": ["decision-swift"],
    },
})
builder.upsert(
    {
        "id": "decision-swift",
        "record_type": "Note",
        "fields": {"title": "Apple client decision"},
        "content": "Apollo chose Swift for its Apple client.",
        "metadata": {"status": "approved"},
    },
    embedding=[1.0, 0.0],
)
database = builder.build()

selection = database.graph.query(
    seeds=[GraphNode("Project", "apollo")],
    traversals=[GraphTraversal("contains")],
)
hits = database.retrieval.hybrid_search(
    "Why did we choose Swift?",
    [1.0, 0.0],
    within=selection,
    where={"status": "approved"},
    alpha=0.6,
    limit=1,
)
print(hits[0]["document_id"])  # decision-swift

Run from source

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

API example

invalid vector dimension: expected 384, got 768;
use the same embedding model for indexing and queries

invalid query parameter 'alpha':
alpha must be finite and between 0 and 1;
use 1 for vector-only or 0 for BM25-only