colivara-py 0.1.5

The official Python SDK for the ColiVara API

colivara-py

The official Python SDK for the ColiVara API

Installation

Install this library using pip:

pip install colivara-py

Usage

Please see the ColiVara API documentation for more information on how to use this library.

You will need to either self-host the API (see the ColiVara API repo) or use the hosted version at https://colivara.com. You will also need an API key, which you can obtain by signing up at ColiVara or from your self-hosted API.

import os
from colivara_py import ColiVara


rag_client = ColiVara(
     # This is the default and can be omitted
    api_key=os.environ.get("COLIVARA_API_KEY"),
    # This is the default and can be omitted
    base_url="https://api.colivara.com"
)
# Create a new collection
new_collection = rag_client.create_collection(name="my_collection", metadata={"description": "A sample collection"})
print(f"Created collection: {new_collection.name}")

# Upload a document to the collection
document = rag_client.upsert_document(
    name="sample_document",
    collection_name="my_collection",
    url="https://example.com/sample.pdf",
    metadata={"author": "John Doe"}
)
print(f"Uploaded document: {document.name}")

# Search for documents
search_results = rag_client.search(
    query="machine learning",
    collection_name="my_collection",
    top_k=3
)
for result in search_results.results:
    print(f"Page {result.page_number} of {result.document_name}: Score {result.normalized_score}")

# List documents in a collection
documents = client.list_documents(collection_name="my_collection")
for doc in documents:
    print(f"Document: {doc.name}, Pages: {doc.num_pages}")

# Generate embeddings
embeddings = rag_client.create_embedding(
    input_data=["This is a sample text for embedding"],
    task="query"
)
print(f"Generated {len(embeddings.data)} embeddings")

# Delete a document
rag_client.delete_document("sample_document", collection_name="my_collection")
print("Document deleted")

Development

To contribute to this library, first checkout the code. Then create a new virtual environment:

We use uv, but you can use the pip interface if you prefer:

cd colivara-py
uv venv
source .venv/bin/activate

Now install the dependencies and test dependencies:

uv sync --extra dev-dependencies

To run the tests:

pytest

To build the documenation locally:

pdocs server colivara_py #to test  
pdocs as_html colivara_py --overwrite #to generate HTML.
pdocs as_markdown colivara_py #to generate markdown.