@salimassili/ai-costguard 1.2.0 → 2.0.0

package/docs/INTEGRATIONS.md

@@ -0,0 +1,153 @@
+# Integrations
+
+AI CostGuard works best when it sits immediately before an AI provider call or agent step. The examples in `examples/integrations` use mocked SDK surfaces so they run without API keys or paid requests.
+
+Run them after building the package:
+
+```bash
+npm run build
+node examples/integrations/openai-agent-loop.mjs
+node examples/integrations/anthropic-workflow-budget.mjs
+node examples/integrations/vercel-ai-chatbot.mjs
+node examples/integrations/langchain-retry-storm.mjs
+node examples/integrations/mastra-agent.mjs
+node examples/integrations/crewai-budget-gate.mjs
+node examples/integrations/ci-budget-check.mjs
+```
+
+## OpenAI SDK
+
+Use `guard()` around the OpenAI client. AI CostGuard guards `chat.completions.create`, `responses.create`, and `completions.create` by default.
+
+```ts
+import OpenAI from 'openai';
+import { guard } from '@salimassili/ai-costguard';
+
+const openai = guard(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
+  budget: 5,
+  scope: { projectId: 'api', sessionId: 'agent-run-1' },
+});
+
+await openai.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Summarize this ticket.' }],
+  max_tokens: 200,
+});
+```
+
+Runnable mock: `examples/integrations/openai-agent-loop.mjs`
+
+## Anthropic SDK
+
+Use `guard()` around the Anthropic client. AI CostGuard guards `messages.create` by default.
+
+```ts
+import Anthropic from '@anthropic-ai/sdk';
+import { guard } from '@salimassili/ai-costguard';
+
+const anthropic = guard(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }), {
+  budget: 2,
+  scope: { projectId: 'workflow', sessionId: 'daily-run' },
+});
+
+await anthropic.messages.create({
+  model: 'claude-haiku-4.5',
+  max_tokens: 300,
+  messages: [{ role: 'user', content: 'Draft the daily workflow summary.' }],
+});
+```
+
+Runnable mock: `examples/integrations/anthropic-workflow-budget.mjs`
+
+## Vercel AI SDK
+
+Vercel AI SDK calls are often function-style. Use `guardFunction()` around your `generateText` adapter and pass a request object that includes `model`, prompt/messages, and output token limits.
+
+```ts
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { guardFunction } from '@salimassili/ai-costguard';
+
+const guardedGenerateText = guardFunction(
+  (request) => generateText({ model: openai(request.model), prompt: request.prompt }),
+  { budget: 1, scope: { projectId: 'chatbot' } }
+);
+
+await guardedGenerateText({
+  model: 'gpt-4o-mini',
+  prompt: 'Answer the user in one paragraph.',
+  max_tokens: 200,
+});
+```
+
+Runnable mock: `examples/integrations/vercel-ai-chatbot.mjs`
+
+## LangChain
+
+LangChain shapes vary by model wrapper. The most reliable pattern is to guard a small adapter function that normalizes LangChain inputs into an object with model, prompt/messages, and max token fields.
+
+```ts
+import { guardFunction } from '@salimassili/ai-costguard';
+
+const invoke = guardFunction(
+  (request) => chatModel.invoke(request.prompt),
+  {
+    budget: 2,
+    retryThreshold: 2,
+    scope: { projectId: 'retrieval-agent', sessionId: 'run-42' },
+  }
+);
+
+await invoke({
+  model: 'gpt-4o-mini',
+  prompt: 'retry failed retrieval after timeout',
+  max_tokens: 150,
+});
+```
+
+Runnable mock: `examples/integrations/langchain-retry-storm.mjs`
+
+## Mastra
+
+For object-style agent runners, guard the agent object and set `guardedMethods` to the method path you want to protect.
+
+```ts
+import { guard } from '@salimassili/ai-costguard';
+
+const app = guard(mastraApp, {
+  budget: 10,
+  guardedMethods: ['agent.run'],
+  scope: { projectId: 'mastra-agent' },
+  pricingOverrides: [
+    {
+      model: 'internal-agent-model',
+      inputPer1kTokens: 0.001,
+      outputPer1kTokens: 0.002,
+      lastUpdated: '2026-06-08',
+      source: 'internal pricing',
+    },
+  ],
+});
+```
+
+Runnable mock: `examples/integrations/mastra-agent.mjs`
+
+## CrewAI
+
+CrewAI is Python-native, so this TypeScript package cannot instrument internal Python SDK calls directly. Practical options:
+
+- Use `aifw check` / `ai-costguard check` in CI or before launching a CrewAI run.
+- Wrap a Node launcher or API boundary with `guardFunction()` before it starts the Python workflow.
+- Use provider-side billing alerts for final reconciliation.
+
+Runnable mock: `examples/integrations/crewai-budget-gate.mjs`
+
+## CI Budget Check
+
+Use the CLI to fail a pipeline before a planned agent run can exceed budget.
+
+```bash
+ai-costguard check --budget 0.25 --model gpt-4o-mini --input-tokens 800 --tokens 1200 --max-steps 20
+```
+
+Runnable example: `examples/integrations/ci-budget-check.mjs`

package/examples/integrations/anthropic-workflow-budget.mjs

@@ -0,0 +1,36 @@
+import { guard, GuardError } from '@salimassili/ai-costguard';
+
+const fakeAnthropic = {
+  messages: {
+    create: async (request) => ({
+      id: 'mock-anthropic-message',
+      content: [{ type: 'text', text: 'mocked Anthropic response' }],
+      usage: { input_tokens: 120, output_tokens: request.max_tokens ?? 100 },
+    }),
+  },
+};
+
+const anthropic = guard(fakeAnthropic, {
+  budget: 0.002,
+  scope: { projectId: 'anthropic-workflow-demo', sessionId: 'daily-summary' },
+});
+
+await anthropic.messages.create({
+  model: 'claude-haiku-4.5',
+  max_tokens: 100,
+  messages: [{ role: 'user', content: 'Draft a short workflow summary.' }],
+});
+
+try {
+  await anthropic.messages.create({
+    model: 'claude-haiku-4.5',
+    max_tokens: 1000,
+    messages: [{ role: 'user', content: 'Draft a much longer workflow summary.' }],
+  });
+} catch (error) {
+  if (error instanceof GuardError) {
+    console.log(JSON.stringify({ blocked: true, code: error.code, estimatedCost: error.context.estimatedCost }, null, 2));
+  } else {
+    throw error;
+  }
+}

package/examples/integrations/ci-budget-check.mjs

@@ -0,0 +1,32 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cliPath = join(here, '..', '..', 'dist', 'cli.js');
+
+const result = spawnSync(
+  process.execPath,
+  [
+    cliPath,
+    'check',
+    '--budget',
+    '0.25',
+    '--model',
+    'gpt-4o-mini',
+    '--input-tokens',
+    '800',
+    '--tokens',
+    '1200',
+    '--max-steps',
+    '20',
+  ],
+  { encoding: 'utf8' }
+);
+
+if (result.status !== 0) {
+  process.stderr.write(result.stderr || result.stdout);
+  process.exitCode = result.status ?? 1;
+} else {
+  process.stdout.write(result.stdout);
+}

package/examples/integrations/crewai-budget-gate.mjs

