Merge pull request #6 from Floe-Labs/feat/vercel-ai-sdk

feat: Vercel AI SDK middleware (TypeScript)

Author: achris7

README.md

@@ -133,10 +133,30 @@ llm.invoke("hello")            # checks budget before the call, records spend af
 The handler checks the budget on LLM start (raising `BudgetExceeded` aborts the
 call before it runs) and records token usage on LLM end.
 
-### Coming next
+### Vercel AI SDK
 
-The Vercel AI SDK (TypeScript middleware) is next. Open an issue if you want one
-sooner.
+The Vercel AI SDK is TypeScript-only, so it ships as a separate npm package that
+lives in [`js/`](js/).
+
+```bash
+npm i floe-guard ai@4 @ai-sdk/openai
+```
+
+```ts
+import { wrapLanguageModel } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { BudgetGuard, budgetGuardMiddleware } from "floe-guard";
+
+const guard = new BudgetGuard(5.0);                   // your ceiling, in USD
+const model = wrapLanguageModel({
+  model: openai("gpt-4o"),
+  middleware: budgetGuardMiddleware(guard),           // throws before crossing
+});
+```
+
+The middleware `check()`s before each call (throwing `BudgetExceeded` to halt the
+run) and `record()`s priced usage after — same semantics as the Python guard. See
+[`js/README.md`](js/README.md).
 
 ## Honest about what this is
 

js/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.tsbuildinfo

js/README.md

@@ -0,0 +1,63 @@
+# floe-guard (Vercel AI SDK)
+
+**A local budget guardrail for AI agents** — the TypeScript counterpart to the
+[Python `floe-guard`](../README.md). It hard-stops your agent *before its next LLM
+call* when it would cross a USD spend ceiling. No account, no signup, no network.
+Runs in your process.
+
+```bash
+npm i floe-guard ai@4 @ai-sdk/openai
+```
+
+```ts
+import { wrapLanguageModel } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { BudgetGuard, budgetGuardMiddleware } from "floe-guard";
+
+const guard = new BudgetGuard(5.0); // your ceiling, in USD
+
+const model = wrapLanguageModel({
+  model: openai("gpt-4o"),
+  middleware: budgetGuardMiddleware(guard),
+});
+// generateText / streamText with `model` now stop at $5 — the call that would
+// cross the ceiling throws `BudgetExceeded` BEFORE it runs.
+```
+
+The middleware sits in the call path: it `check()`s before `doGenerate` /
+`doStream` (throwing `BudgetExceeded` to halt the run) and `record()`s priced
+token usage after — for streaming it reads usage from the `finish` part.
+
+## Pricing
+
+Tokens are priced **offline** from a bundled
+[LiteLLM cost map](src/cost_map.json). A model that isn't in the map (and has no
+manual price) **fails closed**: `record` throws `UnpriceableModelError` rather
+than silently treating spend as free — *you can't cap spend you can't measure.*
+
+```ts
+const guard = new BudgetGuard(5.0, {
+  priceOverrides: {
+    "my-self-hosted-model": { inputCostPerToken: 1e-6, outputCostPerToken: 2e-6 },
+  },
+  // or failClosed: false to warn-and-skip for models you accept un-metered.
+});
+```
+
+## Verified against
+
+`ai@4` (`LanguageModelV1Middleware` via `wrapLanguageModel` /
+`experimental_wrapLanguageModel`). Declared as a peer dependency.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run typecheck
+```
+
+## License
+
+MIT — see [../LICENSE](../LICENSE).