Model Registry

AI Supreme Council uses a community-maintained model registry to keep its list of available models up to date. The registry is a JSON file hosted on GitHub that the app fetches and caches locally.

How It Works

The registry file (registry/models.json) contains a structured list of providers, their models, pricing tiers, free profiles, and preset council configurations. On page load, the AIS.Registry module fetches the latest registry data and caches it locally. The cache uses a stale-while-revalidate pattern with a 24-hour TTL -- the app serves the cached version immediately and fetches a fresh copy in the background.

If the fetch fails (offline, GitHub down), the app falls back to the locally cached copy. This ensures the model list is always available even without network connectivity.

Registry Structure

The models.json file has six top-level sections:

{
  "version": 14,
  "updated": "2026-02-15T12:00:00Z",
  "meta": { ... },
  "providers": { ... },
  "tiers": { ... },
  "models": [ ... ],
  "freeProfiles": [ ... ],
  "presetCouncils": [ ... ]
}

Section	Description
`version`	Integer version number, incremented on each update
`updated`	ISO 8601 timestamp of the last update
`meta`	Metadata: source URL, contributing guide, refresh interval, leaderboard info
`providers`	Provider definitions (API endpoints, auth config, features)
`tiers`	Pricing tier definitions (free, paid, enterprise)
`models`	Array of all model entries with capabilities and pricing
`freeProfiles`	Pre-built profiles for free models (used in the wizard)
`presetCouncils`	Pre-configured council templates (used in the wizard cluster path)

Provider Schema

Each provider entry defines how to connect to that provider's API:

{
  "anthropic": {
    "name": "Anthropic",
    "description": "Claude models",
    "keyPlaceholder": "sk-ant-...",
    "order": 1,
    "arenaScore": 1506,
    "baseUrl": "https://api.anthropic.com/v1/messages",
    "authType": "header",
    "authHeader": "x-api-key",
    "keyUrl": "https://console.anthropic.com/settings/keys",
    "format": "anthropic",
    "features": ["vision", "tools", "streaming", "reasoning"],
    "freeTier": null
  }
}

Field	Required	Description
`name`	Yes	Display name for the provider
`baseUrl`	Yes	API endpoint URL
`authType`	Yes	Authentication method: `bearer`, `header`, `query`, or `none`
`format`	Yes	API format: `anthropic`, `openai`, or `gemini`
`description`	No	Short description shown in the UI
`keyPlaceholder`	No	Placeholder text for the API key input
`order`	No	Display order in the provider list
`arenaScore`	No	Arena ELO score for model ranking
`keyUrl`	No	URL to the provider's API key management page
`features`	No	Array of supported features (`vision`, `tools`, `streaming`, `reasoning`, `json_mode`)
`freeTier`	No	Description of free tier availability, or `null` if no free tier
`extraHeaders`	No	Additional headers to send with every request
`local`	No	`true` for local providers like Ollama
`detectUrl`	No	URL to detect available local models

Model Schema

Each model entry defines a specific model's capabilities and pricing:

{
  "id": "claude-opus-4-6",
  "name": "Claude Opus 4.6",
  "provider": "anthropic",
  "context": 1000000,
  "maxOutput": 128000,
  "pricing": {
    "input": 5.0,
    "output": 25.0,
    "cachedInput": 0.5
  },
  "capabilities": ["vision", "tools", "streaming", "code"],
  "tier": "paid",
  "default": true
}

Field	Required	Type	Description
`id`	Yes	string	Unique model identifier (sent to the API)
`name`	Yes	string	Human-readable display name
`provider`	Yes	string	Provider ID (must exist in `providers` object)
`context`	Yes	integer	Context window size in tokens
`maxOutput`	Yes	integer	Maximum output tokens
`pricing`	Yes	object	`{input, output, cachedInput?}` in $/MTok
`capabilities`	Yes	array	Allowed values: `vision`, `tools`, `streaming`, `json_mode`, `reasoning`, `code`
`tier`	Yes	string	One of: `free`, `paid`, `enterprise`
`default`	No	boolean	If `true`, this model is pre-selected for its provider

Free Profiles

The freeProfiles array contains pre-built single-model profiles for free models. These appear in the wizard's model selection step, allowing new users to get started without a credit card.

