Installation

TypeScript / Cloudflare Workers:

npm install @carloscortezcloud/sayay-guard

Python (Strands, LangChain, CrewAI):

pip install sayay          # core: Memory + File storage
pip install "sayay[redis]" # + Redis storage

Basic Setup — TypeScript

Create a guard with a daily budget and check before each LLM call:

import { SayayGuard, MemoryStorage } from '@carloscortezcloud/sayay-guard';

const guard = new SayayGuard({
  storage: new MemoryStorage(),
  budget: { dailyUsd: 5.0 },
});

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

// If action is 'allow' or 'warn', proceed with LLM call
if (decision.action === 'block') {
  return { error: 'Budget exceeded' };
}

// After the LLM call, record the actual cost
await guard.record('user-123', 0.003);

Basic Setup — Python

Same interface, async API. Same warn (80%) / degrade (95%) / block thresholds:

import asyncio
from sayay import SayayGuard, MemoryStorage

async def main():
    guard = SayayGuard(
        storage=MemoryStorage(),
        budget={"dailyUsd": 5.0},
    )

    # Check before each LLM call
    decision = await guard.check("user-123", 0.01)
    # → {"action": "allow", "remaining": 4.99}

    if decision["action"] == "block":
        return {"error": "Budget exceeded"}

    # After the LLM call, record the actual cost
    await guard.record("user-123", 0.003)

asyncio.run(main())

Storage options in Python: MemoryStorage (in-memory), FileStorage (JSON, survives restarts), RedisStorage (async, requires sayay[redis]).

With Tinkuy Agent

Pass the guard to the Agent constructor — it handles check/record automatically:

import { Agent } from '@carloscortezcloud/tinkuy-agent';
import { SayayGuard, MemoryStorage } from '@carloscortezcloud/sayay-guard';

const agent = new Agent({
  router,
  guard: new SayayGuard({
    storage: new MemoryStorage(),
    budget: { dailyUsd: 5.0 },
  }),
  tools: [myTool],
  systemPrompt: 'You are a helpful assistant.',
});

Budget Config

interface BudgetConfig {
  dailyUsd?: number;     // Resets at midnight UTC
  monthlyUsd?: number;   // Resets on 1st of month
  sessionCredits?: number; // Optional per-session limit
}

Multi-Tenant

Pass a unique userId per user. Sayay tracks spend independently:

await guard.check('user-free-tier', 0.01);   // $0.50/day limit
await guard.check('user-pro-tier', 0.01);    // $50/day limit