intentseal-core 0.1.0__py3-none-any.whl

intentseal_core/__init__.py

@@ -0,0 +1,15 @@
+"""IntentSeal Core Engine."""
+
+import os
+
+__version__ = "0.1.0"
+
+
+def adopt_legacy_env() -> None:
+    """Settings were named ASG_* before 8 Oct 2026 (D-038). An old name still works when the new one is unset."""
+    for name, value in list(os.environ.items()):
+        if name.startswith("ASG_"):
+            os.environ.setdefault("INTENTSEAL_" + name[4:], value)
+
+
+adopt_legacy_env()

intentseal_core/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

intentseal_core/action_guard.py

@@ -0,0 +1,174 @@
+"""CORE-9 Action guard: deterministic checks on every tool call before it runs.
+
+Checks, in order (first hard violation wins; all observations are recorded):
+  1. tool allowed for this agent
+  2. pinned fields: values come from trusted session context, never from the model
+  3. outbound scan: canaries / secrets / registered values in any argument
+  4. recipient allow-list (send-type tools)
+  5. URL domain allow-list (fetch-type tools) - stops data leaving through a URL
+  6. path stays inside the sandbox (file tools)
+  7. provenance: high-risk target that appears only in untrusted content
+  8. session risk: high-risk tool while the session carries risk from untrusted content
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import time
+from dataclasses import dataclass, field
+from email.utils import getaddresses
+from typing import Any
+
+from .outbound import scan_args
+from .policy import AgentPolicy, ToolPolicy
+from .session import Session, domain_of
+from .types import ActionResult, Decision
+
+
+@dataclass
+class ActionCheck:
+    rule: str
+    decision: Decision
+    reason: str
+    labels: list[str] = field(default_factory=list)
+
+
+def _recipient_ok(addr: str, allowed: list[str]) -> bool:
+    a = addr.strip().lower()
+    if a.count("@") != 1 or not a.split("@")[0] or not a.split("@")[1]:
+        return False
+    for rule in allowed:
+        r = rule.lower()
+        if (r.startswith("@") and a.endswith(r)) or a == r:
+            return True
+    return False
+
+
+def recipients(value: Any) -> list[str]:
+    """Addresses a mailer would deliver to, parsed the way mail libraries parse them (display names, angle
+    brackets, comma/semicolon lists). A piece that does not parse to an address is kept as is, so it fails."""
+    raw = ", ".join(map(str, value)) if isinstance(value, (list, tuple)) else str(value)
+    out: list[str] = []
+    for piece in raw.replace(";", ",").split(","):
+        if not piece.strip():
+            continue
+        parsed = [a for _, a in getaddresses([piece])]
+        out += parsed if parsed and all(parsed) else [piece]
+    # getaddresses splits "Name <x@a> @b" into two entries; any leftover fragment must also pass.
+    for _, a in getaddresses([raw.replace(";", ",")]):
+        if a and a not in out:
+            out.append(a)
+    return out
+
+
+def _domain_ok(url: str, allowed: list[str]) -> bool:
+    d = domain_of(url)
+    if not d:
+        return False
+    return any(d == a.lower() or d.endswith("." + a.lower()) or fnmatch.fnmatch(d, a.lower()) for a in allowed)
+
+
+def _path_ok(path: str) -> bool:
+    p = path.replace("\\", "/")
+    return not (p.startswith("/") or ".." in p.split("/") or (len(p) > 1 and p[1] == ":"))
+
+
+def check_action(tool: str, args: dict[str, Any], policy: AgentPolicy, session: Session,
+                 registered_secrets: list[str] | None = None) -> ActionResult:
+    t0 = time.perf_counter()
+    args = dict(args or {})
+    checks: list[ActionCheck] = []
+    tp: ToolPolicy | None = policy.tools.get(tool)
+
+    if tp is None:
+        if policy.unknown_tools == "block":
+            checks.append(ActionCheck("tool-not-allowed", Decision.BLOCK, f"'{tool}' is not an allowed tool for this agent",
+                                      ["Tool Abuse"]))
+        tp = ToolPolicy()
+
+    # 2. pinned fields (rewrite, never trust the model's value)
+    overrides: dict[str, Any] = {}
+    for f in tp.pinned:
+        if f in session.trusted:
+            if str(args.get(f, "")).strip() != str(session.trusted[f]).strip():
+                overrides[f] = {"requested": args.get(f), "pinned": session.trusted[f]}
+            args[f] = session.trusted[f]
+    if overrides:
+        checks.append(ActionCheck("pinned-field-override", Decision.ALLOW,
+                                  f"pinned field(s) {', '.join(overrides)} set from trusted context", ["Tool Abuse"]))
+
+    # 3. outbound secrets / canaries
+    hits = scan_args(args, policy.canary_values(), registered_secrets or [])
+    if hits:
+        kinds = sorted({h.kind for h in hits})
+        checks.append(ActionCheck("outbound-secret", Decision.BLOCK,
+                                  f"arguments contain protected data ({', '.join(kinds)}) in {', '.join(sorted({h.field for h in hits}))}",
+                                  ["Secret Extraction", "Credential Theft"]))
+
+    # 4. recipients
+    if tp.allowed_recipients and tp.recipient_arg in args:
+        parsed = recipients(args[tp.recipient_arg])
+        bad = [r for r in parsed if not _recipient_ok(r, tp.allowed_recipients)]
+        if bad or not parsed:
+            checks.append(ActionCheck("recipient-not-allowed", Decision.BLOCK,
+                                      f"recipient outside allowed list ({len(bad)} address(es))", ["Tool Abuse"]))
+
+    # 5. URL domains
+    if tp.allowed_domains and tp.url_arg in args:
+        if not _domain_ok(str(args[tp.url_arg]), tp.allowed_domains):
+            checks.append(ActionCheck("domain-not-allowed", Decision.BLOCK,
+                                      f"URL domain '{domain_of(str(args[tp.url_arg]))}' is not approved", ["Tool Abuse"]))
+
+    # 6. sandbox paths
+    if tp.path_arg and tp.path_arg in args and not _path_ok(str(args[tp.path_arg])):
+        checks.append(ActionCheck("path-outside-sandbox", Decision.BLOCK, "path leaves the workspace", ["Tool Abuse"]))
+
+    # 7. provenance of high-risk targets
+    if tp.risk == "high":
+        for key in (tp.recipient_arg, tp.url_arg):
+            if key in args and session.from_untrusted_only(str(args[key])):
+                checks.append(ActionCheck("target-from-untrusted-content",
+                                          Decision.ESCALATE if tp.escalate_if_uncertain else Decision.BLOCK,
+                                          f"'{key}' value appears only in untrusted content, not in the user's request",
+                                          ["Indirect Prompt Injection", "Tool Abuse"]))
+
+    # 8. session risk on high-risk tools
+    if tp.risk == "high" and session.risk >= policy.session.escalate_at:
+        hard = session.risk >= policy.session.block_at
+        checks.append(ActionCheck("high-risk-tool-in-risky-session", Decision.BLOCK if hard else Decision.ESCALATE,
+                                  f"session risk {session.risk:.2f} after untrusted content",
+                                  sorted(session.labels) or ["Multi-Step Jailbreaks"]))
+
+    # 8b. explicit intent (reported after the more specific rules above) (docs/13 L1): a share/destructive tool the user never asked for is held for approval
+    if tp.intent_terms and not session.user_asked_for(tp.intent_terms):
+        checks.append(ActionCheck("action-not-requested", Decision.ESCALATE,
+                                  f"the user's messages do not ask for this action ({', '.join(tp.intent_terms[:4])}…)",
+                                  ["Tool Abuse"]))
+
+    # 9. data flow (CORE-17): where each argument's text came from; flagged content into a high-risk tool
+    taint = session.taint.trace(args, policy.taint.min_coverage) if policy.taint.enabled else []
+    flagged = sorted({h.arg for h in taint if h.flagged})
+    if tp.risk == "high" and flagged and policy.taint.flagged_to_high_risk in ("escalate", "block"):
+        checks.append(ActionCheck("tainted-from-flagged-content",
+                                  Decision.BLOCK if policy.taint.flagged_to_high_risk == "block" else Decision.ESCALATE,
+                                  f"argument(s) {', '.join(flagged)} copy text from content the gateway flagged",
+                                  ["Indirect Prompt Injection", "Tool Abuse"]))
+
+    order = {Decision.BLOCK: 3, Decision.ESCALATE: 2, Decision.NEUTRALISE: 1, Decision.ALLOW: 0}
+    worst = max(checks, key=lambda c: order[c.decision], default=None)
+    decision = worst.decision if worst else Decision.ALLOW
+    enforced = decision if policy.mode == "enforce" else Decision.ALLOW
+    labels = sorted({l for c in checks for l in c.labels})
+    reason = "; ".join(c.reason for c in checks) or "within policy"
+    notice = None
+    if enforced == Decision.BLOCK:
+        notice = f"Action '{tool}' was blocked by the security policy: {worst.reason}. Continue the user's task without it."
+    elif enforced == Decision.ESCALATE:
+        notice = f"Action '{tool}' needs human approval ({worst.reason}). It was not performed; tell the user it is awaiting approval."
+    if decision != Decision.ALLOW:
+        session.add_risk(0.5 if decision == Decision.BLOCK else 0.3, labels)
+    return ActionResult(decision=decision, enforced=enforced,
+                        final_args=args if enforced == Decision.ALLOW else None,
+                        pinned_overrides=overrides, labels=labels, taint=[h.as_dict() for h in taint],
+                        policy_rule=worst.rule if worst else "allow", reason=reason, notice=notice,
+                        latency_ms=round((time.perf_counter() - t0) * 1000, 2))

intentseal_core/classifier.py

@@ -0,0 +1,127 @@
+"""Tier 1 classifiers (CORE-4): cheap signals that decide what to escalate, never final decisions (D-011).
+
+- LocalClassifier: protectai/deberta-v3-base-prompt-injection-v2 (Apache-2.0), ONNX on CPU, chunked.
+- RemoteGuard: Llama Prompt Guard 2 via the router role `tier1_remote` (hosted, free tier).
+Both cache by content hash (CC2).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import threading
+import time
+from collections import OrderedDict
+from pathlib import Path
+
+from .config import repo_root
+
+log = logging.getLogger("intentseal.tier1")
+MODEL_REPO = os.environ.get("INTENTSEAL_TIER1_MODEL", "protectai/deberta-v3-base-prompt-injection-v2")
+
+
+class LocalClassifier:
+    def __init__(self, repo: str = MODEL_REPO, threads: int | None = None) -> None:
+        import numpy as np  # noqa: F401  (import check)
+        import onnxruntime as ort
+        from huggingface_hub import snapshot_download
+        from tokenizers import Tokenizer
+
+        os.environ.setdefault("HF_HOME", str(repo_root() / "data" / "hf_cache"))
+        path = Path(snapshot_download(repo, allow_patterns=["onnx/*", "*.json"]))
+        tok = path / "onnx" / "tokenizer.json"
+        self.tok = Tokenizer.from_file(str(tok if tok.exists() else path / "tokenizer.json"))
+        so = ort.SessionOptions()
+        so.intra_op_num_threads = threads or int(os.environ.get("INTENTSEAL_TIER1_THREADS") or "2")
+        self.sess = ort.InferenceSession(str(path / "onnx" / "model.onnx"), so, providers=["CPUExecutionProvider"])
+        self.inputs = {i.name for i in self.sess.get_inputs()}
+        cfg = json.loads((path / "config.json").read_text())
+        self.pos = next(int(k) for k, v in cfg["id2label"].items() if "INJ" in v.upper())
+        self.cls, self.sep = self.tok.token_to_id("[CLS]"), self.tok.token_to_id("[SEP]")
+        self._lock = threading.Lock()
+        self._cache: OrderedDict[str, float] = OrderedDict()   # bounded: CACHE_MAX entries
+
+    def score(self, text: str) -> float:
+        """Max probability over windows of up to 256 tokens (shorter windows keep CPU latency low)."""
+        import numpy as np
+
+        key = hashlib.sha256(text.encode("utf-8", "ignore")).hexdigest()
+        if key in self._cache:
+            return self._cache[key]
+        ids = self.tok.encode(text, add_special_tokens=False).ids
+        best, window, stride = 0.0, 254, 200
+        with self._lock:
+            for start in range(0, max(1, len(ids)), stride):
+                chunk = [self.cls] + ids[start:start + window] + [self.sep]
+                feed = {"input_ids": np.array([chunk], dtype=np.int64),
+                        "attention_mask": np.ones((1, len(chunk)), dtype=np.int64)}
+                if "token_type_ids" in self.inputs:
+                    feed["token_type_ids"] = np.zeros((1, len(chunk)), dtype=np.int64)
+                logits = self.sess.run(None, feed)[0][0]
+                p = np.exp(logits - logits.max())
+                best = max(best, float((p / p.sum())[self.pos]))
+                if start + window >= len(ids):
+                    break
+        self._cache[key] = best
+        while len(self._cache) > CACHE_MAX:
+            self._cache.popitem(last=False)
+        return best
+
+
+CACHE_MAX = 20000
+RETRY_S = 60.0
+_loaded: LocalClassifier | None = None
+_failure: tuple[float, str] | None = None     # (time, error type) of the last failed load
+_load_lock = threading.Lock()
+
+
+def local_classifier() -> LocalClassifier | None:
+    """The process-wide local classifier. A failed load is retried after RETRY_S (never cached for the life of the
+    process); while it is unavailable the engine sends content to the judge or holds it (fail closed)."""
+    global _loaded, _failure
+    if _loaded is not None:
+        return _loaded
+    with _load_lock:
+        if _loaded is None and (_failure is None or time.monotonic() - _failure[0] >= RETRY_S):
+            try:
+                _loaded, _failure = LocalClassifier(), None
+            except Exception as e:  # missing model / runtime
+                _failure = (time.monotonic(), type(e).__name__)
+                log.warning("Tier 1 local classifier unavailable: %s", type(e).__name__)
+    return _loaded
+
+
+def tier1_status() -> dict[str, str | bool]:
+    """For readiness checks: loaded, or the last load error."""
+    return {"loaded": _loaded is not None, "error": _failure[1] if _failure and _loaded is None else ""}
+
+
+class RemoteGuard:
+    """Prompt Guard 2 via the router (role `tier1_remote`). Returns None when unavailable."""
+
+    def __init__(self, router, role: str = "tier1_remote") -> None:
+        self.router = router
+        self.role = role
+        self._cache: dict[str, float] = {}
+
+    async def score(self, text: str) -> float | None:
+        from .llm.adapters import ChatRequest
+        from .llm.router import AllProvidersFailed
+
+        if self.role not in self.router.settings.roles:
+            return None
+        key = hashlib.sha256(text.encode("utf-8", "ignore")).hexdigest()
+        if key in self._cache:
+            return self._cache[key]
+        try:
+            r = await self.router.chat(self.role, ChatRequest(messages=[{"role": "user", "content": text[:2000]}],
+                                                              max_tokens=8, temperature=None))
+            val = float((r.content or "").strip())
+        except (AllProvidersFailed, ValueError):
+            return None
+        self._cache[key] = val
+        if len(self._cache) > CACHE_MAX:
+            self._cache.pop(next(iter(self._cache)))
+        return val

