Documentation
¶
Overview ¶
Package claude is the api.Provider for Anthropic's Messages API.
Build one with New and pass it to neui.WithProvider as the app-wide provider, or to neui.OptionProvider to set one session's provider, which takes precedence over WithProvider if any:
p, err := claude.New(claude.Conf{Model: claude.Opus55},
claude.WithMaxTokens(32000),
claude.WithCacheBreakpoints(claude.CacheTools, claude.CacheMessages))
The key comes from ANTHROPIC_API_KEY unless WithAPIKey sets it. A provider serves one model with one set of options; build two for two settings. New refuses an option it cannot apply and a setting the declared model does not take, so a provider for a declared model that builds sends nothing the API refuses for its configuration alone. For a model not declared here New checks no combination and every option is sent as configured.
Only the Anthropic API is supported: api.anthropic.com, or a gateway or proxy that speaks it unchanged, set with WithBaseURL. Amazon Bedrock and Google Cloud Vertex AI authenticate and address models differently, and no model here is declared for them.
Failures reach the thread as api.EventErr with an api.ErrCode, and an error response from the API carries an *APIError, read with errors.As. The adapter talks to the wire directly, with no SDK dependency.
Index ¶
- Variables
- type APIError
- type Breakpoint
- type CacheTTL
- type Conf
- type Effort
- type Option
- func WithAPIKey(key string) Option
- func WithBaseURL(base string) Option
- func WithBeta(flags ...string) Option
- func WithCacheBreakpoints(points ...Breakpoint) Option
- func WithCacheTTL(ttl CacheTTL) Option
- func WithEffort(effort Effort) Option
- func WithHTTPClient(c *http.Client) Option
- func WithMaxTokens(n int) Option
- func WithStopSequences(seqs ...string) Option
- func WithThinking(t Thinking) Option
- func WithTransport(opt lib.Options) Option
- func WithVersion(v string) Option
- type Provider
- type Thinking
- type ThinkingDisplay
- type ThinkingType
Constants ¶
This section is empty.
Variables ¶
var ( Fable51 = api.Model{Name: "claude-fable-5-1", Context: 1_000_000, ImagePixels: 4784 * 28 * 28, ImageSide: 2576, ImageBytes: 7_500_000, ImagesPerRequest: 600, RequestBytes: 128_000_000} Opus55 = api.Model{Name: "claude-opus-5-5", Context: 1_000_000, ImagePixels: 4784 * 28 * 28, ImageSide: 2576, ImageBytes: 7_500_000, ImagesPerRequest: 600, RequestBytes: 128_000_000} Sonnet55 = api.Model{Name: "claude-sonnet-5-5", Context: 1_000_000, ImagePixels: 4784 * 28 * 28, ImageSide: 2576, ImageBytes: 7_500_000, ImagesPerRequest: 600, RequestBytes: 128_000_000} Haiku55 = api.Model{Name: "claude-haiku-5-5", Context: 1_000_000, ImagePixels: 4784 * 28 * 28, ImageSide: 2576, ImageBytes: 7_500_000, ImagesPerRequest: 600, RequestBytes: 128_000_000} Sonnet5 = api.Model{Name: "claude-sonnet-5", Context: 1_000_000, ImagePixels: 4784 * 28 * 28, ImageSide: 2576, ImageBytes: 7_500_000, ImagesPerRequest: 600, RequestBytes: 128_000_000} Haiku45 = api.Model{Name: "claude-haiku-4-5-20251001", Context: 200_000, ImagePixels: 1568 * 28 * 28, ImageSide: 1568, ImageBytes: 7_500_000, ImagesPerRequest: 100, RequestBytes: 128_000_000} )
The current Claude lineup and the two legacy models it replaced, ready to pass as Conf.Model, with the limits the models overview, the vision guide and the API overview publish for the Anthropic API (https://platform.claude.com/docs/en/about-claude/models/overview, read 2026-11-06). Fable 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5 are current; Sonnet 5 and Haiku 4.5 are legacy and still served. Every id is a pinned snapshot; Haiku 4.5 is the one that still carries a date and the one with the smaller window and the standard resolution tier.
ImageSide and ImagePixels are the vision guide's tiers: a 2576 px long edge on Claude 4.7 and later, 1568 px on Haiku 4.5. ImageBytes is the raw size of the API's 10 MB base64 limit per image, because the field is compared against the image's raw bytes. RequestBytes is the 128 MB the Anthropic API takes. These are the Anthropic API's limits only, the one API this package supports. For a model not listed, build an api.Model with its id and limits; New then checks none of its settings.
Functions ¶
This section is empty.
Types ¶
type APIError ¶
type APIError struct {
// Status is the HTTP status, zero for an in-stream error.
Status int
// Type is the API's error type, such as "overloaded_error" or
// "invalid_request_error".
Type string
// Message is the API's explanation; for a body that was not the
// documented JSON it is the trimmed raw body, cut to 512 characters. A
// response that leaves it empty gets "unparseable <status> response". It
// can be empty for an in-stream error.
Message string
// ErrorCode is the error's details.error_code, such as
// "enforced_spend_limit_reached"; empty when the error carries none.
ErrorCode string
// RequestID is Anthropic's request id, to quote to their support; empty
// for an in-stream error.
RequestID string
// RetryAfter is the Retry-After header's wait, zero when the header is
// absent or not a whole number of seconds.
RetryAfter time.Duration
}
APIError is a failure Anthropic reported about the request itself, as opposed to one the connection produced. It covers both places the API puts them: the body of a non 200 response, and an error frame on a stream that already returned 200. Status is zero for the second, which carries neither a status code nor a request id.
It arrives as the Err of an api.EventErr; read it with errors.As. Branch on the event's Code, and use these fields for logs and support requests.
type Breakpoint ¶
type Breakpoint string
Breakpoint names a place a cache_control marker goes. The three follow the order the API invalidates the cache in: tools, then system, then messages.
const ( CacheTools Breakpoint = "tools" // after the last tool definition CacheSystem Breakpoint = "system" // after the last system block CacheMessages Breakpoint = "messages" // after the last block of the last message )
type CacheTTL ¶
type CacheTTL string
CacheTTL is a cache_control ttl. The consts are the documented values; the type does not validate, so a value a later API release adds passes through unchanged.
type Conf ¶
Conf holds the provider's model. Model has no default: New refuses a Conf whose Model.Name is empty.
type Effort ¶
type Effort string
Effort is an output_config.effort level. The consts are the documented values; the type does not validate, so a level a later API release adds passes through unchanged.
type Option ¶
Option configures a Provider at New. An option that returns an error makes New return it.
func WithAPIKey ¶
WithAPIKey overrides the key read from the environment. An empty key sends no x-api-key header, for a gateway that authenticates through its own transport.
func WithBaseURL ¶
WithBaseURL points the adapter at another host: a gateway, a proxy, or a test server. The path /v1/messages is appended to it. A value that is empty or does not parse as a URL with a scheme and host makes New fail; a trailing "/" is trimmed.
func WithCacheBreakpoints ¶
func WithCacheBreakpoints(points ...Breakpoint) Option
WithCacheBreakpoints turns on prompt caching at the given places. Caching is off without it. CacheMessages caches everything up to the latest message, which is what a growing thread wants; any combination stays within the API's limit of four markers.
func WithCacheTTL ¶
WithCacheTTL sets the ttl of the cache_control markers, for example CacheTTL1H. Empty leaves the five minute default. It has no effect without WithCacheBreakpoints.
func WithEffort ¶
WithEffort sets output_config.effort; empty leaves the model default. New refuses any effort on Haiku 4.5, which takes none; on a model not declared here a level the model does not accept fails each turn with api.CodeInvalid. Like the thinking configuration it is part of the cached prompt.
func WithHTTPClient ¶
WithHTTPClient supplies the client, which is where connection reuse, proxies and any overall request deadline come from; it must not be nil. Do not set Timeout on a client used for streaming: it bounds the whole response, so it cuts long turns mid sentence. Use WithTransport instead.
func WithMaxTokens ¶
WithMaxTokens sets max_tokens, the response cap sent on every request; 0 keeps the default of 16384 and a negative value makes New fail. It caps thinking too, which is on by default on the newest models, so raise it for long answers. A turn that hits it ends with api.CodeCapped. New refuses a value over the output ceiling of a model this package declares; on any other model one over its ceiling fails each turn with api.CodeInvalid.
func WithStopSequences ¶
WithStopSequences adds to stop_sequences. A turn that ends on one ends as an ordinary completion, api.CodeTurn, and nothing reports which sequence was hit.
func WithThinking ¶
WithThinking sets the thinking configuration; the zero value sends none and leaves the model default. On a declared model New refuses the settings Thinking lists. It is part of the cached prompt, so switching providers with different settings mid thread starts a new cache prefix, and mid tool use the API silently drops thinking for that request. Keep one setting per thread.
func WithTransport ¶
WithTransport sets the stream limits documented on lib.Options: how long the wire may stay silent and how large one event may grow. A zero field keeps lib's default. The idle deadline is always on, covers the wait for response headers, and resets on every complete event, ping events included, and on every comment or blank line between events, so it catches a dead connection rather than a slow turn; a turn that crosses it ends with api.CodeNetwork.
func WithVersion ¶
WithVersion overrides the anthropic-version header, 2026-10-21 by default. The adapter is written against that version. An empty version is an error.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is one configured Anthropic endpoint. It is safe for concurrent use and holds no per turn state.
func New ¶
New builds a provider for one model. The key defaults to ANTHROPIC_API_KEY. A nil option is skipped. New returns the error of the first option that fails, and an error for an empty Model.Name. On a model this package declares it also returns one for a configuration the API would refuse on every request: the thinking settings Thinking lists, an effort the model does not take, or a WithMaxTokens over its output ceiling. On any other model nothing is checked.
func (*Provider) Model ¶
Model returns the model from Conf. It is fixed for the provider's lifetime.
func (*Provider) Stream ¶
Stream runs one turn on its own goroutine and returns its events. A turn that finishes ends in exactly one EventOk or EventErr, then the channel closes; a cancelled ctx or a connection that just stops closes it with neither. A request whose content cannot be encoded, or is over Model.RequestBytes, ends at once in EventErr with api.CodeInvalid or api.CodeTooLarge. The thread calls it; hosts normally do not.
type Thinking ¶
type Thinking struct {
Type ThinkingType // adaptive, enabled or disabled; empty sends nothing
Budget int // budget_tokens, extended thinking only
Display ThinkingDisplay // summarized or omitted; empty leaves the model default
}
Thinking is the thinking configuration sent verbatim. The zero value sends no thinking field at all, which is not the same as disabling it: on the newest models thinking is on by default.
On a declared model New refuses what the docs refuse on every model: a Budget outside extended thinking, a Budget under 1024 or not below max_tokens (unless WithBeta adds interleaved-thinking-2025-05-14, under which it may exceed it), and a Display with no Type or with ThinkingDisabled. It also refuses the types that model rejects: enabled on Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5 and Sonnet 5; disabled on Fable 5.1, Opus 5.5 and Sonnet 5.5, and on Haiku 5.5 at EffortXHigh or EffortMax; adaptive on Haiku 4.5. A model not declared here is not checked.
type ThinkingDisplay ¶
type ThinkingDisplay string
ThinkingDisplay is how thinking streams back. As with ThinkingType, the const is the documented value and custom strings pass through.
const ( // DisplaySummarized streams a summary of the thinking rather than the // thinking itself. DisplaySummarized ThinkingDisplay = "summarized" // DisplayOmitted streams thinking blocks with no text, only their // signatures; the default on Claude 5 and later. DisplayOmitted ThinkingDisplay = "omitted" )
The documented display values.
type ThinkingType ¶
type ThinkingType string
ThinkingType is the thinking mode sent on the wire. The consts are the documented values; the type does not validate, so a value a later API release adds passes through unchanged.
const ( ThinkingAdaptive ThinkingType = "adaptive" // the model decides how much to think; 4.6 and later ThinkingEnabled ThinkingType = "enabled" // extended thinking with Thinking.Budget; before 4.7 ThinkingDisabled ThinkingType = "disabled" // no thinking, where the model allows it )