AI Platform

AxilJS AI Providers

Configure OpenAI, Anthropic (Claude), Gemini, and Ollama in AxilJS: default models, retries, timeouts, and one API for completions, streaming, and embeddings.

5 min readUpdated DocumentationEdit this page
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

ProviderAxilJS ProviderPrimary configurationDefault chat modelDefault embedding model
OpenAIOpenAIProviderapiKeygpt-4o-minitext-embedding-3-small
AnthropicAnthropicProviderapiKeyclaude-haiku-4-5-20251001none (no embeddings API)
GeminiGeminiProviderapiKeygemini-1.5-flashtext-embedding-004
OllamaOllamaProvidermodel (local)llama3.2nomic-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.

TypeScript
TS
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.

TypeScript
TS
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.

TypeScript
TS
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.

TypeScript
TS
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:

OptionDefaultDescription
baseUrlprovider's public API (Ollama: http://localhost:11434)API base URL
timeoutMs60000 (Ollama: 120000)Per-attempt socket idle timeout in milliseconds
maxRetries2Retries on retryable errors; 0 disables retries
retryBaseDelayMs500Base delay for exponential backoff with jitter

Unified AI API

All supported providers expose the same core operations:

TypeScript
TS
ai.complete()
ai.stream()
ai.embed()

For example, a completion request uses the same interface regardless of which provider is configured:

TypeScript
TS
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.

Application
@axiljs/ai
Provider Interface
OpenAIAnthropicGeminiOllama

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:

TypeScript
TS
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.

TypeScript
TS
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?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY