feat: extend adapter and create custom model utilities #184
Conversation
📝 WalkthroughWalkthroughThis PR introduces adapter extension utilities that allow developers to extend existing adapter factories with custom models. New utilities include Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
View your CI Pipeline Execution ↗ for commit 0dd7195
☁️ Nx Cloud last updated this comment at |
@tanstack/ai
@tanstack/ai-anthropic
@tanstack/ai-client
@tanstack/ai-devtools-core
@tanstack/ai-gemini
@tanstack/ai-ollama
@tanstack/ai-openai
@tanstack/ai-react
@tanstack/ai-react-ui
@tanstack/ai-solid
@tanstack/ai-solid-ui
@tanstack/ai-svelte
@tanstack/ai-vue
@tanstack/ai-vue-ui
@tanstack/react-ai-devtools
@tanstack/solid-ai-devtools
commit: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
docs/guides/extend-adapter.md (2)
12-13: Minor formatting: add space after comma for consistency.The code style in the example is inconsistent with other examples in this file.
🔎 Suggested fix
-const myOpenaiModel = createModel('my-fine-tuned-gpt4',['text', 'image']); -const myOpenaiModelButCooler = createModel('my-fine-tuned-gpt5',['text', 'image']); +const myOpenaiModel = createModel('my-fine-tuned-gpt4', ['text', 'image']); +const myOpenaiModelButCooler = createModel('my-fine-tuned-gpt5', ['text', 'image']);
61-65: Consider addingas constto demonstrate proper tuple inference.Without
as const, the array type will be inferred asExtendedModelDef[]rather than a tuple, which may not provide the expected literal type inference for model names.🔎 Suggested fix
const models = [ createModel('text-only-model', ['text']), createModel('multimodal-model', ['text', 'image', 'audio']), -] as const +] as const // Required for literal type inferenceNote: The
as constis already present, but a brief inline comment would help clarify why it's necessary.packages/typescript/ai/tests/extend-adapter.test.ts (1)
198-222: Consider clarifying the type test comment.The comment says "should infer custom model name type" but the assertion checks that
adapter.modelextendsMockModel. This is expected behavior (the returned adapter type comes from the original factory), but the comment could be clearer about what's actually being verified.🔎 Suggested clarification
describe('Type inference for custom models', () => { - it('should infer custom model name type', () => { + it('should return adapter with original factory return type', () => { const extendedMock = extendAdapter(mockText, customModels) const adapter = extendedMock('my-fine-tuned-model') - // The adapter model type is the union of all possible models from the factory return - // (This is expected since extendAdapter returns the factory's return type) + // The adapter's model property type comes from the original factory's return type + // Custom model names are accepted as input but the return type is InferAdapterReturn<TFactory> expectTypeOf(adapter.model).toExtend<MockModel>() })
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
docs/guides/extend-adapter.mdpackages/typescript/ai-anthropic/src/index.tspackages/typescript/ai-gemini/src/index.tspackages/typescript/ai-openai/src/index.tspackages/typescript/ai/src/extend-adapter.tspackages/typescript/ai/src/index.tspackages/typescript/ai/tests/extend-adapter.test.ts
🧰 Additional context used
📓 Path-based instructions (4)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx}: Use tree-shakeable adapter architecture for provider implementations - export specialized adapters (text, embedding, summarize, image) as separate imports from/adapterssubpath rather than monolithic adapters
Use Zod for runtime schema validation and type inference, particularly for tool input/output definitions withtoolDefinition()and Zod schema inference
Implement isomorphic tool system usingtoolDefinition()with.server()and.client()implementations for dual-environment execution
Use type-safe per-model configuration with provider options typed based on selected model to ensure compile-time safety
Implement stream processing with StreamProcessor for handling chunked responses and support partial JSON parsing for streaming AI responses
Files:
packages/typescript/ai-openai/src/index.tspackages/typescript/ai-anthropic/src/index.tspackages/typescript/ai-gemini/src/index.tspackages/typescript/ai/tests/extend-adapter.test.tspackages/typescript/ai/src/index.tspackages/typescript/ai/src/extend-adapter.ts
packages/typescript/*/src/index.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Export tree-shakeable adapters with clear subpath exports in package.json (e.g.,
@tanstack/ai/adapters,@tanstack/ai-openai/adapters) to minimize bundle size
Files:
packages/typescript/ai-openai/src/index.tspackages/typescript/ai-anthropic/src/index.tspackages/typescript/ai-gemini/src/index.tspackages/typescript/ai/src/index.ts
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (CLAUDE.md)
Use camelCase for function and variable names throughout the codebase
Files:
packages/typescript/ai-openai/src/index.tspackages/typescript/ai-anthropic/src/index.tspackages/typescript/ai-gemini/src/index.tspackages/typescript/ai/tests/extend-adapter.test.tspackages/typescript/ai/src/index.tspackages/typescript/ai/src/extend-adapter.ts
**/*.test.ts
📄 CodeRabbit inference engine (CLAUDE.md)
Write unit tests using Vitest alongside source files with
.test.tsnaming convention
Files:
packages/typescript/ai/tests/extend-adapter.test.ts
🧠 Learnings (7)
📓 Common learnings
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to packages/typescript/*/src/adapters/*.ts : Create individual adapter implementations for each provider capability (text, embed, summarize, image) with separate exports to enable tree-shaking
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to **/*.{ts,tsx} : Use tree-shakeable adapter architecture for provider implementations - export specialized adapters (text, embedding, summarize, image) as separate imports from `/adapters` subpath rather than monolithic adapters
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to packages/typescript/*/src/model-meta.ts : Maintain model metadata files that define provider options and capabilities per model for per-model type safety
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to **/*.{ts,tsx} : Use type-safe per-model configuration with provider options typed based on selected model to ensure compile-time safety
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to packages/typescript/*/src/index.ts : Export tree-shakeable adapters with clear subpath exports in package.json (e.g., `tanstack/ai/adapters`, `tanstack/ai-openai/adapters`) to minimize bundle size
📚 Learning: 2025-12-13T17:09:09.794Z
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to packages/typescript/*/src/model-meta.ts : Maintain model metadata files that define provider options and capabilities per model for per-model type safety
Applied to files:
packages/typescript/ai-openai/src/index.tspackages/typescript/ai-anthropic/src/index.tspackages/typescript/ai-gemini/src/index.tsdocs/guides/extend-adapter.mdpackages/typescript/ai/tests/extend-adapter.test.tspackages/typescript/ai/src/index.tspackages/typescript/ai/src/extend-adapter.ts
📚 Learning: 2025-12-13T17:09:09.794Z
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to packages/typescript/*/src/index.ts : Export tree-shakeable adapters with clear subpath exports in package.json (e.g., `tanstack/ai/adapters`, `tanstack/ai-openai/adapters`) to minimize bundle size
Applied to files:
packages/typescript/ai-openai/src/index.tspackages/typescript/ai-anthropic/src/index.tspackages/typescript/ai-gemini/src/index.tspackages/typescript/ai/tests/extend-adapter.test.tspackages/typescript/ai/src/index.tspackages/typescript/ai/src/extend-adapter.ts
📚 Learning: 2025-12-13T17:09:09.794Z
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to **/*.{ts,tsx} : Use type-safe per-model configuration with provider options typed based on selected model to ensure compile-time safety
Applied to files:
packages/typescript/ai-anthropic/src/index.tsdocs/guides/extend-adapter.mdpackages/typescript/ai/src/extend-adapter.ts
📚 Learning: 2025-12-13T17:09:09.794Z
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to packages/typescript/*/src/adapters/*.ts : Create individual adapter implementations for each provider capability (text, embed, summarize, image) with separate exports to enable tree-shaking
Applied to files:
packages/typescript/ai-gemini/src/index.tsdocs/guides/extend-adapter.mdpackages/typescript/ai/tests/extend-adapter.test.tspackages/typescript/ai/src/index.tspackages/typescript/ai/src/extend-adapter.ts
📚 Learning: 2025-12-13T17:09:09.794Z
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to **/*.{ts,tsx} : Use tree-shakeable adapter architecture for provider implementations - export specialized adapters (text, embedding, summarize, image) as separate imports from `/adapters` subpath rather than monolithic adapters
Applied to files:
packages/typescript/ai-gemini/src/index.tsdocs/guides/extend-adapter.mdpackages/typescript/ai/tests/extend-adapter.test.tspackages/typescript/ai/src/index.tspackages/typescript/ai/src/extend-adapter.ts
📚 Learning: 2025-12-13T17:09:09.794Z
Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to **/*.test.ts : Write unit tests using Vitest alongside source files with `.test.ts` naming convention
Applied to files:
packages/typescript/ai/tests/extend-adapter.test.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Preview
- GitHub Check: Test
🔇 Additional comments (10)
packages/typescript/ai-openai/src/index.ts (1)
82-88: LGTM!The new
OPENAI_CHAT_MODELSexport follows the existing pattern and aligns with the tree-shakeable architecture. This enables consumers to access chat model metadata for use with the newextendAdapterutilities.packages/typescript/ai-anthropic/src/index.ts (1)
31-31: LGTM!The
ANTHROPIC_MODELSexport is consistent with the pattern used in other provider packages.packages/typescript/ai-gemini/src/index.ts (1)
55-59: LGTM!The new
GEMINI_MODELSexport provides consistency with other provider packages (ANTHROPIC_MODELS,OPENAI_CHAT_MODELS) while the existingGeminiTextModelsalias is preserved for backward compatibility.packages/typescript/ai/tests/extend-adapter.test.ts (2)
1-19: LGTM!Comprehensive test suite with clear documentation of what's being verified. Good use of type-level testing with
expectTypeOfalongside runtime assertions.
76-119: Mock adapter implementation is well-structured.The mock accurately represents the per-model type patterns (provider options and input modalities by model name) used by real adapters like OpenAI. The eslint-disable comments for
@typescript-eslint/require-awaitare acceptable for async generator mocks.packages/typescript/ai/src/index.ts (1)
115-118: LGTM!The new exports follow the established patterns: runtime values exported directly, types exported with
typekeyword. The grouping under "Adapter extension utilities" is clear and maintains the file's organization.packages/typescript/ai/src/extend-adapter.ts (4)
61-70: LGTM!Good use of
constgeneric modifiers to preserve literal types without requiring callers to useas const. ThemodelOptions: {} as unknownis appropriate since it's only used as a type brand.
91-98: Type fallback behavior is reasonable.The fallback to
stringwhen model type can't be inferred provides a safe default. This ensures the utility works even with unconventional factory signatures, though the extended model union won't provide type safety in those edge cases.
166-182: Clean implementation with appropriate type-level design.The runtime passthrough (
return factory as any) is intentional per the documented behavior - all validation happens at compile time. The_customModelsparameter is correctly prefixed to indicate it's unused at runtime but required for type inference.One consideration: if a user passes an invalid custom model name at runtime, the error will come from the underlying provider API rather than this utility. This is documented in the guide but worth noting.
103-108: No changes needed. TheInferConfigutility correctly returnsundefinedwhen a factory has no config parameter, and the conditional spread (lines 174-176) properly handles this case by using an empty args array. This behavior is already tested in the codebase with factories likeollamaTextthat accept only a model parameter without optional config.
🎯 Changes
✅ Checklist
pnpm run test:pr.🚀 Release Impact
Summary by CodeRabbit
New Features
Documentation
Tests
✏️ Tip: You can customize this high-level summary in your review settings.