codi-api-agent 0.3.1__py3-none-any.whl

api_agent/catalog.py

@@ -0,0 +1,147 @@
+"""The operation catalog the router/executor select from.
+
+A `Catalog` is a set of `Tool`s — each one an OpenAPI operation produced by
+`openapi_loader.build_catalog(spec)`. A `Tool` carries an NL description (used for
+routing), a JSON-schema for its arguments, and a `fn` that performs the HTTP call
+and returns ``{"ok", "content", "source", "error"}``.
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+from dataclasses import dataclass
+from typing import Callable
+
+from .log import get_logger, trunc
+
+_LOG = get_logger("api_agent.catalog")
+
+# Leading noise a model tends to add/drop on a tool name (a resource verb, or an `fn_`/`gold_`
+# wrapper prefix) — stripped before matching so a mangled call can still resolve to its tool.
+_NAME_PREFIX = re.compile(r"^(?:gold|fn|get|post|put|patch|delete|head|op)+")
+
+
+def _name_core(name: str) -> str:
+    """Alphanumeric-lowercased tool name with leading verb/wrapper prefixes removed."""
+    return _NAME_PREFIX.sub("", re.sub(r"[^a-z0-9]", "", (name or "").lower()))
+
+
+@dataclass
+class Tool:
+    name: str
+    description: str
+    parameters: dict  # JSON schema for the arguments
+    data_type: str  # "structured"
+    # (args, timeout, list_limit=None) -> {"ok","content","source","error"[,"kind"]}.
+    # `kind` is the OPTIONAL normalized failure taxonomy — "auth" | "unreachable" |
+    # "server_error" — so the agent's failure bookkeeping doesn't have to sniff
+    # backend-specific error strings (HTTP status text vs SQLSTATE). When absent, the
+    # agent falls back to the HTTP string heuristics.
+    fn: Callable[..., dict]
+    backend: str = "http"  # "http" | "sql" — which transport family produced this tool
+    # Scopes the shared result cache: tools with the same name+args but a DIFFERENT data
+    # source (e.g. two warehouse DSNs, dev vs prod) must never serve each other's results.
+    # Blank (the HTTP loader) keeps today's name-keyed behavior.
+    cache_key: str = ""
+
+    def openai_spec(self) -> dict:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+
+# Simple in-process result cache (TTL) so repeated calls don't re-hit the API.
+_RESULT_CACHE: dict[str, tuple[float, dict]] = {}
+_CACHE_TTL = 600.0  # seconds
+
+
+class Catalog:
+    def __init__(self, tools: list[Tool], reference: list[dict] | None = None):
+        self.tools = {t.name: t for t in tools}
+        # Documentation records for ALL operations (incl. non-callable writes), so the agent
+        # can describe an operation's parameters without ever calling it. See openapi_loader.
+        self.reference = reference or []
+        # Resolves a location NAMED IN A QUESTION to the exact values a `*_location_names`
+        # parameter accepts (`sql_loader.LocationIndex`). Set by the SQL loader, absent for HTTP
+        # catalogs — the agent treats None as "no binding", so nothing depends on it existing.
+        self.locations = None
+
+    def specs(self, enabled: list[str] | None = None) -> list[dict]:
+        return [
+            t.openai_spec()
+            for name, t in self.tools.items()
+            if enabled is None or name in enabled
+        ]
+
+    def resolve(self, name: str) -> str | None:
+        """The real tool name for what the model asked to call. Exact match wins; otherwise recover a
+        mangled name (a small model that dropped a `gold_<source>_` prefix or used the underlying
+        `fn_...` function name) — but ONLY when it maps to a SINGLE tool, so we never guess wrong."""
+        if name in self.tools:
+            return name
+        low = name.lower()
+        for n in self.tools:
+            if n.lower() == low:
+                return n
+        want = _name_core(name)
+        if len(want) < 5:  # too short to match safely
+            return None
+        cands = list({n for n in self.tools
+                      if (c := _name_core(n)) and (c.endswith(want) or want.endswith(c))})
+        return cands[0] if len(cands) == 1 else None
+
+    def call(self, name: str, args: dict, timeout: int = 20, list_limit: int | None = None,
+             prefer_period: "tuple | None" = None,
+             prefer_terms: "frozenset[str] | None" = None) -> dict:
+        """`prefer_period` is the (year, month) the QUESTION is about, when it names one.
+
+        A result larger than the display cap has to drop rows, and recency is the right default —
+        but it is wrong for a historical question. Measured: three eval cases asking for 2018,
+        2024 and 2025 provider production were answered "the evidence does not include any data
+        for 2024", because the most-recent-150 slice handed the model 2025-2026 rows from a table
+        that genuinely holds 2024. Backends that cannot use the hint ignore it.
+        """
+        resolved = self.resolve(name)
+        tool = self.tools.get(resolved) if resolved else None
+        if not tool:
+            _LOG.warning("tool call: '%s' is not a known tool (args=%s)", name, trunc(args, 200))
+            return {"ok": False, "error": f"Unknown tool '{name}'", "content": "", "source": ""}
+        if resolved != name:
+            _LOG.info("tool call: recovered mangled name '%s' → '%s'", name, resolved)
+        name = resolved
+        key = (f"{tool.backend}:{tool.cache_key}:{name}:"
+               f"{json.dumps(args, sort_keys=True, default=str)}:{list_limit}:{prefer_period}:"
+               f"{sorted(prefer_terms) if prefer_terms else None}")
+        cached = _RESULT_CACHE.get(key)
+        now = time.time()
+        if cached and now - cached[0] < _CACHE_TTL:
+            _LOG.info("tool call: %s args=%s → result-cache HIT (%d chars)",
+                      name, trunc(args, 300), len(str(cached[1].get("content", ""))))
+            return cached[1]
+        _LOG.info("tool call: %s args=%s limit=%s", name, trunc(args, 300), list_limit)
+        t0 = time.time()
+        try:
+            try:
+                result = tool.fn(args, timeout, list_limit, prefer_period=prefer_period,
+                                 prefer_terms=prefer_terms)
+            except TypeError:            # an executor that predates the hint (the HTTP backend)
+                result = tool.fn(args, timeout, list_limit)
+        except Exception as e:  # network/parse errors degrade gracefully
+            _LOG.warning("tool call: %s raised %s: %s", name, e.__class__.__name__, trunc(str(e), 300))
+            return {"ok": False, "error": str(e), "content": "", "source": ""}
+        if result.get("ok"):
+            _RESULT_CACHE[key] = (now, result)
+            _LOG.info("tool call: %s ← ok (%d chars, %.2fs) source=%s",
+                      name, len(str(result.get("content", ""))), time.time() - t0,
+                      trunc(result.get("source", ""), 200))
+            _LOG.debug("tool call: %s content: %s", name, trunc(result.get("content", "")))
+        else:
+            _LOG.warning("tool call: %s ← FAILED kind=%s error=%s", name,
+                         result.get("kind", "-"), trunc(str(result.get("error", "")), 300))
+        return result

api_agent/chart.py

@@ -0,0 +1,144 @@
+"""When a result is worth drawing, and what to draw — decided in code, never by the model.
+
+A trend is the one shape prose is genuinely bad at. Asked for "the Dentrix production trend for the
+last 12 months through June 2026", the agent produced an accurate paragraph naming the first month,
+the last month, the low, the high, the total and the year-over-year change — six numbers standing in
+for twelve, and the reader still cannot see the shape. Twelve points on one line say it at a glance.
+
+The whole design question is *when*, because a chart of the wrong thing is worse than no chart: it
+is read faster than prose and doubted less. So this module answers with a spec or with None, and the
+conditions are deliberately narrow — every one of them exists to stop a specific way a chart lies:
+
+  * TRUNCATED ROWS ARE NEVER CHARTED. A line drawn over 150 of 665 rows shows a shape the data does
+    not have, and unlike a table it carries no visible sign that anything is missing. This is the
+    strictest rule here and the one most likely to be relaxed by accident.
+  * A GENUINE TIME SERIES ONLY (`metrics.period_column`: every row carries a period, all distinct,
+    already in order). A panel with repeating periods — twelve months x forty providers — would draw
+    a zigzag that means nothing.
+  * SMALL. Above ~36 points the picture stops being "a year at a glance"; below 3 there is no shape
+    to see and a stat tile is the honest form.
+  * ONE SCALE. Series are kept only while they share the primary's order of magnitude, so a dollar
+    line and a percentage line can never share an axis. A dual-scale chart is the most common
+    charting mistake there is, and the only reliable defence is to refuse to build one.
+  * AT MOST THREE SERIES, in a fixed hue order — the count that stays distinguishable under
+    colour-vision deficiency for every pair, so a reader who cannot separate two lines by hue is
+    never left guessing.
+
+Pure and dependency-free so it is testable without Streamlit or a browser; `ui.py` owns the drawing.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from .metrics import _as_period, _num, period_column
+
+# A year of months at a glance is the case this exists for; three years still reads. Past that the
+# eye is doing a job a table does better, and the points crowd below the 8px marker minimum.
+MAX_POINTS = 36
+MIN_POINTS = 3
+# Three hues clear every colour-vision-deficiency pair test in BOTH light and dark; a fourth puts
+# yellow and orange on screen together and stops clearing them. A result with more measures than
+# this keeps them — in the table view, which is always available beside the chart.
+MAX_SERIES = 3
+
+# Columns that are never a measure worth plotting: identifiers and ordering keys. Matched as a
+# whole word so `sort_key` and `card_id` go, because that is what these are — plumbing, not data.
+_NOT_A_MEASURE = re.compile(r"(?:^|_)(?:id|key|sort|idx|rank|code)(?:_|$)", re.I)
+# A BARE calendar column (`year`, `month`) holds an integer that would otherwise plot as a measure.
+# It must be a WHOLE-name match: `prior_year` and `last_year_val` are money, and an affix match on
+# `year` silently dropped the comparison series from every trend chart — the second line, the one
+# the whole chart exists to compare against.
+_CALENDAR_NAME = re.compile(r"(?:year|month|day|qtr|quarter|week|period|date)s?", re.I)
+# A share, a rate or a count lives on a different scale from money and must never share its axis.
+_RATIO = re.compile(r"pct|percent|rate|ratio|share|margin|per_", re.I)
+
+
+@dataclass
+class ChartSpec:
+    """Everything the renderer needs, and nothing about how it looks."""
+    period_column: str
+    series: list[str]                      # measure columns, primary first
+    points: list[dict] = field(default_factory=list)   # [{period, series, value}]
+    label: str = ""                        # what the reader is looking at
+
+
+def _measure_columns(rows: list[dict], period_col: str) -> list[str]:
+    """Numeric columns that hold a measure, most-populated first.
+
+    Order matters: the first one becomes the primary and sets the scale every other series has to
+    match, so it must be the column the reader is most likely to have asked about. Completeness is
+    the best available proxy — a column the warehouse fills for every row is the one the function
+    exists to return, and a mostly-null `budget` should never define the axis.
+    """
+    out: list[tuple[int, int, str]] = []
+    for i, col in enumerate(rows[0]):
+        if col == period_col or _NOT_A_MEASURE.search(col) or _CALENDAR_NAME.fullmatch(col):
+            continue
+        vals = [v for r in rows if (v := _num(r.get(col))) is not None]
+        if len(vals) < len(rows) * 0.5:    # mostly empty — not this result's subject
+            continue
+        out.append((-len(vals), i, col))   # ties keep the warehouse's own column order
+    return [c for _, _, c in sorted(out)]
+
+
+def _same_scale(rows: list[dict], primary: str, other: str) -> bool:
+    """Can `other` share `primary`'s axis?
+
+    Two guards, because either alone lets a lie through. The NAME guard stops a percentage sharing
+    an axis with dollars even when a small month happens to make the magnitudes look close. The
+    MAGNITUDE guard stops a count sharing an axis with dollars even though neither name says so —
+    plotting 3,437 procedures against $421,448 makes the procedure line a flat stripe on the floor
+    and invites the reader to conclude volume never moved.
+    """
+    if bool(_RATIO.search(primary)) != bool(_RATIO.search(other)):
+        return False
+    def typical(col: str) -> float:
+        vals = sorted(abs(v) for r in rows if (v := _num(r.get(col))) not in (None, 0))
+        return vals[len(vals) // 2] if vals else 0.0
+    a, b = typical(primary), typical(other)
+    if not a or not b:
+        return False
+    return max(a, b) / min(a, b) <= 20.0
+
+
+def chart_spec(rows: list[dict] | None, *, truncated: bool = False,
+               label: str = "") -> ChartSpec | None:
+    """A spec for a chart worth drawing, or None. See the module docstring for why each gate exists.
+
+    Returning None is the DEFAULT and the safe answer; every condition below has to hold.
+    """
+    if truncated or not rows or not isinstance(rows[0], dict):
+        return None
+    if not (MIN_POINTS <= len(rows) <= MAX_POINTS):
+        return None
+    period_col = period_column(rows)       # distinct AND ordered — a panel is rejected here
+    if not period_col:
+        return None
+    measures = _measure_columns(rows, period_col)
+    if not measures:
+        return None
+    primary = measures[0]
+    series = [primary] + [c for c in measures[1:] if _same_scale(rows, primary, c)]
+    series = series[:MAX_SERIES]
+    points = [{"period": _period_label(r.get(period_col)), "series": c, "value": v}
+              for r in rows for c in series if (v := _num(r.get(c))) is not None]
+    if len(points) < MIN_POINTS:
+        return None
+    return ChartSpec(period_column=period_col, series=series, points=points, label=label)
+
+
+_MONTHS = ("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec").split()
+
+
+def _period_label(v) -> str:
+    """'2026-06-01' -> 'Jun 2026'. Axis ticks are read, not parsed."""
+    p = _as_period(v)
+    if not p:
+        return str(v)
+    return f"{_MONTHS[p[1] - 1]} {p[0]}"
+
+
+def humanize(col: str) -> str:
+    """`prior_year` -> `Prior Year`. The legend is prose, not a schema."""
+    return re.sub(r"[_\s]+", " ", col or "").strip().title()

api_agent/cli.py

@@ -0,0 +1,31 @@
+"""Console entry point. After ``pip install "codi-api-agent[ui]"``:
+
+    api-agent            # launch the Streamlit UI
+    api-agent --help     # (streamlit flags are passed through, e.g. --server.port 8600)
+
+The DISTRIBUTION is `codi-api-agent` (the generic `api-agent` was already taken on PyPI); the
+import name and this console script stay `api_agent` / `api-agent`. Any install hint printed to a
+user has to name the distribution, or it sends them to a package that cannot be installed.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+def main() -> None:
+    ui = Path(__file__).with_name("ui.py")
+    try:
+        from streamlit.web import cli as stcli
+    except ModuleNotFoundError:
+        sys.exit(
+            'Streamlit is not installed. Install the UI extra:\n\n'
+            '    pip install "codi-api-agent[ui]"\n\n'
+            "(or use the agent programmatically: from api_agent import Agent, Config, load_catalog)"
+        )
+    sys.argv = ["streamlit", "run", str(ui), *sys.argv[1:]]
+    sys.exit(stcli.main())
+
+
+if __name__ == "__main__":
+    main()

api_agent/config.py

@@ -0,0 +1,296 @@
+"""Runtime configuration.
+
+Everything is environment-driven so the LLM provider and the per-component
+models stay swappable without touching code. The Streamlit UI can also override
+any field at runtime via `Config.override(...)`.
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field, replace
+
+try:  # .env is convenient in dev but optional
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except Exception:  # pragma: no cover - dotenv is optional
+    pass
+
+
+# Indicative USD pricing per 1,000,000 tokens as (input, output). Prices change and vary by
+# provider — treat these as defaults and OVERRIDE via the MODEL_PRICING env var (JSON, e.g.
+# '{"gpt-4o": [2.5, 10]}') or Config.model_pricing. A model not in the table (e.g. a free Groq
+# model) is treated as unpriced and no $ cost is shown.
+DEFAULT_MODEL_PRICING: dict[str, tuple[float, float]] = {
+    "gpt-4o": (2.50, 10.00),
+    "gpt-4o-mini": (0.15, 0.60),
+    "gpt-4.1": (2.00, 8.00),
+    "gpt-4.1-mini": (0.40, 1.60),
+    "gpt-4.1-nano": (0.10, 0.40),
+    "o3": (2.00, 8.00),
+    "o4-mini": (1.10, 4.40),
+    "gpt-4-turbo": (10.00, 30.00),
+    "gpt-3.5-turbo": (0.50, 1.50),
+}
+
+
+def _csv_env(name: str) -> list[str]:
+    """Parse a comma-separated env var into a stripped, non-empty list (e.g. LLM_API_KEYS)."""
+    return [x.strip() for x in os.getenv(name, "").split(",") if x.strip()]
+
+
+def _json_list_env(name: str) -> list:
+    """Parse a JSON-array env var (e.g. LLM_POOL) into a list; [] on absent/invalid."""
+    raw = os.getenv(name, "").strip()
+    if not raw:
+        return []
+    try:
+        val = json.loads(raw)
+        return val if isinstance(val, list) else []
+    except Exception:
+        return []
+
+
+def _pricing_from_env(base: dict) -> dict:
+    """Merge a MODEL_PRICING JSON override (e.g. '{"gpt-4o":[2.5,10]}') over the defaults."""
+    raw = os.getenv("MODEL_PRICING", "").strip()
+    merged = dict(base)
+    if raw:
+        try:
+            for k, v in json.loads(raw).items():
+                merged[k] = (float(v[0]), float(v[1]))
+        except Exception:
+            pass
+    return merged
+
+
+@dataclass
+class Config:
+    # OpenAI-compatible provider
+    base_url: str = "https://api.groq.com/openai/v1"
+    api_key: str = ""
+    # Rotate over SEVERAL keys on the same base_url (e.g. multiple Groq free accounts) so each key's
+    # daily/TPM limit is spread. From LLM_API_KEYS (comma-separated); falls back to [api_key].
+    api_keys: list[str] = field(default_factory=list)
+    # Advanced: a cross-provider backend pool (Groq + HuggingFace + …). JSON list of
+    # {"base_url","api_key","model"} via LLM_POOL — when set, the client ROTATES over these full
+    # backends for every call (spreading each provider's limit), ignoring the per-role model below.
+    llm_pool: list[dict] = field(default_factory=list)
+
+    # Per-component model selection (both must support tool calling). Each MAY be a comma-separated
+    # POOL (e.g. "openai/gpt-oss-120b,llama-3.3-70b-versatile") — the client rotates across the pool
+    # per query so no single model hits its rate limit, with automatic failover on a 429.
+    generator_model: str = "llama-3.3-70b-versatile"
+    judge_model: str = "llama-3.3-70b-versatile"
+    router_model: str = ""  # blank -> reuse the generator model
+    # MASTER SWITCH for LLM-BASED JUDGING / SCORING (JUDGE_ENABLED=0 to turn it off for a session).
+    # The judges cost real money — on a paid provider they are the grounding check, the
+    # responsiveness check and the presentation check, i.e. up to three extra calls per answered
+    # query, and the grounding one re-sends the whole evidence block. Off:
+    #   * `_validate` (grounding), `_assess_answered` (responsiveness) and `_assess_communication`
+    #     (presentation) return their neutral no-op verdicts WITHOUT calling the provider;
+    #   * `AgentResult.faithfulness.judged` is False (the UI shows "not judged" and says why);
+    #   * `AgentResult.rubric` is None — a scorecard whose groundedness dimension was never graded
+    #     would read as 0/5 "figures not verified", which is a lie about an unjudged answer;
+    #   * the self-correction retry cannot fire, because nothing flags a claim to fix.
+    # What does NOT change: every DETERMINISTIC guarantee. The figure-match against the fetched data
+    # (`_numbers_grounded`), the total / attribution / derived-figure / superlative repairs, the
+    # confidentiality scrub, the PII scan and the data-quality disclosure all still run — they are
+    # code, not judges. So the answer is still checked; it just isn't SCORED.
+    judge_enabled: bool = True
+    # The USER-FACING WRITING stages (synthesis, self-review, resynthesis) — the only ones whose
+    # output the user actually reads, and the only ones where a stronger model changes perceived
+    # quality. Measured on the 2026-07-25 eval run they are ~42% of input tokens (synthesis 9,896
+    # + self-review 7,224 + resynthesis 142 in/query), so upgrading ONLY these buys most of the
+    # quality for a fraction of a blanket upgrade: gpt-4.1-mini here + gpt-4o-mini everywhere else
+    # costs 1.7x total ($0.0071 -> $0.0123/query) vs 6.4x if every stage moved.
+    # Blank -> reuse the generator model (previous behaviour, so this is backwards-compatible).
+    synthesis_model: str = ""
+
+    # Routing (narrow a large spec's operations to the relevant few per query)
+    router_enabled: bool = True
+    router_top_k: int = 8   # caps.md: recall@5 stuck at 60% across 4 runs — give the executor 8 ops
+    router_min_tools: int = 6  # specs with at/below this many ops skip routing
+    router_llm_window: int = 80  # how many lexically-ranked ops the LLM picks from
+
+    # Embedding-based routing (semantic recall, fused with lexical via RRF = "hybrid"). Set to a
+    # local sentence-transformers model by default (downloaded once, ~80MB, runs offline after).
+    # Blank disables it (lexical only, no deps). If embedding_base_url is set it's a hosted
+    # OpenAI-compatible /embeddings endpoint instead of a local model.
+    embedding_model: str = "all-MiniLM-L6-v2"   # local; or "text-embedding-3-small" w/ a base_url
+    embedding_base_url: str = ""       # set -> hosted; blank -> local sentence-transformers
+    embedding_api_key: str = ""        # hosted key; blank -> reuse api_key
+
+    # Behaviour
+    max_tool_iterations: int = 8   # caps.md: ARQ analytical cases legitimately use 6–10 calls
+    # When the faithfulness judge flags specific unsupported claims, hand them back to the
+    # synthesizer to fix and re-check. 0 disables; each retry is 1 synthesis + 1 judge call, and a
+    # retry is kept only if it scores higher — so it can't make the answer worse.
+    max_synthesis_retries: int = 1
+    # Attach a five-dimension quality scorecard (correctness / completeness / groundedness /
+    # safety / communication) to every substantive answer. Groundedness reuses the existing
+    # (isolated) faithfulness judge and safety/correctness/completeness are DERIVED from signals
+    # already computed — so the ONLY added cost is one narrow presentation-only "communication"
+    # judge call per answered/partial query. Set RUBRIC_REPORT=0 to disable (no extra call, and
+    # AgentResult.rubric is None).
+    rubric_report: bool = True
+    # DATA-QUALITY DISCLOSURE. On: a load fault found in the fetched rows is surfaced to the reader
+    # — a trailing "Data quality" caveat, and for a fault in a figure the answer actually SHOWS, a
+    # leading banner plus a downgrade to `partial`. Set DATA_QUALITY_NOTES=0 to hide all of it from
+    # the answer.
+    #
+    # Hiding it does NOT make the answer safer: the flags fire on incomplete loads (a column that
+    # collapses to near zero, reverses sign, or is empty), and a decline computed against those
+    # values reflects the missing data rather than the business. With this off the reader gets the
+    # figures with nothing to warn them. Detection still runs and every flag is still logged at
+    # WARNING, so the fault stays visible in the trail and to the eval — only the reader stops
+    # seeing it.
+    data_quality_notes: bool = True
+    # DEBUG PANELS — "Sources" and "How this answer was produced". They carry the real operation
+    # names, their exact arguments and the source URIs, because that is what makes an answer
+    # debuggable. That is also exactly what must never reach a customer, so set DEBUG_PANELS=0 in
+    # production. The customer-visible live step trail is unaffected either way: it names only the
+    # business category an operation belongs to.
+    debug_panels: bool = True
+    # Cache: for a reworded repeat that isn't token-identical, the FAST router LLM decides whether it
+    # wants the SAME answer as a recent cached query. This ONLY runs on candidates that already passed
+    # the deterministic VALUE GUARD (same signature, count, numbers AND month names), so the earlier
+    # false-match class (a March finance-and-payroll snapshot served an April NetSuite report) is
+    # fenced out before the LLM is consulted — it can only judge same-vs-different REQUEST within one
+    # period. On by default; set CACHE_SEMANTIC=0 to require an exact normalized-token repeat instead.
+    cache_semantic: bool = True
+    http_timeout: int = 20
+    # SQL (warehouse) backend — used when a Postgres DSN is loaded as a source. The DSN
+    # should point at a SELECT-only role; the loader additionally forces read-only
+    # transactions + a statement timeout on every connection (see sql_loader.py).
+    sql_dsn: str = ""            # e.g. postgresql://agent_ro:***@localhost:7432/arq-dev
+    sql_schema: str = "gold"     # schema whose functions become tools
+    sql_fn_prefix: str = "fn_"   # only functions matching this prefix are exposed
+    sql_timeout: int = 30        # per-statement timeout, seconds
+    evidence_char_limit: int = 12000  # caps.md: floor on each result to SYNTHESIS (ev_cap scales with list_limit)
+    # How many items of a LIST response to show by default; the user can override per query ("show
+    # 100", "list all"). `list_max` caps "all" so a huge list can't blow the token budget. The
+    # per-result char budget scales with the requested count so the extra items actually fit.
+    list_default: int = 150   # caps.md: input is cheap (~15% of window); triples rows the model can filter from
+    list_max: int = 400       # caps.md: opt-in ceiling ("show all"); beyond this, aggregate instead of paging
+    # Append the code-rendered EVIDENCE TABLE beneath the narrative. Off by default: a wall of rows
+    # is not an answer, and the table has repeatedly been mistaken for one — a 54-figure dump
+    # outscored a correct sentence on the parity scorer. The figures a reader needs must come from
+    # the narrative and the derived facts, not from being handed the raw result to add up.
+    # NOTE: `_total_guard` computes its total from THIS table, so with tables off it cannot fire.
+    # Any total must then come from the derived facts (see the Phase 3 work in
+    # docs/hali_replacement_plan_v2.md).
+    render_evidence_table: bool = False
+    # SHARED CACHEABLE PREFIX across the three full-evidence stages (synthesis, self-review,
+    # validator). They each re-send the same evidence — measured at 453,543 input tokens over 62
+    # calls in one 20-case run, 60% of all input — and the provider's prefix cache cannot help,
+    # because each opens with a DIFFERENT system message so the token prefix diverges at position
+    # zero. With this on, every one of them leads with a byte-identical context block (question +
+    # evidence + code-computed facts) and puts its own instruction after it, so calls 2 and 3 read
+    # from cache. OFF by default: it moves each stage's task instruction behind a large block of
+    # data, which can weaken instruction adherence, and that trade has to be MEASURED on the eval
+    # set rather than assumed. Run the suite with it off and on and compare.
+    #
+    # The flag toggles LAYOUT ONLY, and making that true required one change in BOTH arms: the
+    # validator used to render evidence as `[id] content`, dropping the source label and skipping
+    # failed calls, while the other two stages used `[id] (source: …) content`. They now share one
+    # renderer (`_evidence_block`) — measured at +452 characters on a 62,055-character block, and
+    # it gains the judge the failed-call entries the writers already saw. Without that the flag
+    # would have been changing two things at once and the A/B would isolate nothing.
+    shared_prompt_prefix: bool = False
+    # Rows SCANNED (not shown) to build the statistical profile handed to the model in place of
+    # a huge table. The display cap stays `list_default`; this only widens what the DESCRIBE
+    # covers, so "the maximum" is the real maximum instead of the top of the first page — the
+    # measured failure was a $172,994 max computed from 50 of 5,830 rows (true: $228,588).
+    # Rows are discarded after profiling, so the PROMPT cost is ~10 lines regardless of this
+    # number; the only cost is fetch + PII-redaction time, measured at ~1s per 100k rows.
+    # Set high enough that real tables are profiled COMPLETELY (the largest ARQ function
+    # returns 5,830 rows, so this is ~17x headroom) — an incomplete scan makes the agent hedge
+    # ("large SAMPLE, not definitive") and blocks the deterministic superlative repair, which
+    # only fires on a complete profile. A table beyond this is still handled honestly rather
+    # than wrongly: `profile.complete` goes false and no extreme is asserted.
+    profile_rows: int = 100_000
+    # How much of each result is echoed BACK into the executor's working context per turn. Smaller
+    # than evidence_char_limit so the tool-loop stays lean and fast on multi-call (fan-out /
+    # pagination) queries — the executor only needs enough to decide the next call, while synthesis
+    # still gets the full result above. Raise if chaining needs more of each response visible.
+    executor_context_chars: int = 4000   # caps.md: modest bump for chaining; below the accumulation cliff
+    max_operations: int = 1000  # cap on ops loaded from a spec (router narrows per query)
+
+    # Spending guardrails (for paid, per-token providers)
+    # Stop a SINGLE response once its cumulative tokens reach this ceiling — the executor stops
+    # fanning out / retrying and answers with what it has (marked partial). 0 = unlimited.
+    max_response_tokens: int = 150_000   # caps.md: runaway ceiling (~3x a normal query, ~$0.03); was 0 = no cap
+    # Per-model USD pricing {model: (input_per_1M, output_per_1M)} used to estimate $ per response.
+    model_pricing: dict = field(default_factory=lambda: dict(DEFAULT_MODEL_PRICING))
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        d = cls()
+        return cls(
+            base_url=os.getenv("LLM_BASE_URL", d.base_url),
+            api_key=os.getenv("LLM_API_KEY", d.api_key),
+            api_keys=_csv_env("LLM_API_KEYS"),
+            llm_pool=_json_list_env("LLM_POOL"),
+            generator_model=os.getenv("GENERATOR_MODEL", d.generator_model),
+            synthesis_model=os.getenv("SYNTHESIS_MODEL", d.synthesis_model),
+            judge_model=os.getenv("JUDGE_MODEL", d.judge_model),
+            judge_enabled=os.getenv("JUDGE_ENABLED", str(d.judge_enabled)).lower()
+            not in ("0", "false", "no", "off"),
+            router_model=os.getenv("ROUTER_MODEL", d.router_model),
+            router_enabled=os.getenv("ROUTER_ENABLED", str(d.router_enabled)).lower()
+            not in ("0", "false", "no", "off"),
+            router_top_k=int(os.getenv("ROUTER_TOP_K", d.router_top_k)),
+            router_min_tools=int(os.getenv("ROUTER_MIN_TOOLS", d.router_min_tools)),
+            router_llm_window=int(os.getenv("ROUTER_LLM_WINDOW", d.router_llm_window)),
+            max_tool_iterations=int(os.getenv("MAX_TOOL_ITERATIONS", d.max_tool_iterations)),
+            max_synthesis_retries=int(os.getenv("MAX_SYNTHESIS_RETRIES", d.max_synthesis_retries)),
+            rubric_report=os.getenv("RUBRIC_REPORT", str(d.rubric_report)).lower()
+            not in ("0", "false", "no", "off"),
+            data_quality_notes=os.getenv("DATA_QUALITY_NOTES", str(d.data_quality_notes)).lower()
+            not in ("0", "false", "no", "off"),
+            debug_panels=os.getenv("DEBUG_PANELS", str(d.debug_panels)).lower()
+            not in ("0", "false", "no", "off"),
+            cache_semantic=os.getenv("CACHE_SEMANTIC", str(d.cache_semantic)).lower()
+            not in ("0", "false", "no", "off"),
+            http_timeout=int(os.getenv("HTTP_TIMEOUT", d.http_timeout)),
+            sql_dsn=os.getenv("SQL_DSN", d.sql_dsn),
+            sql_schema=os.getenv("SQL_SCHEMA", d.sql_schema),
+            sql_fn_prefix=os.getenv("SQL_FN_PREFIX", d.sql_fn_prefix),
+            sql_timeout=int(os.getenv("SQL_TIMEOUT", d.sql_timeout)),
+            evidence_char_limit=int(os.getenv("EVIDENCE_CHAR_LIMIT", d.evidence_char_limit)),
+            executor_context_chars=int(os.getenv("EXECUTOR_CONTEXT_CHARS", d.executor_context_chars)),
+            list_default=int(os.getenv("LIST_DEFAULT", d.list_default)),
+            list_max=int(os.getenv("LIST_MAX", d.list_max)),
+            render_evidence_table=os.getenv("RENDER_EVIDENCE_TABLE",
+                                            str(d.render_evidence_table)).lower()
+            in ("1", "true", "yes", "on"),
+            shared_prompt_prefix=os.getenv("SHARED_PROMPT_PREFIX",
+                                           str(d.shared_prompt_prefix)).lower()
+            in ("1", "true", "yes", "on"),
+            profile_rows=int(os.getenv("PROFILE_ROWS", d.profile_rows)),
+            max_operations=int(os.getenv("MAX_OPERATIONS", d.max_operations)),
+            max_response_tokens=int(os.getenv("MAX_RESPONSE_TOKENS", d.max_response_tokens)),
+            model_pricing=_pricing_from_env(d.model_pricing),
+            embedding_model=os.getenv("EMBEDDING_MODEL", d.embedding_model),
+            embedding_base_url=os.getenv("EMBEDDING_BASE_URL", d.embedding_base_url),
+            embedding_api_key=os.getenv("EMBEDDING_API_KEY", d.embedding_api_key),
+        )
+
+    def override(self, **kwargs) -> "Config":
+        """Return a copy with non-empty overrides applied (used by the UI)."""
+        clean = {k: v for k, v in kwargs.items() if v is not None and v != ""}
+        return replace(self, **clean)
+
+    def effective_keys(self) -> list[str]:
+        """The API key(s) to rotate over: the LLM_API_KEYS pool if given, else the single api_key."""
+        return self.api_keys or [self.api_key]
+
+    def problems(self) -> list[str]:
+        issues: list[str] = []
+        if not self.api_key:
+            issues.append("LLM_API_KEY is not set — add your provider key.")
+        if not self.base_url:
+            issues.append("LLM_BASE_URL is not set.")
+        return issues