anthropic

package module
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: May 30, 2026 License: GPL-3.0 Imports: 14 Imported by: 0

README

anthropic

golang interface for Anthropic's Machine Learning inference HTTP API interface, specifically the Messaging API. Colloquially, this is the API for the Claude family of Machine Learning model such as Claude Sonnet 3.5.

Note: This library is currently optimized for document processing pipelines and batch operations rather than interactive chat applications. It provides detailed token tracking and handles continuation of long responses, making it ideal for processing large documents, content analysis, and structured data extraction workflows.

It presents a Conversation struct that can be used to interact with the API. The API key is read from the environment variable ANTHROPIC_API_KEY.

The Conversation struct has a Send method that takes a string input and returns a string reply, a string stop reason, input tokens, output tokens, and an error. The stop reason is a string that indicates why the conversation stopped. The input and output tokens are the tokens that were used for the input and output strings, respectively.

More interestingly, the Conversation struct contains the history of the conversation, so you can continue a conversation by calling Send with a new input string.

There is an anthropic.DefaultSettings struct that can be used to set the defaults for the Conversation struct.

You may also set the default API token for the Conversation struct by setting anthropic.DefaultApiToken. This can be useful if you have multiple Conversations.

If you want to set the API key on a per Conversation basis, you can set the ApiToken field of the Conversation struct once it is created using NewConversation.

The anthropic.DefaultSettings struct has the following fields:

var DefaultSettings = SampleSettings{
	Model:       "claude-3-5-sonnet-20240620",
	Version:     "2023-06-01",
	Beta:        "", // "max-tokens-3-5-sonnet-2024-07-15"
	MaxTokens:   4096,
	Temperature: 0.0,
}

Installation

go get github.com/wbrown/anthropic

Usage

package main

import (
    "fmt"
    "log"

    "github.com/wbrown/anthropic"
)

func main() {
    // API key is read from the environment variable ANTHROPIC_API_KEY
    // You can also set the API key by setting conversation.Settings.ApiToken
    conversation := anthropic.NewConversation("You are a friendly chatbot.")
	reply, stopReason, inputTokens, outputTokens, err :=
		conversation.Send("Hello Claude!")
	if err != nil {
		log.Fatal(err)
	}
    fmt.Println("Reply:", reply)
    fmt.Println("Stop Reason:", stopReason)
    fmt.Println("Input Tokens:", inputTokens)
    fmt.Println("Output Tokens:", outputTokens)

    reply, _, _ ,_, err = conversation.Send("How are you?")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("Reply:", reply)
}

Prompt Caching

The library supports Anthropic's prompt caching feature, which can reduce costs by up to 90% and latency by up to 85% for repeated context. This is especially useful for:

  • Large documents or context that doesn't change between requests
  • System prompts that remain constant
  • Multiple questions about the same data
  • Development and testing (using the same context repeatedly)
Basic Caching Example
conversation := anthropic.NewConversation("You are a helpful assistant.")

// Create a large context block and enable caching
contextText := "Here is a large document with 2000+ tokens..."
contextBlock := anthropic.ContentBlock{
    ContentType: "text",
    Text:        &contextText,
}
contextBlock.EnableCaching() // Adds cache_control

// Add the cached context
conversation.AddMessage("user", &[]anthropic.ContentBlock{contextBlock})

// Add your question (not cached)
questionBlock := anthropic.ContentBlock{
    ContentType: "text",
    Text:        &questionText,
}
conversation.AddMessage("user", &[]anthropic.ContentBlock{questionBlock})

// Send the request - first time will cache, subsequent calls reuse cache
reply, _, _, _, err := conversation.Send("")

// Check cache statistics
fmt.Printf("Cache Hit Rate: %.1f%%\n", conversation.CacheHitRate())
fmt.Printf("Savings Rate: %.1f%%\n", conversation.CacheSavingsRate())
Cache Statistics

