@salimassili/ai-costguard 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/CHANGELOG.md +59 -50
  2. package/LICENSE +21 -21
  3. package/README.md +399 -339
  4. package/benchmarks/run.mjs +229 -229
  5. package/benchmarks/token-accuracy.mjs +86 -0
  6. package/dist/core/CostGuard.d.ts +1 -1
  7. package/dist/core/CostGuard.d.ts.map +1 -1
  8. package/dist/core/CostGuard.js +1 -1
  9. package/dist/core/CostGuard.js.map +1 -1
  10. package/dist/core/GuardPro.d.ts +1 -13
  11. package/dist/core/GuardPro.d.ts.map +1 -1
  12. package/dist/core/GuardPro.js +7 -19
  13. package/dist/core/GuardPro.js.map +1 -1
  14. package/dist/core/types.d.ts +1 -3
  15. package/dist/core/types.d.ts.map +1 -1
  16. package/dist/dashboard.js +49 -49
  17. package/dist/index.d.ts +1 -1
  18. package/dist/index.d.ts.map +1 -1
  19. package/dist/index.js +1 -1
  20. package/dist/index.js.map +1 -1
  21. package/dist/pricing/index.d.ts +7 -0
  22. package/dist/pricing/index.d.ts.map +1 -1
  23. package/dist/pricing/index.js +7 -0
  24. package/dist/pricing/index.js.map +1 -1
  25. package/dist/pro.d.ts +1 -1
  26. package/dist/pro.d.ts.map +1 -1
  27. package/dist/pro.js +1 -1
  28. package/dist/pro.js.map +1 -1
  29. package/docs/BENCHMARKS.md +60 -41
  30. package/docs/DASHBOARD.md +61 -61
  31. package/docs/INTEGRATIONS.md +153 -153
  32. package/examples/integrations/anthropic-workflow-budget.mjs +36 -36
  33. package/examples/integrations/ci-budget-check.mjs +32 -32
  34. package/examples/integrations/crewai-budget-gate.mjs +31 -31
  35. package/examples/integrations/langchain-retry-storm.mjs +32 -32
  36. package/examples/integrations/mastra-agent.mjs +41 -41
  37. package/examples/integrations/openai-agent-loop.mjs +44 -44
  38. package/examples/integrations/vercel-ai-chatbot.mjs +29 -29
  39. package/package.json +71 -69
package/CHANGELOG.md CHANGED
@@ -1,53 +1,62 @@
1
- # Changelog
2
-
3
- ## 2.0.0 - Unreleased
1
+ # Changelog
2
+
3
+ ## 2.0.1 - Unreleased
4
4
 
5
5
  ### Changed
6
6
 
