topk-sdk 0.1.12

Python SDK for topk.io

TopK SDK

Full documentation is available on docs.topk.io.

TopK SDK provides a Python API for managing collections, querying data, and performing advanced search operations, including keyword and vector-based searches. It is designed for scalability and flexibility in building search applications.

Features

• Create and manage collections with custom schemas.
• Perform keyword and vector-based searches with scoring and ranking.
• Upsert and delete documents in collections.
• Support for schema validation and collection listing.
• Pythonic API for seamless integration.

Installation

Install the SDK using pip:

pip install topk-sdk

Usage Examples

Create a client:

from topk_sdk import Client

client = Client(api_key="your_api_key", region="aws-us-east-1-thunderbird")

1. Create a Collection

Define a schema and create a collection.

from topk_sdk.schema import text, vector, vector_index, keyword_index

schema = {
    "title": text().required().index(keyword_index()),
    "embedding": vector(3).required().index(vector_index(metric="cosine")),
}

client.collections().create("books", schema=schema)

2. Upsert Documents

Add or update documents in a collection.

client.collection("books").upsert(
    [
        {"_id": "doc1", "title": "Hello World", "embedding": [1.0, 2.0, 3.0]},
        {"_id": "doc2", "title": "Rust Programming", "embedding": [4.0, 5.0, 6.0]},
    ]
)

3. Query for Keyword Search

Perform a keyword search with token matching and scoring.

from topk_sdk.query import match, fn, select

results = client.collection("books").query(
    select(
        text_score=fn.bm25_score(),
    ).filter(
        match("rust", field="title", weight=10.0)
    ).top_k(field("text_score"), k=3)
)

4. Query for Vector Search

Perform a nearest-neighbor search with vector distances.

results = client.collection("books").query(
    select(
        vector_distance=fn.vector_distance("embedding", [1.0, 2.0, 3.0]),
    ).top_k(field("vector_distance"), k=3)
)

5. Delete Documents

Remove documents from a collection.

client.collection("books").delete(["doc1"])

6. List and Delete Collections

Manage collections in your workspace.

# List collections
collections = client.collections().list()

# Delete a collection
client.collections().delete("books")

Testing

Run the test suite with pytest:

pytest