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

> Learn to configure custom model routing with a YAML file in council-of-high-intelligence for precise LLM control. Master explicit mapping for your AI agents.

- Repository: [nyk/council-of-high-intelligence](https://github.com/0xNyk/council-of-high-intelligence)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/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`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/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`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/provider-model-slots.custom.yaml):

```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.

```bash
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`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/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`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/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`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/provider-model-slots.cursor.example.yaml)**: Specialized example for the `cursor_cli` provider aggregator.
- **[`SKILL.md`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/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`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/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`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/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.