@salimassili/ai-costguard 1.2.0 → 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,19 +1,8 @@
 # AI CostGuard
 
-AI CostGuard is a small TypeScript library that wraps OpenAI-like clients and blocks requests before they run when local safety checks predict unsafe AI API spend.
+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.
 
-It is ESM-only, targets Node.js 18+, and is built with `tsc`.
-
-## What Works Today
-
-- `guard()` wraps a client with budget, loop, and retry protection.
-- `GuardError` is thrown when a request is blocked.
-- Budget blocking estimates request cost before the API call.
-- Loop detection blocks repeated prompts within the current process.
-- Retry detection blocks repeated failure/retry prompts within the current process.
-- `middleware()` adds the same local checks to web request flows.
-- `getPricing()` returns known built-in model pricing.
-- `registerPricing()` and `listPricing()` let you manage runtime pricing entries.
+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
 
@@ -21,79 +10,248 @@ It is ESM-only, targets Node.js 18+, and is built with `tsc`.
 npm install @salimassili/ai-costguard
 ```
 
-## Basic Usage
+## Quick Start
 
 ```ts
 import OpenAI from 'openai';
 import { guard, GuardError } from '@salimassili/ai-costguard';
 
-const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
-const ai = guard(client, { budget: 1 });
+const openai = guard(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), {
+  budget: 5,
+  maxSteps: 50,
+  scope: { projectId: 'my-app' },
+});
 
 try {
-  const response = await ai.chat.completions.create({
+  const response = await openai.chat.completions.create({
     model: 'gpt-4o-mini',
-    messages: [{ role: 'user', content: 'Write a short project summary.' }],
-    max_tokens: 200
+    messages: [{ role: 'user', content: 'Write a short summary.' }],
+    max_tokens: 200,
   });
 
-  console.log(response);
+  console.log(response.choices[0]?.message?.content);
 } catch (error) {
   if (error instanceof GuardError) {
-    console.error('AI request blocked:', error.message, error.context);
+    console.error(error.code, error.message, error.context);
   } else {
     throw error;
   }
 }
 ```
 
-## How `guard()` Works
+## What It Guards
+
+By default AI CostGuard evaluates these SDK method paths:
 
-`guard(client, config)` returns a `Proxy` around your client. When code calls a method such as `client.chat.completions.create(...)`, CostGuard:
+- `chat.completions.create`
+- `completions.create`
+- `responses.create`
+- `messages.create`
 
-1. Reads the request model, messages, and `max_tokens`.
-2. Estimates input tokens from message length and combines them with the requested output limit.
-3. Looks up pricing for the model.
-4. Estimates the request cost.
-5. Blocks the call with `GuardError` if the local budget would be exceeded.
-6. Blocks repeated prompts that look like loops.
-7. Blocks repeated prompts that look like retry storms.
-8. Lets the original client method run when checks pass.
+Other client methods are passed through without cost checks. To protect a custom client method:
 
-The free guard state is process-local. Separate Node.js processes do not share budget state.
+```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',
+    },
+  ],
+});
+```
 
-## Budget Blocking
+For function-style SDKs such as Vercel AI SDK adapters, LangChain wrappers, or agent runners:
 
 ```ts
-import { guard } from '@salimassili/ai-costguard';
+import { guardFunction } from '@salimassili/ai-costguard';
 
-const ai = guard(openai, { budget: 0.25 });
+const guardedGenerateText = guardFunction(generateTextAdapter, {
+  budget: 1,
+  scope: { projectId: 'chatbot' },
+});
 
