{"_id":"@ank1015/llm-types","_rev":"3-6650522f71a61bf04eb0eecb3e6767fd","name":"@ank1015/llm-types","dist-tags":{"latest":"0.0.3"},"versions":{"0.0.1":{"name":"@ank1015/llm-types","version":"0.0.1","keywords":["llm","types","typescript"],"license":"MIT","_id":"@ank1015/llm-types@0.0.1","maintainers":[{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"}],"dist":{"shasum":"3fbb8f05a1abb611c646a2baf6bcf6f5a56d02b5","tarball":"https://registry.npmjs.org/@ank1015/llm-types/-/llm-types-0.0.1.tgz","fileCount":94,"integrity":"sha512-suJEOq69T61DZcDDeVQZe8hLByPdkLMLybTXkB8WpFvvTnmGo7F+oMN0A0GTm50vNf852dvMD/AdW3vewpEckA==","signatures":[{"sig":"MEUCIHLN3T3fNbwdywuC612D65BlMzxuLfCTGnki3j4C8BI7AiEApq2dtm6kkBCNCcCJqthp9zN3m3qBKhiMvsx27m9WKAE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":92556},"main":"./dist/index.js","type":"module","_from":"file:ank1015-llm-types-0.0.1.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"dev":"tsc --watch","lint":"echo 'No linter configured yet'","build":"tsc","clean":"rm -rf dist *.tsbuildinfo","typecheck":"tsc --noEmit"},"_npmUser":{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"},"_resolved":"/private/var/folders/1n/t7lbn2t179zg_xjbmn62ypmr0000gn/T/1065edefc3fe3e3fbade1d9a225bd5fe/ank1015-llm-types-0.0.1.tgz","_integrity":"sha512-suJEOq69T61DZcDDeVQZe8hLByPdkLMLybTXkB8WpFvvTnmGo7F+oMN0A0GTm50vNf852dvMD/AdW3vewpEckA==","_npmVersion":"11.6.2","description":"Type definitions for LLM SDK","directories":{},"_nodeVersion":"25.2.1","_hasShrinkwrap":false,"devDependencies":{"openai":"^6.17.0","@google/genai":"^1.39.0","@anthropic-ai/sdk":"^0.72.1","@sinclair/typebox":"^0.34.48"},"_npmOperationalInternal":{"tmp":"tmp/llm-types_0.0.1_1772789854830_0.32734824769979265","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@ank1015/llm-types","version":"0.0.2","keywords":["contracts","llm","sdk","ai","types","typescript"],"license":"MIT","_id":"@ank1015/llm-types@0.0.2","maintainers":[{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"}],"homepage":"https://github.com/ank1015/llm/tree/main/packages/types","bugs":{"url":"https://github.com/ank1015/llm/issues"},"dist":{"shasum":"519981754eb536268aa055eb92726ac1e81a416d","tarball":"https://registry.npmjs.org/@ank1015/llm-types/-/llm-types-0.0.2.tgz","fileCount":92,"integrity":"sha512-u7K3NNDqFDWWibM0fOaC7KNWNqk6RoeeJwkzYu+qbWpTUZw3KSMez1BaKo16XTURkVvkjbcCCHOPT59Y5E9B1w==","signatures":[{"sig":"MEUCIQDlmoda/LNHOcwp4qO3QWNF94yoMN+MmvIalpvpMSnF9AIgFaib3W1CO1kaLXZKUViGmlWnFQfMNU27/FQvE8P10ko=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":95096},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"a26e4bebbd7d4288de908d033f17638c0258f71d","scripts":{"dev":"tsc --watch","lint":"echo 'No linter configured yet'","build":"rm -rf dist *.tsbuildinfo && tsc","clean":"rm -rf dist *.tsbuildinfo","typecheck":"tsc --noEmit"},"_npmUser":{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"},"repository":{"url":"git+https://github.com/ank1015/llm.git","type":"git","directory":"packages/types"},"_npmVersion":"11.6.2","description":"Shared contracts and provider-native types for @ank1015/llm","directories":{},"sideEffects":false,"_nodeVersion":"25.2.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"openai":"^6.27.0","@google/genai":"^1.44.0","@anthropic-ai/sdk":"^0.78.0","@sinclair/typebox":"^0.34.48"},"_npmOperationalInternal":{"tmp":"tmp/llm-types_0.0.2_1773522678576_0.2612430335653364","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@ank1015/llm-types","version":"0.0.3","description":"Shared contracts and provider-native types for @ank1015/llm","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"sideEffects":false,"keywords":["contracts","llm","sdk","ai","types","typescript"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/ank1015/llm.git","directory":"packages/types"},"homepage":"https://github.com/ank1015/llm/tree/main/packages/types","bugs":{"url":"https://github.com/ank1015/llm/issues"},"publishConfig":{"access":"public"},"devDependencies":{"@anthropic-ai/sdk":"^0.78.0","@google/genai":"^1.44.0","@sinclair/typebox":"^0.34.48","openai":"^6.27.0"},"scripts":{"build":"rm -rf dist *.tsbuildinfo && tsc","dev":"tsc --watch","typecheck":"tsc --noEmit","lint":"echo 'No linter configured yet'","clean":"rm -rf dist *.tsbuildinfo"},"_id":"@ank1015/llm-types@0.0.3","_integrity":"sha512-R9enJVK6h0TXiZaeBiI0X6/smA2yGR0lr586VZdRPnOTgDsA3yB+UnuAc5xTZDlB23d50SXYDKyXNuOtWYG6+Q==","_resolved":"/private/var/folders/1n/t7lbn2t179zg_xjbmn62ypmr0000gn/T/76efe5d685b3a62e96809aa28945d65e/ank1015-llm-types-0.0.3.tgz","_from":"file:ank1015-llm-types-0.0.3.tgz","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-R9enJVK6h0TXiZaeBiI0X6/smA2yGR0lr586VZdRPnOTgDsA3yB+UnuAc5xTZDlB23d50SXYDKyXNuOtWYG6+Q==","shasum":"35b0324272788d4eb578dfff22a72b13bc69d967","tarball":"https://registry.npmjs.org/@ank1015/llm-types/-/llm-types-0.0.3.tgz","fileCount":92,"unpackedSize":95299,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGOzdXmm8x52PRKhGWDlAHLqUb/ZLDsyXPXoOxW3DByNAiEAkcgQZEX3fzm5L/Pc6FJlAxOFAOxRb09LayDbFOwl134="}]},"_npmUser":{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"},"directories":{},"maintainers":[{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/llm-types_0.0.3_1774536113296_0.16405745693756946"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-06T09:37:34.707Z","modified":"2026-03-26T14:41:53.636Z","0.0.1":"2026-03-06T09:37:35.085Z","0.0.2":"2026-03-14T21:11:18.774Z","0.0.3":"2026-03-26T14:41:53.510Z"},"bugs":{"url":"https://github.com/ank1015/llm/issues"},"license":"MIT","homepage":"https://github.com/ank1015/llm/tree/main/packages/types","keywords":["contracts","llm","sdk","ai","types","typescript"],"repository":{"type":"git","url":"git+https://github.com/ank1015/llm.git","directory":"packages/types"},"description":"Shared contracts and provider-native types for @ank1015/llm","maintainers":[{"name":"ananya150","email":"ananyakhandelwal60@gmail.com"}],"readme":"# @ank1015/llm-types\n\nShared contracts for a multi-provider LLM SDK that **preserve native provider types** instead of flattening everything into a lowest-common-denominator abstraction.\n\nThis package is mostly compile-time types, with a very small shared runtime surface:\n\n- `KnownApis`\n- `isValidApi()`\n- `LLMError` and its subclasses\n\n## Why This Package Exists\n\nThe monorepo has packages that need the shared contracts without needing the full runtime implementation. For example:\n\n- `@ank1015/llm-core` implements provider calls and streaming\n- `@ank1015/llm-sdk` composes higher-level workflows on top\n- `@ank1015/llm-sdk-adapters` implements storage adapters and mostly needs interfaces, messages, sessions, and errors\n\nKeeping the contracts separate lets those packages share the same shapes without forcing all of them to depend on the provider runtime stack.\n\n## Philosophy\n\nMost multi-provider LLM libraries normalize both inputs and outputs so aggressively that provider-specific capabilities disappear.\n\nThis package takes a different approach:\n\n- **Provider options stay provider-native.** `OpenAIProviderOptions` stays close to the OpenAI Responses API. `AnthropicProviderOptions` stays close to Anthropic Messages. `GoogleProviderOptions` stays close to `@google/genai`.\n- **Native responses are preserved.** `BaseAssistantMessage<TApi>` always keeps the original provider response object in `message`.\n- **Normalized fields are added on top.** You still get provider-agnostic `content`, `usage`, `stopReason`, and streaming event shapes for UI and orchestration logic.\n\n## Installation\n\n```bash\npnpm add @ank1015/llm-types\n```\n\n## Supported Providers\n\n```typescript\ntype Api =\n  | 'openai'\n  | 'codex'\n  | 'google'\n  | 'deepseek'\n  | 'anthropic'\n  | 'claude-code'\n  | 'zai'\n  | 'kimi'\n  | 'minimax'\n  | 'cerebras'\n  | 'openrouter';\n```\n\nThe union is derived from `KnownApis`, so adding a provider in `src/api.ts` automatically updates the type and triggers exhaustiveness errors across consumers.\n\n## Core Types\n\n### `BaseAssistantMessage<TApi>`\n\nThe central response contract preserves both normalized and native data:\n\n```typescript\ninterface BaseAssistantMessage<TApi extends Api> {\n  role: 'assistant';\n  api: TApi;\n  id: string;\n  model: Model<TApi>;\n\n  // Normalized fields\n  content: AssistantResponse;\n  usage: Usage;\n  stopReason: StopReason;\n  timestamp: number;\n  duration: number;\n  errorMessage?: string;\n\n  // Provider-native response\n  message: NativeResponseForApi<TApi>;\n}\n```\n\n`NativeResponseForApi<TApi>` resolves to the real SDK response type:\n\n- `anthropic`, `claude-code`, `minimax` -> `Anthropic.Message`\n- `openai`, `codex` -> `OpenAI.Response`\n- `google` -> `GenerateContentResponse`\n- `deepseek`, `kimi`, `zai`, `cerebras`, `openrouter` -> `ChatCompletion`\n\n### `BaseAssistantEvent<TApi>`\n\nTyped streaming events cover the full assistant lifecycle:\n\n- `start`\n- `text_start` / `text_delta` / `text_end`\n- `thinking_start` / `thinking_delta` / `thinking_end`\n- `image_start` / `image_frame` / `image_end`\n- `toolcall_start` / `toolcall_delta` / `toolcall_end`\n- `done`\n- `error`\n\nEvery event includes the in-progress `BaseAssistantMessage<TApi>`.\n\n### `Content`\n\nUnified multimodal content blocks:\n\n```typescript\ntype Content = (TextContent | ImageContent | FileContent)[];\n```\n\n`ImageContent` also supports normalized generated-image metadata such as:\n\n- generation stage (`partial`, `thought`, `final`)\n- provider\n- provider item id\n- revised prompt\n- output size / quality / format / background\n\n### `Model<TApi>` and `Provider<TApi>`\n\n`Model<TApi>` is the shared model metadata contract:\n\n- `api`, `id`, `name`, `baseUrl`\n- `reasoning`\n- supported inputs\n- token pricing\n- `contextWindow`, `maxTokens`\n- `headers`\n- supported tool capabilities\n\n`Provider<TApi>` pairs a model with its provider-specific options.\n\n### `Tool` and `Context`\n\nTools use TypeBox schemas directly:\n\n```typescript\ninterface Tool<TParameters extends TSchema = TSchema> {\n  name: string;\n  description: string;\n  parameters: TParameters;\n}\n\ninterface Context {\n  messages: Message[];\n  systemPrompt?: string;\n  tools?: Tool[];\n}\n```\n\n## Provider Option Families\n\nThe current provider options fall into a few families:\n\n- **Anthropic Messages-compatible**\n  - `AnthropicProviderOptions`\n  - `ClaudeCodeProviderOptions`\n  - `MiniMaxProviderOptions`\n- **OpenAI Responses-compatible**\n  - `OpenAIProviderOptions`\n  - `CodexProviderOptions`\n- **Google GenAI-compatible**\n  - `GoogleProviderOptions`\n- **OpenAI Chat Completions-compatible**\n  - `DeepSeekProviderOptions`\n  - `KimiProviderOptions`\n  - `ZaiProviderOptions`\n  - `CerebrasProviderOptions`\n  - `OpenRouterProviderOptions`\n\nThe package preserves provider-specific extensions where needed, for example:\n\n- `CodexProviderOptions` requires `chatgpt-account-id`\n- `ClaudeCodeProviderOptions` uses `oauthToken`, `betaFlag`, and `billingHeader`\n- `KimiProviderOptions` and `ZaiProviderOptions` expose thinking config\n- `CerebrasProviderOptions` exposes reasoning format / effort controls\n\n## Type Maps\n\nCompile-time lookups connect `Api` to the right native response and options type:\n\n```typescript\ntype NativeResponseForApi<TApi extends Api> = ApiNativeResponseMap[TApi];\ntype OptionsForApi<TApi extends Api> = ApiOptionsMap[TApi];\ntype WithOptionalKey<T> = Omit<T, 'apiKey'> & { apiKey?: string };\n```\n\n## Agent Contracts\n\nThis package also defines the shared contracts for tool-using agents:\n\n- `AgentTool`\n- `AgentToolResult<T>`\n- `AgentState`\n- `AgentLoopConfig`\n- `AgentEvent`\n- `Attachment`\n- `QueuedMessage<T>`\n- `ToolExecutionContext`\n\nThese are shared here because they are part of the monorepo-wide contract surface, even though the runtime agent loop lives in `@ank1015/llm-core`.\n\n## Storage Contracts\n\nShared adapter and session types also live here:\n\n- `KeysAdapter`\n- `UsageAdapter`\n- `SessionsAdapter`\n- `SessionNode`, `Session`, `SessionSummary`, `BranchInfo`\n- `CreateSessionInput`, `AppendMessageInput`, `AppendCustomInput`, `UpdateSessionNameInput`\n\nThese contracts are consumed directly by packages like `@ank1015/llm-sdk-adapters`.\n\n## Error Classes\n\nMinimal shared runtime errors are exported so every package can throw and catch the same error types:\n\n- `LLMError`\n- `ApiKeyNotFoundError`\n- `CostLimitError`\n- `ContextLimitError`\n- `ConversationBusyError`\n- `ModelNotConfiguredError`\n- `SessionNotFoundError`\n- `InvalidParentError`\n- `PathTraversalError`\n\n## Adding a Provider\n\n1. Create `src/providers/<name>.ts` with native response and provider options types\n2. Add the provider string to `KnownApis` in `src/api.ts`\n3. Add it to `ApiNativeResponseMap` and `ApiOptionsMap` in `src/providers/index.ts`\n4. Re-export it from `src/providers/index.ts`\n5. Re-export it from `src/index.ts`\n\nTypeScript will surface exhaustiveness errors anywhere the new provider is not handled.\n\n## What Does and Doesn't Belong Here\n\nBelongs here:\n\n- Shared public contracts\n- Provider-native response and option types\n- Agent/storage/session interfaces\n- Small shared runtime primitives used across packages\n\nDoes not belong here:\n\n- API clients\n- Provider request execution\n- Streaming implementations\n- Model catalogs\n- Registry/dispatch logic\n\nThose live in `@ank1015/llm-core`.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}