#SundayT1998/chroma-client

#Docs

• docs/CONTRIBUTING.md — setup, the checks a change has to pass, the two test layers, code style, commit and PR conventions.
• docs/chroma-api-coverage.md — which Chroma v2 endpoints the client covers, which it deliberately does not, and why.
• docs/serialization-perf.md — what a large record batch costs to serialize, and why the write path is not streamed.

#Design

• AsyncTransport — asynchronous, with async fn send_async. This is the one the bundled AsyncHttpTransport implements, because moonbitlang/async/http only offers async functions and an async call cannot be made from a synchronous one.

• Transport — synchronous. MemoryTransport implements it, so scripted responses cover the whole request/response cycle in ordinary moon test runs.

• portable — the same code runs on native, wasm and js. The transport limits the library to the backends moonbitlang/async supports; wasm-gc has no async runtime yet, so it is not a supported target;
• testable — MemoryTransport implements the synchronous Transport and replays scripted responses, so the whole request/response cycle is covered by ordinary moon test runs without a server;
• replaceable — AsyncTransport is a two-method-wide seam, so an application that already owns an HTTP stack can plug it in instead of using the bundled one.

#Install

moon add SundayT1998/chroma-client

#Quick start

///|
async fn example() -> Unit raise @chroma.ChromaError {
  // `AsyncHttpTransport` is bundled; point the config at your Chroma server.
  let client = @chroma.ChromaClient::new(
    @chroma.AsyncHttpTransport::new(),
    config=@chroma.Config::new(endpoint="http://localhost:8000"),
  )

  let collection = client.get_or_create_collection_async("notes")

  // Chroma 1.x stores vectors, not text: every record needs coordinates.
  client.add_async(collection.id, [
    @chroma.Record::of_embedding("r1", [1.0, 0.0, 0.0]).with_document(
      "MoonBit is a language for the web",
    ),
    @chroma.Record::of_embedding("r2", [0.0, 1.0, 0.0]).with_document(
      "Chroma stores embeddings",
    ),
  ])

  let result = client.query_embeddings_async(
    collection.id,
    [[1.0, 0.0, 0.0]],
    n_results=2,
  )
  for id in result.ids {
    println(id)
  }
}

Chroma 1.x has no server-side embedding. An add whose records carry documents but no vectors is rejected by the server, so the client refuses it locally and points at Record::with_embedding. Produce the vectors with whatever embedding model you already use; Record::of_document(...).with_embedding(vec) is the usual shape.

#Choosing what a query returns

client.query_embeddings_async(
  collection.id,
  [[0.1, 0.9, 0.0]],
  n_results=5,
  include_fields=@chroma.Include::all(),
)

#Filtering

let filter = @chroma.Filter::new()
  .with_metadata("source", @chroma.MString("handbook"))
  .with_limit(20)
client.get_async(collection.id, filter=filter)

#Metadata types

@chroma.MetadataValue::MString("hello")
@chroma.MetadataValue::MInt(42)
@chroma.MetadataValue::MFloat(0.5)
@chroma.MetadataValue::MBool(true)
@chroma.MetadataValue::MNull

#Adding a real transport

///|
impl @chroma.AsyncTransport for MyTransport with fn send_async(self, request) {
  let headers : @ah.Headers = Map([])
  for entry in request.headers {
    let (key, value) = entry
    headers[key] = value
  }
  let payload : &@aio.Data = match request.body {
    Some(body) => body
    None => ""
  }
  let (response, response_body) = @ah.request(
    request.url,
    to_ah_method(request.verb),
    headers,
    payload,
  )
  {
    status: response.code,
    headers: converted(response.headers),
    body: response_body.text(),
  }
}

///|
pub extend MyTransport with @chroma.AsyncTransport::{send_async}

#Native transport

moon run cmd/main --target native -- http://localhost:8000 my-collection

#Authentication

///|
let client = @chroma.ChromaClient::new(
  transport,
  config=@chroma.Config::new()
    .with_token("my-api-token")
    .with_basic_auth("user", "password"),
)

#Timeouts

///|
let client = @chroma.ChromaClient::new(
  @chroma.TimeoutTransport::new(http_stack, 5000),
  // or, to pick up Config::timeout_ms:
  // @chroma.TimeoutTransport::from_config(http_stack, config)
)

#Counting and previewing

///|
let total = client.count(collection.id)

///|
let sample = client.peek(collection.id, limit=5)

#Pagination

///|
client.get_async(
  collection.id,
  filter=@chroma.Filter::new(limit=Some(10), offset=Some(5)),
)

#Records and vectors

///|
// Vector first, text attached afterwards.
@chroma.Record::of_embedding("r1", [1.0, 0.0]).with_document("hello")

///|
// Text first, vector attached afterwards.
@chroma.Record::of_document("r2", "world").with_embedding([0.0, 1.0])

///|
// Metadata, either way.
@chroma.Record::of_embedding("r3", [1.0, 1.0]).with_metadata([
  ("source", @chroma.MString("handbook")),
])

#Errors

• Transport(String) — the request could not be sent;
• Api(ApiError) — the server answered non-2xx with Chroma's error body;
• Status(Int, String) — the server answered non-2xx with a body that is not a Chroma error envelope (a proxy page, say);
• Decode(String) — the response body was not the expected JSON;
• InvalidArgument(String) — the arguments would be rejected by Chroma, so nothing was sent.

///|
match result {
  Err(error) =>
    if error.status_code() == Some(404) {
      // nothing there
    } else if error.is_retryable() {
      // 429 or 5xx, worth trying again
    } else {
      println(error.message())
    }
  Ok(value) => ignore(value)
}

#Retrying

///|
let client = @chroma.ChromaClient::new(
  @chroma.RetryTransport::new(
    http_stack,
    policy=@chroma.RetryPolicy::new(
      enabled=true,
      max_attempts=3,
      initial_delay_ms=200,
      max_delay_ms=5000,
      backoff_factor=2.0,
    ),
  ),
)

///|
let transport = @chroma.RetryTransport::new(http_stack).on_retry((
  attempt,
  delay_ms,
  error,
) => {
  println(
    "retry " +
    attempt.to_string() +
    " in " +
    delay_ms.to_string() +
    "ms: " +
    error.to_string(),
  )
})

#Response size

#Local validation

• an empty records batch on add / upsert / update;
• a record with an empty id, or with neither a document nor an embedding;
• an empty embeddings list on query_embeddings;
• n_results <= 0, and an offset that is not smaller than limit.

#Decoding rules

• required and missing ⇒ Decode. Collection.id / Collection.name and the ids of a get result are never silently defaulted, because an empty list and a broken response are different answers;
• optional and missing ⇒ empty default. metadata, configuration, log_position, version, and everything include controls (documents, embeddings, metadatas, distances) may legitimately be absent.

#Examples

moon run cmd/main --target native -- http://localhost:8000 my-collection

#Testing

sh scripts/ci.sh

sh scripts/ci.sh fmt check     # just formatting and type-checking
sh scripts/ci.sh test coverage # just tests and coverage

sh scripts/integration.sh      # starts chromadb/chroma, runs, tears down

CHROMA_ENDPOINT=http://localhost:8000 \
  moon test --target native -p SundayT1998/chroma-client

#Status

#License