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

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.

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

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 to select an appropriate model based on tier.

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.

/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:

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

# 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:

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

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:

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.

Configuring Fallback Seats

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

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 – Baseline multi-provider mapping with Anthropic, OpenAI, Google, xAI, and NVIDIA NIM seats.
• configs/provider-model-slots.nim.example.yaml – NVIDIA NIM-specific configuration showing OpenAI-compatible endpoint setup.
• configs/provider-model-slots.cursor.example.yaml – Configuration template for the Cursor CLI provider integration.
• configs/auto-route-defaults.yaml – Default tier mappings (low/medium/high) for automatic model selection.
• 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 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 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 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.

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