ai-registry

Resolve a stable alias to a concrete AI deployment — provider, model, account, endpoint — and stop there.

ai-registry is the configuration layer under your AI stack, not another client. It answers one question — "which provider, which model, whose key, what URL?" — and hands the answer to whatever SDK you already use.

It makes no network requests, defines no chat interface, ships no gateway, and cannot hold a literal API key. The runtime dependency closure is six packages.

from ai_registry import Registry

registry = Registry.from_project()  # reads ./.ai-registry/registry.yaml
resolution = registry.resolve("chat-default")

The model, provider, account, or endpoint behind "chat-default" can change in configuration without touching application code.

Why a resolver instead of a client

Most tools in this space fuse two separate concerns: deciding what to call and calling it. Fusing them means you adopt someone's request translation, error types, retry semantics, and dependency tree in order to get their configuration model.

That fusion has a well-known failure mode. From openai/codex#1370, on Azure deployment names:

No logic should inspect the user's deployment name when making assumptions about model capabilities.

That is exactly the split this library enforces. A deployment is where you send the request. A model is what the model can do. They are different objects, and Resolution gives you both.

Install

pip install ai-registry                    # core: pydantic + pyyaml only
pip install "ai-registry[cli]"             # + ai-registry command
pip install "ai-registry[openai]"          # + OpenAI SDK adapter
pip install "ai-registry[pydantic-ai]"     # + Pydantic AI adapter
pip install "ai-registry[langchain]"       # + LangChain chat/embeddings adapter

Requires Python 3.11+.

Configure

Projects keep configuration in .ai-registry/ at the repository root, resolved from any subdirectory:

<project-root>/
└── .ai-registry/
    ├── providers/            # OPTIONAL — override or add providers
    ├── registry.yaml         # default
    ├── registry.dev.yaml     # OPTIONAL — profile "dev"
    └── registry.prod.yaml    # OPTIONAL — profile "prod"

# .ai-registry/registry.yaml
accounts:
  - id: deepseek-primary
    provider_id: deepseek
    credential: env:DEEPSEEK_API_KEY      # a reference, never a key
    enabled_models: [deepseek-chat, deepseek-reasoner]
  - id: uniapi-chat
    provider_id: uniapi
    credential: env:UNIAPI_API_KEY
    enabled_models: [deepseek-v4-flash]

aliases:
  - id: chat-default
    deployments:
      - account_id: deepseek-primary      # preferred
        model_id: deepseek-chat
      - account_id: uniapi-chat           # used when the first is cooling down
        model_id: deepseek-v4-flash
        routing: {priority: 1}

Select a profile with Registry.from_project(profile="prod") or AI_REGISTRY_PROFILE=prod.

Use the result

Build a client yourself, or use an optional adapter:

from ai_registry import ClientFactory

factory = ClientFactory.from_project()

# An openai.OpenAI client, pointed at the resolved endpoint and key:
client = factory.openai_client("chat-default")

# A Pydantic AI model — a framework with no config-file registry of its own:
model = factory.pydantic_ai_model("chat-default")

# Registry routing becomes Pydantic AI request-time failover:
model = factory.pydantic_ai_fallback_model("chat-default")

# A LangChain model — LangGraph states take it directly as a node model:
model = factory.langchain_chat_model("chat-default")

Or drive failover yourself — candidates() returns every healthy deployment in preference order:

for resolution in factory.registry.candidates("chat-default"):
    try:
        response = call(resolution)
    except TransientError:
        factory.registry.record_failure(resolution)  # cools this target down everywhere
        continue
    factory.registry.record_success(resolution)
    break

Inspect it

$ ai-registry explain chat-default
1. deepseek-primary/deepseek-chat -> https://api.deepseek.com/anthropic (credential: env (ok))
2. uniapi-chat/deepseek-v4-flash -> https://uni-api.cstcloud.cn/v1 (credential: env (unresolved))

$ ai-registry models --type chat --tools --min-context 500000
deepseek	deepseek-v4-flash	chat	1000000	reasoning,structured_output,tools

resolve and explain report whether a credential resolves, never its name or value.

Features

• Alias-first resolution, with an explicit account-id/model-id escape hatch.
• Multiple accounts and keys per provider, as reusable first-class objects.
• Deterministic deployment selection: priority, weight, disabled, plus a health store with time-based cooldown and exponential backoff.
• Capability-aware catalog queries — find a chat model with tools and a 200k window without hardcoding a model id.
• Secret references, not secrets: env: / secret_ref:, resolved lazily, with a pluggable SecretResolver for Vault, AWS, or Kubernetes.
• Secret-safe by construction: literal keys rejected; repr, dumps, and errors redacted; credential-bearing URLs refused.
• Bring your own catalog: ai_registry.catalog.load_models_dev() imports a models.dev api.json, and the built-in catalog takes its whole model set from a vendored snapshot — provider files carry only endpoints, settings, and deltas. Maintainers refresh it with ai-registry catalog diff|sync.
• Observability built in: Resolution.otel_attributes() emits OpenTelemetry GenAI attributes plus which alias and account were selected.
• Testable: ai_registry.testing ships supported fakes.

Why not X?

Use LiteLLM instead if you want one completion() call across providers, request translation, retries, spend tracking, or a proxy. It does far more than this library and does it well.

Use ai-registry if you already have SDKs you like and only want the configuration layer — especially if the dependency footprint of the component that touches every API key you own is something you care about. For scale: the resolved closure is 49 packages for litellm, 107 for litellm[proxy], and 6 here. In March 2026 two litellm releases were compromised on PyPI with a .pth file that harvested cloud credentials on every Python start. Fewer moving parts near your keys is a real property, not an aesthetic one.

The two are not exclusive: point an Account at a LiteLLM proxy and use this to decide which one.

Documentation

Non-goals

This package does not make network requests, define a unified AI response interface, translate or retry requests, or ship a gateway. Deployment selection is deterministic and based on configuration plus recorded health; request-time concerns belong to the caller or the adapter.

License

MIT.