token-budget-guard 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# token-budget-guard
+
+A small utility to enforce token budgets for AI API calls.
+
+## Why
+Tokens affect cost, latency, and reliability.
+This utility makes token usage explicit and enforceable.
+
+## Features
+- token estimation
+- budget enforcement
+- fail-fast / trim / warn strategies
+
+## Token estimation
+Uses a rough heuristic (~4 chars/token). Counts may differ from model-specific tokenizers,
+especially for non-English text or code/JSON.
+
+## Install
+```bash
+npm install token-budget-guard
+```
+
+## Usage
+```ts
+import { withTokenBudget } from "token-budget-guard";
+
+await withTokenBudget({
+  model: "gpt-4",
+  maxTokens: 8000,
+  prompt,
+  context,
+  expectedOutputTokens: 500,
+  strategy: "trim_context",
+  call: async ({ prompt, context }) => {
+    return client.responses.create({
+      model: "gpt-4",
+      input: [{ role: "user", content: [prompt, ...context] }],
+    });
+  },
+});
+```

package/dist/budget.d.ts

@@ -0,0 +1,6 @@
+export declare function calculateTokenUsage(prompt: string, context?: string[], expectedOutputTokens?: number): {
+    promptTokens: number;
+    contextTokens: number;
+    expectedOutputTokens: number;
+    totalTokens: number;
+};

package/dist/budget.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateTokenUsage = calculateTokenUsage;
+const tokenizer_1 = require("./tokenizer");
+function calculateTokenUsage(prompt, context = [], expectedOutputTokens = 0) {
+    const promptTokens = (0, tokenizer_1.estimateTokens)(prompt);
+    const contextTokens = context.reduce((sum, c) => sum + (0, tokenizer_1.estimateTokens)(c), 0);
+    return {
+        promptTokens,
+        contextTokens,
+        expectedOutputTokens,
+        totalTokens: promptTokens + contextTokens + expectedOutputTokens,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { TokenBudgetOptions } from "./types";
+export declare function withTokenBudget<T>(opts: TokenBudgetOptions<T>): Promise<T>;

package/dist/index.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withTokenBudget = withTokenBudget;
+const budget_1 = require("./budget");
+const tokenizer_1 = require("./tokenizer");
+const strategies_1 = require("./strategies");
+async function withTokenBudget(opts) {
+    const { prompt, context = [], expectedOutputTokens = 0, maxTokens, strategy = "fail_fast", call, } = opts;
+    const usage = (0, budget_1.calculateTokenUsage)(prompt, context, expectedOutputTokens);
+    if (usage.totalTokens <= maxTokens) {
+        return call({ prompt, context, expectedOutputTokens });
+    }
+    if (strategy === "warn_only") {
+        console.warn("[token-budget] exceeded", usage);
+        return call({ prompt, context, expectedOutputTokens });
+    }
+    if (strategy === "trim_context") {
+        const remaining = maxTokens - usage.promptTokens - expectedOutputTokens;
+        if (remaining <= 0) {
+            throw new Error("Token budget exceeded: no room for context");
+        }
+        const trimmedContext = (0, strategies_1.trimContext)(context, remaining, tokenizer_1.estimateTokens);
+        const trimmedUsage = (0, budget_1.calculateTokenUsage)(prompt, trimmedContext, expectedOutputTokens);
+        if (trimmedUsage.totalTokens > maxTokens) {
+            throw new Error(`Token budget exceeded (${trimmedUsage.totalTokens}/${maxTokens})`);
+        }
+        return call({
+            prompt,
+            context: trimmedContext,
+            expectedOutputTokens,
+        });
+    }
+    throw new Error(`Token budget exceeded (${usage.totalTokens}/${maxTokens})`);
+}

package/dist/strategies.d.ts

@@ -0,0 +1 @@
+export declare function trimContext(context: string[], maxContextTokens: number, estimate: (text: string) => number): string[];

package/dist/strategies.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trimContext = trimContext;
+function trimContext(context, maxContextTokens, estimate) {
+    let tokens = 0;
+    const trimmed = [];
+    for (let i = context.length - 1; i >= 0; i--) {
+        const t = estimate(context[i]);
+        if (tokens + t > maxContextTokens)
+            break;
+        tokens += t;
+        trimmed.unshift(context[i]);
+    }
+    return trimmed;
+}

package/dist/tokenizer.d.ts

@@ -0,0 +1 @@
+export declare function estimateTokens(text: string): number;

package/dist/tokenizer.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateTokens = estimateTokens;
+function estimateTokens(text) {
+    // Rough heuristic: ~4 chars per token
+    return Math.ceil(text.length / 4);
+}

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+export type Strategy = "fail_fast" | "trim_context" | "warn_only";
+export interface TokenBudgetOptions<T> {
+    model: string;
+    maxTokens: number;
+    prompt: string;
+    context?: string[];
+    expectedOutputTokens?: number;
+    strategy?: Strategy;
+    call: (payload: {
+        prompt: string;
+        context: string[];
+        expectedOutputTokens: number;
+    }) => Promise<T>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "token-budget-guard",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [],
+  "author": "Mostafa Hanafy",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.2.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "tsx": "^4.21.0"
+  }
+}