{
  "name": "Gemini 3 Flash",
  "icon": "⚡",
  "provider": "gemini",
  "model": "gemini-3-flash-preview",
  "description": "Fast Gemini 3, 1M context. Vision + tools.",
  "tags": ["fast", "vision", "tools", "code"],
  "recommended": true,
  "arenaScore": 1473
}

Free profiles are sorted by arenaScore in the wizard to show the highest-quality free models first. Profiles with recommended: true are highlighted.

Current free model sources include:

Google Gemini free tier (Gemini 3 Flash, Gemini 2.5 Flash, Gemini 2.5 Flash-Lite)
OpenRouter free models (DeepSeek R1, Qwen 3 Coder, GLM 4.5 Air, Mistral Small, GPT-OSS 120B, and others)

Preset Councils

The presetCouncils array contains pre-configured multi-model council templates. These appear in the wizard's cluster path, allowing users to create councils with a single click.

{
  "name": "Research Team",
  "icon": "🔬",
  "description": "Top arena models from 5 providers...",
  "simpleDescription": "Your dream team of AI brains...",
  "style": "research",
  "chairman": 0,
  "privacy": "private",
  "members": [
    { "provider": "anthropic", "model": "claude-opus-4-6" },
    { "provider": "gemini", "model": "gemini-3-pro-preview" },
    { "provider": "xai", "model": "grok-4-1-fast-reasoning" }
  ],
  "recommended": true
}

Field	Description
`name`	Council display name
`icon`	Emoji icon
`description`	Technical description (shown to advanced users)
`simpleDescription`	Plain-language description (shown in simple mode)
`style`	Council deliberation style (research, compare, arena, moa, router, debate, consensus)
`chairman`	Index of the chairman member (0-based), or `null` for no chairman
`members`	Array of `{provider, model}` member definitions (minimum 2)
`recommended`	If `true`, highlighted in the wizard

Contributing Models

To add or update models in the registry:

Fork the repository on GitHub
Edit registry/models.json with your changes
Run the validation script: python3 registry/validate.py
Submit a pull request

Validation Rules

The validation script (registry/validate.py) enforces these rules:

Provider validation:

All required fields present: name, baseUrl, authType, format

Model validation:

All required fields present: id, name, provider, context, maxOutput, pricing, capabilities, tier
No duplicate model IDs across the entire registry
Provider reference must exist in the providers object
Tier must be one of: free, paid, enterprise
Capabilities must be from the allowed set: vision, tools, streaming, json_mode, reasoning, code
Pricing values must be non-negative
Context and maxOutput must be positive integers

Preset council validation:

Required fields: name, style, members
Style must be valid: research, compare, arena, moa, router, debate, consensus
Members must be an array with at least 2 entries
Each member must have provider and model fields
Chairman index (if set) must be within the members array bounds

Running Validation

# Validate models (default)
python3 registry/validate.py

# Validate with a specific file path
python3 registry/validate.py /path/to/models.json

# Validate packages registry
python3 registry/validate.py packages

# Validate a manifest file
python3 registry/validate.py manifest path/to/manifest.json

# Validate themes registry
python3 registry/validate.py themes

# Validate templates registry
python3 registry/validate.py templates

The script exits with code 0 on success and code 1 on failure, with detailed error messages for each validation failure.

Auto-Refresh

The registry refreshes automatically when the page loads. The meta.refreshInterval field (default: 86400 seconds = 24 hours) controls how long the cached data is considered fresh. You can force a refresh by clearing the app's cached data in Settings > Privacy.

Registry Hosting

The registry is served from GitHub as a static JSON file. This means:

No server-side logic required
Changes go live as soon as the PR is merged
The file is CDN-cached for fast global access
The app falls back gracefully if GitHub is unreachable
Multiple CDN layers ensure global availability

info

The registry is a bootstrap mechanism. At planetary scale (see the project's architecture goals), the registry propagates through a DHT (Distributed Hash Table) and gossip protocol. The GitHub-hosted JSON serves as the initial bootstrap and fallback.

How It Works​

Registry Structure​

Provider Schema​

Model Schema​

Free Profiles​

Preset Councils​

Contributing Models​

Validation Rules​

Running Validation​

Auto-Refresh​

Registry Hosting​