llm-catalog-core 0.1.0__tar.gz

llm_catalog_core-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Shinsuke Mori
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

llm_catalog_core-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: llm-catalog-core
+Version: 0.1.0
+Summary: Gateway-agnostic core for llm-catalog: config schema, resolver, GatewayTransport, and LiteLLM codegen. Knows nothing about any runtime adapter.
+Keywords: llm,catalog,gateway,httpx,config
+Author: Shinsuke Mori
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: httpx>=0.27
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/sincekmori/llm-catalog
+Project-URL: Repository, https://github.com/sincekmori/llm-catalog
+Project-URL: Issues, https://github.com/sincekmori/llm-catalog/issues
+Project-URL: Changelog, https://github.com/sincekmori/llm-catalog/blob/main/packages/llm-catalog-core/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# llm-catalog-core
+
+Gateway-agnostic core for [llm-catalog](https://github.com/sincekmori/llm-catalog).
+It holds the config schema, loader/validation, role resolution, the path-rewriting `GatewayTransport`, and native LiteLLM codegen.
+
+This package knows nothing about any runtime adapter, so installing it pulls in neither Pydantic AI nor LiteLLM.
+Use it directly when you only need resolution or codegen.
+Otherwise install one of the adapter distributions (`llm-catalog-pydantic-ai`, `llm-catalog-litellm`), which depend on this.
+
+```python
+from llm_catalog.core import Catalog
+
+cat = Catalog.from_file("catalog.yaml")
+rm = cat.resolve_role("fast")   # -> ResolvedModel (no adapter types)
+print(rm.backend, rm.slug, rm.base_url)
+```
+
+See the [repository README](https://github.com/sincekmori/llm-catalog) for the full picture, the public/private boundary, and the verification notes.
+
+import namespace: `llm_catalog.core`

llm_catalog_core-0.1.0/README.md

@@ -0,0 +1,20 @@
+# llm-catalog-core
+
+Gateway-agnostic core for [llm-catalog](https://github.com/sincekmori/llm-catalog).
+It holds the config schema, loader/validation, role resolution, the path-rewriting `GatewayTransport`, and native LiteLLM codegen.
+
+This package knows nothing about any runtime adapter, so installing it pulls in neither Pydantic AI nor LiteLLM.
+Use it directly when you only need resolution or codegen.
+Otherwise install one of the adapter distributions (`llm-catalog-pydantic-ai`, `llm-catalog-litellm`), which depend on this.
+
+```python
+from llm_catalog.core import Catalog
+
+cat = Catalog.from_file("catalog.yaml")
+rm = cat.resolve_role("fast")   # -> ResolvedModel (no adapter types)
+print(rm.backend, rm.slug, rm.base_url)
+```
+
+See the [repository README](https://github.com/sincekmori/llm-catalog) for the full picture, the public/private boundary, and the verification notes.
+
+import namespace: `llm_catalog.core`

llm_catalog_core-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "llm-catalog-core"
+version = "0.1.0"
+description = "Gateway-agnostic core for llm-catalog: config schema, resolver, GatewayTransport, and LiteLLM codegen. Knows nothing about any runtime adapter."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Shinsuke Mori" }]
+keywords = ["llm", "catalog", "gateway", "httpx", "config"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.7",
+    "pyyaml>=6.0",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/sincekmori/llm-catalog"
+Repository = "https://github.com/sincekmori/llm-catalog"
+Issues = "https://github.com/sincekmori/llm-catalog/issues"
+Changelog = "https://github.com/sincekmori/llm-catalog/blob/main/packages/llm-catalog-core/CHANGELOG.md"
+
+[project.scripts]
+llm-catalog-codegen = "llm_catalog.core.codegen:main"
+
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+# PEP 420 namespace: ship only the `llm_catalog/core` subpackage. No
+# llm_catalog/__init__.py is created, so this distribution merges into the shared
+# `llm_catalog` namespace alongside the adapter distributions.
+[tool.uv.build-backend]
+module-name = "llm_catalog.core"
+namespace = true

llm_catalog_core-0.1.0/src/llm_catalog/core/__init__.py

@@ -0,0 +1,56 @@
+# Copyright 2026 Shinsuke Mori
+# SPDX-License-Identifier: Apache-2.0
+"""llm-catalog-core: gateway-agnostic config, resolution, transport, and codegen.
+
+This distribution knows nothing about any runtime adapter (Pydantic AI, LiteLLM).
+It loads and validates ``catalog.yaml``, resolves roles/keys to
+:class:`ResolvedModel`, provides the path-rewriting :class:`GatewayTransport`,
+and generates a native LiteLLM config (:func:`to_litellm_config`).
+
+``llm_catalog`` is a PEP 420 namespace shared with the adapter distributions;
+this package ships only ``llm_catalog.core``.
+"""
+
+from .catalog import Catalog
+from .codegen import to_litellm_config
+from .config import (
+    Backend,
+    CatalogConfig,
+    Gateway,
+    ModelCapabilities,
+    ModelEntry,
+    Provider,
+    RoleRef,
+    load_config,
+    parse_config,
+)
+from .errors import (
+    ConfigError,
+    LLMCatalogError,
+    ProviderIdCollisionWarning,
+    ResolutionError,
+)
+from .resolve import ResolvedModel
+from .transport import GatewayTransport, GatewayTransportSync, HeaderRewrite
+
+__all__ = [
+    "Backend",
+    "Catalog",
+    "CatalogConfig",
+    "ConfigError",
+    "Gateway",
+    "GatewayTransport",
+    "GatewayTransportSync",
+    "HeaderRewrite",
+    "LLMCatalogError",
+    "ModelCapabilities",
+    "ModelEntry",
+    "Provider",
+    "ProviderIdCollisionWarning",
+    "ResolutionError",
+    "ResolvedModel",
+    "RoleRef",
+    "load_config",
+    "parse_config",
+    "to_litellm_config",
+]

llm_catalog_core-0.1.0/src/llm_catalog/core/catalog.py

@@ -0,0 +1,95 @@
+# Copyright 2026 Shinsuke Mori
+# SPDX-License-Identifier: Apache-2.0
+"""The gateway-agnostic resolution entry point.
+
+:class:`Catalog` is the centre of ``llm-catalog-core``. It does **resolution
+only**: role/key -> :class:`ResolvedModel`. It returns no Pydantic AI / LiteLLM
+objects (those live in the adapter distributions), so importing it pulls in
+neither runtime.
+"""
+
+from pathlib import Path
+
+from .config import CatalogConfig, ModelEntry, Provider, load_config
+from .errors import ResolutionError
+from .resolve import ResolvedModel
+
+__all__ = ["Catalog"]
+
+
+class Catalog:
+    """Resolves roles and ``provider:model`` keys to :class:`ResolvedModel`."""
+
+    def __init__(self, config: CatalogConfig) -> None:
+        self._config = config
+        self._providers: dict[str, Provider] = {p.id: p for p in config.providers}
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> "Catalog":
+        """Load and validate ``catalog.yaml`` (or .json) and build a catalog."""
+        return cls(load_config(path))
+
+    @property
+    def config(self) -> CatalogConfig:
+        """The validated underlying config."""
+        return self._config
+
+    @property
+    def roles(self) -> list[str]:
+        """The names of every defined role."""
+        return list(self._config.roles)
+
+    def resolve_role(self, role: str) -> ResolvedModel:
+        """Resolve a role name to a :class:`ResolvedModel`."""
+        ref = self._config.roles.get(role)
+        if ref is None:
+            raise ResolutionError(
+                f'Unknown role "{role}". Defined roles: {sorted(self._config.roles)}.'
+            )
+        return self._resolve(ref.provider, ref.model)
+
+    def resolve_key(self, key: str) -> ResolvedModel:
+        """Resolve a ``"provider:model_id"`` key to a :class:`ResolvedModel`."""
+        provider_id, sep, model_id = key.partition(":")
+        if not sep:
+            raise ResolutionError(
+                f'Invalid model key "{key}"; expected "provider:model_id".'
+            )
+        return self._resolve(provider_id, model_id)
+
+    def meta_for_role(self, role: str) -> ResolvedModel:
+        """Alias of :meth:`resolve_role`, named for capability/metadata lookups."""
+        return self.resolve_role(role)
+
+    def _resolve(self, provider_id: str, model_id: str) -> ResolvedModel:
+        provider = self._providers.get(provider_id)
+        if provider is None:
+            raise ResolutionError(f'Unknown provider "{provider_id}".')
+
+        model = _find_model(provider, model_id)
+        if model is None:
+            raise ResolutionError(
+                f'Unknown model "{model_id}" in provider "{provider_id}".'
+            )
+
+        backend = provider.gateway.backends[model.backend]
+        # provider defaults first, then model settings win on conflict.
+        settings = {**provider.settings, **model.settings}
+
+        return ResolvedModel(
+            provider_id=provider.id,
+            model_id=model.id,
+            backend=model.backend,
+            slug=model.slug or model.id,
+            api=model.api,
+            base_url=provider.gateway.base_url,
+            api_key_env=provider.gateway.api_key_env,
+            path_template=backend.path_template,
+            action_map=dict(backend.action_map),
+            settings=settings,
+            capabilities=model.capabilities,
+        )
+
+
+def _find_model(provider: Provider, model_id: str) -> ModelEntry | None:
+    return next((m for m in provider.models if m.id == model_id), None)

llm_catalog_core-0.1.0/src/llm_catalog/core/codegen.py

@@ -0,0 +1,109 @@
+# Copyright 2026 Shinsuke Mori
+# SPDX-License-Identifier: Apache-2.0
+"""Generate a native LiteLLM ``config.yaml`` from a ``catalog.yaml`` (route 2a).
+
+This is the *lean alternative* to the LiteLLM plugin: it emits a plain LiteLLM
+config that uses LiteLLM's **built-in** providers (``anthropic/...``,
+``openai/...``, ``gemini/...``) plus ``api_base``, with a ``model_group_alias``
+for the roles.
+
+It imports neither ``litellm`` nor any adapter — it is pure dict/YAML text — so
+it ships in *core* and runs with only ``llm-catalog-core`` installed.
+
+Limitations (documented in the README): because it relies on LiteLLM's built-in
+path construction, it does **not** honour a custom ``pathTemplate`` or native
+grounding. Use the ``llm-catalog-litellm`` plugin when those matter.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .config import CatalogConfig, ModelEntry, Provider, load_config
+
+__all__ = ["main", "to_litellm_config"]
+
+# catalog backend -> LiteLLM built-in provider prefix.
+_BACKEND_TO_LITELLM: dict[str, str] = {
+    "anthropic": "anthropic",
+    "openai": "openai",
+    "google": "gemini",
+}
+
+
+def _litellm_params(provider: Provider, model: ModelEntry) -> dict[str, Any]:
+    prefix = _BACKEND_TO_LITELLM[model.backend]
+    slug = model.slug or model.id
+
+    params: dict[str, Any] = {
+        "model": f"{prefix}/{slug}",
+        "api_base": provider.gateway.base_url,
+        # LiteLLM reads "os.environ/NAME" as an env reference — the key value is
+        # never written into the generated file.
+        "api_key": f"os.environ/{provider.gateway.api_key_env}",
+    }
+    # Merge provider then model defaults (model wins).
+    merged = {**provider.settings, **model.settings}
+    params.update(merged)
+    return params
+
+
+def to_litellm_config(config: CatalogConfig) -> dict[str, Any]:
+    """Build a LiteLLM ``config.yaml`` structure (model_list + role aliases)."""
+    model_list: list[dict[str, Any]] = [
+        {
+            "model_name": f"{provider.id}/{model.id}",
+            "litellm_params": _litellm_params(provider, model),
+        }
+        for provider in config.providers
+        for model in provider.models
+    ]
+
+    result: dict[str, Any] = {"model_list": model_list}
+
+    if config.roles:
+        result["router_settings"] = {
+            "model_group_alias": {
+                role: f"{ref.provider}/{ref.model}"
+                for role, ref in config.roles.items()
+            }
+        }
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Generate a LiteLLM config.yaml from a catalog (CLI entry point).
+
+    Usage: ``python -m llm_catalog.core.codegen catalog.yaml -o out.yaml``.
+    """
+    parser = argparse.ArgumentParser(
+        prog="llm-catalog-codegen",
+        description="Generate a native LiteLLM config.yaml from a catalog.yaml.",
+    )
+    parser.add_argument("catalog", type=Path, help="path to catalog.yaml / .json")
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=None,
+        help="output path (default: stdout)",
+    )
+    args = parser.parse_args(argv)
+
+    config = load_config(args.catalog)
+    rendered = yaml.safe_dump(
+        to_litellm_config(config), sort_keys=False, allow_unicode=True
+    )
+
+    if args.output is None:
+        sys.stdout.write(rendered)
+    else:
+        args.output.write_text(rendered, encoding="utf-8")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

llm_catalog_core-0.1.0/src/llm_catalog/core/config.py

@@ -0,0 +1,271 @@
+# Copyright 2026 Shinsuke Mori
+# SPDX-License-Identifier: Apache-2.0
+"""Declarative ``catalog.yaml`` schema, loader, and validation.
+
+This is the single source of truth for providers, the models they serve, and the
+roles an application references. It mirrors the structure of the TypeScript
+``ai-sdk-catalog`` config so the *same* file can drive both ecosystems: the
+camelCase keys (``baseURL``, ``apiKeyEnvVarName``, ``pathTemplate``,
+``actionMap``) are accepted via Pydantic aliases, while ``populate_by_name``
+also lets Python code build models with snake_case names.
+
+Unlike the TypeScript schema, this Python schema models **gateway providers
+only** — every provider routes through a gateway and every model names a
+``backend``. Direct/resolver providers are out of scope here.
+
+Secrets never live in config: a model carries only ``api_key_env`` (the *name*
+of an environment variable), never the key value itself.
+"""
+
+import json
+import warnings
+from pathlib import Path
+from typing import Any, Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from .errors import ConfigError, ProviderIdCollisionWarning
+
+__all__ = [
+    "Backend",
+    "CatalogConfig",
+    "Gateway",
+    "ModelCapabilities",
+    "ModelEntry",
+    "Provider",
+    "RoleRef",
+    "load_config",
+    "parse_config",
+]
+
+# Built-in LiteLLM provider names. A custom provider id that collides with one of
+# these is silently bypassed by LiteLLM's custom_provider_map (upstream issue
+# #23352), so we warn at load time. This list is intentionally conservative — it
+# covers the common built-ins; it does not need to be exhaustive to be useful.
+_LITELLM_BUILTIN_PROVIDERS: frozenset[str] = frozenset(
+    {
+        "openai",
+        "azure",
+        "azure_ai",
+        "anthropic",
+        "bedrock",
+        "vertex_ai",
+        "vertex_ai_beta",
+        "gemini",
+        "google",
+        "palm",
+        "cohere",
+        "cohere_chat",
+        "mistral",
+        "groq",
+        "xai",
+        "deepseek",
+        "perplexity",
+        "ollama",
+        "ollama_chat",
+        "openrouter",
+        "fireworks_ai",
+        "together_ai",
+        "deepinfra",
+        "cerebras",
+        "replicate",
+        "huggingface",
+        "nlp_cloud",
+        "ai21",
+        "voyage",
+        "databricks",
+        "watsonx",
+        "sagemaker",
+        "cloudflare",
+        "nvidia_nim",
+        "sambanova",
+    }
+)
+
+# camelCase aliases must round-trip both ways (read camelCase from YAML, or build
+# from snake_case in code), so every model uses this config.
+_MODEL_CONFIG = ConfigDict(populate_by_name=True, extra="forbid")
+
+
+class Backend(BaseModel):
+    """How one upstream backend is laid out on the gateway.
+
+    ``path_template`` is the path (relative to the gateway ``base_url``) the
+    gateway expects, with ``{slug}`` (the model) and optionally ``{action}`` (the
+    operation, google only) placeholders. ``action_map`` renames an operation to
+    the gateway's name (e.g. ``streamGenerateContent`` ->
+    ``customStreamGenerateContent``); operations not listed pass through unchanged.
+    """
+
+    model_config = _MODEL_CONFIG
+
+    path_template: str = Field(alias="pathTemplate")
+    action_map: dict[str, str] = Field(default_factory=dict, alias="actionMap")
+
+
+class ModelCapabilities(BaseModel):
+    """Python-side capability hints, namespaced under ``capabilities:``.
+
+    These are optional and ignored by the TypeScript side. They tell the adapters
+    how to drive a model without hardcoding anything gateway-specific.
+    """
+
+    model_config = _MODEL_CONFIG
+
+    structured_output: Literal["native", "tool", "prompted"] = "native"
+    multi_step_tools: bool = True
+    grounding: list[str] = Field(default_factory=list)
+
+
+class ModelEntry(BaseModel):
+    """One model a provider serves, tagged with the backend that handles it."""
+
+    model_config = _MODEL_CONFIG
+
+    id: str
+    backend: Literal["anthropic", "openai", "google"]
+    slug: str | None = None  # path segment; defaults to ``id`` when omitted
+    api: Literal["chat", "responses"] | None = None  # openai backend only
+    settings: dict[str, Any] = Field(default_factory=dict)
+    capabilities: ModelCapabilities = Field(default_factory=ModelCapabilities)
+
+
+class Gateway(BaseModel):
+    """Where the gateway lives, which env var holds its key, and its topology."""
+
+    model_config = _MODEL_CONFIG
+
+    base_url: str = Field(alias="baseURL")
+    api_key_env: str = Field(alias="apiKeyEnvVarName")
+    backends: dict[str, Backend]
+
+
+class Provider(BaseModel):
+    """A gateway provider and the models it serves.
+
+    ``settings`` are provider-level call defaults; each model's own ``settings``
+    are merged on top (model wins).
+    """
+
+    model_config = _MODEL_CONFIG
+
+    id: str
+    gateway: Gateway
+    settings: dict[str, Any] = Field(default_factory=dict)
+    models: list[ModelEntry]
+
+
+class RoleRef(BaseModel):
+    """A role points at exactly one ``(provider, model)`` pair."""
+
+    model_config = _MODEL_CONFIG
+
+    provider: str
+    model: str
+
+
+class CatalogConfig(BaseModel):
+    """The whole catalog: providers plus the roles an app references."""
+
+    model_config = _MODEL_CONFIG
+
+    providers: list[Provider]
+    roles: dict[str, RoleRef] = Field(default_factory=dict)
+
+
+def _check_invariants(config: CatalogConfig) -> None:
+    """Cross-field checks that need the whole object.
+
+    Raises :class:`ConfigError` for hard inconsistencies and emits
+    :class:`ProviderIdCollisionWarning` for the soft LiteLLM-collision case.
+    """
+    provider_ids: set[str] = set()
+    # provider id -> {model id -> ModelEntry}
+    index: dict[str, dict[str, ModelEntry]] = {}
+
+    for provider in config.providers:
+        if provider.id in provider_ids:
+            raise ConfigError(f'Duplicate provider id "{provider.id}".')
+        provider_ids.add(provider.id)
+
+        if provider.id in _LITELLM_BUILTIN_PROVIDERS:
+            warnings.warn(
+                f'Provider id "{provider.id}" collides with a built-in LiteLLM '
+                "provider name; LiteLLM may silently bypass the custom handler "
+                "(issue #23352). Choose a distinct provider id.",
+                ProviderIdCollisionWarning,
+                stacklevel=3,
+            )
+
+        models: dict[str, ModelEntry] = {}
+        for model in provider.models:
+            if model.id in models:
+                raise ConfigError(
+                    f'Duplicate model id "{model.id}" in provider "{provider.id}".'
+                )
+            models[model.id] = model
+
+            if model.backend not in provider.gateway.backends:
+                raise ConfigError(
+                    f'Model "{model.id}" uses backend "{model.backend}", but '
+                    f'"{provider.id}.gateway.backends.{model.backend}" is not '
+                    "configured."
+                )
+            if model.api is not None and model.backend != "openai":
+                raise ConfigError(
+                    f'Model "{model.id}" sets api="{model.api}", which is only '
+                    f'allowed when backend == "openai" (got "{model.backend}").'
+                )
+        index[provider.id] = models
+
+    for role, ref in config.roles.items():
+        models = index.get(ref.provider, {})
+        if ref.provider not in index:
+            raise ConfigError(
+                f'Role "{role}" references unknown provider "{ref.provider}".'
+            )
+        if ref.model not in models:
+            raise ConfigError(
+                f'Role "{role}" references unknown model "{ref.provider}:{ref.model}".'
+            )
+
+
+def parse_config(data: dict[str, Any]) -> CatalogConfig:
+    """Validate an already-parsed mapping and return a typed :class:`CatalogConfig`.
+
+    This is the portable core (no filesystem access): hand it a dict from any
+    source — parsed YAML/JSON, a fixture, an API response. Raises
+    :class:`ConfigError` on any schema or invariant violation.
+    """
+    try:
+        config = CatalogConfig.model_validate(data)
+    except ValidationError as exc:
+        raise ConfigError(str(exc)) from exc
+    _check_invariants(config)
+    return config
+
+
+def load_config(path: str | Path) -> CatalogConfig:
+    """Read ``path`` (.yaml/.yml/.json), validate it, and return the config.
+
+    The extension selects the parser; YAML is a superset of JSON so ``.json``
+    also parses as YAML, but we honour the extension for clarity. Raises
+    :class:`ConfigError` (with the file path) on any problem.
+    """
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    try:
+        data = json.loads(text) if p.suffix.lower() == ".json" else yaml.safe_load(text)
+    except (yaml.YAMLError, json.JSONDecodeError) as exc:
+        raise ConfigError(f"{p}: failed to parse: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise ConfigError(
+            f"{p}: expected a mapping at the top level, got {type(data).__name__}."
+        )
+
+    try:
+        return parse_config(data)
+    except ConfigError as exc:
+        raise ConfigError(f"{p}:\n{exc}") from exc

llm_catalog_core-0.1.0/src/llm_catalog/core/errors.py

@@ -0,0 +1,35 @@
+# Copyright 2026 Shinsuke Mori
+# SPDX-License-Identifier: Apache-2.0
+"""Error and warning types raised by llm-catalog-core.
+
+Everything user-facing inherits from :class:`LLMCatalogError` so callers can
+catch the whole family with one ``except``.
+"""
+
+
+class LLMCatalogError(Exception):
+    """Base class for every error raised by llm-catalog."""
+
+
+class ConfigError(LLMCatalogError):
+    """The ``catalog.yaml`` is structurally invalid or internally inconsistent.
+
+    Raised by :func:`llm_catalog.core.load_config` / ``parse_config`` for schema
+    violations (wrapping Pydantic's ``ValidationError``) and for the cross-field
+    checks (unknown role target, backend not configured, ``api`` on a non-openai
+    backend, ...).
+    """
+
+
+class ResolutionError(LLMCatalogError):
+    """A role or ``provider:model`` key could not be resolved against the config."""
+
+
+class ProviderIdCollisionWarning(UserWarning):
+    """A provider ``id`` collides with a built-in LiteLLM provider name.
+
+    LiteLLM silently bypasses a ``custom_provider_map`` entry whose name clashes
+    with a built-in provider (upstream issue #23352). We surface this as a
+    warning at load time so the collision is caught before it manifests as a
+    confusing routing bug.
+    """

llm_catalog_core-0.1.0/src/llm_catalog/core/resolve.py

@@ -0,0 +1,51 @@
+# Copyright 2026 Shinsuke Mori
+# SPDX-License-Identifier: Apache-2.0
+"""The resolved view of a single model, produced by :class:`Catalog`.
+
+A :class:`ResolvedModel` is a flat, adapter-agnostic snapshot of everything
+needed to call one model through its gateway: the addressing (backend, slug,
+api), the gateway endpoint (``base_url`` + path template), the *name* of the env
+var holding the key, the merged call settings, and the capability hints.
+
+It deliberately holds no Pydantic AI / LiteLLM types and no secret values — the
+key is read from the environment at call time by whichever adapter uses it.
+"""
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from .config import ModelCapabilities
+
+__all__ = ["ResolvedModel"]
+
+
+@dataclass(frozen=True)
+class ResolvedModel:
+    """Flat, gateway-aware description of one model. Adapter-agnostic."""
+
+    provider_id: str
+    model_id: str
+    backend: str
+    slug: str
+    api: str | None
+    base_url: str
+    api_key_env: str
+    path_template: str
+    action_map: dict[str, str] = field(default_factory=dict)
+    settings: dict[str, Any] = field(default_factory=dict)
+    capabilities: ModelCapabilities = field(default_factory=ModelCapabilities)
+
+    def api_key(self) -> str:
+        """Read the key value from the environment, lazily and per call.
+
+        Raises :class:`KeyError` (via ``os.environ``) when the variable is unset,
+        which surfaces a clear, actionable message naming the missing var.
+        """
+        try:
+            return os.environ[self.api_key_env]
+        except KeyError as exc:
+            raise KeyError(
+                f'environment variable "{self.api_key_env}" is not set '
+                f'(needed for provider "{self.provider_id}")'
+            ) from exc

llm_catalog_core-0.1.0/src/llm_catalog/core/transport.py

@@ -0,0 +1,187 @@
+# Copyright 2026 Shinsuke Mori
+# SPDX-License-Identifier: Apache-2.0
+"""Path-rewriting httpx transport that adapts vendor SDKs to a gateway layout.
+
+Each vendor SDK (anthropic / openai / google-genai) builds its own fixed request
+path (``/v1/messages``, ``/chat/completions``, ``/v1beta/models/{m}:{action}``).
+A gateway instead expects a ``path_template`` such as ``anthropic/{slug}``.
+
+:class:`GatewayTransport` sits in the vendor SDK's ``httpx`` client and rewrites
+each outgoing request's path to the gateway's, leaving everything else (method,
+headers, body, query string) intact. It lives in *core* so both adapters reuse
+the exact same rewriting.
+
+Slug source
+-----------
+The ``{slug}`` placeholder is filled from, in order:
+
+* an explicit ``slug`` passed to the transport (what the adapters do — they know
+  the resolved model's slug, which may differ from the model id carried in the
+  request), or
+* the model identifier extracted from the request itself (body ``model`` for
+  fixed-path backends, the URL for google) when no explicit slug is given.
+
+Extraction is what keeps the transport generic and is exercised directly by the
+tests; the explicit-slug path is what lets a configured ``slug`` differ from the
+model id sent upstream in the body.
+"""
+
+import json
+import re
+from collections.abc import Callable
+
+import httpx
+
+__all__ = ["GatewayTransport", "GatewayTransportSync", "HeaderRewrite"]
+
+HeaderRewrite = Callable[[httpx.Headers], None]
+
+# Matches the model id and operation in a google-genai URL path, e.g.
+# "/v1beta/models/gemini-2.5-pro:streamGenerateContent".
+_GOOGLE_PATH = re.compile(r"/models/(?P<model>[^:/]+):(?P<action>[A-Za-z]+)")
+
+# Backends whose model lives in the JSON request body (not the URL).
+_BODY_BACKENDS = frozenset({"anthropic", "openai"})
+
+
+def _extract_slug_action(
+    request: httpx.Request, backend: str
+) -> tuple[str | None, str | None]:
+    """Pull ``(slug, action)`` out of a request for the given backend.
+
+    Returns ``(None, None)`` when nothing can be extracted (the caller then falls
+    back to the configured slug, or leaves the request unrewritten).
+    """
+    if backend == "google":
+        match = _GOOGLE_PATH.search(request.url.path)
+        if match is None:
+            return None, None
+        return match.group("model"), match.group("action")
+
+    if backend in _BODY_BACKENDS:
+        try:
+            raw = request.content
+        except httpx.RequestNotRead:  # streaming body not materialised — uncommon here
+            return None, None
+        if not raw:
+            return None, None
+        try:
+            body = json.loads(raw)
+        except ValueError:  # JSONDecodeError and UnicodeDecodeError both subclass it
+            return None, None
+        model = body.get("model") if isinstance(body, dict) else None
+        return (model if isinstance(model, str) and model else None), None
+
+    return None, None
+
+
+def _build_url(
+    request: httpx.Request,
+    *,
+    base_url: str,
+    path_template: str,
+    action_map: dict[str, str],
+    backend: str,
+    slug: str | None,
+) -> httpx.URL | None:
+    """Compute the rewritten gateway URL, or ``None`` to leave the request as-is."""
+    extracted_slug, action = _extract_slug_action(request, backend)
+    final_slug = slug if slug is not None else extracted_slug
+    if final_slug is None:
+        # Nothing to substitute — don't touch the request.
+        return None
+
+    mapped_action = action_map.get(action, action) if action is not None else ""
+    new_path = path_template.format(slug=final_slug, action=mapped_action)
+
+    base = base_url.rstrip("/")
+    path = new_path.lstrip("/")
+    # Plain concatenation (not httpx.URL.join) so a gateway base path like
+    # ".../base" is preserved rather than treated as a sibling to replace.
+    url = httpx.URL(f"{base}/{path}")
+    # Re-attach the original query string (e.g. google's ?alt=sse).
+    return url.copy_merge_params(request.url.params)
+
+
+class GatewayTransport(httpx.AsyncBaseTransport):
+    """Async transport that rewrites vendor paths to the gateway's layout."""
+
+    def __init__(
+        self,
+        inner: httpx.AsyncBaseTransport,
+        base_url: str,
+        path_template: str,
+        backend: str,
+        action_map: dict[str, str] | None = None,
+        slug: str | None = None,
+        header_rewrite: HeaderRewrite | None = None,
+    ) -> None:
+        self.inner = inner
+        self.base_url = base_url
+        self.path_template = path_template
+        self.backend = backend
+        self.action_map = action_map or {}
+        self.slug = slug
+        self.header_rewrite = header_rewrite
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        """Rewrite the request path to the gateway layout, then delegate."""
+        new_url = _build_url(
+            request,
+            base_url=self.base_url,
+            path_template=self.path_template,
+            action_map=self.action_map,
+            backend=self.backend,
+            slug=self.slug,
+        )
+        if new_url is not None:
+            request.url = new_url
+        if self.header_rewrite is not None:
+            self.header_rewrite(request.headers)
+        return await self.inner.handle_async_request(request)
+
+    async def aclose(self) -> None:
+        """Close the wrapped inner transport."""
+        await self.inner.aclose()
+
+
+class GatewayTransportSync(httpx.BaseTransport):
+    """Synchronous counterpart of :class:`GatewayTransport`."""
+
+    def __init__(
+        self,
+        inner: httpx.BaseTransport,
+        base_url: str,
+        path_template: str,
+        backend: str,
+        action_map: dict[str, str] | None = None,
+        slug: str | None = None,
+        header_rewrite: HeaderRewrite | None = None,
+    ) -> None:
+        self.inner = inner
+        self.base_url = base_url
+        self.path_template = path_template
+        self.backend = backend
+        self.action_map = action_map or {}
+        self.slug = slug
+        self.header_rewrite = header_rewrite
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        """Rewrite the request path to the gateway layout, then delegate."""
+        new_url = _build_url(
+            request,
+            base_url=self.base_url,
+            path_template=self.path_template,
+            action_map=self.action_map,
+            backend=self.backend,
+            slug=self.slug,
+        )
+        if new_url is not None:
+            request.url = new_url
+        if self.header_rewrite is not None:
+            self.header_rewrite(request.headers)
+        return self.inner.handle_request(request)
+
+    def close(self) -> None:
+        """Close the wrapped inner transport."""
+        self.inner.close()