{"_id":"@charcoalhq/ai-sdk","name":"@charcoalhq/ai-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@charcoalhq/ai-sdk","version":"0.1.0","description":"Charcoal tools for the Vercel AI SDK","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"engines":{"node":">=20"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup src/index.ts --format esm --dts","test":"tsx --env-file=.env src/test.ts","typecheck":"tsc --noEmit","changeset":"changeset","release":"pnpm run build && changeset publish","prepublishOnly":"pnpm build"},"keywords":["ai","ai-sdk","tools","charcoal","rag","search"],"repository":{"type":"git","url":"git+https://github.com/CharcoalHQ/ai-sdk.git"},"homepage":"https://docs.withcharcoal.com","bugs":{"url":"https://github.com/CharcoalHQ/ai-sdk/issues"},"author":{"name":"Charcoal"},"license":"MIT","packageManager":"pnpm@10.8.0","devDependencies":{"@changesets/cli":"^2.27.0","@charcoalhq/sdk":"^0.3.0","@types/node":"^24.10.1","dotenv":"^17.2.3","tsup":"^8.5.0","tsx":"^4.20.6","typescript":"^5.9.3"},"peerDependencies":{"@charcoalhq/sdk":"^0.3.0","ai":"^5.0.0","zod":"^4.0.0"},"_id":"@charcoalhq/ai-sdk@0.1.0","gitHead":"5d5bcdebcbcd50cf3ceef0ff61fc5deffe7a534c","_nodeVersion":"22.11.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-eMrk2ZkZAAyrAV1q1KnrtPSC4EzBhVPsTu7i7KFAGVN2JjahoWKX44Pz5tyaEZs+rsA9VlLBi/pbkTfuhsFZag==","shasum":"f8764634ba9f1f0b8cedb7413af551cc83db4143","tarball":"https://registry.npmjs.org/@charcoalhq/ai-sdk/-/ai-sdk-0.1.0.tgz","fileCount":4,"unpackedSize":12725,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCkrC6TOC8aU3LDw/snwXXsXPxJdLelcbcdRy3Uzki8vwIhAPv3SW2EGJQ5+ocQy/ZudK5v/mOtZzY4BpEnRo4MmwrS"}]},"_npmUser":{"name":"charcoalhq-admin","email":"accounts+npm@withcharcoal.com"},"directories":{},"maintainers":[{"name":"charcoalhq-admin","email":"accounts+npm@withcharcoal.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-sdk_0.1.0_1776274854272_0.3778972787863297"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-15T17:40:54.118Z","0.1.0":"2026-04-15T17:40:54.413Z","modified":"2026-04-15T17:40:54.693Z"},"maintainers":[{"name":"charcoalhq-admin","email":"accounts+npm@withcharcoal.com"}],"description":"Charcoal tools for the Vercel AI SDK","homepage":"https://docs.withcharcoal.com","keywords":["ai","ai-sdk","tools","charcoal","rag","search"],"repository":{"type":"git","url":"git+https://github.com/CharcoalHQ/ai-sdk.git"},"author":{"name":"Charcoal"},"bugs":{"url":"https://github.com/CharcoalHQ/ai-sdk/issues"},"license":"MIT","readme":"# @charcoalhq/ai-sdk\n\nCharcoal tools for the [Vercel AI SDK](https://sdk.vercel.ai).\n\nGive your agent one tool and let Charcoal handle planning, multi-hop retrieval, and citation over your corpus.\n\n## Installation\n\n```bash\nnpm install @charcoalhq/ai-sdk @charcoalhq/sdk ai zod\n```\n\n## Usage\n\nSet `CHARCOAL_API_KEY` in your environment. The package ships two entry points — a zero-config tool and a factory for the common case where you want to bake defaults in code.\n\n### `searchTool`\n\nYour agent's model supplies `namespace`, `objective`, and `context` on every call.\n\n```ts\nimport { generateText } from \"ai\";\nimport { anthropic } from \"@ai-sdk/anthropic\";\nimport { searchTool } from \"@charcoalhq/ai-sdk\";\n\nconst { text } = await generateText({\n  model: anthropic(\"claude-sonnet-4-6\"),\n  tools: { search: searchTool },\n  prompt:\n    \"In the `contracts` namespace, find every MSA with auto-renewal longer than 24 months.\",\n});\n```\n\n### `createSearchTool`\n\nBake the namespace, auth, filters, or description into the tool. Anything set here is removed from the input schema your agent's model sees, so it only reasons about `objective` and `context`.\n\n```ts\nimport { createSearchTool } from \"@charcoalhq/ai-sdk\";\n\nconst contractSearch = createSearchTool({\n  namespace: \"contracts\",\n  filters: { status: \"active\" },\n  description: \"Search active vendor contracts.\",\n});\n\nconst { text } = await generateText({\n  model: anthropic(\"claude-sonnet-4-6\"),\n  tools: { search: contractSearch },\n  prompt: \"Find every MSA with auto-renewal longer than 24 months.\",\n});\n```\n\nUnder the hood, each tool call hits `client.namespaces.search.create(namespace, { objective, context, filters? })` on `@charcoalhq/sdk` and returns a synthesized answer with cited excerpts.\n\n### Streaming\n\nBoth `searchTool` and `createSearchTool` stream by default. Under the hood, `execute` is an async generator that yields each `SearchStreamEvent` as it arrives — the AI SDK surfaces intermediate yields (`status` events) as preliminary tool outputs on the data stream, so your UI sees progress in real time. The final yield is the `session_result` event, which your agent's model consumes as the tool result. Error events are thrown by the underlying SDK.\n\n```ts\n// UI code consuming the AI SDK's data stream — no extra plumbing needed.\nconst { textStream, fullStream } = streamText({\n  model: anthropic(\"claude-sonnet-4-6\"),\n  tools: { search: createSearchTool({ namespace: \"contracts\" }) },\n  prompt: \"...\",\n});\nfor await (const part of fullStream) {\n  if (part.type === \"tool-output-available\") {\n    // part.output is a SearchStreamEvent — 'status', 'session_result', etc.\n  }\n}\n```\n\nSet `stream: false` to opt into a single-shot non-streaming call that yields just the synthesized `SearchResponse`.\n\n`SearchStreamEvent` is re-exported from `@charcoalhq/sdk`, so you get proper narrowing on `event.type`.\n\n### `CreateSearchToolOptions`\n\n```ts\ntype CreateSearchToolOptions = {\n  // Namespace to search. If set, removed from the input schema your agent's model sees.\n  namespace?: string;\n  // Defaults to process.env.CHARCOAL_API_KEY.\n  apiKey?: string;\n  // Pre-built Charcoal client (takes precedence over apiKey and baseUrl).\n  client?: Charcoal;\n  // Filters applied to every search call.\n  filters?: SearchCreateParams[\"filters\"];\n  // Override the tool description shown to your agent's model.\n  description?: string;\n  // Stream SSE events through execute as an async generator. Defaults to true.\n  stream?: boolean;\n  // Override the API base URL. Defaults to https://api.withcharcoal.com.\n  baseUrl?: string;\n};\n```\n\nSee [docs.withcharcoal.com](https://docs.withcharcoal.com) for the full search API, filter syntax, and schema reference.\n\n## Development\n\n```bash\npnpm install\ncp .env.example .env   # add your CHARCOAL_API_KEY and CHARCOAL_NAMESPACE\npnpm test              # invokes the tool against a real namespace (streaming)\npnpm build             # emits dist/\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-724d37e620b1d5514dd033ed45871a9c"}