The ONLY block types that may reach each style's wire. A part encoding to anything else never leaves this namespace: map-and-hope is precisely how an unknown block reaches a provider that answers 200 and drops the content.
The ONLY block types that may reach each style's wire. A part encoding to anything else never leaves this namespace: map-and-hope is precisely how an unknown block reaches a provider that answers 200 and drops the content.
(attach source)(attach source opts)The edge: hand it whatever you actually have and get a path-free part.
A STRING is dispatched on its shape — a data: URL is parsed, an http(s):
URL is kept as a :url, anything else is a filesystem path read now. ANYTHING
ELSE is bytes, and goes to from-bytes: a native byte array (JVM byte[] /
Go []byte) or any sequence of byte values. To attach a string as its UTF-8
BYTES rather than as a path, call from-bytes directly — attach cannot tell
those two apart, and guessing is how a payload silently becomes a filename.
A host file/stream object (java.io.File, InputStream, a Go *os.File) is
refused by name — see from-bytes for why this port's list is shorter than the
other six.
The edge: hand it whatever you actually have and get a path-free part. A STRING is dispatched on its shape — a `data:` URL is parsed, an `http(s):` URL is kept as a `:url`, anything else is a filesystem path read now. ANYTHING ELSE is bytes, and goes to `from-bytes`: a native byte array (JVM `byte[]` / Go `[]byte`) or any sequence of byte values. To attach a string as its UTF-8 BYTES rather than as a path, call `from-bytes` directly — `attach` cannot tell those two apart, and guessing is how a payload silently becomes a filename. A host file/stream object (`java.io.File`, `InputStream`, a Go `*os.File`) is refused by name — see `from-bytes` for why this port's list is shorter than the other six.
(base-name p)The last path segment of p. Both separators are folded, so a Windows-shaped
path does not come back whole on a POSIX host.
The last path segment of `p`. Both separators are folded, so a Windows-shaped path does not come back whole on a POSIX host.
(base64-bytes b64)The DECODED byte length of standard, padded base64 — without decoding it.
maxPartBytes is measured in these bytes, which is the whole point: the base64
string is 33% larger and a limit against it would be a different limit.
The DECODED byte length of standard, padded base64 — without decoding it. `maxPartBytes` is measured in these bytes, which is the whole point: the base64 string is 33% larger and a limit against it would be a different limit.
(build-wire messages opts)The canonical transcript as opts's style wants it.
Returns {:messages [...]} or {:error msg :code c} — never throws, and never
mutates the transcript it was handed.
The canonical transcript as `opts`'s style wants it.
Returns `{:messages [...]}` or `{:error msg :code c}` — never throws, and never
mutates the transcript it was handed.(content-part? x)True when x looks like a §1B ContentPart — as opposed to a provider-native
block that happens to be a map.
True when `x` looks like a §1B ContentPart — as opposed to a provider-native block that happens to be a map.
(describe-part part)How a part appears in a log line or a §9 event: {type, mimeType, bytes}.
NEVER data. Same rule as never-log-headers — a part's payload is user
content, and a §9 event is a place it must not leak.
How a part appears in a log line or a §9 event: `{type, mimeType, bytes}`.
NEVER `data`. Same rule as never-log-headers — a part's payload is user
content, and a §9 event is a place it must not leak.(encode-part part style)One part as its provider block, or nil when the style defines NO shape for it.
The nils are EXPLICIT refusals, never a fall-through: openai × file+url (Chat
Completions has no URL form for a file), openai × audio+url, and
anthropic × audio (the provider defines no audio block at all).
One part as its provider block, or nil when the style defines NO shape for it. The nils are EXPLICIT refusals, never a fall-through: `openai × file+url` (Chat Completions has no URL form for a file), `openai × audio+url`, and `anthropic × audio` (the provider defines no audio block at all).
(encode-parts parts
{:keys [style provenance on-unsupported-part max-part-bytes]})Encode parts for one style. Returns {:blocks [...]} or {:error msg :code c}.
§8A, by PROVENANCE: a part the caller ATTACHED that the style cannot represent
is an error before any HTTP call — the caller asked for something specific and
silently changing it is the betrayal. A part DERIVED from a tool / MCP result
degrades to a text placeholder and warns once — failing a caller's run because
a server volunteered an audio clip would be a regression on behaviour that
succeeds today. :on-unsupported-part ("error" | "text") overrides both
uniformly. A part is NEVER dropped silently.
This returns data rather than throwing for the reason at the top of the file:
the loop turns an :error into a stopped RunResult, which is how a failure
crosses a boundary in this port.
Encode `parts` for one style. Returns `{:blocks [...]}` or `{:error msg :code c}`.
§8A, by PROVENANCE: a part the caller ATTACHED that the style cannot represent
is an error before any HTTP call — the caller asked for something specific and
silently changing it is the betrayal. A part DERIVED from a tool / MCP result
degrades to a text placeholder and warns once — failing a caller's run because
a server volunteered an audio clip would be a regression on behaviour that
succeeds today. `:on-unsupported-part` ("error" | "text") overrides both
uniformly. A part is NEVER dropped silently.
This returns data rather than throwing for the reason at the top of the file:
the loop turns an `:error` into a stopped RunResult, which is how a failure
crosses a boundary in this port.(error-part code message)A construction failure, AS DATA. Clojure's source boundary does not throw
(toolnexus.tool/execute, toolnexus.mcp), and neither does this one — the
failure travels as a value until the loop can report it, which is the same
deferred-error shape the Go port's File(path) uses.
A construction failure, AS DATA. Clojure's source boundary does not throw (`toolnexus.tool/execute`, `toolnexus.mcp`), and neither does this one — the failure travels as a value until the loop can report it, which is the same deferred-error shape the Go port's `File(path)` uses.
(extension-of p)The lower-cased extension of p WITHOUT the dot, or "" when there is none.
Read off the base name so a dot in a parent directory cannot be mistaken for
one.
The lower-cased extension of `p` WITHOUT the dot, or "" when there is none. Read off the base name so a dot in a parent directory cannot be mistaken for one.
(from-bytes bs mime)(from-bytes bs mime opts)A part from bytes already in hand. mime is REQUIRED — bytes carry no
extension to read — and the base64 happens here, so the caller never pays the
encoding tax in their own program.
ACCEPTS, on both hosts: a native byte array (JVM byte[] / Go []byte, i.e.
what koine.fs/read-bytes returns), ANY sequence of byte values (vector, list,
lazy seq, (seq some-byte-array); signed or unsigned), and a string, which is
taken as its UTF-8 bytes.
DOES NOT ACCEPT a host file/stream object — java.io.File, java.io.InputStream,
a Go *os.File. Not an oversight: this port is one .cljc for two hosts, and
naming a JVM type here would make the namespace unloadable on cljgo, while koine
offers no host-neutral stream abstraction to stand in for one. Such a source
gets an unsupported-source ERROR PART naming the type and telling the caller
to pass a path or bytes — never a cast error, and never a throw.
koine.codec/encode is the encoder because its docstring names this exact use:
standard base64 with padding (RFC 4648 §4), NOT the URL-safe alphabet, which is
what MCP image/blob blocks and every provider want.
A part from bytes already in hand. `mime` is REQUIRED — bytes carry no extension to read — and the base64 happens here, so the caller never pays the encoding tax in their own program. ACCEPTS, on both hosts: a native byte array (JVM `byte[]` / Go `[]byte`, i.e. what `koine.fs/read-bytes` returns), ANY sequence of byte values (vector, list, lazy seq, `(seq some-byte-array)`; signed or unsigned), and a string, which is taken as its UTF-8 bytes. DOES NOT ACCEPT a host file/stream object — `java.io.File`, `java.io.InputStream`, a Go `*os.File`. Not an oversight: this port is one `.cljc` for two hosts, and naming a JVM type here would make the namespace unloadable on cljgo, while koine offers no host-neutral stream abstraction to stand in for one. Such a source gets an `unsupported-source` ERROR PART naming the type and telling the caller to pass a path or bytes — never a cast error, and never a throw. `koine.codec/encode` is the encoder because its docstring names this exact use: standard base64 with padding (RFC 4648 §4), NOT the URL-safe alphabet, which is what MCP image/blob blocks and every provider want.
(from-data-url u)(from-data-url u opts)Parse data:<mime>;base64,<b64> into {:mimeType … :data …}, so two spellings
of the same bytes cannot diverge downstream. NEVER stored as a :url.
Parse `data:<mime>;base64,<b64>` into `{:mimeType … :data …}`, so two spellings
of the same bytes cannot diverge downstream. NEVER stored as a `:url`.(from-file path)(from-file path opts)Read path NOW and base64 it NOW, so the part never carries the path (§1B).
The mime type comes from the FIXED extension table (or :mimeType in opts);
an unknown extension with no explicit mime is an error part naming it.
koine.fs/read-bytes, never read-file: the text route is slurp, which is
lossy for non-UTF-8 bytes IDENTICALLY ON BOTH HOSTS — so it would produce a
plausible, self-consistent, WRONG base64 that agrees with itself and disagrees
with the other six ports.
Read `path` NOW and base64 it NOW, so the part never carries the path (§1B). The mime type comes from the FIXED extension table (or `:mimeType` in `opts`); an unknown extension with no explicit mime is an error part naming it. `koine.fs/read-bytes`, never `read-file`: the text route is `slurp`, which is lossy for non-UTF-8 bytes IDENTICALLY ON BOTH HOSTS — so it would produce a plausible, self-consistent, WRONG base64 that agrees with itself and disagrees with the other six ports.
(from-url u)(from-url u opts)Keep an http(s): URL as a :url part. The mime comes from the table or from
:mimeType; an unknown extension with neither is an error part naming it.
Keep an `http(s):` URL as a `:url` part. The mime comes from the table or from `:mimeType`; an unknown extension with neither is an error part naming it.
(image-file path)(image-file path opts)from-file, pinned to an image part — the spelling SPEC §1B's Clojure
example uses. A path whose table entry is not an image is an error part rather
than a quietly different kind.
`from-file`, pinned to an `image` part — the spelling SPEC §1B's Clojure example uses. A path whose table entry is not an image is an error part rather than a quietly different kind.
(inbound-part block)An inbound OpenAI-shaped content block as a §1B ContentPart, or nil when the block is neither. Accepts a ContentPart written literally AND the native block the same part encodes to, so a caller's own OpenAI messages translate as faithfully as ours do.
An inbound OpenAI-shaped content block as a §1B ContentPart, or nil when the block is neither. Accepts a ContentPart written literally AND the native block the same part encodes to, so a caller's own OpenAI messages translate as faithfully as ours do.
(media-type-for p)The table entry for a path or URL path, or nil when the extension is not media.
The table entry for a path or URL path, or nil when the extension is not media.
SPEC §6 — FIXED, shared with the edge constructors, identical in every port.
No magic-byte sniffing and no platform mime database: /etc/mime.types varies
per machine, so the same .webp would resolve differently on two boxes and
break the byte-identical fixture this repo is built around.
SPEC §6 — FIXED, shared with the edge constructors, identical in every port. No magic-byte sniffing and no platform mime database: `/etc/mime.types` varies per machine, so the same `.webp` would resolve differently on two boxes and break the byte-identical fixture this repo is built around.
(part-array? content)True when a message's :content is a canonical ContentPart vector rather than
an already-native block array.
True when a message's `:content` is a canonical ContentPart vector rather than an already-native block array.
(part-bytes part)A part's payload size in decoded bytes. A url-only part carries no bytes here.
A part's payload size in decoded bytes. A url-only part carries no bytes here.
(part-type-for-mime mime)Part kind for a mime type: image/* ⇒ image, audio/* ⇒ audio, else file.
Part kind for a mime type: `image/*` ⇒ image, `audio/*` ⇒ audio, else file.
(relocation-header name id)The text preceding each relocated part, so the model can attribute it to its call. Byte-pinned across the ports.
The text preceding each relocated part, so the model can attribute it to its call. Byte-pinned across the ports.
(reset-unsupported-warnings!)Test seam — forget which unsupported pairs have been warned about.
Test seam — forget which unsupported pairs have been warned about.
(summarize-part part)A one-line, payload-free rendering of a part — for output text.
SPEC §1B pins this string BYTE-IDENTICALLY across all seven ports: it reaches a
model's context, so a port inventing its own wording is exactly the drift §0
exists to prevent. <bytes> is the DECODED count as a plain integer, and a part
carrying a url instead of data renders it as 0.
A one-line, payload-free rendering of a part — for `output` text. SPEC §1B pins this string BYTE-IDENTICALLY across all seven ports: it reaches a model's context, so a port inventing its own wording is exactly the drift §0 exists to prevent. `<bytes>` is the DECODED count as a plain integer, and a part carrying a `url` instead of `data` renders it as 0.
(text-part s)A text part. NOT named text: this namespace already requires koine.text
as text, and a var shadowing an alias is the kind of one-host surprise the
port avoids on principle.
A `text` part. NOT named `text`: this namespace already requires `koine.text` as `text`, and a var shadowing an alias is the kind of one-host surprise the port avoids on principle.
(unsupported-placeholder part)What a degraded (non-failing) unsupported part leaves behind — never silence. The third of §1B's three byte-identical user-visible strings.
What a degraded (non-failing) unsupported part leaves behind — never silence. The third of §1B's three byte-identical user-visible strings.
(validate-part part)(validate-part part max-part-bytes)SPEC §1B — exactly one of data / url, and (when max-part-bytes is set)
a decoded payload within it. Returns the part, or an ERROR PART naming what is
wrong. An error part passes straight through so the first failure is the one
reported.
SPEC §1B — exactly one of `data` / `url`, and (when `max-part-bytes` is set) a decoded payload within it. Returns the part, or an ERROR PART naming what is wrong. An error part passes straight through so the first failure is the one reported.
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 |