{"_id":"@clarit.ai/vercel-ai-provider","_rev":"4-a0b50aff9572b2ed11947f89fad22577","name":"@clarit.ai/vercel-ai-provider","dist-tags":{"latest":"0.2.2"},"versions":{"0.1.0":{"name":"@clarit.ai/vercel-ai-provider","version":"0.1.0","keywords":["vercel","ai-sdk","clarit","engram","mamba","stateful","snapshot","sglang"],"author":{"name":"Clarit AI"},"license":"Apache-2.0","_id":"@clarit.ai/vercel-ai-provider@0.1.0","maintainers":[{"name":"billy-clarit.ai","email":"billy@clarit.ai"}],"homepage":"https://github.com/Clarit-AI/vercel-ai-provider#readme","bugs":{"url":"https://github.com/Clarit-AI/vercel-ai-provider/issues"},"dist":{"shasum":"994de4182531a5a96228a5f3c6812a836d57ae38","tarball":"https://registry.npmjs.org/@clarit.ai/vercel-ai-provider/-/vercel-ai-provider-0.1.0.tgz","fileCount":10,"integrity":"sha512-h+nOX87beZCI6CfiYPgibD/G6c3LkiIGfLw+u1iWWb9FSvhnE8a8FCWTdSgNkwWZuViBFxLNwkjSHNAmOZrikA==","signatures":[{"sig":"MEUCIFAj6D7VZWKgnjKcGhnLrwiZTPD57pGx4hPL+IWX0vR0AiEAypahSTON8s90ziWkftY0Nnc38B2TdYbh72kslkIf+IQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":63680},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./snapshots":{"types":"./dist/snapshots/index.d.ts","import":"./dist/snapshots/index.js"}},"gitHead":"c44014dab88ece0f09dca389f984d3a42bc25655","scripts":{"test":"vitest run","build":"tsup","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"billy-clarit.ai","email":"billy@clarit.ai"},"repository":{"url":"git+https://github.com/Clarit-AI/vercel-ai-provider.git","type":"git"},"_npmVersion":"11.11.1","description":"Vercel AI SDK provider for Clarit (Engram) — persistent Mamba state as a drop-in","directories":{},"_nodeVersion":"25.8.2","dependencies":{"@ai-sdk/provider":"^1.1.0","@ai-sdk/provider-utils":"^2.2.0","@ai-sdk/openai-compatible":"^0.2.0"},"_hasShrinkwrap":false,"devDependencies":{"ai":"^4.3.0","tsup":"^8.4.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"peerDependencies":{"ai":">=4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/vercel-ai-provider_0.1.0_1775202295170_0.6756940446718331","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@clarit.ai/vercel-ai-provider","version":"0.2.0","keywords":["vercel","ai-sdk","clarit","engram","mamba","stateful","snapshot","sglang"],"author":{"name":"Clarit AI"},"license":"Apache-2.0","_id":"@clarit.ai/vercel-ai-provider@0.2.0","maintainers":[{"name":"billy-clarit.ai","email":"billy@clarit.ai"}],"homepage":"https://github.com/Clarit-AI/Engram-Vercel-Provider#readme","bugs":{"url":"https://github.com/Clarit-AI/Engram-Vercel-Provider/issues"},"dist":{"shasum":"572fb3152ed7fdb8ae8f2c248fbc374a934179fb","tarball":"https://registry.npmjs.org/@clarit.ai/vercel-ai-provider/-/vercel-ai-provider-0.2.0.tgz","fileCount":10,"integrity":"sha512-aJYnVBHYmXOc/Bn6xBPQYBU1Gnjw7ml2atbc2CMwUeUqaY3s1L37U0QrCrr+A3QMdn8/x/JSDbedd4yEtQ9vlA==","signatures":[{"sig":"MEUCIQDq0o2vLwixe4HXUvwTf/9If6duhVZiHtKIn+YBRuu7UAIgMxXHnvo0FWalZbhRRzICF+xf6gC+3IvHeAL6DWIwLZs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@clarit.ai%2fvercel-ai-provider@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":101483},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./snapshots":{"types":"./dist/snapshots/index.d.ts","import":"./dist/snapshots/index.js"}},"gitHead":"7782558535b20923c562342defbe51fafea290c1","scripts":{"test":"vitest run","build":"tsup","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"billy-clarit.ai","email":"billy@clarit.ai"},"repository":{"url":"git+https://github.com/Clarit-AI/Engram-Vercel-Provider.git","type":"git"},"_npmVersion":"10.9.7","description":"Vercel AI SDK provider for Clarit (Engram) — persistent Mamba state as a drop-in","directories":{},"_nodeVersion":"22.22.2","dependencies":{"@ai-sdk/provider":"^3.0.0","@ai-sdk/provider-utils":"^4.0.0","@ai-sdk/openai-compatible":"^2.0.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"ai":"^5.0.0","tsup":"^8.4.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"peerDependencies":{"ai":">=5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/vercel-ai-provider_0.2.0_1775284969680_0.3218715122341005","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@clarit.ai/vercel-ai-provider","version":"0.2.1","keywords":["vercel","ai-sdk","clarit","engram","mamba","stateful","snapshot","sglang"],"author":{"name":"Clarit AI"},"license":"Apache-2.0","_id":"@clarit.ai/vercel-ai-provider@0.2.1","maintainers":[{"name":"billy-clarit.ai","email":"billy@clarit.ai"}],"homepage":"https://github.com/Clarit-AI/Engram-Vercel-Provider#readme","bugs":{"url":"https://github.com/Clarit-AI/Engram-Vercel-Provider/issues"},"dist":{"shasum":"945a0a4329eb14275385feccc2112296fc4d9132","tarball":"https://registry.npmjs.org/@clarit.ai/vercel-ai-provider/-/vercel-ai-provider-0.2.1.tgz","fileCount":10,"integrity":"sha512-0rY4TncPLazz99Tn6p+m9T1ZukflEWw7lCPSvwKNWOuqS5gcBgkx0gL/NL7va3pTdryB1C5eIHWxl2mYTA+0sA==","signatures":[{"sig":"MEYCIQDL0q6eWe33s/2Omz86NaGAKntPhoOLePCqRX9G3QH7KwIhAMMoCl0mosW1EHeGBMeooN/fXM9AkG7JpDbu6HPMKi9s","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":101720},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./snapshots":{"types":"./dist/snapshots/index.d.ts","import":"./dist/snapshots/index.js"}},"gitHead":"4ab77bd82bbf2937c0d9e1543e33161eb2cb1beb","scripts":{"test":"vitest run","build":"tsup","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"billy-clarit.ai","email":"billy@clarit.ai"},"repository":{"url":"git+https://github.com/Clarit-AI/Engram-Vercel-Provider.git","type":"git"},"_npmVersion":"11.12.1","description":"Vercel AI SDK provider for Clarit (Engram) — persistent Mamba state as a drop-in","directories":{},"_nodeVersion":"26.0.0","dependencies":{"@ai-sdk/provider":"^3.0.0","@ai-sdk/provider-utils":"^4.0.0","@ai-sdk/openai-compatible":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ai":"^5.0.0","tsup":"^8.4.0","vitest":"^3.0.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"peerDependencies":{"ai":">=5.0.0"},"_npmOperationalInternal":{"tmp":"tmp/vercel-ai-provider_0.2.1_1779679029526_0.8182822753438754","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@clarit.ai/vercel-ai-provider","version":"0.2.2","description":"Vercel AI SDK provider for Clarit (Engram) — persistent Mamba state as a drop-in","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./snapshots":{"import":"./dist/snapshots/index.js","types":"./dist/snapshots/index.d.ts"}},"scripts":{"build":"tsup","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","clean":"rm -rf dist"},"keywords":["vercel","ai-sdk","clarit","engram","mamba","stateful","snapshot","sglang"],"author":{"name":"Clarit AI"},"license":"Apache-2.0","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/Clarit-AI/Engram-Vercel-Provider.git"},"peerDependencies":{"ai":">=5.0.0"},"dependencies":{"@ai-sdk/openai-compatible":"^2.0.0","@ai-sdk/provider":"^3.0.0","@ai-sdk/provider-utils":"^4.0.0"},"devDependencies":{"ai":"^5.0.0","tsup":"^8.4.0","typescript":"^5.7.0","vitest":"^3.0.0","@types/node":"^22.0.0"},"gitHead":"5f5e784ccd1ebe495df35ae889fb56a10f40b169","_id":"@clarit.ai/vercel-ai-provider@0.2.2","bugs":{"url":"https://github.com/Clarit-AI/Engram-Vercel-Provider/issues"},"homepage":"https://github.com/Clarit-AI/Engram-Vercel-Provider#readme","_nodeVersion":"26.0.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-VWTgnlbA00rP1U2m5nf8e+CFVyIU96uIW076EDfx8vavnEqIviOaSk0sNRqd8OzRQQOJp2K+vzGjrahtF9HNrA==","shasum":"5552ebe3b7375fa156e9200e45ec850e5de5da92","tarball":"https://registry.npmjs.org/@clarit.ai/vercel-ai-provider/-/vercel-ai-provider-0.2.2.tgz","fileCount":10,"unpackedSize":109800,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIE/h5d4SnwSvm/61f/BqnS2z1NG9HpgW1AUxrIa9UAk9AiEAuWY5sN4uBEExPIQ5vOe+KUU2OMb6J/HW8HPoglL99pw="}]},"_npmUser":{"name":"billy-clarit.ai","email":"billy@clarit.ai"},"directories":{},"maintainers":[{"name":"billy-clarit.ai","email":"billy@clarit.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vercel-ai-provider_0.2.2_1779737636393_0.33333064006053204"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-03T07:44:55.049Z","modified":"2026-05-25T19:33:56.664Z","0.1.0":"2026-04-03T07:44:55.362Z","0.2.0":"2026-04-04T06:42:49.847Z","0.2.1":"2026-05-25T03:17:09.694Z","0.2.2":"2026-05-25T19:33:56.532Z"},"bugs":{"url":"https://github.com/Clarit-AI/Engram-Vercel-Provider/issues"},"author":{"name":"Clarit AI"},"license":"Apache-2.0","homepage":"https://github.com/Clarit-AI/Engram-Vercel-Provider#readme","keywords":["vercel","ai-sdk","clarit","engram","mamba","stateful","snapshot","sglang"],"repository":{"type":"git","url":"git+https://github.com/Clarit-AI/Engram-Vercel-Provider.git"},"description":"Vercel AI SDK provider for Clarit (Engram) — persistent Mamba state as a drop-in","maintainers":[{"name":"billy-clarit.ai","email":"billy@clarit.ai"}],"readme":"# @clarit.ai/vercel-ai-provider\n\n### Vercel AI SDK models that remember.\n\n[![Built on SGLang](https://img.shields.io/badge/built%20on-SGLang-blue)](https://github.com/sgl-project/sglang)\n[![Vercel AI SDK](https://img.shields.io/badge/AI--SDK-v4-black)](https://sdk.vercel.ai)\n\nStandard LLM providers treat model state as disposable. Every new message re-reads the entire conversation history from scratch, costing you time and tokens.\n\n**Clarit (Engram) changes the rules.** \n\nThis provider for the [Vercel AI SDK](https://sdk.vercel.ai) turns model state into a durable asset. Save conversation state to disk and restore it in ~2ms. Skip the prefill, slash token costs by 94%, and pick up exactly where you left off.\n\n---\n\n## Installation\n\n```bash\nnpm install @clarit.ai/vercel-ai-provider ai\n```\n\n## Features\n\n- **Drop-in Persistence**: Wrap any OpenAI-compatible Mamba/hybrid model.\n- **Auto-Save Snapshots**: Automatically persist conversation state to the Engram 3-tier hierarchy (VRAM/RAM/Disk).\n- **Restore-and-Generate**: Perform inference by restoring state directly, bypassing standard `/v1/chat/completions` prefill overhead.\n- **Snapshot Management**: Direct TypeScript client for listing, querying, and deleting conversation checkpoints.\n\n## Quick Start\n\n```typescript\nimport { createClarit } from '@clarit.ai/vercel-ai-provider';\nimport { generateText } from 'ai';\n\nconst clarit = createClarit({\n  baseURL: 'http://your-engram-server:30000',\n});\n\n// 1. Initial Turn: Save the context\nconst { text } = await generateText({\n  model: clarit('granite-4.0-h-small'),\n  messages: [{ role: 'user', content: 'My name is Alice.' }],\n  providerOptions: {\n    clarit: {\n      conversationId: 'session-123',\n      turnNumber: 1,\n      autoSaveSnapshot: true,\n    },\n  },\n});\n\n// 2. Future Session: Instant Recall\n// Restores Alice's state in ~2ms, skipping re-reading Turn 1.\nconst { text: recalled } = await generateText({\n  model: clarit('granite-4.0-h-small'),\n  messages: [], // History is restored from state, not re-read from text\n  providerOptions: {\n    clarit: {\n      conversationId: 'session-123',\n      turnNumber: 1,\n      restoreBeforeGenerate: true,\n      continuationIds: [5812, 1072, 30], // Tokenized \"What is my name?\"\n      maxNewTokens: 64,\n    },\n  },\n});\n```\n\n## Provider Options\n\n| Option | Type | Description |\n|--------|------|-------------|\n| `conversationId` | `string` | Stable ID for grouping conversation snapshots. |\n| `turnNumber` | `number` | The turn index to save to or restore from. |\n| `branchName` | `string` | Alternate conversation branch name. |\n| `autoSaveSnapshot` | `boolean` | Save state after generation completes (best-effort). |\n| `restoreBeforeGenerate` | `boolean` | Mode: Restore state -> Append tokens -> Generate. |\n| `continuationIds` | `number[]` | Token IDs for the new turn (required for restore mode). |\n| `maxNewTokens` | `number` | Max tokens to generate in restore mode. |\n| `compatibilityMode` | `'append-only' \\| false` | Enable stateless compatibility bridge (`@experimental`). |\n\n## Compatibility Mode (`@experimental`)\n\nFor chat harnesses that don't natively manage Engram state, the **append-only compatibility bridge** automatically detects when new messages are an extension of a previously snapshotted conversation and takes the fast-path (restore-and-generate), falling back to standard `/v1/chat/completions` otherwise.\n\n```typescript\nimport { type ClaritResponseMetadata } from '@clarit.ai/vercel-ai-provider';\n\nconst { text, providerMetadata } = await generateText({\n  model: clarit('granite-4.0-h-small'),\n  messages: [\n    { role: 'system', content: 'You are helpful.' },\n    { role: 'user', content: 'Hello!' },\n    { role: 'assistant', content: 'Hi there!' },\n    { role: 'user', content: 'What is 2+2?' },  // ← new message appended\n  ],\n  providerOptions: {\n    clarit: {\n      conversationId: 'session-123',\n      autoSaveSnapshot: true,\n      compatibilityMode: 'append-only',\n      maxNewTokens: 128,  // required for fast-path\n    },\n  },\n});\n\n// Check what happened\nconst meta = providerMetadata?.clarit as ClaritResponseMetadata;\nconsole.log(meta.compatibilityResult); // 'fast-path' | 'fallback'\n```\n\n### How it works\n\n1. Tokenizes the full message list via the server's `/tokenize_chat` endpoint.\n2. Fetches the latest snapshot's `fill_ids` (cached tokens) via `/get_snapshot_info`.\n3. Checks whether the new messages are a pure **append** on top of the snapshot using `isAppendOnly()`.\n4. **Fast-path**: If append-only, restores the snapshot and sends only the delta tokens — skips re-prefilling the entire conversation.\n5. **Fallback**: If the conversation was edited, contains unsupported content, or no snapshot exists, falls back to standard generation.\n\n### Fallback reasons\n\n| Reason | Meaning |\n|--------|---------|\n| `disabled` | `maxNewTokens` not set or zero. |\n| `no-snapshot` | No snapshot found for the conversation. |\n| `fill-ids-missing` | Snapshot exists but has no `fill_ids`. |\n| `prefix-mismatch` | Messages were edited (not an append-only extension). |\n| `unsupported-content` | Prompt contains tool calls, files, or other non-text content. |\n| `tokenization-error` | Server-side tokenization failed. |\n| `missing-conversation-id` | No `conversationId` provided. |\n\n### Response metadata\n\nWhen compatibility mode is active, `providerMetadata.clarit` includes diagnostics:\n\n| Field | Description |\n|-------|-------------|\n| `compatibilityResult` | `'fast-path'` or `'fallback'` |\n| `fallbackReason` | Why fallback was taken (see table above) |\n| `reusedTokenCount` | Tokens reused from snapshot (fast-path only) |\n| `continuationTokenCount` | New delta tokens sent (fast-path only) |\n\n## Snapshot Management\n\nAccess the Engram management API directly via `clarit.snapshots`:\n\n```typescript\nconst snapshots = await clarit.snapshots.list('conversation-123');\nconsole.log(`Found ${snapshots.length} checkpoints.`);\n\nawait clarit.snapshots.delete({\n  conversation_id: 'conversation-123',\n  turn_number: 1\n});\n```\n\n## Built-in Agent Skills\n\nThis repo ships Claude Code / agent skills in `.claude/skills/` that give AI assistants working knowledge of the systems this provider touches — no extra setup required:\n\n| Skill | Purpose |\n|-------|---------|\n| `vercel-ai-provider-spec` | Vercel AI SDK Language Model spec (V3/V4), type reference, and upgrade patterns |\n| `engram-sglang` | Engram server architecture, snapshot API contract, server flags, model compatibility matrix |\n\nIf you're using Claude Code, these are loaded automatically. For other agents, the Markdown content in each `SKILL.md` and its `references/` directory is designed to be consumable as-is.\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}