7
- - Moved Redis-backed `GuardPro` exports to `@salimassili/ai-costguard/pro` so the root import stays lightweight.
8
- - Removed fake local license enforcement from `GuardPro`; `licenseKey` and `validateLicense()` are compatibility helpers only.
9
- - Unknown models now block by default unless runtime pricing, guard pricing overrides, or explicit fallback pricing is configured.
10
- - Guard proxy now checks known AI SDK method paths instead of charging every function call on the wrapped client.
11
- - Loop detection now requires repeated similar prompts in the same scope before blocking.
12
- - Retry detection now requires stronger retry/failure signals to reduce false positives.
13
- - Prompt and retry histories are scoped and TTL-bound.
14
-
15
- ### Added
16
-
17
- - `guardFunction()` for Vercel AI SDK, LangChain, Mastra-style, CrewAI launcher, and other function-style integrations.
18
- - Local JSONL event logging and `ai-costguard dashboard` / `aifw dashboard` for local-only visibility.
19
- - Mocked runnable integration examples for OpenAI, Anthropic, Vercel AI SDK, LangChain, Mastra, CrewAI, and CI checks.
20
- - Local benchmark script and benchmark documentation.
21
- - Structured `GuardError.code` and `GuardError.metadata`.
22
- - Scoped accounting fields for attempted, allowed, blocked, and reconciled actual cost.
23
- - CLI custom pricing flags for private/custom models.
24
- - `/pricing` package subpath export.
25
- - Repository smoke checks for examples, templates, package exports, and stale claims.
26
-
27
- ### Removed
28
-
29
- - Active root docs and templates for unimplemented proxy/dashboard/SaaS features.
30
- - Unused postinstall helper, stale ESLint config, and stale npm ignore file.
31
-
32
- ## 1.2.0 - 2026-05-28
33
-
34
- ### Changed
35
-
36
- - Rebuilt the package around a strict ESM TypeScript core.
37
- - Replaced the old character-count token heuristic with an inline BPE-style estimator.
38
- - Replaced exact prompt matching with character trigram cosine similarity loop detection at the default `0.85` threshold.
39
- - Reworked `GuardPro` with pooled Redis connections, TTL-based spend windows, and local fallback when Redis is unavailable.
40
- - Rewrote the README to describe only shipped behavior.
41
-
42
- ### Added
43
-
44
- - `guard.on('block' | 'allow' | 'cost', callback)` event hooks.
45
- - Optional Slack and Discord block webhooks with exponential backoff and silent failure.
46
- - `aifw check --budget --model --tokens --max-steps` CLI for CI budget checks.
47
- - Stale pricing warnings for entries older than 30 days.
48
- - Node-native unit and integration tests for GuardCore, GuardFree, GuardPro, middleware, pricing, token estimation, webhooks, and CLI behavior.
49
-
50
- ### Removed
51
-
52
- - Removed stale Jest configuration and CommonJS-era test setup.
53
- - Removed README claims about dashboards, hosted monitoring, and proxy features that are not shipped in this package.
7
+ - Removed `licenseKey`, `validateLicense`, and `INVALID_LICENSE` compatibility surfaces. AI CostGuard does not contain license-key checks or local commercial-license enforcement.
8
+ - Added explicit built-in pricing freshness notice: `2026-06-07`.
9
+ - Added README loop detection tuning guidance and trust sections.
10
+ - Added token accuracy benchmark documentation showing the estimator materially overestimates the fixed corpus.
11
+
12
+ ## 2.0.0 - 2026-06-08
13
+
14
+ ### Changed
15
+
16
+ - Moved Redis-backed `GuardPro` exports to `@salimassili/ai-costguard/pro` so the root import stays lightweight.
17
+ - Removed fake local license enforcement from `GuardPro`.
18
+ - Unknown models now block by default unless runtime pricing, guard pricing overrides, or explicit fallback pricing is configured.
19
+ - Guard proxy now checks known AI SDK method paths instead of charging every function call on the wrapped client.
20
+ - Loop detection now requires repeated similar prompts in the same scope before blocking.
21
+ - Retry detection now requires stronger retry/failure signals to reduce false positives.
22
+ - Prompt and retry histories are scoped and TTL-bound.
23
+
24
+ ### Added
25
+
26
+ - `guardFunction()` for Vercel AI SDK, LangChain, Mastra-style, CrewAI launcher, and other function-style integrations.
27
+ - Local JSONL event logging and `ai-costguard dashboard` / `aifw dashboard` for local-only visibility.
28
+ - Mocked runnable integration examples for OpenAI, Anthropic, Vercel AI SDK, LangChain, Mastra, CrewAI, and CI checks.
29
+ - Local benchmark script and benchmark documentation.
30
+ - Structured `GuardError.code` and `GuardError.metadata`.
31
+ - Scoped accounting fields for attempted, allowed, blocked, and reconciled actual cost.
32
+ - CLI custom pricing flags for private/custom models.
33
+ - `/pricing` package subpath export.
34
+ - Repository smoke checks for examples, templates, package exports, and stale claims.
35
+
36
+ ### Removed
37
+
38
+ - Active root docs and templates for unimplemented proxy/dashboard/SaaS features.
39
+ - Unused postinstall helper, stale ESLint config, and stale npm ignore file.
40
+
41
+ ## 1.2.0 - 2026-05-28
42
+
43
+ ### Changed
44
+
45
+ - Rebuilt the package around a strict ESM TypeScript core.
46
+ - Replaced the old character-count token heuristic with an inline BPE-style estimator.
47
+ - Replaced exact prompt matching with character trigram cosine similarity loop detection at the default `0.85` threshold.
48
+ - Reworked `GuardPro` with pooled Redis connections, TTL-based spend windows, and local fallback when Redis is unavailable.
49
+ - Rewrote the README to describe only shipped behavior.
50
+
51
+ ### Added
52
+
53
+ - `guard.on('block' | 'allow' | 'cost', callback)` event hooks.
54
+ - Optional Slack and Discord block webhooks with exponential backoff and silent failure.
55
+ - `aifw check --budget --model --tokens --max-steps` CLI for CI budget checks.
56
+ - Stale pricing warnings for entries older than 30 days.
57
+ - Node-native unit and integration tests for GuardCore, GuardFree, GuardPro, middleware, pricing, token estimation, webhooks, and CLI behavior.
58
+
59
+ ### Removed
60
+
61
+ - Removed stale Jest configuration and CommonJS-era test setup.
62
+ - Removed README claims about dashboards, hosted monitoring, and proxy features that are not shipped in this package.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Salim Assili
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Salim Assili
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.