@@ -0,0 +1,31 @@
+import { guardFunction, GuardError } from '@salimassili/ai-costguard';
+
+async function mockCrewAiLauncher(request) {
+  return {
+    command: 'crewai run',
+    launched: false,
+    reason: 'mock example only; no Python process or paid API call is started',
+    request,
+  };
+}
+
+const runCrewAi = guardFunction(mockCrewAiLauncher, {
+  budget: 0.01,
+  scope: { projectId: 'crewai-demo', sessionId: 'crew-run-1' },
+});
+
+try {
+  const result = await runCrewAi({
+    model: 'gpt-4o-mini',
+    prompt: 'Run a CrewAI research workflow with a strict budget gate.',
+    max_tokens: 500,
+  });
+
+  console.log(JSON.stringify({ ok: true, command: result.command, launched: result.launched }, null, 2));
+} catch (error) {
+  if (error instanceof GuardError) {
+    console.log(JSON.stringify({ ok: false, code: error.code }, null, 2));
+  } else {
+    throw error;
+  }
+}

package/examples/integrations/langchain-retry-storm.mjs

@@ -0,0 +1,32 @@
+import { guardFunction, GuardError } from '@salimassili/ai-costguard';
+
+async function mockLangChainInvoke(request) {
+  return {
+    content: `mock LangChain response for ${request.prompt}`,
+    usage: { prompt_tokens: 32, completion_tokens: request.max_tokens ?? 64 },
+  };
+}
+
+const invoke = guardFunction(mockLangChainInvoke, {
+  budget: 1,
+  retryThreshold: 2,
+  scope: { projectId: 'langchain-demo', sessionId: 'retriever-run' },
+});
+
+const prompts = [
+  'retry failed retrieval after timeout for customer A',
+  'again after 429 error for customer B',
+  'repeat after failed vector search for customer C',
+];
+
+for (const prompt of prompts) {
+  try {
+    await invoke({ model: 'gpt-4o-mini', prompt, max_tokens: 64 });
+  } catch (error) {
+    if (error instanceof GuardError) {
+      console.log(JSON.stringify({ blocked: true, code: error.code }, null, 2));
+    } else {
+      throw error;
+    }
+  }
+}

package/examples/integrations/mastra-agent.mjs

@@ -0,0 +1,41 @@
+import { guard, GuardError } from '@salimassili/ai-costguard';
+
+const fakeMastraAgent = {
+  agent: {
+    run: async (request) => ({
+      output: `mock Mastra agent result for ${request.prompt}`,
+      usage: { inputTokens: 50, outputTokens: request.max_tokens ?? 100 },
+    }),
+  },
+};
+
+const guardedAgent = guard(fakeMastraAgent, {
+  budget: 0.01,
+  guardedMethods: ['agent.run'],
+  scope: { projectId: 'mastra-demo', sessionId: 'agent-run-1' },
+  pricingOverrides: [
+    {
+      model: 'mastra-demo-model',
+      inputPer1kTokens: 0.001,
+      outputPer1kTokens: 0.002,
+      lastUpdated: '2026-06-08',
+      source: 'example override',
+    },
+  ],
+});
+
+try {
+  const result = await guardedAgent.agent.run({
+    model: 'mastra-demo-model',
+    prompt: 'Plan the next workflow step.',
+    max_tokens: 100,
+  });
+
+  console.log(JSON.stringify({ ok: true, output: result.output }, null, 2));
+} catch (error) {
+  if (error instanceof GuardError) {
+    console.log(JSON.stringify({ ok: false, code: error.code }, null, 2));
+  } else {
+    throw error;
+  }
+}

package/examples/integrations/openai-agent-loop.mjs

@@ -0,0 +1,44 @@
+import { guard, GuardError } from '@salimassili/ai-costguard';
+
+const fakeOpenAI = {
+  chat: {
+    completions: {
+      create: async (request) => ({
+        id: `mock-${request.messages.length}`,
+        choices: [{ message: { content: 'mocked OpenAI response' } }],
+        usage: { prompt_tokens: 24, completion_tokens: request.max_tokens ?? 16 },
+      }),
+    },
+  },
+};
+
+const openai = guard(fakeOpenAI, {
+  budget: 1,
+  loopSimilarityThreshold: 0.9,
+  loopMinRepeats: 2,
+  scope: { projectId: 'openai-agent-demo', sessionId: 'run-1' },
+});
+
+let blocked = false;
+
+for (let step = 1; step <= 3; step++) {
+  try {
+    await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [{ role: 'user', content: 'inspect the same failing tool result and try to continue' }],
+      max_tokens: 64,
+    });
+  } catch (error) {
+    if (error instanceof GuardError) {
+      blocked = true;
+      console.log(JSON.stringify({ blocked, step, code: error.code }, null, 2));
+      break;
+    }
+
+    throw error;
+  }
+}
+
+if (!blocked) {
+  throw new Error('Expected loop protection to block the repeated agent prompt.');
+}

