{"slug": "the-complete-guide-to-yait-aichain-s-model-registry", "title": "The Complete Guide to yait_aichain's Model Registry", "summary": "Yait_aichain's Model Registry provides a single abstraction layer that maps logical model names to provider-specific configurations, allowing developers to reference models by registry keys like \"openai/gpt4o\" or \"anthropic/claude-sonnet\" without hardcoding provider details. The registry handles resolution, parameter defaults, and provider routing, and changing one line in the registry updates all Skills, Chains, and Agents that reference that model automatically. The framework ships with pre-configured entries for OpenAI, Anthropic, Google, and Mistral models, and supports YAML-based configuration for production systems.", "body_md": "Most AI frameworks make you hardcode provider details into every function call. You write `openai.ChatCompletion.create(model=\"gpt-4\")`\n\nin forty places, then OpenAI deprecates the endpoint. You spend a Tuesday afternoon doing find-and-replace across your codebase. Two months later, you want to add Anthropic. Another Tuesday afternoon, gone.\n\nThe [yait_aichain](https://github.com/yaitio/aichain/tree/main) Model Registry exists so you never lose another Tuesday.\n\nIt's a single abstraction layer that maps logical model names to provider-specific configurations. You reference a model by its registry key — `\"openai/gpt4o\"`\n\nor `\"anthropic/claude-sonnet\"`\n\n— and the registry handles resolution, parameter defaults, and provider routing. Change one line in the registry, and every Skill, Chain, and Agent that references that model updates automatically.\n\nThis guide covers everything: how the registry works internally, how to configure it, how to register custom models, and how to use environment variables to keep secrets out of your source code.\n\nThe `Model`\n\nclass is one of five core primitives in yait_aichain:\n\n``` python\nfrom yait_aichain import Model, Skill, Chain, Pool, Agent\n```\n\nA **Skill** performs a single LLM operation. A **Chain** sequences Skills. A **Pool** runs them in parallel. An **Agent** orchestrates dynamically. None of these do anything without a `Model`\n\n— it's the connection between your logic and the actual inference provider.\n\nWhen you instantiate a `Model`\n\n, the registry resolves the model key, injects default parameters, and returns a configured object ready to pass into a Skill:\n\n```\nmodel = Model(\"openai/gpt4o\")\nskill = Skill(model=model, instruction=\"Summarize the input text.\")\nresult = skill.run(\"Paste your long document here.\")\n```\n\n`skill.run()`\n\naccepts a string and returns a string synchronously. The Skill never knows or cares which provider is behind the model — it sends a prompt, gets a response. That separation is the entire point.\n\nOut of the box, yait_aichain ships with a pre-configured registry covering the most common providers and models. You don't need to set up anything to start using them. Just reference the key.\n\nEvery model key follows the pattern `provider/model_name`\n\n:\n\n| Key | Provider | Underlying Model |\n|---|---|---|\n`openai/gpt4o` |\nOpenAI | gpt-4o |\n`openai/gpt4o-mini` |\nOpenAI | gpt-4o-mini |\n`openai/gpt4-turbo` |\nOpenAI | gpt-4-turbo |\n`anthropic/claude-sonnet` |\nAnthropic | claude-3-5-sonnet-20241022 |\n`anthropic/claude-haiku` |\nAnthropic | claude-3-5-haiku-20241022 |\n`anthropic/claude-opus` |\nAnthropic | claude-3-opus-20240229 |\n`google/gemini-pro` |\ngemini-1.5-pro | |\n`google/gemini-flash` |\ngemini-1.5-flash | |\n`mistral/mistral-large` |\nMistral | mistral-large-latest |\n\nThe slash is not decorative. The segment before it tells the registry which provider adapter to load; the segment after it identifies the specific model variant. This convention means the registry can route to the correct API client without any additional configuration from you.\n\nThe built-in registry always uses fully dated model names (e.g., `claude-3-5-sonnet-20241022`\n\n) when the provider requires them. If you need to target a different version, override the entry as shown in the custom registration section below.\n\nEach registered model carries a set of sensible defaults:\n\n```\nmodel = Model(\"openai/gpt4o\")\n# Defaults applied:\n#   temperature: 0.7\n#   max_tokens: 4096\n#   top_p: 1.0\n```\n\nYou override any of these at instantiation:\n\n```\nmodel = Model(\"openai/gpt4o\", temperature=0.2, max_tokens=512)\n```\n\nThe override applies only to that instance. The registry's defaults remain untouched for the next caller.\n\nFor production systems, model configuration shouldn't be scattered across Python files. yait_aichain supports YAML-based configuration that defines your full model setup in one place.\n\nA valid configuration file follows this structure:\n\n```\nversion: \"2.0\"\n\nmodels:\n  openai/gpt4o:\n    provider: openai\n    model_name: gpt-4o\n    parameters:\n      temperature: 0.7\n      max_tokens: 4096\n      top_p: 1.0\n\n  anthropic/claude-sonnet:\n    provider: anthropic\n    model_name: claude-3-5-sonnet-20241022\n    parameters:\n      temperature: 0.7\n      max_tokens: 4096\n\n  custom/my-finetuned:\n    provider: openai\n    model_name: ft:gpt-4o:my-org:custom-model:abc123\n    parameters:\n      temperature: 0.3\n      max_tokens: 2048\n```\n\nThe `version`\n\nfield is required and must be `\"2.0\"`\n\nfor the current release. The `models`\n\nblock is a dictionary where each key becomes the registry key you'll reference in code.\n\n``` python\nfrom yait_aichain import Model\n\nModel.load_registry(\"path/to/models.yaml\")\n\nmodel = Model(\"custom/my-finetuned\")\n```\n\nWhen you call `load_registry()`\n\n, the models defined in YAML merge with the built-in registry. If a key in your YAML matches a built-in key, your configuration wins. This lets you override defaults without forking the library.\n\nThe YAML loader validates your file against the expected schema on load. If you misspell a field or provide an invalid type, you get an error immediately — not five minutes into a pipeline run when the model finally gets called.\n\nCommon validation errors:\n\n`version`\n\nfield`version: \"2.0\"`\n\n.`provider`\n\nvalue`openai`\n\n, `anthropic`\n\n, `google`\n\n, `mistral`\n\n, or a custom-registered provider).`temperature`\n\nmust be a float between 0.0 and 2.0. `max_tokens`\n\nmust be a positive integer.API keys and provider-specific settings should never appear in YAML files or Python source code. yait_aichain reads them from environment variables with a consistent naming convention.\n\nTip:Set`AICHAIN_LOG_LEVEL=DEBUG`\n\nwhenever you're configuring the registry for the first time. The registry logs every resolution step, which makes misconfiguration obvious immediately rather than at runtime. See the Debugging section for sample output.\n\n| Provider | Environment Variable | Description |\n|---|---|---|\n| OpenAI | `OPENAI_API_KEY` |\nYour OpenAI API key |\n| Anthropic | `ANTHROPIC_API_KEY` |\nYour Anthropic API key |\n`GOOGLE_API_KEY` |\nYour Google AI API key | |\n| Mistral | `MISTRAL_API_KEY` |\nYour Mistral API key |\n\nBeyond API keys, you can control library behavior through additional environment variables:\n\n| Variable | Default | Description |\n|---|---|---|\n`AICHAIN_DEFAULT_MODEL` |\n`openai/gpt4o` |\nThe model used when no model key is specified |\n`AICHAIN_LOG_LEVEL` |\n`WARNING` |\nLogging verbosity: `DEBUG` , `INFO` , `WARNING` , `ERROR`\n|\n`AICHAIN_TIMEOUT` |\n`30` |\nRequest timeout in seconds |\n`AICHAIN_MAX_RETRIES` |\n`3` |\nNumber of retry attempts on transient failures |\n`AICHAIN_REGISTRY_PATH` |\n`None` |\nPath to a YAML config file, loaded automatically on import |\n\n`AICHAIN_REGISTRY_PATH`\n\nis particularly useful in containerized deployments. Instead of calling `Model.load_registry()`\n\nin your application code, you set the environment variable and the registry configures itself when yait_aichain is first imported:\n\n```\nexport AICHAIN_REGISTRY_PATH=/etc/aichain/models.yaml\nexport OPENAI_API_KEY=sk-...\nexport ANTHROPIC_API_KEY=sk-ant-...\npython\nfrom yait_aichain import Model, Skill\n\n# Registry already loaded from /etc/aichain/models.yaml\nmodel = Model(\"custom/my-finetuned\")\nskill = Skill(model=model, instruction=\"Extract key entities from the text.\")\nresult = skill.run(\"Apple introduced the M4 chip at its May 2024 iPad Pro event.\")\n```\n\nNo `load_registry()`\n\ncall. No API key in sight. The environment handles it.\n\nFor local development, create a `.env`\n\nfile in your project root:\n\n```\nOPENAI_API_KEY=sk-dev-abc123\nANTHROPIC_API_KEY=sk-ant-dev-xyz789\nAICHAIN_LOG_LEVEL=DEBUG\nAICHAIN_DEFAULT_MODEL=openai/gpt4o-mini\n```\n\nyait_aichain automatically detects and loads `.env`\n\nfiles from the current working directory. Add `.env`\n\nto your `.gitignore`\n\n. This is non-negotiable.\n\nYAML works well for static configurations. But sometimes you need to register models at runtime — maybe you're dynamically selecting a fine-tuned model based on user input, or you're integrating a self-hosted model behind a custom API.\n\n``` python\nfrom yait_aichain import Model\n\nModel.register(\n    key=\"custom/llama-local\",\n    provider=\"openai\",  # compatible API format\n    model_name=\"meta-llama/Llama-3-70b\",\n    base_url=\"http://localhost:8080/v1\",\n    parameters={\n        \"temperature\": 0.5,\n        \"max_tokens\": 2048,\n    }\n)\n\nmodel = Model(\"custom/llama-local\")\n```\n\nThe `base_url`\n\nparameter is critical for self-hosted models. If you're running vLLM, Ollama, or any OpenAI-compatible server, set `provider`\n\nto `\"openai\"`\n\nand point `base_url`\n\nto your server. The OpenAI adapter handles the rest.\n\nYou can re-register a built-in key to change its behavior globally:\n\n```\nModel.register(\n    key=\"openai/gpt4o\",\n    provider=\"openai\",\n    model_name=\"gpt-4o-2024-08-06\",  # pin to specific version\n    parameters={\n        \"temperature\": 0.3,  # lower default for your use case\n        \"max_tokens\": 8192,\n    }\n)\n```\n\nAfter this call, every `Model(\"openai/gpt4o\")`\n\ninstantiation in your application uses the pinned version with your custom defaults. This is how you roll out model version updates safely: change the registry, not the call sites.\n\nRun different models in development and production without changing code:\n\n```\n# Development\nexport AICHAIN_DEFAULT_MODEL=openai/gpt4o-mini\n\n# Production\nexport AICHAIN_DEFAULT_MODEL=openai/gpt4o\npython\nfrom yait_aichain import Model, Skill\n\n# Uses whatever AICHAIN_DEFAULT_MODEL points to\nmodel = Model()\nskill = Skill(model=model, instruction=\"Classify the support ticket by urgency.\")\nresult = skill.run(\"My account has been locked for three days and I can't log in.\")\n```\n\nIn development you're spending fractions of a cent per call with gpt-4o-mini. In production you get the full capability of gpt-4o. Same code, different bill.\n\nUse the registry to define a primary and fallback model, then build a Chain that degrades gracefully when the primary provider is unavailable:\n\n``` python\nfrom yait_aichain import Model, Skill, Chain\n\nprimary_model = Model(\"openai/gpt4o\")\nfallback_model = Model(\"anthropic/claude-sonnet\")\n\nprimary_skill = Skill(\n    model=primary_model,\n    instruction=\"Generate a detailed product description.\"\n)\n\nfallback_skill = Skill(\n    model=fallback_model,\n    instruction=\"Generate a detailed product description.\"\n)\n\nchain = Chain(skills=[primary_skill, fallback_skill], mode=\"fallback\")\n\ntry:\n    result = chain.run(\"Noise-cancelling wireless headphones, over-ear, 30hr battery.\")\nexcept Exception as e:\n    print(f\"Both providers failed: {e}\")\n```\n\nIn `\"fallback\"`\n\nmode, the Chain runs `primary_skill`\n\nfirst. If it raises a provider error, the Chain automatically retries with `fallback_skill`\n\n. Because both models are resolved through the registry, switching providers later means changing one key — not rewriting API calls.\n\nIn a shared repository, put your model configuration in a checked-in YAML file (without secrets) and let environment variables supply the keys:\n\n```\n# config/models.yaml\nversion: \"2.0\"\n\nmodels:\n  project/summarizer:\n    provider: openai\n    model_name: gpt-4o\n    parameters:\n      temperature: 0.3\n      max_tokens: 1024\n\n  project/classifier:\n    provider: anthropic\n    model_name: claude-3-5-haiku-20241022\n    parameters:\n      temperature: 0.0\n      max_tokens: 128\n\n  project/generator:\n    provider: google\n    model_name: gemini-1.5-pro\n    parameters:\n      temperature: 0.8\n      max_tokens: 4096\npython\nfrom yait_aichain import Model, Skill\n\nModel.load_registry(\"config/models.yaml\")\n\nsummarizer = Skill(\n    model=Model(\"project/summarizer\"),\n    instruction=\"Summarize in 3 bullet points.\"\n)\n\nclassifier = Skill(\n    model=Model(\"project/classifier\"),\n    instruction=\"Classify as positive, negative, or neutral.\"\n)\n\nresult = summarizer.run(\"Your input text here.\")\n```\n\nEvery team member uses the same model configurations. Nobody accidentally runs gpt-3.5-turbo when the project requires gpt-4o. The YAML file is the single source of truth for model settings; the code is the single source of truth for behavior.\n\nWhen something goes wrong, set `AICHAIN_LOG_LEVEL=DEBUG`\n\nand check the output. The registry logs every resolution step:\n\n```\nDEBUG:aichain.registry: Resolving model key 'openai/gpt4o'\nDEBUG:aichain.registry: Found in YAML override config\nDEBUG:aichain.registry: Applied parameters: temperature=0.3, max_tokens=8192\nDEBUG:aichain.registry: Provider adapter: openai\nDEBUG:aichain.registry: Model instance created successfully\n```\n\nCommon issues and their fixes:\n\n`OPENAI_API_KEY`\n\n, `ANTHROPIC_API_KEY`\n\n, etc.`/v1`\n\nsuffix if the server expects it.If you're migrating from an earlier version, the registry saw significant changes in 2.0:\n\n`version: \"2.0\"`\n\nfield is now required`provider/model`\n\nformat`\"gpt4o\"`\n\nmust become `\"openai/gpt4o\"`\n\n.`Model.load_registry()`\n\nmerges`.env`\n\nfile auto-loading`AICHAIN_REGISTRY_PATH`\n\nA typical 1.x instantiation looked like this:\n\n```\n# yait_aichain 1.x — no longer supported\nmodel = Model(\"gpt4o\")\n```\n\nThe 2.0 equivalent:\n\n```\n# yait_aichain 2.0\nmodel = Model(\"openai/gpt4o\")\n```\n\nSearch your codebase for `Model(\"`\n\nand confirm every key contains a slash. That's the entire migration for most projects.\n\nThe Model Registry is the configuration backbone of yait_aichain. A consistent `Model(\"provider/name\")`\n\ninterface, centralized YAML configuration, environment-driven secrets, and clean override semantics mean that when a provider deprecates a model version, you change one registry entry and move on. Thirty seconds, not a Tuesday afternoon.", "url": "https://wpnews.pro/news/the-complete-guide-to-yait-aichain-s-model-registry", "canonical_source": "https://dev.to/yait/the-complete-guide-to-yaitaichains-model-registry-2mgc", "published_at": "2026-07-08 07:19:00+00:00", "updated_at": "2026-07-08 07:28:28.328522+00:00", "lang": "en", "topics": ["developer-tools", "large-language-models", "ai-infrastructure", "ai-tools", "mlops"], "entities": ["yait_aichain", "OpenAI", "Anthropic", "Google", "Mistral", "GPT-4o", "Claude 3.5 Sonnet", "Gemini 1.5 Pro"], "alternates": {"html": "https://wpnews.pro/news/the-complete-guide-to-yait-aichain-s-model-registry", "markdown": "https://wpnews.pro/news/the-complete-guide-to-yait-aichain-s-model-registry.md", "text": "https://wpnews.pro/news/the-complete-guide-to-yait-aichain-s-model-registry.txt", "jsonld": "https://wpnews.pro/news/the-complete-guide-to-yait-aichain-s-model-registry.jsonld"}}