intentseal_core/cli.py

@@ -0,0 +1,163 @@
+"""Command line.
+
+  intentseal init [--agent my-agent] [--template research-assistant] [--mode enforce] [--home DIR]
+      write a starter policy (and a .env template) for the SDK's embedded mode
+  intentseal init --list                       the policy templates
+  intentseal providers check [--no-call] [--models]
+      providers, key *aliases* and health; one minimal test call per key (key values are never printed)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+import yaml
+
+from .config import config_path, load_settings, repo_root
+from .llm.adapters import ChatRequest, ProviderError
+from .llm.router import Router
+
+
+def _check_model(settings, provider: str) -> str | None:
+    p = settings.providers[provider]
+    if p.options.get("check_model"):
+        return str(p.options["check_model"])
+    for role in settings.roles.values():
+        for m in role.models:
+            if m.provider == provider:
+                return m.model
+    return None
+
+
+async def providers_check(call: bool, show_models: bool) -> int:
+    settings = load_settings()
+    router = Router(settings)
+    bad = 0
+    try:
+        configured = {(m.provider, m.model) for r in settings.roles.values() for m in r.models}
+        for name, p in sorted(settings.providers.items(), key=lambda kv: kv[1].priority):
+            aliases = ", ".join(k.alias for k in p.keys) or "-"
+            print(f"\n[{name}] type={p.type} priority={p.priority} keys={len(p.keys)} ({aliases})")
+            print(f"  status: {router.provider_status(name)}")
+            if not p.active:
+                continue
+            if show_models:
+                try:
+                    ids = await router.list_models(name)
+                    print(f"  models available: {len(ids)}")
+                    for prov, model in sorted(configured):
+                        if prov == name:
+                            found = model in ids or f"models/{model}" in ids
+                            print(f"    configured {model}: {'FOUND' if found else 'NOT LISTED'}")
+                except ProviderError as e:
+                    print(f"  models: error {e.kind}")
+            if not call:
+                continue
+            model = _check_model(settings, name)
+            if not model:
+                print("  test call: skipped (no model configured for this provider)")
+                continue
+            for key in p.keys:
+                req = ChatRequest(messages=[{"role": "user", "content": "Reply with the single word: ok"}],
+                                  max_tokens=64, temperature=0)
+                try:
+                    r = await router.call_direct(name, model, req, key=key)
+                    text = (r.content or "").strip().replace("\n", " ")[:20]
+                    print(f"  {key.alias}: OK  {r.latency_ms:.0f} ms  model={model}  reply='{text}'")
+                except ProviderError as e:
+                    bad += 1
+                    print(f"  {key.alias}: FAIL {e.kind} (HTTP {e.http_status})  model={model}")
+    finally:
+        await router.aclose()
+    return 1 if bad else 0
+
+
+ENV_TEMPLATE = """# IntentSeal settings (read from this folder and from your project's .env). Keys are never printed or logged.
+# The AI judge (Tier 2) uses free-tier providers by default; set at least one key:
+GROQ_API_KEY=
+GEMINI_API_KEY=
+NVIDIA_API_KEY=
+OPENROUTER_API_KEY=
+# Values that must never leave through a tool argument (comma-separated), e.g. a test canary:
+# INTENTSEAL_CANARIES=
+"""
+
+
+def init(agent: str, template: str, mode: str, home: str | None, list_only: bool) -> int:
+    templates = {f.stem: f for f in sorted(config_path("policy-templates").glob("*.yaml"))}
+    if list_only:
+        for name, f in templates.items():
+            data = yaml.safe_load(f.read_text(encoding="utf-8")) or {}
+            print(f"{name:20} {data.get('description', '')}")
+        return 0
+    if template not in templates:
+        print(f"unknown template '{template}'; choose one of: {', '.join(templates)}", file=sys.stderr)
+        return 2
+    from .policy import AgentPolicy, policy_path, save_policy
+
+    if home:
+        os.environ["INTENTSEAL_HOME"] = str(Path(home).resolve())
+    root = repo_root()
+    raw = dict((yaml.safe_load(templates[template].read_text(encoding="utf-8")) or {}).get("policy") or {})
+    raw.update({"agent": agent, "mode": mode})
+    try:
+        policy = AgentPolicy.model_validate(raw)
+        target = policy_path(agent)
+    except ValueError as e:
+        print(f"invalid agent id or policy: {str(e)[:200]}", file=sys.stderr)
+        return 2
+    if target.exists():
+        print(f"{target} already exists; edit it or choose another --agent")
+        return 1
+    path = save_policy(policy)
+    env = root / ".env"
+    if not env.exists():
+        env.parent.mkdir(parents=True, exist_ok=True)
+        env.write_text(ENV_TEMPLATE, encoding="utf-8")
+    print(f"policy  {path}  ({template}, {mode} mode, tools: {', '.join(policy.tools) or 'none'})")
+    print(f"keys    {env}  (add at least one provider key for the AI judge)")
+    print(f"""
+Next, in your agent:
+
+    from intentseal import Guard
+    guard = Guard("{agent}")                              # embedded: pip install "intentseal[embedded]"
+    # guard = Guard("{agent}", remote="https://<gateway>", api_key=...)   # or a shared gateway
+
+    with guard.session(user_id="u1", task=user_message):
+        text = guard.inspect(page_html, source="web")     # cleaned content, or a safe notice
+
+    @guard.tool()                                         # checked before it runs
+    def {next(iter(policy.tools), 'send_message')}(...): ...
+
+Rename the policy's tools to your agent's tool names: any tool not listed is blocked in enforce mode.""")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="intentseal")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    pr = sub.add_parser("providers", help="provider operations")
+    prs = pr.add_subparsers(dest="sub", required=True)
+    chk = prs.add_parser("check", help="list providers, key aliases, health; test each key")
+    chk.add_argument("--no-call", action="store_true", help="do not make test calls")
+    chk.add_argument("--models", action="store_true", help="verify configured model IDs against /models")
+    ini = sub.add_parser("init", help="write a starter policy and a .env template")
+    ini.add_argument("--agent", default="my-agent", help="agent id (letters, digits, '.', '_' or '-')")
+    ini.add_argument("--template", default="research-assistant", help="policy template (see --list)")
+    ini.add_argument("--mode", default="enforce", choices=["enforce", "monitor"])
+    ini.add_argument("--home", help="folder for policies and settings (default: INTENTSEAL_HOME or ~/.intentseal)")
+    ini.add_argument("--list", action="store_true", help="list the templates and exit")
+    args = ap.parse_args(argv)
+    if args.cmd == "init":
+        return init(args.agent, args.template, args.mode, args.home, args.list)
+    if args.cmd == "providers" and args.sub == "check":
+        return asyncio.run(providers_check(call=not args.no_call, show_models=args.models))
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

intentseal_core/config.py

@@ -0,0 +1,185 @@
+"""Configuration loading. Providers and models come from YAML; keys and paths from the environment."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+from dotenv import load_dotenv
+
+from .secrets import ApiKey, load_keys
+
+
+DEFAULTS = Path(__file__).resolve().parent / "defaults"   # bundled config, policy templates, starter policy
+
+
+def repo_root() -> Path:
+    """Where IntentSeal keeps its configuration and data: INTENTSEAL_HOME, else the source checkout this package runs
+    from (development), else a per-user folder (~/.intentseal) for an installed package."""
+    env = os.environ.get("INTENTSEAL_HOME")
+    if env:
+        return Path(env)
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        if (parent / "config" / "providers.yaml").exists():
+            return parent
+    return Path.home() / ".intentseal"
+
+
+def config_path(*parts: str) -> Path:
+    """A configuration file or folder: the home's own copy if there is one, else the copy bundled with the package."""
+    own = repo_root().joinpath("config", *parts)
+    return own if own.exists() else DEFAULTS.joinpath(*parts)
+
+
+def load_env() -> None:
+    load_dotenv(repo_root() / ".env", override=False)
+    load_dotenv(Path.cwd() / ".env", override=False)   # an installed package: the project's own .env
+    from . import adopt_legacy_env
+
+    adopt_legacy_env()
+
+
+@dataclass
+class ProviderConfig:
+    name: str
+    type: str
+    enabled: bool
+    base_url: str
+    keys: list[ApiKey]
+    priority: int = 50
+    timeout_s: float = 30
+    connect_timeout_s: float = 5
+    retries: int = 1
+    backoff_base_s: float = 1.0
+    backoff_max_s: float = 60
+    circuit_failures: int = 3
+    circuit_open_s: float = 60
+    key_rotation: str = "on_auth_failure"
+    rpm: float | None = None
+    tpm: float | None = None              # tokens per minute, per model (provider limits are per model)
+    daily_token_budget: int | None = None
+    extra_headers: dict[str, str] = field(default_factory=dict)
+    options: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def active(self) -> bool:
+        return self.enabled and bool(self.keys)
+
+    @property
+    def disabled_reason(self) -> str | None:
+        if not self.enabled:
+            return "disabled in config"
+        if not self.keys:
+            return "no keys in environment"
+        return None
+
+
+@dataclass
+class ModelRef:
+    provider: str
+    model: str
+    price_in: float = 0.0   # USD per million input tokens (list price, for reporting)
+    price_out: float = 0.0
+    params: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RoleConfig:
+    name: str
+    models: list[ModelRef]
+    cache: bool = True
+    cache_ttl_s: int = 86400
+    defaults: dict[str, Any] = field(default_factory=dict)
+    wait_on_rate_limit_s: float = 0.0   # >0: wait out a provider cooldown (up to this long) instead of failing
+    max_queue_s: float | None = None    # longest client-side throttle wait before failing over (latency-sensitive roles)
+
+
+@dataclass
+class Settings:
+    providers: dict[str, ProviderConfig]
+    roles: dict[str, RoleConfig]
+    db_path: Path | str                 # SQLite file, or a postgresql:// URL (INTENTSEAL_DATABASE_URL)
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    with open(path, encoding="utf-8") as f:
+        return yaml.safe_load(f) or {}
+
+
+def load_providers(path: Path | None = None) -> dict[str, ProviderConfig]:
+    path = path or config_path("providers.yaml")
+    raw = _read_yaml(path)
+    defaults = raw.get("defaults", {}) or {}
+    out: dict[str, ProviderConfig] = {}
+    for name, p in (raw.get("providers") or {}).items():
+        merged = {**defaults, **p}
+        keys_cfg = merged.get("keys") or {}
+        limits = merged.get("limits") or {}
+        budget = merged.get("budget") or {}
+        known = {
+            "type", "enabled", "base_url", "keys", "priority", "timeout_s", "connect_timeout_s",
+            "retries", "backoff_base_s", "backoff_max_s", "circuit_failures", "circuit_open_s",
+            "key_rotation", "limits", "budget", "extra_headers", "no_auth",
+        }
+        out[name] = ProviderConfig(
+            name=name,
+            type=merged.get("type", "openai_compatible"),
+            enabled=bool(merged.get("enabled", True)),
+            base_url=str(merged.get("base_url", "")).rstrip("/"),
+            # `no_auth: true` (local servers such as Ollama or vLLM): one empty key, so the provider is usable.
+            keys=([ApiKey(f"{name}#local", "")] if merged.get("no_auth")
+                  else load_keys(name, keys_cfg.get("env_prefix"), keys_cfg.get("env_list"))),
+            priority=int(merged.get("priority", 50)),
+            timeout_s=float(merged.get("timeout_s", 30)),
+            connect_timeout_s=float(merged.get("connect_timeout_s", 5)),
+            retries=int(merged.get("retries", 1)),
+            backoff_base_s=float(merged.get("backoff_base_s", 1.0)),
+            backoff_max_s=float(merged.get("backoff_max_s", 60)),
+            circuit_failures=int(merged.get("circuit_failures", 3)),
+            circuit_open_s=float(merged.get("circuit_open_s", 60)),
+            key_rotation=str(merged.get("key_rotation", "on_auth_failure")),
+            rpm=limits.get("rpm"),
+            tpm=limits.get("tpm"),
+            daily_token_budget=budget.get("daily_tokens"),
+            extra_headers=dict(merged.get("extra_headers") or {}),
+            options={k: v for k, v in merged.items() if k not in known},
+        )
+    return out
+
+
+def load_roles(path: Path | None = None) -> dict[str, RoleConfig]:
+    path = path or config_path("models.yaml")
+    raw = _read_yaml(path)
+    out: dict[str, RoleConfig] = {}
+    for name, r in (raw.get("roles") or {}).items():
+        models = [
+            ModelRef(
+                provider=m["provider"],
+                model=m["model"],
+                price_in=float((m.get("price_per_mtok") or {}).get("input", 0.0)),
+                price_out=float((m.get("price_per_mtok") or {}).get("output", 0.0)),
+                params=dict(m.get("params") or {}),
+            )
+            for m in r.get("models", [])
+        ]
+        out[name] = RoleConfig(
+            name=name,
+            models=models,
+            cache=bool(r.get("cache", True)),
+            cache_ttl_s=int(r.get("cache_ttl_s", 86400)),
+            defaults=dict(r.get("defaults") or {}),
+            wait_on_rate_limit_s=float(r.get("wait_on_rate_limit_s", 0.0)),
+            max_queue_s=r.get("max_queue_s"),
+        )
+    return out
+
+
+def load_settings() -> Settings:
+    load_env()
+    url = os.environ.get("INTENTSEAL_DATABASE_URL", "").strip()
+    db: Path | str = url or Path(os.environ.get("INTENTSEAL_DB_PATH") or repo_root() / "data" / "intentseal.db")
+    return Settings(providers=load_providers(), roles=load_roles(), db_path=db)