Valstorm AI Agent Model Strategy & Allocation Specification

1. Executive Summary & Model Tier Taxonomy

Modern LLMs fall into three distinct operational tiers based on reasoning depth, latency, token economics, and tool execution reliability:

┌────────────────────────────────────────────────────────────────────────┐
│                        TIER 1: HEAVY THINKERS                          │
│     System Architecture • Technical Planning • High-Stakes Ideation     │
│        Gemini 3.1 Pro Preview  |  Claude Opus 5  |  gpt-5.6-sol        │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Generates Architecture & Specs
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                          TIER 2: REASONERS                             │
│     Orchestration • Monorepo Dev • Tool Calling • Pytest & Playwright   │
│      Gemini 3.7 / 3.6 Flash  |  Claude Sonnet 5  |  gpt-5.3-codex      │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ Delegates Micro-Tasks
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        TIER 3: WORKER BEES                             │
│     Spec Execution • CUD Mutations • Schema Lookups • Data Scraping    │
│    Gemini 3.5 / 3.1 Flash-Lite  |  Claude Haiku 4.5  |  gpt-5.6-luna    │
└────────────────────────────────────────────────────────────────────────┘

2. Model Tier Specification & Best Use Cases

Tier 1: Heavy Thinkers (Architects & High-Stakes Planners)

• Role: High-level system architecture, multi-file code planning, complex database schema design, technical trade-off evaluation, and deep root-cause debugging breakdowns.
• When to Use: Only invoke during the planning/architecture phase or when an escalation threshold is reached (e.g. when a sub-agent is stuck).
• Cost Range: $2.00 - $5.00+ / 1M input tokens | $12.00 - $30.00+ / 1M output tokens.
• Recommended Models:
  • Google Gemini: gemini-3.1-pro-preview ($2.00 input / $12.00 output) — Massive context window, superior structural reasoning.
  • Anthropic Claude: claude-opus-5 ($5.00 input / $25.00 output) — Unmatched nuanced comprehension and architectural prose.
  • OpenAI: gpt-5.6-sol ($5.00 input / $30.00 output) / gpt-5.5 ($5.00 / $30.00) — Deep chain-of-thought and mathematical rigor.

Tier 2: Reasoners (Orchestrators, Full-Stack Devs & QA Engineers)

• Role: Interactive REPL orchestration, multi-tool agent execution, monorepo coding (FastAPI backend + React frontend), test suite authoring (Pytest/Playwright), API integration, domain research, and dynamic debugging.
• When to Use: The primary engine for all active interactive turns, multi-tool workflows, and specialized developers. They reason reliably, make structured tool calls without schema hallucination, and run at low latency (< 1.5s TTFT).
• Cost Range: $1.50 - $3.00 / 1M input tokens | $7.50 - $15.00 / 1M output tokens.
• Recommended Models:
  • Google Gemini: gemini-3.7-flash / gemini-3.6-flash ($1.50 input / $7.50 output) — Industry-leading speed-to-intelligence ratio, excellent function calling.
  • Anthropic Claude: claude-sonnet-5 ($2.00 input / $10.00 output) — Exceptional code generation, precise refactoring, and tool execution.
  • OpenAI: gpt-5.6-terra ($2.00 input / $12.00 output) / gpt-5.3-codex ($1.75 input / $14.00 output) — Specialized code completions and fast reasoning.

Tier 3: Worker Bees (Spec Executors & Single-Task Micro-Agents)

• Role: Pure execution of rigid specifications, single-field CRUD mutations, schema lookups, basic SQL generation, log aggregation, web scraping extraction, simple data formatting, and summarization.
• When to Use: High-throughput automated pipelines and isolated sub-tasks where the prompt already provides exact instructions and constraints.
• Cost Range: $0.20 - $1.00 / 1M input tokens | $1.20 - $5.00 / 1M output tokens.
• Recommended Models:
  • Google Gemini: gemini-3.5-flash-lite ($0.30 input / $2.50 output) / gemini-3.1-flash-lite ($0.25 input / $1.50 output) — High-throughput, ultra-low cost.
  • Anthropic Claude: claude-haiku-4.5 ($1.00 input / $5.00 output) — Fast, structured JSON generation.
  • OpenAI: gpt-5.6-luna ($0.20 input / $1.20 output) / gpt-5.4-nano ($0.20 input / $1.25 output) — Micro-agent execution.

3. Valstorm AI Agent Model Allocations

Below is the proposed allocation for all 49 AI Agents currently configured in Valstorm.

Part A: Core Swarm Profiles (18 Agents)

Part B: Platform Code & Logic Agents (8 Agents)

Part C: Query & UI Builder Agents (5 Agents)

Part D: Single-Task CRUD, Schema & Utility Micro-Agents (18 Agents)

4. Verification and Update Scripting

A migration script (hermes-management/apply_model_updates.py) is prepared to:

1. Update the live ai_agent records in Valstorm (via authenticated ValstormApiClient.records_update).
2. Update the local profile files in ~/.valstorm/profiles/<slug>.json.
3. Update apps/agent-runtime/exports/ai_agents_migrated.json.
4. Update apps/agent-runtime/core/context.py built-in profile defaults.