ai-spend-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khalid IBNFKIH
+
+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,74 @@
+# AI Spend Guard
+
+**Stop your AI calls from wasting money.**
+
+### The Problem
+Running AI calls in production gets expensive fast. A single classification task might cost $0.66 with GPT-4o when GPT-4o-mini would've cost $0.02.
+
+**Without guardrails:** $0.66  
+**With Spend Guard:** $0.02  
+**Saved:** 97%
+
+---
+
+## Install
+
+```bash
+npm install ai-spend-guard
+```
+
+## Quick start (policy only)
+
+```ts
+import { createSpendGuard } from "ai-spend-guard";
+
+const guard = createSpendGuard({
+  cacheRepeatedPrompts: true,
+  autoReroute: true,
+  maxCostPerCall: 0.2
+});
+
+const result = guard.evaluate({
+  task: "classification",
+  model: "gpt-4o",
+  prompt: "Classify this support ticket",
+  estimatedInputTokens: 180,
+  estimatedOutputTokens: 40
+});
+
+console.log(result.action, result.model, result.savingsUsd);
+```
+
+## Wrap live calls
+
+```ts
+import { createAIGuard } from "ai-spend-guard";
+
+const guard = createAIGuard({
+  apiKey: process.env.HUGGINGFACE_API_KEY!,
+  provider: "huggingface",
+  huggingfaceModel: "deepseek-ai/DeepSeek-R1:fastest",
+  policy: { cacheRepeatedPrompts: true, autoReroute: true }
+});
+
+const response = await guard.chat({
+  model: "deepseek-ai/DeepSeek-R1:fastest",
+  messages: [{ role: "user", content: "Classify this ticket" }]
+}, "classification");
+
+console.log(response.choices?.[0]?.message?.content);
+```
+
+## Pricing
+
+Model pricing lives in `pricing.rates.json`. You can override it with the `AI_SPEND_GUARD_PRICING` environment variable.
+
+## Development scripts
+
+- `npm run check` - type-check the project
+- `npm run build` - build to `dist/`
+- `npm run demo` - run the local demo
+
+## Usage Guide
+
+See the usage guide for integration examples, policy examples, and a middleware sample: [USAGE.md](USAGE.md)

package/dist/cache.d.ts

@@ -0,0 +1,23 @@
+export interface CacheEntry {
+    response: unknown;
+    timestamp: number;
+    cost: number;
+    model: string;
+}
+export declare class InMemoryCache {
+    private cache;
+    private readonly ttlMs;
+    private readonly maxSize;
+    constructor(options?: {
+        ttlMs?: number;
+        maxSize?: number;
+    });
+    get(key: string): CacheEntry | null;
+    set(key: string, response: unknown, cost: number, model: string): void;
+    stats(): {
+        size: number;
+        maxSize: number;
+        ttlMs: number;
+    };
+    clear(): void;
+}

package/dist/cache.js

@@ -0,0 +1,52 @@
+export class InMemoryCache {
+    cache = new Map();
+    ttlMs;
+    maxSize;
+    constructor(options = {}) {
+        this.ttlMs = options.ttlMs ?? 3600000; // 1 hour default
+        this.maxSize = options.maxSize ?? 1000;
+    }
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return null;
+        // Check TTL
+        if (Date.now() - entry.timestamp > this.ttlMs) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry;
+    }
+    set(key, response, cost, model) {
+        // Simple LRU: delete oldest if at max size (loop to avoid sort overhead)
+        if (this.cache.size >= this.maxSize && this.cache.size > 0) {
+            let oldestKey = null;
+            let oldestTime = Infinity;
+            for (const [k, v] of this.cache.entries()) {
+                if (v.timestamp < oldestTime) {
+                    oldestTime = v.timestamp;
+                    oldestKey = k;
+                }
+            }
+            if (oldestKey) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        this.cache.set(key, {
+            response,
+            timestamp: Date.now(),
+            cost,
+            model
+        });
+    }
+    stats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.maxSize,
+            ttlMs: this.ttlMs
+        };
+    }
+    clear() {
+        this.cache.clear();
+    }
+}

package/dist/cli-demo.d.ts

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

package/dist/cli-demo.js

