AI Platform

AxilJS AI Platform Overview

The AxilJS AI platform for TypeScript and Node.js: LLM providers, streaming, embeddings, vector search, RAG, tool-calling agents, and MCP, with no SDKs.

5 min readUpdated DocumentationEdit this page
On this page10

The AxilJS AI platform provides a unified foundation for building AI applications with TypeScript and Node.js.

It brings together LLM provider abstraction, streaming, embeddings, vector search, retrieval-augmented generation (RAG), AI agents, and Model Context Protocol (MCP) integration under the @axiljs/ai package.

The provider abstraction lets applications work with different AI providers while keeping application-level AI code consistent.

What Is Included

AxilJS AI includes the following capabilities:

  • Provider abstraction — Connect to OpenAI, Anthropic, Gemini, and Ollama through a unified interface.
  • Streaming — Process AI responses token-by-token using streaming and SSE.
  • Embeddings — Convert text into numerical vectors for semantic search and retrieval workflows.
  • Vector store — Store and retrieve vectors for semantic search.
  • RAG pipeline — Index documents and query relevant information for AI applications.
  • Agents — Build ReAct-style AI agents that can reason and use tools.
  • MCP client — Connect AI applications and agents to external tools through Model Context Protocol.
  • Governance — Enforce token, cost and request budgets, redact personal data and secrets before they reach the model, and record responses for offline tests. See Governance.

These capabilities can be used independently or combined to build more advanced AI workflows. The providers talk to each API directly with Node.js built-in http and https modules, with no third-party SDKs.

Installation

❯npm install @axiljs/ai
❯pnpm add @axiljs/ai
❯yarn add @axiljs/ai
❯bun add @axiljs/ai

Quick Example

The @axiljs/ai package provides a common interface for interacting with supported AI providers.

For example, you can use the Ollama provider with a local model:

TypeScript
TS
1import { OllamaProvider } from '@axiljs/ai'
2
3const ai = new OllamaProvider({
4  model: 'llama3.2'
5})
6
7const res = await ai.complete({
8  messages: [
9    {
10      role: 'user',
11      content: 'What is AxilJS?'
12    }
13  ]
14})
15
16console.log(res.content)

The same completion interface can be used across the supported provider implementations. Default models are gpt-4o-mini (OpenAI), claude-haiku-4-5-20251001 (Anthropic), gemini-1.5-flash (Gemini), and llama3.2 (Ollama); pass model per call to use another, such as claude-opus-5-5 or claude-sonnet-5-5.

Changes in 0.3.5

  • Budgets — withBudget enforces token, cost and request limits per tenant and time window, checked before the provider is called. Calls over a limit fail with AIBudgetExceededError (429). See Governance.
  • Redaction — withRedaction masks, tokenizes or blocks e-mail addresses, phone numbers, card numbers, IBANs, API keys, JWTs and custom patterns before they reach the model, and can restore them in the answer. Blocked calls fail with AIPolicyViolationError (422). See Governance.
  • Recorded tests — recordingProvider and replayProvider record responses once and replay them with no network or API key. See Governance.
  • Middleware status codes — aiChat, aiEmbed and aiAgent now answer budget and policy errors with 429 (with Retry-After) and 422 instead of 500.

Changes in 0.3.3

Warning

Cosine similarity scores are now plain cosine similarity (-1 to 1) instead of (cos + 1) / 2. The RAGPipeline default minScore of 0.3 now actually filters unrelated chunks. If you set your own threshold t on the old scale, use 2t - 1 now. See RAG.

  • Short documents are indexed — a document shorter than the minimum chunk size becomes a single chunk instead of being skipped; the threshold is configurable with chunker.minChunkSize.
  • Separate embedding provider — RAGPipeline accepts embeddingProvider, so Claude can generate answers while OpenAI, Gemini, or Ollama produces embeddings (Anthropic has no embeddings API).
  • Logger option — RAGPipeline and Agent accept logger: omit it for the default console output, pass false for silence, or pass an object with info and warn.

Switch LLM Providers

AxilJS separates application-level AI logic from the underlying LLM provider.

This means you can switch providers without rewriting the application code that consumes the AI interface.

Application
@axiljs/ai
Provider abstraction
OpenAIAnthropicGeminiOllama

Provider selection can be changed through environment configuration, allowing the underlying model provider to change without requiring changes to the application-level AI logic.

AI Platform Architecture

The main AxilJS AI capabilities can be viewed as layers:

AxilJS AI
Providers
LLM models
AI runtime
Streaming
Embeddings
Vector store
RAG
Tools
Agents
MCP

Each capability addresses a different part of an AI application:

  • Providers handle access to LLMs.
  • Streaming handles incremental AI responses.
  • Embeddings convert text into vectors.
  • Vector stores support semantic retrieval.
  • RAG combines retrieval with AI generation.
  • Agents combine model reasoning with executable tools.
  • MCP provides an interface for integrating external tools.

Build AI Applications with AxilJS

The platform can be used for different levels of AI application complexity.

For a basic AI application, start with a provider and complete():

TypeScript
TS
1const res = await ai.complete({
2  messages: [
3    {
4      role: 'user',
5      content: 'What is AxilJS?'
6    }
7  ]
8})

For applications that need semantic retrieval, use embeddings and the RAG capabilities.

For applications that need autonomous multi-step tool execution, use Agents.

For applications that need external tool integration, use the MCP client.

Common Use Cases

AxilJS AI capabilities can be combined to build applications such as:

  • AI chat applications
  • AI assistants
  • Semantic search systems
  • Retrieval-augmented generation applications
  • Document question-answering systems
  • Tool-enabled AI agents
  • Multi-step AI workflows
  • Applications using local LLMs
  • Applications integrating external MCP tools

Explore the AI Platform

Start with Providers to understand the LLM provider abstraction.

Then explore Embeddings and RAG for retrieval-based AI applications.

For tool-enabled AI workflows, see Agents and MCP.

To control cost and keep personal data away from the model, see Governance.

Tip

Start with Providers, then explore RAG and Agents.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY