embeddings-clj

Text embeddings for Clojure with local sentence-transformers ONNX exports or hosted OpenAI, Cohere, and Voyage models.

Stack

Installation

deps.edn:

net.clojars.savya/embeddings-clj {:mvn/version "0.5.1"}

Leiningen:

[net.clojars.savya/embeddings-clj "0.5.1"]

The library parses JSON with the declared org.clojure/data.json dependency. It does not depend on Gson.

Providers

Local and hosted models implement embeddings.core/EmbeddingProvider, with embed, embed-batch, and dimension operations.

(require '[embeddings.core :as emb]
         '[embeddings.providers :as providers])

(def openai
  (providers/openai {:api-key (System/getenv "OPENAI_API_KEY")
                     :model "text-embedding-3-small"
                     :dimensions 512}))

(emb/embed openai "A sentence to embed")

(def cohere
  (providers/cohere {:api-key (System/getenv "COHERE_API_KEY")
                     :model "embed-v4.0"
                     :input-type "search_document"}))

(def voyage
  (providers/voyage {:api-key (System/getenv "VOYAGE_API_KEY")
                     :model "voyage-3-large"
                     :input-type "query"}))

Hosted provider options include :api-key, :model, :dimensions, :batch-size (default 128), :url for an endpoint override, and :transport for an injectable request function. Cohere and Voyage also accept :input-type. The transport receives {:url :method :headers :body} and must return {:status :body}.

Local model options

embeddings.core/load-model accepts pooling, normalization, maximum-length, and execution-provider options, plus:

• :output-name: select a named ONNX graph output.
• :input-schema: map custom ONNX input names to an encoded source keyword or {:source keyword :pad-value number}. Built-in inputs include input_ids, attention_mask, token_type_ids, and position_ids.
• :output-dimensions: truncate Matryoshka embeddings to a positive dimension no larger than the model output. Truncation happens before normalization.

Documentation

• Getting a model
• Usage

Running tests

clojure -M:test

The unit suite runs against tiny deterministic ONNX fixtures. Generate them with python3 dev/gen_fixture.py, which needs pip install onnx. If the fixtures are absent, the tests skip and the suite stays green.

The optional integration suite uses a real all-MiniLM-L6-v2 model:

./dev/fetch-model.sh          # ~90MB download from HuggingFace
clojure -M:test --focus-meta :integration

License

Copyright © 2026 Savyasachi.

Distributed under the Eclipse Public License 2.0.