adra 0.4.0__py3-none-any.whl

adra/__init__.py

@@ -0,0 +1,36 @@
+"""ADRA — Adversarial Dev Review Agent.
+
+A client-agnostic, deterministic-first, adversarial-validation engine that supports the
+software lifecycle. It formalizes six capabilities a team runs informally under
+adversarial human direction:
+
+    code_review | pr_eval | experiment | improve | document | decide
+
+The design spine is *adversarial validation*: every generated artifact is passed through
+a blocking, tool-grounded adversarial critic before it is accepted, and every run emits
+an immutable provenance record (the deep change history). Deterministic tools
+(git / CI / SQL / static analysis) are ground truth; the LLM only adds what tools cannot
+settle. Connectors (GitHub / Azure DevOps / Databricks / Azure) and a self-contained
+offline emulator sit behind one Protocol, so the same engine runs against a real
+platform or a synthetic one.
+
+The package runs offline with a deterministic ``mock`` provider (no API key required)
+and switches to a real provider (e.g. Anthropic Claude) when its key is present.
+"""
+
+from adra.config import Settings, load_settings
+from adra.orchestrator import Orchestrator
+from adra.state import CriticVerdict, Finding, RunState, Severity, ToolResult
+
+__all__ = [
+    "Settings",
+    "load_settings",
+    "Orchestrator",
+    "Finding",
+    "Severity",
+    "ToolResult",
+    "CriticVerdict",
+    "RunState",
+]
+
+__version__ = "0.4.0"  # PEP 440 package version; display/tag version is v0.04.000 (see VERSION)

adra/clients/synthetic/northwind/README.md

@@ -0,0 +1,44 @@
+# Northwind Data Platform — engineering standards (fictional client suite)
+
+> **Fictional.** Northwind Trading and everything below are invented for this
+> reference agent. They model a realistic governance baseline so ADRA has a concrete
+> client to reason against, without referencing any real organization. Point the
+> agent at a different client by replacing this `standards/` folder.
+
+## Client profile
+
+**Northwind Trading** — a fictional B2B commerce company. The **Northwind Data Platform
+(NDP)** runs the analytics and decision-support products for four operating domains.
+
+| Item | Value |
+|---|---|
+| Cloud / compute | Azure Databricks |
+| Catalog / governance | Unity Catalog (UC) |
+| Deploy unit | Databricks Asset Bundles (DAB) |
+| Pipelines | Delta Live Tables (DLT) |
+| Source control / CI | Azure DevOps — org `NorthwindNDP`, project `Data Platform`, shared CI templates `ndp-ci` |
+| Integration branch | `main` |
+| Work branches | `task/<NDP-ticket>/<slug>` |
+| Tickets | `NDP-####` |
+| Catalog naming | `<env>_<domain>_<subdomain>` (env ∈ `dev` / `preprod` / `prod`) |
+
+### Domains
+
+| Domain | Scope | Example catalog |
+|---|---|---|
+| `catalog` | Product catalog & merchandising | `prod_catalog_items` |
+| `orders` | Order management & fulfilment | `prod_orders_fulfilment` |
+| `payments` | Payments, billing & reconciliation | `prod_payments_ledger` |
+| `analytics` | Demand/risk forecasting & decision support | `prod_analytics_forecast` |
+
+## Index
+
+- `conventions.md` — language, naming, branching, PR body, labels.
+- `ci-standards.md` — the exact CI command, coverage, test discovery, bundle validate.
+- `glossary.md` — domain and platform terms.
+- `adr/` — Architecture Decision Records (`ADR-0001` … `ADR-0008`).
+- `cases/` — anonymized post-incident notes the rubric is learned from (`CASE-*`).
+
+These documents are the source of truth the ADRA agent grounds on. The adversarial
+rubric (`adra/rubric.py`) references them by id, and the skill/critic prompts cite
+them, so "what we check" lives in one place.

adra/clients/synthetic/northwind/adr/ADR-0001-deterministic-grounding.md

