AxilJS AI Providers
Configure OpenAI, Anthropic (Claude), Gemini, and Ollama in AxilJS: default models, retries, timeouts, and one API for completions, streaming, and embeddings.
On this page11
AxilJS provides a unified AI provider interface for connecting TypeScript and Node.js applications to multiple large language model (LLM) providers.
The @axiljs/ai package provides integrations for OpenAI, Anthropic, Gemini, and Ollama with no third-party SDKs. All providers expose the same core AI operations, allowing application code to use complete(), stream(), and embed() consistently.
Supported AI Providers
| Provider | AxilJS Provider | Primary configuration | Default chat model | Default embedding model |
|---|---|---|---|---|
| OpenAI | OpenAIProvider | apiKey | gpt-4o-mini | text-embedding-3-small |
| Anthropic | AnthropicProvider | apiKey | claude-haiku-4-5-20251001 | none (no embeddings API) |
| Gemini | GeminiProvider | apiKey | gemini-1.5-flash | text-embedding-004 |
| Ollama | OllamaProvider | model (local) | llama3.2 | nomic-embed-text |
Every call accepts a model option to override the default. The hosted providers throw at construction time if apiKey is missing.
OpenAI
Use OpenAIProvider to connect AxilJS to OpenAI models.
1import { OpenAIProvider } from '@axiljs/ai'
2
3const ai = new OpenAIProvider({
4 apiKey: process.env.OPENAI_API_KEY!,
5 organization: process.env.OPENAI_ORG_ID // optional
6})baseUrl defaults to https://api.openai.com/v1 and can point to any OpenAI-compatible API.
Anthropic
Use AnthropicProvider to connect your application to Claude models.
1import { AnthropicProvider } from '@axiljs/ai'
2
3const ai = new AnthropicProvider({
4 apiKey: process.env.ANTHROPIC_API_KEY!
5})
6
7const res = await ai.complete({
8 model: 'claude-sonnet-5-5', // or 'claude-opus-5-5'; default: 'claude-haiku-4-5-20251001'
9 messages: [{ role: 'user', content: 'Hello!' }]
10})The provider works with any Messages API model. The default is claude-haiku-4-5-20251001; the current Claude models include claude-opus-5-5 and claude-sonnet-5-5, selected per call with model. maxTokens defaults to 4096.
Warning
Anthropic has no embeddings API, so AnthropicProvider.embed() always throws. Use OpenAIProvider, GeminiProvider, or OllamaProvider for embeddings. With RAGPipeline, keep Anthropic as provider and pass another provider as embeddingProvider (see RAG).
Gemini
Use GeminiProvider to connect AxilJS to Gemini.
1import { GeminiProvider } from '@axiljs/ai'
2
3const ai = new GeminiProvider({
4 apiKey: process.env.GOOGLE_API_KEY!
5})The example reads the Gemini API credential from the GOOGLE_API_KEY environment variable.
Ollama
AxilJS also supports Ollama for local AI model execution.
1import { OllamaProvider } from '@axiljs/ai'
2
3const ai = new OllamaProvider({
4 model: 'llama3.2', // default model for this instance
5 baseUrl: 'http://localhost:11434' // default
6})Unlike the hosted providers, Ollama needs no API key. Its model option sets the instance's default chat model (llama3.2 if omitted), and its per-attempt socket timeout defaults to 120 seconds because local models can be slow.
Common Provider Options
All providers accept these options in addition to their own:
| Option | Default | Description |
|---|---|---|
baseUrl | provider's public API (Ollama: http://localhost:11434) | API base URL |
timeoutMs | 60000 (Ollama: 120000) | Per-attempt socket idle timeout in milliseconds |
maxRetries | 2 | Retries on retryable errors; 0 disables retries |
retryBaseDelayMs | 500 | Base delay for exponential backoff with jitter |
Unified AI API
All supported providers expose the same core operations:
ai.complete()
ai.stream()
ai.embed()For example, a completion request uses the same interface regardless of which provider is configured:
1const result = await ai.complete({
2 messages: [
3 {
4 role: 'user',
5 content: 'What is AxilJS?'
6 }
7 ]
8})
9
10console.log(result.content)The provider-specific configuration is isolated when the ai instance is created. Tool calling (tools and toolChoice) also works on all four providers, so Agents run on any of them.
Provider Abstraction
The AxilJS provider architecture separates application logic from the underlying LLM service.
Your application uses the common AI API while the provider implementation handles communication with the selected LLM service.
Choosing a Provider
Use OpenAI, Anthropic, or Gemini when your application is designed around a hosted LLM provider.
Use Ollama when you want to run a supported model locally.
Because the application interacts with the provider through the common AxilJS API, changing providers does not require changing the basic complete(), stream(), or embed() calls. The exception is embeddings with Anthropic, which needs a second provider.
Retries, Cancellation, and Timeouts
All four providers retry HTTP 408, 409, 425, 429, and 5xx responses (including Anthropic's 529 "overloaded") and transient network errors, using exponential backoff with jitter and honoring retry-after / retry-after-ms headers. Streams are only retried before the first line is received.
Each call can also be cancelled or given an overall deadline:
1const controller = new AbortController()
2
3const res = await ai.complete({
4 messages,
5 signal: controller.signal, // abort() tears the HTTP request down (AbortError)
6 timeoutMs: 15_000 // overall deadline across retries (TimeoutError)
7})signal and timeoutMs work for stream() and embed() too. The per-call timeoutMs is independent of the provider-level timeoutMs, which stays a per-attempt socket idle timeout.
AI Provider Error Handling
A failed provider call rejects its promise; it does not crash the server. Non-2xx responses (after retries) reject with an AIHttpError that carries the HTTP status and the raw response body.
1import { AIHttpError } from '@axiljs/ai'
2
3try {
4 await ai.complete({ messages })
5} catch (err) {
6 if (err instanceof AIHttpError) {
7 console.error(err.status, err.body)
8 }
9}The HTTP handlers aiChat(), aiEmbed(), and aiAgent() catch these errors and respond with status 500 and an AI_ERROR error code. Since 0.3.5, errors that carry a 4xx status keep it: governance budget errors return 429 and policy violations return 422.
Tip
Keep provider credentials in environment variables rather than hard-coding API keys in application source code.
Was this page helpful?