# How to Configure Custom Provider and Model Slot Mappings Using YAML in Council of High Intelligence

> Learn to configure custom provider and model slot mappings using YAML in Council of High Intelligence. Define profiles, strategies, and seats for seamless integration.

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

---

**You configure custom provider and model slot mappings by creating a declarative YAML file with `profile`, `strategy`, and `seats` sections, then loading it via the `--models` CLI flag when running the council coordinator.**

The **Council of High Intelligence** framework uses YAML-based configuration to define which LLM providers and models power each council member (or "seat"). By customizing these mappings, you control the diversity of reasoning approaches, distribute requests across multiple AI providers, and specify fallback behavior when primary models fail. This guide explains the schema, required fields, and implementation details based on the source configuration files in the `0xNyk/council-of-high-intelligence` repository.

## Understanding the YAML Schema Structure

A valid provider-model-slots file contains three top-level sections that govern council behavior.

**`profile`** selects a built-in coordination strategy (e.g., `exploration-orthogonal`) that determines how the council deliberates.

**`strategy`** tunes the coordinator algorithm with boolean flags like `provider_spread_first` and `avoid_pair_collocation`.

**`seats`** maps each council member to specific provider credentials, model names, and reasoning hints.

```yaml
profile: exploration-orthogonal
strategy:
  provider_spread_first: true
  avoid_pair_collocation: true

seats:
  socrates:
    provider: anthropic
    model: claude-sonnet-4
    reasoning_mode: analytical

```

The coordinator parses this file at runtime in [`configs/provider-model-slots.example.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/provider-model-slots.example.yaml) to instantiate each seat with the specified provider client.

## Provider-Specific Configuration Options

Individual seats support override fields for non-standard endpoints and authentication.

**`base_url`** – Overrides the default API endpoint when using OpenAI-compatible providers like NVIDIA NIM.

**`api_key_env`** – Specifies the environment variable name containing the provider's API key.

**`reasoning_mode`** – Provides an optional hint to the coordinator about the seat's cognitive style (e.g., `analytical`, `mechanistic`, `formal`).

**`fallback`** – A global fallback seat configuration used when a specific provider fails initialization or returns errors.

```yaml
seats:
  ada:
    provider: nvidia_nim
    model: qwen/qwen3.5-397b-a17b
    base_url: https://integrate.api.nvidia.com/v1
    api_key_env: NVIDIA_API_KEY
    reasoning_mode: formal

fallback:
  provider: nvidia_nim
  model: deepseek-ai/deepseek-v4-pro
  base_url: https://integrate.api.nvidia.com/v1
  api_key_env: NVIDIA_API_KEY

```

## Auto-Routing Defaults

When a seat definition omits the `model` field, the coordinator consults [`configs/auto-route-defaults.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/auto-route-defaults.yaml) to select an appropriate model based on tier.

```yaml
provider_models:
  anthropic:
    low: claude-3-5-sonnet-20240620
    medium: claude-opus-20240229
    high: null  # Selects first available high-tier model

  openai:
    low: gpt-4o-mini
    medium: gpt-4o
    high: gpt-4-turbo

```

This file acts as a lookup table mapping provider IDs to low, medium, and high-tier model identifiers, enabling dynamic model selection when specific versions aren't pinned.

## Loading Custom Mappings via CLI

To apply your custom YAML configuration, pass the file path to the `--models` flag when invoking the council.

```bash
/council \
  --profile exploration-orthogonal \
  --models configs/provider-model-slots.example.yaml \
  "Explain the impact of quantum computing on AI safety."

```

The example files include comment headers showing exact invocation syntax, such as in [`provider-model-slots.example.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/provider-model-slots.example.yaml):

```yaml

# Use with: /council --profile exploration-orthogonal --models configs/provider-model-slots.example.yaml "..."

```

## Complete Configuration Examples

### Minimal Multi-Provider Setup

This configuration creates two seats using distinct providers to maximize viewpoint diversity.

```yaml

# my-custom-slots.yaml

profile: exploration-orthogonal
strategy:
  provider_spread_first: true
  avoid_pair_collocation: true

seats:
  socrates:
    provider: anthropic
    model: claude-sonnet-4
    reasoning_mode: analytical
  feynman:
    provider: openai
    model: gpt-4o
    reasoning_mode: mechanistic

```

Run with:

```bash
/council \
  --profile exploration-orthogonal \
  --models my-custom-slots.yaml \
  "Compare the philosophical arguments of Kant and Hume."

```

### NVIDIA NIM Integration

Configure access to NVIDIA NIM models using the OpenAI-compatible endpoint pattern.

```yaml
seats:
  ada:
    provider: nvidia_nim
    model: qwen/qwen3.5-397b-a17b
    base_url: https://integrate.api.nvidia.com/v1
    api_key_env: NVIDIA_API_KEY
    reasoning_mode: formal

```

Export your credentials before execution:

```bash
export NVIDIA_API_KEY=nvapi-xxxxxxxxxxxx
/council --models configs/provider-model-slots.nim.example.yaml "Generate a formal proof of the Pythagorean theorem."

```

Reference implementation appears in [`configs/provider-model-slots.nim.example.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/provider-model-slots.nim.example.yaml).