@@ -0,0 +1,21 @@
+# ADR-0001 — Deterministic-first grounding and second-method proof
+
+**Status:** Accepted
+
+## Context
+Reviews and experiments that rely on a reviewer's narrative ("this looks fine",
+"that's probably because…") let unverified claims through. Plausible explanations
+without verification have caused rework and missed defects.
+
+## Decision
+- Deterministic, high-precision checks (the exact CI command, `bundle validate`,
+  git merge-base, language scan, SQL probes) run **first** and are **ground truth**.
+- Any cause or outcome must be backed by a **second, independent method** (a probe,
+  a re-run of the exact command, a cross-check) or stated as **"unknown"**.
+- An LLM may only add findings the deterministic tools cannot settle; it may not
+  contradict them.
+
+## Consequences
+- Verdicts carry evidence, not opinion.
+- The agent reproduces the exact thing under test instead of approximating.
+- See `cases/CASE-2024-058` (an anomaly confirmed only after live verification).

adra/clients/synthetic/northwind/adr/ADR-0002-no-stale-base-merges.md

@@ -0,0 +1,20 @@
+# ADR-0002 — No stale-base merges (merge-base health)
+
+**Status:** Accepted
+
+## Context
+A pull request whose branch is based on an outdated `main` can, on merge, silently
+revert or delete work that landed in the meantime — including notebooks and bundle
+resources — because its diff is computed against an old base.
+
+## Decision
+- Every PR is checked for **merge-base health**: compute the merge-base and the
+  number of commits the branch is **behind** `main`.
+- A branch behind a fresh `main` must be **rebased or recreated** before review.
+- The diff against the merge-base is scanned for the destructive signature:
+  **file deletions** and **resource renames** (see `ADR-0003`). Both are blocking
+  until explicitly confirmed.
+
+## Consequences
+- Destructive merges are caught before they land.
+- See `cases/CASE-2024-031`.

adra/clients/synthetic/northwind/adr/ADR-0003-bundle-resources-stay-yml.md

@@ -0,0 +1,19 @@
+# ADR-0003 — Bundle resource files stay `.yml`
+
+**Status:** Accepted
+
+## Context
+A Databricks Asset Bundle includes resources (jobs, schemas, volumes, pipelines)
+declared in `resources/bundle.resources.<kind>.yml`. Renaming such a file to any
+other extension (e.g. `.yml.t`) silently removes the resource from the bundle, so a
+deploy drops the job/schema/volume without an obvious diff signal.
+
+## Decision
+- Resource files **must keep the `.yml` extension**.
+- A rename away from `.yml` (e.g. `→ .yml.t`) is a **blocking** finding.
+- Any change under `resources/` requires `databricks bundle validate -t <env>`
+  returning `Validation OK!` before review (see `ci-standards.md`).
+
+## Consequences
+- Bundle composition stays explicit and validated.
+- See `cases/CASE-2024-031`.

adra/clients/synthetic/northwind/adr/ADR-0004-test-discovery.md

@@ -0,0 +1,20 @@
+# ADR-0004 — Test discovery is `test*.py`; product logic must be importable
+
+**Status:** Accepted
+
+## Context
+`ndp-ci` runs `unittest discover -s databricks -p "test*.py"` under coverage. Two
+failure modes recur: test files that do not match the discovery pattern, and product
+logic that lives only inside notebooks (excluded from coverage and not importable).
+
+## Decision
+- Test files **must match `test*.py`** (prefix). A `*_test.py` (suffix) file is never
+  collected — it is dead code and must be renamed or removed.
+- A test directory must contain `__init__.py` to be recursed into.
+- Product logic that needs coverage must live in **importable, non-notebook** modules
+  (plain `.py` outside `tests/`).
+- `Ran 0 tests` / "No data was collected" is a **blocking** CI failure.
+
+## Consequences
+- Coverage measures real product code.
+- See `cases/CASE-2024-047`.

adra/clients/synthetic/northwind/adr/ADR-0005-experiments-on-warehouse.md

