airmux 0.1.2__tar.gz

airmux-0.1.2/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

airmux-0.1.2/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.5
+Name: airmux
+Version: 0.1.2
+Summary: Self-hosted LLM gateway and management CLI
+Project-URL: Documentation, https://github.com/michel-tricot/airmux/tree/main/docs
+Project-URL: Repository, https://github.com/michel-tricot/airmux
+Project-URL: Issues, https://github.com/michel-tricot/airmux/issues
+License-Expression: Elastic-2.0
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: alembic
+Requires-Dist: anyio
+Requires-Dist: argon2-cffi>=23.1
+Requires-Dist: asyncpg
+Requires-Dist: fastapi
+Requires-Dist: httpx[http2]
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
+Requires-Dist: rich
+Requires-Dist: sqlalchemy[asyncio]>=2
+Requires-Dist: sqlmodel
+Requires-Dist: starlette
+Requires-Dist: tiktoken
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer
+Requires-Dist: uvicorn[standard]
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <h1>airmux</h1>
+  <p><strong>One self-hosted LLM gateway. Any compatible client. Multiple providers.</strong></p>
+  <p>
+    Connect through a supported inference API while airmux centralizes provider translation, routing, policy,
+    credentials, failover, and usage accounting behind one endpoint.
+  </p>
+  <p>
+    <a href="https://github.com/michel-tricot/airmux/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/michel-tricot/airmux/actions/workflows/ci.yml/badge.svg"></a>
+    <a href="https://pypi.org/project/airmux/"><img alt="PyPI" src="https://img.shields.io/pypi/v/airmux?logo=pypi&logoColor=white"></a>
+    <a href="https://www.python.org/downloads/"><img alt="Python 3.13+" src="https://img.shields.io/badge/python-3.13%2B-3776AB?logo=python&logoColor=white"></a>
+    <a href="LICENSE"><img alt="Elastic License 2.0" src="https://img.shields.io/badge/license-Elastic--2.0-4C1?logo=elastic&logoColor=white"></a>
+  </p>
+  <p>
+    <a href="#quickstart">Quickstart</a> ·
+    <a href="docs/index.mdx">Documentation</a> ·
+    <a href="CONTRIBUTING.md">Contributing</a> ·
+    <a href="https://github.com/michel-tricot/airmux/issues/new">Report a bug</a>
+  </p>
+</div>
+
+airmux gives applications, agents, CLIs, and services one self-hosted origin for calling multiple provider families.
+Clients can send Chat Completions, Responses, or Messages requests through any SDK or integration that can
+target the corresponding HTTP API. airmux authenticates the workspace, applies policy, selects a model and scoped
+provider credential, translates the request, and records the result.
+
+> [!NOTE]
+> airmux is pre-1.0. Configuration, APIs, and migrations may change before the first stable release.
+
+## Quickstart
+
+Run a local gateway with no Docker, Postgres, or control plane. You need Python 3.13+, [uv](https://docs.astral.sh/uv/),
+and an OpenAI API key.
+
+### 1. Install and start the gateway
+
+```bash
+uv tool install airmux
+mkdir airmux-demo
+cd airmux-demo
+export OPENAI_API_KEY='your-provider-key'
+airmux gateway init
+airmux gateway serve
+```
+
+`init` creates a local configuration, a model taxonomy, and a private inference key under `.airmux/`. The gateway
+reads provider credentials from the environment and reloads taxonomy edits while it runs.
+
+### 2. Make a real model request
+
+In another terminal:
+
+```bash
+cd airmux-demo
+export AIRMUX_INFERENCE_KEY="$(cat .airmux/inference.key)"
+curl --fail-with-body http://127.0.0.1:8080/inf/v1/chat/completions \
+  -H "Authorization: Bearer $AIRMUX_INFERENCE_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Say hello in one word."}],"max_completion_tokens":16}'
+```
+
+The same gateway accepts streaming requests, tool calls, structured output, reasoning, images, and PDF inputs when the
+selected model supports them. Continue with the [gateway-only guide](docs/deployment/gateway.mdx) for configuration and
+operation.
+
+## Use your existing client
+
+Any client that can target one of airmux's exposed HTTP APIs and send an inference key through
+`Authorization: Bearer` or `x-api-key` can connect. That includes SDKs,
+agent frameworks, CLIs, services, and raw HTTP integrations.
+
+| API | Endpoint |
+| --- | --- |
+| Chat Completions | `POST /inf/v1/chat/completions` |
+| Responses | `POST /inf/v1/responses` |
+| Messages | `POST /inf/v1/messages` |
+| Model discovery | `GET /inf/v1/models` and `GET /inf/v1/models/{model_id}` |
+
+The OpenAI SDK is one example. Point it at `/inf/v1` and replace the upstream key with an airmux inference key:
+
+```python
+import os
+
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://127.0.0.1:8080/inf/v1",
+    api_key=os.environ["AIRMUX_INFERENCE_KEY"],
+)
+
+response = client.chat.completions.create(
+    model="openai/gpt-4o-mini",
+    messages=[{"role": "user", "content": "Why use an LLM gateway?"}],
+)
+
+print(response.choices[0].message.content)
+```
+
+The client protocol does not constrain the provider route. A Messages request can target an OpenAI-compatible model,
+and a Chat Completions request can target an Anthropic model. airmux translates the request and returns the response
+and errors in the caller's dialect. See the [OpenAI SDK](docs/guides/openai-sdk.mdx) and
+[Anthropic SDK](docs/guides/anthropic-sdk.mdx) guides for complete examples, including streaming.
+
+## Why airmux
+
+- **Protocol-first clients:** connect any SDK, agent framework, CLI, service, or raw HTTP integration that speaks an exposed API
+- **Policy at the gateway:** compose model and provider allowlists, price ceilings, request limits, credential rules, denials, strict parameters, and fallbacks
+- **Scoped provider secrets:** separate instance, organization, and workspace credentials without exposing secret values to configuration bundles
+- **Predictable failover:** retry eligible credentials and route to bounded backup models without escaping workspace policy
+- **Complete request records:** capture tokens, cost, latency, status, credential scope, configuration version, and every fallback attempt
+- **A resilient request path:** gateways evaluate immutable local bundles and can keep serving through a control-plane outage
+
+The shipped catalog includes Anthropic, Cerebras, DeepSeek, Fireworks, Groq, Mistral, OpenAI, Together, and xAI. Model
+IDs, prices, context windows, modalities, capabilities, and parameter support are explicit, inspectable data in the
+[taxonomy](taxonomy/taxonomy.yml).
+
+## Full-platform quickstart
+
+Use the complete stack when you want the web console, organizations and workspaces, managed credentials, live policy,
+usage history, and audit activity. You need Docker with Compose 2.24.4+, Python 3.13+, uv, and at least one provider API
+key.
+
+```bash
+git clone https://github.com/michel-tricot/airmux.git
+cd airmux
+cp .env.example .env
+```
+
+Add a provider key such as `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` to `.env`, then run:
+
+```bash
+uv tool install airmux
+docker compose up -d --build --wait
+airmux quickstart --url http://localhost:8080
+```
+
+`quickstart` creates or resumes the owner account, organization, and workspace; imports missing provider credentials;
+mints an inference key; and proves the installation with a real model request. Open
+[localhost:8080](http://localhost:8080) for the console.
+
+| Goal | Command |
+| --- | --- |
+| List catalog models | `airmux models list` |
+| Inspect the installation | `airmux doctor` |
+| Follow gateway activity | `airmux events tail --interval 2 --keep 30` |
+| Follow service logs | `docker compose logs -f airmux` |
+| Stop while preserving state | `docker compose down` |
+
+## Architecture
+
+airmux separates mutable management work from the inference request path.
+
+```mermaid
+flowchart LR
+  A[Application] -->|Inference key| G[Data plane]
+  U[Operator] --> C[Console or CLI]
+  C --> M[Control plane]
+  M --> P[(Postgres)]
+  M --> S[(Secret store)]
+  M -->|Versioned bundles| G
+  G -->|Cold secret resolution| S
+  G -->|Provider request| L[LLM provider]
+  G -->|Usage and health| M
+```
+
+Caller dialects and provider protocols cross through one canonical model. Adding a caller dialect requires one ingress
+adapter; adding a provider family requires one egress adapter. Policy, routing, streaming, and metering stay
+provider-neutral instead of multiplying into a translator for every caller and provider pair.
+
+The control plane compiles complete, versioned organization bundles. Data-plane workers validate them, build immutable
+indexes, and atomically adopt them. Inference therefore avoids management database reads and an in-flight request never
+observes partially updated policy. Cold provider-secret resolution is the only database-capable exception, and secret
+values never enter a bundle.
+
+Read the [architecture guide](docs/concepts/architecture.mdx) for the full data flow, failure boundaries, and deployment
+shapes.
+
+## Documentation
+
+| I want to... | Start here |
+| --- | --- |
+| Try the complete stack | [Quickstart](docs/quickstart.mdx) |
+| Connect an application | [OpenAI SDK](docs/guides/openai-sdk.mdx) or [Anthropic SDK](docs/guides/anthropic-sdk.mdx) |
+| Add routing and access rules | [Policy workflow](docs/guides/policy-workflow.mdx) |
+| Understand supported inference shapes | [Inference reference](docs/reference/inference.mdx) |
+| Deploy airmux | [Deployment overview](docs/deployment/index.mdx) |
+| Upgrade or roll back a deployment | [Upgrade and rollback](docs/deployment/upgrades.mdx) |
+| Call the management API | [Management API](docs/reference/management-api.mdx) |
+| Work on the project | [Contributing](CONTRIBUTING.md) and [Development guide](docs/development.mdx) |
+
+The complete management API is generated from [`lib/api-spec/openapi.yaml`](lib/api-spec/openapi.yaml).

airmux-0.1.2/README.md

@@ -0,0 +1,191 @@
+<div align="center">
+  <h1>airmux</h1>
+  <p><strong>One self-hosted LLM gateway. Any compatible client. Multiple providers.</strong></p>
+  <p>
+    Connect through a supported inference API while airmux centralizes provider translation, routing, policy,
+    credentials, failover, and usage accounting behind one endpoint.
+  </p>
+  <p>
+    <a href="https://github.com/michel-tricot/airmux/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/michel-tricot/airmux/actions/workflows/ci.yml/badge.svg"></a>
+    <a href="https://pypi.org/project/airmux/"><img alt="PyPI" src="https://img.shields.io/pypi/v/airmux?logo=pypi&logoColor=white"></a>
+    <a href="https://www.python.org/downloads/"><img alt="Python 3.13+" src="https://img.shields.io/badge/python-3.13%2B-3776AB?logo=python&logoColor=white"></a>
+    <a href="LICENSE"><img alt="Elastic License 2.0" src="https://img.shields.io/badge/license-Elastic--2.0-4C1?logo=elastic&logoColor=white"></a>
+  </p>
+  <p>
+    <a href="#quickstart">Quickstart</a> ·
+    <a href="docs/index.mdx">Documentation</a> ·
+    <a href="CONTRIBUTING.md">Contributing</a> ·
+    <a href="https://github.com/michel-tricot/airmux/issues/new">Report a bug</a>
+  </p>
+</div>
+
+airmux gives applications, agents, CLIs, and services one self-hosted origin for calling multiple provider families.
+Clients can send Chat Completions, Responses, or Messages requests through any SDK or integration that can
+target the corresponding HTTP API. airmux authenticates the workspace, applies policy, selects a model and scoped
+provider credential, translates the request, and records the result.
+
+> [!NOTE]
+> airmux is pre-1.0. Configuration, APIs, and migrations may change before the first stable release.
+
+## Quickstart
+
+Run a local gateway with no Docker, Postgres, or control plane. You need Python 3.13+, [uv](https://docs.astral.sh/uv/),
+and an OpenAI API key.
+
+### 1. Install and start the gateway
+
+```bash
+uv tool install airmux
+mkdir airmux-demo
+cd airmux-demo
+export OPENAI_API_KEY='your-provider-key'
+airmux gateway init
+airmux gateway serve
+```
+
+`init` creates a local configuration, a model taxonomy, and a private inference key under `.airmux/`. The gateway
+reads provider credentials from the environment and reloads taxonomy edits while it runs.
+
+### 2. Make a real model request
+
+In another terminal:
+
+```bash
+cd airmux-demo
+export AIRMUX_INFERENCE_KEY="$(cat .airmux/inference.key)"
+curl --fail-with-body http://127.0.0.1:8080/inf/v1/chat/completions \
+  -H "Authorization: Bearer $AIRMUX_INFERENCE_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Say hello in one word."}],"max_completion_tokens":16}'
+```
+
+The same gateway accepts streaming requests, tool calls, structured output, reasoning, images, and PDF inputs when the
+selected model supports them. Continue with the [gateway-only guide](docs/deployment/gateway.mdx) for configuration and
+operation.
+
+## Use your existing client
+
+Any client that can target one of airmux's exposed HTTP APIs and send an inference key through
+`Authorization: Bearer` or `x-api-key` can connect. That includes SDKs,
+agent frameworks, CLIs, services, and raw HTTP integrations.
+
+| API | Endpoint |
+| --- | --- |
+| Chat Completions | `POST /inf/v1/chat/completions` |
+| Responses | `POST /inf/v1/responses` |
+| Messages | `POST /inf/v1/messages` |
+| Model discovery | `GET /inf/v1/models` and `GET /inf/v1/models/{model_id}` |
+
+The OpenAI SDK is one example. Point it at `/inf/v1` and replace the upstream key with an airmux inference key:
+
+```python
+import os
+
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://127.0.0.1:8080/inf/v1",
+    api_key=os.environ["AIRMUX_INFERENCE_KEY"],
+)
+
+response = client.chat.completions.create(
+    model="openai/gpt-4o-mini",
+    messages=[{"role": "user", "content": "Why use an LLM gateway?"}],
+)
+
+print(response.choices[0].message.content)
+```
+
+The client protocol does not constrain the provider route. A Messages request can target an OpenAI-compatible model,
+and a Chat Completions request can target an Anthropic model. airmux translates the request and returns the response
+and errors in the caller's dialect. See the [OpenAI SDK](docs/guides/openai-sdk.mdx) and
+[Anthropic SDK](docs/guides/anthropic-sdk.mdx) guides for complete examples, including streaming.
+
+## Why airmux
+
+- **Protocol-first clients:** connect any SDK, agent framework, CLI, service, or raw HTTP integration that speaks an exposed API
+- **Policy at the gateway:** compose model and provider allowlists, price ceilings, request limits, credential rules, denials, strict parameters, and fallbacks
+- **Scoped provider secrets:** separate instance, organization, and workspace credentials without exposing secret values to configuration bundles
+- **Predictable failover:** retry eligible credentials and route to bounded backup models without escaping workspace policy
+- **Complete request records:** capture tokens, cost, latency, status, credential scope, configuration version, and every fallback attempt
+- **A resilient request path:** gateways evaluate immutable local bundles and can keep serving through a control-plane outage
+
+The shipped catalog includes Anthropic, Cerebras, DeepSeek, Fireworks, Groq, Mistral, OpenAI, Together, and xAI. Model
+IDs, prices, context windows, modalities, capabilities, and parameter support are explicit, inspectable data in the
+[taxonomy](taxonomy/taxonomy.yml).
+
+## Full-platform quickstart
+
+Use the complete stack when you want the web console, organizations and workspaces, managed credentials, live policy,
+usage history, and audit activity. You need Docker with Compose 2.24.4+, Python 3.13+, uv, and at least one provider API
+key.
+
+```bash
+git clone https://github.com/michel-tricot/airmux.git
+cd airmux
+cp .env.example .env
+```
+
+Add a provider key such as `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` to `.env`, then run:
+
+```bash
+uv tool install airmux
+docker compose up -d --build --wait
+airmux quickstart --url http://localhost:8080
+```
+
+`quickstart` creates or resumes the owner account, organization, and workspace; imports missing provider credentials;
+mints an inference key; and proves the installation with a real model request. Open
+[localhost:8080](http://localhost:8080) for the console.
+
+| Goal | Command |
+| --- | --- |
+| List catalog models | `airmux models list` |
+| Inspect the installation | `airmux doctor` |
+| Follow gateway activity | `airmux events tail --interval 2 --keep 30` |
+| Follow service logs | `docker compose logs -f airmux` |
+| Stop while preserving state | `docker compose down` |
+
+## Architecture
+
+airmux separates mutable management work from the inference request path.
+
+```mermaid
+flowchart LR
+  A[Application] -->|Inference key| G[Data plane]
+  U[Operator] --> C[Console or CLI]
+  C --> M[Control plane]
+  M --> P[(Postgres)]
+  M --> S[(Secret store)]
+  M -->|Versioned bundles| G
+  G -->|Cold secret resolution| S
+  G -->|Provider request| L[LLM provider]
+  G -->|Usage and health| M
+```
+
+Caller dialects and provider protocols cross through one canonical model. Adding a caller dialect requires one ingress
+adapter; adding a provider family requires one egress adapter. Policy, routing, streaming, and metering stay
+provider-neutral instead of multiplying into a translator for every caller and provider pair.
+
+The control plane compiles complete, versioned organization bundles. Data-plane workers validate them, build immutable
+indexes, and atomically adopt them. Inference therefore avoids management database reads and an in-flight request never
+observes partially updated policy. Cold provider-secret resolution is the only database-capable exception, and secret
+values never enter a bundle.
+
+Read the [architecture guide](docs/concepts/architecture.mdx) for the full data flow, failure boundaries, and deployment
+shapes.
+
+## Documentation
+
+| I want to... | Start here |
+| --- | --- |
+| Try the complete stack | [Quickstart](docs/quickstart.mdx) |
+| Connect an application | [OpenAI SDK](docs/guides/openai-sdk.mdx) or [Anthropic SDK](docs/guides/anthropic-sdk.mdx) |
+| Add routing and access rules | [Policy workflow](docs/guides/policy-workflow.mdx) |
+| Understand supported inference shapes | [Inference reference](docs/reference/inference.mdx) |
+| Deploy airmux | [Deployment overview](docs/deployment/index.mdx) |
+| Upgrade or roll back a deployment | [Upgrade and rollback](docs/deployment/upgrades.mdx) |
+| Call the management API | [Management API](docs/reference/management-api.mdx) |
+| Work on the project | [Contributing](CONTRIBUTING.md) and [Development guide](docs/development.mdx) |
+
+The complete management API is generated from [`lib/api-spec/openapi.yaml`](lib/api-spec/openapi.yaml).

airmux-0.1.2/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "airmux"
+version = "0.1.2"
+description = "Self-hosted LLM gateway and management CLI"
+readme = "README.md"
+license = "Elastic-2.0"
+requires-python = ">=3.13"
+dependencies = [
+  "alembic",
+  "anyio",
+  "argon2-cffi>=23.1",
+  "asyncpg",
+  "fastapi",
+  "httpx[http2]",
+  "pydantic>=2",
+  "python-dotenv",
+  "pyyaml",
+  "rich",
+  "sqlalchemy[asyncio]>=2",
+  "sqlmodel",
+  "starlette",
+  "tiktoken",
+  "tomli-w>=1.2.0",
+  "typer",
+  "uvicorn[standard]",
+]
+
+[project.urls]
+Documentation = "https://github.com/michel-tricot/airmux/tree/main/docs"
+Repository = "https://github.com/michel-tricot/airmux"
+Issues = "https://github.com/michel-tricot/airmux/issues"
+
+[project.scripts]
+airmux = "cli.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = [
+  "src/api_models",
+  "src/airmux_runtime",
+  "src/cli",
+  "src/contract",
+  "src/control_plane",
+  "src/data_plane",
+]

airmux-0.1.2/src/airmux_runtime/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

airmux-0.1.2/src/airmux_runtime/config.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated
+
+import yaml
+from pydantic import AfterValidator, Field, ValidationInfo
+
+_REFERENCE = re.compile(r"^\$\{(env|file):(.+)\}$")
+_DEFAULT_SEPARATOR = ":-"
+
+
+class UnsupportedRefSchemeError(ValueError):
+    def __init__(self, scheme: str) -> None:
+        super().__init__(f"unsupported configuration reference scheme: {scheme}")
+
+
+class MissingConfigReferenceError(ValueError):
+    def __init__(self, scheme: str, target: str) -> None:
+        super().__init__(f"configuration references missing {scheme} value: {target}")
+
+
+class InvalidConfigReferenceError(ValueError):
+    def __init__(self) -> None:
+        super().__init__("configuration references must occupy the whole YAML value and use the env or file scheme")
+
+
+@dataclass(frozen=True)
+class ConfigContext:
+    base_dir: Path
+
+
+def _resolve_path(path: Path, info: ValidationInfo) -> Path:
+    if isinstance(info.context, ConfigContext):
+        return info.context.base_dir / path
+    return path
+
+
+ConfigPath = Annotated[Path, AfterValidator(_resolve_path), Field(validate_default=True)]
+
+
+def load_yaml(path: Path) -> object:
+    return yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+
+
+def _split_default(value: str) -> tuple[str, str | None]:
+    target, separator, fallback = value.partition(_DEFAULT_SEPARATOR)
+    return (target, fallback) if separator else (target, None)
+
+
+def resolve_ref(ref: str, *, base_dir: Path = Path()) -> str:
+    scheme, separator, value = ref.partition(":")
+    if not separator or scheme not in {"env", "file"}:
+        raise UnsupportedRefSchemeError(scheme)
+    target, fallback = _split_default(value)
+    if scheme == "env":
+        resolved = os.environ.get(target, fallback)
+    else:
+        source = base_dir / target
+        resolved = source.read_text(encoding="utf-8").strip() if source.is_file() else fallback
+    if resolved is None:
+        raise MissingConfigReferenceError(scheme, target)
+    return resolved
+
+
+def resolve_refs(node: object, *, base_dir: Path = Path()) -> object:
+    if isinstance(node, dict):
+        return {key: resolve_refs(value, base_dir=base_dir) for key, value in node.items()}
+    if isinstance(node, list):
+        return [resolve_refs(value, base_dir=base_dir) for value in node]
+    if isinstance(node, str):
+        if match := _REFERENCE.fullmatch(node):
+            return resolve_ref(f"{match.group(1)}:{match.group(2)}", base_dir=base_dir)
+        if "${" in node:
+            raise InvalidConfigReferenceError
+    return node
+
+
+def load_config_section(name: str, config_path: str | Path) -> dict[str, object]:
+    path = Path(config_path)
+    if not path.is_file():
+        raise FileNotFoundError(path)
+    document = load_yaml(path)
+    if not isinstance(document, dict):
+        message = f"{path} must contain a {name} section"
+        raise TypeError(message)
+    declared = document.get(name)
+    if not isinstance(declared, dict):
+        message = f"{path} must contain a {name} section"
+        raise TypeError(message)
+    section = resolve_refs(declared, base_dir=path.parent)
+    if not isinstance(section, dict):
+        message = f"{path} must contain a {name} mapping"
+        raise TypeError(message)
+    return {str(key): value for key, value in section.items()}