The conversation tracks cache usage:

  • CacheStats.CacheHits - Number of times cached content was reused
  • CacheStats.CacheMisses - Number of times new content was cached
  • CacheStats.TotalTokensSaved - Tokens saved by using cache (90% discount)
  • CacheHitRate() - Percentage of cache hits vs misses
  • CacheSavingsRate() - Percentage of tokens saved
Important Notes
  • Content must be at least 1,024 tokens for Claude 3.5 Sonnet to be cacheable
  • Cache duration is 5 minutes by default (1 hour with beta enabled)
  • Content must be 100% identical for cache hits
  • Cache writes cost 25% more, but cache reads cost 90% less
  • The library enables 1-hour cache beta by default

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var DefaultApiToken = ""

DefaultApiToken is set to the environment variable ANTHROPIC_API_KEY, if it exists. It can be overridden by setting it directly. It is used as the default API token for all conversations.

View Source 
var DefaultSettings = SampleSettings{
	Model:       "claude-sonnet-4-6",
	Version:     "2023-06-01",
	Beta:        "",
	MaxTokens:   20000,
	Temperature: 0.0,
}

DefaultSettings is the default settings for the Conversation. It is used as the default settings for all Conversations, and can be overridden by setting it directly.

Functions

This section is empty.

Types

type CacheControl added in v1.0.2 

type CacheControl struct {
	Type string `json:"type"`          // "ephemeral" for caching
	TTL  string `json:"ttl,omitempty"` // "5m" or "1h" (requires beta)
}

CacheControl specifies caching behavior for content blocks

type ContentBlock 

type ContentBlock struct {
	ContentType  string           `json:"type"`
	Text         *string          `json:"text,omitempty"`
	Thinking     *string          `json:"thinking,omitempty"`  // For thinking content blocks
	Signature    *string          `json:"signature,omitempty"` // For thinking block verification
	Source       *ContentSource   `json:"source,omitempty"`
	ID           *string          `json:"id,omitempty"`
	Name         *string          `json:"name,omitempty"`
	Input        *json.RawMessage `json:"input,omitempty"`
	ToolUseID    *string          `json:"tool_use_id,omitempty"`
	Content      *string          `json:"content,omitempty"`
	CacheControl *CacheControl    `json:"cache_control,omitempty"`
	// contains filtered or unexported fields
}

ContentBlock is a single block of content in a message.

func (*ContentBlock) DisableCaching added in v1.0.2 

func (cb *ContentBlock) DisableCaching()

DisableCaching removes cache control from a content block

func (*ContentBlock) EnableCaching added in v1.0.2 

func (cb *ContentBlock) EnableCaching()

EnableCaching adds cache control to a content block (5-minute TTL by default)

func (*ContentBlock) EnableLongCaching added in v1.0.2 

func (cb *ContentBlock) EnableLongCaching()

EnableLongCaching adds cache control with 1-hour TTL (requires beta)

type ContentSource 

type ContentSource struct {
	// Encoding type
	// Possible values are:
	//    base64: The content is base64 encoded.
	Encoding string `json:"type"`
	// MediaType type
	// Possible values are:
	//    image/png: The content is a PNG image.
	//    image/jpeg: The content is a JPEG image.
	//    image/gif: The content is a GIF image.
	//    image/webp: The content is a WebP image.
	MediaType string `json:"media_type"`
	// Data is the base64 encoded image data.
	Data string `json:"data"`
}

ContentSource is the encoded data for the content block. It is presently used for images only.

type Conversation 