@@ -0,0 +1,29 @@
+# ADR-0005 — Experiments run on the shared SQL warehouse; 8-point access preflight
+
+**Status:** Accepted
+
+## Context
+Ad-hoc validation that spins up interactive clusters is slow and costly, and
+"no access to this catalog" is often concluded prematurely (wrong profile, stopped
+warehouse, missing grant) instead of diagnosed.
+
+## Decision
+- Validation experiments use the **shared SQL warehouse** via
+  `databricks api post /api/2.0/sql/statements`; do not create interactive clusters.
+- A hypothesis is **falsifiable**, carries a probability and an impact-if-true, and
+  is tied to a **standalone probe**; raw rows are persisted (`runs/*.json`).
+- Conclude only what the rows support; record discarded hypotheses with data too.
+
+### The 8-point access preflight (exhaust before declaring "no access")
+1. Profile matches the catalog env (`prod` for `prod_*`, `dev` for `dev_*`).
+2. `databricks current-user me --profile <p>` returns the expected user.
+3. `warehouse_id` is valid for the profile and is `RUNNING`.
+4. The catalog exists in that workspace (`SHOW CATALOGS`).
+5. The schema exists (`SHOW SCHEMAS IN <catalog>`).
+6. The table exists (`SHOW TABLES IN <catalog>.<schema>`).
+7. `current_user` is a member of the granting group (`is_member(...)`).
+8. If the warehouse runs as a service principal, the SP has the grant.
+
+## Consequences
+- Reproducible, cheap experiments; "no access" becomes a diagnosis, not a guess.
+- See `cases/CASE-2024-052`.

adra/clients/synthetic/northwind/adr/ADR-0006-docs-from-provenance.md

@@ -0,0 +1,19 @@
+# ADR-0006 — Documentation is generated from provenance
+
+**Status:** Accepted
+
+## Context
+Documentation written from memory drifts from what actually shipped. Change history
+was shallow: hard to answer *why* a change was made and *on what evidence*.
+
+## Decision
+- Documentation is **generated from the run record** (provenance), not authored from
+  memory; pages cite evidence files and **commit-pinned** links (`?version=GC<sha>`).
+- Change history has layers: a **PR change-control page** per merged PR, an
+  **experiment page** per experiment, and a **methodology-history** that records only
+  **architectural milestones** (contract / persistence / strategy / input changes).
+- A **source-of-truth gap table** is kept when a change makes existing docs stale.
+- Pages are **English, third person, no AI-session leak** (see `conventions.md`).
+
+## Consequences
+- Docs stay aligned with reality and are auditable.

adra/clients/synthetic/northwind/adr/ADR-0007-decision-support-framing.md

@@ -0,0 +1,19 @@
+# ADR-0007 — Decision-support outputs avoid overclaiming
+
+**Status:** Accepted
+
+## Context
+`analytics` products are decision support: demand and risk forecasts, anomaly scores,
+prioritization. Language that claims a model "detects", "predicts", "guarantees" or
+"prevents" an outcome overstates what the model does and creates liability exposure when
+the outcome differs from the claim.
+
+## Decision
+- `analytics` / decision-support outputs are framed as **likelihoods, risk scores and
+  recommendations** that carry their evidence — never as guaranteed detection or prediction.
+- Documentation, code comments, UI strings and PR text use non-overclaiming framing.
+- The high-consequence decision stays **human-owned**; the model prepares the evidence.
+
+## Consequences
+- Claims match what the models actually do (calibration honesty).
+- The `overclaim_language` rubric item flags violations on any decision-support deliverable.

adra/clients/synthetic/northwind/adr/ADR-0008-minimum-functional.md

@@ -0,0 +1,19 @@
+# ADR-0008 — Minimum-functional, smallest reversible change
+
+**Status:** Accepted
+
+## Context
+Changes that copy whole templates or add "just in case" scaffolding accumulate dead
+code and widen blast radius. Larger diffs are harder to review and to roll back.
+
+## Decision
+- Include **only what advances the result**; prune filler even when it was copied
+  from a team standard or template.
+- Removing code requires **proof it is dead** (not collected by CI discovery,
+  unreferenced) — not an assertion.
+- Prefer the **smallest, reversible** diff; name the rollback. Assess **blast radius**
+  (shared CI templates, cross-domain libraries, prod data) and prefer the
+  smallest-scope route (see `cases/CASE-2024-061`).
+
+## Consequences
+- Smaller, safer, defensible changes; less dead code.

adra/clients/synthetic/northwind/cases/CASE-2024-031-stale-base-destructive-merge.md

@@ -0,0 +1,19 @@
+# CASE-2024-031 — Stale-base PR dropped a notebook and bundle resources
+
+**Domain:** `orders` · **Relates to:** ADR-0002, ADR-0003
+
+## What happened
+A PR for the orders bundle was opened from a branch based on a `main` that was ~12
+commits stale. Because the diff was computed against the old merge-base, the PR:
+- deleted `nb-priority-coverage.py` (which had landed on `main` in the meantime), and
+- renamed `bundle.resources.schemas.yml` and `…volumes.yml` to `.yml.t`, dropping
+  both resources from the bundle.
+
+`databricks bundle validate` would have failed, but it was not run.
+
+## Root cause
+Stale merge-base + no destructive-diff review + no bundle validation.
+
+## Fix / rule
+Rebuilt the change cleanly on a fresh `main`. Codified as ADR-0002 (merge-base
+health + destructive-diff scan) and ADR-0003 (resources stay `.yml`).

