{"_id":"@braingrid/sdk","_rev":"2-50253f3e68e5635eb7226893ed31b642","name":"@braingrid/sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@braingrid/sdk","version":"0.1.0","keywords":["ai","sdk","vercel","llm","wrapper","json-guard","retry","hooks"],"_id":"@braingrid/sdk@0.1.0","maintainers":[{"name":"acossta","email":"nico@acosta.io"},{"name":"braingrid_tyler","email":"tyler@braingrid.ai"}],"dist":{"shasum":"fb85c95838cd407f0a92b298df26762f6d82b8df","tarball":"https://registry.npmjs.org/@braingrid/sdk/-/sdk-0.1.0.tgz","fileCount":9,"integrity":"sha512-DmGFogNbpBaMB7Z7CpurHiQyjqmT+6L0gV5Doetq+LJJL26lfidB3MpZ6stsR+VKVAQRLkRIzZ3MjusL1tt5eQ==","signatures":[{"sig":"MEQCIADswRImZCLq5EeCuKgbzeUxIdYH/NEaCRkYW6/vcX85AiAQoZ7n9qDnVUhtx4QhP94ukY9i8hM31sHjYLTdcIViWw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":69348},"main":"./dist/index.cjs","type":"module","_from":"file:braingrid-sdk-0.1.0.tgz","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","clean":"rm -rf dist","test:watch":"vitest","type-check":"tsc --noEmit"},"_npmUser":{"name":"braingrid_tyler","email":"tyler@braingrid.ai"},"_resolved":"/private/var/folders/mt/c41k7_b167q49y0dr5z1yp040000gn/T/6aca9d7f03147ab63bb3774ccf2bdc54/braingrid-sdk-0.1.0.tgz","_integrity":"sha512-DmGFogNbpBaMB7Z7CpurHiQyjqmT+6L0gV5Doetq+LJJL26lfidB3MpZ6stsR+VKVAQRLkRIzZ3MjusL1tt5eQ==","_npmVersion":"10.9.2","description":"Drop-in wrapper for Vercel's ai SDK with optional integrations for json-guard, retry, cost tracking, and providers","directories":{},"_nodeVersion":"22.17.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"ai":"^5.0.0","tsup":"^8.0.0","vitest":"^2.0.0","typescript":"^5.6.0","@types/node":"^20.0.0","@braingrid/json-guard":"0.1.0"},"peerDependencies":{"ai":">=5.0.0"},"peerDependenciesMeta":{"ai":{"optional":false}},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1762647515527_0.8512060343072181","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@braingrid/sdk","version":"0.2.0","description":"Drop-in wrapper for Vercel's ai SDK with optional integrations for json-guard, retry, cost tracking, and providers","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"build":"tsup","dev":"tsup --watch","type-check":"tsc --noEmit","test":"vitest run","test:watch":"vitest","clean":"rm -rf dist"},"keywords":["ai","sdk","vercel","llm","wrapper","json-guard","retry","hooks"],"author":{"name":"BrainGrid AI, Inc."},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/BrainGridAI/ai-kit.git","directory":"packages/sdk"},"homepage":"https://github.com/BrainGridAI/ai-kit/tree/main/packages/sdk#readme","bugs":{"url":"https://github.com/BrainGridAI/ai-kit/issues"},"peerDependencies":{"ai":">=5.0.0"},"peerDependenciesMeta":{"ai":{"optional":false}},"dependencies":{},"devDependencies":{"@types/node":"^20.0.0","ai":"^5.0.0","tsup":"^8.0.0","typescript":"^5.6.0","vitest":"^2.0.0","@braingrid/json-guard":"workspace:*"},"publishConfig":{"access":"public","provenance":false},"gitHead":"34fc61b8d99d92746e6027c8d929d5e90721d37d","_id":"@braingrid/sdk@0.2.0","_nodeVersion":"20.19.5","_npmVersion":"11.6.2","dist":{"integrity":"sha512-AiaMYYFkjCBAMDfiXok8oT88q65+Qk9W7SNcG3Dpb5fWrYmr3DpE9Oz8lLl9UE1Mz5H0OLOCNv0gmPxORUfOOA==","shasum":"746a6c65bdb97647456e360c5e7f4c00de740c9b","tarball":"https://registry.npmjs.org/@braingrid/sdk/-/sdk-0.2.0.tgz","fileCount":8,"unpackedSize":77233,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD7o70Twady0O8WfQ6SKnWIKudefW+6V2ZS2y6v50Cc4gIhALkXA2rk0UCnf7vv2TYWPUEDq6zbvz5evrStVTTso5w8"}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:7b9db347-994f-40e5-8af2-929064a20c73"}},"directories":{},"maintainers":[{"name":"acossta","email":"nico@acosta.io"},{"name":"braingrid_tyler","email":"tyler@braingrid.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.2.0_1762811511548_0.9086365249427659"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-09T00:18:35.426Z","modified":"2025-11-10T21:51:51.973Z","0.1.0":"2025-11-09T00:18:35.732Z","0.2.0":"2025-11-10T21:51:51.780Z"},"keywords":["ai","sdk","vercel","llm","wrapper","json-guard","retry","hooks"],"description":"Drop-in wrapper for Vercel's ai SDK with optional integrations for json-guard, retry, cost tracking, and providers","maintainers":[{"name":"acossta","email":"nico@acosta.io"},{"name":"braingrid_tyler","email":"tyler@braingrid.ai"}],"readme":"# @braingrid/sdk\n\nDrop-in wrapper for Vercel's `ai` SDK with optional integrations for json-guard, retry logic, cost tracking, and custom providers.\n\n## Features\n\n- **100% Compatible**: Preserves identical function signatures to Vercel's `ai` SDK\n- **Auto-imports**: Peer dependency management ensures `ai` package is automatically installed\n- **Version Resilient**: New exports from `ai` are automatically available via proxy\n- **Optional Integrations**: All integrations are optional and no-op if not configured\n  - JSON Guard for tool argument validation/repair\n  - Retry logic with configurable backoff (shim for future @braingrid/llm-retry)\n  - Cost tracking (shim for future @braingrid/cost-tracker)\n  - Custom provider injection (fetch, baseURL, headers)\n- **Lifecycle Hooks**: Monitor and debug with beforeCall, afterCall, onToken, onRetry, onCost, onGuard\n\n## Installation\n\n```bash\npnpm add @braingrid/sdk\n# The ai package is automatically installed as a peer dependency\n```\n\n## Basic Usage\n\n```typescript\nimport { createAiSdk } from \"@braingrid/sdk\";\n\n// Create SDK with default settings (identical to raw ai SDK)\nconst ai = createAiSdk();\n\n// Use exactly like the Vercel ai SDK\nconst response = await ai.generateText({\n  model: \"gpt-4o\",\n  prompt: \"Hello, world!\",\n});\n\n// Stream text\nconst stream = await ai.streamText({\n  model: \"gpt-4o\",\n  prompt: \"Tell me a story\",\n});\n\nfor await (const chunk of stream.textStream) {\n  console.log(chunk.text);\n}\n```\n\n## Advanced Usage\n\n### With JSON Guard Integration\n\n```typescript\nimport { createAiSdk } from \"@braingrid/sdk\";\nimport { createGuard, ajvAdapter } from \"@braingrid/json-guard\";\n\nconst ai = createAiSdk({\n  jsonGuard: {\n    guard: createGuard(),\n    resolveSchema: (event) => {\n      // Return schema for tool validation\n      if (event.toolName === \"search\") {\n        return ajvAdapter().fromJsonSchema({\n          type: \"object\",\n          required: [\"query\"],\n          properties: {\n            query: { type: \"string\" },\n            limit: { type: \"integer\", default: 10 },\n          },\n          additionalProperties: false,\n        });\n      }\n      return undefined;\n    },\n  },\n});\n```\n\n### With Lifecycle Hooks\n\n```typescript\nconst ai = createAiSdk({\n  hooks: {\n    beforeCall: async ({ id, fn, args }) => {\n      console.log(`[${id}] Calling ${fn}`, args);\n    },\n    afterCall: async ({ id, ok, latencyMs, usage }) => {\n      console.log(`[${id}] Completed in ${latencyMs}ms`, { ok, usage });\n    },\n    onToken: ({ id, text, delta }) => {\n      console.log(`[${id}] Token:`, delta);\n    },\n    onRetry: ({ id, attempt, waitMs, reason }) => {\n      console.log(`[${id}] Retry attempt ${attempt} in ${waitMs}ms: ${reason}`);\n    },\n    onCost: ({ id, costUSD }) => {\n      console.log(`[${id}] Cost: $${costUSD.toFixed(4)}`);\n    },\n    onGuard: ({ id, tool, ok, diagnostics }) => {\n      console.log(`[${id}] Guard ${tool}:`, ok ? \"passed\" : \"failed\", diagnostics);\n    },\n  },\n});\n```\n\n### With Provider Configuration\n\n```typescript\nconst ai = createAiSdk({\n  provider: {\n    // Custom fetch implementation\n    fetch: customFetch,\n    // Base URL for API calls\n    baseURL: \"https://api.custom-provider.com\",\n    // Additional headers\n    headers: {\n      \"X-API-Key\": \"your-api-key\",\n      \"X-Organization\": \"your-org\",\n    },\n  },\n});\n```\n\n### Complete Example\n\n```typescript\nimport { createAiSdk } from \"@braingrid/sdk\";\nimport { createGuard, ajvAdapter } from \"@braingrid/json-guard\";\n\nconst ai = createAiSdk({\n  // JSON validation for tool calls\n  jsonGuard: {\n    guard: createGuard(),\n    resolveSchema: (event) => {\n      // Return appropriate schema based on tool\n    },\n  },\n\n  // Custom provider settings\n  provider: {\n    baseURL: process.env.AI_API_URL,\n    headers: {\n      \"X-API-Key\": process.env.AI_API_KEY,\n    },\n  },\n\n  // Retry configuration (requires @braingrid/llm-retry - OUT OF SCOPE)\n  retry: {\n    maxAttempts: 3,\n    backoffMs: 1000,\n  },\n\n  // Cost tracking (requires @braingrid/cost-tracker - OUT OF SCOPE)\n  cost: {\n    pricing: {\n      \"gpt-4o\": { promptCost: 0.01, completionCost: 0.03 },\n    },\n  },\n\n  // Lifecycle hooks for monitoring\n  hooks: {\n    afterCall: async ({ latencyMs, usage }) => {\n      metrics.record(\"ai.call\", { latencyMs, ...usage });\n    },\n    onCost: ({ costUSD }) => {\n      metrics.increment(\"ai.cost\", costUSD);\n    },\n  },\n});\n\n// Use the SDK normally\nconst response = await ai.generateText({\n  model: \"gpt-4o\",\n  prompt: \"Explain quantum computing\",\n});\n```\n\n## API Reference\n\n### `createAiSdk(options?)`\n\nCreates an AI SDK instance with optional integrations.\n\n#### Options\n\n- `jsonGuard` - **Fully functional** JSON Guard integration for tool validation\n  - `guard` - Guard instance from `@braingrid/json-guard`\n  - `resolveSchema` - Function to resolve schemas for tool validation\n- `retry` - Retry configuration (planned for future @braingrid/llm-retry)\n- `logger` - Logger configuration (planned for future @braingrid/logger)\n- `cost` - Cost tracking configuration (planned for future @braingrid/cost-tracker)\n- `provider` - Custom provider configuration\n  - `fetch` - Custom fetch implementation\n  - `baseURL` - Base URL for API calls\n  - `headers` - Additional headers to inject\n- `hooks` - Lifecycle hooks\n  - `beforeCall` - Called before making an SDK call\n  - `afterCall` - Called after an SDK call completes\n  - `onRetry` - Called when a retry occurs\n  - `onToken` - Called for each token in a stream\n  - `onCost` - Called when cost is calculated\n  - `onGuard` - Called when json-guard processes tool arguments\n\n#### Returns\n\nAn `AiSdk` instance with the same API as Vercel's `ai` package, including:\n- `generateText` - Generate text using an LLM\n- `streamText` - Stream text from an LLM\n- All other exports from the `ai` package (via proxy)\n\n## Feature Status\n\n### Fully Functional\n- ✅ **JSON Guard Integration** - Validates and repairs tool arguments using `@braingrid/json-guard`\n- ✅ **Provider Configuration** - Custom fetch, baseURL, and headers\n- ✅ **Lifecycle Hooks** - Complete monitoring via beforeCall, afterCall, onToken, onGuard\n\n### Planned (Future Packages)\nThe following features are **planned** but not yet implemented:\n- ⏳ `@braingrid/llm-retry` - Retry logic with configurable backoff\n- ⏳ `@braingrid/logger` - Structured logging\n- ⏳ `@braingrid/cost-tracker` - Token usage and cost tracking\n\nConfiguration for these planned features is accepted but will no-op gracefully until the packages are available.\n\n## License\n\nApache-2.0","readmeFilename":"README.md","homepage":"https://github.com/BrainGridAI/ai-kit/tree/main/packages/sdk#readme","repository":{"type":"git","url":"git+https://github.com/BrainGridAI/ai-kit.git","directory":"packages/sdk"},"author":{"name":"BrainGrid AI, Inc."},"bugs":{"url":"https://github.com/BrainGridAI/ai-kit/issues"},"license":"Apache-2.0"}