Types Reference

Chat

The conversation lifecycle controller.

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

Chat manages conversation state, delegates to a processor for reasoning, and streams output through an emitter. It handles turn-taking via continuations.

Methods:

• Handle(ctx, input) — process user input
• ID() — unique identifier
• Session() — conversation history
• Config() — configuration
• HasContinuation() — check if awaiting input

See: API Reference

Config

Configuration for a Chat.

type Config struct {
    SystemPrompt string
    Metadata     map[string]any
}

Processor

Interface for reasoning and execution logic.

type Processor interface {
    Process(ctx context.Context, input string, session *zyn.Session) (Result, error)
}

Implement this interface to define how your chat handles user input. The processor receives the input and conversation history, and returns a Result.

The context contains the Emitter (retrievable via EmitterFromContext) for pushing resources during processing.

ProcessorFunc

Adapter to use a function as a Processor.

type ProcessorFunc func(ctx context.Context, input string, session *zyn.Session) (Result, error)

processor := chit.ProcessorFunc(func(ctx context.Context, input string, session *zyn.Session) (chit.Result, error) {
    return &chit.Response{Content: "Hello"}, nil
})

Result

Interface for processing outcomes.

type Result interface {
    IsComplete() bool
    IsYielded() bool
}

Two concrete implementations exist: *Response and *Yield.

Response

A complete result with content to emit.

type Response struct {
    Content  string
    Metadata map[string]any
}

return &chit.Response{
    Content:  "Here's your answer.",
    Metadata: map[string]any{"tokens": 150},
}, nil

Yield

Indicates processing paused awaiting further input.

type Yield struct {
    Prompt       string
    Continuation Continuation
    Metadata     map[string]any
}

return &chit.Yield{
    Prompt: "What's your email?",
    Continuation: func(ctx context.Context, email string) (chit.Result, error) {
        return &chit.Response{Content: "Thanks, " + email}, nil
    },
}, nil

Continuation

Function that resumes processing with new input.

type Continuation func(ctx context.Context, input string) (Result, error)

Continuations can return either *Response (to complete) or *Yield (to chain another continuation).

Emitter

Interface for streaming output to the client.

type Emitter interface {
    Emit(ctx context.Context, msg Message) error
    Push(ctx context.Context, resource Resource) error
    Close() error
}

Message

A streamed response unit.

type Message struct {
    Role     string
    Content  string
    Metadata map[string]any
}

Resource

Structured data pushed to the client.

type Resource struct {
    Type     string
    URI      string
    Payload  any
    Metadata map[string]any
}

emitter.Push(ctx, chit.Resource{
    Type:    "data",
    URI:     "db://users/123",
    Payload: map[string]string{"name": "Alice"},
})

Option

Functional option for configuring a Chat.

type Option func(*Chat)

See API Reference for available options.

ChatRequest

The request object that flows through the pipz pipeline.

type ChatRequest struct {
    Input     string
    Session   *zyn.Session
    ChatID    string
    RequestID string
    Result    Result
}

Implements pipz.Cloner for concurrent middleware support.

ChatProvider

Interface for types that can provide a pipeline for composition.

type ChatProvider interface {
    GetPipeline() pipz.Chainable[*ChatRequest]
}

Used by WithFallback to compose fallback pipelines. Chat implements this interface.

PipelineOption

Function that wraps a pipeline with additional behavior.

type PipelineOption func(pipz.Chainable[*ChatRequest]) pipz.Chainable[*ChatRequest]

Used internally. See API Reference for the Option-returning wrappers.

Terminal Functions

Internal functions that create the innermost pipeline layer.

NewTerminal

func NewTerminal(processor Processor) pipz.Chainable[*ChatRequest]

Creates the terminal that calls the Processor. Used for fresh input processing.

NewContinuationTerminal

func NewContinuationTerminal(cont Continuation) pipz.Chainable[*ChatRequest]

Creates a terminal that calls the given continuation. Used when resuming yielded processing.

Both terminals:

• Receive a *ChatRequest with input and session
• Call their target (processor or continuation) with the input
• Store the result in req.Result
• Are wrapped with the same pipeline options for reliability parity

MetricsRecorder

Interface for recording chat metrics.

type MetricsRecorder interface {
    RecordRequest(chatID string, inputLength int)
    RecordLatency(chatID string, duration time.Duration)
}

Used by UseMetrics middleware.

Enricher

Interface for enriching chat requests.

type Enricher interface {
    Enrich(ctx context.Context, req *ChatRequest) error
}

Used by UseEnrich middleware.

Errors

Sentinel errors for chit operations.

var (
    ErrUnknownResultType = errors.New("chit: unknown result type")
    ErrNilProcessor      = errors.New("chit: processor is required")
    ErrNilEmitter        = errors.New("chit: emitter is required")
    ErrEmitterClosed     = errors.New("chit: emitter is closed")
)

Signals

Lifecycle signals emitted via capitan.

var (
    ChatCreated         = capitan.NewSignal("chit.chat.created", ...)
    InputReceived       = capitan.NewSignal("chit.input.received", ...)
    ProcessingStarted   = capitan.NewSignal("chit.processing.started", ...)
    ProcessingCompleted = capitan.NewSignal("chit.processing.completed", ...)
    ProcessingFailed    = capitan.NewSignal("chit.processing.failed", ...)
    ResponseEmitted     = capitan.NewSignal("chit.response.emitted", ...)
    ResourcePushed      = capitan.NewSignal("chit.resource.pushed", ...)
    TurnYielded         = capitan.NewSignal("chit.turn.yielded", ...)
    TurnResumed         = capitan.NewSignal("chit.turn.resumed", ...)
)

Signal Fields

Field keys for signal event data.

var (
    FieldChatID             = capitan.NewStringKey("chat_id")
    FieldInput              = capitan.NewStringKey("input")
    FieldInputSize          = capitan.NewIntKey("input_size")
    FieldProcessingDuration = capitan.NewDurationKey("processing_duration")
    FieldRole               = capitan.NewStringKey("role")
    FieldContentSize        = capitan.NewIntKey("content_size")
    FieldResourceType       = capitan.NewStringKey("resource_type")
    FieldResourceURI        = capitan.NewStringKey("resource_uri")
    FieldPrompt             = capitan.NewStringKey("prompt")
    FieldError              = capitan.NewErrorKey("error")
)

Test Helpers

The github.com/zoobz-io/chit/testing package provides test utilities.

MockProcessor

type MockProcessor struct {
    ProcessFunc func(ctx context.Context, input string, session *zyn.Session) (chit.Result, error)
    Calls       []ProcessCall
}

type ProcessCall struct {
    Input   string
    Session *zyn.Session
}

MockEmitter

type MockEmitter struct {
    EmitFunc  func(ctx context.Context, msg chit.Message) error
    PushFunc  func(ctx context.Context, resource chit.Resource) error
    CloseFunc func() error
    Messages  []chit.Message
    Resources []chit.Resource
    Closed    bool
}

CollectingEmitter

type CollectingEmitter struct {
    Messages  []chit.Message
    Resources []chit.Resource
}

func (e *CollectingEmitter) Content() string

Factory Functions

func EchoProcessor() chit.Processor
func YieldingProcessor(prompt, finalResponse string) chit.Processor

See: Testing Guide

Next Steps

• API Reference — function documentation
• Concepts — mental models
• Architecture — internal design