@spec beta_headers() :: [{String.t(), String.t()}]

Get the required beta headers for Skills API requests.

These headers must be included in all API requests that use Skills or code execution features.

Example

headers = Conjure.API.Anthropic.beta_headers()
# => [{"anthropic-beta", "code-execution-2025-08-25,skills-2025-10-02,files-api-2025-04-14"}]

@spec build_assistant_message(map()) :: map()

Build the assistant message from a response for continuing conversation.

Use this when handling pause_turn to build the next messages array.

Example

# Response came back with pause_turn
assistant_message = build_assistant_message(response)
updated_messages = messages ++ [assistant_message]
# Continue with updated_messages

@spec build_request([map()], map(), keyword()) :: map()

Build a complete messages API request body.

Combines messages, container config, and options into a complete request body ready to be JSON-encoded.

Options

• :model - Model to use (default: "claude-sonnet-4-5-20250929")
• :max_tokens - Maximum tokens in response (default: 4096)
• :system - System prompt
• :tools - Additional tools (code_execution is added automatically)
• :metadata - Request metadata

Example

{:ok, container} = container_config([{:anthropic, "xlsx", "latest"}])

request = build_request(
  [%{"role" => "user", "content" => "Create a spreadsheet"}],
  container,
  model: "claude-sonnet-4-5-20250929",
  max_tokens: 8192,
  system: "You are a helpful assistant."
)

@spec code_execution_tool() :: map()

Get the code execution tool definition.

This tool definition must be included in the tools array when making API requests with Skills.

Example

tools = [Conjure.API.Anthropic.code_execution_tool()]

@spec container_config([skill_spec()]) :: {:ok, map()} | {:error, Conjure.Error.t()}

Build the container configuration for skills.

Accepts a list of skill specifications and returns the container parameter for the API request. Maximum 8 skills per request.

Skill Specification Format

Each skill is a tuple: {type, skill_id, version}

• type - :anthropic for pre-built skills, :custom for uploaded
• skill_id - Short name ("xlsx") or generated ID ("skill_01...")
• version - Version string or "latest"

Example

{:ok, container} = Conjure.API.Anthropic.container_config([
  {:anthropic, "xlsx", "latest"},
  {:custom, "skill_01AbCdEfGhIjKlMnOpQrStUv", "v1"}
])

# Returns:
# %{
#   "skills" => [
#     %{"type" => "anthropic", "skill_id" => "xlsx", "version" => "latest"},
#     %{"type" => "custom", "skill_id" => "skill_01...", "version" => "v1"}
#   ]
# }

@spec container_config!([skill_spec()]) :: map()

Build container config, raising on error.

@spec end_turn?(map() | parsed_response()) :: boolean()

Check if response indicates end_turn (conversation complete).

@spec extract_file_ids(map()) :: [String.t()]

Extract file IDs from a response.

Skills that create files (xlsx, pptx, pdf) include file references in the response content. These IDs can be used with the Files API to download the created documents.

Example

file_ids = extract_file_ids(response)
# => ["file_01AbCdEf...", "file_02GhIjKl..."]

Enum.each(file_ids, fn file_id ->
  {:ok, content, filename} = Conjure.Files.Anthropic.download(file_id, api_callback)
  File.write!(filename, content)
end)

@spec extract_text(map()) :: String.t()

Extract text content from a response.

@spec parse_response(map()) :: {:ok, parsed_response()} | {:error, term()}

Parse an API response, extracting relevant fields.

Extracts content, stop_reason, container_id, file_ids, and usage from the response.

Example

{:ok, parsed} = parse_response(api_response)

if pause_turn?(parsed) do
  # Continue conversation
end

file_ids = parsed.file_ids

@spec pause_turn?(map() | parsed_response()) :: boolean()

Check if response indicates a pause_turn (long-running operation).

When true, the conversation should continue by sending the response content back to the API with the same container ID.

Example

{:ok, parsed} = parse_response(response)

if pause_turn?(parsed) do
  # Long-running operation in progress, continue conversation
  updated_container = with_container_id(container, parsed.container_id)
  # ... continue loop
end

@spec with_container_id(map(), String.t()) :: map()

Add a container ID to an existing container config.

Use this for multi-turn conversations to reuse the same container.

Example

# First request - no container ID
{:ok, container} = container_config([{:anthropic, "xlsx", "latest"}])

# Parse container ID from response
container_id = get_in(response, ["container", "id"])

# Subsequent requests - reuse container
container_with_id = with_container_id(container, container_id)