anthropic

package
v0.13.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 15, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package anthropic is the anthropic dialect: Claude through the Messages API, first-party and on Vertex AI (docs/design.md §7.3, phase L4).

It adapts the official SDK (github.com/anthropics/anthropic-sdk-go): a genai-shaped llm.Request becomes a MessageNewParams, and the SSE stream is accumulated back into genai-shaped Responses. The shape is mast's — option structs, no registry, usage in usage.Detail — and the behavior core-agent built after the two copies split is ported onto it: rolling and one-hour prompt caching (cache.go), per-call opt-outs through callctx, and the positional schema normalizer. The thinking-request shape is mast's, chosen per model generation.

Retries

The SDK's own retries are off. Package retry's Transport does it in the HTTP client instead, as for every other dialect, so a 429 is handled the same way whichever model a workload names and each attempt carries a fresh credential.

Vertex AI

Claude on Vertex is the same Messages body sent to a different URL: the model moves from the body into the path, and the body carries an anthropic_version. Options.Vertex turns that rewrite on; see vertex.go. It is done here rather than through the SDK's vertex package so that the credential is core-models' own (package auth) and the core module takes no golang.org/x/oauth2 or google.golang.org/api dependency.

Index

Constants

View Source
const (
	// TTL5m is the five-minute breakpoint, Anthropic's default. Writes
	// bill at 1.25x base input.
	TTL5m = "5m"
	// TTL1h is the one-hour breakpoint. Writes bill at 2x base input,
	// so it only pays when consecutive requests are routinely more than
	// five minutes apart.
	TTL1h = "1h"
)

Prompt-cache breakpoint lifetimes, for CacheOptions.TTL.

View Source
const DefaultBaseURL = "https://api.anthropic.com"

DefaultBaseURL is the first-party API root.

View Source
const DefaultMaxTokens = 16_384

DefaultMaxTokens caps a single response when the request sets no MaxOutputTokens. 16K is plenty for most turns and well under the streaming HTTP timeouts.

View Source
const VertexVersion = "vertex-2023-10-16"

VertexVersion is the anthropic_version Vertex AI requires in the body of every Claude request, in place of the first-party anthropic-version header.

View Source
const WebSearch = "web_search"

WebSearch is the provider-neutral name for Claude's web_search, the one built-in this adapter surfaces.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError

type APIError struct {
	// contains filtered or unexported fields
}

APIError is an error the Anthropic API answered with. It wraps the SDK's *anthropic.Error, which errors.As still finds, and adds the HTTPStatus method products classify retryable failures by — the same method openaichat.APIError has, so one check covers every dialect.

An error can arrive two ways. Before the stream starts it is an ordinary non-2xx response, which package retry has already retried if the status allowed. After it starts, the server sends an SSE error event on a response that answered 200 — an overloaded_error midway through generation, say. The transport cannot retry that: tokens may already have reached the caller, and replaying the request would deliver them twice. HTTPStatus then reports the status the error's type stands for (overloaded_error is 529), not the stream's 200, so a product's own retry policy can still tell a transient failure from a permanent one; MidStream says which case it was.

func (*APIError) Error

func (e *APIError) Error() string

Error is the SDK's message with the URL corrected. The SDK names the request as it built it; on Vertex AI the middleware then rewrote it (…/v1/messages → …/models/<id>:rawPredict), and a message naming the path that was never called sends anyone reading logs to the wrong endpoint (#35). The response carries the request actually sent.

func (*APIError) HTTPStatus

func (e *APIError) HTTPStatus() int

HTTPStatus is the response's status, or for a mid-stream error the status its type stands for.

func (*APIError) MidStream

func (e *APIError) MidStream() bool

MidStream reports whether the error arrived as an SSE event after the response had started, which no transport retries.

func (*APIError) Unwrap

func (e *APIError) Unwrap() error

type BuiltinTools

type BuiltinTools struct {
	WebSearch bool // Server-side web search; per-search billing on top of tokens.
}

BuiltinTools toggles Anthropic's server-side built-in tools surfaced by this provider. Each enabled flag becomes one entry on the request's Tools slice alongside any user-defined function declarations.

Defaults: everything OFF. Anthropic's server-side tools are billed per use on top of token cost (web_search is per-search), so we apply the same "active surface = opt in" rule that keeps Gemini's CodeExecution off by default. The library caller decides explicitly whether the cost and external-action posture are acceptable.

To turn one on:

