• scripts/test_cloud_all_models.py — Primary benchmark: single prompt to every model, precision metrics (18dp Decimal), actual eval_count/eval_duration from Ollama API; see Latest Benchmark and How Cloud Works Without an API Key
• scripts/test_cloud_inference.py — Original multi-source benchmark (local + cloud + vLLM)
• scripts/test_ollama_connection.py — Connection test using OllamaAPI

Existing mindX Ollama Docs (pre-2026-04-11)

• docs/ollama_api_integration.md — Original API compliance notes (timeouts, keep_alive, token counting)
• docs/ollama_integration.md — Custom client (OllamaAPI) vs official library (Python SDK)
• docs/ollama_model_capability_tool.md — Model discovery and capability registration
• docs/OLLAMA_VLLM_CLOUD_RESEARCH.md — Cloud + vLLM research (2026-04-10); established the dual-pillar strategy
• llm/RESILIENCE.md — Graded inference hierarchy: Primary → Secondary → Failsafe (CPU) → Guarantee (Cloud)

Latest Benchmark (2026-04-11)

Aggregate (all values ACTUAL from Ollama API, 18dp precision):

• Total tokens: 399 (218 eval + 181 prompt) = 399000000000000000000 sub-tokens
• Aggregate throughput: 11.03 tok/s (11.033658223708593293 at 18dp)
• Cloud vs CPU speedup: 8.2x (65.52 vs ~7.6 tok/s) — 120B cloud GPU vs 1.5B local CPU

Cloud Timing Note

Cloud-proxied models (gpt-oss:120b-cloud) return eval_duration_ns: 0 — the local offload proxy does not expose per-stage timing from the remote GPU. The total_duration_ns is used for tok/s calculation instead. CPU pillar models return all duration fields. See test_cloud_all_models.py line 114 for the fallback logic.

36 Additional Cloud Models Available

The cloud catalog lists 36 models at ollama.com/api/tags. To test them:

# Option A: Pull with -cloud suffix for free-tier proxy (metadata only, no weights)
ollama pull deepseek-v3.2-cloud
python3 scripts/test_cloud_all_models.py --local

Option B: Set API key for direct cloud access to all 36 models
export OLLAMA_API_KEY=your_key
python3 scripts/test_cloud_all_models.py

How Cloud Works Without an API Key

test_cloud_inference.py and OllamaCloudTool return cloud model responses without OLLAMA_API_KEY because of Ollama's local offload architecture:

The -cloud Suffix

Model names with -cloud appended (e.g., gpt-oss:120b-cloud) are metadata-only pulls that proxy inference to ollama.com. Without the suffix (e.g., gpt-oss:120b), ollama pull downloads the full model weights (gigabytes) for CPU pillar execution.

The cloud catalog returns names without -cloud. Append it for free-tier local proxy:

ollama pull gpt-oss:120b-cloud      # metadata only → inference proxied to cloud
ollama pull deepseek-v3.2-cloud     # metadata only → inference proxied to cloud
vs
ollama pull gemma3:4b               # downloads 3.3GB weights for local CPU execution

The Mechanism

1. ollama pull gpt-oss:120b-cloud downloads metadata (not weights) to the local daemon
2. ollama run gpt-oss:120b-cloud sends the request to localhost:11434 like any local model
3. The local Ollama daemon detects the -cloud tag and transparently proxies to ollama.com
4. Authentication is handled by the daemon using credentials from ollama signin (stored at ~/.ollama/id_ed25519; see FAQ)
5. OllamaCloudTool calls localhost:11434/api/chat — no Bearer token needed because the local daemon is the auth proxy

Agent → OllamaCloudTool.execute(operation="chat") → _try_local_proxy()
    → localhost:11434/api/chat (model-cloud) → local Ollama daemon
                                                  ↓ (transparent proxy)
                                             ollama.com (auth via ed25519 key)
                                                  ↓
                                             Cloud GPU inference
                                                  ↓
Agent ← result (eval_count, tokens_per_sec, 18dp) ← ollama.com

Three Access Paths

OllamaCloudTool in auto mode tries local proxy first, then direct cloud — matching the dual-pillar design.

Why /api/tags Works Without Auth

The model listing endpoint at https://ollama.com/api/tags is publicly accessible — it lists available cloud models for discovery. This is how test_cloud_all_models.py, OllamaCloudTool.list_models, and OllamaCloudModelDiscovery discover available models without authentication.

Free Tier Limits

See Cloud Rate Limiting for the adaptive pacing strategy (3s–30s based on quota utilization) that maximizes throughput within these limits using actual token counts.

Modelfile as Canonical Schema

The Ollama Modelfile is mindX's canonical schema for model collection and rating across both pillars:

This feeds into:

1. HierarchicalModelScorer — learned task_scores from precision metrics feedback
2. OllamaCloudModelDiscovery — dynamic capability detection across both CPU and cloud models
3. InferenceDiscovery — provider routing with cloud guarantee fallback
4. Agent-model alignment toward Chimaiera (the ROI moment when model composition outperforms single-model inference)

See Modelfile Reference for the full instruction set and Chimaiera alignment section.

Precision Metrics

Token tracking at 18 decimal places using Python Decimal. No floating-point drift. No estimation. Applied identically to both CPU and Cloud pillars.

Local metrics: data/metrics/precision_metrics.json (via OllamaAPI) Cloud metrics: data/metrics/cloud_precision_metrics.json (via OllamaCloudTool)

Full docs: Precision Metrics.

Resilience Design

The 5-step resolution chain in _resolve_inference_model() ensures mindX always has inference when any network path is available:

Step 1: InferenceDiscovery → best provider (Gemini, Mistral, Groq, etc.)
          ↓ all keys exhausted or rate limited
Step 2: OllamaChatManager → local model selection (HierarchicalModelScorer)
          ↓ connection stale or failed
Step 3: Re-init OllamaChatManager → retry with fresh connection
          ↓ still failing
Step 4: Direct HTTP → localhost:11434/api/tags (zero dependencies)
          ↓ local Ollama completely down
Step 5: OllamaCloudTool → ollama.com GPU inference ← GUARANTEE (24/7/365)
          ↓ cloud also unreachable (network down)
     → None → fallback_decide() rule-based heuristics → 2-min backoff

Cloud is guarantee, not default. The _cloud_inference_active flag in mindXagent.py routes one chat through OllamaCloudTool, then resets so the next cycle tries local first. This preserves CPU pillar autonomy while ensuring the cloud pillar catches every gap.

InferenceDiscovery.get_provider_for_task() routes tasks through the same hierarchy: preferred provider → ollama_local → ollama_cloud → any available → None.

Implementation: _resolve_inference_model() (5 steps) → InferenceDiscovery (provider probing + cloud fallback) → OllamaCloudTool (cloud guarantee) → RESILIENCE.md (graded hierarchy docs) → chat_with_ollama() (cloud routing when active).

mindX File Map

Core Ollama Integration

Test Scripts

External References

Version Info

• Ollama docs: Fetched 2026-04-11 from docs.ollama.com
• Operational standards: CPU (OllamaAPI + OllamaChatManager) + Cloud (OllamaCloudTool)
• Resilience: 5-step chain in _resolve_inference_model() with cloud guarantee
• Precision: 18dp Decimal via precision_metrics.py, actual counts from Ollama API
• Production: mindx.pythai.net (4GB VPS, CPU pillar, dual-URL failover)
• Benchmark: 2026-04-11 — 3 models, 399 tokens, cloud 8.2x faster than CPU
• 28 files, ~6,000 lines — self-contained for resilient offline operation