type Conversation struct {
	// Ctx is the context for cancellation and timeouts.
	// If nil, context.Background() is used.
	Ctx context.Context
	// System is the system prompt to use for the conversation.
	System *string
	// SystemCacheable indicates if the system prompt should be cached
	SystemCacheable bool
	// Messages is the sequence of messages in the conversation. This always
	// starts with a user message, and alternates between user and assistant.
	Messages *[]*Message
	// Usage is the usage statistics for the conversation in total.
	Usage struct {
		InputTokens  int `json:"input_tokens"`
		OutputTokens int `json:"output_tokens"`
	}
	// CacheStats tracks cache usage statistics
	CacheStats struct {
		TotalCacheCreationTokens int
		TotalCacheReadTokens     int
		TotalTokensSaved         int
		CacheHits                int
		CacheMisses              int
	}
	// HttpClient is the HTTP client used for API requests
	HttpClient *http.Client
	// apiToken is the API token used for API requests
	ApiToken string `json:"-"`
	// Endpoint overrides the API endpoint URL for this conversation.
	// If empty, the default messagesURI is used.
	Endpoint string
	// Settings is the settings for the conversation.
	Settings *SampleSettings
	// Tools are optional tool definitions for the conversation
	Tools []ToolDefinition
	// ToolsCacheable indicates if tools should be cached
	ToolsCacheable bool
	// ConversationCacheable enables automatic cache breakpoints on conversation turns.
	// When enabled, the last user message's last content block is marked with
	// cache_control before each API call, so the conversation prefix is cached.
	ConversationCacheable bool
	// HasThinkingContent tracks if any responses included thinking blocks
	HasThinkingContent bool
}

A Conversation is a sequence of messages between a user and an assistant.

func NewConversation 

func NewConversation(system string) *Conversation

NewConversation creates a new conversation with the given system prompt. It initializes the messages and usage statistics, as well as reasonable defaults.

func (*Conversation) AddMessage 

func (conversation *Conversation) AddMessage(role llmapi.Role, content string)

AddMessage adds a message to the conversation with the given role and content. It is used internally and can also be used externally to manipulate conversations.

func (*Conversation) AddRichMessage added in v1.0.2 

func (c *Conversation) AddRichMessage(role llmapi.Role, content []llmapi.ContentBlock)

AddRichMessage adds a message with multiple content blocks.

func (*Conversation) CacheHitRate added in v1.0.2 

func (c *Conversation) CacheHitRate() float64

CacheHitRate returns the cache hit rate as a percentage

func (*Conversation) CacheLastNMessages added in v1.0.2 

func (c *Conversation) CacheLastNMessages(n int)

CacheLastNMessages enables caching on the last N messages This is useful for caching accumulated tool results

func (*Conversation) CacheSavingsRate added in v1.0.2 

func (c *Conversation) CacheSavingsRate() float64

CacheSavingsRate returns the percentage of input tokens saved by caching. This is calculated as tokens saved divided by the total tokens that would have been charged without caching (input tokens + cache read tokens).

func (*Conversation) Clear added in v1.0.2 

func (conversation *Conversation) Clear()

Clear resets the conversation history and usage statistics. The system prompt and settings are preserved.

func (*Conversation) DisableBeta added in v1.0.2 

func (c *Conversation) DisableBeta(beta string)

DisableBeta removes a beta feature from the conversation settings

func (*Conversation) DisableConversationCaching added in v1.0.2 

func (c *Conversation) DisableConversationCaching() error

DisableConversationCaching disables automatic conversation turn caching.

func (*Conversation) EnableBeta added in v1.0.2 

func (c *Conversation) EnableBeta(beta string)

EnableBeta adds a beta feature to the conversation settings

func (*Conversation) EnableConversationCaching added in v1.0.2 

func (c *Conversation) EnableConversationCaching() error

EnableConversationCaching enables automatic cache breakpoints on conversation turns. Before each API call, the last user message's last content block is marked with cache_control so that the conversation prefix is served from cache on subsequent turns.

func (*Conversation) EnableSystemCaching added in v1.0.2 

func (c *Conversation) EnableSystemCaching() error

EnableSystemCaching enables caching for the system prompt.

func (*Conversation) EnableThinking added in v1.0.2 

func (c *Conversation) EnableThinking(budgetTokens int)

EnableThinking enables extended thinking with the specified token budget

func (*Conversation) EnableToolsCaching added in v1.0.2 

func (c *Conversation) EnableToolsCaching()

EnableToolsCaching enables caching for tool definitions

func (*Conversation) GetCapabilities added in v1.0.2 

