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.
 
 ---
 
@@ -164,7 +164,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 — ten via API key, 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 (10 API-key + 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 | Yes | 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,7 @@ 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, OpenRouter (varies), Atlas Cloud (varies) | $0.50–$3.00 |
 | **$$$** (Premium) | OpenAI, Anthropic | $3.00–$15.00 |
 
 ### Cost-Aware Caps
@@ -385,6 +391,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 +514,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 | Yes | Yes | `auto/none` | OpenAI-compatible JSON schema mode |
 | Ollama | Partial | No | `auto/none` | Model-dependent |
 
 ### Embedding Support

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@framers/agentos",
   "version": "0.9.140",
-  "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' },