How to Configure Custom Model Routing Using a YAML File in council-of-high-intelligence

The council-of-high-intelligence CLI routes language models to council seats through either automatic tier-based mapping or explicit custom YAML configuration.

The 0xNyk/council-of-high-intelligence repository implements a multi-agent deliberation system where each "seat" (council member) requires specific LLM capabilities. Understanding how to configure custom model routing using a YAML file allows you to override automatic tier assignments and bind specific providers and models to individual members for reproducible, fine-tuned reasoning workflows.

Understanding the Two-Tier Routing Architecture

The coordinator decides which language model each seat uses through a two-step process controlled by CLI flags.

Auto-Routing Defaults

When you omit the --models argument, the coordinator consults configs/auto-route-defaults.yaml. This file defines provider_models with high and mid tier mappings for each supported provider (Anthropic, OpenAI, Google, etc.).

Seats whose front-matter declares model: opus are automatically mapped to the provider’s high tier model (e.g., Anthropic’s opus), while seats with model: sonnet route to the mid tier (e.g., sonnet). The file also stores optional chairman_defaults for overriding the default chairman model without modifying individual seat configurations.

Custom YAML Slot Files

Supplying --models <path>.yaml bypasses auto-routing entirely. The coordinator instantiates each seat using the exact provider/model pairs specified in your custom file, skipping the tier-matching heuristic. This enables provider-diverse councils and precise model selection per member.

Creating Your Custom Model Routing YAML File

Your custom routing file must follow the schema demonstrated in configs/provider-model-slots.example.yaml. The structure requires four top-level keys:

• profile: Documents which profile this configuration targets (informational only).
• strategy: Boolean and numeric options influencing member selection logic, including provider_spread_first, avoid_pair_collocation, and force_counterfactual_if_consensus_gt.
• seats: A map where each key is a seat name and the value is an object containing provider, model, and reasoning_mode.
• fallback: A default provider/model pair used when a seat cannot be satisfied (e.g., provider unavailable).

Practical Configuration Example

Create a file named configs/provider-model-slots.custom.yaml:

profile: my-custom-profile
strategy:
  provider_spread_first: true            # Spread seats across providers before model-tier matching

  avoid_pair_collocation: true           # Prevent two seats from using the same provider in a single run

  force_counterfactual_if_consensus_gt: 0.75
  require_dissenting_members: 1

seats:
  alice:
    provider: openai
    model: gpt-5
    reasoning_mode: analytical
  bob:
    provider: anthropic
    model: claude-sonnet-4
    reasoning_mode: strategic
  carol:
    provider: google
    model: gemini-2.5-pro
    reasoning_mode: pragmatic

fallback:
  provider: openai
  model: gpt-5-mini

Running the Council with Custom Routing

Pass your YAML file to the --models flag when invoking the CLI. The coordinator reads the configuration, instantiates each seat with the specified provider and model, and uses the fallback entry for any unmatched seats.

council --profile exploration-orthogonal \
        --models configs/provider-model-slots.custom.yaml \
        "Should we expand our AI devtool into enterprise compliance workflows?"

To revert to auto-routing, simply omit the --models flag. Use --no-auto-route to force Claude-only defaults if you prefer the built-in tier mapping without custom files.

Key Configuration Files Reference

Understanding these source files helps debug routing behavior:

• configs/auto-route-defaults.yaml: Defines the default provider-tier mappings that translate opus/sonnet front-matter tags into concrete model IDs.
• configs/provider-model-slots.example.yaml: Reference implementation showing the full schema for custom seat-to-model mapping.
• configs/provider-model-slots.cursor.example.yaml: Specialized example for the cursor_cli provider aggregator.
• SKILL.md: Documents CLI flags including --models and --no-auto-route.

Summary

• Auto-routing maps opus/sonnet tags to high/mid tier models via configs/auto-route-defaults.yaml when no --models flag is present.
• Custom YAML routing requires the --models flag and overrides all defaults with explicit per-seat provider and model assignments.
• The custom YAML schema requires profile, strategy, seats, and fallback top-level keys.
• Each seat entry specifies provider, model, and reasoning_mode to guide the coordinator's internal deliberation style.
• The fallback section ensures execution continuity when specific providers are unavailable.

Frequently Asked Questions

What happens if a seat is defined in the front-matter but missing from the custom YAML file?

If a seat referenced in the council profile is absent from the seats mapping in your custom YAML file, the coordinator automatically substitutes the provider and model specified in the fallback section of the YAML file. This ensures the council can still execute even when specific member configurations are omitted.

Can I mix auto-routing for some seats and custom assignments for others?

No, the routing system operates in binary mode. When you supply --models <path>.yaml, the coordinator switches entirely to explicit assignment mode and ignores configs/auto-route-defaults.yaml. All seats must be defined in your custom YAML file or covered by the fallback entry; there is no hybrid mode that combines automatic tier mapping with selective custom overrides.

What is the purpose of the reasoning_mode field in the YAML configuration?

The reasoning_mode field guides the coordinator's internal processing style for that specific seat, accepting values like analytical, mechanistic, strategic, or pragmatic. While the underlying LLM API call uses the specified model and provider, this metadata instructs the council's deliberation logic how to weight and interpret that member's contributions during the reasoning process.

How do I prevent multiple seats from using the same provider in a single run?

Set avoid_pair_collocation: true in the strategy section of your custom YAML file. This boolean flag instructs the coordinator to prevent two seats from using the same provider during a single execution, enforcing provider diversity across the council and reducing single-point-of-failure risks during deliberation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}