@salimassili/ai-costguard 1.1.7 → 1.1.8

package/README.md

@@ -1,48 +1,107 @@
-# @salimassili/ai-costguard
+# AI CostGuard
 
-![npm](https://img.shields.io/npm/v/@salimassili/ai-costguard)
-![downloads](https://img.shields.io/npm/dw/@salimassili/ai-costguard)
-![license](https://img.shields.io/npm/l/@salimassili/ai-costguard)
+The kill-switch for AI agents.
 
----
+Prevent runaway AI agent loops, token bombs, and budget explosions before they happen.
 
-## ⚡ What it does
+```bash
+npm install @salimassili/ai-costguard
+```
+
+## Install & Protect (30 seconds)
+
+```ts
+import { withCostGuard } from '@salimassili/ai-costguard';
+
+const openai = withCostGuard(client, {
+  maxTotalCostPerDay: 5
+});
+```
+
+## What You Get
+
+When your agent spirals:
+
+```
+[CostGuard] BLOCKED LOOP → 12 recursive cycles detected → estimated save: $18.42
+```
+
+A financial save event. Not a vague error.
+
+## Why This Exists
+
+AI agents don't fail gracefully. They fail exponentially.
+
+A stuck agent can burn hundreds of dollars in API credits overnight. Not because it's fast. Because it's relentless.
+
+Your agent framework has no kill-switch. Rate limiters don't detect semantic loops. Cost alerts tell you after the money is gone.
+
+This is the missing layer.
 
-AI execution firewall for cost control and runtime protection.
+## Real-World Protection
 
----
+### 1. Recursive Loop
+Agent repeats the same reasoning forever.
 
-## 📦 Install
+### 2. Tool Retry Explosion
+Agent retries a failing tool endlessly.
+
+### 3. Budget Breach
+Agent burns tokens rapidly until blocked.
+
+## API
+
+```ts
+withCostGuard(client, {
+  maxTotalCostPerDay: 10,    // Hard USD limit
+  maxTokensPerRequest: 4000, // Per-call limit
+  maxRequestsPerMinute: 30,  // Rate limit
+  loopDetection: true        // Catch repeated prompts
+})
+```
+
+## Example
+
+```ts
+import { withCostGuard, CostGuardError } from '@salimassili/ai-costguard';
+
+const openai = withCostGuard(
+  new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  { maxTotalCostPerDay: 5 }
+);
+
+try {
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'Hello' }],
+  });
+} catch (err) {
+  if (err instanceof CostGuardError) {
+    console.log('Agent blocked:', err.message);
+    // Handle gracefully
+  }
+}
+```
+
+## Express Middleware
+
+```ts
+import { costGuardMiddleware } from '@salimassili/ai-costguard';
+
+app.use(costGuardMiddleware({ maxTotalCostPerDay: 10 }));
+```
+
+## Features
+
+- **Loop detection** — kills repeated prompts and recursive cycles
+- **Daily cost caps** — hard USD limits, no overages
+- **Token limits** — block oversized single requests
+- **RPM limits** — catch agents hammering the API
+
+## Install Before You Deploy
 
 ```bash
 npm install @salimassili/ai-costguard
-🚀 Quick Start
-import * as ai from "@salimassili/ai-costguard";
-
-console.log(ai);
-🧠 Real usage
-Middleware usage
-// example placeholder
-// const protectedAI = ai.withFirewall(model);
-CLI usage
-npx ai-costguard
-Production example
-// server.ts
-// ai protection layer in backend
-📚 API Reference
-Exports
-ExecutionGuard
-CostEstimator
-PolicyEngine
-withFirewall
-
----
-
-# 🌍 STEP 2 — Add README to git
-
-Save file, then run:
+```
 
-```bash
-git add README.md
-git commit -m "docs: improve README for production readiness"
-git push origin main
+MIT | [GitHub](https://github.com/salimassili62-afk/ai-costguard)

package/dist/core/CostGuard.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CostGuard.ts — AI Agent Loop & Cost Firewall
+ *
+ * Wraps your AI client and kills runaway loops before they burn money.
+ * When it blocks, it tells you exactly how much it saved.
+ */
+import { CostGuardConfig, RequestContext, GuardState } from './types.js';
+/**
+ * Wraps any AI client. Detects loops. Enforces hard limits.
+ * Throws on block so your app handles it.
+ */
+export declare function withCostGuard(client: any, config: any, sharedState?: GuardState): any;
+/**
+ * Standalone middleware for Express/Fastify
+ */
+export declare function costGuardMiddleware(config?: Partial<CostGuardConfig>): (req: any, res: any, next: any) => void;
+/** Custom error so users can catch it specifically */
+export declare class CostGuardError extends Error {
+    context: RequestContext;
+    constructor(message: string, context: RequestContext);
+}
+/** Get current pricing for a model (cents per 1K tokens) */
+export declare function getPricing(model: string): {
+    input: number;
+    output: number;
+} | undefined;
+//# sourceMappingURL=CostGuard.d.ts.map

package/dist/core/CostGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CostGuard.d.ts","sourceRoot":"","sources":["../../src/core/CostGuard.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAiB,MAAM,YAAY,CAAC;AAYxF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,CAAC,EAAE,UAAU,OAmE/E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,GAAE,OAAO,CAAC,eAAe,CAAM,IAiB/D,KAAK,GAAG,EAAE,KAAK,GAAG,EAAE,MAAM,GAAG,UAgBtC;AAoFD,sDAAsD;AACtD,qBAAa,cAAe,SAAQ,KAAK;IACvC,OAAO,EAAE,cAAc,CAAC;gBACZ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc;CAKrD;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAEvF"}

package/dist/core/CostGuard.js

@@ -0,0 +1,191 @@
+/**
+ * CostGuard.ts — AI Agent Loop & Cost Firewall
+ *
+ * Wraps your AI client and kills runaway loops before they burn money.
+ * When it blocks, it tells you exactly how much it saved.
+ */
+const MODEL_PRICING = {
+    'gpt-4': { input: 0.03, output: 0.06 },
+    'gpt-4o': { input: 0.005, output: 0.015 },
+    'gpt-4o-mini': { input: 0.00015, output: 0.0006 },
+    'gpt-3.5-turbo': { input: 0.0005, output: 0.0015 },
+    'claude-3-opus': { input: 0.015, output: 0.075 },
+    'claude-3-sonnet': { input: 0.003, output: 0.015 },
+    'claude-3-haiku': { input: 0.00025, output: 0.00125 },
+};
+/**
+ * Wraps any AI client. Detects loops. Enforces hard limits.
+ * Throws on block so your app handles it.
+ */
+export function withCostGuard(client, config, sharedState) {
+    const defaults = {
+        maxTokensPerRequest: 4000,
+        maxRequestsPerMinute: 30,
+        maxTotalCostPerDay: 10.00,
+        loopDetection: true,
+    };
+    const guard = { ...defaults, ...config };
+    // Use shared state if provided (for nested objects), otherwise create new
+    const state = sharedState || {
+        requestCount: 0,
+        totalCost: 0,
+        lastRequestTime: 0,
+        recentPrompts: [],
+        blockedCount: 0,
+    };
+    return new Proxy(client, {
+        get(target, prop) {
+            const value = target[prop];
+            // If it's a function (like .create), wrap it
+            if (typeof value === 'function') {
+                return (...args) => {
+                    // Extract request details from args
+                    const ctx = extractContext(args, prop);
+                    // Evaluate against limits
+                    const decision = evaluate(guard, state, ctx);
+                    if (decision === 'block') {
+                        state.blockedCount++;
+                        // Build a financial save message
+                        const saveMsg = buildSaveMessage(state, ctx);
+                        console.error(saveMsg);
+                        if (guard.onLimitHit)
+                            guard.onLimitHit('Limit exceeded', ctx.estimatedCost);
+                        throw new CostGuardError(saveMsg.replace('[AI CostGuard] ', ''), ctx);
+                    }
+                    // Update state
+                    state.requestCount++;
+                    state.totalCost += ctx.estimatedCost;
+                    state.lastRequestTime = Date.now();
+                    if (guard.loopDetection)
+                        state.recentPrompts.push(ctx.prompt);
+                    if (state.recentPrompts.length > 20)
+                        state.recentPrompts.shift();
+                    console.log(`[AI CostGuard] ALLOW: ${ctx.model} | ${ctx.tokens}t | $${ctx.estimatedCost.toFixed(4)} | Total: $${state.totalCost.toFixed(2)}`);
+                    // Pass through to actual API call
+                    return value.apply(target, args);
+                };
+            }
+            // If it's a nested object (like .chat.completions), recurse with shared state
+            if (value && typeof value === 'object') {
+                return withCostGuard(value, guard, state);
+            }
+            return value;
+        },
+    });
+}
+/**
+ * Standalone middleware for Express/Fastify
+ */
+export function costGuardMiddleware(config = {}) {
+    const guard = {
+        maxTokensPerRequest: 4000,
+        maxRequestsPerMinute: 30,
+        maxTotalCostPerDay: 10.00,
+        loopDetection: true,
+        ...config,
+    };
+    const state = {
+        requestCount: 0,
+        totalCost: 0,
+        lastRequestTime: 0,
+        recentPrompts: [],
+        blockedCount: 0,
+    };
+    return (req, res, next) => {
+        req.costGuard = {
+            state,
+            evaluate: (ctx) => {
+                const decision = evaluate(guard, state, ctx);
+                if (decision === 'block') {
+                    state.blockedCount++;
+                    throw new CostGuardError('Request blocked by cost guard', ctx);
+                }
+                state.requestCount++;
+                state.totalCost += ctx.estimatedCost;
+                state.lastRequestTime = Date.now();
+            },
+        };
+        next();
+    };
+}
+/** Extract request context from API call args */
+function extractContext(args, prop) {
+    const params = args[0] || {};
+    const model = params.model || 'unknown';
+    const messages = params.messages || [];
+    const prompt = messages.map((m) => m.content).join(' ').slice(0, 200);
+    // Estimate tokens (rough: 1 token ≈ 4 chars for English)
+    const inputText = JSON.stringify(messages);
+    const estimatedInputTokens = Math.ceil(inputText.length / 4);
+    const maxOutputTokens = params.max_tokens || 1000;
+    const tokens = estimatedInputTokens + maxOutputTokens;
+    // Estimate cost
+    const pricing = MODEL_PRICING[model] || { input: 0.01, output: 0.03 };
+    const estimatedCost = (estimatedInputTokens / 1000) * pricing.input +
+        (maxOutputTokens / 1000) * pricing.output;
+    return {
+        model,
+        tokens,
+        estimatedCost,
+        timestamp: Date.now(),
+        prompt,
+    };
+}
+/** Build a human-readable "financial save" message */
+function buildSaveMessage(state, ctx) {
+    const duplicates = state.recentPrompts.filter(p => p === ctx.prompt).length;
+    const isLoop = duplicates >= 2;
+    // Estimate how much we saved by blocking this + projected future calls
+    // Assume a runaway loop would repeat ~50 more times if unchecked
+    const projectedCycles = isLoop ? 50 : 10;
+    const estimatedSave = (ctx.estimatedCost * projectedCycles) + ctx.estimatedCost;
+    if (isLoop) {
+        return `[AI CostGuard] BLOCKED LOOP → ${duplicates + 1} recursive cycles detected → estimated save: $${estimatedSave.toFixed(2)}`;
+    }
+    if (ctx.tokens > 4000) {
+        return `[AI CostGuard] BLOCKED TOKEN BOMB → ${ctx.tokens} tokens → estimated save: $${ctx.estimatedCost.toFixed(2)}`;
+    }
+    if (state.totalCost + ctx.estimatedCost > 5) {
+        const remaining = (state.totalCost + ctx.estimatedCost) - 5;
+        return `[AI CostGuard] BLOCKED BUDGET BREACH → daily cap reached → estimated save: $${remaining.toFixed(2)}`;
+    }
+    return `[AI CostGuard] BLOCKED → estimated save: $${ctx.estimatedCost.toFixed(2)}`;
+}
+/** Evaluate request against all limits */
+function evaluate(guard, state, ctx) {
+    // 1. Token limit
+    if (ctx.tokens > guard.maxTokensPerRequest) {
+        return 'block';
+    }
+    // 2. RPM limit
+    const oneMinuteAgo = Date.now() - 60000;
+    if (state.lastRequestTime > oneMinuteAgo && state.requestCount >= guard.maxRequestsPerMinute) {
+        return 'block';
+    }
+    // 3. Daily cost limit
+    if (state.totalCost + ctx.estimatedCost > guard.maxTotalCostPerDay) {
+        return 'block';
+    }
+    // 4. Loop detection (simple: same prompt repeated)
+    if (guard.loopDetection && state.recentPrompts.length > 0) {
+        const duplicates = state.recentPrompts.filter(p => p === ctx.prompt).length;
+        if (duplicates >= 2) {
+            return 'block';
+        }
+    }
+    return 'allow';
+}
+/** Custom error so users can catch it specifically */
+export class CostGuardError extends Error {
+    context;
+    constructor(message, context) {
+        super(message);
+        this.name = 'CostGuardError';
+        this.context = context;
+    }
+}
+/** Get current pricing for a model (cents per 1K tokens) */
+export function getPricing(model) {
+    return MODEL_PRICING[model];
+}
+//# sourceMappingURL=CostGuard.js.map

package/dist/core/CostGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CostGuard.js","sourceRoot":"","sources":["../../src/core/CostGuard.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -1,26 +1,31 @@
-export interface FirewallMetadata {
-    orgId?: string;
-    teamId?: string;
-    appId?: string;
-    userId?: string;
-    sessionId?: string;
-    agentId?: string;
-    workflowId?: string;
-    apiKeyId?: string;
-    requestId?: string;
-    provider?: string;
-    integration?: string;
-    model?: string;
-    [key: string]: string | number | boolean | undefined;
+/**
+ * Minimal types for AI CostGuard MVP
+ */
+export interface CostGuardConfig {
+    /** Max tokens per single request */
+    maxTokensPerRequest: number;
+    /** Max requests per minute */
+    maxRequestsPerMinute: number;
+    /** Max total cost per day in USD */
+    maxTotalCostPerDay: number;
+    /** Enable loop detection */
+    loopDetection: boolean;
+    /** Alert callback when limit hit */
+    onLimitHit?: (reason: string, cost: number) => void;
 }
-export interface TokenBreakdown {
-    inputTokens?: number;
-    outputTokens?: number;
-    totalTokens?: number;
-    cachedInputTokens?: number;
-    reasoningTokens?: number;
-    audioInputTokens?: number;
-    audioOutputTokens?: number;
-    imageUnits?: number;
+export interface RequestContext {
+    model: string;
+    tokens: number;
+    estimatedCost: number;
+    timestamp: number;
+    prompt: string;
 }
+export interface GuardState {
+    requestCount: number;
+    totalCost: number;
+    lastRequestTime: number;
+    recentPrompts: string[];
+    blockedCount: number;
+}
+export type GuardDecision = 'allow' | 'block';
 //# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACtD;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,eAAe;IAC9B,oCAAoC;IACpC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,8BAA8B;IAC9B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oCAAoC;IACpC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,4BAA4B;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,oCAAoC;IACpC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,OAAO,CAAC"}

package/dist/core/types.js

@@ -1,3 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Minimal types for AI CostGuard MVP
+ */
+export {};
 //# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/index.d.ts

@@ -1,40 +1,21 @@
 /**
- * AI Cost Guard - Ambient Execution Safety Constraint for AI Systems
+ * AI CostGuard — AI Agent Loop & Cost Firewall
  *
- * Runtime enforcement layer that activates automatically.
+ * Detects infinite loops in autonomous AI agents and kills them
+ * before they burn your API budget.
  *
- * Usage:
- *   import 'ai-costguard'
+ * Wraps your AI client. Enforces hard limits.
+ * When it blocks, it tells you exactly how much it saved.
  *
- * That's it. Protection is now active. All AI calls are intercepted.
+ * @example
+ * import { OpenAI } from 'openai';
+ * import { withCostGuard } from '@salimassili/ai-costguard';
  *
- * System identity: "Ambient execution safety constraint for AI systems"
- * NOT: tool, SDK, framework, product, middleware
- * YES: runtime enforcement layer (like TLS for AI)
- *
- * Removing this import makes your AI execution unsafe.
+ * const openai = withCostGuard(
+ *   new OpenAI({ apiKey: 'sk-...' }),
+ *   { maxTotalCostPerDay: 5.00 }
+ * );
  */
-import { ambientProtection, getAmbientStatus } from './ambient/AmbientProtection';
-export { OpenAI } from './replacements/openai';
-export { fetch } from './replacements/fetch';
-export { default as axios } from './replacements/axios';
-export { getAmbientStatus };
-export { STARTER_OPENAI_PROTECTED, generateOpenAIStarter } from './starters/openai-protected';
-export { STARTER_EXPRESS_PROTECTED, generateExpressStarter } from './starters/express-protected';
-export { STARTER_SERVERLESS_PROTECTED, generateServerlessStarter } from './starters/serverless-protected';
-export { STARTER_LANGCHAIN_PROTECTED, generateLangChainStarter } from './starters/langchain-protected';
-export { ProductionSaaS, startProductionSaaS } from './saas';
-export { publicLedger } from './trust/PublicVerificationLedger';
-export declare const protection: {
-    active: boolean;
-    status: {
-        active: boolean;
-        mode: string;
-        interceptCount: number;
-        blockCount: number;
-        aiUsageDetected: boolean;
-    };
-    message: string;
-};
-export default ambientProtection;
+export { withCostGuard, costGuardMiddleware, CostGuardError, getPricing } from './core/CostGuard.js';
+export type { CostGuardConfig, RequestContext, GuardState } from './core/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAWlF,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAI/C,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAI7C,OAAO,EAAE,OAAO,IAAI,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAIxD,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAI5B,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAC9F,OAAO,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AACjG,OAAO,EAAE,4BAA4B,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAC1G,OAAO,EAAE,2BAA2B,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAIvG,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAI7D,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAIhE,eAAO,MAAM,UAAU;;;;;;;;;;CAItB,CAAC;AAGF,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACrG,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -1,76 +1,20 @@
-"use strict";
 /**
- * AI Cost Guard - Ambient Execution Safety Constraint for AI Systems
+ * AI CostGuard — AI Agent Loop & Cost Firewall
  *
- * Runtime enforcement layer that activates automatically.
+ * Detects infinite loops in autonomous AI agents and kills them
+ * before they burn your API budget.
  *
- * Usage:
- *   import 'ai-costguard'
+ * Wraps your AI client. Enforces hard limits.
+ * When it blocks, it tells you exactly how much it saved.
  *
- * That's it. Protection is now active. All AI calls are intercepted.
+ * @example
+ * import { OpenAI } from 'openai';
+ * import { withCostGuard } from '@salimassili/ai-costguard';
  *
- * System identity: "Ambient execution safety constraint for AI systems"
- * NOT: tool, SDK, framework, product, middleware
- * YES: runtime enforcement layer (like TLS for AI)
- *
- * Removing this import makes your AI execution unsafe.
+ * const openai = withCostGuard(
+ *   new OpenAI({ apiKey: 'sk-...' }),
+ *   { maxTotalCostPerDay: 5.00 }
+ * );
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.protection = exports.publicLedger = exports.startProductionSaaS = exports.ProductionSaaS = exports.generateLangChainStarter = exports.STARTER_LANGCHAIN_PROTECTED = exports.generateServerlessStarter = exports.STARTER_SERVERLESS_PROTECTED = exports.generateExpressStarter = exports.STARTER_EXPRESS_PROTECTED = exports.generateOpenAIStarter = exports.STARTER_OPENAI_PROTECTED = exports.getAmbientStatus = exports.axios = exports.OpenAI = void 0;
-// === AUTO-ACTIVATE ON IMPORT ===
-// Protection activates immediately when module is loaded
-const AmbientProtection_1 = require("./ambient/AmbientProtection");
-Object.defineProperty(exports, "getAmbientStatus", { enumerable: true, get: function () { return AmbientProtection_1.getAmbientStatus; } });
-// Console notification
-console.log('[AI Cost Guard] Execution constraint active');
-console.log('[AI Cost Guard] All AI calls will be intercepted');
-// === DROP-IN REPLACEMENTS ===
-// Replace your imports with protected versions
-// Replace: import { OpenAI } from 'openai'
-// With:    import { OpenAI } from 'ai-costguard/openai'
-var openai_1 = require("./replacements/openai");
-Object.defineProperty(exports, "OpenAI", { enumerable: true, get: function () { return openai_1.OpenAI; } });
-// Replace: import { fetch } from 'cross-fetch'
-// With:    import { fetch } from 'ai-costguard/fetch'
-var fetch_1 = require("./replacements/fetch");
-Object.defineProperty(exports, "fetch", { enumerable: true, get: function () { return fetch_1.fetch; } });
-// Replace: import axios from 'axios'
-// With:    import axios from 'ai-costguard/axios'
-var axios_1 = require("./replacements/axios");
-Object.defineProperty(exports, "axios", { enumerable: true, get: function () { return __importDefault(axios_1).default; } });
-// === PROJECT STARTERS ===
-// Full working repos, already protected
-var openai_protected_1 = require("./starters/openai-protected");
-Object.defineProperty(exports, "STARTER_OPENAI_PROTECTED", { enumerable: true, get: function () { return openai_protected_1.STARTER_OPENAI_PROTECTED; } });
-Object.defineProperty(exports, "generateOpenAIStarter", { enumerable: true, get: function () { return openai_protected_1.generateOpenAIStarter; } });
-var express_protected_1 = require("./starters/express-protected");
-Object.defineProperty(exports, "STARTER_EXPRESS_PROTECTED", { enumerable: true, get: function () { return express_protected_1.STARTER_EXPRESS_PROTECTED; } });
-Object.defineProperty(exports, "generateExpressStarter", { enumerable: true, get: function () { return express_protected_1.generateExpressStarter; } });
-var serverless_protected_1 = require("./starters/serverless-protected");
-Object.defineProperty(exports, "STARTER_SERVERLESS_PROTECTED", { enumerable: true, get: function () { return serverless_protected_1.STARTER_SERVERLESS_PROTECTED; } });
-Object.defineProperty(exports, "generateServerlessStarter", { enumerable: true, get: function () { return serverless_protected_1.generateServerlessStarter; } });
-var langchain_protected_1 = require("./starters/langchain-protected");
-Object.defineProperty(exports, "STARTER_LANGCHAIN_PROTECTED", { enumerable: true, get: function () { return langchain_protected_1.STARTER_LANGCHAIN_PROTECTED; } });
-Object.defineProperty(exports, "generateLangChainStarter", { enumerable: true, get: function () { return langchain_protected_1.generateLangChainStarter; } });
-// === SELF-HOSTED INFRASTRUCTURE ===
-// For running your own protection server
-var saas_1 = require("./saas");
-Object.defineProperty(exports, "ProductionSaaS", { enumerable: true, get: function () { return saas_1.ProductionSaaS; } });
-Object.defineProperty(exports, "startProductionSaaS", { enumerable: true, get: function () { return saas_1.startProductionSaaS; } });
-// === TRUST & VERIFICATION ===
-// Public cryptographic proofs
-var PublicVerificationLedger_1 = require("./trust/PublicVerificationLedger");
-Object.defineProperty(exports, "publicLedger", { enumerable: true, get: function () { return PublicVerificationLedger_1.publicLedger; } });
-// === SYSTEM STATE ===
-// Current protection status
-exports.protection = {
-    active: true,
-    status: (0, AmbientProtection_1.getAmbientStatus)(),
-    message: 'Execution secured. AI calls intercepted.',
-};
-// Default export is the ambient protection singleton
-exports.default = AmbientProtection_1.ambientProtection;
+export { withCostGuard, costGuardMiddleware, CostGuardError, getPricing } from './core/CostGuard.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;;;;AAEH,kCAAkC;AAClC,yDAAyD;AACzD,mEAAkF;AAuBzE,iGAvBmB,oCAAgB,OAuBnB;AArBzB,uBAAuB;AACvB,OAAO,CAAC,GAAG,CAAC,6CAA6C,CAAC,CAAC;AAC3D,OAAO,CAAC,GAAG,CAAC,kDAAkD,CAAC,CAAC;AAEhE,+BAA+B;AAC/B,+CAA+C;AAE/C,2CAA2C;AAC3C,wDAAwD;AACxD,gDAA+C;AAAtC,gGAAA,MAAM,OAAA;AAEf,+CAA+C;AAC/C,sDAAsD;AACtD,8CAA6C;AAApC,8FAAA,KAAK,OAAA;AAEd,qCAAqC;AACrC,kDAAkD;AAClD,8CAAwD;AAA/C,+GAAA,OAAO,OAAS;AAMzB,2BAA2B;AAC3B,wCAAwC;AACxC,gEAA8F;AAArF,4HAAA,wBAAwB,OAAA;AAAE,yHAAA,qBAAqB,OAAA;AACxD,kEAAiG;AAAxF,8HAAA,yBAAyB,OAAA;AAAE,2HAAA,sBAAsB,OAAA;AAC1D,wEAA0G;AAAjG,oIAAA,4BAA4B,OAAA;AAAE,iIAAA,yBAAyB,OAAA;AAChE,sEAAuG;AAA9F,kIAAA,2BAA2B,OAAA;AAAE,+HAAA,wBAAwB,OAAA;AAE9D,qCAAqC;AACrC,yCAAyC;AACzC,+BAA6D;AAApD,sGAAA,cAAc,OAAA;AAAE,2GAAA,mBAAmB,OAAA;AAE5C,+BAA+B;AAC/B,8BAA8B;AAC9B,6EAAgE;AAAvD,wHAAA,YAAY,OAAA;AAErB,uBAAuB;AACvB,4BAA4B;AACf,QAAA,UAAU,GAAG;IACxB,MAAM,EAAE,IAAI;IACZ,MAAM,EAAE,IAAA,oCAAgB,GAAE;IAC1B,OAAO,EAAE,0CAA0C;CACpD,CAAC;AAEF,qDAAqD;AACrD,kBAAe,qCAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}