Cyclium.AdaptiveBudget (Cyclium v0.2.0)

Copy Markdown View Source

ETS-backed advisory budget tracking.

Tracks actual resource usage (turns, tokens, wall time) across episodes and recommends budgets based on historical p95 values. Does not automatically adjust budgets — advisory only.

Usage

# After episode completion:
Cyclium.AdaptiveBudget.record(:my_actor, :check_health, %{
  turns_used: 4,
  tokens_used: 8_500,
  wall_ms: 15_000
})

# Get recommendation:
Cyclium.AdaptiveBudget.recommend(:my_actor, :check_health)
# => %{max_turns: 8, max_tokens: 18_000, max_wall_ms: 45_000}

# Get detailed stats:
Cyclium.AdaptiveBudget.stats(:my_actor, :check_health)

Summary

Functions

Idempotent ETS table creation.

Recommend budgets based on historical p95 usage with headroom.

Record resource usage for an episode.

Get detailed usage statistics.

Functions

ensure_table()

Idempotent ETS table creation.

recommend(actor_id, expectation_id)

Recommend budgets based on historical p95 usage with headroom.

Returns a budget map or nil if insufficient samples (< 5). Adds 25% headroom above p95 values.

record(actor_id, expectation_id, usage)

Record resource usage for an episode.

usage should include any of:

  • :turns_used — number of turns consumed
  • :tokens_used — number of tokens consumed
  • :wall_ms — wall-clock duration in milliseconds

stats(actor_id, expectation_id)

Get detailed usage statistics.