@@ -0,0 +1,132 @@
+import { SpendGuardEngine } from "./engine.js";
+import { estimateChatCostUsd } from "./pricing.js";
+import { AIGuard } from "./client.js";
+import readline from "node:readline";
+const requests = [
+    {
+        id: 1,
+        task: "classification",
+        model: "gpt-4o",
+        prompt: "Classify this ticket as billing or technical",
+        estimatedInputTokens: 50000,
+        estimatedOutputTokens: 5000
+    },
+    {
+        id: 2,
+        task: "classification",
+        model: "gpt-4o",
+        prompt: "Classify this ticket as billing or technical",
+        estimatedInputTokens: 50000,
+        estimatedOutputTokens: 5000
+    }
+];
+async function runMock() {
+    const engine = new SpendGuardEngine({ cacheRepeatedPrompts: true, autoReroute: true });
+    let totalBefore = 0;
+    let totalAfter = 0;
+    const actionsTaken = {};
+    for (const r of requests) {
+        const before = estimateChatCostUsd(r.model, r.estimatedInputTokens, r.estimatedOutputTokens);
+        totalBefore += before;
+        const decision = engine.evaluate({
+            task: r.task,
+            model: r.model,
+            prompt: r.prompt,
+            estimatedInputTokens: r.estimatedInputTokens,
+            estimatedOutputTokens: r.estimatedOutputTokens
+        });
+        const afterModel = decision.model ?? r.model;
+        const after = estimateChatCostUsd(afterModel, r.estimatedInputTokens, r.estimatedOutputTokens);
+        totalAfter += after;
+        actionsTaken[decision.action] = (actionsTaken[decision.action] || 0) + 1;
+    }
+    const saved = totalBefore - totalAfter;
+    const savedPct = totalBefore > 0 ? Math.round((saved / totalBefore) * 100) : 0;
+    console.log("\n=== AI Guard Demo ===\n");
+    console.log(`Task: classification + repeat\n`);
+    console.log("Without AI Guard:");
+    console.log(`  Cost: $${totalBefore.toFixed(2)}\n`);
+    console.log("With AI Guard:");
+    console.log(`  Cost: $${totalAfter.toFixed(2)}\n`);
+    console.log(`Saved: $${saved.toFixed(2)} (${savedPct}%)\n`);
+    console.log("Actions taken:");
+    if (actionsTaken["reroute"]) {
+        console.log(` - Rerouted model → saved on ${actionsTaken["reroute"]} request(s)`);
+    }
+    if (actionsTaken["cache"]) {
+        console.log(` - Cached repeated request(s) → saved on ${actionsTaken["cache"]} request(s)`);
+    }
+    if (actionsTaken["warn"]) {
+        console.log(` - Warnings shown on ${actionsTaken["warn"]} request(s)`);
+    }
+    if (actionsTaken["block"]) {
+        console.log(` - Blocked ${actionsTaken["block"]} request(s)`);
+    }
+    console.log('\nTry integrating: import { createAIGuard } from "./src/index.js" and use guard.chat(...)');
+}
+async function runLive() {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        console.error("OPENAI_API_KEY not set. Set it in your environment to run live.");
+        process.exit(1);
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((res) => rl.question("Proceed with live OpenAI calls? This may incur cost (y/N): ", res));
+    rl.close();
+    if (!/^y(es)?$/i.test(answer.trim())) {
+        console.log("Aborted live run.");
+        return;
+    }
+    const guard = new AIGuard({ apiKey, enableLogging: true });
+    let totalBefore = 0;
+    let totalAfter = 0;
+    const actionsTaken = {};
+    for (const r of requests) {
+        const before = estimateChatCostUsd(r.model, r.estimatedInputTokens, r.estimatedOutputTokens);
+        totalBefore += before;
+        const messages = [{ role: "user", content: r.prompt }];
+        const resp = await guard.chat({ model: r.model, messages }, "classification");
+        const usedIn = resp.usage?.prompt_tokens ?? r.estimatedInputTokens;
+        const usedOut = resp.usage?.completion_tokens ?? r.estimatedOutputTokens;
+        const finalModel = resp.model ?? r.model;
+        const after = estimateChatCostUsd(finalModel, usedIn, usedOut);
+        totalAfter += after;
+        // attempt to infer action from logs
+        const lastLog = guard.getLogs().slice(-1)[0];
+        if (lastLog) {
+            actionsTaken[lastLog.rerouted ? "reroute" : lastLog.cached ? "cache" : lastLog.ruleSavingsUsd ? "warn" : "other"] = (actionsTaken[lastLog.rerouted ? "reroute" : lastLog.cached ? "cache" : lastLog.ruleSavingsUsd ? "warn" : "other"] || 0) + 1;
+        }
+    }
+    const saved = totalBefore - totalAfter;
+    const savedPct = totalBefore > 0 ? Math.round((saved / totalBefore) * 100) : 0;
+    console.log("\n=== AI Guard Live Demo ===\n");
+    console.log(`Task: classification + repeat\n`);
+    console.log("Without AI Guard:");
+    console.log(`  Cost: $${totalBefore.toFixed(2)}\n`);
+    console.log("With AI Guard:");
+    console.log(`  Cost: $${totalAfter.toFixed(2)}\n`);
+    console.log(`Saved: $${saved.toFixed(2)} (${savedPct}%)\n`);
+    console.log("Actions taken:");
+    if (actionsTaken["reroute"]) {
+        console.log(` - Rerouted model → saved on ${actionsTaken["reroute"]} request(s)`);
+    }
+    if (actionsTaken["cache"]) {
+        console.log(` - Cached repeated request(s) → saved on ${actionsTaken["cache"]} request(s)`);
+    }
+    if (actionsTaken["warn"]) {
+        console.log(` - Warnings shown on ${actionsTaken["warn"]} request(s)`);
+    }
+}
+async function main() {
+    const live = process.argv.includes("--live");
+    if (live) {
+        await runLive();
+    }
+    else {
+        await runMock();
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,70 @@
+import type { PolicyConfig, TaskKind } from "./types.js";
+export interface RequestLog {
+    id: string;
+    model: string;
+    tokensIn: number;
+    tokensOut: number;
+    estimatedCostUsd: number;
+    actualCostUsd: number;
+    promptHash: string;
+    cached: boolean;
+    rerouted: boolean;
+    originalModel?: string;
+    potentialSavingsUsd: number;
+    ruleSavingsUsd: number;
+    latencyMs: number;
+    timestamp: number;
+    warnings: string[];
+}
+export interface AIGuardConfig {
+    apiKey: string;
+    provider?: "openai" | "huggingface";
+    huggingfaceModel?: string;
+    policy?: PolicyConfig;
+    cacheOptions?: {
+        ttlMs?: number;
+        maxSize?: number;
+    };
+    backendUrl?: string;
+    enableLogging?: boolean;
+}
+export declare class AIGuard {
+    private provider;
+    private openai;
+    private apiKey;
+    private huggingfaceModel;
+    private guard;
+    private cache;
+    private requestLogs;
+    private backendUrl;
+    private enableLogging;
+    constructor(config: AIGuardConfig);
+    chat(request: {
+        model: string;
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+        [key: string]: unknown;
+    }, task?: TaskKind): Promise<any>;
+    private callProvider;
+    private logRequest;
+    private generateId;
+    getLogs(): RequestLog[];
+    getStats(): {
+        totalRequests: number;
+        actualCostUsd: number;
+        couldHaveSpentUsd: number;
+        wastedCostUsd: number;
+        wastedPercentage: number;
+        reroutedRequests: number;
+        cachedRequests: number;
+        avgLatencyMs: number;
+        cacheStats: {
+            size: number;
+            maxSize: number;
+            ttlMs: number;
+        };
+    };
+    clearLogs(): void;
+}

package/dist/client.js

@@ -0,0 +1,162 @@
+import OpenAI from "openai";
+import { SpendGuardEngine } from "./engine.js";
+import { InMemoryCache } from "./cache.js";
+import { estimateTokens, hashPrompt } from "./tokens.js";
+import { estimateChatCostUsd } from "./pricing.js";
+export class AIGuard {
+    provider;
+    openai;
+    apiKey;
+    huggingfaceModel;
+    guard;
+    cache;
+    requestLogs = [];
+    backendUrl;
+    enableLogging;
+    constructor(config) {
+        this.provider = config.provider ?? "openai";
+        this.apiKey = config.apiKey;
+        this.huggingfaceModel = config.huggingfaceModel ?? "deepseek-ai/DeepSeek-R1:fastest";
+        this.openai = new OpenAI(this.provider === "huggingface"
+            ? { apiKey: config.apiKey, baseURL: "https://router.huggingface.co/v1" }
+            : { apiKey: config.apiKey });
+        this.guard = new SpendGuardEngine(config.policy);
+        this.cache = new InMemoryCache(config.cacheOptions);
+        this.backendUrl = config.backendUrl;
+        this.enableLogging = config.enableLogging !== false;
+    }
+    async chat(request, task = "other") {
+        const startTime = Date.now();
+        const promptHash = hashPrompt(request.messages);
+        // Check cache
+        const cached = this.cache.get(promptHash);
+        if (cached) {
+            const log = {
+                id: this.generateId(),
+                model: request.model,
+                tokensIn: 0,
+                tokensOut: 0,
+                estimatedCostUsd: 0,
+                actualCostUsd: cached.cost,
+                promptHash,
+                cached: true,
+                rerouted: false,
+                potentialSavingsUsd: 0,
+                ruleSavingsUsd: 0,
+                latencyMs: Date.now() - startTime,
+                timestamp: Date.now(),
+                warnings: ["Served from cache"]
+            };
+            this.logRequest(log);
+            return cached.response;
+        }
+        // Estimate tokens
+        const { input, output } = estimateTokens(request.model, "", request.messages);
+        // Evaluate guardrails
+        const decision = this.guard.evaluate({
+            task,
+            model: request.model,
+            prompt: request.messages.map((m) => m.content).join("\n"),
+            estimatedInputTokens: input,
+            estimatedOutputTokens: output
+        });
+        const estimatedCost = estimateChatCostUsd(request.model, input, output);
+        // Determine final model
+        let finalModel = request.model;
+        let rerouted = false;
+        if (decision.action === "reroute" && decision.model !== request.model) {
+            finalModel = decision.model;
+            rerouted = true;
+        }
+        if (decision.action === "block") {
+            throw new Error(`[AI Guard] Request blocked: ${decision.reasons.join("; ")}`);
+        }
+        if (decision.action === "warn" && this.enableLogging) {
+            console.warn(`[AI Guard] Warning: ${decision.reasons.join("; ")}`);
+        }
+        // Make the actual call
+        const updatedRequest = { ...request, model: finalModel };
+        const response = await this.callProvider(updatedRequest);
+        const latencyMs = Date.now() - startTime;
+        const actualTokensIn = response.usage?.prompt_tokens ?? input;
+        const actualTokensOut = response.usage?.completion_tokens ?? output;
+        const actualCost = estimateChatCostUsd(finalModel, actualTokensIn, actualTokensOut);
+        // Cache the response
+        this.cache.set(promptHash, response, actualCost, finalModel);
+        // Log the request
+        const potentialSavings = Math.max(0, estimatedCost - actualCost);
+        const log = {
+            id: this.generateId(),
+            model: request.model,
+            tokensIn: actualTokensIn,
+            tokensOut: actualTokensOut,
+            estimatedCostUsd: estimatedCost,
+            actualCostUsd: actualCost,
+            promptHash,
+            cached: false,
+            rerouted,
+            potentialSavingsUsd: Math.round(potentialSavings * 100) / 100,
+            ruleSavingsUsd: Math.round((decision.savingsUsd ?? 0) * 100) / 100,
+            latencyMs,
+            timestamp: Date.now(),
+            warnings: decision.warnings,
+            ...(rerouted ? { originalModel: request.model } : {})
+        };
+        this.logRequest(log);
+        if (this.enableLogging) {
+            console.log(`[AI Guard] Cost: $${actualCost.toFixed(2)} (saved $${decision.savingsUsd.toFixed(2)})${rerouted ? ` [rerouted to ${finalModel}]` : ""}${cached ? " [cached]" : ""}`);
+        }
+        return response;
+    }
+    async callProvider(request) {
+        if (!this.openai) {
+            throw new Error("OpenAI client is not initialized");
+        }
+        const routedRequest = this.provider === "huggingface"
+            ? { ...request, model: this.huggingfaceModel ?? request.model }
+            : request;
+        return this.openai.chat.completions.create(routedRequest);
+    }
+    logRequest(log) {
+        this.requestLogs.push(log);
+        if (this.backendUrl) {
+            fetch(`${this.backendUrl}/log`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(log)
+            }).catch(() => {
+                // Silently fail if backend is unavailable
+            });
+        }
+    }
+    generateId() {
+        return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    }
+    getLogs() {
+        return this.requestLogs;
+    }
+    getStats() {
+        const logs = this.requestLogs;
+        const totalCost = logs.reduce((sum, log) => sum + log.actualCostUsd, 0);
+        const totalSavings = logs.filter((l) => l.rerouted || l.cached).length;
+        const cachedRequests = logs.filter((l) => l.cached).length;
+        const totalPotentialSavings = Math.round((logs.reduce((s, l) => s + (l.potentialSavingsUsd ?? 0), 0)) * 100) / 100;
+        const couldHaveSpent = Math.round(((totalCost + totalPotentialSavings) * 100)) / 100;
+        const overspendRatio = totalCost > 0 ? Math.round((totalPotentialSavings / totalCost) * 100) : 0;
+        return {
+            totalRequests: logs.length,
+            actualCostUsd: Math.round(totalCost * 100) / 100,
+            couldHaveSpentUsd: couldHaveSpent,
+            wastedCostUsd: totalPotentialSavings,
+            wastedPercentage: overspendRatio,
+            reroutedRequests: logs.filter((l) => l.rerouted).length,
+            cachedRequests,
+            avgLatencyMs: logs.length > 0 ? Math.round(logs.reduce((sum, l) => sum + l.latencyMs, 0) / logs.length) : 0,
+            cacheStats: this.cache.stats()
+        };
+    }
+    clearLogs() {
+        this.requestLogs = [];
+        this.cache.clear();
+    }
+}

package/dist/demo-report.d.ts

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

package/dist/demo-report.js

@@ -0,0 +1,57 @@
+import { SpendGuardEngine } from "./engine.js";
+import { estimateChatCostUsd } from "./pricing.js";
+// Simple single-file demo that doesn't call a real model.
+// It shows before vs after costs for a request and demonstrates caching.
+const engine = new SpendGuardEngine({ cacheRepeatedPrompts: true, autoReroute: true });
+const requests = [
+    {
+        id: 1,
+        task: "classification",
+        model: "gpt-4o",
+        prompt: "Classify this ticket as billing or technical",
+        estimatedInputTokens: 50000,
+        estimatedOutputTokens: 5000
+    },
+    {
+        id: 2,
+        task: "classification",
+        model: "gpt-4o",
+        prompt: "Classify this ticket as billing or technical",
+        estimatedInputTokens: 50000,
+        estimatedOutputTokens: 5000
+    }
+];
+let totalBefore = 0;
+let totalAfter = 0;
+let savedCount = 0;
+let downgradeCount = 0;
+let cacheCount = 0;
+for (const r of requests) {
+    const before = estimateChatCostUsd(r.model, r.estimatedInputTokens, r.estimatedOutputTokens);
+    totalBefore += before;
+    const decision = engine.evaluate({
+        task: r.task,
+        model: r.model,
+        prompt: r.prompt,
+        estimatedInputTokens: r.estimatedInputTokens,
+        estimatedOutputTokens: r.estimatedOutputTokens
+    });
+    const afterModel = decision.model;
+    const after = estimateChatCostUsd(afterModel, r.estimatedInputTokens, r.estimatedOutputTokens);
+    totalAfter += after;
+    if (decision.action === "reroute")
+        downgradeCount++;
+    if (decision.action === "cache")
+        cacheCount++;
+    if (after < before)
+        savedCount++;
+    console.log(JSON.stringify({ id: r.id, before: `$${before.toFixed(2)}`, after: `$${after.toFixed(2)}`, action: decision.action, model: afterModel, savings: `$${(before - after).toFixed(2)}` }, null, 2));
+}
+console.log("\n==== SUMMARY ====");
+console.log(`Requests: ${requests.length}`);
+console.log(`Saved on ${savedCount} requests`);
+console.log(`Downgrades: ${downgradeCount}`);
+console.log(`Cached: ${cacheCount}`);
+console.log(`Total before: $${totalBefore.toFixed(2)}`);
+console.log(`Total after:  $${totalAfter.toFixed(2)}`);
+console.log(`Total saved:  $${(totalBefore - totalAfter).toFixed(2)}`);

package/dist/demo.d.ts

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

package/dist/demo.js

@@ -0,0 +1,29 @@
+import { createSpendGuard } from "./index.js";
+const guard = createSpendGuard({
+    cacheRepeatedPrompts: true,
+    autoReroute: true,
+    disallowModels: ["gpt-4.1"],
+    maxCostPerCall: 0.2
+});
+const requests = [
+    {
+        task: "classification",
+        model: "gpt-4o",
+        prompt: "Classify this ticket as billing or technical",
+        estimatedInputTokens: 50000,
+        estimatedOutputTokens: 5000,
+        retries: 0
+    },
+    {
+        task: "classification",
+        model: "gpt-4o",
+        prompt: "Classify this ticket as billing or technical",
+        estimatedInputTokens: 50000,
+        estimatedOutputTokens: 5000,
+        retries: 0
+    }
+];
+for (const request of requests) {
+    const decision = guard.evaluate(request);
+    console.log(JSON.stringify({ request, decision }, null, 2));
+}

package/dist/engine.d.ts

@@ -0,0 +1,7 @@
+import type { ChatRequest, GuardrailDecision, PolicyConfig } from "./types.js";
+export declare class SpendGuardEngine {
+    private readonly policy;
+    constructor(policy?: PolicyConfig);
+    evaluate(request: ChatRequest): GuardrailDecision;
+    private detectRules;
+}

package/dist/engine.js

@@ -0,0 +1,135 @@
+import { estimateChatCostUsd, getCheaperModel } from "./pricing.js";
+const promptHistory = new Map();
+export class SpendGuardEngine {
+    policy;
+    constructor(policy = {}) {
+        this.policy = policy;
+    }
+    evaluate(request) {
+        const estimatedCostUsd = estimateChatCostUsd(request.model, request.estimatedInputTokens, request.estimatedOutputTokens);
+        const warnings = [];
+        const reasons = [];
+        const appliedRuleIds = [];
+        let action = "allow";
+        let routedModel = request.model;
+        let savingsUsd = 0;
+        const rules = this.detectRules(request, estimatedCostUsd);
+        for (const rule of rules) {
+            appliedRuleIds.push(rule.id);
+            reasons.push(rule.reason);
+            if (rule.action === "warn") {
+                warnings.push(rule.reason);
+            }
+            if (rule.action === "cache") {
+                action = "cache";
+                savingsUsd = Math.max(savingsUsd, rule.estimatedSavingsUsd ?? 0);
+                break;
+            }
+            if (rule.action === "reroute" && this.policy.autoReroute !== false) {
+                action = "reroute";
+                routedModel = rule.suggestedModel ?? routedModel;
+                savingsUsd = Math.max(savingsUsd, rule.estimatedSavingsUsd ?? 0);
+                continue;
+            }
+            if (rule.action === "block" && this.policy.allowBlocking) {
+                action = "block";
+                savingsUsd = Math.max(savingsUsd, estimatedCostUsd);
+                continue;
+            }
+            if (rule.action === "warn" && action === "allow") {
+                action = "warn";
+            }
+        }
+        if (request.retries !== undefined && request.retries >= 3) {
+            warnings.push("Retry loop detected");
+            reasons.push("Retry loop detected");
+            action = action === "allow" ? "warn" : action;
+        }
+        if (estimatedCostUsd > (this.policy.maxCostPerCall ?? Number.POSITIVE_INFINITY)) {
+            warnings.push(`Estimated cost ${formatUsd(estimatedCostUsd)} exceeds policy max`);
+            reasons.push("Call exceeds maximum cost policy");
+            if (this.policy.allowBlocking) {
+                action = "block";
+            }
+            else if (action === "allow") {
+                action = "warn";
+            }
+        }
+        if (routedModel !== request.model) {
+            const routedCost = estimateChatCostUsd(routedModel, request.estimatedInputTokens, request.estimatedOutputTokens);
+            savingsUsd = Math.max(savingsUsd, estimatedCostUsd - routedCost);
+        }
+        return {
+            action,
+            model: routedModel,
+            estimatedCostUsd,
+            savingsUsd: roundMoney(savingsUsd),
+            warnings,
+            reasons,
+            appliedRuleIds
+        };
+    }
+    detectRules(request, estimatedCostUsd) {
+        const rules = [];
+        const promptKey = normalizePrompt(request.prompt);
+        const repeatCount = (promptHistory.get(promptKey) ?? 0) + 1;
+        promptHistory.set(promptKey, repeatCount);
+        if (this.policy.disallowModels?.includes(request.model)) {
+            const suggestedModel = getCheaperModel(request.model);
+            rules.push({
+                id: "disallow-model",
+                reason: `${request.model} is disallowed by policy`,
+                action: this.policy.allowBlocking ? "block" : "reroute",
+                estimatedSavingsUsd: estimatedCostUsd * 0.7,
+                ...(suggestedModel ? { suggestedModel } : {})
+            });
+        }
+        if (request.task === "classification" && isHighCostModel(request.model)) {
+            const suggestedModel = getCheaperModel(request.model);
+            rules.push({
+                id: "overpowered-model-classification",
+                reason: "Overpowered model used for classification",
+                action: "reroute",
+                estimatedSavingsUsd: estimatedCostUsd * 0.8,
+                ...(suggestedModel ? { suggestedModel } : {})
+            });
+        }
+        if (repeatCount >= 2 && this.policy.cacheRepeatedPrompts) {
+            rules.push({
+                id: "identical-prompt-repeat",
+                reason: `Identical prompt repeated ${repeatCount} times`,
+                action: "cache",
+                estimatedSavingsUsd: estimatedCostUsd * 0.9
+            });
+        }
+        if (request.retries !== undefined && request.retries >= 2) {
+            rules.push({
+                id: "retry-loop",
+                reason: "Retry loop detected",
+                action: "warn",
+                estimatedSavingsUsd: estimatedCostUsd * 0.3
+            });
+        }
+        if (estimatedCostUsd >= 0.02 && request.task === "classification") {
+            rules.push({
+                id: "high-cost-low-variance",
+                reason: "High-cost call with low-variance output likely wasteful",
+                action: "warn",
+                estimatedSavingsUsd: estimatedCostUsd * 0.5
+            });
+        }
+        return rules;
+    }
+}
+function normalizePrompt(prompt) {
+    return prompt.trim().replace(/\s+/g, " ").toLowerCase();
+}
+function isHighCostModel(model) {
+    return model === "gpt-4o" || model === "gpt-4.1";
+}
+function roundMoney(value) {
+    return Math.round(value * 100) / 100;
+}
+function formatUsd(value) {
+    return `$${value.toFixed(2)}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { SpendGuardEngine } from "./engine.js";
+export { estimateChatCostUsd } from "./pricing.js";
+export { AIGuard } from "./client.js";
+export { InMemoryCache } from "./cache.js";
+export { estimateTokens, hashPrompt } from "./tokens.js";
+export type { ChatRequest, GuardrailDecision, GuardrailRule, PolicyConfig, SpendAction, TaskKind } from "./types.js";
+export type { RequestLog, AIGuardConfig } from "./client.js";
+import { AIGuard } from "./client.js";
+import { SpendGuardEngine } from "./engine.js";
+import type { PolicyConfig } from "./types.js";
+export declare function createAIGuard(config: ConstructorParameters<typeof AIGuard>[0]): AIGuard;
+export declare function createSpendGuard(policy?: PolicyConfig): SpendGuardEngine;

package/dist/index.js

@@ -0,0 +1,13 @@
+export { SpendGuardEngine } from "./engine.js";
+export { estimateChatCostUsd } from "./pricing.js";
+export { AIGuard } from "./client.js";
+export { InMemoryCache } from "./cache.js";
+export { estimateTokens, hashPrompt } from "./tokens.js";
+import { AIGuard } from "./client.js";
+import { SpendGuardEngine } from "./engine.js";
+export function createAIGuard(config) {
+    return new AIGuard(config);
+}
+export function createSpendGuard(policy = {}) {
+    return new SpendGuardEngine(policy);
+}

package/dist/middleware.d.ts

@@ -0,0 +1,2 @@
+import type { ChatRequest } from "./types.js";
+export declare function guardedChatFetch(request: ChatRequest): Promise<any>;

package/dist/middleware.js

@@ -0,0 +1,48 @@
+import { createSpendGuard } from "./index.js";
+// Very small example showing how to use the guard before calling an OpenAI-like API.
+// This file is illustrative — adapt request shaping for your client library.
+const guard = createSpendGuard({
+    cacheRepeatedPrompts: true,
+    autoReroute: true,
+    maxCostPerCall: 0.5
+});
+export async function guardedChatFetch(request) {
+    // request should include: task, model, prompt, estimatedInputTokens, estimatedOutputTokens
+    const decision = guard.evaluate(request);
+    // Soft enforcement: warn and continue, reroute, or return cached result.
+    if (decision.action === 'cache') {
+        // Your cache lookup here (example omitted).
+        // If cached value exists, return it immediately.
+        const cached = null; // TODO: implement cache lookup
+        if (cached)
+            return cached;
+    }
+    const finalModel = decision.model;
+    if (decision.action === 'warn') {
+        console.warn('Spend guard warning:', decision.reasons.join('; '));
+    }
+    if (decision.action === 'block') {
+        throw new Error('Call blocked by spend policy: ' + decision.reasons.join('; '));
+    }
+    // Build the upstream request adapting the model if rerouted
+    const upstreamPayload = {
+        model: finalModel,
+        messages: [
+            { role: 'system', content: 'You are a helpful assistant.' },
+            { role: 'user', content: request.prompt }
+        ],
+        max_tokens: request.estimatedOutputTokens
+    };
+    // Replace the URL and headers with your provider / API key
+    const resp = await fetch('https://api.openai.com/v1/chat/completions', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`
+        },
+        body: JSON.stringify(upstreamPayload)
+    });
+    const body = await resp.json();
+    // Optionally store response in cache if decision.action was 'cache' and caching enabled
+    return body;
+}

