@spec allowlist(String.t()) :: [String.t()]

The positive allowlist of provider block types, per client style (SPEC §8A).

@spec assert_allowed!(map(), String.t(), term()) :: map()

Assert an encoded block against the style's positive allowlist (SPEC §8A). A block that is not on the list never reaches the wire: an unknown block type upstream returns HTTP 200 with the content silently discarded, not an error.

@spec audio(
  term(),
  keyword()
) :: {:ok, t()} | {:error, Exception.t()}

Build an audio part from any accepted source (see new/3).

@spec audio!(
  term(),
  keyword()
) :: t()

Like audio/2 but raises on failure and returns the part.

@spec byte_size_of(t() | map()) :: non_neg_integer()

Decoded byte length of a part's payload — 0 for a URL-backed or text part.

@spec describe(t() | map()) :: map()

Log/event rendering of a part (SPEC §9): {type, mimeType, bytes} — never data.

@spec encode([t() | map()], String.t(), keyword()) :: [map()]

Encode a list of parts into provider blocks for style, applying the SPEC §8A provenance rule to any part the style cannot represent:

• provenance: :attached (the caller attached it) ⇒ a typed error, raised at assembly, before any HTTP call;
• provenance: :derived (it came off a tool / MCP result) ⇒ a text placeholder naming the type and mime type, warned at most once, the run continues.

on_unsupported ("error" | "text") overrides both uniformly. Every produced block is asserted against the style's positive allowlist before it is returned.

:max_part_bytes is enforced HERE, at assembly, over every part whatever its provenance — not only in the edge constructors. A part that arrived from an MCP server never passed through a constructor, so a limit it can walk around is not a limit. Going over routes through the same provenance rule as an unsupported part, so a server volunteering a huge image still cannot fail the caller's run.

@spec estimated_tokens(t() | map()) :: non_neg_integer()

Byte-derived token estimate for a part (SPEC §9). Never the length of the mimeType string — that would score a 5 MB image at ~3 tokens and make it uncompactable.

@spec file(
  term(),
  keyword()
) :: {:ok, t()} | {:error, Exception.t()}

Build a file part from any accepted source (see new/3).

@spec file!(
  term(),
  keyword()
) :: t()

Like file/2 but raises on failure and returns the part.

@spec from_map(map()) :: t()

Decode from a JSON-shaped map (string keys, mimeType spelling).

@spec image(
  term(),
  keyword()
) :: {:ok, t()} | {:error, Exception.t()}

Build an image part from any accepted source (see new/3).

@spec image!(
  term(),
  keyword()
) :: t()

Like image/2 but raises on failure and returns the part.

@spec media_for_path(String.t()) :: {:ok, {String.t(), String.t()}} | :error

{mimeType, type} for a path's extension, or :error when it is not in the table.

@spec media_table() :: %{required(String.t()) => {String.t(), String.t()}}

The fixed extension → {mimeType, part type} media table (SPEC §6).

@spec new(String.t(), term(), keyword()) :: {:ok, t()} | {:error, Exception.t()}

Build a non-text part of type from source, normalising at construction (SPEC §1B):

• a data:<mime>;base64,<b64> URL → {mime_type, data}, never stored as url
• an http:/https: URL → kept as url
• {:bytes, binary} → base64 now; :mime_type required
• iodata (any iolist, improper lists included) → IO.iodata_to_binary/1 now, base64 now; :mime_type required
• a File.Stream → read to bytes now, base64 now; mime from the stream's .path via the fixed table (§6) unless :mime_type says otherwise
• any other Enumerable of binary chunks → consumed eagerly now; :mime_type required
• any other binary → a filesystem path: read now, base64 now, mime from the fixed table

A bare binary is never treated as raw content — see the module doc for why {:bytes, bin} stays explicitly tagged.

Options: :mime_type (required for bytes/iodata/enumerables, overrides the table for a path or a File.Stream), :name, :max_part_bytes (a cap on decoded bytes).

@spec new!(String.t(), term(), keyword()) :: t()

Like new/3 but raises on failure and returns the part.

@spec part?(term()) :: boolean()

True when m is a ContentPart (or its wire map) rather than a provider block.

@spec summary(t() | map()) :: String.t()

A one-line, data-free description of a non-text part, used as output when a tool or an MCP server returned parts and no text at all (so output is never a bare empty string).

@spec text(String.t()) :: t()

A text part.

@spec to_block(t() | map(), String.t()) :: {:ok, map()} | {:unsupported, String.t()}

Map one part onto a provider block for style ("openai" | "anthropic").

Returns {:ok, block}, or {:unsupported, reason} when the style defines no shape for that part — anthropic × audio and openai × file+url are the named refusals.

@spec to_map(t() | map()) :: map()

Encode to a JSON-shaped map (string keys, nil fields omitted).

@spec validate(t()) :: {:ok, t()} | {:error, Exception.t()}

Validate a part built by hand: exactly one of data/url on a non-text part, and a mime_type unless the source is a bare URL.