func (c *Conversation) GetCapabilities() llmapi.Capabilities

GetCapabilities returns Anthropic's supported features.

func (*Conversation) GetMessages added in v1.0.2 

func (conversation *Conversation) GetMessages() []llmapi.Message

GetMessages returns the conversation history as llmapi.Message slices. This converts from the internal ContentBlock-based format to simple role/content strings for interface compliance.

Note: Only the first text content block from each message is extracted. Tool use, images, and other content types are not included in the output.

func (*Conversation) GetRichMessages added in v1.0.2 

func (c *Conversation) GetRichMessages() []llmapi.RichMessage

GetRichMessages returns the full conversation with content blocks.

func (*Conversation) GetSystem added in v1.0.2 

func (conversation *Conversation) GetSystem() string

GetSystem returns the system prompt for this conversation.

func (*Conversation) GetTools added in v1.0.2 

func (c *Conversation) GetTools() []llmapi.ToolDefinition

GetTools returns currently configured tools.

func (*Conversation) GetUsage added in v1.0.2 

func (conversation *Conversation) GetUsage() llmapi.Usage

GetUsage returns the cumulative token usage for this conversation. This includes all input and output tokens across all Send calls.

func (*Conversation) MergeIfLastTwoAssistant 

func (conversation *Conversation) MergeIfLastTwoAssistant()

MergeIfLastTwoAssistant merges the last two assistant messages if they are both from the assistant. This is useful for combining messages that are split and continued due to token limits.

This is used on Conversation on all API returns, as it is a no-op if there are less than two messages, or if the last two messages are not both from the assistant.

func (*Conversation) REPL 

func (conversation *Conversation) REPL()

REPL is a Read-Eval-Print Loop for a conversation. It reads input from stdin, sends it to the assistant, and prints the assistant's response. It also prints the total tokens used for the conversation, and the tokens used for the last message.

It is intended as a simple way to interact with the assistant via a console.

func (*Conversation) Send 

func (conversation *Conversation) Send(text string, sampling llmapi.Sampling) (reply, stopReason string, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens int, err error)

Send sends a message to the assistant and returns the reply. It also returns the reason the conversation stopped, the number of input tokens used, and the number of output tokens used.

If the text is empty, it sends the message as is, and does not add a user message to the conversation. This is useful for continuing an incomplete conversation by "assistant", in the case of a stopReason of "max_tokens".

func (*Conversation) SendRich added in v1.0.2 

func (c *Conversation) SendRich(content []llmapi.ContentBlock, sampling llmapi.Sampling) (*llmapi.RichResponse, error)

SendRich sends a message with rich content blocks.

func (*Conversation) SendRichStreaming added in v1.0.2 

func (c *Conversation) SendRichStreaming(content []llmapi.ContentBlock, sampling llmapi.Sampling, callback llmapi.StreamCallback) (*llmapi.RichResponse, error)

SendRichStreaming sends rich content with streaming.

func (*Conversation) SendStreaming added in v1.0.2 

func (conversation *Conversation) SendStreaming(text string, sampling llmapi.Sampling, callback llmapi.StreamCallback) (reply, stopReason string, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens int, err error)

SendStreaming sends a message with real-time token streaming via SSE. The callback is invoked for each text fragment received from the API.

Parameters:

  • text: The user message to send. If empty, continues from the last message.
  • sampling: Sampling parameters to override conversation defaults (Temperature, TopP, TopK).
  • callback: Called with each text fragment; called with ("", true) when done.

Returns the same values as Send, but tokens are streamed via callback as they arrive.

func (*Conversation) SendStreamingUntilDone added in v1.0.2 

func (conversation *Conversation) SendStreamingUntilDone(text string, sampling llmapi.Sampling, callback llmapi.StreamCallback) (reply, stopReason string, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens int, err error)

SendStreamingUntilDone combines streaming with automatic continuation. It calls SendStreaming repeatedly until stopReason != "max_tokens", streaming tokens via callback throughout the entire generation.

