Example
Chroma — vector similarity search (no server, no key)

A real, runnable mini-project. Download it and run with Docker.

View samples/chroma_1 on GitHub ↗

June 28, 2026

Chroma — vector similarity search (no server, no key)

A tiny Chroma demo: it stores a few documents — Chroma embeds them with a built-in model — then runs a nearest-neighbour query. Swap the toy docs for your own and it is a RAG retriever. No API key.

Run with Docker

cd samples/chroma_1
docker build -t aas-chroma .
docker run --rm aas-chroma "tell me about young cats"

The first query downloads Chroma's built-in embedding model (all-MiniLM-L6-v2, ~80 MB), so the run needs internet once.

Run with Docker (in a devcontainer with DooD)

In a dev container that talks to the host Docker daemon (Docker-outside-of-Docker), the attached docker run may print nothing even though it ran — the live attached stream drops output over the VM boundary. Run detached and read the logs:

cd samples/chroma_1
docker build -t aas-chroma .
docker logs -f "$(docker run -d aas-chroma "tell me about young cats")"

Run locally

cd samples/chroma_1
pip install -r requirements.txt
python app.py "tell me about young cats"

Example run

Embeddings are deterministic (fixed model + input), so the ranking is the same every run — only the first run downloads the model.

nearest to 'tell me about young cats' by distance:
  kitten     0.8413
  cat        1.0233
  rocket     1.8533

Files

app.py 
"""Chroma: vector similarity search with no server and no API key.

Stores a few documents in an in-memory Chroma collection (Chroma embeds them
with a built-in model), then runs a nearest-neighbour query. Swap the toy docs
for your own and it is a RAG retriever.

Run:
    docker build -t aas-chroma .
    docker run --rm aas-chroma "tell me about young cats"
"""

import sys

import chromadb

DOCS = {
    "cat": "Cats are independent pets that purr and chase laser pointers.",
    "kitten": "A kitten is a young cat that loves to play and nap.",
    "airplane": "An airplane is a powered flying vehicle with fixed wings.",
    "rocket": "A rocket is propelled by ejecting exhaust gas at high speed.",
}


def main() -> None:
    query = " ".join(sys.argv[1:]) or "tell me about young cats"

    client = chromadb.Client()  # in-memory; built-in embedding model
    col = client.create_collection("docs")
    col.add(ids=list(DOCS), documents=list(DOCS.values()))

    res = col.query(query_texts=[query], n_results=3)

    print(f"nearest to {query!r} by distance:")
    for label, dist in zip(res["ids"][0], res["distances"][0]):
        print(f"  {label:10s} {dist:.4f}")


if __name__ == "__main__":
    main()