-await ai.chat.completions.create({
+await guardedGenerateText({
   model: 'gpt-4o-mini',
-  messages: [{ role: 'user', content: 'Hello' }],
-  max_tokens: 100
+  prompt: 'Answer the user in one paragraph.',
+  max_tokens: 200,
 });
 ```
 
-When the estimated cumulative spend in the current process would exceed `budget`, CostGuard throws `GuardError` before calling the underlying AI client.
+## Decisions And Errors
+
+Blocked requests throw `GuardError` before the provider method is called.
 
-## Loop And Retry Detection
+```ts
+try {
+  await openai.chat.completions.create(request);
+} catch (error) {
+  if (error instanceof GuardError) {
+    console.log(error.code);
+    console.log(error.metadata);
+  }
+}
+```
 
-CostGuard keeps a short in-memory history of recent prompts for the wrapped client:
+Current runtime block codes:
 
-- Loop detection blocks repeated prompt hashes.
-- Retry detection blocks repeated prompts containing retry/failure language such as `retry`, `again`, `repeat`, `error`, `fail`, or `timeout`.
+- `UNKNOWN_MODEL`
+- `BUDGET_EXCEEDED`
+- `MAX_STEPS_EXCEEDED`
+- `LOOP_DETECTED`
+- `RETRY_STORM_DETECTED`
 
-These checks are intentionally local and lightweight.
+`INVALID_LICENSE` remains in the exported type for compatibility with older callers, but the current Pro helper does not enforce local license checks.
 
-## Middleware
+## Configuration
 
 ```ts
-import express from 'express';
-import { middleware, GuardError } from '@salimassili/ai-costguard';
+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',
+});
+```
+
+`scope` isolates budgets and behavior history. If no scope is supplied, the guard uses one process-local default scope.
+
+## Accounting Semantics
 
-const app = express();
+AI CostGuard is a pre-call estimator, not a billing ledger.
+
+- `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.
+
+## Pricing
+
+Known model pricing comes from built-in registry entries, runtime registrations, or per-guard overrides. Unknown models are blocked by default.
+
+```ts
+import { registerPricing } from '@salimassili/ai-costguard';
+
+registerPricing([
+  {
+    model: 'my-company-model',
+    inputPer1kTokens: 0.001,
+    outputPer1kTokens: 0.002,
+    lastUpdated: '2026-06-07',
+    source: 'internal',
+  },
+]);
+```
+
+If you intentionally want fallback pricing for unknown models:
+
+```ts
+guard(client, {
+  budget: 5,
+  unknownModelPolicy: 'fallback',
+  unknownModelPricing: {
+    model: 'fallback',
+    inputPer1kTokens: 0.001,
+    outputPer1kTokens: 0.002,
+    lastUpdated: '2026-06-07',
+    source: 'application fallback',
+  },
+});
+```
+
+Pricing changes frequently. Verify provider pricing before production use and override entries when needed.
+
+## Events
+
+```ts
+const unsubscribe = openai.on('block', (event) => {
+  console.log(event.code, event.reason, event.context.estimatedCost);
+});
+
+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:
+
+```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:
+
+```bash
+ai-costguard dashboard --events .ai-costguard/events.jsonl --budget 5 --once --json
+```
+
+See `docs/DASHBOARD.md`.
+
+## Integrations
+
+Runnable mocked examples are included for:
+
+- 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
+
+See `docs/INTEGRATIONS.md` and `examples/integrations`.
+
+## Express Middleware
+
+The middleware attaches a manual checker. It does not automatically parse or inspect every route.
+
+```ts
+import { middleware, GuardError } from '@salimassili/ai-costguard';
 
 app.use(middleware({ budget: 2 }));
 
@@ -101,101 +259,121 @@ app.post('/chat', async (req, res, next) => {
   try {
     req.localSafety.check({
       model: 'gpt-4o-mini',
-      tokens: 1000,
-      estimatedCost: 0.001,
+      tokens: 500,
+      inputTokens: 100,
+      outputTokens: 400,
+      estimatedCost: 0.0003,
       timestamp: Date.now(),
-      prompt: req.body?.prompt ?? ''
+      prompt: String(req.body?.prompt ?? ''),
     });
 
     res.json({ ok: true });
   } catch (error) {
     if (error instanceof GuardError) {
-      res.status(402).json({ error: error.message, context: error.context });
+      res.status(403).json({ code: error.code, reason: error.message });
       return;
     }
-
     next(error);
   }
 });
 ```
 
-## Pricing
+## Optional Redis / Pro Helper
 
-```ts
-import { getPricing, listPricing, registerPricing } from '@salimassili/ai-costguard';
+Redis-backed shared spend tracking is isolated behind a subpath import:
 
-console.log(getPricing('gpt-4o-mini'));
+```ts
+import { GuardPro } from '@salimassili/ai-costguard/pro';
 
-registerPricing([
-  {
-    model: 'custom-model',
-    inputPer1kTokens: 0.001,
-    outputPer1kTokens: 0.002,
-    lastUpdated: '2026-05-21',
-    source: 'internal'
-  }
-]);
+const pro = new GuardPro({
+  redisUrl: process.env.REDIS_URL ?? '',
+  budget: 25,
+  windowSeconds: 86400,
+});
 
-console.log(listPricing());
+await pro.checkAndCharge('production', 0.0042);
+await pro.shutdown();
 ```
 
-`getPricing(model)` returns an exact match when available, then falls back to simple fuzzy matching. Unknown models return `undefined`.
+`ioredis` is an optional dependency and is not loaded by the root import.
 
-## Pro Features (Coming Soon)
+`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.
 
-> These features are under active development and not yet available:
-> - Distributed Redis-backed budget state
-> - Real Slack/Discord webhook alerts
-> - Multi-instance coordination
-> - Production license validation
+## CLI
 
-## API
+```bash
+aifw check --budget 1 --model gpt-4o-mini --input-tokens 500 --tokens 1000 --max-steps 5
+```
 
-### `guard(client, config)`
+The package also installs an `ai-costguard` bin alias:
 
-Wraps an OpenAI-like client.
+```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
+```
 
-```ts
-guard(client, { budget: 10 });
+For custom models:
+
+```bash
+aifw check --budget 1 --model internal-model --tokens 1000 --input-price-per-1k 0.001 --output-price-per-1k 0.002
 ```
 
-### `GuardError`
+Exit codes:
 
-Thrown when CostGuard blocks a request.
+- `0`: projected cost is within budget
+- `1`: projected cost exceeds budget
+- `2`: usage/config error
 
-```ts
-try {
-  await ai.chat.completions.create(params);
-} catch (error) {
-  if (error instanceof GuardError) {
-    console.log(error.context);
-  }
-}
-```
+## Benchmarks
+
+Run local benchmarks:
 
-### `middleware(config)`
+```bash
+npm run build
+npm run benchmark
+```
 
-Creates request middleware with local budget, loop, and retry checks.
+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`.
 
-### `getPricing(model, overrides?)`
+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.
 
-Returns pricing for a model from overrides, runtime registrations, or built-in entries.
+## Why Not 50 Lines Of Code?
 
-### `registerPricing(entries)`
+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:
 
-Registers or replaces runtime pricing entries by model name.
+- 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.
 
-### `listPricing()`
+## Development
 
-Returns built-in and runtime pricing entries, deduplicated by model name.
+```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
+```
 
 ## Limitations
 
-- Free guard state is stored in memory only.
-- Budget checks are estimates, not billing records.
-- Token estimation is approximate.
-- Pricing entries are static until the package or runtime registry is updated.
-- The library does not include dashboards, analytics, governance workflows, or hosted services.
+- 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