adra/clients/synthetic/northwind/cases/CASE-2024-047-coverage-no-data.md

@@ -0,0 +1,19 @@
+# CASE-2024-047 — Coverage CI failed with "No data was collected"
+
+**Domain:** `catalog` · **Relates to:** ADR-0004
+
+## What happened
+The `catalog` repo's coverage stage exited 1 with `Ran 0 tests` then
+`CoverageWarning: No data was collected`. The only test-shaped file was
+`py_aux_functions_v3_test.py` (a `*_test.py` **suffix**), which `unittest discover -p
+"test*.py"` never collects. The product logic lived inside a notebook (excluded from
+coverage, not importable).
+
+## Diagnosis (second method)
+Ran the **exact** CI command locally and confirmed 0 collected tests. Cross-checked a
+sibling repo whose coverage passed: it had a discoverable `test*.py` exercising an
+importable module — proving the difference, not guessing it.
+
+## Fix / rule
+Added an importable module + a discoverable `test*.py`; removed the dead suffix file.
+Codified as ADR-0004 (discovery pattern + importable logic).

adra/clients/synthetic/northwind/cases/CASE-2024-052-premature-no-access.md

@@ -0,0 +1,16 @@
+# CASE-2024-052 — "No access" to a catalog, concluded prematurely
+
+**Domain:** `payments` · **Relates to:** ADR-0005
+
+## What happened
+An experiment reported "no access to `prod_payments_ledger`" and was closed. In fact
+the query had been issued with the `dev` profile against a `prod_*` catalog; the
+profile is bound to the workspace, so the grant did not apply.
+
+## Diagnosis (preflight)
+Walking the 8-point preflight surfaced it at step 1 (profile/env mismatch). Re-running
+with `--profile prod` returned rows immediately.
+
+## Fix / rule
+Codified the 8-point access preflight in ADR-0005: never declare "no access" without
+exhausting it.

adra/clients/synthetic/northwind/cases/CASE-2024-058-anomaly-verified-live.md

@@ -0,0 +1,17 @@
+# CASE-2024-058 — Column-coverage anomaly traced to a config typo (verified live)
+
+**Domain:** `orders` · **Relates to:** ADR-0001
+
+## What happened
+An orders-pipeline verification flagged 2 of 41 expected source columns as "missing"
+from the refined stream. The tempting conclusion was "the source is incomplete".
+
+## Diagnosis (second method)
+A probe against the live table (~130M rows, last 7 days) showed 39/41 columns present
+and the 2 "missing" ones used a malformed literal (absent for those two
+columns) — a **config typo**, not missing data. The conclusion was only made *after*
+the rows confirmed it.
+
+## Fix / rule
+Corrected the column literals. Codified ADR-0001: conclude from a second-method proof,
+record confirmed vs discarded with numbers — never assert from the symptom.

adra/clients/synthetic/northwind/cases/CASE-2024-061-route-blast-radius.md

@@ -0,0 +1,18 @@
+# CASE-2024-061 — Choosing a route by blast radius and precedent
+
+**Domain:** `catalog` · **Relates to:** ADR-0008
+
+## What happened
+A catalog refresh trigger needed a higher cadence. Two routes were on the table:
+(a) edit the **shared `ndp-ci` trigger template** (touches every consuming repo), or
+(b) change the cadence **in the catalog repo's own trigger**, matching an existing
+precedent already present for a sibling trigger.
+
+## Decision
+Route (b) was chosen: smaller **blast radius**, reversible, and **justified against a
+precedent** in the same repo (a sibling trigger already ran at the target cadence).
+Route (a) was recorded as discarded with its trade-off (broad blast radius).
+
+## Fix / rule
+Codified ADR-0008: prefer the smallest reversible route; justify against convention
+or a measured gap; assess blast radius explicitly.

adra/clients/synthetic/northwind/ci-standards.md

