The Four Actions

Sayay returns one of four actions on each check():

Budget Usage → 0% ────────── 80% ────── 95% ─── 100% →
               │             │           │        │
Action:      allow        warn       degrade    block

allow

Budget is healthy. Proceed with the LLM call normally.

const decision = await guard.check('user-123', 0.01);
// → { action: 'allow', remaining: 4.99 }

warn

Budget is at 80%+ consumption. The call is still allowed, but you should notify the user or admin.

// → { action: 'warn', remaining: 1.20, reason: '80% of daily budget used' }

degrade

Budget is at 95%+ consumption. Tinkuy automatically switches to a cheaper/free model. If you’re not using Tinkuy, implement your own degrade logic:

// → { action: 'degrade', remaining: 0.25, reason: 'Budget low — degrading model' }

// Recommended: use free model
const model = decision.action === 'degrade'
  ? 'nvidia/nemotron-3-ultra-550b:free'
  : 'gpt-4o';

block

Budget is fully exceeded. The LLM call is refused.

// → { action: 'block', remaining: 0, reason: 'Daily budget exceeded' }
// Throw an error or return a cached/fallback response

Custom Thresholds

Override the default 80/95 thresholds:

const guard = new SayayGuard({
  storage: new MemoryStorage(),
  budget: { dailyUsd: 10.0 },
  thresholds: {
    warn: 0.70,    // Warn at 70%
    degrade: 0.90, // Degrade at 90%
  },
});

Budget Per Period

All budget types are checked independently. If ANY budget is exceeded, the action is ‘block’:

const guard = new SayayGuard({
  storage: new MemoryStorage(),
  budget: {
    dailyUsd: 5.0,      // $5/day
    monthlyUsd: 50.0,   // $50/month
    sessionCredits: 0.50, // $0.50/session
  },
});