Quickstart

Go from an empty environment to your first governed retrieval query. This guide uses the real Python SDK surface and clearly marks the packaged v0.9 step that is still being finalized.

Prerequisites

For the current source-build path, use Rust 1.98 and the repository instructions. Python is used below for the client example. Docker Compose is the target public v0.9 onboarding path.

1. Run Ketebe

docker compose up -d
curl http://localhost:7610/health

Until those artifacts are published, build and run Ketebe from the source repository.

2. Connect a client

from ketebe import Client, CreateCollection, DocumentUpsert, QueryRequest, RecordId

client = Client("http://127.0.0.1:7610")

3. Create a collection

A collection defines the vector dimensions and similarity semantics for the records you will retrieve.

client.create_collection(
    CreateCollection("docs", 384, "cosine")
)

4. Ingest a document

Use document ingestion when you want Ketebe to own the document-to-searchable-state path rather than precomputing every vector in application code.

client.upsert_document(
    "docs",
    RecordId.string("intro"),
    DocumentUpsert(
        text="Ketebe is an AI-native retrieval platform.",
        metadata={"source": "guide"},
    ),
)

5. Run a query

result = client.query(
    "docs",
    QueryRequest(
        text="What is Ketebe?",
        top_k=5,
        search_profile="balanced",
        explain=True,
    ),
)

The balanced profile is designed to express retrieval policy at the platform layer. Explainability can surface how the query was processed instead of leaving relevance behavior opaque to the caller.

Next steps