### Configuring Fallback Seats

Define resilient council behavior by specifying a global fallback when primary seats fail.

```yaml
fallback:
  provider: openai
  model: gpt-4o-mini
  api_key_env: OPENAI_API_KEY

```

If the coordinator cannot initialize any seat in the primary configuration (e.g., due to missing API keys or service outages), it automatically instantiates the fallback seat to maintain council functionality.

## Key Configuration Files Reference

The repository contains several canonical examples demonstrating different provider integrations:

- **[`configs/provider-model-slots.example.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/provider-model-slots.example.yaml)** – Baseline multi-provider mapping with Anthropic, OpenAI, Google, xAI, and NVIDIA NIM seats.
- **[`configs/provider-model-slots.nim.example.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/provider-model-slots.nim.example.yaml)** – NVIDIA NIM-specific configuration showing OpenAI-compatible endpoint setup.
- **[`configs/provider-model-slots.cursor.example.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/provider-model-slots.cursor.example.yaml)** – Configuration template for the Cursor CLI provider integration.
- **[`configs/auto-route-defaults.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/auto-route-defaults.yaml)** – Default tier mappings (low/medium/high) for automatic model selection.
- **[`scripts/detect-providers.sh`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/scripts/detect-providers.sh)** – Environment scanner that identifies available provider credentials to help populate your YAML files.

## Summary

- **Council of High Intelligence** uses declarative YAML files to map council members (seats) to LLM providers and specific models.
- **Required sections** include `profile` for strategy selection, `strategy` for algorithm tuning, and `seats` for provider-model mappings.
- **Provider overrides** like `base_url` and `api_key_env` enable integration with OpenAI-compatible endpoints such as NVIDIA NIM.
- **Fallback configuration** at the root level ensures council continuity when primary providers fail.
- **Auto-routing defaults** in [`configs/auto-route-defaults.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/auto-route-defaults.yaml) provide tier-based model selection when explicit models aren't specified.
- **CLI invocation** requires the `--models` flag pointing to your YAML file to override built-in defaults.

## Frequently Asked Questions

### What is the difference between `profile` and `strategy` in the YAML file?

The `profile` field selects a pre-built coordination algorithm (like `exploration-orthogonal`) that dictates how the council deliberates and votes, while the `strategy` section contains boolean toggles that微调 (fine-tune) that behavior—such as `provider_spread_first` to distribute seats across distinct providers before doubling up on any single provider. You can think of `profile` as choosing the debate format and `strategy` as adjusting the specific rules of engagement.

### How do I use environment variables for API keys without hardcoding them?

Set the `api_key_env` field under any seat to the name of your environment variable, such as `ANTHROPIC_API_KEY` or `NVIDIA_API_KEY`. The coordinator reads the value from that environment variable at runtime, keeping credentials out of your configuration files. Ensure the variable is exported in your shell before running the `/council` command.

### Can I mix different providers in the same council session?

Yes, and this is encouraged for reducing training-data overlap bias. The `provider_spread_first: true` flag in the `strategy` section explicitly forces the coordinator to distribute seats across different providers (e.g., combining Anthropic, OpenAI, and NVIDIA NIM) before assigning multiple seats to the same provider. Example files like [`configs/provider-model-slots.example.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/provider-model-slots.example.yaml) demonstrate valid multi-provider configurations.

### What happens if I don't specify a model name in a seat configuration?

If the `model` field is omitted, the coordinator consults [`configs/auto-route-defaults.yaml`](https://github.com/0xNyk/council-of-high-intelligence/blob/main/configs/auto-route-defaults.yaml) to select an appropriate model based on the provider's tier mapping (low, medium, or high). If you haven't customized the defaults file, the system uses the repository's built-in mappings, which may select `null` (first available) for high-tier slots depending on the provider.