The Complete Guide to yait_aichain's Model Registry

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.

Most AI frameworks make you hardcode provider details into every function call. You write openai.ChatCompletion.create model="gpt-4" in 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. The yait aichain https://github.com/yaitio/aichain/tree/main Model Registry exists so you never lose another Tuesday. It's a single abstraction layer that maps logical model names to provider-specific configurations. You reference a model by its registry key — "openai/gpt4o" or "anthropic/claude-sonnet" — 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. This 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. The Model class is one of five core primitives in yait aichain: python from yait aichain import Model, Skill, Chain, Pool, Agent A 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 — it's the connection between your logic and the actual inference provider. When you instantiate a Model , the registry resolves the model key, injects default parameters, and returns a configured object ready to pass into a Skill: model = Model "openai/gpt4o" skill = Skill model=model, instruction="Summarize the input text." result = skill.run "Paste your long document here." skill.run accepts 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. Out 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. Every model key follows the pattern provider/model name : | Key | Provider | Underlying Model | |---|---|---| openai/gpt4o | OpenAI | gpt-4o | openai/gpt4o-mini | OpenAI | gpt-4o-mini | openai/gpt4-turbo | OpenAI | gpt-4-turbo | anthropic/claude-sonnet | Anthropic | claude-3-5-sonnet-20241022 | anthropic/claude-haiku | Anthropic | claude-3-5-haiku-20241022 | anthropic/claude-opus | Anthropic | claude-3-opus-20240229 | google/gemini-pro | gemini-1.5-pro | | google/gemini-flash | gemini-1.5-flash | | mistral/mistral-large | Mistral | mistral-large-latest | The 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. The built-in registry always uses fully dated model names e.g., claude-3-5-sonnet-20241022 when the provider requires them. If you need to target a different version, override the entry as shown in the custom registration section below. Each registered model carries a set of sensible defaults: model = Model "openai/gpt4o" Defaults applied: temperature: 0.7 max tokens: 4096 top p: 1.0 You override any of these at instantiation: model = Model "openai/gpt4o", temperature=0.2, max tokens=512 The override applies only to that instance. The registry's defaults remain untouched for the next caller. For 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. A valid configuration file follows this structure: version: "2.0" models: openai/gpt4o: provider: openai model name: gpt-4o parameters: temperature: 0.7 max tokens: 4096 top p: 1.0 anthropic/claude-sonnet: provider: anthropic model name: claude-3-5-sonnet-20241022 parameters: temperature: 0.7 max tokens: 4096 custom/my-finetuned: provider: openai model name: ft:gpt-4o:my-org:custom-model:abc123 parameters: temperature: 0.3 max tokens: 2048 The version field is required and must be "2.0" for the current release. The models block is a dictionary where each key becomes the registry key you'll reference in code. python from yait aichain import Model Model.load registry "path/to/models.yaml" model = Model "custom/my-finetuned" When you call load registry , 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. The 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. Common validation errors: version field version: "2.0" . provider value openai , anthropic , google , mistral , or a custom-registered provider . temperature must be a float between 0.0 and 2.0. max tokens must 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. Tip:Set AICHAIN LOG LEVEL=DEBUG whenever 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. | Provider | Environment Variable | Description | |---|---|---| | OpenAI | OPENAI API KEY | Your OpenAI API key | | Anthropic | ANTHROPIC API KEY | Your Anthropic API key | GOOGLE API KEY | Your Google AI API key | | | Mistral | MISTRAL API KEY | Your Mistral API key | Beyond API keys, you can control library behavior through additional environment variables: | Variable | Default | Description | |---|---|---| AICHAIN DEFAULT MODEL | openai/gpt4o | The model used when no model key is specified | AICHAIN LOG LEVEL | WARNING | Logging verbosity: DEBUG , INFO , WARNING , ERROR | AICHAIN TIMEOUT | 30 | Request timeout in seconds | AICHAIN MAX RETRIES | 3 | Number of retry attempts on transient failures | AICHAIN REGISTRY PATH | None | Path to a YAML config file, loaded automatically on import | AICHAIN REGISTRY PATH is particularly useful in containerized deployments. Instead of calling Model.load registry in your application code, you set the environment variable and the registry configures itself when yait aichain is first imported: export AICHAIN REGISTRY PATH=/etc/aichain/models.yaml export OPENAI API KEY=sk-... export ANTHROPIC API KEY=sk-ant-... python from yait aichain import Model, Skill Registry already loaded from /etc/aichain/models.yaml model = Model "custom/my-finetuned" skill = Skill model=model, instruction="Extract key entities from the text." result = skill.run "Apple introduced the M4 chip at its May 2024 iPad Pro event." No load registry call. No API key in sight. The environment handles it. For local development, create a .env file in your project root: OPENAI API KEY=sk-dev-abc123 ANTHROPIC API KEY=sk-ant-dev-xyz789 AICHAIN LOG LEVEL=DEBUG AICHAIN DEFAULT MODEL=openai/gpt4o-mini yait aichain automatically detects and loads .env files from the current working directory. Add .env to your .gitignore . This is non-negotiable. YAML 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. python from yait aichain import Model Model.register key="custom/llama-local", provider="openai", compatible API format model name="meta-llama/Llama-3-70b", base url="http://localhost:8080/v1", parameters={ "temperature": 0.5, "max tokens": 2048, } model = Model "custom/llama-local" The base url parameter is critical for self-hosted models. If you're running vLLM, Ollama, or any OpenAI-compatible server, set provider to "openai" and point base url to your server. The OpenAI adapter handles the rest. You can re-register a built-in key to change its behavior globally: Model.register key="openai/gpt4o", provider="openai", model name="gpt-4o-2024-08-06", pin to specific version parameters={ "temperature": 0.3, lower default for your use case "max tokens": 8192, } After this call, every Model "openai/gpt4o" instantiation 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. Run different models in development and production without changing code: Development export AICHAIN DEFAULT MODEL=openai/gpt4o-mini Production export AICHAIN DEFAULT MODEL=openai/gpt4o python from yait aichain import Model, Skill Uses whatever AICHAIN DEFAULT MODEL points to model = Model skill = Skill model=model, instruction="Classify the support ticket by urgency." result = skill.run "My account has been locked for three days and I can't log in." In 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. Use the registry to define a primary and fallback model, then build a Chain that degrades gracefully when the primary provider is unavailable: python from yait aichain import Model, Skill, Chain primary model = Model "openai/gpt4o" fallback model = Model "anthropic/claude-sonnet" primary skill = Skill model=primary model, instruction="Generate a detailed product description." fallback skill = Skill model=fallback model, instruction="Generate a detailed product description." chain = Chain skills= primary skill, fallback skill , mode="fallback" try: result = chain.run "Noise-cancelling wireless headphones, over-ear, 30hr battery." except Exception as e: print f"Both providers failed: {e}" In "fallback" mode, the Chain runs primary skill first. If it raises a provider error, the Chain automatically retries with fallback skill . Because both models are resolved through the registry, switching providers later means changing one key — not rewriting API calls. In a shared repository, put your model configuration in a checked-in YAML file without secrets and let environment variables supply the keys: config/models.yaml version: "2.0" models: project/summarizer: provider: openai model name: gpt-4o parameters: temperature: 0.3 max tokens: 1024 project/classifier: provider: anthropic model name: claude-3-5-haiku-20241022 parameters: temperature: 0.0 max tokens: 128 project/generator: provider: google model name: gemini-1.5-pro parameters: temperature: 0.8 max tokens: 4096 python from yait aichain import Model, Skill Model.load registry "config/models.yaml" summarizer = Skill model=Model "project/summarizer" , instruction="Summarize in 3 bullet points." classifier = Skill model=Model "project/classifier" , instruction="Classify as positive, negative, or neutral." result = summarizer.run "Your input text here." Every 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. When something goes wrong, set AICHAIN LOG LEVEL=DEBUG and check the output. The registry logs every resolution step: DEBUG:aichain.registry: Resolving model key 'openai/gpt4o' DEBUG:aichain.registry: Found in YAML override config DEBUG:aichain.registry: Applied parameters: temperature=0.3, max tokens=8192 DEBUG:aichain.registry: Provider adapter: openai DEBUG:aichain.registry: Model instance created successfully Common issues and their fixes: OPENAI API KEY , ANTHROPIC API KEY , etc. /v1 suffix if the server expects it.If you're migrating from an earlier version, the registry saw significant changes in 2.0: version: "2.0" field is now required provider/model format "gpt4o" must become "openai/gpt4o" . Model.load registry merges .env file auto-loading AICHAIN REGISTRY PATH A typical 1.x instantiation looked like this: yait aichain 1.x — no longer supported model = Model "gpt4o" The 2.0 equivalent: yait aichain 2.0 model = Model "openai/gpt4o" Search your codebase for Model " and confirm every key contains a slash. That's the entire migration for most projects. The Model Registry is the configuration backbone of yait aichain. A consistent Model "provider/name" interface, 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.