@@ -0,0 +1,41 @@
+# NDP CI standards
+
+The `ndp-ci` shared templates are the source of truth for "green". The agent must
+reproduce the **exact** commands, never an approximation (see `adr/ADR-0001`).
+
+## Unit tests + coverage (the exact command)
+
+```bash
+python -m coverage run -m unittest discover -s databricks -p "test*.py"
+python -m coverage report --fail-under=80
+```
+
+- **Discovery pattern is `test*.py`** (prefix). A file named `*_test.py` (suffix) is
+  **never collected** and is dead code (see `adr/ADR-0004`, `cases/CASE-2024-047`).
+- A package without `__init__.py` is **not** recursed into by `unittest discover`.
+- Product logic must be **importable, non-notebook** code (a plain `.py` outside
+  `tests/`); notebooks are excluded from coverage and cannot be imported (they call
+  `dbutils` / `spark` at module load).
+- `Ran 0 tests` → coverage reports **"No data was collected"** → non-zero exit. This
+  is a CI failure, not a warning.
+
+## Bundle validation
+
+```bash
+databricks bundle validate -t <env>
+```
+
+Must print `Validation OK!`. Run it before any PR that touches `resources/` or the
+bundle (see `adr/ADR-0003`).
+
+## Experiments / ad-hoc data access
+
+Experiments run against the **shared SQL warehouse**, never a fresh interactive
+cluster (see `adr/ADR-0005`):
+
+```bash
+databricks api post /api/2.0/sql/statements --profile <prod|dev> --json '{...}'
+```
+
+Before concluding "no access" to a catalog, exhaust the 8-point preflight in
+`adr/ADR-0005`.

adra/clients/synthetic/northwind/conventions.md

@@ -0,0 +1,46 @@
+# NDP conventions
+
+## Language & authorship
+- Everything written to disk is **English**: code, docstrings, comments, commit
+  messages, PR titles/descriptions, test names, file and folder names.
+- **Third person.** No first-person singular in code, docs, commits or PRs.
+- **No AI-session leak.** Nothing written to a repo may reveal AI authorship
+  (no `Claude`, `Anthropic`, `Co-Authored-By`, "generated with AI", etc.). See
+  `adr/ADR-0006`.
+
+## Naming
+- Catalogs: `<env>_<domain>_<subdomain>` — e.g. `prod_orders_fulfilment`. `env` ∈
+  `dev` / `preprod` / `prod`.
+- Schemas follow the medallion split: `landing` / `trusted` / `refined`.
+- DAB resource files: `bundle.resources.<kind>.yml` and they **stay `.yml`** (see
+  `adr/ADR-0003`).
+- Notebooks: `nb-<purpose>.py` with the `# Databricks notebook source` header.
+
+## Branching & tickets
+- Integration branch: `main`. Never commit product changes directly to `main`.
+- Work branches: `task/<NDP-####>/<short-slug>`, always rebased on a fresh `main`
+  (see `adr/ADR-0002`).
+- Tickets are `NDP-####`; every PR links its ticket.
+
+## Pull requests
+PR description uses these sections, in order:
+
+```
+## Objective
+## Changes
+## What is NOT touched
+## Validation        (exact CI command output; `bundle validate` OK)
+## Risks / mitigations
+## Test plan
+## Work Item         (NDP-####)
+```
+
+- Reference another PR by its **full URL**, never a bare `#NNNN`.
+- Use **commit-pinned** file links (`?version=GC<full-sha>`) so links survive the merge.
+- Apply the owning team's **labels** before completing the PR.
+- A PR with any deterministic blocker is **changes-requested** regardless of opinion.
+
+## Decision-support framing
+`analytics` products are **decision support**: outputs are *forecasts, risk scores and
+recommendations* with their evidence — never claims to "guarantee", "prevent",
+"detect" or "predict" an outcome (see `adr/ADR-0007`).

adra/clients/synthetic/northwind/glossary.md

