@salimassili/ai-costguard 1.1.9 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+## 2.0.0 - Unreleased
+
+### Changed
+
+- Moved Redis-backed `GuardPro` exports to `@salimassili/ai-costguard/pro` so the root import stays lightweight.
+- Removed fake local license enforcement from `GuardPro`; `licenseKey` and `validateLicense()` are compatibility helpers only.
+- Unknown models now block by default unless runtime pricing, guard pricing overrides, or explicit fallback pricing is configured.
+- Guard proxy now checks known AI SDK method paths instead of charging every function call on the wrapped client.
+- Loop detection now requires repeated similar prompts in the same scope before blocking.
+- Retry detection now requires stronger retry/failure signals to reduce false positives.
+- Prompt and retry histories are scoped and TTL-bound.
+
+### Added
+
+- `guardFunction()` for Vercel AI SDK, LangChain, Mastra-style, CrewAI launcher, and other function-style integrations.
+- Local JSONL event logging and `ai-costguard dashboard` / `aifw dashboard` for local-only visibility.
+- Mocked runnable integration examples for OpenAI, Anthropic, Vercel AI SDK, LangChain, Mastra, CrewAI, and CI checks.
+- Local benchmark script and benchmark documentation.
+- Structured `GuardError.code` and `GuardError.metadata`.
+- Scoped accounting fields for attempted, allowed, blocked, and reconciled actual cost.
+- CLI custom pricing flags for private/custom models.
+- `/pricing` package subpath export.
+- Repository smoke checks for examples, templates, package exports, and stale claims.
+
+### Removed
+
+- Active root docs and templates for unimplemented proxy/dashboard/SaaS features.
+- Unused postinstall helper, stale ESLint config, and stale npm ignore file.
+
+## 1.2.0 - 2026-05-28
+
+### Changed
+
+- Rebuilt the package around a strict ESM TypeScript core.
+- Replaced the old character-count token heuristic with an inline BPE-style estimator.
+- Replaced exact prompt matching with character trigram cosine similarity loop detection at the default `0.85` threshold.
+- Reworked `GuardPro` with pooled Redis connections, TTL-based spend windows, and local fallback when Redis is unavailable.
+- Rewrote the README to describe only shipped behavior.
+
+### Added
+
+- `guard.on('block' | 'allow' | 'cost', callback)` event hooks.
+- Optional Slack and Discord block webhooks with exponential backoff and silent failure.
+- `aifw check --budget --model --tokens --max-steps` CLI for CI budget checks.
+- Stale pricing warnings for entries older than 30 days.
+- Node-native unit and integration tests for GuardCore, GuardFree, GuardPro, middleware, pricing, token estimation, webhooks, and CLI behavior.
+
+### Removed
+
+- Removed stale Jest configuration and CommonJS-era test setup.
+- Removed README claims about dashboards, hosted monitoring, and proxy features that are not shipped in this package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Salim Assili
+
+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

@@ -1,233 +1,380 @@
-# AI CostGuard - Smoke Detector + Circuit Breaker for AI Agents
+# AI CostGuard
 
-**"Smoke detector + circuit breaker for AI systems."**
+AI CostGuard is a local-first runtime safety layer for AI agents that prevents runaway costs, loops, retries, and budget explosions before API calls execute. It wraps OpenAI-compatible clients and function-style SDK calls, estimates request cost locally, blocks budget overruns, detects repeated prompts, emits structured events, and exposes CLI checks plus a local dashboard.
 
-Install in 60 seconds. Save thousands from catastrophic AI disasters.
+It is local-first. It does not include a SaaS control plane, cloud dashboard, proxy gateway, telemetry service, billing reconciliation service, or hard security boundary.
 
----
+## Install
 
-## 🚨 CATASTROPHIC INCIDENT
+```bash
+npm install @salimassili/ai-costguard
+```
 
-**AI agent entered infinite retry loop. Started burning $3,000/hour. Free version didn't stop it. Company lost $24,000 overnight.**
+## Quick Start
 
