AI Service

ObjectOS treats AI as a first-class capability with three pluggable layers:

All three are optional, all three are provider-agnostic, and all three can be reconfigured at runtime from Console → Configuration without a restart.

Chat / generation

Powered by the Vercel AI SDK. Install the provider(s) you want as peer deps:

pnpm add @ai-sdk/openai          # OpenAI
pnpm add @ai-sdk/anthropic       # Claude
pnpm add @ai-sdk/google          # Gemini
pnpm add @ai-sdk/gateway         # AI gateway / OpenRouter / proxies

Then register the service with one or more models:

import { ServiceAI } from '@objectstack/service-ai';
import { openai }     from '@ai-sdk/openai';
import { anthropic }  from '@ai-sdk/anthropic';

ServiceAI.configure({
  defaultModel: 'fast',
  models: {
    fast:     openai('gpt-4o-mini'),
    smart:    openai('gpt-4o'),
    claude:   anthropic('claude-3-5-sonnet-latest'),
  },
  enableStreaming: true,
  maxHistoryLength: 50,
});

Provider API keys come from each SDK's normal env vars:

In Console you can paste these as runtime settings instead — they go through the same precedence (env > settings) but live editing means no restart.

Using the AI service from code

const ai = kernel.getService<IAIService>('ai');

const convo = await ai.createConversation({
  model: 'smart',
  systemPrompt: 'You are a helpful assistant.',
});

const reply = await ai.sendMessage({
  conversationId: convo.id,
  message: 'Summarize ObjectStack in two sentences.',
});

Using it from a flow

The automation capability exposes an ai_call step type:

{
  type: 'action',
  action: 'ai_call',
  inputs: {
    model:   'fast',
    prompt:  'Categorize this ticket: {!trigger.record.subject}',
    schema:  { category: 'string', priority: 'string' },
  },
  output: 'classified',
}

See Flows & Automation for the surrounding context.

Embedders

The embedder service converts text to dense vectors. ObjectStack ships adapters for many providers — chosen because the embedding landscape moves fast and your "best" choice depends on cost, latency, and language.

Configure in code:

import { ServiceEmbedder }      from '@objectstack/service-embedder';
import { OpenAIEmbedderPlugin } from '@objectstack/embedder-openai';

ServiceEmbedder.configure({ defaultModel: 'small' });
// then register the adapter plugin:
new OpenAIEmbedderPlugin({
  model: 'text-embedding-3-small',
  // OPENAI_API_KEY from env
});

Or pick at runtime from Console → Configuration → AI → Embedder. Switch providers without restart; existing vectors stay searchable (you can re-index in the background).

Knowledge / RAG

The knowledge service orchestrates document ingestion, chunking, embedding (via the embedder service), and retrieval. The actual storage and search backend is pluggable:

import { ServiceKnowledge }     from '@objectstack/service-knowledge';
import { TursoKnowledgePlugin } from '@objectstack/knowledge-turso';

ServiceKnowledge.configure();
new TursoKnowledgePlugin({
  databaseUrl: process.env.TURSO_DATABASE_URL,
  authToken:   process.env.TURSO_AUTH_TOKEN,
});

Indexed knowledge bases become first-class objects — query them from flows, surface them in Console, attach them to AI assistants as retrieval context.

MCP — Model Context Protocol

ObjectOS can expose itself as a tool server to AI agents (Claude Desktop, IDEs, custom agents) via the open Model Context Protocol.

import { McpServerPlugin } from '@objectstack/plugin-mcp-server';

new McpServerPlugin({
  // expose specific objects + actions as MCP tools
  expose: ['todo_task', 'support_ticket'],
});

Agents discover and invoke ObjectOS actions through MCP — subject to the calling user's permission set. The MCP server also exposes a small set of universal tools: search_records, get_record, create_record, invoke_action.

Operational guarantees

• No mandatory cloud dependency. Use Ollama for chat + Ollama embedder + memory knowledge — entirely air-gapped.
• Live swappable. Change provider in Console; new requests use the new provider on next call. No restart.
• Per-tenant config. Each Environment has its own AI settings. Tenant A on OpenAI, tenant B on Anthropic — same runtime.
• Audit log entries. Every conversation, tool call, and embedder request can be audited (@objectstack/plugin-audit).
• Cost-aware. Token counts and provider IDs flow through to the audit log for chargeback / cost analysis.

Where to go next

• Flows & Automation — call AI from declarative business logic
• Marketplace — AI-powered apps in the default catalog
• Security & Compliance — how AI data flows are isolated
• @objectstack/service-ai source
• @objectstack/service-embedder source
• @objectstack/service-knowledge source