@@ -0,0 +1,19 @@
+# NDP glossary
+
+| Term | Meaning |
+|---|---|
+| NDP | Northwind Data Platform |
+| Domain | A product area: `catalog`, `orders`, `payments`, `analytics` |
+| UC | Unity Catalog (governance over catalogs / schemas / tables / volumes) |
+| DAB | Databricks Asset Bundle (the deploy unit) |
+| DLT | Delta Live Tables (declarative pipelines) |
+| Medallion | `landing` → `trusted` → `refined` schema split |
+| Warehouse | Shared serverless SQL warehouse for ad-hoc queries / experiments |
+| SKU | Stock-keeping unit — a `catalog` product identifier |
+| Threshold | A configurable decision target in `analytics` (e.g. a fraud-score cutoff) |
+| Conversion | Order conversion rate (%) tracked in `analytics` |
+| Forecast/risk output | `analytics` decision-support output — a likelihood/recommendation, not a guarantee |
+| Data contract | The documented schema + semantics of a published UC table |
+| Provenance run record | The immutable JSON ADRA writes per run (evidence + decisions) |
+| Preflight | The 8-point access checklist before declaring "no access" (`adr/ADR-0005`) |
+| Blast radius | The reach of a change (shared templates, cross-domain libs, prod data) |

adra/config.py

