Document invocation observation and cost reporting

This commit is contained in:
2026-11-22 18:38:11 +00:00
parent d4509b163e
commit 20c5ea47af
22 changed files with 231 additions and 52 deletions

View File

@@ -18,8 +18,10 @@ import (
type ExecutionObserver func(ExecutionEvent)
// WithExecutionObserver adds an observer to executions using the returned
// context. Inherited observers run before the newly added observer. A nil
// observer leaves the context unchanged.
// context. Request observers run first, then inherited contextual observers
// in registration order. A nil observer leaves the context unchanged.
// Prepared executions use their execution context, not their preparation
// context. Callers own context propagation and synchronization of observers.
func WithExecutionObserver(ctx context.Context, observer ExecutionObserver) context.Context {
if observer == nil {
return ctx
@@ -102,7 +104,9 @@ type ObservedTokenUsage struct {
}
// CacheHitRatio returns the fraction of input tokens served from cache when
// both counts are known, complete, and consistent. Cache writes are independent.
// both counts are known, complete, and consistent, with positive input and
// reads between zero and input inclusive. Otherwise it returns (0, false).
// Cache writes are independent; aggregate ratios use summed counts.
func (u ObservedTokenUsage) CacheHitRatio() (float64, bool) {
input, reads := u.PromptTokens, u.CachedTokens
if !input.Known || !input.Complete || !reads.Known || !reads.Complete || input.Value <= 0 || reads.Value < 0 || reads.Value > input.Value {