events

package
v1.1.4 Latest Latest
Warning

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

Go to latest
Published: Dec 5, 2025 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Overview

Package events provides a lightweight pub/sub event bus for runtime observability.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ContextBuiltData

type ContextBuiltData struct {
	MessageCount int
	TokenCount   int
	TokenBudget  int
	Truncated    bool
	// contains filtered or unexported fields
}

ContextBuiltData contains data for context building events.

type CustomEventData

type CustomEventData struct {
	MiddlewareName string
	EventName      string
	Data           map[string]interface{}
	Message        string
	// contains filtered or unexported fields
}

CustomEventData allows middleware to emit arbitrary structured events.

type Emitter

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

Emitter provides helpers for publishing runtime events with shared metadata.

func NewEmitter

func NewEmitter(bus *EventBus, runID, sessionID, conversationID string) *Emitter

NewEmitter creates a new event emitter.

func (*Emitter) ContextBuilt

func (e *Emitter) ContextBuilt(messageCount, tokenCount, tokenBudget int, truncated bool)

ContextBuilt emits the context.built event.

func (*Emitter) EmitCustom

func (e *Emitter) EmitCustom(
	eventType EventType,
	middlewareName, eventName string,
	data map[string]interface{},
	message string,
)

EmitCustom allows middleware to emit arbitrary event types with structured payloads.

func (*Emitter) MiddlewareCompleted

func (e *Emitter) MiddlewareCompleted(name string, index int, duration time.Duration)

MiddlewareCompleted emits the middleware.completed event.

func (*Emitter) MiddlewareFailed

func (e *Emitter) MiddlewareFailed(name string, index int, err error, duration time.Duration)

MiddlewareFailed emits the middleware.failed event.

func (*Emitter) MiddlewareStarted

func (e *Emitter) MiddlewareStarted(name string, index int)

MiddlewareStarted emits the middleware.started event.

func (*Emitter) PipelineCompleted

func (e *Emitter) PipelineCompleted(
	duration time.Duration,
	totalCost float64,
	inputTokens, outputTokens, messageCount int,
)

PipelineCompleted emits the pipeline.completed event.

func (*Emitter) PipelineFailed

func (e *Emitter) PipelineFailed(err error, duration time.Duration)

PipelineFailed emits the pipeline.failed event.

func (*Emitter) PipelineStarted

func (e *Emitter) PipelineStarted(middlewareCount int)

PipelineStarted emits the pipeline.started event.

func (*Emitter) ProviderCallCompleted

func (e *Emitter) ProviderCallCompleted(data *ProviderCallCompletedData)

ProviderCallCompleted emits the provider.call.completed event.

func (*Emitter) ProviderCallFailed

func (e *Emitter) ProviderCallFailed(provider, model string, err error, duration time.Duration)

ProviderCallFailed emits the provider.call.failed event.

func (*Emitter) ProviderCallStarted

func (e *Emitter) ProviderCallStarted(provider, model string, messageCount, toolCount int)

ProviderCallStarted emits the provider.call.started event.

func (*Emitter) StateLoaded

func (e *Emitter) StateLoaded(conversationID string, messageCount int)

StateLoaded emits the state.loaded event.

func (*Emitter) StateSaved

func (e *Emitter) StateSaved(conversationID string, messageCount int)

StateSaved emits the state.saved event.

func (*Emitter) StreamInterrupted

func (e *Emitter) StreamInterrupted(reason string)

StreamInterrupted emits the stream.interrupted event.

func (*Emitter) TokenBudgetExceeded

func (e *Emitter) TokenBudgetExceeded(required, budget, excess int)

TokenBudgetExceeded emits the context.token_budget_exceeded event.

func (*Emitter) ToolCallCompleted

func (e *Emitter) ToolCallCompleted(toolName, callID string, duration time.Duration, status string)

ToolCallCompleted emits the tool.call.completed event.

func (*Emitter) ToolCallFailed

func (e *Emitter) ToolCallFailed(toolName, callID string, err error, duration time.Duration)

ToolCallFailed emits the tool.call.failed event.

func (*Emitter) ToolCallStarted

func (e *Emitter) ToolCallStarted(toolName, callID string, args map[string]interface{})

