usage

Documentation

Overview

Package usage provides a loop.Handler that accumulates token usage metadata from artifact.Usage artifacts and emits PropertiesEvent with running session totals. It is designed to be wired into a loop.Step alongside other handlers.

The handler is thread-safe (protected by sync.Mutex) and gracefully skips turns where no Usage artifact is present (e.g., when the provider stream is interrupted before the final usage chunk arrives). Handle never returns an error; non-Usage artifacts are silently ignored.

A PropertiesEvent is emitted for every Usage artifact, even when all token counts are zero.

The emitted PropertiesEvent contains the following string key/value pairs:

• "sent": per-turn prompt token count
• "received": per-turn completion token count
• "thinking": per-turn output tokens consumed by the model's extended-thinking / reasoning phase
• "total": cumulative total token count

Usage

import (
    "github.com/andrewhowdencom/ore/loop"
    "github.com/andrewhowdencom/ore/x/usage"
)

handler := usage.New()
step := loop.New(
    loop.WithHandlers(handler),
)

Deprecation Consideration

x/telemetry provides per-artifact, per-role OpenTelemetry character metrics that offer finer-grained attribution than token-level PropertiesEvent. PropertiesEvent may be deprecated in future framework versions in favor of these metrics. However, PropertiesEvent is still required for TUI status bar rendering until the TUI is updated to consume telemetry metrics directly.

Package usage provides a loop.Handler that aggregates token usage from artifact.Usage artifacts and broadcasts running totals via PropertiesEvent.

It is designed to be wired as a handler on a loop.Step alongside other artifact handlers (e.g., tool execution). Usage artifacts are left in state so models can optionally see consumption history; this handler only aggregates and emits metadata.

Example:

step := loop.New(loop.WithHandlers(usage.New(), otherHandler))

Index

• type Handler
  • func New() *Handler
  • func (h *Handler) Handle(ctx context.Context, art artifact.Artifact, e loop.Emitter) error

Types

type Handler

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

Handler aggregates token counts from artifact.Usage artifacts and emits a PropertiesEvent after each one so conduits can display running totals.

func New

func New() *Handler

New creates a new usage aggregation handler.

func (*Handler) Handle

func (h *Handler) Handle(ctx context.Context, art artifact.Artifact, e loop.Emitter) error

Handle inspects the artifact for artifact.Usage, adds its counts to the running totals, and emits a PropertiesEvent with the aggregated values. All other artifact kinds are ignored.