JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 21
  • Score
    100M100P100Q85083F
  • License MIT

AI Cost Control Plane — budget guardrails, auto-downgrade, and kill switch for AI API calls

Package Exports

  • caplyr

Readme

Caplyr

AI Cost Control Plane — Stop runaway API bills automatically.

Caplyr sits between your app and AI providers, controlling how requests execute based on cost constraints. Budget guardrails, auto-downgrade, and kill switch — in 2 lines of code.

Install

npm install caplyr

Quick Start

import Anthropic from "@anthropic-ai/sdk";
import { protect } from "caplyr";

// Wrap your client — everything else stays the same
const client = protect(new Anthropic(), {
  apiKey: "caplyr_...",       // Get yours at https://app.caplyr.com
  budget: 500,                // Monthly cap in dollars
  fallback: "claude-haiku-3-5-20241022",  // Auto-downgrade target
});

// Use exactly as before — Caplyr is invisible
const response = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});

Works with OpenAI too:

import OpenAI from "openai";
import { protect } from "caplyr";

const client = protect(new OpenAI(), {
  apiKey: "caplyr_...",
  budget: 500,
  fallback: "gpt-4o-mini",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
});

What It Does

Feature Description
Budget Guardrails Daily and monthly caps enforced at the SDK level. Hit the limit → requests are blocked or downgraded.
Auto Downgrade When budget threshold is reached, automatically route to a cheaper model. Your app keeps working.
Kill Switch One-click emergency stop. Halts all AI API calls instantly.

Modes

// Alert-only (default): observe and project, don't enforce
protect(client, { apiKey: "...", mode: "alert_only" });

// Cost protect: enforce budget caps and auto-downgrade
protect(client, { apiKey: "...", mode: "cost_protect", budget: 500 });

Configuration

Option Type Default Description
apiKey string required Your Caplyr project API key
budget number — Monthly budget cap in dollars
dailyBudget number — Daily budget cap in dollars
fallback string auto Fallback model for auto-downgrade
mode string "alert_only" "alert_only" | "cost_protect" | "kill_switch"
downgradeThreshold number 0.8 Budget % at which downgrade activates
endpoint_tag string — Custom tag for cost attribution

Handling Blocked Requests

When a request is blocked, Caplyr throws a structured error:

try {
  const response = await client.messages.create({ ... });
} catch (err) {
  if (err.caplyr) {
    // Caplyr enforcement event
    console.log(err.caplyr.code);        // "BUDGET_EXCEEDED" | "KILL_SWITCH_ACTIVE"
    console.log(err.caplyr.retry_after); // ISO timestamp for next reset
    console.log(err.caplyr.budget_used); // Current spend
  }
}

Shutdown

import { shutdown } from "caplyr";

// Flush pending logs on app exit
process.on("SIGTERM", () => shutdown());

License

MIT