c, _ := anthropic.New(anthropic.Options{
    …,
    BuiltinTools: anthropic.BuiltinTools{WebSearch: true},
})

callctx.WithoutBuiltins drops them for one call.

Other Anthropic server-side tools (web_fetch, code_execution, text_editor, bash, memory) aren't surfaced today. Add them under the same struct when a concrete consumer needs one.

func BuiltinToolsFromNames

func BuiltinToolsFromNames(names []string) (BuiltinTools, error)

BuiltinToolsFromNames maps provider-neutral names onto the toggles. A name Claude has no tool for — url_context and code_execution are Gemini's — is an error, not a silently absent tool, as for the gemini dialect.

func (BuiltinTools) Names

func (b BuiltinTools) Names() []string

Names reports the enabled built-ins under the provider-neutral names mast's and core-agent's builtin_tools blocks use, so a report reads the same whichever provider is resolved and an operator can match it against the keys they typed.

The block's url_context and code_execution are Gemini-side and have no Anthropic equivalent, so they can never appear here. That is the direction that fails safe: a tool this provider cannot send is one it cannot leave on.

type CacheOptions

type CacheOptions struct {
	// System marks the last system block. Since the render order is
	// tools → system → messages, that one marker caches the tool
	// schemas and the system prompt together.
	System bool
	// History places rolling breakpoints over the tail of the
	// conversation so a growing transcript is re-read at the cache
	// rate instead of re-billed in full every turn (core-agent #714).
	History bool
	// TTL is the breakpoint lifetime: TTL5m (the zero value's meaning)
	// or TTL1h. Both are priced, and the response reports which one
	// each write used (usage.Detail.CacheWrite1hTokens), so the ledger
	// is right either way (core-agent #770). Any other value is treated
	// as TTL5m.
	TTL string
}

CacheOptions selects which parts of a request carry Anthropic cache_control breakpoints. Both halves are prefix-cached by the same mechanism; they're separable because they fail differently — System is worthless if the instruction carries a per-turn timestamp, History is worthless for one-shot calls that never replay a prefix.

The zero value disables caching entirely.

func DefaultCacheOptions

func DefaultCacheOptions() CacheOptions

DefaultCacheOptions caches the stable prefix and the conversation tail at the five-minute TTL. coremodels.Open applies it unless told otherwise: the break-even is two requests against a 5-minute TTL, and an agent loop issues its second request seconds after the first. The shape that loses — a single request whose prefix is never seen again — is a side call, and callctx.WithoutPromptCache turns caching off for exactly that call.

func (CacheOptions) Enabled

func (o CacheOptions) Enabled() bool

Enabled reports whether any breakpoint would be placed.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client holds one configured SDK client. It is safe for concurrent use, and every model it returns shares its connection pool.

func New

func New(opts Options) (*Client, error)

New returns a Client for opts.

func (*Client) Model

func (c *Client) Model(id string) llm.LLM

Model returns the model id as an llm.LLM. Vertex AI sometimes serves Claude under a date-suffixed id ("claude-opus-4-5@20251101"); pass the id the backend expects, since it goes into the URL verbatim.

type Options

type Options struct {
	// BaseURL is the API root. Empty means DefaultBaseURL. With Vertex
	// set it is the publisher prefix
	// .../projects/{p}/locations/{r}/publishers/anthropic/models, and a
	// request goes to BaseURL/{model}:streamRawPredict.
	BaseURL string
	// Credential authenticates every request: an api_key credential as
	// x-api-key, as the first-party API expects, and any other kind as
	// a bearer token (Google ADC on Vertex, or a gateway's token). Nil
	// sends none.
	Credential *auth.Credential
	// Vertex routes requests the way Vertex AI serves Claude.
	Vertex bool
	// HTTPClient supplies the base transport and timeout. Nil means a
	// client with http.DefaultTransport.
	HTTPClient *http.Client
	// Retry is the HTTP-layer retry policy. Nil means retry.Default().
	Retry *retry.Policy

	// Backend and Region are stamped into every usage.Detail.
	Backend string
	Region  string

	// Cache is the prompt-caching policy. The zero value places no
	// breakpoints; coremodels.Open passes DefaultCacheOptions unless
	// told otherwise.
	Cache CacheOptions
	// BuiltinTools are Anthropic's server-side tools, all off unless
	// set (mast #340).
	BuiltinTools BuiltinTools
}

Options configures a Client. A coremodels.Open caller never builds one by hand; it comes from a resolved profile.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL