budget-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kimbeomgyu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# budget-guard
+
+**A circuit breaker for your LLM API bill.** One wrap, set a hard daily cap — runaway retry loops get blocked *before* they bill you. Plus per-feature cost attribution so you know what actually costs what.
+
+> Built for indie devs shipping on the OpenAI / Anthropic APIs who've seen "a $40 bill from a $5 task." Drop-in: your calls still go straight to the provider — `budget-guard` just counts and caps.
+
+Free & open source (MIT). A hosted dashboard with cross-project spend + alerts is planned — but the SDK is, and stays, free.
+
+## Install
+
+```bash
+npm i budget-guard
+```
+
+## Use it (OpenAI)
+
+```ts
+import OpenAI from 'openai';
+import { guard } from 'budget-guard';
+
+const openai = new OpenAI();
+const ai = guard(openai.chat.completions, { project: 'my-app', dailyCapUSD: 50 });
+
+// use it exactly like before — just add an optional feature tag
+const res = await ai.create(
+  { model: 'gpt-4o', messages: [{ role: 'user', content: 'hi' }] },
+  { feature: 'chat' },
+);
+```
+
+If today's spend for `my-app` is already past `$50`, the **next call throws `BudgetExceededError` before it bills**. No more 3am surprise invoices.
+
+## Use it (Anthropic)
+
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+import { guard } from 'budget-guard';
+
+const anthropic = new Anthropic();
+const ai = guard(anthropic.messages, { project: 'my-app', dailyCapUSD: 50 });
+
+await ai.create(
+  { model: 'claude-opus-4', max_tokens: 1024, messages: [{ role: 'user', content: 'hi' }] },
+  { feature: 'summarize' },
+);
+```
+
+`budget-guard` auto-detects OpenAI (`prompt_tokens`/`completion_tokens`) and Anthropic (`input_tokens`/`output_tokens`) usage shapes. For anything else, pass your own extractor:
+
+```ts
+guard(client, opts, { usageOf: (res) => ({ input: res.in, output: res.out }) });
+```
+
+## Know what costs what
+
+```ts
+import { spendReport } from 'budget-guard';
+
+spendReport('my-app');
+// → { chat: 2.41, summarize: 0.88 }   (today, in USD)
+```
+
+## Options
+
+```ts
+guard(client, {
+  project: 'my-app',     // groups spend & shares one cap
+  dailyCapUSD: 50,       // hard cap per day
+  onCap: 'block',        // 'block' (throw) | 'warn' (log only). default 'block'
+});
+```
+
+## Warn instead of block
+
+```ts
+const ai = guard(openai.chat.completions, { project: 'my-app', dailyCapUSD: 50, onCap: 'warn' });
+// over cap → logs a warning, still calls. Good for easing in.
+```
+
+## Notes (v0.1)
+
+- Caps are accounted **after each call** and enforced on the **next** one (no pre-call token estimation yet).
+- The ledger is in-memory per process. Persistence + a hosted dashboard are on the roadmap.
+- Prices live in `PRICES` (USD per 1K tokens) — PRs to keep them current are welcome.
+
+## License
+
+MIT

package/dist/cost.d.ts

@@ -0,0 +1,3 @@
+import type { Usage } from './types';
+/** 토큰 사용량을 가격표 기준 USD 비용으로 환산한다. */
+export declare function cost(model: string, usage: Usage): number;

package/dist/cost.js

@@ -0,0 +1,8 @@
+import { PRICES } from './pricing';
+/** 토큰 사용량을 가격표 기준 USD 비용으로 환산한다. */
+export function cost(model, usage) {
+    const p = PRICES[model];
+    if (!p)
+        throw new Error(`Unknown model: ${model}. Add it to PRICES in pricing.ts`);
+    return (usage.input / 1000) * p.in + (usage.output / 1000) * p.out;
+}

package/dist/guard.d.ts

@@ -0,0 +1,48 @@
+import type { GuardOptions, Usage } from './types';
+/** 호출별 비용 이벤트 (대시보드/로그용). */
+export interface SpendEvent {
+    project: string;
+    feature: string;
+    model: string;
+    usd: number;
+    dayTotalUsd: number;
+}
+interface GuardInternals<R> {
+    /** 테스트용 주입 시계. 기본 실제 시각. */
+    now?: () => Date;
+    /** 비용 발생 시 콜백 (로깅/대시보드 전송). */
+    onSpend?: (e: SpendEvent) => void;
+    /** 제공자 응답에서 토큰 usage를 직접 뽑는 추출기 (자동 인식 안 될 때). */
+    usageOf?: (res: R) => Usage;
+}
+/** 캡 초과로 호출이 차단될 때 던지는 에러. */
+export declare class BudgetExceededError extends Error {
+    project: string;
+    spentUsd: number;
+    capUsd: number;
+    constructor(project: string, spentUsd: number, capUsd: number);
+}
+type CreateArgs = {
+    model: string;
+    [k: string]: unknown;
+};
+/**
+ * LLM 클라이언트를 감싸 (1) 하루 하드 캡으로 폭주를 차단하고
+ * (2) project/feature별로 비용을 귀속한다. 실제 호출은 제공자로 그대로 나간다.
+ *
+ * @example
+ *   const ai = guard(openai.chat.completions, { project: 'app', dailyCapUSD: 50 });
+ *   await ai.create({ model: 'gpt-4o', messages }, { feature: 'summarize' });
+ */
+export declare function guard<R extends object>(client: {
+    create(args: CreateArgs): Promise<R>;
+}, opts: GuardOptions, internals?: GuardInternals<R>): {
+    create(args: CreateArgs, tags?: {
+        feature?: string;
+    }): Promise<R>;
+};
+/** 특정 프로젝트의 그날 기능별 비용 내역을 돌려준다. */
+export declare function spendReport(project: string, day?: string): Record<string, number>;
+/** 테스트 전용: 장부 초기화. */
+export declare function _resetLedger(): void;
+export {};

package/dist/guard.js

@@ -0,0 +1,85 @@
+import { cost } from './cost';
+import { normalizeUsage } from './usage';
+/** 캡 초과로 호출이 차단될 때 던지는 에러. */
+export class BudgetExceededError extends Error {
+    project;
+    spentUsd;
+    capUsd;
+    constructor(project, spentUsd, capUsd) {
+        super(`🛡 Budget cap hit for "${project}": $${spentUsd.toFixed(2)} / $${capUsd} — call blocked`);
+        this.project = project;
+        this.spentUsd = spentUsd;
+        this.capUsd = capUsd;
+        this.name = 'BudgetExceededError';
+    }
+}
+// 앱 전역 장부: "project|feature|YYYY-MM-DD" -> 누적 USD.
+// (한 프로젝트의 캡은 호출 위치와 무관하게 합산되어야 하므로 모듈 전역)
+const ledger = {};
+const SEP = '|';
+const TOTAL = '__total__';
+function dayKey(d) {
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * LLM 클라이언트를 감싸 (1) 하루 하드 캡으로 폭주를 차단하고
+ * (2) project/feature별로 비용을 귀속한다. 실제 호출은 제공자로 그대로 나간다.
+ *
+ * @example
+ *   const ai = guard(openai.chat.completions, { project: 'app', dailyCapUSD: 50 });
+ *   await ai.create({ model: 'gpt-4o', messages }, { feature: 'summarize' });
+ */
+export function guard(client, opts, internals = {}) {
+    const now = internals.now ?? (() => new Date());
+    const onCap = opts.onCap ?? 'block';
+    const extract = internals.usageOf ?? ((res) => normalizeUsage(res.usage));
+    return {
+        async create(args, tags = {}) {
+            const day = dayKey(now());
+            const feature = tags.feature ?? 'default';
+            const totalKey = `${opts.project}${SEP}${TOTAL}${SEP}${day}`;
+            const spentToday = ledger[totalKey] ?? 0;
+            // --- 하드 캡: 돈 나가는 호출 "전에" 차단 ---
+            if (spentToday >= opts.dailyCapUSD) {
+                const err = new BudgetExceededError(opts.project, spentToday, opts.dailyCapUSD);
+                if (onCap === 'block')
+                    throw err;
+                console.warn(err.message);
+            }
+            // --- 진짜 호출은 제공자에게 그대로 ---
+            const res = await client.create(args);
+            // --- 비용 적립 + 기능별 귀속 ---
+            const usd = cost(args.model, extract(res));
+            ledger[totalKey] = spentToday + usd;
+            const featKey = `${opts.project}${SEP}${feature}${SEP}${day}`;
+            ledger[featKey] = (ledger[featKey] ?? 0) + usd;
+            internals.onSpend?.({
+                project: opts.project,
+                feature,
+                model: args.model,
+                usd,
+                dayTotalUsd: ledger[totalKey],
+            });
+            return res;
+        },
+    };
+}
+/** 특정 프로젝트의 그날 기능별 비용 내역을 돌려준다. */
+export function spendReport(project, day = dayKey(new Date())) {
+    const prefix = `${project}${SEP}`;
+    const suffix = `${SEP}${day}`;
+    const out = {};
+    for (const [k, v] of Object.entries(ledger)) {
+        if (k.startsWith(prefix) && k.endsWith(suffix)) {
+            const feature = k.slice(prefix.length, k.length - suffix.length);
+            if (feature !== TOTAL)
+                out[feature] = v;
+        }
+    }
+    return out;
+}
+/** 테스트 전용: 장부 초기화. */
+export function _resetLedger() {
+    for (const k of Object.keys(ledger))
+        delete ledger[k];
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { guard, spendReport, BudgetExceededError } from './guard';
+export { cost } from './cost';
+export { normalizeUsage } from './usage';
+export { PRICES } from './pricing';
+export type { Usage, GuardOptions } from './types';
+export type { SpendEvent } from './guard';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { guard, spendReport, BudgetExceededError } from './guard';
+export { cost } from './cost';
+export { normalizeUsage } from './usage';
+export { PRICES } from './pricing';

package/dist/pricing.d.ts

@@ -0,0 +1,5 @@
+/** 모델별 1K 토큰당 USD 단가 [input, output]. 제공자 가격 변경 시 갱신. */
+export declare const PRICES: Record<string, {
+    in: number;
+    out: number;
+}>;

package/dist/pricing.js

@@ -0,0 +1,6 @@
+/** 모델별 1K 토큰당 USD 단가 [input, output]. 제공자 가격 변경 시 갱신. */
+export const PRICES = {
+    'gpt-4o': { in: 0.0025, out: 0.01 },
+    'gpt-4o-mini': { in: 0.00015, out: 0.0006 },
+    'claude-opus-4': { in: 0.015, out: 0.075 },
+};

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+/** 한 번의 LLM 호출이 쓴 토큰 수. 제공자가 응답의 usage로 알려준다. */
+export interface Usage {
+    input: number;
+    output: number;
+}
+/** guard()에 넘기는 설정. */
+export interface GuardOptions {
+    /** 비용을 묶는 단위(예: 'agent-worker'). */
+    project: string;
+    /** 하루 하드 캡(USD). 초과하면 다음 호출을 막는다. */
+    dailyCapUSD: number;
+    /** 캡 초과 시 동작. 기본 'block'(throw) / 'warn'(경고만). */
+    onCap?: 'block' | 'warn';
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/usage.d.ts

@@ -0,0 +1,9 @@
+import type { Usage } from './types';
+/**
+ * 제공자별 usage 형태를 {input, output} 토큰으로 정규화한다.
+ * - 우리 형태:  { input, output }
+ * - OpenAI:    { prompt_tokens, completion_tokens }
+ * - Anthropic: { input_tokens, output_tokens }
+ * 인식 못 하면 guard()에 usageOf 추출기를 넘기라고 안내.
+ */
+export declare function normalizeUsage(raw: unknown): Usage;

package/dist/usage.js

@@ -0,0 +1,23 @@
+/**
+ * 제공자별 usage 형태를 {input, output} 토큰으로 정규화한다.
+ * - 우리 형태:  { input, output }
+ * - OpenAI:    { prompt_tokens, completion_tokens }
+ * - Anthropic: { input_tokens, output_tokens }
+ * 인식 못 하면 guard()에 usageOf 추출기를 넘기라고 안내.
+ */
+export function normalizeUsage(raw) {
+    const u = raw;
+    if (!u) {
+        throw new Error('No usage on response. Pass a usageOf() extractor to guard().');
+    }
+    if (typeof u.input === 'number' && typeof u.output === 'number') {
+        return { input: u.input, output: u.output };
+    }
+    if (typeof u.prompt_tokens === 'number') {
+        return { input: u.prompt_tokens, output: u.completion_tokens ?? 0 };
+    }
+    if (typeof u.input_tokens === 'number') {
+        return { input: u.input_tokens, output: u.output_tokens ?? 0 };
+    }
+    throw new Error('Unrecognized usage shape. Pass a usageOf() extractor to guard().');
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "budget-guard",
+  "version": "0.1.0",
+  "description": "A circuit breaker for your LLM API bill — hard budget caps + per-feature cost attribution for the OpenAI & Anthropic APIs.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["openai", "anthropic", "llm", "cost", "budget", "tokens", "ai", "rate-limit"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kimbeomgyu/budget-guard.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kimbeomgyu/budget-guard/issues"
+  },
+  "homepage": "https://github.com/kimbeomgyu/budget-guard#readme",
+  "author": "kimbeomgyu",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  }
+}