package/examples/integrations/vercel-ai-chatbot.mjs

@@ -0,0 +1,29 @@
+import { guardFunction, GuardError } from '@salimassili/ai-costguard';
+
+async function mockGenerateText(request) {
+  return {
+    text: `mocked answer for ${request.prompt}`,
+    usage: { prompt_tokens: 40, completion_tokens: request.max_tokens ?? 80 },
+  };
+}
+
+const generateText = guardFunction(mockGenerateText, {
+  budget: 0.001,
+  scope: { projectId: 'vercel-chatbot-demo', sessionId: 'chat-123' },
+});
+
+try {
+  const result = await generateText({
+    model: 'gpt-4o-mini',
+    prompt: 'Answer the user in one paragraph.',
+    max_tokens: 80,
+  });
+
+  console.log(JSON.stringify({ ok: true, text: result.text }, null, 2));
+} catch (error) {
+  if (error instanceof GuardError) {
+    console.log(JSON.stringify({ ok: false, code: error.code }, null, 2));
+  } else {
+    throw error;
+  }
+}

package/package.json

@@ -1,27 +1,53 @@
 {
   "name": "@salimassili/ai-costguard",
-  "version": "1.2.0",
-  "description": "AI Agent Loop & Cost Firewall. Detects infinite loops in autonomous AI agents and kills them before they burn your API budget.",
+  "version": "2.0.0",
+  "description": "Local-first runtime safety layer for AI agents that blocks runaway costs, loops, retries, and budget overruns before API calls execute.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "bin": {
+    "aifw": "./dist/cli.js",
+    "ai-costguard": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./pro": {
+      "types": "./dist/pro.d.ts",
+      "import": "./dist/pro.js",
+      "default": "./dist/pro.js"
+    },
+    "./pricing": {
+      "types": "./dist/pricing/index.d.ts",
+      "import": "./dist/pricing/index.js",
+      "default": "./dist/pricing/index.js"
     }
   },
   "files": [
     "dist",
-    "README.md"
+    "docs/DASHBOARD.md",
+    "docs/INTEGRATIONS.md",
+    "docs/BENCHMARKS.md",
+    "examples/integrations",
+    "benchmarks/run.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
   ],
   "scripts": {
     "clean": "rimraf dist",
     "build": "npm run clean && tsc",
-    "test": "node --experimental-vm-modules test/smoke.mjs",
-    "prepublishOnly": "npm run build"
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test --experimental-test-coverage --test-coverage-include=dist/**/*.js --test-coverage-lines=80 --test-coverage-functions=80 --test-coverage-branches=70 \"test/**/*.test.mjs\"",
+    "smoke": "node test/smoke-examples.mjs",
+    "benchmark": "node benchmarks/run.mjs",
+    "preflight": "node scripts/preflight.js",
+    "prepublishOnly": "npm run preflight"
   },
   "keywords": [
     "ai",
@@ -29,7 +55,9 @@
     "llm",
     "cost-control",
     "agent",
-    "firewall"
+    "runtime-safety",
+    "ai-agents",
+    "budget-guard"
   ],
   "author": "Salim Assili",
   "license": "MIT",
@@ -40,7 +68,7 @@
     "rimraf": "^5.0.10",
     "typescript": "^5.3.3"
   },
-  "dependencies": {
+  "optionalDependencies": {
     "ioredis": "^5.10.1"
   }
 }