Normandy.Components.ContentBlock.Document (normandy v0.6.0)

View Source

Represents a document content block inside a multimodal message.

Currently supports documents referenced by a Files-API file_id. Base64 and URL sources can be added later — the library's raw-list fallback in the adapter already handles arbitrary pre-shaped block maps.

Cache control

An optional cache_control field carries an Anthropic prompt-cache breakpoint annotation that the adapter ships verbatim on the wire. Use with_cache/1 for the default ephemeral type, or with_cache/2 for a custom map (e.g. %{"type" => "ephemeral", "ttl" => "1h"}). Atom keys are accepted and stringified at serialization time.

Summary

Types

source()
t()

Functions

new_file(file_id)

Builds a document block referencing a file uploaded via Anthropic's Files API.

to_claudio(block)

Converts the block into the Anthropic/Claudio content-block map shape (string keys). Includes cache_control only when set.

with_cache(block)

Annotates this block with an ephemeral cache breakpoint.

with_cache(block, cache_control)

Annotates this block with a caller-supplied cache_control map.

Types

source()

@type source() :: :file_id

t()

@type t() :: %Normandy.Components.ContentBlock.Document{
  __meta__: term(),
  cache_control: map() | nil,
  file_id: String.t() | nil,
  source: source()
}

Functions

new_file(file_id)

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

Builds a document block referencing a file uploaded via Anthropic's Files API.

to_claudio(block)

@spec to_claudio(t()) :: %{required(String.t()) => term()}

Converts the block into the Anthropic/Claudio content-block map shape (string keys). Includes cache_control only when set.

Raises ArgumentError on an incomplete struct (e.g. source: :file_id with nil file_id). The constructor (new_file/1) enforces valid state, so this only fires when a caller bypasses it.

with_cache(block)

@spec with_cache(t()) :: t()

Annotates this block with an ephemeral cache breakpoint.

with_cache(block, cache_control)

@spec with_cache(t(), map()) :: t()

Annotates this block with a caller-supplied cache_control map.

Atom keys are accepted; they are stringified when serialized.