Open History to see the last commit
Type-Safe Multi-Adapter AI API#
This package provides complete TypeScript type safety for working with multiple AI providers, ensuring that you can only use models that are supported by each adapter.
Features#
- ✅ Adapter-specific model validation - TypeScript prevents using GPT models with Anthropic and vice versa
- ✅ Full autocomplete support - Your IDE suggests only valid models for the selected adapter
- ✅ Compile-time safety - Catch model incompatibilities before runtime
- ✅ Multi-adapter support - Use multiple AI providers in a single application
- ✅ Type inference - Model types are automatically inferred from adapter configuration
Installation#
npm install @tanstack/ai @tanstack/ai-openai @tanstack/ai-anthropic
Basic Usage#
Creating an AI instance with multiple adapters#
import { AI } from "@tanstack/ai";
import { OpenAIAdapter } from "@tanstack/ai-openai";
import { AnthropicAdapter } from "@tanstack/ai-anthropic";
const ai = new AI({
adapters: {
"openai": new OpenAIAdapter({
apiKey: process.env.OPENAI_API_KEY!,
}),
"anthropic": new AnthropicAdapter({
apiKey: process.env.ANTHROPIC_API_KEY!,
}),
},
});
Type-safe model selection#
// ✅ VALID - OpenAI with GPT model
await ai.chat({
adapter: "openai",
model: "gpt-4", // TypeScript knows this is valid
messages: [{ role: "user", content: "Hello!" }],
});
// ✅ VALID - Anthropic with Claude model
await ai.chat({
adapter: "anthropic",
model: "claude-3-5-sonnet-20241022", // TypeScript knows this is valid
messages: [{ role: "user", content: "Hello!" }],
});
// ❌ COMPILE ERROR - Wrong model for adapter
await ai.chat({
adapter: "anthropic",
model: "gpt-4", // TypeScript error: "gpt-4" not valid for Anthropic!
messages: [{ role: "user", content: "Hello!" }],
});
// ❌ COMPILE ERROR - Wrong model for adapter
await ai.chat({
adapter: "openai",
model: "claude-3-5-sonnet-20241022", // TypeScript error: Claude not valid for OpenAI!
messages: [{ role: "user", content: "Hello!" }],
});
Available Models#
OpenAI Models#
type OpenAIModel =
| "gpt-4"
| "gpt-4-turbo"
| "gpt-4-turbo-preview"
| "gpt-4o"
| "gpt-4o-mini"
| "gpt-3.5-turbo"
| "gpt-3.5-turbo-16k"
| "gpt-3.5-turbo-instruct"
| "text-embedding-ada-002"
| "text-embedding-3-small"
| "text-embedding-3-large";
Anthropic Models#
type AnthropicModel =
| "claude-3-5-sonnet-20241022"
| "claude-3-5-sonnet-20240620"
| "claude-3-opus-20240229"
| "claude-3-sonnet-20240229"
| "claude-3-haiku-20240307"
| "claude-2.1"
| "claude-2.0"
| "claude-instant-1.2";
API Methods#
All methods support the same type-safe adapter and model selection:
Chat Completion#
const result = await ai.chat({
adapter: "openai",
model: "gpt-4",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "What is TypeScript?" },
],
temperature: 0.7,
maxTokens: 500,
});
Streaming Chat#
for await (const chunk of ai.streamChat({
adapter: "anthropic",
model: "claude-3-5-sonnet-20241022",
messages: [{ role: "user", content: "Count from 1 to 5" }],
})) {
if (chunk.type === "content") {
process.stdout.write(chunk.delta);
}
}
Text Generation#
const result = await ai.generateText({
adapter: "openai",
model: "gpt-3.5-turbo-instruct",
prompt: "Write a haiku about TypeScript",
maxTokens: 100,
});
Summarization#
const result = await ai.summarize({
adapter: "anthropic",
model: "claude-3-haiku-20240307",
text: "Long text to summarize...",
style: "bullet-points",
maxLength: 200,
});
Embeddings#
const result = await ai.embed({
adapter: "openai",
model: "text-embedding-3-small",
input: "Text to embed",
});
Advanced Features#
Dynamic Adapter Addition#
const aiWithGemini = ai.addAdapter(
"gemini",
new GeminiAdapter({ apiKey: "..." })
);
// Now "gemini" is available with full type safety
await aiWithGemini.chat({
adapter: "gemini",
model: "gemini-pro", // Types updated automatically
messages: [{ role: "user", content: "Hello!" }],
});
Getting Available Adapters#
console.log(ai.adapterNames); // ["openai", "anthropic"]
Direct Adapter Access#
const openai = ai.getAdapter("openai");
console.log(openai.models); // Array of OpenAI models
Benefits#
1. Compile-Time Safety#
Before:
// Runtime error when deployed
await ai.chat({
provider: "anthropic",
model: "gpt-4", // Oops! Wrong model
});
// Error: Model 'gpt-4' not found for provider 'anthropic'
After:
// Compile-time error in your editor
await ai.chat({
adapter: "anthropic",
model: "gpt-4", // TypeScript error immediately
});
// Error: Type '"gpt-4"' is not assignable to type 'claude-...'
2. IDE Autocomplete#
When you type model:, your IDE will show you only the models available for the selected adapter:
- Select
openai→ See GPT models - Select
anthropic→ See Claude models
3. Refactoring Safety#
If you switch adapters, TypeScript will immediately flag any incompatible models:
// Change from OpenAI to Anthropic
await ai.chat({
adapter: "anthropic", // Changed this
model: "gpt-4", // TypeScript immediately flags this as an error
messages: [],
});
4. Self-Documenting Code#
The types serve as documentation - you can see all available models without checking docs:
// Hover over "model" to see all valid options
ai.chat({ adapter: "openai", model: /* hover here */ });
Creating Custom Adapters#
To create a custom adapter with type safety:
import { BaseAdapter } from "@tanstack/ai";
const MY_MODELS = ["my-model-1", "my-model-2", "my-model-3"] as const;
export class MyAdapter extends BaseAdapter<typeof MY_MODELS> {
name = "my-adapter";
models = MY_MODELS;
// Implement required methods...
}
Then use it with full type safety:
const ai = new AI({
adapters: {
"my-adapter": new MyAdapter({ apiKey: "..." }),
},
});
// TypeScript now knows about "my-model-1", "my-model-2", etc.
await ai.chat({
adapter: "my-adapter",
model: "my-model-1", // Autocomplete works!
messages: [],
});
Examples#
See the /examples directory for complete working examples:
model-safety-demo.ts- Comprehensive demonstration of type safetytype-safety-demo.ts- Quick reference showing valid and invalid usagemulti-adapter-example.ts- Real-world multi-adapter usage
TypeScript Configuration#
This package requires TypeScript 4.5 or higher for full type inference support.
License#
MIT