Iris Core Package

core

Entry points

client := core.NewClient(provider,
    core.WithTelemetry(hook),
    core.WithRetryPolicy(core.DefaultRetryPolicy()),
    core.WithWarningHandler(handler),
)

Key types

Type	Purpose
Client	Provider wrapper that exposes Chat() and common workflows. Thread-safe.
ChatBuilder	Fluent builder for chat requests. NOT thread-safe—use Clone().
MessageBuilder	Build multimodal messages with text, images, and files.
ChatStream	Streaming response channels (Ch, Err, Final).
ChatRequest / ChatResponse	Canonical request and response structures.
Tool / ToolCall / ToolResult	Tool definitions, model call payloads, and results.
Memory / InMemoryStore	Conversation memory interface and implementation.
Conversation	High-level multi-turn conversation API.
Secret	Wrap sensitive strings with automatic redaction.
RetryPolicy / RetryConfig	Retry policy configuration.
TelemetryHook	Request lifecycle events.

Provider Interface

type Provider interface {
    ID() string                                          // Provider identifier
    Models() []ModelInfo                                 // Available models
    Supports(feature Feature) bool                       // Feature capability check
    Chat(ctx context.Context, req *ChatRequest) (*ChatResponse, error)
    StreamChat(ctx context.Context, req *ChatRequest) (*ChatStream, error)
}

Feature Constants

const (
    FeatureChat                    Feature = "chat"
    FeatureChatStreaming           Feature = "chat_streaming"
    FeatureToolCalling             Feature = "tool_calling"
    FeatureReasoning               Feature = "reasoning"
    FeatureBuiltInTools            Feature = "built_in_tools"
    FeatureEmbeddings              Feature = "embeddings"
    FeatureContextualizedEmbeddings Feature = "contextualized_embeddings"
    FeatureReranking               Feature = "reranking"
)

Core functions

func NewClient(p Provider, opts ...ClientOption) *Client
func WithTelemetry(h TelemetryHook) ClientOption
func WithRetryPolicy(r RetryPolicy) ClientOption
func WithWarningHandler(h WarningHandler) ClientOption
func DefaultRetryPolicy() RetryPolicy
func NewRetryPolicy(cfg RetryConfig) RetryPolicy
func DrainStream(ctx context.Context, s *ChatStream) (*ChatResponse, error)
func NewSecret(value string) Secret
func NewInMemoryStore() *InMemoryStore
func NewConversation(client *Client, model string, opts ...ConversationOption) *Conversation

ChatBuilder (selected)

func (c *Client) Chat(model string) *ChatBuilder
func (b *ChatBuilder) System(text string) *ChatBuilder
func (b *ChatBuilder) User(text string) *ChatBuilder
func (b *ChatBuilder) Assistant(text string) *ChatBuilder
func (b *ChatBuilder) Tools(tools ...Tool) *ChatBuilder
func (b *ChatBuilder) ToolResults(results ...ToolResult) *ChatBuilder
func (b *ChatBuilder) Temperature(v float64) *ChatBuilder
func (b *ChatBuilder) MaxTokens(v int) *ChatBuilder
func (b *ChatBuilder) Instructions(text string) *ChatBuilder
func (b *ChatBuilder) ReasoningEffort(effort ReasoningEffort) *ChatBuilder
func (b *ChatBuilder) WebSearch() *ChatBuilder
func (b *ChatBuilder) FileSearch() *ChatBuilder
func (b *ChatBuilder) CodeInterpreter() *ChatBuilder
func (b *ChatBuilder) ResponseJSON() *ChatBuilder
func (b *ChatBuilder) ResponseJSONSchema(schema *JSONSchemaDefinition) *ChatBuilder
func (b *ChatBuilder) Timeout(d time.Duration) *ChatBuilder
func (b *ChatBuilder) Stream(ctx context.Context) (*ChatStream, error)
func (b *ChatBuilder) GetResponse(ctx context.Context) (*ChatResponse, error)
func (b *ChatBuilder) Clone() *ChatBuilder

Structured Output

type JSONSchemaDefinition struct {
    Name        string          // Schema name for caching
    Description string          // Optional description
    Strict      bool            // Enable strict validation
    Schema      json.RawMessage // JSON Schema definition
}

MessageBuilder (selected)

func (b *ChatBuilder) UserMultimodal() *MessageBuilder
func (m *MessageBuilder) Text(text string) *MessageBuilder
func (m *MessageBuilder) ImageURL(url string) *MessageBuilder
func (m *MessageBuilder) ImageURLWithDetail(url string, detail string) *MessageBuilder
func (m *MessageBuilder) ImageFileID(fileID string) *MessageBuilder
func (m *MessageBuilder) FileURL(url string) *MessageBuilder
func (m *MessageBuilder) FileID(fileID string) *MessageBuilder
func (m *MessageBuilder) FileBase64(data, mimeType string) *MessageBuilder
func (m *MessageBuilder) Done() *ChatBuilder

