Home

Awesome

ColiVara = COntextualized Late Interaction Vision Augmented Retrieval API

codecov Tests

Discord

State of the Art Retrieval - with a delightful developer experience

Colivara is a suite of services that allows you to store, search, and retrieve documents based on their visual embedding.

It is a web-first implementation of the ColPali paper using ColQwen2 as the LLM model. It works exactly like RAG from the end-user standpoint - but using vision models instead of chunking and text-processing for documents.

Cloud Quickstart:

  1. Get a free API Key from the ColiVara Website.

  2. Install the Python SDK and use it to interact with the API.

pip install colivara-py
  1. Index a document. Colivara accepts a file url, or base64 encoded file, or a file path. We support over 100 file formats including PDF, DOCX, PPTX, and more. We will also automatically take a screenshot of URLs (webpages) and index them.
from colivara_py import ColiVara

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"
)

# Upload a document to the default_collection
document = client.upsert_document(
    name="sample_document",
    url="https://example.com/sample.pdf",
    # optional - add metadata
    metadata={"author": "John Doe"},
    # optional - specify a collection
    collection_name="user_1_collection", 
    # optional - wait for the document to index
    wait=True
)
  1. Search for a document. You can filter by collection name, collection metadata, and document metadata. You can also specify the number of results you want.
# Simple search
results = client.search("what is 1+1?")
# search with a specific collection
results = client.search("what is 1+1?", collection_name="user_1_collection")
# Search with a filter on document metadata
results = client.search(
    "what is 1+1?",
    query_filter={
        "on": "document",
        "key": "author",
        "value": "John Doe",
        "lookup": "key_lookup",  # or contains
    },
)
# Search with a filter on collection metadata
results = client.search(
    "what is 1+1?",
    query_filter={
        "on": "collection",
        "key": ["tag1", "tag2"],
        "lookup": "has_any_keys",
    },
)
# top 3 pages with the most relevant information
print(results)

Documentation:

Our documentation is available at docs.colivara.com.

[!NOTE] If you prefer Swagger, you can try our endpoints at ColiVara API Swagger. You can also import an openAPI spec (for example for Postman) from the swagger documentation endpoint at v1/docs/openapi.json

Why?

RAG (Retrieval Augmented Generation) is a powerful technique that allows us to enhance LLMs (Language Models) output with private documents and proprietary knowledge that is not available elsewhere. (For example, a company's internal documents or a researcher's notes).

However, it is limited by the quality of the text extraction pipeline. With limited ability to extract visual cues and other non-textual information, RAG can be suboptimal for documents that are visually rich.

ColiVara uses vision models to generate embeddings for documents, allowing you to retrieve documents based on their visual content.

From the ColPali paper:

Documents are visually rich structures that convey information through text, as well as tables, figures, page layouts, or fonts. While modern document retrieval systems exhibit strong performance on query-to-text matching, they struggle to exploit visual cues efficiently, hindering their performance on practical document retrieval applications such as Retrieval Augmented Generation.

Learn More in the ColPali Paper

How does it work?

Credit: helloIamleonie on X

ColPali Explainer

Key Features

Evals:

The ColPali team has provided the following evals in their paper. We have run quick sanity checks on the API and the Embeddings Service and are getting similar results. We are working on our own independent evals repository and will update this section with our results and how to reproduce them.

Updates:

ColPali Evals

Components:

  1. Postgres DB with pgvector extension for storing embeddings. (This repo)

  2. REST API for document/collection management (This repo)

  3. Embeddings Service. This needs a GPU with at least 8gb VRAM. The code is under ColiVarE repo and is optimized for a serverless GPU workload.

    You can run the embedding service separately and use your own storage and API for the rest of the components. The Embedding service is designed to be modular and can be used with any storage and API. (For example, if you want to use Qdrant for storage and Node for the API)

  4. Language-specific SDKs for the API (Typescript SDK Coming Soon)

    1. Python SDK: colivara-py

Roadmap

  1. Independent Evals for quality + latency
  2. Full Demo with Generative Models
  3. Automated SDKs for popular languages other than Python

Getting Started (Local Setup)

  1. Setup the Embeddings Service (ColiVarE) - This is a separate repo and is required for the API to work. The directions are available here: ColiVarE

  2. Clone the repo

git clone https://github.com/tjmlabs/ColiVara
  1. Create a .env.dev file in the root directory with the following variables:
EMBEDDINGS_URL="the serverless embeddings service url" # for local setup use http://localhost:8000/runsync/
EMBEDDINGS_URL_TOKEN="the serverless embeddings service token"  # for local setup use any string will do.
AWS_S3_ACCESS_KEY_ID="an S3 or compatible storage access key"
AWS_S3_SECRET_ACCESS_KEY="an S3 or compatible storage secret key"
AWS_STORAGE_BUCKET_NAME="an S3 or compatible storage bucket name"
  1. Run the following commands:
docker-compose up -d --build
docker-compose exec web python manage.py migrate
docker-compose exec web python manage.py createsuperuser
# get the token from the superuser creation
docker-compose exec web python manage.py shell
from accounts.models import CustomUser
user = CustomUser.objects.first().token # save this token somewhere

  1. Application will be running at http://localhost:8001 and the swagger documentation at http://localhost:8001/v1/docs

  2. To run tests - we have 100% test coverage

docker-compose exec web pytest
  1. mypy for type checking
docker-compose exec web mypy .

License

This project is licensed under Functional Source License, Version 1.1, Apache 2.0 Future License. See the LICENSE.md file for details.

For commercial licensing, please contact us at tjmlabs.com. We are happy to work with you to provide a license that meets your needs.