AI Service

ObjectOS adds an in-product AI runtime — the ask data-query assistant, the build authoring assistant, and the /api/v1/ai/* chat endpoints — on top of AI primitives that ship in the open-source ObjectStack framework: the MCP server, the Knowledge Protocol and its adapters, and the embedder.

On a Self-Managed deployment, a license is what unlocks the in-product AI. A single-organization deployment without one runs with Community behaviour — the open MCP server, bring your own AI — and with one, the AI Builder and "ask your data" are unlocked on your own infrastructure. See Docker → License.

What is configured where

Chat model provider

There is no AI package to install or register. @objectstack/service-ai left the open ObjectStack distribution in 11.0; the AI runtime it provides ships with ObjectOS, not with the open-source framework.

The provider, model and credentials are settings in the ai namespace, so they resolve like every other setting: an environment variable wins over the value stored in Setup, and locks it (System Settings → Resolution order).

For example, to lock a third-party OpenAI-compatible provider for the whole deployment without using Setup:

OS_AI_PROVIDER=openai
OS_AI_OPENAI_API_KEY=sk-...
OS_AI_OPENAI_MODEL=your-model
OS_AI_OPENAI_BASE_URL=https://your-provider.example.com/v1

Use OS_AI_OPENAI_BASE_URL for an OpenAI-compatible base URL, or the same field in Setup; OPENAI_BASE_URL is not a platform-level variable.

When no provider is set

The runtime picks an adapter at boot from the first upstream credential it finds:

1. AI_GATEWAY_MODEL (with AI_GATEWAY_API_KEY), through the Vercel AI Gateway;
2. OPENAI_API_KEY;
3. ANTHROPIC_API_KEY;
4. GOOGLE_GENERATIVE_AI_API_KEY;
5. none of them: MemoryLLMAdapter, an echo mode with no real provider behind it.

These keep their upstream names; they are not renamed to OS_*. OS_AI_MODEL overrides the model id for the direct OpenAI, Anthropic and Google detection. After boot, the runtime reads the ai settings namespace and swaps the adapter when the provider comes from an environment variable or a value stored in Setup.

Calling it

The in-product AI is served under /api/v1/ai/* — chat (JSON or streaming), completion, the models an environment offers, and conversations — and the @objectstack/client SDK reaches it through its ai namespace: ai.chat, ai.chatStream, ai.complete, ai.models, and ai.conversations. For declarative AI — agents, skills, and tools — see AI Agents.

Embedders

@objectstack/embedder-openai works against any endpoint that speaks the OpenAI POST /v1/embeddings shape: OpenAI, Azure OpenAI, DashScope, Zhipu BigModel, SiliconFlow, Doubao, MiniMax, Ollama, or your own gateway. A preset fills in the base URL of a known provider; baseUrl points at any other endpoint.

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

const embedder = createOpenAIEmbedder({
  preset: 'dashscope',
  apiKey: process.env.DASHSCOPE_API_KEY!,
  model: 'text-embedding-v3',
});

apiKey is required. The package README lists the base URL and a typical model for each provider.

No knowledge adapter in the open framework consumes an embedder yet: @objectstack/knowledge-memory and @objectstack/knowledge-ragflow take no embedder option.

Knowledge / RAG

The knowledge service declares knowledge sources and filters what comes back by permission; an adapter plugin does the retrieval itself.

In the open framework the wiring is:

import { KnowledgeServicePlugin } from '@objectstack/service-knowledge';
import { KnowledgeRagflowPlugin } from '@objectstack/knowledge-ragflow';

kernel.use(new KnowledgeServicePlugin({
  sources: [{
    id: 'product_docs',
    label: 'Product documentation',
    adapter: 'ragflow',
    source: { kind: 'http', urls: ['https://docs.example.com/sitemap.xml'] },
    adapterConfig: { datasetId: 'rgf_doc_dataset_id' }, // RAGFlow dataset to bind
  }],
}));
kernel.use(new KnowledgeRagflowPlugin({
  endpoint: process.env.RAGFLOW_ENDPOINT!, // e.g. http://localhost:9380
  apiKey: process.env.RAGFLOW_API_KEY!,
}));

The RAGFlow adapter does not create datasets: create one once in the RAGFlow UI, where you pick the chunking method, embedding model, and rerank policy.

Every hit that carries a source record is re-checked against the caller's permissions — the same row-level security that gates a plain ObjectQL query. Exposing retrieval to the in-product chat as the search_knowledge tool is part of the ObjectOS runtime.

MCP — Model Context Protocol

Every ObjectOS deployment already serves the Model Context Protocol at /api/v1/mcp — on by default, no plugin to install — and can serve it over stdio as well. Connect AI Tools (MCP) covers connecting a client, the stdio switch, and the tools an agent gets.

Registering the MCP server plugin explicitly, in the open framework:

import { MCPServerPlugin } from '@objectstack/mcp';

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

Tools are not opted into per option: the plugin bridges the AI tool registry, the metadata service and the data engine when it starts. Every call runs under the calling user's permissions.

Where to go next

• AI Agents — declarative agents, skills, and tools
• Connect AI Tools (MCP) — point an external client at your app
• System Settings — how a setting resolves, and what an environment variable locks
• Security & Compliance — how AI data flows are isolated
• @objectstack/embedder-openai source
• @objectstack/service-knowledge source
• @objectstack/knowledge-ragflow source
• @objectstack/mcp source