----
+```ts
+import OpenAI from 'openai';
+import { guard, GuardError } from '@salimassili/ai-costguard';
 
-## 🛑 SOLUTION
+const openai = guard(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
+  budget: 5,
+  maxSteps: 50,
+  scope: { projectId: 'my-app' },
+});
 
-**Emergency brake for AI agents.**
+try {
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4o-mini',
+    messages: [{ role: 'user', content: 'Write a short summary.' }],
+    max_tokens: 200,
+  });
+
+  console.log(response.choices[0]?.message?.content);
+} catch (error) {
+  if (error instanceof GuardError) {
+    console.error(error.code, error.message, error.context);
+  } else {
+    throw error;
+  }
+}
+```
 
----
+## What It Guards
 
-## 🟦 FREE VERSION - SMOKE DETECTOR
+By default AI CostGuard evaluates these SDK method paths:
 
-**Smoke detector for development.**
+- `chat.completions.create`
+- `completions.create`
+- `responses.create`
+- `messages.create`
 
-```ts
-import { guard } from '@salimassili/ai-costguard';
+Other client methods are passed through without cost checks. To protect a custom client method:
 
-const ai = guard(openai); // One line magic
+```ts
+const client = guard(customClient, {
+  budget: 2,
+  guardedMethods: ['agent.run'],
+  pricingOverrides: [
+    {
+      model: 'internal-model',
+      inputPer1kTokens: 0.001,
+      outputPer1kTokens: 0.002,
+      lastUpdated: '2026-06-07',
+      source: 'internal pricing sheet',
+    },
+  ],
+});
 ```
 
-**What it detects:**
-- Hard budget limits
-- Infinite loops (2x repetition)
-- Retry storms (1x failure pattern)
-- Token explosions (20x spikes)
+For function-style SDKs such as Vercel AI SDK adapters, LangChain wrappers, or agent runners:
 
-**Output:**
-```
-🚨 SMOKE DETECTOR: Infinite loop → saved $18.42
-```
+```ts
+import { guardFunction } from '@salimassili/ai-costguard';
 
-**WARNING:** Single process only. Not production safe.
+const guardedGenerateText = guardFunction(generateTextAdapter, {
+  budget: 1,
+  scope: { projectId: 'chatbot' },
+});
 
----
+await guardedGenerateText({
+  model: 'gpt-4o-mini',
+  prompt: 'Answer the user in one paragraph.',
+  max_tokens: 200,
+});
+```
 
-## 🟥 PAID VERSION - CIRCUIT BREAKER
+## Decisions And Errors
 
-**Circuit breaker that saves companies thousands.**
+Blocked requests throw `GuardError` before the provider method is called.
 
 ```ts
-import { getProGuard } from '@salimassili/ai-costguard';
+try {
+  await openai.chat.completions.create(request);
+} catch (error) {
+  if (error instanceof GuardError) {
+    console.log(error.code);
+    console.log(error.metadata);
+  }
+}
+```
 
-const breaker = getProGuard("LICENSE_KEY", {
-  slack: { webhook: "webhook_url", channel: "#alerts" }
-});
+Current runtime block codes:
 
-breaker.activateCircuitBreaker({
-  projectId: "production", 
-  budget: 5000
-});
+- `UNKNOWN_MODEL`
+- `BUDGET_EXCEEDED`
+- `MAX_STEPS_EXCEEDED`
+- `LOOP_DETECTED`
+- `RETRY_STORM_DETECTED`
 
-breaker.panicShutdown("production"); // Panic button
-```
+`INVALID_LICENSE` remains in the exported type for compatibility with older callers, but the current Pro helper does not enforce local license checks.
 
-**What it saves:**
-- Hard global budget limits (cross-instance)
-- Instant emergency shutdown
-- Global usage caps
-- Real-time spend tracking
-- Slack/Discord panic alerts
-- Distributed coordination (2-second sync)
-- Simple policy rules
+## Configuration
 
----
+```ts
+guard(client, {
+  budget: 10,
+  maxSteps: 100,
+  behaviorAnalysis: true,
+  maxHistory: 32,
+  historyTtlMs: 5 * 60 * 1000,
+  loopSimilarityThreshold: 0.85,
+  loopMinRepeats: 2,
+  retryThreshold: 2,
+  scope: {
+    projectId: 'production-api',
+    userId: 'optional-user',
+    sessionId: 'optional-agent-run',
+  },
+  guardedMethods: ['chat.completions.create', 'responses.create'],
+  pricingOverrides: [],
+  webhooks: {
+    slack: process.env.SLACK_WEBHOOK,
+    discord: process.env.DISCORD_WEBHOOK,
+    retries: 2,
+    timeoutMs: 1500,
+  },
+  eventLogPath: '.ai-costguard/events.jsonl',
+  eventLogPrompt: 'none',
+});
+```
 