package/dist/pricing.d.ts

@@ -0,0 +1,2 @@
+export declare function estimateChatCostUsd(model: string, inputTokens: number, outputTokens: number): number;
+export declare function getCheaperModel(model: string): string | undefined;

package/dist/pricing.js

@@ -0,0 +1,107 @@
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const DEFAULT_TABLE = {
+    default: {
+        inputPer1MTokens: 5,
+        outputPer1MTokens: 15
+    },
+    models: {
+        "gpt-4o": {
+            inputPer1MTokens: 5,
+            outputPer1MTokens: 15
+        },
+        "gpt-4.1": {
+            inputPer1MTokens: 10,
+            outputPer1MTokens: 30
+        },
+        "gpt-4o-mini": {
+            inputPer1MTokens: 0.15,
+            outputPer1MTokens: 0.6
+        },
+        "gpt-4.1-mini": {
+            inputPer1MTokens: 0.4,
+            outputPer1MTokens: 1.6
+        },
+        "gpt-3.5-turbo": {
+            inputPer1MTokens: 0.5,
+            outputPer1MTokens: 1.5
+        }
+    }
+};
+let cachedTable = null;
+export function estimateChatCostUsd(model, inputTokens, outputTokens) {
+    const table = loadPricingTable();
+    const modelEntry = table.models[model];
+    const fallback = table.default ?? DEFAULT_TABLE.default;
+    const inputRate = modelEntry?.inputPer1MTokens ?? fallback.inputPer1MTokens;
+    const outputRate = modelEntry?.outputPer1MTokens ?? fallback.outputPer1MTokens;
+    const inputCost = (inputTokens / 1_000_000) * inputRate;
+    const outputCost = (outputTokens / 1_000_000) * outputRate;
+    return roundToCents(inputCost + outputCost);
+}
+export function getCheaperModel(model) {
+    if (model === "gpt-4.1") {
+        return "gpt-4o-mini";
+    }
+    if (model === "gpt-4o") {
+        return "gpt-4o-mini";
+    }
+    if (model === "gpt-4.1-mini") {
+        return "gpt-4o-mini";
+    }
+    return undefined;
+}
+function roundToCents(value) {
+    return Math.round(value * 100) / 100;
+}
+function loadPricingTable() {
+    if (cachedTable) {
+        return cachedTable;
+    }
+    const envPath = process.env.AI_SPEND_GUARD_PRICING;
+    const baseDir = dirname(fileURLToPath(import.meta.url));
+    const defaultPath = resolve(baseDir, "../pricing.rates.json");
+    const pricingPath = envPath ? resolve(envPath) : defaultPath;
+    try {
+        const raw = readFileSync(pricingPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (isPricingTable(parsed)) {
+            cachedTable = parsed;
+            return parsed;
+        }
+    }
+    catch {
+        // Fall back to defaults if the file cannot be read.
+    }
+    cachedTable = DEFAULT_TABLE;
+    return DEFAULT_TABLE;
+}
+function isPricingTable(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const table = value;
+    if (!table.default || !isRateEntry(table.default)) {
+        return false;
+    }
+    if (!table.models || typeof table.models !== "object") {
+        return false;
+    }
+    for (const entry of Object.values(table.models)) {
+        if (!isRateEntry(entry)) {
+            return false;
+        }
+    }
+    return true;
+}
+function isRateEntry(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const entry = value;
+    return isValidRate(entry.inputPer1MTokens) && isValidRate(entry.outputPer1MTokens);
+}
+function isValidRate(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}

package/dist/sdk-demo.d.ts

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

package/dist/sdk-demo.js

@@ -0,0 +1,62 @@
+// This is a demo of the full SDK wrapper
+// It shows how to use the AIGuard to wrap OpenAI or Hugging Face chat calls with guardrails
+// Example usage:
+// const guard = createAIGuard({
+//   apiKey: process.env.OPENAI_API_KEY,
+//   provider: "openai",
+//   policy: {
+//     autoReroute: true,
+//     cacheRepeatedPrompts: true,
+//     maxCostPerCall: 0.5
+//   }
+// });
+//
+// const response = await guard.chat({
+//   model: "gpt-4o",
+//   messages: [
+//     { role: "user", content: "Classify this ticket" }
+//   ]
+// }, "classification");
+//
+// console.log(guard.getStats());
+console.log(`
+╔════════════════════════════════════════════════════════════════════╗
+║                    AI Spend Guard - SDK Ready                      ║
+╠════════════════════════════════════════════════════════════════════╣
+║                                                                    ║
+║  The SDK is ready to wrap your OpenAI calls with cost guardrails. ║
+║                                                                    ║
+║  To use it in your app:                                           ║
+║                                                                    ║
+║  1. Install: npm install                                          ║
+║  2. Import: import { createAIGuard } from './src/index.js'       ║
+║  3. Configure:                                                    ║
+║     const guard = createAIGuard({                                 ║
+║       apiKey: process.env.OPENAI_API_KEY,                         ║
+║       policy: {                                                   ║
+║         autoReroute: true,                                        ║
+║         cacheRepeatedPrompts: true,                               ║
+║         maxCostPerCall: 0.5                                       ║
+║       }                                                           ║
+║     })                                                            ║
+║  4. Make calls:                                                   ║
+║     const response = await guard.chat({                           ║
+║       model: "gpt-4o",                                            ║
+║       messages: [{ role: "user", content: "..." }]               ║
+║     }, "classification")                                          ║
+║  5. Check stats:                                                  ║
+║     console.log(guard.getStats())                                 ║
+║                                                                    ║
+║  Features:                                                        ║
+║  ✓ Token estimation with tiktoken                                 ║
+║  ✓ Prompt hashing & caching                                       ║
+║  ✓ Automatic model downgrading                                    ║
+║  ✓ Cost tracking per request                                      ║
+║  ✓ Guardrail rules & soft enforcement                             ║
+║  ✓ Request logging                                                ║
+║                                                                    ║
+║  Note: Set OPENAI_API_KEY environment variable to use live API.  ║
+║                                                                    ║
+╚════════════════════════════════════════════════════════════════════╝
+`);
+export {};

package/dist/tokens.d.ts

@@ -0,0 +1,11 @@
+export declare function estimateTokens(model: string, prompt: string, messages?: Array<{
+    role: string;
+    content: string;
+}>): {
+    input: number;
+    output: number;
+};
+export declare function hashPrompt(content: string | Array<{
+    role: string;
+    content: string;
+}>): string;

package/dist/tokens.js

@@ -0,0 +1,29 @@
+import { encodingForModel } from "js-tiktoken";
+import { createHash } from "node:crypto";
+export function estimateTokens(model, prompt, messages) {
+    try {
+        const enc = encodingForModel(model);
+        let inputTokens = 0;
+        if (messages) {
+            for (const msg of messages) {
+                inputTokens += enc.encode(msg.content).length;
+            }
+        }
+        else {
+            inputTokens = enc.encode(prompt).length;
+        }
+        // Rough estimate: output is often 25-30% of input for most tasks
+        const outputTokens = Math.max(Math.ceil(inputTokens * 0.3), 50);
+        return { input: inputTokens, output: outputTokens };
+    }
+    catch {
+        // Fallback to rough estimate if model is unknown
+        const inputTokens = Math.ceil((messages?.reduce((sum, m) => sum + m.content.length, 0) ?? prompt.length) / 4);
+        const outputTokens = Math.max(Math.ceil(inputTokens * 0.3), 50);
+        return { input: inputTokens, output: outputTokens };
+    }
+}
+export function hashPrompt(content) {
+    const text = Array.isArray(content) ? content.map((m) => m.content).join("\n") : content;
+    return createHash("sha256").update(text).digest("hex");
+}

package/dist/types.d.ts

@@ -0,0 +1,34 @@
+export type TaskKind = "classification" | "summarization" | "generation" | "qa" | "other";
+export type SpendAction = "allow" | "warn" | "reroute" | "cache" | "block";
+export interface ChatRequest {
+    task: TaskKind;
+    model: string;
+    prompt: string;
+    estimatedInputTokens: number;
+    estimatedOutputTokens: number;
+    retries?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface PolicyConfig {
+    maxCostPerCall?: number;
+    disallowModels?: string[];
+    cacheRepeatedPrompts?: boolean;
+    autoReroute?: boolean;
+    allowBlocking?: boolean;
+}
+export interface GuardrailRule {
+    id: string;
+    reason: string;
+    action: SpendAction;
+    suggestedModel?: string;
+    estimatedSavingsUsd?: number;
+}
+export interface GuardrailDecision {
+    action: SpendAction;
+    model: string;
+    estimatedCostUsd: number;
+    savingsUsd: number;
+    warnings: string[];
+    reasons: string[];
+    appliedRuleIds: string[];
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "ai-spend-guard",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Cost-control guardrails for OpenAI- and Hugging Face-compatible chat calls.",
+  "license": "MIT",
+  "keywords": [
+    "ai",
+    "llm",
+    "cost",
+    "guardrails",
+    "openai",
+    "huggingface",
+    "cache",
+    "budget"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "pricing.rates.json"
+  ],
+  "scripts": {
+    "build": "node ./node_modules/typescript/bin/tsc -p tsconfig.json",
+    "check": "node ./node_modules/typescript/bin/tsc -p tsconfig.json --noEmit",
+    "example": "node --import tsx examples/basic.ts",
+    "demo": "node --import tsx src/demo.ts",
+    "demo-cli": "node --import tsx src/cli-demo.ts",
+    "server": "node --import tsx src/server.ts"
+  },
+  "dependencies": {
+    "openai": "^4.67.1",
+    "express": "^4.19.2",
+    "js-tiktoken": "^1.0.14"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.29",
+    "@types/express": "^4.17.21",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}

package/pricing.rates.json

@@ -0,0 +1,28 @@
+{
+  "default": {
+    "inputPer1MTokens": 5,
+    "outputPer1MTokens": 15
+  },
+  "models": {
+    "gpt-4o": {
+      "inputPer1MTokens": 5,
+      "outputPer1MTokens": 15
+    },
+    "gpt-4.1": {
+      "inputPer1MTokens": 10,
+      "outputPer1MTokens": 30
+    },
+    "gpt-4o-mini": {
+      "inputPer1MTokens": 0.15,
+      "outputPer1MTokens": 0.6
+    },
+    "gpt-4.1-mini": {
+      "inputPer1MTokens": 0.4,
+      "outputPer1MTokens": 1.6
+    },
+    "gpt-3.5-turbo": {
+      "inputPer1MTokens": 0.5,
+      "outputPer1MTokens": 1.5
+    }
+  }
+}