vibezcheck 0.5.9 → 0.5.11

package/README.md

@@ -1,241 +1,646 @@
 # ✦ VibezCheck
 
-> **Track AI token spend and bill users in real time. Setup in 1 line.**  
-> No database needed. No added latency.
+Know what every AI request costs.  
+The cost layer for AI applications.
 
-[![npm version](https://img.shields.io/npm/v/vibezcheck.svg?color=cb3837)](https://npmjs.org/package/vibezcheck)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://www.typescriptlang.org/)
-[![Tests](https://img.shields.io/badge/Tests-95%20Passed-brightgreen.svg)]()
-[![Latency](https://img.shields.io/badge/Latency-0ms%20Added-orange.svg)]()
+VibezCheck measures AI usage in real dollars — per request, customer, feature, model, or agent session.
+
+```text
+AI request → tokens → provider cost → customer economics
+```
+
+```bash
+npm install vibezcheck
+```
+
+---
+
+## Why VibezCheck?
+
+Tokens are useful for engineers.  
+Dollars are useful for businesses.
+
+AI providers bill you in tokens.
+
+Your users buy:
+- messages
+- documents
+- agent runs
+- API calls
+- credits
+- subscriptions
+
+VibezCheck connects the two.
+
+```text
+What your user does
+       ↓
+   AI usage
+       ↓
+ Provider cost
+       ↓
+Customer economics
+```
+
+Without a metering layer, you know what your users are doing — but not necessarily what each action costs you.
+
+---
+
+## ⚡ Quick Start
+
+### Vercel AI SDK
+
+Wrap an existing model:
+
+```typescript
+import { streamText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { vibezcheck } from 'vibezcheck';
+
+const result = streamText({
+  model: vibezcheck(openai('gpt-4o-mini'), {
+    customer: 'user_123',
+    maxCostPerCallUSD: 0.50,
+  }),
+  prompt: 'Summarize quantum computing in three sentences.',
+});
+```
+
+That's it.
+
+VibezCheck can now calculate the request's usage and provider cost while the request runs.
+
+**Example:**
+> `✦ $0.0028 · 1,420 tok · gpt-4o-mini`
+
+- No VibezCheck proxy.
+- No required database.
+- No required cloud account.
+
+---
+
+## 💰 Measure
+
+VibezCheck gives your application an economic view of AI usage.
+
+### Request cost
+
+```typescript
+const cost = vibezcheck.calculateCost('gpt-4o-mini', {
+  promptTokens: 1240,
+  completionTokens: 150,
+});
+console.log(cost.totalUSD);
+// 0.000276
+```
+
+### Customer attribution
+
+```typescript
+const model = vibezcheck(openai('gpt-4o-mini'), {
+  customer: 'user_123',
+  threadId: 'thread_456',
+  metadata: {
+    plan: 'pro',
+    feature: 'document-analysis',
+  },
+});
+```
+
+Track usage by:
+- customer
+- organization
+- feature
+- thread
+- model
+- agent session
+
+---
+
+## 🛡️ Control
+
+AI agents can make multiple calls before a workflow finishes.  
+Put a ceiling on them.
+
+### Per-request limits
+
+```typescript
+const model = vibezcheck(openai('gpt-4o-mini'), {
+  maxCostPerCallUSD: 0.25,
+  maxTokensPerCall: 4000,
+});
+```
+
+### Agent session budgets
+
+```typescript
+const session = vibezcheck.session({
+  customer: 'tenant_123',
+  sessionBudgetUSD: 2.00,
+});
+```
+
+The entire workflow gets a hard spending ceiling.
+
+### Tool costs
+
+```typescript
+const tools = session.tools(agentTools, {
+  web_search: {
+    costUSD: 0.01,
+  },
+  code_interpreter: {
+    costUSD: 0.05,
+  },
+});
+```
+
+Now you can account for:
+
+```text
+LLM usage + Tool usage = Agent cost
+```
 
 ---
 
-### The 1-Line Setup
+## 💳 Monetize
+
+Your provider cost can become part of your application's pricing model.
 
-**1. On your server:** wrap your model to track spending and set a profit margin
 ```typescript
-const model = vibezcheck(openai('gpt-4o-mini'), { pricing: { margin: 1.3 } });
+const model = vibezcheck(openai('gpt-4o-mini'), {
+  customer: 'user_123',
+  pricing: {
+    markup: 1.3,
+  },
+});
+```
+
+A 1.3x markup means:
+
+```text
+Provider cost   $1.00
+Customer price  $1.30
+─────────────────────
+Markup            30%
 ```
 
-**2. On your frontend:** drop in the component to see spendings in real time
+This lets you build products where AI usage can map directly to:
+- credits
+- usage limits
+- customer pricing
+- subscriptions
+- metered billing
+
+---
+
+## 🧾 AI Cost Receipts
+
+Show users the cost of individual AI responses.
+
+```tsx
+import { VibezReceipt } from 'vibezcheck/ui';
+
+{message.role === 'assistant' && (
+  <VibezReceipt message={message} />
+)}
+```
+
+**Example:**
+> `✦ $0.0001 · 31 tok · gpt-4o-mini`
+
+For complete conversations, use the spending HUD:
+
 ```tsx
+import { VibezCheck } from 'vibezcheck/ui';
+
 <VibezCheck messages={messages} />
 ```
 
-That’s it. You get real-time token tracking, live dollar costs, runaway loop protection, and a sleek spending HUD.
+The HUD can show:
+
+```text
+┌─────────────────────────┐
+│ AI Usage                │
+│                         │
+│ $0.0248                 │
+│ 12,420 tokens           │
+│                         │
+│ gpt-4o-mini     $0.0182 │
+│ gpt-4o          $0.0066 │
+└─────────────────────────┘
+```
 
 ---
 
-## What VibezCheck does for you
+## 🔌 Native Provider Streams
 
-When you build an AI app, chatbot, or agent:
+VibezCheck also works outside the Vercel AI SDK.
 
-* **👀 See spending in real time**: You and your users can see the exact cost (e.g. `$0.0014`) and token count for every turn as it streams in.
-* **🛡️ Never get a surprise $500 bill**: A built-in `$0.50` circuit breaker stops runaway prompts or infinite agent loops automatically before they drain your credit card.
-* **💰 Turn costs into profit**: Add `pricing: { margin: 1.3 }` to mark up wholesale API prices by 30%. You make money on every message without writing custom billing code.
-* **🤖 Works with multiple models**: If a conversation uses GPT-4o-mini, Claude 3.5, or Gemini, VibezCheck automatically breaks down the spending per model.
-* **🆓 Zero database required**: Test locally on `localhost:3000` with zero database tables and zero Stripe keys. It runs straight in memory.
-* **⚡ 0ms added latency**: Streaming is direct and transparent. Spending telemetry attaches cleanly at the very end of the stream without delaying first-token response time.
-* **🧹 Clean context window**: Telemetry stays out of your prompts. When messages get sent back to the model on the next turn, telemetry is automatically stripped so you never waste tokens.
+```typescript
+import OpenAI from 'openai';
+import { vibezcheck } from 'vibezcheck';
+
+const openai = new OpenAI();
+const client = vibezcheck.create();
+
+const stream = await openai.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [
+    {
+      role: 'user',
+      content: 'Hello!',
+    },
+  ],
+  stream: true,
+  stream_options: {
+    include_usage: true,
+  },
+});
+
+const meteredStream = client.wrapStream(stream, {
+  model: 'gpt-4o-mini',
+  customer: 'user_123',
+  onUsage: (event) => {
+    console.log(
+      `Cost: $${event.cost.totalUSD} (${event.usage.totalTokens} tokens)`
+    );
+  },
+});
+```
+
+Use VibezCheck with native provider streams without routing requests through a VibezCheck gateway.
 
 ---
 
-## 🚀 End-to-End Chatbot Example (Next.js App Router)
+## 💵 Offline Pricing Engine
 
-Here is a complete, copy-paste ready AI chatbot with live per-message spending receipts and the floating financial HUD:
+VibezCheck includes a bundled pricing catalog so known model costs can be calculated locally.
 
-### 1. Install Dependencies
+```typescript
+const rates = vibezcheck.getModelPricing('gpt-4o-mini');
+console.log(rates);
+// { inputPer1M: 0.15, outputPer1M: 0.60 }
+```
 
-```bash
-npm install vibezcheck ai @ai-sdk/openai @ai-sdk/react stripe
+Calculate costs synchronously:
+
+```typescript
+const cost = vibezcheck.calculateCost('gpt-4o-mini', {
+  promptTokens: 1000,
+  completionTokens: 500,
+});
+console.log(cost.totalUSD);
+// 0.00045
 ```
 
-### 2. Server Route (`app/api/chat/route.ts`)
+Optional pricing synchronization:
 
 ```typescript
-import { convertToModelMessages, streamText, UIMessage } from 'ai';
-import { openai } from '@ai-sdk/openai';
-import { vibezcheck } from 'vibezcheck';
+await vibezcheck.syncPricing();
+await vibezcheck.syncVercelGateway();
+```
 
-export const maxDuration = 30;
+---
 
-export async function POST(req: Request) {
-  const { messages }: { messages: UIMessage[] } = await req.json();
+## 📊 700+ Model Pricing Catalog
 
-  const result = streamText({
-    // ✦ 1 Line: track costs, add 30% profit margin, and set $0.50 runaway safety fuse
-    model: vibezcheck(openai('gpt-4o-mini'), {
-      customer: 'user_alex@example.com', // User email or Stripe customer ID
-      pricing: { margin: 1.3 },         // +30% profit margin
-      maxCostPerCallUSD: 0.50,          // Auto-stops if call exceeds $0.50
-    }),
-    instructions: 'You are a helpful AI assistant.',
-    messages: await convertToModelMessages(messages),
-  });
+VibezCheck ships with pricing information for hundreds of models and providers.
 
-  // ✦ Transmits stream with verified spending telemetry attached
-  return vibezcheck.toResponse(result);
-}
+| Provider | Examples |
+|---|---|
+| **OpenAI** | GPT-4o, GPT-4o-mini, o1, o3-mini |
+| **Anthropic** | Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus |
+| **Google** | Gemini 2.0 Flash, Gemini 1.5 Pro, Gemini 1.5 Flash |
+| **DeepSeek** | DeepSeek R1, DeepSeek V3 |
+| **Meta / Groq** | Llama 3.3 70B, Llama 3.1 8B |
+| **Mistral** | Mistral Large, Codestral, Pixtral |
+| **Gateways / Cloud** | AWS Bedrock, Azure OpenAI, OpenRouter, Vercel AI Gateway |
+
+Pricing is bundled locally for offline calculations and can optionally be refreshed.
+
+---
+
+## 🗄️ Store Usage Events
+
+VibezCheck does not require a database.  
+When you want persistence, attach a sink.
+
+### Supabase
+
+```typescript
+const model = vibezcheck(openai('gpt-4o-mini'), {
+  customer: 'user_123',
+  database: vibezcheck.supabase(supabase),
+});
 ```
 
-### 3. Frontend Client (`app/page.tsx`)
+### Custom database
 
-```tsx
-'use client';
-
-import { useChat } from '@ai-sdk/react';
-import { DefaultChatTransport } from 'ai';
-import { useState } from 'react';
-import { VibezReceipt, VibezCheck } from 'vibezcheck/ui';
-
-export default function ChatPage() {
-  const [input, setInput] = useState('');
-  const { messages, sendMessage, status } = useChat({
-    transport: new DefaultChatTransport({
-      api: '/api/chat',
-    }),
-  });
+Use your existing infrastructure:
 
-  return (
-    <div className="flex flex-col w-full max-w-lg py-20 mx-auto px-4 min-h-screen">
-      {/* Messages Stream */}
-      <div className="flex-1 space-y-4 mb-28">
-        {messages.map((message) => (
-          <div
-            key={message.id}
-            className={`p-4 rounded-2xl border ${
-              message.role === 'user'
-                ? 'bg-zinc-100 dark:bg-zinc-800 border-zinc-200 dark:border-zinc-700 ml-10'
-                : 'bg-white dark:bg-zinc-900 border-zinc-200 dark:border-zinc-800 mr-10 shadow-sm'
-            }`}
-          >
-            <div className="text-xs font-semibold uppercase tracking-wider text-zinc-400 mb-1.5">
-              {message.role === 'user' ? 'You' : 'Assistant'}
-            </div>
-
-            {/* Message Text */}
-            <div className="text-sm whitespace-pre-wrap leading-relaxed">
-              {message.parts
-                ? message.parts.map((part, index) => {
-                    switch (part.type) {
-                      case 'text':
-                        return <span key={index}>{part.text}</span>;
-                      default:
-                        return null;
-                    }
-                  })
-                : message.content}
-            </div>
-
-            {/* ✦ 1 Line: Micro-Receipt showing tokens, micro-cost, model, and latency */}
-            {message.role === 'assistant' && (
-              <div className="mt-3 flex justify-end">
-                <VibezReceipt message={message} />
-              </div>
-            )}
-          </div>
-        ))}
-
-        {status === 'streaming' && (
-          <div className="text-xs text-zinc-400 italic">Assistant is typing...</div>
-        )}
-      </div>
-
-      {/* Input Form */}
-      <form
-        onSubmit={(e) => {
-          e.preventDefault();
-          if (!input.trim()) return;
-          sendMessage({ text: input });
-          setInput('');
-        }}
-        className="fixed bottom-0 left-0 right-0 p-4 bg-white/80 dark:bg-zinc-950/80 backdrop-blur-md border-t border-zinc-200 dark:border-zinc-800"
-      >
-        <div className="max-w-lg mx-auto flex gap-2">
-          <input
-            className="flex-1 p-3 text-sm rounded-xl border border-zinc-300 dark:border-zinc-700 bg-white dark:bg-zinc-900 shadow-sm focus:outline-none focus:ring-2 focus:ring-zinc-900 dark:focus:ring-zinc-100"
-            value={input}
-            placeholder="Type your prompt..."
-            onChange={(e) => setInput(e.target.value)}
-          />
-          <button
-            type="submit"
-            disabled={status === 'streaming' || !input.trim()}
-            className="px-5 py-3 bg-zinc-900 dark:bg-zinc-100 text-white dark:text-zinc-900 text-sm font-semibold rounded-xl hover:opacity-90 disabled:opacity-50 transition"
-          >
-            Send
-          </button>
-        </div>
-      </form>
-
-      {/* ✦ 1 Line: Floating HUD showing real-time spending and tokens */}
-      <VibezCheck messages={messages} />
-    </div>
-  );
-}
+```typescript
+const model = vibezcheck(openai('gpt-4o-mini'), {
+  customer: 'user_123',
+  database: vibezcheck.database(async (event) => {
+    await db.insert(usageEvents).values({
+      customerId: event.customerId,
+      model: event.model,
+      tokens: event.usage.totalTokens,
+      costUSD: event.cost.totalUSD,
+    });
+  }),
+});
 ```
 
-### 4. Environment Variables (`.env.local`)
+Use your own:
+- PostgreSQL
+- Supabase
+- Drizzle
+- Prisma
+- MongoDB
+- ClickHouse
+- webhooks
+- analytics systems
+
+---
 
-```env
-OPENAI_API_KEY=sk-...
+## 💳 Billing Integrations
+
+Usage events can be connected to billing systems such as Stripe or Metronome.
+
+For example:
+
+```typescript
+const model = vibezcheck('openai/gpt-4o-mini', {
+  customer: 'cus_123',
+  database: vibezcheck.database(async (event) => {
+    // Send event to your billing system
+    await recordBillableUsage({
+      customerId: event.customerId,
+      costUSD: event.cost.totalUSD,
+    });
+  }),
+});
 ```
 
+VibezCheck gives you the usage event.  
+You decide how that usage becomes revenue.
+
 ---
 
-## The UI Components (Zero Props Needed)
+## 🧠 AI Agents
 
-Import from `vibezcheck/ui` or `vibezcheck/react`:
+Agentic applications need more than token tracking.  
+They need economic boundaries.
 
-### 1. `<VibezCheck messages={messages} />`
+```typescript
+const session = vibezcheck.session({
+  customer: 'enterprise_123',
+  sessionBudgetUSD: 5.00,
+});
+
+const tools = session.tools(agentTools, {
+  web_search: {
+    costUSD: 0.01,
+  },
+  code_interpreter: {
+    costUSD: 0.05,
+  },
+});
+
+const result = await runAutonomousWorkflow({
+  model: session.model('gpt-4o'),
+  tools,
+});
+```
 
-A floating financial HUD and expandable card:
-* **⇅ Unit Swap**: Click the `⇅` icon to switch between **Dollar Cost** (`$0.0028`) and **Tokens** (`1,420 tok`).
-* **Session vs Turn**: Switch between `[Session]` (total conversation spend) and `[Latest Turn]` (last reply).
-* **Multi-Model Breakdown**: If you use multiple models in one chat, it shows the exact split for each model.
-* **Customer Privacy by Default**: End-users only see their billed cost. Your wholesale costs and profit margins are hidden by default.
+VibezCheck can track:
 
-```tsx
-<VibezCheck
-  messages={messages}
-  remainingBalanceUSD={10.00}
-  onTopUp={(amount) => console.log('User wants to top up credits:', amount)}
-/>
+```text
+Model calls + Tool calls + Multiple turns
+                  ↓
+          Total agent cost
 ```
 
-### 2. `<VibezReceipt message={message} />`
+---
 
-A small, elegant badge under each assistant message:
-```tsx
-<VibezReceipt message={message} />
-// Renders: ✦ $0.0001 · 31 tok · gpt-4o-mini
+## 🏗️ Production Characteristics
+
+### Zero runtime dependencies
+`dependencies: {}`  
+The core library does not require an external runtime dependency.  
+Provider SDKs, React, and database clients are optional integrations.
+
+### No network proxy
+Model requests continue directly between your application and the provider.  
+VibezCheck runs inside your application.
+
+### No prompt storage by default
+VibezCheck does not need to store prompts or model completions to calculate usage and cost.  
+Your application controls what gets persisted through optional database adapters.
+
+### Failure isolation
+Telemetry and database reporting should not become a dependency of the user-facing AI response.  
+VibezCheck supports asynchronous reporting through serverless lifecycle mechanisms such as:
+- Next.js / Vercel `globalThis.after()`
+- Cloudflare Workers `waitUntil()`
+
+### Offline capable
+The bundled pricing catalog allows cost calculations without requiring an external network request.
+
+---
+
+## 🔄 How It Works
+
+```text
+Your Application
+       │
+       ▼
+┌──────────────────┐
+│   AI Provider    │
+│ OpenAI / Claude  │
+│  Gemini / etc.   │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│   VibezCheck     │
+│                  │
+│     Usage        │
+│     Cost         │
+│  Attribution     │
+│     Limits       │
+└────────┬─────────┘
+         │
+    ┌────┴────┐
+    ▼         ▼
+Application  Async sinks
+ economics   DB / billing / analytics
 ```
 
+The important part:  
+Your model traffic stays in your application path.  
+VibezCheck adds the economic layer around it.
+
 ---
 
-## Multi-Model Sessions (Automatic Breakdown)
+## 🧩 Supported Integrations
+
+### AI SDKs
+- Vercel AI SDK
+- OpenAI
+- Anthropic
+- Gemini
+- Native streaming APIs
+
+### Storage
+- Supabase
+- Custom database adapters
+- PostgreSQL
+- Drizzle
+- Prisma
+- MongoDB
+- ClickHouse
+
+### Billing
+- Stripe
+- Metronome
+- Custom billing systems
+
+### UI
+- React
+- `<VibezReceipt />`
+- `<VibezCheck />`
 
-If your app routes between different models (e.g. `gpt-4o-mini` for quick chat and `claude-3-5-sonnet` for coding):
+---
+
+## 🔍 CLI
 
-VibezCheck automatically detects every model used and lists them in the HUD:
-* `gpt-4o-mini (1 turn)`: 31 tok · $0.0001
-* `claude-3-5-sonnet (1 turn)`: 420 tok · $0.0068
+Audit your project for potentially unmetered AI calls:
 
-Click any model to see its specific spending.
+```bash
+npx vibezcheck audit
+```
+
+Generate starter examples:
+
+```bash
+npx vibezcheck examples
+```
 
 ---
 
-## Need Stripe Billing? (Optional)
+## 🚀 Complete Example
+
+A typical AI chat application can look like this:
+
+```typescript
+import { streamText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { vibezcheck } from 'vibezcheck';
+
+export async function POST(req: Request) {
+  const { messages, userId } = await req.json();
+
+  const result = streamText({
+    model: vibezcheck(openai('gpt-4o-mini'), {
+      customer: userId,
+      pricing: {
+        markup: 1.3,
+      },
+      maxCostPerCallUSD: 0.50,
+    }),
+    messages,
+  });
+
+  return vibezcheck.toResponse(result);
+}
+```
+
+Your application now has:
+- ✓ Model usage
+- ✓ Dollar cost
+- ✓ Customer attribution
+- ✓ Pricing / markup
+- ✓ Per-request protection
+- ✓ Streaming support
+
+---
+
+## 🎯 The Economic Layer for AI
+
+AI applications are becoming more autonomous.  
+More messages.  
+More context.  
+More tool calls.  
+More model calls.  
+More cost.
+
+VibezCheck gives your application a way to understand that cost at the point where the AI request happens.
+
+```text
+       MEASURE
+          │
+    ┌─────┴─────┐
+    │           │
+ tokens      dollars
+    │           │
+    └─────┬─────┘
+          │
+       CONTROL
+  budgets / limits
+          │
+      MONETIZE
+  pricing / billing
+```
+
+**Know what every AI request costs.**
+
+---
+
+## Roadmap
+
+### Current
+- Request-level cost metering
+- 700+ model pricing catalog
+- Streaming support
+- Customer attribution
+- Circuit breakers
+- Agent session budgets
+- Tool cost tracking
+- React usage UI
+- Database sinks
+
+### Next
+- Persistent cost history
+- Per-customer budgets
+- Spend alerts
+- Cost anomaly detection
+- Native billing integrations
+- Unit economics analytics
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+```bash
+pnpm install
+pnpm test
+pnpm typecheck
+```
 
-When you want to charge real money, VibezCheck has built-in Stripe helpers:
+To update model pricing:  
+`src/pricing/catalog.ts`
 
-* **Prepaid Credits**: Let users buy credit balance with Stripe Checkout (`BillingHelper.createTopUpSession`).
-* **Customer API Keys**: Issue `vz_live_...` keys saved in Stripe customer metadata (`ApiKeyAuth`).
-* **Agent Session Ceilings**: Limit a multi-step agent to a hard $1.00 budget with `AgentSession`.
+Please ensure tests pass and no unnecessary runtime dependencies are introduced.
 
 ---
 
-## 📄 License
+## License
 
-MIT © [VibezCheck](https://vibezcheck.xyz)
+MIT © VibezCheck  
+[Website](https://vibezcheck.xyz/) · [npm](https://www.npmjs.com/package/vibezcheck)  
+Contact: [yt@vibezcheck.app](mailto:yt@vibezcheck.app)