-## 💥 TERRIFYING DEMO
+`scope` isolates budgets and behavior history. If no scope is supplied, the guard uses one process-local default scope.
 
-**Scenario:** AI agent processing user data goes into infinite retry loop.
+## Accounting Semantics
 
-**Free version:** Each server thinks it's fine. Cost explodes to $15,000/hour.
+AI CostGuard is a pre-call estimator, not a billing ledger.
 
-**Paid version:** Circuit breaker detects pattern across all servers. Panic shutdown activated in 8 seconds. Company saves $12,000.
+- `attemptedCost`: estimated cost of every guarded attempt, including blocked attempts.
+- `totalCost`: estimated cost of allowed calls.
+- `blockedCost`: estimated cost stopped before provider execution.
+- `actualCost`: provider-reported usage cost when the response includes recognizable `usage` fields.
 
----
+Budget decisions use estimated allowed cost. Actual usage is recorded for observability but does not rewrite earlier decisions.
 
-## 🚀 60-SECOND MAGICAL INSTALLATION
+## Pricing
 
-```bash
-npm install @salimassili/ai-costguard
-```
+Known model pricing comes from built-in registry entries, runtime registrations, or per-guard overrides. Unknown models are blocked by default.
 
-### Development (FREE)
 ```ts
-import { guard } from '@salimassili/ai-costguard';
-import OpenAI from 'openai';
+import { registerPricing } from '@salimassili/ai-costguard';
+
+registerPricing([
+  {
+    model: 'my-company-model',
+    inputPer1kTokens: 0.001,
+    outputPer1kTokens: 0.002,
+    lastUpdated: '2026-06-07',
+    source: 'internal',
+  },
+]);
+```
 
