ai

ai/*http-post*#

HTTP POST seam. Rebind with binding in tests to inject a fake transport. Tagged ^:dynamic so concurrent tests rebinding it stay isolated per fiber.

Example:

(binding [*http-post* (fn [url opts] {:status 200 :body "..."})] ...)

ai/build-index#

(build-index texts & [opts])

Builds a searchable index from a collection of text strings.

Embeds all texts and returns a vector of {:text, :embedding} maps suitable for use with nearest.

Options are passed through to embed.

Example:

(build-index ["hello" "world"])

ai/chat#

(chat messages & [{:keys [system], :as opts}])

Sends a chat completion request with a list of message maps.

Each message is a map with :role and :content keys. Returns the assistant's text response as a string.

Accepts an optional options map: :system - System prompt string :model - Override the configured model :max-tokens - Override the configured max tokens :provider - Override the configured provider :timeout - HTTP timeout in seconds :base-url - Override the API base URL :api-key - Override the configured API key

Example:

(chat [{:role "user" :content "Hello!"}])

ai/chat-with-history#

(chat-with-history history user-message & [opts])

Appends a new user message to an existing conversation history, sends it, and returns the updated history with the assistant's response.

Useful for building multi-turn conversations.

Example:

(chat-with-history [{:role "user" :content "Hi"}
                              {:role "assistant" :content "Hello!"}]
                             "How are you?")

ai/chat-with-tools#

(chat-with-tools messages tools & [{:keys [system], :as opts}])

Sends a chat request with tool definitions.

Returns a map: :text - Assistant text content (may be nil if model only called tools) :tool-calls - Vector of {:name :id :input} maps for any tool calls :stop-reason - Provider-specific stop reason :raw - The full provider response body

Options map accepts the same keys as chat.

Example:

(chat-with-tools [{:role "user" :content "What's the weather?"}]
                             [(tool "get-weather" "Gets weather" {:city {:type "string"}})])

ai/complete#

(complete prompt & [opts])

Sends a simple text completion request.

Takes a prompt string and returns the assistant's text response. This is a convenience wrapper around chat for single-turn interactions.

Example:

(complete "Explain monads in one sentence")

ai/config#

Current AI configuration atom. Use configure to update.

Example:

@ai/config

ai/configure#

(configure opts)

Merges the given options into the AI configuration.

Supported keys: :provider - :anthropic (default), :openai, or :voyageai :model - Model name string :max-tokens - Maximum tokens in response :api-key - API key string (or set via env var) :base-url - Override the API base URL :timeout - HTTP timeout in seconds (default 120) :max-retries - Retry attempts on 429/5xx (default 2)

Example:

(configure {:api-key "sk-ant-..." :model "claude-sonnet-4-5"})

ai/cosine-similarity#

(cosine-similarity a b)

Computes the cosine similarity between two numeric vectors. Returns a float between -1.0 and 1.0, where 1.0 means identical direction.

Example:

(cosine-similarity [1 0] [0 1]) ; => 0.0

ai/dot-product#

(dot-product a b)

Computes the dot product of two numeric vectors.

Example:

(dot-product [1 2 3] [4 5 6]) ; => 32

ai/embed#

(embed texts & [{:keys [model provider], :or {provider :openai}}])

Generates embeddings for one or more text strings.

Returns a vector of embedding vectors (one per input text). Uses OpenAI's text-embedding-3-small by default.

Options: :model - Override the embedding model name :provider - :openai (default) or :voyageai

Example:

(embed ["hello world"]) ; => [[0.123 -0.456 ...]]

ai/embed-one#

(embed-one text & [opts])

Generates an embedding for a single text string. Returns a single embedding vector.

Example:

(embed-one "hello world") ; => [0.123 -0.456 ...]

ai/extract#

(extract schema text & [opts])

Extracts structured data from text using AI.

schema is a map of field names to type descriptions. Each key becomes a field in the output, and each value tells the AI what to extract.

Returns a Phel map with the schema keys populated from the AI response.

Options: :system - Override the system prompt :model - Override the configured model :max-tokens - Override the configured max tokens

Example:

(extract {:name "string" :age "integer"} "John is 30 years old")

ai/extract-many#

(extract-many schema text & [opts])

Extracts a list of structured items from text.

Similar to extract, but returns a vector of maps when the text contains multiple items matching the schema.

Example:

(extract-many {:name "string" :role "string"} "Alice is CEO, Bob is CTO")

ai/magnitude#

(magnitude v)

Computes the magnitude (L2 norm) of a numeric vector.

Example:

(magnitude [3 4]) ; => 5.0

ai/nearest#

(nearest query-embedding index & [k])

Finds the k nearest items to a query embedding from an index.

index is a vector of {:text "..." :embedding [...]} maps. Returns a vector of {:text, :embedding, :similarity} maps sorted by descending similarity.

Example:

(nearest query-embedding index 5)

ai/run-tools#

(run-tools messages tools handlers & [opts])

Drives a tool-calling loop: repeatedly sends messages with tools, resolves any tool calls via handlers, and feeds the results back in until the model returns a final text response (or :max-turns is hit).

• messages: initial conversation (vector of role/content maps)
• tools: tool definitions built with tool
• handlers: map of tool-name (string) -> fn taking the call's :input map and returning a value (stringified into the tool result)
• opts: same keys as chat-with-tools, plus :max-turns (default 5)

Returns the assistant's final text. Throws if a tool name has no handler or if :max-turns is reached without a final response. Anthropic-only; OpenAI tool loops require a different message shape and are not handled.

Example:

(run-tools [{:role "user" :content "weather?"}]
                       [(tool "get-weather" "..." {:city "string"})]
                       {"get-weather" (fn [args] "72F")})

ai/search#

(search query index & [{:keys [k model provider], :or {k 5}}])

Semantic search: embeds a query and finds the k nearest matches in a pre-built index.

Returns a vector of {:text, :embedding, :similarity} maps.

Example:

(search "greeting" my-index 3)

ai/tool#

(tool tool-name description input-schema)

Creates a tool definition map for use with chat-with-tools.

tool-name is a string identifier for the tool. description describes what the tool does. input-schema is a map of parameter names to JSON Schema type maps.

The returned map is provider-agnostic; chat-with-tools converts it to the provider's native format.

Example:

(tool "get-weather" "Gets weather for a city" {:location {:type "string"}})

ai/tool-calls#

(tool-calls response)

Extracts tool call requests from an AI response.

Accepts either a raw provider response body or a map produced by chat-with-tools. Returns a vector of {:name :id :input} maps.

Example:

(tool-calls response)

ai/tool-result#

(tool-result call-id result & [opts])

Builds a tool-result message for the given provider.

call-id is the tool call id returned by the model. result is the tool's output as a string (or value that will be stringified).

Optional opts can set :provider (defaults to current config).

Example:

(tool-result "call_abc" "72F sunny")

ai/with-config#

(with-config opts & body)

Temporarily merges opts into the global config for the duration of body, then restores the previous config. Safer than configure for embedded use, since it won't leave global state mutated when body throws.

Example:

(with-config {:provider :openai :model "gpt-4o"} (complete "hi"))