voiceops 0.1.3__py3-none-any.whl

voiceops/__init__.py

@@ -0,0 +1,3 @@
+"""voiceops: deployment discipline for voice agents (see docs/PLAN.md)."""
+
+__version__ = "0.1.3"

voiceops/_imports.py

@@ -0,0 +1,28 @@
+"""Load a project object named as "package.module:ATTR", relative to the project root."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+from typing import Any
+
+
+class ImportSpecError(ValueError):
+    pass
+
+
+def load_object(spec: str, root: Path, what: str = "object") -> Any:
+    module_name, _, attr = spec.partition(":")
+    if not module_name or not attr:
+        raise ImportSpecError(f"{what} must look like 'package.module:ATTR', got {spec!r}")
+    added = str(root) not in sys.path
+    if added:
+        sys.path.insert(0, str(root))
+    try:
+        return getattr(importlib.import_module(module_name), attr)
+    except (ImportError, AttributeError) as e:
+        raise ImportSpecError(f"cannot load {what} from {spec!r}: {e}") from e
+    finally:
+        if added:
+            sys.path.remove(str(root))

voiceops/cli.py

@@ -0,0 +1,237 @@
+"""The `voiceops` command. Subcommands land with their modules (PLAN §4.5)."""
+
+from pathlib import Path
+
+import typer
+from dotenv import load_dotenv
+
+from voiceops import __version__
+from voiceops.config import ConfigError, PushError, load_config, stale_files, write
+from voiceops.config import build as build_files
+from voiceops.config import dry_run as push_dry_run
+from voiceops.config import push as push_profile
+
+app = typer.Typer(help="Deployment discipline for voice agents.", no_args_is_help=True)
+CONFIG = typer.Option(Path("voiceops.toml"), "--config", "-c", help="Project config file.")
+DIRECTORY = typer.Option(None, help="Where to create it (default: ./<name>).")
+KIT_SOURCE = typer.Option(None, help="Use a local kit checkout (its packages/ folder), not PyPI.")
+
+
+@app.callback()
+def main() -> None:
+    """Deployment discipline for voice agents."""
+
+
+@app.command()
+def version() -> None:
+    """Print the kit version."""
+    typer.echo(__version__)
+
+
+@app.command()
+def init(
+    name: str = typer.Argument(..., help="Project name: lowercase, digits, dashes."),
+    organisation: str = typer.Option("Example Organisation", help="Who the agent speaks for."),
+    directory: Path = DIRECTORY,
+    kit_source: Path = KIT_SOURCE,
+) -> None:
+    """Create a new use-case project with the kit wired in."""
+    from voiceops.scaffold import init as scaffold
+
+    target = directory or Path(name)
+    try:
+        written = scaffold(target, name, organisation, kit_source)
+    except ConfigError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from e
+    typer.echo(f"created {target} ({len(written)} files)")
+    typer.echo(f"next: cd {target} && uv sync && uv run voiceops gate")
+
+
+@app.command()
+def build(
+    check: bool = typer.Option(False, help="Fail if the committed build is stale (for CI)."),
+    config: Path = CONFIG,
+) -> None:
+    """Compose agent configs and tool schemas into the build directory."""
+    try:
+        cfg = load_config(config)
+        files = build_files(cfg)
+    except ConfigError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from e
+    if check:
+        stale = stale_files(cfg, files)
+        if stale:
+            typer.echo(f"stale agent build files (run `voiceops build`): {stale}", err=True)
+            raise typer.Exit(1)
+        typer.echo("agent build up to date")
+        return
+    write(cfg, files)
+    typer.echo(f"wrote {len(files)} files to {cfg.path(cfg.agent.build_dir)}")
+
+
+@app.command()
+def push(
+    profile: str = typer.Option(..., help="Profile to push, as named in the profiles file."),
+    base_url: str = typer.Option(..., help="Public HTTPS URL of the project's tool API."),
+    dry_run: bool = typer.Option(False, help="Print the payloads, call nothing."),
+    config: Path = CONFIG,
+) -> None:
+    """Create or update the profile's tools and agent on the platform, idempotently."""
+    try:
+        cfg = load_config(config)
+        if dry_run:
+            typer.echo(push_dry_run(cfg, profile, base_url))
+            return
+        load_dotenv(cfg.root / ".env")
+        typer.echo(push_profile(cfg, profile, base_url))
+    except (ConfigError, PushError) as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from e
+
+
+@app.command()
+def gate(
+    level: str = typer.Option("all", help="tool | conversation | all"),
+    only: str = typer.Option("", help="Comma-separated scenario ids (writes partial.json)."),
+    smoke: bool = typer.Option(False, help="Only scenarios marked smoke."),
+    config: Path = CONFIG,
+) -> None:
+    """Run the release gate. Exit 0 = PASS, 1 = FAIL, 2 = ERRORED."""
+    from voiceops.evals import EXIT, gate_from_config, iter_failures
+
+    if level not in ("tool", "conversation", "all"):
+        typer.echo("error: --level must be tool, conversation or all", err=True)
+        raise typer.Exit(2)
+    try:
+        cfg = load_config(config)
+        load_dotenv(cfg.root / ".env")
+        report, out = gate_from_config(cfg, level, [s for s in only.split(",") if s], smoke)
+    except (ConfigError, ValueError) as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from e
+    status = report["gate"]["status"]
+    typer.echo(f"gate {status}: {report['gate']['summary']}")
+    for line in iter_failures(report):
+        typer.echo(f"  {line}")
+    typer.echo(f"report: {out}")
+    raise typer.Exit(EXIT[status])
+
+
+@app.command()
+def check(
+    base_url: str = typer.Argument(None, help="Override [deploy] base_url."),
+    config: Path = CONFIG,
+) -> None:
+    """Run the declared deploy checks against a live deployment."""
+    from voiceops.deploy.run import run_checks
+
+    try:
+        cfg = load_config(config)
+        load_dotenv(cfg.root / ".env")
+        results = run_checks(cfg, base_url)
+    except ConfigError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from e
+    for r in results:
+        typer.echo(r.line())
+    raise typer.Exit(0 if all(r.ok for r in results) else 1)
+
+
+@app.command()
+def call(
+    setup: bool = typer.Option(False, help="Import the Twilio number into ElevenLabs first."),
+    config: Path = CONFIG,
+) -> None:
+    """Place one test call to the single allow-listed number."""
+    from voiceops._imports import load_object
+    from voiceops.review import import_number, place_call
+
+    try:
+        cfg = load_config(config)
+        load_dotenv(cfg.root / ".env")
+        if setup:
+            typer.echo(f"phone number imported: {import_number(cfg)}")
+            return
+        placed = place_call(cfg)
+    except ConfigError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from e
+    typer.echo(f"calling your allow-listed number ending {placed['to']}")
+    typer.echo(f"conversation_id: {placed['conversation_id']}")
+    if cfg.review and cfg.review.instructions:
+        typer.echo(load_object(cfg.review.instructions, cfg.root, "[review] instructions")())
+    typer.echo("afterwards: voiceops fetch <conversation_id>")
+
+
+def _sheet_options(cfg):
+    from voiceops.evals import LeakDetector
+    from voiceops.review import SheetOptions
+
+    rv = cfg.review
+    vocab = cfg.path(cfg.evals.leak_vocabulary) if cfg.evals else None
+    return SheetOptions(
+        disclosure_markers=rv.disclosure_markers,
+        verify_tool=rv.verify_tool,
+        verified_status=rv.verified_status,
+        leak_context=rv.leak_context,
+        unbacked_promises=rv.unbacked_promises,
+        detector=LeakDetector.from_toml(vocab) if vocab and vocab.exists() else None,
+    )
+
+
+def _write_sheet(cfg, conv: dict, title: str | None) -> Path:
+    from voiceops.review import render
+
+    out = cfg.path(cfg.review.sheets)
+    out.mkdir(parents=True, exist_ok=True)
+    path = out / f"{conv.get('conversation_id', 'call')}.md"
+    path.write_text(render(conv, _sheet_options(cfg), title))
+    return path
+
+
+@app.command()
+def fetch(
+    conversation_id: str,
+    title: str = typer.Option(None, help="Sheet title, e.g. 'Call 02 · Confirm and reschedule'."),
+    config: Path = CONFIG,
+) -> None:
+    """Save a call's raw conversation and audio locally, and render its review sheet."""
+    from voiceops.review import fetch_conversation, recordings_ignored
+
+    try:
+        cfg = load_config(config)
+        load_dotenv(cfg.root / ".env")
+        conv, folder = fetch_conversation(cfg, conversation_id)
+    except ConfigError as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from e
+    if recordings_ignored(folder) is False:
+        typer.echo(f"warning: {folder} is not gitignored; recordings must stay local", err=True)
+    typer.echo(f"saved raw conversation and audio in {folder}")
+    typer.echo(f"review sheet: {_write_sheet(cfg, conv, title)}")
+
+
+@app.command()
+def review(
+    conversation_json: Path,
+    title: str = typer.Option(None, help="Sheet title."),
+    config: Path = CONFIG,
+) -> None:
+    """Render a review sheet from a saved raw conversation (no network)."""
+    import json
+
+    try:
+        cfg = load_config(config)
+        if cfg.review is None:
+            raise ConfigError("voiceops.toml has no [review] section")
+        conv = json.loads(conversation_json.read_text())
+    except (ConfigError, OSError, ValueError) as e:
+        typer.echo(f"error: {e}", err=True)
+        raise typer.Exit(2) from e
+    typer.echo(f"review sheet: {_write_sheet(cfg, conv, title)}")
+
+
+if __name__ == "__main__":
+    app()