Memory Interface

type Memory interface {
    AddMessage(msg Message)
    AddMessages(msgs []Message)
    GetHistory() []Message
    GetLastN(n int) []Message
    Clear()
    Len() int
    SetMessages(msgs []Message)
}

ToolCall and ToolResult

type ToolCall struct {
    ID        string          // Unique call identifier
    Name      string          // Tool name
    Arguments json.RawMessage // JSON-encoded arguments
}

type ToolResult struct {
    CallID  string // Corresponds to ToolCall.ID
    Content any    // Result content
    IsError bool   // True if this is an error result
}

Secret Type

type Secret struct { value string }

func NewSecret(value string) Secret
func (s Secret) String() string    // Returns "[REDACTED]"
func (s Secret) Expose() string    // Returns actual value
func (s Secret) IsEmpty() bool

Batch API

// Check if provider supports batch operations
func AsBatchProvider(p Provider) (BatchProvider, bool)

type BatchProvider interface {
    CreateBatch(ctx context.Context, requests []BatchRequest) (string, error)
    GetBatchStatus(ctx context.Context, batchID string) (*BatchInfo, error)
    GetBatchResults(ctx context.Context, batchID string) ([]BatchResult, error)
    CancelBatch(ctx context.Context, batchID string) error
    ListBatches(ctx context.Context, limit int) ([]BatchInfo, error)
}

type BatchRequest struct {
    CustomID string       // Your identifier for the request
    Request  ChatRequest  // The chat request
}

type BatchInfo struct {
    ID        string      // Batch identifier
    Status    BatchStatus // Current status
    Total     int         // Total requests
    Completed int         // Completed requests
    Failed    int         // Failed requests
    Error     string      // Error message if failed
}

type BatchResult struct {
    CustomID string        // Your identifier
    Response *ChatResponse // Response (if successful)
    Error    *BatchError   // Error (if failed)
}

func (r *BatchResult) IsSuccess() bool

type BatchStatus string
const (
    BatchStatusPending    BatchStatus = "pending"
    BatchStatusInProgress BatchStatus = "in_progress"
    BatchStatusCompleted  BatchStatus = "completed"
    BatchStatusFailed     BatchStatus = "failed"
    BatchStatusCancelled  BatchStatus = "cancelled"
    BatchStatusExpired    BatchStatus = "expired"
)

func (i *BatchInfo) IsComplete() bool

// BatchWaiter polls for batch completion
func NewBatchWaiter(bp BatchProvider) *BatchWaiter
func (w *BatchWaiter) WithPollInterval(d time.Duration) *BatchWaiter
func (w *BatchWaiter) WithMaxWait(d time.Duration) *BatchWaiter
func (w *BatchWaiter) Wait(ctx context.Context, batchID string) (*BatchInfo, error)
func (w *BatchWaiter) WaitAndCollect(ctx context.Context, batchID string) ([]BatchResult, error)

Conversation

func NewConversation(client *Client, model string, opts ...ConversationOption) *Conversation

type ConversationOption func(*Conversation)
func WithSystemMessage(msg string) ConversationOption

func (c *Conversation) Send(content string) (*ChatResponse, error)
func (c *Conversation) Stream(content string) (*ChatStream, error)
func (c *Conversation) MessageCount() int
func (c *Conversation) GetHistory() []Message
func (c *Conversation) Clear()

Sentinel Errors

var (
    ErrUnauthorized  // Authentication failed
    ErrRateLimited   // Rate limit exceeded
    ErrBadRequest    // Malformed request
    ErrNotFound      // Resource not found
    ErrServer        // Provider server error
    ErrNetwork       // Network connectivity error
    ErrDecode        // Response decoding error
    ErrNotSupported  // Feature not supported
    ErrModelRequired // Model parameter required
    ErrNoMessages    // No messages in request
)

---

testing

The testing package provides utilities for deterministic testing of LLM code.

MockProvider

func NewMockProvider() *MockProvider
func (m *MockProvider) WithResponse(resp ChatResponse) *MockProvider
func (m *MockProvider) WithDefaultResponse(resp ChatResponse) *MockProvider
func (m *MockProvider) WithError(err error) *MockProvider
func (m *MockProvider) WithStreamingResponse(chunks []string, final *ChatResponse) *MockProvider
func (m *MockProvider) Calls() []MockCall

type MockCall struct {
    Method   string       // "Chat" or "StreamChat"
    Request  *ChatRequest // The request made
}

RecordingProvider

func NewRecordingProvider(provider Provider) *RecordingProvider
func (r *RecordingProvider) Recordings() []Recording
func (r *RecordingProvider) Clear()

type Recording struct {
    Method   string         // "Chat" or "StreamChat"
    Request  *ChatRequest   // The request
    Response *ChatResponse  // The response (if successful)
    Error    error          // The error (if failed)
    Duration time.Duration  // How long the call took
}