This is useful for long responses that exceed max_tokens - the callback receives a continuous stream of tokens across all continuation requests, while the returned reply contains the complete accumulated response.

Consecutive assistant messages are automatically merged in the conversation history to maintain a clean message structure.

func (*Conversation) SendUntilDone 

func (conversation *Conversation) SendUntilDone(text string, sampling llmapi.Sampling) (reply, stopReason string, inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens int, err error)

func (*Conversation) SetContext added in v1.0.2 

func (conversation *Conversation) SetContext(ctx context.Context)

SetContext sets the context for cancellation and timeouts. The context applies to all subsequent API calls until changed. Pass nil to clear the context (will use context.Background()).

func (*Conversation) SetEndpoint added in v1.0.2 

func (c *Conversation) SetEndpoint(endpoint string)

SetEndpoint overrides the API endpoint URL for this conversation. Pass empty string to revert to the default messagesURI.

func (*Conversation) SetModel added in v1.0.2 

func (conversation *Conversation) SetModel(model string)

SetModel changes the model for subsequent API calls. If settings haven't been initialized, they are created from DefaultSettings.

func (*Conversation) SetTools added in v1.0.2 

func (c *Conversation) SetTools(tools []llmapi.ToolDefinition)

SetTools sets the tools for the conversation.

type Message 

type Message struct {
	// Role of the message sender.
	// Possible values are:
	//   "user": The message is from the user.
	//   "assistant": The message is from the assistant.
	Role string `json:"role"`
	// Content is the content of the message, and may be a single string or
	// image, or an array of content blocks.
	Content *[]ContentBlock `json:"content"`
}

Message is a single message in a conversation.

type Messages 

type Messages struct {
	Model     string `json:"model"`
	MaxTokens int    `json:"max_tokens"`
	// Temperature is a pointer so the field can be omitted entirely from the
	// JSON body — Claude Opus 4.7 and later reject any temperature key (the
	// check is presence-based, not value-based). See supportsSampling.
	Temperature *float64         `json:"temperature,omitempty"`
	TopP        float64          `json:"top_p,omitempty"`
	TopK        int              `json:"top_k,omitempty"`
	System      interface{}      `json:"system,omitempty"` // Can be string or []SystemPrompt
	Messages    *[]*Message      `json:"messages"`
	Tools       []ToolDefinition `json:"tools,omitempty"`
	Thinking    *ThinkingConfig  `json:"thinking,omitempty"`
	Stream      bool             `json:"stream,omitempty"`
}

Messages is a sequence of messages in a conversation. It usually starts with a user message, and alternates between user and assistant messages.

type Model added in v1.0.2 

type Model struct {
	Type        string    `json:"type"`
	ID          string    `json:"id"`
	DisplayName string    `json:"display_name"`
	CreatedAt   time.Time `json:"created_at"`
}

Model represents an available Claude model

type ModelsResponse added in v1.0.2 

type ModelsResponse struct {
	Data    []Model `json:"data"`
	FirstID string  `json:"first_id"`
	LastID  string  `json:"last_id"`
	HasMore bool    `json:"has_more"`
}

ModelsResponse represents the response from the models list API

func ListModels added in v1.0.2 

func ListModels(ctx context.Context, apiKey string) (*ModelsResponse, error)

ListModels retrieves the list of available models. If ctx is nil, context.Background() is used.

type Response 