@@ -0,0 +1,164 @@
+"""Runtime settings for ADRA.
+
+Settings come from environment variables (a ``.env`` is loaded if present) with
+safe defaults so the package runs offline out of the box. Nothing here reads or
+stores secrets beyond the LLM key, which is only ever taken from the environment.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from adra.utils import client_dir as _client_dir
+
+# Default Anthropic model — claude-haiku-4-5 per ADR-0053 (cost-appropriate default for
+# private/quality apps; switch to claude-sonnet-4-6 when reasoning depth matters). Overridable via ADRA_MODEL.
+DEFAULT_ANTHROPIC_MODEL = "claude-haiku-4-5"
+
+# Built-in providers. Anthropic uses its native SDK; every entry below speaks the
+# OpenAI-compatible Chat Completions API, so OpenAI, Groq, xAI, Mistral, DeepSeek,
+# OpenRouter, Together AND local servers (Ollama / LM Studio / vLLM) all work — bring
+# whatever you have, or run a local model for free. Any other OpenAI-compatible service
+# works via ADRA_BASE_URL + ADRA_API_KEY.
+PROVIDERS: dict[str, dict[str, str]] = {
+    "openai":     {"base_url": "https://api.openai.com/v1",      "key_env": "OPENAI_API_KEY",     "default_model": "gpt-4o"},
+    "groq":       {"base_url": "https://api.groq.com/openai/v1", "key_env": "GROQ_API_KEY",       "default_model": "llama-3.3-70b-versatile"},
+    "xai":        {"base_url": "https://api.x.ai/v1",            "key_env": "XAI_API_KEY",        "default_model": "grok-4"},
+    "mistral":    {"base_url": "https://api.mistral.ai/v1",      "key_env": "MISTRAL_API_KEY",    "default_model": "mistral-large-latest"},
+    "deepseek":   {"base_url": "https://api.deepseek.com/v1",    "key_env": "DEEPSEEK_API_KEY",   "default_model": "deepseek-chat"},
+    "openrouter": {"base_url": "https://openrouter.ai/api/v1",   "key_env": "OPENROUTER_API_KEY", "default_model": "openai/gpt-4o"},
+    "together":   {"base_url": "https://api.together.xyz/v1",    "key_env": "TOGETHER_API_KEY",   "default_model": "meta-llama/Llama-3.3-70B-Instruct-Turbo"},
+    "ollama":     {"base_url": "http://localhost:11434/v1",      "key_env": "",                   "default_model": "llama3.1"},
+}
+
+# Auto-detect order when ADRA_PROVIDER is unset: a present key wins; else offline mock.
+_AUTODETECT_ORDER = ("anthropic", "openai", "groq", "xai", "mistral", "deepseek", "openrouter", "together")
+
+
+def default_model(provider: str) -> str:
+    """The default model id for a provider (overridable with ADRA_MODEL)."""
+    if provider in ("anthropic", "mock"):
+        return DEFAULT_ANTHROPIC_MODEL
+    info = PROVIDERS.get(provider)
+    return info["default_model"] if info else DEFAULT_ANTHROPIC_MODEL
+
+
+def _autodetect_provider() -> str:
+    """Pick a provider from whichever API key is present; offline mock if none."""
+    for name in _AUTODETECT_ORDER:
+        key_env = "ANTHROPIC_API_KEY" if name == "anthropic" else PROVIDERS.get(name, {}).get("key_env", "")
+        if key_env and os.environ.get(key_env):
+            return name
+    return "mock"
+
+
+def _load_dotenv(path: Path) -> None:
+    """Minimal .env loader (no external dependency).
+
+    Only sets keys that are not already present in the environment, so explicit
+    environment variables always win.
+    """
+    if not path.exists():
+        return
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key, value = key.strip(), value.strip().strip('"').strip("'")
+        os.environ.setdefault(key, value)
+
+
+@dataclass
+class Settings:
+    """Resolved configuration for a run."""
+
+    # LLM (the deterministic loop runs offline with NO key; a provider adds the semantic
+    # layer). provider: mock | anthropic | openai | groq | xai | mistral | deepseek |
+    # openrouter | together | ollama (local). See adra.config.PROVIDERS.
+    provider: str = "mock"
+    model: str = DEFAULT_ANTHROPIC_MODEL
+    temperature: float = 0.0
+    max_tokens: int = 4096
+    # Per-role model overrides so one run can orchestrate across providers (e.g. a strong
+    # model for the critic/judge, a cheaper/faster one for generation). Value per role is
+    # "provider:model" or just "model" (provider inherits the default). Empty => default.
+    role_models: dict[str, str] = field(default_factory=dict)
+
+    # Adversarial loop
+    max_rounds: int = 3  # generate -> critic -> revise iterations before escalation
+    judge_swap_average: bool = True  # evaluate pairwise comparisons in both orders
+
+    # Provenance
+    runs_dir: Path = field(default_factory=lambda: Path("runs"))
+
+    # Repo context (for deterministic tools); optional.
+    repo_path: Path | None = None
+
+    # Active client governance suite (conventions / ADRs / CI standards / cases) the
+    # engine grounds on. Defaults to the bundled synthetic client; ADRA_CLIENT_DIR overrides.
+    client_dir: Path = field(default_factory=_client_dir)
+
+    # Safety: deterministic tools that mutate or call external services stay off
+    # unless explicitly enabled (default is dry-run / read-only).
+    allow_external_calls: bool = False
+
+    def role(self, role: str) -> tuple[str, str]:
+        """Resolve (provider, model) for a flow role: 'plan'|'generate'|'critic'|'judge'.
+
+        Falls back to the run's default provider/model; overridden per role via
+        ``role_models`` (``ADRA_MODEL_<ROLE>``), value ``"provider:model"`` or ``"model"``.
+        """
+        spec = self.role_models.get(role, "")
+        if not spec:
+            return self.provider, self.model
+        if ":" in spec:
+            prov, _, mdl = spec.partition(":")
+            return (prov or self.provider), (mdl or self.model)
+        return self.provider, spec
+
+    def model_id(self, role: str) -> str:
+        """``provider:model`` string for the given role (for logging / provenance)."""
+        prov, mdl = self.role(role)
+        return f"{prov}:{mdl}"
+
+    @property
+    def offline(self) -> bool:
+        return self.provider == "mock"
+
+
+def load_settings(**overrides) -> Settings:
+    """Build :class:`Settings` from env + overrides.
+
+    Provider auto-detects: if ``ADRA_PROVIDER`` is unset, the first provider with a
+    present API key wins (Anthropic → OpenAI → Groq → xAI → ...); otherwise the offline
+    ``mock`` provider. Model defaults per provider unless ``ADRA_MODEL`` is set; per-role
+    overrides come from ``ADRA_MODEL_{PLAN,GENERATE,CRITIC,JUDGE}``.
+    """
+    _load_dotenv(Path(".env"))
+
+    provider = os.environ.get("ADRA_PROVIDER") or _autodetect_provider()
+
+    role_models: dict[str, str] = {}
+    for role in ("plan", "generate", "critic", "judge"):
+        spec = os.environ.get(f"ADRA_MODEL_{role.upper()}")
+        if spec:
+            role_models[role] = spec
+
+    settings = Settings(
+        provider=provider,
+        model=os.environ.get("ADRA_MODEL") or default_model(provider),
+        temperature=float(os.environ.get("ADRA_TEMPERATURE", "0.0")),
+        max_tokens=int(os.environ.get("ADRA_MAX_TOKENS", "4096")),
+        max_rounds=int(os.environ.get("ADRA_MAX_ROUNDS", "3")),
+        allow_external_calls=os.environ.get("ADRA_ALLOW_EXTERNAL", "0") == "1",
+        role_models=role_models,
+    )
+    repo = os.environ.get("ADRA_REPO_PATH")
+    if repo:
+        settings.repo_path = Path(repo)
+    for key, value in overrides.items():
+        setattr(settings, key, value)
+    return settings