How to Set Up Per-User Token Budgets

# In config/auth.yaml:
authentication:
  enabled: true
  method: jwt  # or "api_key", "oauth"

  # Require auth for all requests:
  require_auth: true

  # Extract user_id from token:
  user_id_claim: "sub"  # JWT claim containing user ID

# Or for simple setups without auth:
# In config/users.yaml:
user_identification:
  method: api_key
  users:
    - id: user_alice
      api_key: ak_alice_...
    - id: user_bob
      api_key: ak_bob_...

# In config/budgets.yaml:
per_user_budgets:
  enabled: true

  default_limits:
    daily_tokens: 50000    # 50k tokens/day default
    monthly_tokens: 1000000  # 1M tokens/month

  user_overrides:
    user_alice:
      daily_tokens: 100000   # Power user gets more
      monthly_tokens: 2000000

    user_bob:
      daily_tokens: 25000    # Occasional user gets less
      monthly_tokens: 500000

  # Budget allocation by role:
  role_limits:
    admin: 200000  # daily
    developer: 100000
    viewer: 10000

# In config/budgets.yaml (continued):
per_user_budgets:
  reset_schedule:
    daily_reset_time: "00:00"  # Midnight UTC
    monthly_reset_day: 1       # 1st of month
    timezone: "UTC"

  # Rollover unused tokens?
  rollover:
    enabled: false  # No rollover (use it or lose it)
    # enabled: true  # Unused tokens carry to next period
    # max_rollover_tokens: 100000

  # Warn users approaching limit:
  warnings:
    - at_percent: 75
      message: "You've used 75% of your daily token budget"
    - at_percent: 90
      message: "You've used 90% of your daily budget. Limit will be enforced at 100%"

# In config/budgets.yaml (continued):
per_user_budgets:
  on_approaching_limit:
    action: warn
    message_template: |
      You've used {percent_used}% of your {period} token budget.
      Remaining: {tokens_remaining} tokens
      Resets: {reset_time}

  # Show budget status in responses:
  include_budget_in_response: true
  budget_footer: |
    ---
    Your usage: {tokens_used}/{tokens_limit} tokens ({percent_used}%)
    Resets: {reset_time}

# Admin endpoint to view all user budgets:
# GET /api/admin/budgets

# Expected response:
{
  "users": [
    {
      "user_id": "user_alice",
      "daily_used": 45000,
      "daily_limit": 100000,
      "daily_remaining": 55000,
      "monthly_used": 890000,
      "monthly_limit": 2000000,
      "status": "ok"
    },
    {
      "user_id": "user_bob",
      "daily_used": 25000,
      "daily_limit": 25000,
      "daily_remaining": 0,
      "monthly_used": 520000,
      "monthly_limit": 500000,
      "status": "over_limit"
    }
  ]
}

# Create admin dashboard:
# admin-dashboard.html with real-time budget display

# In config/budgets.yaml (continued):
per_user_budgets:
  on_limit_exceeded:
    action: soft_limit  # Options: "soft_limit", "hard_stop", "reduced_priority"

    # Soft limit: warn but allow continuation
    soft_limit:
      message: |
        You've exceeded your daily token budget.
        Continued usage will be flagged for review.
      notify_admin: true

    # Hard stop: reject new requests
    hard_stop:
      message: |
        You've reached your daily token limit.
        Your budget resets at {reset_time}.
      status_code: 429  # Too Many Requests

    # Reduced priority: route to cheaper models
    reduced_priority:
      force_model: anthropic/claude-3-haiku
      message: "Over budget. Routing to Haiku."