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 AI service plugin with a Vercel-SDK adapter:

import { AIServicePlugin, VercelLLMAdapter } from '@objectstack/service-ai';
import { openai } from '@ai-sdk/openai';

kernel.use(new AIServicePlugin({
  adapter: new VercelLLMAdapter({ model: openai('gpt-4o') }),
  models: [
    { id: 'fast',  provider: 'openai', model: 'gpt-4o-mini' },
    { id: 'smart', provider: 'openai', model: 'gpt-4o' },
  ],
  defaultModelId: 'fast',
}));

The models list feeds the runtime model registry — it drives default-model resolution and cost attribution in traces. By default the plugin also binds to the ai settings namespace and rebuilds the adapter live when an operator edits the provider/credentials/model in Console, so no restart is needed.

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');

// One-shot chat
const result = await ai.chat(
  [{ role: 'user', content: 'Summarize ObjectStack in two sentences.' }],
  { model: 'smart' },
);

// Structured output
const { object } = await ai.generateObject(
  [{ role: 'user', content: 'Classify this ticket: ...' }],
  { schema, model: 'fast' },
);

The service also exposes complete(), streamChat(), embed(), and listModels(). Conversations are persisted as ai_conversations / ai_messages records and managed over the REST API (POST /api/v1/ai/chat, POST /api/v1/ai/conversations).

Using it from agents and flows

For declarative AI — agents, skills, and tools — see AI Agents. Flows can invoke any registered action (including actions that wrap an ai.chat() / ai.generateObject() call) as an action node; see Flows & Automation for the surrounding context.

Embedders

The embedder converts text to dense vectors. A single OpenAI-compatible adapter, @objectstack/embedder-openai, covers OpenAI plus any provider that exposes an OpenAI-compatible /v1/embeddings endpoint — pick one with a preset (which sets the base URL for you) or point baseUrl at a custom endpoint.

Configure in code:

import { createOpenAIEmbedder } from '@objectstack/embedder-openai';

const embedder = createOpenAIEmbedder({
  preset: 'openai',
  model: 'text-embedding-3-small',
  // apiKey from OPENAI_API_KEY env if omitted
});

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 { KnowledgeServicePlugin } from '@objectstack/service-knowledge';
import { KnowledgeRagflowPlugin } from '@objectstack/knowledge-ragflow';

kernel.use(new KnowledgeServicePlugin({ defaultTopK: 10 }));
kernel.use(new KnowledgeRagflowPlugin({
  endpoint: process.env.RAGFLOW_ENDPOINT, // e.g. http://localhost:9380
  apiKey:   process.env.RAGFLOW_API_KEY,
}));

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';

kernel.use(new MCPServerPlugin({
  transport: 'stdio', // or 'http'
  autoStart: true,
}));

Agents discover and invoke ObjectOS tools through MCP — subject to the calling user's permissions. The server bridges the AI service's tool registry, including universal tools such as list_objects, describe_object, query_records, get_record, and aggregate_data.

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

• AI Agents — declarative agents, skills, and tools
• 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/embedder-openai source
• @objectstack/service-knowledge source