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());

Links

• Dashboard: app.caplyr.com
• Docs: docs.caplyr.com
• Website: caplyr.com

License

MIT