llm.sdk — net.clojars.deadmeme5441/clojure-llm-sdk 0.1.0

Public API for clojure-llm-sdk. Complete, embed, stream, list-models, capabilities, normalize-usage, estimate-cost, provider registration.

*retry-sleep-fn* clj

Indirection for tests - replace to drive retry without actually sleeping. Default is Thread/sleep.

cache-strategy clj

(cache-strategy provider-id model)

(cache-strategy provider-id model request-cache)

Inspect which cache strategy + layout the SDK will use for a given provider, model, and (optional) :request/cache map. Useful for debugging cache misses without sending a real request.

Returns {:strategy :system-and-3|:prompt-key|:explicit|:cache-point|:none :layout :native|:envelope|nil :reason string}

canonical-cache clj

(canonical-cache usage)

Build a canonical :response/cache map from a canonical Usage.

canonical-cost clj

(canonical-cost provider model usage)

Build a canonical :response/cost map (the same shape complete/embed stamp on responses). Useful for after-the-fact attribution. Returns {:cost/usd :unknown :cost/estimated? true ...} when pricing or usage is unknown.

classify-error clj

(classify-error e & opts)

Classify an exception or error response.

complete clj

(complete provider-id request & {:keys [stream? on-event retry config]})

Send a canonical request and return a canonical response. Provider must be a registered provider keyword (e.g. :openai). Request is a map conforming to llm.sdk.schema/Request.

The returned response is stamped with :response/cost and :response/cache derived from its :response/usage. When pricing or cache stats are unknown, those fields carry honest :unknown markers

• never substituted 0/$0.

Options: :stream? If true, returns a lazy seq of stream events (or a list-of-events plus terminal response when :on-event is given). :on-event Callback fn for each stream event (only if stream? true). :retry Opt-in retry policy. nil/false → one-shot (default). true → use llm.sdk.retry/default-policy. A map → merged into the default policy; supply only the keys you want to override (e.g. {:retry/max-attempts 5}). Streaming requests are not retried - partial streams can't be safely resumed by the SDK. :config Per-call runtime config: :api-key/:auth-token, :base-url, :headers, :http-client, :connect-timeout-ms, :timeout-ms.

default-retry-policy clj

(default-retry-policy)

Return the default retry policy map.

embed clj

(embed provider-id request & opts)

Send a canonical embed request and return a canonical EmbedResponse. Provider must be a registered provider whose profile carries a :profile/embed-transport-constructor. Request keys: :embed/model, :embed/inputs (vector of strings), plus optional :embed/dimensions, :embed/encoding-format, :embed/user, :embed/provider-options.

estimate-cost clj

(estimate-cost provider model usage & {:keys [fetch-pricing? api-key]})

Estimate cost for a provider+model given canonical Usage. Optionally fetch live pricing first with :fetch-pricing? true.

generate-image clj

(generate-image provider-id request & opts)

Send a canonical image generation request and return an ImageGenResponse. Provider must carry :profile/image-transport-constructor in its profile.

Required: :image/prompt. Optional: :image/model, :image/n, :image/size, :image/quality, :image/style, :image/response-format, :image/user, :image/provider-options.

list-models clj

(list-models)

(list-models provider-id)

List known model ids. With no args, returns a sorted distinct seq across every provider the registry knows. With a provider keyword, returns the ModelEntry maps under that provider.

list-providers clj

(list-providers)

Return a seq of registered provider keywords.

model-capabilities clj

(model-capabilities model-id)

(model-capabilities provider-id model-id)

Return the capability set for a model. Single-arg form scans across providers (prefers native over alias); two-arg form is provider-aware.

model-context-length clj

(model-context-length model-id)

(model-context-length provider-id model-id)

Return the context length for a model in tokens, or nil if unknown.

model-info clj

(model-info model-id)

(model-info provider-id model-id)

Return the full registry ModelEntry for (provider, model), or just (model) when the id is globally unique. Includes context-length, max-output-tokens, capabilities, cost, source provenance.

moderate clj

(moderate provider-id request & opts)

Send a canonical moderation request and return a ModerationResponse. Provider must carry :profile/moderation-transport-constructor in its profile.

:moderation/inputs is a vector of either strings or maps shaped {:type :text :text "..."} / {:type :image_url :image_url "https://..."}. omni-moderation models accept the multi-modal shape; text-moderation models are text-only.

normalize-usage clj

(normalize-usage provider raw-usage)

Normalize raw provider usage data to canonical Usage shape.

provider-profile clj

(provider-profile provider-id)

Get a provider profile by keyword.

refresh-models! clj

(refresh-models! & {:keys [provider]})

Hit each provider's live /models endpoint and merge results into the registry's live tier. With no args, refreshes every provider that supports live model listing (skipping :codex/:codex-backend/:bedrock). With :provider <kw>, refreshes only that one. Returns a map of provider → {:count n} or {:error msg :data data}.

register-model-info clj

(register-model-info provider-id model-id entry)

Inject a caller-provided model entry into the registry override tier. Useful when targeting custom endpoints models.dev doesn't know about. Entry takes the canonical ModelEntry shape minus the provider/id (those are passed explicitly).

rerank clj

(rerank provider-id request & opts)

Send a canonical rerank request and return a RerankResponse. Provider must carry :profile/rerank-transport-constructor in its profile.

Required keys: :rerank/model, :rerank/query, :rerank/documents (vector of strings). Optional: :rerank/top-n, :rerank/return-documents, :rerank/provider-options.

speak clj

(speak provider-id request & opts)

Send a canonical text-to-speech request and return a SpeakResponse {:audio/bytes byte-array :audio/content-type str ...}. Provider must carry :profile/speak-transport-constructor in its profile.

Required: :speak/model, :speak/input. Optional: :speak/voice, :speak/format (:mp3|:opus|:aac|:flac|:wav|:pcm), :speak/speed, :speak/instructions, :speak/provider-options.

transcribe clj

(transcribe provider-id request & opts)

Send a canonical audio-transcription request and return a TranscribeResponse. Provider must carry :profile/transcribe-transport-constructor in its profile.

Required: :transcribe/file (java.io.File / path / bytes / InputStream) and :transcribe/model. Optional: :transcribe/language, :transcribe/prompt, :transcribe/temperature, :transcribe/response-format (:json|:text|:srt|:verbose_json|:vtt), :transcribe/timestamp-granularities (#{:segment :word}), :transcribe/provider-options.

with-fallbacks clj

(with-fallbacks providers request)

(with-fallbacks providers request opts)

Try each [provider-id model-id] pair in order against the given request, returning the first success. If all fail, throws ex-info with :attempts (vector of failure maps) and :providers.

No credential pools, no cooldowns, no rate-limit tracking - that's credential-pool routing, which is explicitly out of scope for this SDK. Compose this with your own resilience layer for those needs.