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) 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

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

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
)