type Response struct {
	// id: The ID of the response.
	ID string `json:"id"`
	// MessageType is the type of the message.
	MessageType string `json:"type"`
	// Role of the message sender. This is usually almost always "assistant".
	Role string `json:"role"`
	// Model is the model used for the response.
	Model string `json:"model"`
	// Content is the content of the response. This usually only has one
	// content block.
	Content *[]ContentBlock `json:"content"`
	// StopReason is the reason the response was stopped. They can be:
	//   "end_turn": The response reached the end of the turn.
	//   "max_tokens": The response reached the maximum token limit.
	//   "stop_sequence": The response reached a stop sequence.
	//   "tools_use": The model invoked one or more tools.
	StopReason string `json:"stop_reason"`
	// StopSequence is the stop sequence that caused the response to stop,
	// in the case of a StopReason of "stop_sequence"
	StopSequence *string `json:"stop_sequence"`
	// Usage is the usage statistics for the response.
	Usage struct {
		InputTokens              int `json:"input_tokens"`
		OutputTokens             int `json:"output_tokens"`
		CacheCreationInputTokens int `json:"cache_creation_input_tokens,omitempty"`
		CacheReadInputTokens     int `json:"cache_read_input_tokens,omitempty"`
	} `json:"usage"`
}

Response is the response from the Anthropic API for a message.

type SampleSettings 

type SampleSettings struct {
	// Model to use for the sample.
	Model string `json:"model"`
	// Version of the model to use for the sample.
	Version string `json:"version"`
	// Beta is the beta version of the model to use for the sample.
	Beta string `json:"beta"`
	// MaxTokens is the max number of tokens to generate.
	MaxTokens int `json:"max_tokens"`
	// Temperature to use for sampling (0.0-1.0).
	Temperature float64 `json:"temperature"`
	// TopP for nucleus sampling (0.0-1.0). Use either Temperature or TopP, not both.
	TopP float64 `json:"top_p,omitempty"`
	// TopK limits sampling to the top K tokens.
	TopK int `json:"top_k,omitempty"`
	// Thinking configuration for extended reasoning
	Thinking *ThinkingConfig `json:"thinking,omitempty"`
}

SampleSettings is used to set the settings for the request. Usually it pertains to samplers.

type StreamDelta added in v1.0.2 

type StreamDelta struct {
	Type        string  `json:"type,omitempty"`
	Text        string  `json:"text,omitempty"`
	Thinking    string  `json:"thinking,omitempty"`
	PartialJSON string  `json:"partial_json,omitempty"`
	StopReason  *string `json:"stop_reason,omitempty"`
}

StreamDelta contains incremental content updates from streaming responses. For content_block_delta events, Text contains the new text fragment. For message_delta events, StopReason contains the final stop reason.

type StreamEvent added in v1.0.2 

type StreamEvent struct {
	Type    string        `json:"type"`
	Message *Response     `json:"message,omitempty"`       // Populated in message_start
	Index   int           `json:"index,omitempty"`         // Content block index
	Delta   *StreamDelta  `json:"delta,omitempty"`         // Populated in content_block_delta and message_delta
	Usage   *StreamUsage  `json:"usage,omitempty"`         // Populated in message_delta
	Content *ContentBlock `json:"content_block,omitempty"` // Populated in content_block_start
}

StreamEvent represents an SSE event from the Anthropic streaming API. The Type field corresponds to the SSE event name, and other fields are populated based on the event type.

type StreamUsage added in v1.0.2 

type StreamUsage struct {
	InputTokens  int `json:"input_tokens,omitempty"`
	OutputTokens int `json:"output_tokens,omitempty"`
}

StreamUsage contains token usage information from streaming responses. This is sent in the message_delta event at the end of the stream.

type SystemPrompt added in v1.0.2 

type SystemPrompt struct {
	Type         string        `json:"type"`
	Text         string        `json:"text"`
	CacheControl *CacheControl `json:"cache_control,omitempty"`
}

SystemPrompt represents a system prompt with optional cache control

type ThinkingConfig added in v1.0.2 

type ThinkingConfig struct {
	Type         string `json:"type"`          // "enabled"
	BudgetTokens int    `json:"budget_tokens"` // minimum 1024
}

ThinkingConfig configures extended thinking for Claude

type ToolDefinition added in v1.0.2 

type ToolDefinition struct {
	Name         string          `json:"name"`
	Description  string          `json:"description"`
	InputSchema  json.RawMessage `json:"input_schema"`
	CacheControl *CacheControl   `json:"cache_control,omitempty"`
}

ToolDefinition represents a tool that can be used by Claude

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.