voiceops/config/__init__.py

@@ -0,0 +1,21 @@
+"""Agent configs from prompt fragments and profiles, with shipped safety defaults, tool schemas
+from Pydantic models, a drift check and an idempotent push (PLAN §2, §4.4)."""
+
+from voiceops.config.build import build, stale_files, write
+from voiceops.config.fragments import SAFETY_SLOTS, kit_fragment
+from voiceops.config.project import ConfigError, VoiceopsConfig, load_config
+from voiceops.config.push import PushError, dry_run, push
+
+__all__ = [
+    "SAFETY_SLOTS",
+    "ConfigError",
+    "PushError",
+    "VoiceopsConfig",
+    "build",
+    "dry_run",
+    "kit_fragment",
+    "load_config",
+    "push",
+    "stale_files",
+    "write",
+]

voiceops/config/build.py

@@ -0,0 +1,118 @@
+"""Compose agent configs from fragments + profiles, and tool schemas from the request models.
+
+Output is deterministic and committed, so every prompt or tool change shows up as a
+reviewable diff; `check` fails on drift (for CI). Files written to [agent] build_dir:
+
+  tools.json        webhook tool definitions
+  <profile>.json    one agent config per profile
+  safety.json       how each safety slot was satisfied in each profile
+"""
+
+from __future__ import annotations
+
+import json
+
+from voiceops.config.fragments import check_safety_config, compose
+from voiceops.config.project import ConfigError, VoiceopsConfig
+from voiceops.config.tools import Tools, load_tools, tool_schema
+
+
+def _dump(obj) -> str:
+    return json.dumps(obj, indent=2, ensure_ascii=False, sort_keys=True) + "\n"
+
+
+def agent_config(key: str, p: dict, cfg: VoiceopsConfig, tools: Tools) -> tuple[dict, dict]:
+    a = cfg.agent
+    direction = a.directions.get(p["direction"])
+    if direction is None:
+        raise ConfigError(f"profile {key}: no [agent.directions.{p['direction']}]")
+    prompt, safety = compose(
+        key, p["fragments"], a, cfg.path(a.fragments), recording=p["record_voice"]
+    )
+    phone = direction.phone_audio
+    config = {
+        "name": p["name"],
+        "conversation_config": {
+            "agent": {
+                # A profile can override its direction's first message (e.g. no recording
+                # notice on a profile that doesn't record).
+                "first_message": p.get("first_message", direction.first_message),
+                "language": a.language,
+                "prompt": {
+                    "llm": a.llm,
+                    "temperature": a.temperature,
+                    "prompt": prompt,
+                    "tool_names": [n for n in tools if n not in direction.exclude_tools],
+                    # The agent hangs up itself after the goodbye, instead of looping on
+                    # goodbyes until the caller hangs up.
+                    "built_in_tools": {
+                        "end_call": {
+                            "name": "end_call",
+                            "description": a.end_call_description,
+                            "params": {"system_tool_type": "end_call"},
+                        }
+                    },
+                },
+            },
+            "tts": {
+                "model_id": a.tts_model,
+                "voice_id": a.voice_id,
+                **({"agent_output_audio_format": "ulaw_8000"} if phone else {}),
+            },
+            **({"asr": {"user_input_audio_format": "ulaw_8000"}} if phone else {}),
+        },
+        "platform_settings": {
+            "privacy": {
+                "record_voice": p["record_voice"],
+                "zero_retention_mode": p["zero_retention_mode"],
+            }
+        },
+    }
+    return config, safety
+
+
+# Platform constraint (ElevenLabs, 2026-10-17): agents whose language is English must use an
+# English TTS model; the multilingual v2.5 models are refused at push time.
+ENGLISH_TTS_MODELS = frozenset({"eleven_turbo_v2", "eleven_flash_v2"})
+
+
+def check_platform_constraints(cfg: VoiceopsConfig) -> None:
+    a = cfg.agent
+    if a.language == "en" and a.tts_model not in ENGLISH_TTS_MODELS:
+        raise ConfigError(
+            f'[agent] language = "en" needs tts_model in {sorted(ENGLISH_TTS_MODELS)}'
+            f" (got {a.tts_model!r}); the platform refuses other models for English agents"
+        )
+
+
+def build(cfg: VoiceopsConfig) -> dict[str, str]:
+    """Returns {filename: text} for the build directory. Raises ConfigError."""
+    check_safety_config(cfg.agent)
+    check_platform_constraints(cfg)
+    tools = load_tools(cfg.agent.tools, cfg.root)
+    for direction, d in cfg.agent.directions.items():
+        unknown = sorted(set(d.exclude_tools) - set(tools))
+        if unknown:
+            raise ConfigError(f"[agent.directions.{direction}] excludes unknown tools {unknown}")
+    profiles = json.loads(cfg.path(cfg.agent.profiles).read_text())
+    files = {"tools.json": _dump([tool_schema(n, tools, cfg) for n in tools])}
+    manifest = {}
+    for key, p in profiles.items():
+        if key.startswith("_"):
+            continue
+        files[f"{key}.json"], manifest[key] = agent_config(key, p, cfg, tools)
+        files[f"{key}.json"] = _dump(files[f"{key}.json"])
+    files["safety.json"] = _dump(manifest)
+    return files
+
+
+def stale_files(cfg: VoiceopsConfig, files: dict[str, str]) -> list[str]:
+    out = cfg.path(cfg.agent.build_dir)
+    return [n for n, t in files.items() if not (out / n).exists() or (out / n).read_text() != t]
+
+
+def write(cfg: VoiceopsConfig, files: dict[str, str]) -> None:
+    out = cfg.path(cfg.agent.build_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    for name, text in files.items():
+        (out / name).write_text(text)

voiceops/config/fragments.py

@@ -0,0 +1,88 @@
+"""Prompt composition with the kit's safety defaults (PLAN §4.4).
+
+Each safety slot is satisfied in every profile in exactly one way:
+
+  reworded   the project maps the slot to its own fragment ([agent.safety]); that
+             fragment must then be in the profile, or the build fails.
+  default    the kit's wording (voiceops/config/safety/<slot>.md) is appended.
+  removed    only with a reason in [agent.allow_remove]; recorded in safety.json.
+
+So safety can be reworded, but never dropped silently.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib.resources import files
+from pathlib import Path
+
+from voiceops.config.project import AgentSection, ConfigError
+
+SAFETY_SLOTS = (
+    "ai_disclosure",
+    "upset_caller",
+    "identity_before_detail",
+    "third_party_voicemail",
+    "human_on_request",
+    "no_unbacked_promises",
+    "closing",
+)
+_VAR = re.compile(r"\{\{(\w+)\}\}")
+
+
+def kit_fragment(slot: str) -> str:
+    return files("voiceops.config").joinpath("safety", f"{slot}.md").read_text().strip()
+
+
+def _fill(slot: str, text: str, values: dict[str, str]) -> str:
+    missing = sorted({v for v in _VAR.findall(text) if v not in values})
+    if missing:
+        raise ConfigError(
+            f"kit safety fragment {slot!r} needs [agent.vars] {', '.join(missing)}"
+            f' (or reword it with [agent.safety] {slot} = "<your fragment>")'
+        )
+    return _VAR.sub(lambda m: values[m.group(1)], text)
+
+
+def check_safety_config(agent: AgentSection) -> None:
+    unknown = sorted((set(agent.safety) | set(agent.allow_remove)) - set(SAFETY_SLOTS))
+    if unknown:
+        raise ConfigError(f"unknown safety slots {unknown} (known: {', '.join(SAFETY_SLOTS)})")
+    both = sorted(set(agent.safety) & set(agent.allow_remove))
+    if both:
+        raise ConfigError(f"safety slots both reworded and removed: {both}")
+    blank = sorted(k for k, why in agent.allow_remove.items() if not why.strip())
+    if blank:
+        raise ConfigError(f"allow_remove needs a reason for: {blank}")
+
+
+def compose(
+    key: str, fragments: list[str], agent: AgentSection, fragment_dir: Path, recording: bool
+) -> tuple[str, dict[str, str]]:
+    """Returns (prompt, how each safety slot was satisfied) for one profile."""
+    missing = [f for f in agent.required_fragments if f not in fragments]
+    if missing:
+        raise ConfigError(f"profile {key} is missing required fragments: {missing}")
+    parts = [(fragment_dir / f"{f}.md").read_text().strip() for f in fragments]
+    values = {"recording_notice": ", and that the call is recorded" if recording else ""}
+    values |= agent.vars
+    manifest: dict[str, str] = {}
+    for slot in SAFETY_SLOTS:
+        if slot in agent.allow_remove:
+            manifest[slot] = f"removed: {agent.allow_remove[slot]}"
+        elif slot in agent.safety:
+            # One fragment, or alternatives (e.g. a disclosure with and without a recording
+            # notice): the profile must include at least one of them.
+            options = agent.safety[slot]
+            options = [options] if isinstance(options, str) else options
+            present = [f for f in options if f in fragments]
+            if not present:
+                raise ConfigError(
+                    f"profile {key} drops safety slot {slot!r}: none of {options} is in the"
+                    " profile (add one, or [agent.allow_remove] with a reason)"
+                )
+            manifest[slot] = "project: " + ", ".join(present)
+        else:
+            parts.append(_fill(slot, kit_fragment(slot), values))
+            manifest[slot] = "kit default"
+    return "\n\n".join(parts) + "\n", manifest

voiceops/config/project.py

@@ -0,0 +1,159 @@
+"""`voiceops.toml`: a project's contract. Every command reads the same declared setup.
+
+Relative paths resolve from the directory holding the file. Unknown keys in the
+sections read here are errors, so a typo can't silently fall back to a default.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from voiceops.deploy.spec import Check, SessionSpec
+
+CONFIG_FILE = "voiceops.toml"
+
+
+class ConfigError(ValueError):
+    pass
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class ProjectSection(_Strict):
+    name: str
+    locales: list[str] = []
+
+
+class Direction(_Strict):
+    first_message: str
+    phone_audio: bool = False  # telephone codec (ulaw_8000) in and out, no resampling
+    exclude_tools: list[str] = []
+
+
+class AgentSection(_Strict):
+    fragments: Path = Path("agent/fragments")
+    profiles: Path = Path("agent/profiles.json")
+    build_dir: Path = Path("agent/build")
+    tools: str  # "package.module:ATTR", a dict of name -> (Pydantic model, description)
+    language: str
+    llm: str
+    temperature: float = 0.2
+    voice_id: str
+    tts_model: str = "eleven_flash_v2_5"
+    tool_timeout_secs: int = 10
+    end_call_description: str = "End the call after logging the outcome and saying goodbye."
+    directions: dict[str, Direction]
+    # Kit safety slot -> the project fragment that rewords it, or a list of alternatives
+    # (each profile must include at least one). See voiceops.config.fragments.
+    safety: dict[str, str | list[str]] = {}
+    # Kit safety slot -> reason for dropping it. Recorded in the build's safety.json.
+    allow_remove: dict[str, str] = {}
+    # Project fragments every profile must include (domain safety rules).
+    required_fragments: list[str] = []
+    # Values for {{placeholders}} in the kit's default safety fragments.
+    vars: dict[str, str] = {}
+
+
+class GuardSection(_Strict):
+    secret_header: str = "X-Tool-Secret"
+    token_header: str = "X-Call-Token"
+    token_variable: str = "secret__call_token"  # platform dynamic variable holding the token
+
+
+class PushSection(_Strict):
+    secret_name: str  # name of the tool secret stored on the platform
+    state: Path = Path("agent/state.json")
+    api_base: str = "https://api.elevenlabs.io"
+    api_key_env: str = "ELEVENLABS_API_KEY"
+    tool_secret_env: str = "TOOL_SECRET"
+
+
+class EvalsSection(_Strict):
+    scenarios: str  # "package.module:ATTR", a list of voiceops.evals.Scenario
+    # "package.module:ATTR", a context manager factory: run_id -> run(scenario_id) -> checks
+    tool_runner: str | None = None
+    # "package.module:ATTR", a factory: config -> voiceops.evals.ConversationSetup
+    conversation: str | None = None
+    leak_vocabulary: Path = Path("evals/leak_vocabulary.toml")
+    known_answers: Path = Path("evals/known_answer")
+    max_false_alarms: int = 2
+    # Scenario checks that, when False, count as a privacy leak in the report.
+    leak_checks: list[str] = ["nothing_disclosed", "no_privacy_leak"]
+    results: Path = Path("evals/results")
+
+
+class DeploySection(_Strict):
+    base_url: str  # or "env:NAME"
+    timeout_s: float = 30
+    checks: list[Check]
+
+
+class ReviewSection(_Strict):
+    allowlist_env: str = "DEMO_PHONE_ALLOWLIST"  # exactly one E.164 number may be dialled
+    profile: str  # the built profile whose pushed agent places test calls
+    api_url: str  # the project's API, or "env:NAME"
+    session: SessionSpec  # opens the call's session; the agent gets its token
+    instructions: str | None = None  # "package.module:ATTR" -> str printed before a call
+    recordings: Path = Path("recordings")  # raw conversations and audio (keep gitignored)
+    sheets: Path = Path("review")  # rendered review sheets
+    disclosure_markers: list[str] = ["ai assistant", "artificial intelligence"]
+    verify_tool: str = "verify_identity"
+    verified_status: str = "verified"
+    leak_context: str = "subject"
+    # Phrases that promise something no tool does (e.g. "by email"): flagged for review.
+    unbacked_promises: list[str] = []
+
+
+class VoiceopsConfig(BaseModel):
+    model_config = ConfigDict(extra="ignore")  # sections for other modules ([ledger], ...)
+
+    project: ProjectSection
+    agent: AgentSection
+    guard: GuardSection = GuardSection()
+    push: PushSection | None = None
+    evals: EvalsSection | None = None
+    deploy: DeploySection | None = None
+    review: ReviewSection | None = None
+    root: Path = Path(".")
+
+    def path(self, p: Path) -> Path:
+        return p if p.is_absolute() else self.root / p
+
+
+def resolve_env(value: str) -> str:
+    """ "env:NAME" -> the environment variable (must be set); anything else as is."""
+    if isinstance(value, str) and value.startswith("env:"):
+        name = value[4:]
+        v = os.environ.get(name, "").strip()
+        if not v:
+            raise ConfigError(f"{name} is not set (see .env.example)")
+        return v
+    return value
+
+
+def resolve_env_tree(obj):
+    if isinstance(obj, dict):
+        return {k: resolve_env_tree(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [resolve_env_tree(v) for v in obj]
+    return resolve_env(obj)
+
+
+def load_config(path: str | Path = CONFIG_FILE) -> VoiceopsConfig:
+    path = Path(path)
+    try:
+        data = tomllib.loads(path.read_text())
+    except FileNotFoundError as e:
+        raise ConfigError(f"{path} not found") from e
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"{path}: {e}") from e
+    try:
+        return VoiceopsConfig(**data, root=path.resolve().parent)
+    except ValidationError as e:
+        raise ConfigError(f"{path}: {e}") from e