feat: add Atlas Cloud LLM provider

CITATION.cff

@@ -1,7 +1,7 @@
 cff-version: 1.2.0
 message: "If you use AgentOS in your work, please cite it using this metadata."
 title: AgentOS
-abstract: "An Apache-2.0 TypeScript AI agent runtime: persistent cognitive memory, optional HEXACO personality, multi-agent orchestration, runtime tool forging, multimodal RAG, and one dispatch interface across 11 LLM providers."
+abstract: "An Apache-2.0 TypeScript AI agent runtime: persistent cognitive memory, optional HEXACO personality, multi-agent orchestration, runtime tool forging, multimodal RAG, and one dispatch interface across 12 LLM providers."
 type: software
 authors:
   - given-names: Johnny

README.md

@@ -8,7 +8,7 @@
 
 # **AgentOS** · TypeScript AI Agent Framework
 
-**Agents that remember, forge their own tools, and survive long-running sessions.** Persistent cognitive memory, optional HEXACO personality, multi-agent orchestration, and one dispatch interface across 11 LLM providers. Apache-2.0.
+**Agents that remember, forge their own tools, and survive long-running sessions.** Persistent cognitive memory, optional HEXACO personality, multi-agent orchestration, and one dispatch interface across 12 LLM providers. Apache-2.0.
 
 [![npm](https://img.shields.io/npm/v/@framers/agentos?style=flat-square&logo=npm&color=cb3837)](https://www.npmjs.com/package/@framers/agentos)
 [![CI](https://img.shields.io/github/actions/workflow/status/framerslab/agentos/ci.yml?branch=master&style=flat-square&logo=github&label=CI)](https://github.com/framerslab/agentos/actions/workflows/ci.yml)
@@ -33,7 +33,7 @@ AgentOS is an open-source TypeScript framework for AI agents that **remember, ad
 - **Top open-source memory benchmarks:** [85.6% on LongMemEval-S](https://github.com/framerslab/agentos-bench/blob/master/results/LEADERBOARD.md) at $0.0090/correct (gpt-4o), and 70.2% on LongMemEval-M, the only open-source library above 65% on M with reproducible methodology.
 - **Runtime tool forging.** An agent writes a TypeScript function with a Zod schema, an LLM judge approves it, and it runs in a hardened `node:vm` sandbox before joining the catalog for the rest of the session.
 - **Persistent [cognitive memory](https://docs.agentos.sh/features/cognitive-memory)** with 8 neuroscience-backed mechanisms: Ebbinghaus decay, retrieval-induced forgetting, reconsolidation, source-confidence decay.
-- **Optional [HEXACO personality](https://docs.agentos.sh/features/hexaco-personality)**, [6 orchestration strategies](https://docs.agentos.sh/features/agency-collaboration), [guardrails](https://docs.agentos.sh/features/guardrails-architecture), and [voice](https://docs.agentos.sh/features/voice-pipeline) across **11 LLM providers**; 100+ extensions and 88 skills auto-load at startup.
+- **Optional [HEXACO personality](https://docs.agentos.sh/features/hexaco-personality)**, [6 orchestration strategies](https://docs.agentos.sh/features/agency-collaboration), [guardrails](https://docs.agentos.sh/features/guardrails-architecture), and [voice](https://docs.agentos.sh/features/voice-pipeline) across **12 LLM providers**; 100+ extensions and 88 skills auto-load at startup.
 
 ---
 
@@ -178,7 +178,7 @@ Strategies: `sequential`, `parallel`, `debate`, `review-loop`, `hierarchical`, `
 
 | Package | Role |
 |---|---|
-| [`@framers/agentos`](https://www.npmjs.com/package/@framers/agentos) | Core runtime: agents, cognitive memory, orchestration, guardrails, voice, 11 LLM providers. Apache-2.0. |
+| [`@framers/agentos`](https://www.npmjs.com/package/@framers/agentos) | Core runtime: agents, cognitive memory, orchestration, guardrails, voice, 12 LLM providers. Apache-2.0. |
 | [`@framers/agentos-extensions`](https://www.npmjs.com/package/@framers/agentos-extensions) | 100+ first-party extensions: channel adapters, tool packs, integrations, guardrail packs. |
 | [`@framers/agentos-extensions-registry`](https://www.npmjs.com/package/@framers/agentos-extensions-registry) | Discovery + auto-loader for the extensions catalog. |
 | [`@framers/agentos-skills`](https://www.npmjs.com/package/@framers/agentos-skills) | 88 curated `SKILL.md` skills. |

docs/architecture/ARCHITECTURE.md

@@ -14,7 +14,7 @@ This page is the system map. For the *what* of each subsystem — components, li
 For specific subsystem deep-dives, see:
 - [Provenance & Immutability](../features/provenance-immutability.md)
 
-![AgentOS layered architecture: seven cooperating layers from caller-facing API (generateText, streamText, agent, agency, mission) through cognitive substrate (GMI coordinator, PersonaOverlayManager, SentimentTracker, MetapromptExecutor), memory and RAG (4-tier memory, 8 cognitive mechanisms, HyDE, GraphRAG, 7 vector backends), tools and capabilities (100+ extension packs, 88 SKILL.md modules, runtime tool forging), guardrails and HITL (PII redaction, ML classifiers, NLI grounding, 5 approval triggers), orchestration (workflow, mission, AgentGraph, checkpointing), down to I/O and providers (voice pipeline, channels, media generation, 11 LLM providers, OpenRouter fanout).](/img/diagrams/system-architecture.svg)
+![AgentOS layered architecture: seven cooperating layers from caller-facing API (generateText, streamText, agent, agency, mission) through cognitive substrate (GMI coordinator, PersonaOverlayManager, SentimentTracker, MetapromptExecutor), memory and RAG (4-tier memory, 8 cognitive mechanisms, HyDE, GraphRAG, 7 vector backends), tools and capabilities (100+ extension packs, 88 SKILL.md modules, runtime tool forging), guardrails and HITL (PII redaction, ML classifiers, NLI grounding, 5 approval triggers), orchestration (workflow, mission, AgentGraph, checkpointing), down to I/O and providers (voice pipeline, channels, media generation, 12 LLM providers, OpenRouter fanout).](/img/diagrams/system-architecture.svg)
 
 Each layer above corresponds to a section below. The mapping is one-to-one: layer 1 → [API Surface Contract](#api-surface-contract), layer 2 → [GMI](#gmi-generalized-mind-instance), layer 3 → [Memory System](#memory-system), layer 4 → [Tools, Skills, Extensions](#tools-skills--extensions), layer 5 → [Safety & Guardrails](#safety--guardrails), layer 6 → [Orchestration](#orchestration), layer 7 → [Perception & Channels](#perception--channels). The component pills inside each layer in the diagram are the same class and function names you'll see in the subsystem write-ups.
 

docs/features/LLM_PROVIDERS.md

@@ -1,6 +1,6 @@
 # LLM Providers — multi-provider configuration & routing
 
-AgentOS abstracts every LLM behind a single [`IProvider`](https://github.com/framerslab/agentos/blob/master/src/core/llm/providers/IProvider.ts) interface. Eleven providers are wired in directly — nine via API key, two via local CLI bridges that ride an existing Claude Max or Google account subscription. OpenRouter, included in the eleven, fans out to 200+ additional models from the same set of vendors. Every provider speaks the same streaming protocol, supports the same tool-call shape (with the documented exceptions below), and participates in the same cost ledger. The fallback chain is auto-built from whichever keys are set in the environment and is overridable per agent.
+AgentOS abstracts every LLM behind a single [`IProvider`](https://github.com/framerslab/agentos/blob/master/src/core/llm/providers/IProvider.ts) interface. Twelve providers are wired in directly — nine via API key, Ollama locally, and two via local CLI bridges that ride an existing Claude Max or Google account subscription. OpenRouter, included in the twelve, fans out to 200+ additional models from the same set of vendors. Every provider speaks the same streaming protocol, supports the same tool-call shape (with the documented exceptions below), and participates in the same cost ledger. The fallback chain is auto-built from whichever keys are set in the environment and is overridable per agent.
 
 ---
 
@@ -22,6 +22,7 @@ AgentOS abstracts every LLM behind a single [`IProvider`](https://github.com/fra
    - [Mistral AI](#mistral-ai)
    - [xAI (Grok)](#xai-grok)
    - [OpenRouter](#openrouter)
+   - [Atlas Cloud](#atlas-cloud)
    - [Ollama](#ollama)
 9. [Programmatic Configuration](#programmatic-configuration)
 10. [Adding a Custom Provider](#adding-a-custom-provider)
@@ -36,7 +37,7 @@ AgentOS abstracts LLM access behind a unified [`IProvider`](https://github.com/f
 
 **Key features:**
 
-- **11 providers** supported out of the box (9 API-key + 2 CLI-based)
+- **12 providers** supported out of the box (9 API-key + Ollama + 2 CLI-based)
 - **CLI providers**: Use your Claude Max or Google account subscription via local CLI — no API key needed
 - **Auto-detection**: Set an API key or install a CLI and the provider is available
 - **Fallback**: Automatic retry with alternate providers on failure (`fallbackProviders`)
@@ -58,6 +59,7 @@ AgentOS abstracts LLM access behind a unified [`IProvider`](https://github.com/f
 | **Mistral** | `MISTRAL_API_KEY` | `mistral-large-latest` | Yes | Yes | No | Yes | $$ |
 | **xAI** | `XAI_API_KEY` | `grok-2` | Yes | Yes | Yes | No | $$ |
 | **OpenRouter** | `OPENROUTER_API_KEY` | `openai/gpt-4o` | Yes | Yes | Yes* | Yes* | Varies |
+| **Atlas Cloud** | `ATLASCLOUD_API_KEY` | `deepseek-ai/deepseek-v4-pro` | Yes | Model-dep. | No | No | Varies |
 | **Ollama** | `OLLAMA_BASE_URL` | `llama3.2` | Yes | Partial | Model-dep. | Yes | Free |
 | **Claude Code CLI** | _(PATH detection)_ | `claude-sonnet-4-5-20250929` | Yes | Yes | Yes | No | Free* |
 | **Gemini CLI** | _(PATH detection)_ | `gemini-2.5-flash` | Yes | Partial** | Yes | No | Free* |
@@ -111,15 +113,16 @@ order and uses the first one found:
 
 1. `OPENROUTER_API_KEY` → OpenRouter
 2. `OPENAI_API_KEY` → OpenAI
-3. `ANTHROPIC_API_KEY` → Anthropic
-4. `GEMINI_API_KEY` → Google Gemini
-5. `GROQ_API_KEY` → Groq
-6. `TOGETHER_API_KEY` → Together AI
-7. `MISTRAL_API_KEY` → Mistral
-8. `XAI_API_KEY` → xAI
-9. `which claude` → Claude Code CLI (PATH detection — no API key, uses Max subscription)
-10. `which gemini` → Gemini CLI (PATH detection — no API key, uses Google account)
-11. `OLLAMA_BASE_URL` → Ollama
+3. `ATLASCLOUD_API_KEY` → Atlas Cloud
+4. `ANTHROPIC_API_KEY` → Anthropic
+5. `GEMINI_API_KEY` → Google Gemini
+6. `GROQ_API_KEY` → Groq
+7. `TOGETHER_API_KEY` → Together AI
+8. `MISTRAL_API_KEY` → Mistral
+9. `XAI_API_KEY` → xAI
+10. `which claude` → Claude Code CLI (PATH detection — no API key, uses Max subscription)
+11. `which gemini` → Gemini CLI (PATH detection — no API key, uses Google account)
+12. `OLLAMA_BASE_URL` → Ollama
 
 You can override auto-detection in four ways, highest priority first:
 
@@ -161,6 +164,9 @@ OPENAI_API_KEY=sk-...
 # Fallback provider
 OPENROUTER_API_KEY=sk-or-...
 
+# OpenAI-compatible provider
+ATLASCLOUD_API_KEY=...
+
 # Local provider (no API key needed)
 OLLAMA_BASE_URL=http://localhost:11434
 ```
@@ -240,7 +246,8 @@ AgentOS tracks token usage and cost across all providers:
 | Tier | Providers | Approximate Cost (1M tokens) |
 |------|-----------|------------------------------|
 | **$** (Budget) | Groq, Together, Ollama (free) | $0.00–$0.60 |
-| **$$** (Standard) | Gemini, Mistral, xAI, OpenRouter (varies) | $0.50–$3.00 |
+| **$$** (Standard) | Gemini, Mistral, xAI | $0.50–$3.00 |
+| **Varies** | OpenRouter, Atlas Cloud | Model-dependent |
 | **$$$** (Premium) | OpenAI, Anthropic | $3.00–$15.00 |
 
 ### Cost-Aware Caps
@@ -385,6 +392,23 @@ Popular OpenRouter models:
 - `google/gemini-2.5-flash`
 - `meta-llama/llama-3.3-70b-instruct`
 
+### Atlas Cloud
+
+```bash
+export ATLASCLOUD_API_KEY=...
+# Optional endpoint override for proxies or private deployments:
+export ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1
+```
+
+Atlas Cloud uses an OpenAI-compatible `/v1/chat/completions` endpoint, so it
+shares AgentOS's standard OpenAI-compatible transport, streaming, tool-call, and
+structured-output handling.
+
+| Model | Context | Vision | Tool Calling | Notes |
+|-------|---------|--------|-------------|-------|
+| `deepseek-ai/deepseek-v4-pro` | 1M | No | Yes | Default long-context reasoning model |
+| `qwen/qwen3.5-flash` | 1M | No | Partial | Fast chat model |
+
 ### Ollama
 
 ```bash
@@ -491,6 +515,7 @@ exercised paths.
 | Mistral | Yes | No | `auto/none/any` | Good support |
 | xAI | Yes | No | `auto/none` | Basic tool use |
 | OpenRouter | Model-dependent | Model-dependent | Model-dependent | Pass-through |
+| Atlas Cloud | Model-dependent | Model-dependent | Model-dependent | Depends on the selected Atlas Cloud model |
 | Ollama | Partial | No | `auto/none` | Model-dependent |
 
 ### Embedding Support

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@framers/agentos",
   "version": "0.10.1",
-  "description": "AgentOS: open-source TypeScript framework for autonomous AI agents. Unified graph orchestration, cognitive memory, runtime tool forging, multi-tier guardrails, voice pipeline, and 11 LLM providers.",
+  "description": "AgentOS: open-source TypeScript framework for autonomous AI agents. Unified graph orchestration, cognitive memory, runtime tool forging, multi-tier guardrails, voice pipeline, and 12 LLM providers.",
   "homepage": "https://agentos.sh",
   "repository": {
     "type": "git",

scripts/build-knowledge-corpus.mjs

@@ -210,7 +210,7 @@ function getFaqEntries(skillCount = 0) {
       id: 'faq:supported-models',
       heading: 'What LLM models are supported?',
       content:
-        'AgentOS supports 11 LLM providers: OpenAI (gpt-4o, gpt-4o-mini), Anthropic (claude-sonnet, claude-haiku, claude-opus), Google Gemini (gemini-2.5-pro, gemini-2.5-flash), Groq, Together AI, Mistral, xAI, OpenRouter (fans out to 200+ models), and Ollama (any local model), plus CLI bridges for Claude Code and Gemini CLI.',
+        'AgentOS supports 12 LLM providers: OpenAI (gpt-4o, gpt-4o-mini), Anthropic (claude-sonnet, claude-haiku, claude-opus), Google Gemini (gemini-2.5-pro, gemini-2.5-flash), Groq, Together AI, Mistral, xAI, Atlas Cloud, OpenRouter (fans out to 200+ models), and Ollama (any local model), plus CLI bridges for Claude Code and Gemini CLI.',
       category: 'faq',
     },
     {
@@ -489,7 +489,7 @@ function getApiReferenceEntries() {
       id: 'api:generateText',
       heading: 'generateText() API',
       content:
-        "import { generateText } from '@framers/agentos'. generateText({ model: 'openai:gpt-4o', prompt: 'Hello', system?: '...', tools?: [...], maxSteps?: 5, temperature?: 0.7 }) -> Promise<{ text, provider, model, usage, toolCalls }>. The core text generation function supporting all 11 LLM providers.",
+        "import { generateText } from '@framers/agentos'. generateText({ model: 'openai:gpt-4o', prompt: 'Hello', system?: '...', tools?: [...], maxSteps?: 5, temperature?: 0.7 }) -> Promise<{ text, provider, model, usage, toolCalls }>. The core text generation function supporting all 12 LLM providers.",
       category: 'api',
     },
     {

src/api/model.ts

@@ -39,6 +39,7 @@ export interface ResolvedProvider {
 
 const ENV_KEY_MAP: Record<string, string> = {
   openai: 'OPENAI_API_KEY',
+  atlascloud: 'ATLASCLOUD_API_KEY',
   anthropic: 'ANTHROPIC_API_KEY',
   openrouter: 'OPENROUTER_API_KEY',
   gemini: 'GEMINI_API_KEY',
@@ -52,6 +53,7 @@ const ENV_KEY_MAP: Record<string, string> = {
 
 const ENV_URL_MAP: Record<string, string> = {
   openai: 'OPENAI_BASE_URL',
+  atlascloud: 'ATLASCLOUD_BASE_URL',
   openrouter: 'OPENROUTER_BASE_URL',
   stability: 'STABILITY_BASE_URL',
   replicate: 'REPLICATE_BASE_URL',

src/api/runtime/__tests__/provider-defaults.test.ts

@@ -13,7 +13,7 @@ import { resolveModelOption, resolveProvider } from '../model.js';
 
 describe('PROVIDER_DEFAULTS', () => {
   it('has text model for all major providers', () => {
-    for (const id of ['openai', 'anthropic', 'ollama', 'openrouter', 'gemini']) {
+    for (const id of ['openai', 'anthropic', 'ollama', 'openrouter', 'atlascloud', 'gemini']) {
       expect(PROVIDER_DEFAULTS[id]?.text).toBeDefined();
     }
   });
@@ -40,6 +40,7 @@ describe('autoDetectProvider', () => {
     // Restore env after each test
     for (const key of [
       'OPENROUTER_API_KEY',
+      'ATLASCLOUD_API_KEY',
       'OPENAI_API_KEY',
       'ANTHROPIC_API_KEY',
       'GEMINI_API_KEY',
@@ -62,6 +63,7 @@ describe('autoDetectProvider', () => {
   it('detects openai from OPENAI_API_KEY', () => {
     delete process.env.ANTHROPIC_API_KEY;
     delete process.env.OPENROUTER_API_KEY;
+    delete process.env.ATLASCLOUD_API_KEY;
     process.env.OPENAI_API_KEY = 'test';
     expect(autoDetectProvider()).toBe('openai');
   });
@@ -75,13 +77,15 @@ describe('autoDetectProvider', () => {
   it('detects anthropic from ANTHROPIC_API_KEY', () => {
     delete process.env.OPENAI_API_KEY;
     delete process.env.OPENROUTER_API_KEY;
+    delete process.env.ATLASCLOUD_API_KEY;
     process.env.ANTHROPIC_API_KEY = 'test';
     expect(autoDetectProvider()).toBe('anthropic');
   });
 
   it('skips providers without image defaults when detecting for image tasks', () => {
     delete process.env.OPENAI_API_KEY;
     delete process.env.OPENROUTER_API_KEY;
+    delete process.env.ATLASCLOUD_API_KEY;
     process.env.ANTHROPIC_API_KEY = 'anthropic-test';
     process.env.STABILITY_API_KEY = 'stability-test';
 
@@ -92,6 +96,7 @@ describe('autoDetectProvider', () => {
     delete process.env.OPENAI_API_KEY;
     delete process.env.ANTHROPIC_API_KEY;
     delete process.env.OPENROUTER_API_KEY;
+    delete process.env.ATLASCLOUD_API_KEY;
     delete process.env.GEMINI_API_KEY;
     delete process.env.GROQ_API_KEY;
     delete process.env.TOGETHER_API_KEY;
@@ -107,6 +112,7 @@ describe('autoDetectProvider', () => {
     delete process.env.OPENAI_API_KEY;
     delete process.env.ANTHROPIC_API_KEY;
     delete process.env.OPENROUTER_API_KEY;
+    delete process.env.ATLASCLOUD_API_KEY;
     delete process.env.GEMINI_API_KEY;
     delete process.env.GROQ_API_KEY;
     delete process.env.TOGETHER_API_KEY;
@@ -120,6 +126,13 @@ describe('autoDetectProvider', () => {
 
     expect(autoDetectProvider()).toBe('claude-code-cli');
   });
+
+  it('detects atlascloud from ATLASCLOUD_API_KEY', () => {
+    delete process.env.OPENROUTER_API_KEY;
+    delete process.env.OPENAI_API_KEY;
+    process.env.ATLASCLOUD_API_KEY = 'atlas-test';
+    expect(autoDetectProvider()).toBe('atlascloud');
+  });
 });
 
 describe('resolveModelOption', () => {
@@ -128,6 +141,11 @@ describe('resolveModelOption', () => {
     expect(result).toEqual({ providerId: 'openai', modelId: 'gpt-4o' });
   });
 
+  it('resolves atlascloud provider-only to default text model', () => {
+    const result = resolveModelOption({ provider: 'atlascloud' }, 'text');
+    expect(result).toEqual({ providerId: 'atlascloud', modelId: 'deepseek-ai/deepseek-v4-pro' });
+  });
+
   it('resolves provider + explicit model override', () => {
     const result = resolveModelOption({ provider: 'openai', model: 'gpt-4o-mini' }, 'text');
     expect(result).toEqual({ providerId: 'openai', modelId: 'gpt-4o-mini' });

src/api/runtime/__tests__/responseFormatForProvider.test.ts

@@ -81,6 +81,15 @@ describe('buildResponseFormatForProvider', () => {
     ).toEqual({ type: 'json_object' });
   });
 
+  it('atlascloud + plain schema -> strict json_schema; record -> json_object', () => {
+    expect(
+      buildResponseFormatForProvider(inputs('atlascloud', 'deepseek-ai/deepseek-v4-pro', plainSchema)),
+    ).toMatchObject({ type: 'json_schema' });
+    expect(
+      buildResponseFormatForProvider(inputs('atlascloud', 'deepseek-ai/deepseek-v4-pro', recordSchema)),
+    ).toEqual({ type: 'json_object' });
+  });
+
   it('unknown provider -> undefined (schema rides the system prompt)', () => {
     expect(
       buildResponseFormatForProvider(inputs('ollama', 'llama3', plainSchema)),

src/api/runtime/provider-defaults.ts

@@ -55,6 +55,10 @@ export const PROVIDER_DEFAULTS: Record<string, ProviderDefaults> = {
     text: 'openai/gpt-4o',
     cheap: 'openai/gpt-4o-mini',
   },
+  atlascloud: {
+    text: 'deepseek-ai/deepseek-v4-pro',
+    cheap: 'qwen/qwen3.5-flash',
+  },
   gemini: {
     text: 'gemini-2.5-flash',
     cheap: 'gemini-2.0-flash',
@@ -125,6 +129,7 @@ const AUTO_DETECT_ORDER: AutoDetectProbe[] = [
   // are set".
   { envKey: 'OPENROUTER_API_KEY', provider: 'openrouter' },
   { envKey: 'OPENAI_API_KEY', provider: 'openai' },
+  { envKey: 'ATLASCLOUD_API_KEY', provider: 'atlascloud' },
   { envKey: 'ANTHROPIC_API_KEY', provider: 'anthropic' },
   { envKey: 'GEMINI_API_KEY', provider: 'gemini' },
   { envKey: 'GROQ_API_KEY', provider: 'groq' },