-const ai = guard(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
+If you intentionally want fallback pricing for unknown models:
 
-// Your AI code works normally, but protected
-const response = await ai.chat.completions.create({
-  model: 'gpt-4',
-  messages: [{ role: 'user', content: 'Hello' }]
+```ts
+guard(client, {
+  budget: 5,
+  unknownModelPolicy: 'fallback',
+  unknownModelPricing: {
+    model: 'fallback',
+    inputPer1kTokens: 0.001,
+    outputPer1kTokens: 0.002,
+    lastUpdated: '2026-06-07',
+    source: 'application fallback',
+  },
 });
 ```
 
-### Production (PAID)
-```ts
-import { getProGuard } from '@salimassili/ai-costguard';
+Pricing changes frequently. Verify provider pricing before production use and override entries when needed.
 
-// Activate circuit breaker
-const breaker = getProGuard(process.env.COSTGUARD_LICENSE, {
-  slack: { webhook: process.env.SLACK_WEBHOOK, channel: "#ai-alerts" }
+## Events
+
+```ts
+const unsubscribe = openai.on('block', (event) => {
+  console.log(event.code, event.reason, event.context.estimatedCost);
 });
 
-breaker.activateCircuitBreaker({
-  projectId: "production",
-  budget: 10000
+unsubscribe();
+```
+
+Supported events are `cost`, `allow`, and `block`. Handler errors are swallowed so observability code cannot change guard decisions.
+
+## Local Dashboard
+
+Opt into a local JSONL event log:
+
+```ts
+const openai = guard(client, {
+  budget: 5,
+  eventLogPath: '.ai-costguard/events.jsonl',
 });
+```
+
+Start the local-only dashboard:
 
-// Your AI code is now circuit-protected
+```bash
+ai-costguard dashboard --events .ai-costguard/events.jsonl --budget 5
+```
+
+For one-off package execution:
+
+```bash
+npx @salimassili/ai-costguard dashboard --events .ai-costguard/events.jsonl --budget 5
 ```
 
----
+If the package is installed locally, `npx ai-costguard dashboard` also works. The dashboard binds to `127.0.0.1` by default and reads only local event files.
+
+For CI or terminal output:
 
-## 🎯 TARGET USERS
+```bash
+ai-costguard dashboard --events .ai-costguard/events.jsonl --budget 5 --once --json
+```
 
-- **AI agent startups** - Can't afford $10k mistakes
-- **Founders using OpenAI/Claude in production** - Need sleep at night
-- **Teams running autonomous workflows** - Multiple instances, high risk
-- **Companies spending $1k+/month on AI APIs** - High exposure
+See `docs/DASHBOARD.md`.
 
----
+## Integrations
 
-## 💰 ROI
+Runnable mocked examples are included for:
 
-**Free:** Saves $100s in development, proves value immediately
-**Paid:** Prevents $5,000-$50,000 production disasters
+- OpenAI SDK agent loop protection
+- Anthropic SDK workflow budget guard
+- Vercel AI SDK chatbot budget cap
+- LangChain retry-storm prevention
+- Mastra-style agent runner protection
+- CrewAI launch/budget gate
+- CI budget checks
 
-**Question:** Can you afford NOT to have this installed?
+See `docs/INTEGRATIONS.md` and `examples/integrations`.
 
----
+## Express Middleware
 
-## 🔧 CORE FEATURES (ONLY 10)
+The middleware attaches a manual checker. It does not automatically parse or inspect every route.
 
-1. **Hard global budget limits** - Stop spending instantly
-2. **Instant kill switch** - Emergency shutdown button
-3. **Infinite loop detection** - Stop runaway agents
-4. **Retry storm detection** - Kill retry explosions
-5. **Token explosion detection** - Prevent cost spikes
-6. **Emergency execution shutdown** - Panic button for all instances
-7. **Global usage caps** - Cross-instance coordination
-8. **Slack/Discord panic alerts** - Real-time emergency notifications
-9. **Real-time spend tracking** - Live monitoring
-10. **Simple policy rules** - Configurable thresholds
+```ts
+import { middleware, GuardError } from '@salimassili/ai-costguard';
+
+app.use(middleware({ budget: 2 }));
+
+app.post('/chat', async (req, res, next) => {
+  try {
+    req.localSafety.check({
+      model: 'gpt-4o-mini',
+      tokens: 500,
+      inputTokens: 100,
+      outputTokens: 400,
+      estimatedCost: 0.0003,
+      timestamp: Date.now(),
+      prompt: String(req.body?.prompt ?? ''),
+    });
+
+    res.json({ ok: true });
+  } catch (error) {
+    if (error instanceof GuardError) {
+      res.status(403).json({ code: error.code, reason: error.message });
+      return;
+    }
+    next(error);
+  }
+});
+```
 
----
+## Optional Redis / Pro Helper
 
-## 🛠️ TECH STACK
+Redis-backed shared spend tracking is isolated behind a subpath import:
 
-- **TypeScript-first** - Full type safety
-- **Redis-ready** - Distributed state management
-- **Proxy-based** - Zero integration overhead
-- **OpenAI + Anthropic** - Major providers supported
-- **Minimal dependencies** - Lightweight, secure
-- **Serverless-friendly** - Works anywhere
-- **Production-ready** - Battle tested
+```ts
+import { GuardPro } from '@salimassili/ai-costguard/pro';
 
----
+const pro = new GuardPro({
+  redisUrl: process.env.REDIS_URL ?? '',
+  budget: 25,
+  windowSeconds: 86400,
+});
 
-## 🚫 WHAT WE DON'T DO
+await pro.checkAndCharge('production', 0.0042);
+await pro.shutdown();
+```
 
-❌ No dashboards  
-❌ No analytics  
-❌ No enterprise complexity  
-❌ No governance systems  
-❌ No features nobody pays for  
+`ioredis` is an optional dependency and is not loaded by the root import.
 
-**We do ONE thing: Prevent catastrophic AI cost disasters.**
+`licenseKey` is accepted as a deprecated compatibility field only. AI CostGuard does not enforce commercial licenses locally, and `validateLicense()` is a format sanity helper, not security.
 
----
+## CLI
 
-## 🎯 POSITIONING
+```bash
+aifw check --budget 1 --model gpt-4o-mini --input-tokens 500 --tokens 1000 --max-steps 5
+```
 
-**"Every production AI system should have this installed."**
+The package also installs an `ai-costguard` bin alias:
 
-**This is not a tool. This is insurance.**
+```bash
+ai-costguard check --budget 1 --model gpt-4o-mini --tokens 1000 --max-steps 5
+ai-costguard dashboard --events .ai-costguard/events.jsonl --budget 5
+```
 
----
+For custom models:
 
-## 💥 MARKETING STORIES
+```bash
+aifw check --budget 1 --model internal-model --tokens 1000 --input-price-per-1k 0.001 --output-price-per-1k 0.002
+```
 
-### Story 1: The $15,000 Mistake
-"AI agent processing customer feedback entered infinite retry loop. Free version on each server thought everything was fine. Cost exploded to $15,000/hour. Circuit breaker killed all instances in 8 seconds. Company saved $12,000."
+Exit codes:
 
-### Story 2: The $3,000 Overnight Bill
-"Background job processing user data got stuck in recursive tool calls. Each server kept retrying independently. Free version didn't coordinate across instances. Paid version detected global pattern and panic shutdown. Saved $3,000."
+- `0`: projected cost is within budget
+- `1`: projected cost exceeds budget
+- `2`: usage/config error
 
-### Story 3: The $50,000 Disaster
-"Autonomous workflow system went into runaway execution chain. 12 servers burning $4,000/hour each. Circuit breaker detected anomaly across all instances and emergency shutdown. Prevented $50,000 disaster."
+## Benchmarks
 
----
+Run local benchmarks:
 
-## 🏆 TRUST MOAT
+```bash
+npm run build
+npm run benchmark
+```
 
-**Why companies can't replace this:**
+The script reports runtime overhead, approximate heap delta, false-positive scenarios, loop detection behavior, and cost-estimation boundaries. Results are local measurements, not universal guarantees. See `docs/BENCHMARKS.md`.
 
-✅ **Reliability** - Works when everything else fails  
-✅ **Trust** - Saves companies thousands, proves value instantly  
-✅ **Integration** - One-line installation, zero overhead  
-✅ **Emergency response** - Panic button works in seconds  
-✅ **Distributed coordination** - Handles multi-instance disasters  
+Latest local benchmark in this repo on Node `v24.14.1` / Windows measured `0.020691 ms` added per mocked guarded call over `5000` iterations. Re-run on your target runtime before using this number in performance-sensitive claims.
 
-**Not because of complexity, but because it's the reliable emergency brake for AI agents.**
+## Why Not 50 Lines Of Code?
 
----
+A simple homemade budget check can stop one request after one counter crosses one number. AI CostGuard packages the parts that usually become messy once agents enter production:
 
-## 🚀 PATH TO $5K+ MRR
+- Provider pricing registry with runtime overrides and unknown-model blocking.
+- Structured `GuardError` codes and metadata for API responses.
+- Scoped budget and behavior state per project, user, or session.
+- TTL-bounded prompt history.
+- Loop and retry-storm detection.
+- Estimated, attempted, blocked, and actual usage accounting.
+- Method filtering so non-AI SDK calls are not charged.
+- Event hooks, best-effort webhooks, JSONL event logs, and local dashboard visibility.
+- CI budget checks and runnable integration examples.
 
-1. **Free version drives viral adoption** - Developers install in 60 seconds
-2. **Production incidents create urgency** - Real disasters create immediate need
-3. **Paid version becomes unavoidable** - Can't safely run AI in production without it
-4. **Emergency alerts prove value** - Slack notifications save thousands
-5. **Trust creates lock-in** - Reliable circuit breaker becomes infrastructure
+## Development
 
----
+```bash
+npm ci
+npm run build
+npm run typecheck
+npm test
+npm run smoke
+npm run benchmark
+npm audit --omit=dev
+npm pack --dry-run
+```
 
-## 🎯 FINAL PHILOSOPHY
+## Limitations
 
-**"If this is not installed, your AI infrastructure is financially unsafe."**
+- Token counting is approximate and dependency-free.
+- Pricing entries can become stale; override them for production.
+- The free guard is process-local.
+- Loop detection uses character trigram similarity, not embeddings.
+- Retry detection is heuristic.
+- Webhooks are best-effort and never affect enforcement.
+- The dashboard reads local JSONL logs only; it is not a hosted analytics product.
+- Provider usage reconciliation only works when responses expose recognizable `usage` fields.
 
----
+## License
 
-MIT | [GitHub](https://github.com/salimassili62-afk/ai-costguard)
+MIT