ToolCallStarted emits the tool.call.started event.

func (*Emitter) ValidationFailed

func (e *Emitter) ValidationFailed(
	validatorName, validatorType string,
	err error,
	duration time.Duration,
	violations []string,
)

ValidationFailed emits the validation.failed event.

func (*Emitter) ValidationPassed

func (e *Emitter) ValidationPassed(validatorName, validatorType string, duration time.Duration)

ValidationPassed emits the validation.passed event.

func (*Emitter) ValidationStarted

func (e *Emitter) ValidationStarted(validatorName, validatorType string)

ValidationStarted emits the validation.started event.

type Event

type Event struct {
	Type           EventType
	Timestamp      time.Time
	RunID          string
	SessionID      string
	ConversationID string
	Data           EventData
}

Event represents a runtime event delivered to listeners.

type EventBus

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

EventBus manages event distribution to listeners.

func NewEventBus

func NewEventBus() *EventBus

NewEventBus creates a new event bus.

func (*EventBus) Clear

func (eb *EventBus) Clear()

Clear removes all listeners (primarily for tests).

func (*EventBus) Publish

func (eb *EventBus) Publish(event *Event)

Publish sends an event to all registered listeners asynchronously.

func (*EventBus) Subscribe

func (eb *EventBus) Subscribe(eventType EventType, listener Listener)

Subscribe registers a listener for a specific event type.

func (*EventBus) SubscribeAll

func (eb *EventBus) SubscribeAll(listener Listener)

SubscribeAll registers a listener for all event types.

type EventData

type EventData interface {
	// contains filtered or unexported methods
}

EventData is a marker interface for event payloads.

type EventType

type EventType string

EventType identifies the type of event emitted by the runtime.

const (
	// EventPipelineStarted marks pipeline start.
	EventPipelineStarted EventType = "pipeline.started"
	// EventPipelineCompleted marks pipeline completion.
	EventPipelineCompleted EventType = "pipeline.completed"
	// EventPipelineFailed marks pipeline failure.
	EventPipelineFailed EventType = "pipeline.failed"

	// EventMiddlewareStarted marks middleware start.
	EventMiddlewareStarted EventType = "middleware.started"
	// EventMiddlewareCompleted marks middleware completion.
	EventMiddlewareCompleted EventType = "middleware.completed"
	// EventMiddlewareFailed marks middleware failure.
	EventMiddlewareFailed EventType = "middleware.failed"

	// EventProviderCallStarted marks provider call start.
	EventProviderCallStarted EventType = "provider.call.started"
	// EventProviderCallCompleted marks provider call completion.
	EventProviderCallCompleted EventType = "provider.call.completed"
	// EventProviderCallFailed marks provider call failure.
	EventProviderCallFailed EventType = "provider.call.failed"

	// EventToolCallStarted marks tool call start.
	EventToolCallStarted EventType = "tool.call.started"
	// EventToolCallCompleted marks tool call completion.
	EventToolCallCompleted EventType = "tool.call.completed"
	// EventToolCallFailed marks tool call failure.
	EventToolCallFailed EventType = "tool.call.failed"

	// EventValidationStarted marks validation start.
	EventValidationStarted EventType = "validation.started"
	// EventValidationPassed marks validation success.
	EventValidationPassed EventType = "validation.passed"
	// EventValidationFailed marks validation failure.
	EventValidationFailed EventType = "validation.failed"

	// EventContextBuilt marks context creation.
	EventContextBuilt EventType = "context.built"
	// EventTokenBudgetExceeded marks token budget overflow.
	EventTokenBudgetExceeded EventType = "context.token_budget_exceeded"
	// EventStateLoaded marks state load.
	EventStateLoaded EventType = "state.loaded"
	// EventStateSaved marks state save.
	EventStateSaved EventType = "state.saved"

	// EventStreamInterrupted marks a stream interruption.
	EventStreamInterrupted EventType = "stream.interrupted"
)

type Listener

type Listener func(*Event)

Listener is a function that handles events.

type MiddlewareCompletedData

type MiddlewareCompletedData struct {
	Name     string
	Index    int
	Duration time.Duration
	// contains filtered or unexported fields
}

MiddlewareCompletedData contains data for middleware completion events.

type MiddlewareFailedData

type MiddlewareFailedData struct {
	Name     string
	Index    int
	Error    error
	Duration time.Duration
	// contains filtered or unexported fields
}

MiddlewareFailedData contains data for middleware failure events.

type MiddlewareStartedData

type MiddlewareStartedData struct {
	Name  string
	Index int
	// contains filtered or unexported fields
}

MiddlewareStartedData contains data for middleware start events.

type PipelineCompletedData

type PipelineCompletedData struct {
	Duration     time.Duration
	TotalCost    float64
	InputTokens  int
	OutputTokens int
	MessageCount int
	// contains filtered or unexported fields
}

PipelineCompletedData contains data for pipeline completion events.

type PipelineFailedData

type PipelineFailedData struct {
	Error    error
	Duration time.Duration
	// contains filtered or unexported fields
}

PipelineFailedData contains data for pipeline failure events.

type PipelineStartedData

type PipelineStartedData struct {
	MiddlewareCount int
	// contains filtered or unexported fields
}

PipelineStartedData contains data for pipeline start events.

type ProviderCallCompletedData

type ProviderCallCompletedData struct {
	Provider      string
	Model         string
	Duration      time.Duration
	InputTokens   int
	OutputTokens  int
	CachedTokens  int
	Cost          float64
	FinishReason  string
	ToolCallCount int
	// contains filtered or unexported fields
}

ProviderCallCompletedData contains data for provider call completion events.

type ProviderCallFailedData

type ProviderCallFailedData struct {
	Provider string
	Model    string
	Error    error
	Duration time.Duration
	// contains filtered or unexported fields
}

ProviderCallFailedData contains data for provider call failure events.

type ProviderCallStartedData

type ProviderCallStartedData struct {
	Provider     string
	Model        string
	MessageCount int
	ToolCount    int
	// contains filtered or unexported fields
}

ProviderCallStartedData contains data for provider call start events.

type StateLoadedData

type StateLoadedData struct {
	ConversationID string
	MessageCount   int
	// contains filtered or unexported fields
}

StateLoadedData contains data for state load events.

type StateSavedData

type StateSavedData struct {
	ConversationID string
	MessageCount   int
	// contains filtered or unexported fields
}

StateSavedData contains data for state save events.

type StreamInterruptedData

type StreamInterruptedData struct {
	Reason string
	// contains filtered or unexported fields
}

StreamInterruptedData contains data for stream interruption events.

type TokenBudgetExceededData

type TokenBudgetExceededData struct {
	RequiredTokens int
	Budget         int
	Excess         int
	// contains filtered or unexported fields
}

TokenBudgetExceededData contains data for token budget exceeded events.

type ToolCallCompletedData

type ToolCallCompletedData struct {
	ToolName string
	CallID   string
	Duration time.Duration
	Status   string // e.g. "success", "error", "pending"
	// contains filtered or unexported fields
}

ToolCallCompletedData contains data for tool call completion events.

type ToolCallFailedData

type ToolCallFailedData struct {
	ToolName string
	CallID   string
	Error    error
	Duration time.Duration
	// contains filtered or unexported fields
}

ToolCallFailedData contains data for tool call failure events.

type ToolCallStartedData

type ToolCallStartedData struct {
	ToolName string
	CallID   string
	Args     map[string]interface{}
	// contains filtered or unexported fields
}

ToolCallStartedData contains data for tool call start events.

type ValidationFailedData

type ValidationFailedData struct {
	ValidatorName string
	ValidatorType string
	Error         error
	Duration      time.Duration
	Violations    []string
	// contains filtered or unexported fields
}

ValidationFailedData contains data for validation failure events.

type ValidationPassedData

type ValidationPassedData struct {
	ValidatorName string
	ValidatorType string
	Duration      time.Duration
	// contains filtered or unexported fields
}

ValidationPassedData contains data for validation success events.

type ValidationStartedData

type ValidationStartedData struct {
	ValidatorName string
	ValidatorType string // e.g. "input", "output", "semantic"
	// contains filtered or unexported fields
}

ValidationStartedData contains data for validation start events.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL