observability

type CallInfo struct {
	Provider ai.Provider
	ModelID  string
	Request  ai.Request
	// Streaming reports whether the call is Stream (true) or Generate.
	Streaming bool
}

type Hooks struct {
	// OnStart fires before the underlying call. The returned context is used
	// for the call, so a hook may attach a span or values; return ctx
	// unchanged to opt out.
	OnStart func(ctx context.Context, info CallInfo) context.Context
	// OnStreamEvent fires for each streaming event (never for Generate).
	OnStreamEvent func(ctx context.Context, info CallInfo, ev ai.StreamEvent)
	// OnFinish fires after a call completes without error.
	OnFinish func(ctx context.Context, result Result)
	// OnError fires when a call (or stream) fails.
	OnError func(ctx context.Context, info CallInfo, err error)
}

type Result struct {
	CallInfo
	// Response is set for Generate calls; nil for Stream (use OnStreamEvent
	// and the message_end usage for streaming accounting).
	Response *ai.Response
	// Usage is the token usage observed (from the response, or accumulated
	// from stream events).
	Usage ai.Usage
	// FinishReason is the normalized stop reason.
	FinishReason ai.FinishReason
	// Duration is the wall-clock time from call start to completion.
	Duration time.Duration
}