chromago

Chroma Go

A simple Chroma Vector Database client written in Go

Works with Chroma Version: v0.4.3 - v1.0.x

We invite users to visit the docs site for the library for more in-depth information: Chroma Go Docs

[!NOTE] v0.2.0 documentation is still being updated. Please consult the tests under pkg/api/v2 for more detailed usage examples. We are working on updating the documentation with full usage examples (also feel free to contribute if you have any examples you would like to share).

Feature Parity with ChromaDB API

Additional support features:

• ✅ Authentication (Basic, Token with Authorization header, Token with X-Chroma-Token header)
• ✅ Private PKI and self-signed certificate support
• ✅ Chroma Cloud support
• ⚒️ Persistent Embedding Function support (coming soon) - automatically load embedding function from Chroma collection configuration
• ⚒️ Persistent Client support (coming soon) - Run/embed full-featured Chroma in your go application without the need for Chroma server.

Embedding API and Models Support

• 🔥✅ Default Embedding Support - Since 0.2.0+, we also support the default all-MiniLM-L6-v2 model running on Onnx Runtime (ORT).
• ✅ OpenAI Embedding Support
• ✅ Cohere (including Multi-language support)
• ✅ Sentence Transformers (HuggingFace Inference API and HFEI local server)
• ✅ Google Gemini Embedding Support
• 🚫 Custom Embedding Function

✅ HuggingFace Embedding Inference Server Support

• ✅ Ollama Embedding Support
• ✅ Cloudflare Workers AI Embedding Support
• ✅ Together AI Embedding Support
• ✅ Voyage AI Embedding Support
• ✅ Mistral AI API Embedding Support
• ✅ Nomic AI Embedding Support
• ✅ Jina AI Embedding Support

Reranking Functions

From release 0.2.0 the Chroma Go client also supports Reranking functions. The following are supported:

• ✅ Cohere
• ✅ Jina AI
• ✅ HuggingFace Embedding Inference Server Reranker
• More coming soon...

Installation

[!IMPORTANT]
There are many new changes leading up to v0.2.0, as documented below. If you'd like to use them please install the latest version of the client.

go get github.com/amikos-tech/chroma-go@main

go get github.com/amikos-tech/chroma-go

Import v1:

import (
chroma "github.com/amikos-tech/chroma-go"
)

Usage

Ensure you have a running instance of Chroma running. We recommend one of the two following options:

• Official documentation
• If you are a fan of Kubernetes, you can use the Helm chart (Note: You will need Docker, minikube and kubectl installed)

The Setup (Cloud-native):

minikube start --profile chromago
minikube profile chromago
helm repo add chroma https://amikos-tech.github.io/chromadb-chart/
helm repo update
helm install chroma chroma/chromadb --set chromadb.allowReset=true,chromadb.apiVersion=0.

[!NOTE] To delete the minikube cluster: minikube delete --profile chromago

Getting Started (Chroma API v2)

• We create a new collection
• Add documents using the default embedding function
• Query the collection using the same embedding function
• Delete documents from the collection

package main

import (
	"context"
	"fmt"
	"log"

	chroma "github.com/amikos-tech/chroma-go/pkg/api/v2"
)

func main() {
	// Create a new Chroma client
	client, err := chroma.NewHTTPClient()
	if err != nil {
		log.Fatalf("Error creating client: %s \n", err)
		return
	}
	// Close the client to release any resources such as local embedding functions
	defer func() {
		err = client.Close()
		if err != nil {
			log.Fatalf("Error closing client: %s \n", err)
		}
	}()

	// Create a new collection with options. We don't provide an embedding function here, so the default embedding function will be used
	col, err := client.GetOrCreateCollection(context.Background(), "col1",
		chroma.WithCollectionMetadataCreate(
			chroma.NewMetadata(
				chroma.NewStringAttribute("str", "hello"),
				chroma.NewIntAttribute("int", 1),
				chroma.NewFloatAttribute("float", 1.1),
			),
		),
	)
	if err != nil {
		log.Fatalf("Error creating collection: %s \n", err)
		return
	}

	err = col.Add(context.Background(),
		//chroma.WithIDGenerator(chroma.NewULIDGenerator()),
		chroma.WithIDs("1", "2"),
		chroma.WithTexts("hello world", "goodbye world"),
		chroma.WithMetadatas(
			chroma.NewDocumentMetadata(chroma.NewIntAttribute("int", 1)),
			chroma.NewDocumentMetadata(chroma.NewStringAttribute("str", "hello")),
		))
	if err != nil {
		log.Fatalf("Error adding collection: %s \n", err)
	}

	count, err := col.Count(context.Background())
	if err != nil {
		log.Fatalf("Error counting collection: %s \n", err)
		return
	}
	fmt.Printf("Count collection: %d\n", count)

	qr, err := col.Query(context.Background(), chroma.WithQueryTexts("say hello"))
	if err != nil {
		log.Fatalf("Error querying collection: %s \n", err)
		return
	}
	fmt.Printf("Query result: %v\n", qr.GetDocumentsGroups()[0][0])

	err = col.Delete(context.Background(), chroma.WithIDsDelete("1", "2"))
	if err != nil {
		log.Fatalf("Error deleting collection: %s \n", err)
		return
	}
}

Development

Build

make build

Test

V1 API:

make test

V2 API:

make test-v2

Generate ChromaDB API Client (only for v1)

make generate 

Lint

make lint-fix

Local Server

Note: Docker must be installed

make server

References

• Official Chroma documentation
• Chroma Helm chart for cloud-native deployments
• Chroma Cookbook for examples and recipes