LLM client layer: HTTP transport, message construction, and all LLM interaction functions (ask!, abstract!, eval!, refine!, models!, sample!).
LLM client layer: HTTP transport, message construction, and all LLM interaction functions (ask!, abstract!, eval!, refine!, models!, sample!).
Optional map bound by callers to add context to SVAR logs. e.g. {:query-id "abc" :iteration 0} When bound, all HTTP logs include this context.
Optional map bound by callers to add context to SVAR logs.
e.g. {:query-id "abc" :iteration 0}
When bound, all HTTP logs include this context.(abstract! router opts)Routed abstract! — provider fallback + rate limiting.
Routed abstract! — provider fallback + rate limiting.
(abstract!* router
{:keys [text iterations target-length special-instructions eval?
refine? threshold]
:as opts
:or {iterations DEFAULT_ITERATIONS
target-length DEFAULT_TARGET_LENGTH
eval? false
refine? false
threshold 0.9}})Creates a dense, entity-rich summary of text using Chain of Density prompting.
Based on "From Sparse to Dense: GPT-4 Summarization with Chain of Density Prompting" (Adams et al., 2023). Iteratively refines a summary by identifying missing salient entities and incorporating them while maintaining a fixed length.
When :eval? is true, each iteration is scored against the source text using eval!,
giving a quality gradient across iterations (:score field per iteration).
When :refine? is true, the final summary is verified against the source text using
Chain of Verification (CoVe) via refine!. This catches hallucinated framing,
unfaithful claims, and information not present in the source.
Opts: :text - String. Source text to summarize. :model - String. LLM model to use. :iterations - Integer. Number of CoD densification iterations (default: 5). :target-length - Integer. Target summary length in words (default: 80). :special-instructions - String, optional. Additional instructions for the LLM. :eval? - Boolean. Score each iteration for a quality gradient (default: false). :refine? - Boolean. Run CoVe faithfulness verification on final summary (default: false). :threshold - Float. Min eval score for refinement early stop, 0.0-1.0 (default: 0.9).
Creates a dense, entity-rich summary of text using Chain of Density prompting. Based on "From Sparse to Dense: GPT-4 Summarization with Chain of Density Prompting" (Adams et al., 2023). Iteratively refines a summary by identifying missing salient entities and incorporating them while maintaining a fixed length. When `:eval?` is true, each iteration is scored against the source text using `eval!`, giving a quality gradient across iterations (`:score` field per iteration). When `:refine?` is true, the final summary is verified against the source text using Chain of Verification (CoVe) via `refine!`. This catches hallucinated framing, unfaithful claims, and information not present in the source. Opts: :text - String. Source text to summarize. :model - String. LLM model to use. :iterations - Integer. Number of CoD densification iterations (default: 5). :target-length - Integer. Target summary length in words (default: 80). :special-instructions - String, optional. Additional instructions for the LLM. :eval? - Boolean. Score each iteration for a quality gradient (default: false). :refine? - Boolean. Run CoVe faithfulness verification on final summary (default: false). :threshold - Float. Min eval score for refinement early stop, 0.0-1.0 (default: 0.9).
(ask! router opts)Structured output with automatic provider routing, fallback, and rate limiting.
Params:
router - Router instance from make-router. Required.
opts - Map. Accepts all opts that ask!* accepts, plus:
:routing - Map with routing preferences:
:optimize - :cost, :intelligence, or :speed (nil = first model)
:provider - keyword, override specific provider
:model - string, override specific model
:on-transient-error - :hybrid (default), :auto-route-cross-providers,
:fallback-model-in-the-same-provider, :fail
Structured output with automatic provider routing, fallback, and rate limiting.
Params:
`router` - Router instance from make-router. Required.
`opts` - Map. Accepts all opts that ask!* accepts, plus:
:routing - Map with routing preferences:
:optimize - :cost, :intelligence, or :speed (nil = first model)
:provider - keyword, override specific provider
:model - string, override specific model
:on-transient-error - :hybrid (default), :auto-route-cross-providers,
:fallback-model-in-the-same-provider, :fail(ask!* router {:keys [spec messages humanizer] :as opts})Low-level ask — calls the LLM directly without routing. Use ask! instead.
Includes automatic pre-flight context limit checking. If your input exceeds the model's context window, throws a clear error with actionable suggestions BEFORE making the API call.
Supports multimodal input via the user + image helpers.
Params:
opts - Map with keys:
Returns: Map with :result, :tokens, :cost, :duration-ms.
Low-level ask — calls the LLM directly without routing. Use ask! instead. Includes automatic pre-flight context limit checking. If your input exceeds the model's context window, throws a clear error with actionable suggestions BEFORE making the API call. Supports multimodal input via the `user` + `image` helpers. Params: `opts` - Map with keys: - :spec - Spec definition, required. - :messages - Vector of message maps, required. - :model - String, required. LLM model to use. - :humanizer - Function, optional. Applied to ::spec/humanize? fields. - :output-reserve - Integer, optional. - :check-context? - Boolean, optional. - :timeout-ms - Integer, optional. Returns: Map with :result, :tokens, :cost, :duration-ms.
(assistant content)Creates an assistant message (for few-shot examples or conversation history).
Params:
content - String. The assistant's response.
Returns: Message map with :role "assistant".
Creates an assistant message (for few-shot examples or conversation history). Params: `content` - String. The assistant's response. Returns: Message map with :role "assistant".
(chat-completion messages model api-key base-url)(chat-completion messages model api-key base-url opts)Calls the LLM API (OpenAI compatible) with the given messages.
Params:
messages - Vector. Chat messages.
model - String. Model name.
api-key - String. Bearer token.
base-url - String. API base URL.
opts - Map, optional:
Returns: Map with :content, :reasoning (may be nil), :api-usage.
Calls the LLM API (OpenAI compatible) with the given messages.
Params:
`messages` - Vector. Chat messages.
`model` - String. Model name.
`api-key` - String. Bearer token.
`base-url` - String. API base URL.
`opts` - Map, optional:
- :timeout-ms - Integer. Request timeout (default: router/DEFAULT_TIMEOUT_MS).
- :extra-body - Map. Additional params for the API request body.
- :on-chunk - Function. When provided, enables SSE streaming. Callback receives
accumulated text string after each chunk.
- :max-retries, :initial-delay-ms, :max-delay-ms, :multiplier — retry config.
Returns:
Map with :content, :reasoning (may be nil), :api-usage.(eval! router opts)Routed eval! — provider fallback + rate limiting.
Routed eval! — provider fallback + rate limiting.
(eval!* router
{:keys [task output messages criteria ground-truths context]
:as opts
:or {criteria EVAL_CRITERIA}})Low-level eval — calls ask!* directly without routing. Use eval! instead.
Low-level eval — calls ask!* directly without routing. Use eval! instead.
(image source)(image source media-type)Creates an image attachment for use with user messages.
Accepts either base64-encoded image data or an HTTP(S) URL. URLs are passed through directly to the LLM API; base64 strings are wrapped in a data URI with the given media-type.
Params:
source - String. Base64-encoded image data or an image URL (http/https).
media-type - String, optional. MIME type (default: "image/png").
Ignored when source is a URL.
Returns:
Map marker that user recognizes and converts to multimodal content.
When source is a URL, returns {:svar/type :image :url "..."}.
When source is base64, returns {:svar/type :image :base64 "..." :media-type "..."}.
Creates an image attachment for use with `user` messages.
Accepts either base64-encoded image data or an HTTP(S) URL.
URLs are passed through directly to the LLM API; base64 strings
are wrapped in a data URI with the given media-type.
Params:
`source` - String. Base64-encoded image data or an image URL (http/https).
`media-type` - String, optional. MIME type (default: "image/png").
Ignored when source is a URL.
Returns:
Map marker that `user` recognizes and converts to multimodal content.
When source is a URL, returns {:svar/type :image :url "..."}.
When source is base64, returns {:svar/type :image :base64 "..." :media-type "..."}.Creates a router from a vector of provider maps. Delegates to router/make-router.
Creates a router from a vector of provider maps. Delegates to router/make-router.
(models! router)(models! router opts)Fetches available models from the LLM API.
Fetches available models from the LLM API.
(refine! router opts)Routed refine — iterative refinement with provider fallback and rate limiting.
Routed refine — iterative refinement with provider fallback and rate limiting.
(refine!* router
{:keys [spec messages iterations threshold stop-strategy window-size
criteria documents]
:as opts
:or {iterations DEFAULT_REFINE_ITERATIONS
threshold DEFAULT_REFINE_THRESHOLD
stop-strategy :both
window-size 3
criteria EVAL_CRITERIA}})Low-level refine — calls ask!* directly without routing. Use refine! instead.
Implements the Factor+Revise variant of Chain of Verification (CoVe) from Dhuliawala et al. (2023), combined with DuTy decomposition.
Low-level refine — calls ask!* directly without routing. Use refine! instead. Implements the Factor+Revise variant of Chain of Verification (CoVe) from Dhuliawala et al. (2023), combined with DuTy decomposition.
Resets the router's budget counters. Delegates to router/reset-budget!.
Resets the router's budget counters. Delegates to router/reset-budget!.
Resets a provider's circuit breaker. Delegates to router/reset-provider!.
Resets a provider's circuit breaker. Delegates to router/reset-provider!.
(routed-chat-completion router messages opts)Routes a chat-completion across providers with fallback. opts may include :routing and :on-chunk.
Routes a chat-completion across providers with fallback. opts may include :routing and :on-chunk.
Returns cumulative + windowed stats. Delegates to router/router-stats.
Returns cumulative + windowed stats. Delegates to router/router-stats.
(sample! router opts)Routed sample! — provider fallback + rate limiting.
Routed sample! — provider fallback + rate limiting.
(sample!* router
{:keys [spec messages criteria iterations threshold]
:as opts
n :count
:or {criteria SAMPLE_CRITERIA
iterations DEFAULT_SAMPLE_ITERATIONS
threshold DEFAULT_SAMPLE_THRESHOLD}})Low-level sample — generates test data without routing. Use sample! instead.
Low-level sample — generates test data without routing. Use sample! instead.
Returns [provider model-map] or nil. Delegates to router/select-provider.
Returns [provider model-map] or nil. Delegates to router/select-provider.
(shutdown-http-client!)Closes the shared HTTP client's virtual-thread executor. Idempotent — safe to call multiple times. Call before JVM exit in scripts/tests to avoid hanging on non-daemon threads. Registered as a shutdown hook automatically; manual invocation is only needed when the JVM would otherwise not exit.
After shutdown, subsequent HTTP calls will fail with RejectedExecutionException. Do not call during active request traffic.
Closes the shared HTTP client's virtual-thread executor. Idempotent — safe to call multiple times. Call before JVM exit in scripts/tests to avoid hanging on non-daemon threads. Registered as a shutdown hook automatically; manual invocation is only needed when the JVM would otherwise not exit. After shutdown, subsequent HTTP calls will fail with RejectedExecutionException. Do not call during active request traffic.
(system content)Creates a system message.
Params:
content - String. System instructions / objective.
Returns: Message map with :role "system".
Creates a system message. Params: `content` - String. System instructions / objective. Returns: Message map with :role "system".
(user content & images)Creates a user message, optionally with images for multimodal models.
Params:
content - String. The user's message text.
images - Zero or more image maps created with image.
Creates a user message, optionally with images for multimodal models. Params: `content` - String. The user's message text. `images` - Zero or more image maps created with `image`.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |