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

api_agent/llm.py

@@ -0,0 +1,470 @@
+"""Thin wrapper over any OpenAI-compatible chat endpoint.
+
+Because Groq, HuggingFace, Ollama and OpenAI all expose the same surface, the
+only thing that changes between providers is `base_url` / `api_key` / `model` —
+all of which are configuration. Per-component model choice is handled by the
+caller passing `model=...`.
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+import uuid
+import contextvars
+from contextlib import contextmanager
+from typing import Any
+
+from .config import Config
+from .log import get_logger, trunc
+from .schemas import Usage
+
+# Current pipeline stage, for per-stage token attribution. A ContextVar, not an
+# attribute: judges run concurrently and must not file each other's tokens.
+_STAGE: contextvars.ContextVar[str] = contextvars.ContextVar("llm_stage", default="")
+
+_LOG = get_logger("api_agent.llm")
+
+
+def _log_request(messages: list[dict], model: str, tools, json_mode: bool, kind: str) -> None:
+    """One line per LLM request. INFO = shape summary; DEBUG = every message in full."""
+    total = sum(len(str(m.get("content") or "")) for m in messages)
+    _LOG.info("%s → model=%s messages=%d (%s chars) tools=%d json=%s",
+              kind, model, len(messages), f"{total:,}", len(tools or []), json_mode)
+    if _LOG.isEnabledFor(10):  # DEBUG — full inputs
+        for i, m in enumerate(messages):
+            _LOG.debug("%s msg[%d] %s: %s", kind, i, m.get("role"), trunc(m.get("content") or ""))
+
+
+def _log_response(resp, model: str, kind: str) -> None:
+    """One line per LLM response. INFO = shape + tokens; DEBUG = full content + tool calls."""
+    try:
+        msg = resp.choices[0].message
+        content = msg.content or ""
+        calls = getattr(msg, "tool_calls", None) or []
+        u = getattr(resp, "usage", None)
+        toks = f" tokens={u.prompt_tokens}+{u.completion_tokens}" if u else ""
+        if u:
+            det = getattr(u, "prompt_tokens_details", None)
+            hit = getattr(det, "cached_tokens", None) if det is not None else None
+            if hit:  # only when the provider reports a hit — silence means "no cache info"
+                toks += f" (cached {hit}/{u.prompt_tokens} = {100 * hit / max(u.prompt_tokens, 1):.0f}%)"
+        _LOG.info("%s ← model=%s content=%d chars tool_calls=%d%s",
+                  kind, model, len(content), len(calls), toks)
+        if _LOG.isEnabledFor(10):  # DEBUG — full outputs
+            if content:
+                _LOG.debug("%s reply: %s", kind, trunc(content))
+            for c in calls:
+                _LOG.debug("%s tool_call: %s(%s)", kind, c.function.name,
+                           trunc(c.function.arguments or ""))
+    except Exception:  # logging must never break the pipeline
+        pass
+
+# When a backend returns a rate-limit (429), rest it this long before trying it again — so the
+# rotation stops hammering an exhausted key/model and spreads onto the others. A transient 5xx /
+# connection blip gets a short rest instead (the provider is up, just hiccuped).
+_RATE_COOLDOWN_S = 60
+_TRANSIENT_COOLDOWN_S = 5
+# When EVERY backend is rate-limited/hiccuping on a call (the common case with a SINGLE key), wait
+# briefly and retry rather than failing the whole query on one 429 — providers cap requests-per-
+# minute, and the agent bursts several calls per question, so a short wait usually clears it.
+_RATE_RETRIES = 3            # extra attempts after the first
+_RATE_RETRY_MAX_WAIT = 12.0  # seconds cap per backoff sleep (keeps a UI Stop responsive)
+
+
+def _retry_after_seconds(error: Exception) -> float | None:
+    """Seconds the provider asked us to wait, from a ``Retry-After`` response header, if present."""
+    resp = getattr(error, "response", None)
+    headers = getattr(resp, "headers", None)
+    if not headers:
+        return None
+    for key in ("retry-after", "Retry-After"):
+        val = headers.get(key) if hasattr(headers, "get") else None
+        if val:
+            try:
+                return float(str(val).strip().rstrip("s"))
+            except ValueError:
+                pass
+    return None
+
+
+def _retry_wait(error: Exception, attempt: int) -> float:
+    """How long to sleep before the next retry: the provider's Retry-After, else exponential
+    backoff (2, 4, 8 …), capped so a UI Stop stays responsive."""
+    hinted = _retry_after_seconds(error)
+    return min(_RATE_RETRY_MAX_WAIT, hinted if hinted is not None else 2.0 * (2 ** attempt))
+
+
+def _is_rate_limit(error: Exception) -> bool:
+    """True for a provider rate-limit / quota error (HTTP 429) — the signal to fail over."""
+    if error.__class__.__name__ == "RateLimitError":
+        return True
+    code = getattr(error, "status_code", None) or getattr(error, "code", None)
+    if code == 429 or code == "429":
+        return True
+    s = str(error).lower()
+    return any(h in s for h in ("rate limit", "429", "too many requests", "quota", "insufficient_quota"))
+
+
+def _is_transient(error: Exception) -> bool:
+    """True for a temporary server/connection error worth retrying on a DIFFERENT backend (5xx,
+    connection, timeout) — but NOT a 4xx like `tool_use_failed`, which the caller must handle."""
+    if error.__class__.__name__ in ("APIConnectionError", "APITimeoutError", "InternalServerError"):
+        return True
+    code = getattr(error, "status_code", None)
+    return bool(isinstance(code, int) and 500 <= code < 600)
+
+
+class LLMClient:
+    """OpenAI-compatible client with built-in **multi-LLM rotation**. A model string may be a
+    comma-separated POOL ("a,b,c"), and multiple keys / a cross-provider `llm_pool` can be given;
+    the client round-robins across these backends PER QUERY (stable within a query for a consistent
+    answer, different across queries to spread load) and fails over on a 429 with a cooldown — so no
+    single free-tier model or key hits its limit. A single model + key behaves exactly as before."""
+
+    def __init__(self, config: Config):
+        from openai import OpenAI  # lazy import so the pure helpers don't need the SDK
+
+        self.config = config
+        # Build the unique OpenAI clients + the (client_idx, model) backends to rotate over.
+        self._pool_entries: list[tuple[int, str]] | None = None  # set only in cross-provider pool mode
+        if config.llm_pool:
+            uniq: dict[tuple[str, str], int] = {}
+            self._clients = []
+            self._pool_entries = []
+            for e in config.llm_pool:
+                bu = e.get("base_url") or config.base_url
+                key = e.get("api_key") or config.api_key or "not-needed"
+                model = e.get("model") or config.generator_model
+                ck = (bu, key)
+                if ck not in uniq:
+                    uniq[ck] = len(self._clients)
+                    self._clients.append(OpenAI(base_url=bu, api_key=key))
+                self._pool_entries.append((uniq[ck], model))
+        else:
+            # Simple mode: one client per key on the single base_url; models come from the passed pool.
+            self._clients = [OpenAI(base_url=config.base_url, api_key=k or "not-needed")
+                             for k in config.effective_keys()]
+
+        self._query_idx = -1            # bumped each reset_usage → per-query rotation offset
+        self._cooldown: dict[tuple[int, str], float] = {}  # (client_idx, model) -> usable-after epoch
+        # Running token tally for the CURRENT query (reset per Agent.run). `on_usage` is an optional
+        # callback fired after each call with the updated tally, so a UI can show a live counter.
+        self.usage = Usage()
+        self.on_usage = None
+
+    @contextmanager
+    def stage(self, name: str):
+        """Attribute every call made inside this block to pipeline stage `name`.
+
+        Nests safely (the previous stage is restored on exit) so a helper that tags its own
+        stage can be called from within another without losing the outer attribution.
+
+        Held in a ContextVar rather than on `self` because stages can now run CONCURRENTLY. As a
+        plain attribute the last writer won: two judges running at once would file each other's
+        tokens, and the losing branch's `finally` would restore a stage that was never its own —
+        silently corrupting the per-stage numbers that make cost work targetable in the first
+        place. A ContextVar gives each thread its own value, and `contextvars.copy_context()` at
+        the point of hand-off carries the caller's stage in as the starting value."""
+        token = _STAGE.set(name)
+        try:
+            yield
+        finally:
+            _STAGE.reset(token)
+
+    # -- rotation helpers ------------------------------------------------------------------------ #
+    @staticmethod
+    def _split(model) -> list[str]:
+        if isinstance(model, (list, tuple)):
+            return [str(m).strip() for m in model if str(m).strip()] or [""]
+        return [m.strip() for m in str(model).split(",") if m.strip()] or [""]
+
+    def _combos(self, model) -> list[tuple[int, str]]:
+        """The (client_idx, model) backends for this call. Cross-provider pool mode uses the fixed
+        pool; simple mode is every key × every model in the passed pool."""
+        if self._pool_entries is not None:
+            return self._pool_entries
+        return [(ci, m) for m in self._split(model) for ci in range(len(self._clients))]
+
+    def _ordered(self, model) -> list[tuple[int, str]]:
+        """Backends to try, best first: start at the per-query offset, ready (not-cooled) ones first."""
+        combos = self._combos(model)
+        n = len(combos)
+        start = self._query_idx % n if n else 0
+        order = [combos[(start + i) % n] for i in range(n)]
+        now = time.time()
+        ready = [c for c in order if self._cooldown.get(c, 0) <= now]
+        return ready or order  # if everything is cooling down, try anyway rather than give up
+
+    def reset_usage(self) -> None:
+        self.usage = Usage()  # rebind (don't mutate) so an already-returned result keeps its own
+        self._query_idx += 1  # rotate to the next backend for this new query
+
+    @staticmethod
+    def _cached_tokens(raw) -> int | None:
+        """Prompt tokens the provider served from its prefix cache, or None when it doesn't say.
+        OpenAI reports `usage.prompt_tokens_details.cached_tokens`; providers that don't support
+        caching simply omit the field, so this stays None and nothing is assumed."""
+        details = getattr(raw, "prompt_tokens_details", None)
+        if details is None:
+            return None
+        got = getattr(details, "cached_tokens", None)
+        if got is None and isinstance(details, dict):
+            got = details.get("cached_tokens")
+        return got
+
+    def _record_usage(self, raw, model: str = "") -> None:
+        """Fold one response's token usage (attributed to `model`) into the running tally and notify
+        any listener."""
+        self.usage.add(getattr(raw, "prompt_tokens", None),
+                       getattr(raw, "completion_tokens", None),
+                       getattr(raw, "total_tokens", None), model=model,
+                       cached=self._cached_tokens(raw), stage=_STAGE.get())
+        if self.on_usage:
+            try:
+                self.on_usage(self.usage)
+            except Exception:
+                pass
+
+    def _cool(self, combo: tuple[int, str], error: Exception) -> None:
+        self._cooldown[combo] = time.time() + (_RATE_COOLDOWN_S if _is_rate_limit(error)
+                                               else _TRANSIENT_COOLDOWN_S)
+
+    @staticmethod
+    def _kwargs(model, messages, tools, tool_choice, json_mode, temperature, stream) -> dict:
+        kwargs: dict[str, Any] = {"model": model, "messages": messages, "temperature": temperature}
+        if tools:
+            kwargs["tools"] = tools
+            kwargs["tool_choice"] = tool_choice or "auto"
+        if json_mode:
+            kwargs["response_format"] = {"type": "json_object"}
+        if stream:
+            kwargs["stream"] = True
+            kwargs["stream_options"] = {"include_usage": True}  # final usage-only chunk
+        return kwargs
+
+    def complete(
+        self,
+        messages: list[dict],
+        model: str,
+        tools: list[dict] | None = None,
+        tool_choice: str | None = None,
+        json_mode: bool = False,
+        temperature: float = 0.0,
+    ):
+        _log_request(messages, model, tools, json_mode, "llm")
+        last: Exception | None = None
+        for attempt in range(_RATE_RETRIES + 1):
+            last = None
+            for (ci, m) in self._ordered(model):
+                kwargs = self._kwargs(m, messages, tools, tool_choice, json_mode, temperature, stream=False)
+                try:
+                    resp = self._clients[ci].chat.completions.create(**kwargs)
+                except Exception as e:
+                    if _is_rate_limit(e) or _is_transient(e):  # this backend is busy → try the next one
+                        _LOG.warning("llm backend %s rate-limited/transient (%s) — failing over",
+                                     m, trunc(str(e), 200))
+                        self._cool((ci, m), e)
+                        last = e
+                        continue
+                    _LOG.warning("llm call failed on %s: %s", m, trunc(str(e), 300))
+                    raise  # e.g. tool_use_failed (400) — the caller recovers it; don't fail over
+                self._record_usage(getattr(resp, "usage", None), model=m)
+                _log_response(resp, m, "llm")
+                return resp
+            # Every backend was rate-limited/hiccuping this pass. Rather than fail the whole query on
+            # one 429 (the usual outcome with a SINGLE key), wait briefly and retry — per-minute caps
+            # clear fast. Only 429/5xx reach here; a hard 4xx re-raised above already.
+            if attempt < _RATE_RETRIES and last is not None:
+                time.sleep(_retry_wait(last, attempt))
+                continue
+            break
+        raise last if last else RuntimeError("no LLM backend available")
+
+    def stream(self, messages: list[dict], model: str, json_mode: bool = False,
+               temperature: float = 0.0):
+        """Yield content-delta strings from a STREAMING chat completion (no tool calls). Rotates like
+        `complete`: fails over to the next backend on a pre-stream 429; once tokens start flowing it
+        re-raises (the caller falls back to a normal `complete`, which rotates again)."""
+        _log_request(messages, model, None, json_mode, "llm-stream")
+        last: Exception | None = None
+        for (ci, m) in self._ordered(model):
+            kwargs = self._kwargs(m, messages, None, None, json_mode, temperature, stream=True)
+            yielded = False
+            parts: list[str] = []  # accumulated for the output log (streamed = no single response)
+            try:
+                final_usage = None
+                for chunk in self._clients[ci].chat.completions.create(**kwargs):
+                    u = getattr(chunk, "usage", None)
+                    if u:
+                        final_usage = u  # arrives on the terminal chunk (choices is empty there)
+                    try:
+                        delta = chunk.choices[0].delta.content
+                    except (IndexError, AttributeError):
+                        delta = None
+                    if delta:
+                        yielded = True
+                        parts.append(delta)
+                        yield delta
+                self._record_usage(final_usage, model=m)
+                streamed = "".join(parts)
+                _LOG.info("llm-stream ← model=%s content=%d chars", m, len(streamed))
+                _LOG.debug("llm-stream reply: %s", trunc(streamed))
+                return
+            except Exception as e:
+                if not yielded and (_is_rate_limit(e) or _is_transient(e)):
+                    _LOG.warning("llm-stream backend %s rate-limited/transient (%s) — failing over",
+                                 m, trunc(str(e), 200))
+                    self._cool((ci, m), e)
+                    last = e
+                    continue
+                _LOG.warning("llm-stream failed on %s after %d chars: %s",
+                             m, sum(len(p) for p in parts), trunc(str(e), 300))
+                raise
+        if last:
+            raise last
+
+
+def extract_json(text: str | None) -> dict:
+    """Best-effort JSON parse from a model response.
+
+    Small/open models sometimes wrap JSON in prose or code fences, so we strip
+    fences and fall back to the outermost ``{...}`` span before giving up.
+    """
+    if not text:
+        return {}
+    text = text.strip()
+    if text.startswith("```"):
+        parts = text.split("```")
+        if len(parts) >= 2:
+            text = parts[1]
+        if text.lstrip().lower().startswith("json"):
+            text = text.lstrip()[4:]
+    text = text.strip()
+    try:
+        return json.loads(text)
+    except Exception:
+        start, end = text.find("{"), text.rfind("}")
+        if start != -1 and end != -1 and end > start:
+            try:
+                return json.loads(text[start : end + 1])
+            except Exception:
+                return {}
+    return {}
+
+
+# Some open models (notably Llama on Groq) emit tool calls as text like
+# `<function=name{...json...}</function>` instead of the structured tool_calls the
+# provider expects. The provider then returns a 400 `tool_use_failed` with the raw
+# attempt in `failed_generation`. We parse it and resume the loop.
+_FUNCTION_RE = re.compile(r"<function=([\w.\-]+)\s*>?\s*(\{.*?\})", re.DOTALL)
+
+
+def _error_body(error: Exception) -> dict | None:
+    """The provider error object. The SDK stores it directly on ``.body``; older/other
+    shapes nest it under an ``error`` key — handle both."""
+    body = getattr(error, "body", None)
+    if isinstance(body, dict):
+        return body.get("error") if isinstance(body.get("error"), dict) else body
+    return None
+
+
+def is_tool_use_failed(error: Exception) -> bool:
+    """True if the error is a provider `tool_use_failed` (Groq/Llama tool-format issue)."""
+    err = _error_body(error)
+    if err and err.get("code") == "tool_use_failed":
+        return True
+    return "tool_use_failed" in str(error)
+
+
+def _first_json_object(text: str, start: int = 0) -> str | None:
+    """Return the first balanced ``{...}`` substring at/after ``start`` (brace-aware of
+    quoted strings), so we can pull a JSON tool call out of a stringified error."""
+    i = text.find("{", start)
+    while i != -1:
+        depth, in_str, esc, quote = 0, False, "", ""
+        for j in range(i, len(text)):
+            c = text[j]
+            if in_str:
+                if esc:
+                    esc = False
+                elif c == "\\":
+                    esc = True
+                elif c == quote:
+                    in_str = False
+            elif c in ("\"", "'"):
+                in_str, quote = True, c
+            elif c == "{":
+                depth += 1
+            elif c == "}":
+                depth -= 1
+                if depth == 0:
+                    return text[i : j + 1]
+        i = text.find("{", i + 1)
+    return None
+
+
+def _calls_from_json(text: str) -> list[tuple[str, str, dict]]:
+    """Parse ``{"name":..,"arguments":{..}}`` (or a list of them) into recovered calls."""
+    try:
+        parsed = json.loads(text)
+    except Exception:
+        return []
+    out: list[tuple[str, str, dict]] = []
+    for item in parsed if isinstance(parsed, list) else [parsed]:
+        if not isinstance(item, dict):
+            continue
+        name = item.get("name") or (item.get("function") or {}).get("name")
+        args = item.get("arguments")
+        if args is None:
+            args = item.get("parameters") or (item.get("function") or {}).get("arguments") or {}
+        if isinstance(args, str):
+            try:
+                args = json.loads(args)
+            except Exception:
+                args = {}
+        if name and isinstance(args, dict):
+            out.append((f"call_{uuid.uuid4().hex[:8]}", name, args))
+    return out
+
+
+def recover_tool_calls(error: Exception) -> list[tuple[str, str, dict]] | None:
+    """Recover tool calls from a `tool_use_failed` error.
+
+    Returns a list of ``(call_id, tool_name, args_dict)`` or ``None`` if nothing
+    recoverable was found.
+    """
+    err = _error_body(error)
+    failed = err.get("failed_generation") if err else None
+    text = str(error)
+
+    calls: list[tuple[str, str, dict]] = []
+    # Format A: `<function=name{...json...}</function>` text (search the clean field and
+    # the raw error string).
+    for source in (failed, text):
+        if not source:
+            continue
+        for name, raw in _FUNCTION_RE.findall(source):
+            try:
+                args = json.loads(raw)
+            except Exception:
+                continue
+            calls.append((f"call_{uuid.uuid4().hex[:8]}", name, args))
+        if calls:
+            return calls
+
+    # Format B: a clean JSON tool call the provider rejected on schema validation, e.g.
+    # `{"name": "op", "arguments": {...}}` with a required param omitted. Recover the intent
+    # so the executor can run it (missing path params default to the collection/root).
+    candidates: list[str] = []
+    if failed:
+        candidates.append(failed)
+    if "failed_generation" in text:  # body not a dict / unwrapped — pull it from the text
+        obj = _first_json_object(text, text.find("failed_generation"))
+        if obj:
+            candidates.append(obj)
+    for c in candidates:
+        calls.extend(_calls_from_json(c))
+        if calls:
+            return calls
+    return None

api_agent/log.py

@@ -0,0 +1,138 @@
+"""Pipeline logging — every step's inputs and outputs, correlated per run.
+
+One logger tree (``api_agent.*``) instrumented at the pipeline's chokepoints, so a full
+debug trace needs no code changes — just environment variables:
+
+    LOG_LEVEL=INFO    step tracking: every stage, tool call, LLM call, routing decision,
+                      verdict and final status, with truncated inputs/outputs (default)
+    LOG_LEVEL=DEBUG   full payloads: complete LLM message lists + responses, complete
+                      tool-call args + result content
+    LOG_LEVEL=WARNING quiet (failures/failovers only)
+    LOG_FILE=agent.log       also write to a file (console always on)
+    LOG_PAYLOAD_CHARS=800    truncation for any single logged payload (0 = unlimited)
+    LOG_RAW_ROWS=1           log warehouse rows BEFORE PII redaction (opt-in; see below)
+
+For the complete console trail — every step's full input and output — set:
+
+    LOG_LEVEL=DEBUG  LOG_PAYLOAD_CHARS=0
+
+Both are read AFTER `load_dotenv()` when the UI calls `setup(force=True)`, so putting them in
+`.env` works. They did not, before that call existed: `agent.py` imports `metrics` → this module
+before it imports `config`, so the level and the cap were frozen at their pre-dotenv values and a
+setting in `.env` was ignored with nothing said.
+
+Every record carries a ``run_id`` — a short id minted per ``Agent.run()`` — so parallel
+tool calls and interleaved queries stay attributable:
+
+    12:01:03 INFO    [a1b2c3d4] api_agent.agent: [call] Calling gold_fn_...(p_year=2026)
+
+Payload notes: tool-result content is logged AFTER PII redaction (it's the same string the
+model sees), and credentials are never logged (no DSNs, no auth headers, no api keys).
+
+`LOG_RAW_ROWS=1` additionally logs the warehouse rows as the DATABASE returned them, before
+redaction. It is log-only and changes nothing the model receives — redaction still runs, so the
+answer's PII guarantee holds either way. It exists because redaction happens at FETCH, not at log
+time, so without it the unredacted payload does not exist anywhere to log. It writes personal and
+contact data to the console (and to LOG_FILE), so enable it only where that is acceptable.
+"""
+from __future__ import annotations
+
+import contextvars
+import logging
+import os
+import uuid
+
+_run_id: contextvars.ContextVar[str] = contextvars.ContextVar("run_id", default="-")
+
+# Default truncation for a single logged payload; 0 = unlimited.
+#
+# READ DYNAMICALLY, never frozen at import — that was a silent bug. `agent.py` imports `metrics`
+# (and therefore this module) BEFORE it imports `config`, which is where `load_dotenv()` runs. So
+# `LOG_LEVEL=DEBUG` / `LOG_PAYLOAD_CHARS=0` placed in `.env` were read too late and ignored
+# entirely: the cap stayed 800 and the logger stayed INFO, with nothing to say so.
+PAYLOAD_CHARS = int(os.getenv("LOG_PAYLOAD_CHARS", "800") or 0)
+
+
+def payload_chars() -> int:
+    """The CURRENT truncation cap. Env wins, so it can be set after this module was imported."""
+    raw = os.getenv("LOG_PAYLOAD_CHARS")
+    if raw is None or raw.strip() == "":
+        return PAYLOAD_CHARS
+    try:
+        return int(raw)
+    except ValueError:
+        return PAYLOAD_CHARS
+
+_FMT = "%(asctime)s %(levelname)-7s [%(run_id)s] %(name)s: %(message)s"
+_configured = False
+
+
+def _install_record_factory() -> None:
+    """Stamp the current run's correlation id onto EVERY LogRecord (a logger-level filter
+    would miss records propagated up from child loggers like ``api_agent.catalog``). The
+    id rides a contextvar, so the UI's worker thread and — via the context copy in
+    ``Agent._run_calls`` — parallel tool-call threads all carry the right one."""
+    old = logging.getLogRecordFactory()
+    if getattr(old, "_api_agent_run_id", False):  # idempotent
+        return
+
+    def factory(*args, **kwargs):
+        record = old(*args, **kwargs)
+        record.run_id = _run_id.get()
+        return record
+
+    factory._api_agent_run_id = True
+    logging.setLogRecordFactory(factory)
+
+
+def setup(level: str | None = None, file: str | None = None, force: bool = False) -> None:
+    """Configure the ``api_agent`` logger (console + optional file). Idempotent — safe to call from
+    Agent/Supervisor/UI init; later calls are no-ops.
+
+    ``force=True`` RE-APPLIES the level to an already-configured logger. The UI needs it: this
+    module is imported (and configured at the then-current LOG_LEVEL) before `config.load_dotenv()`
+    has run, so a level set in `.env` would otherwise never take effect.
+    """
+    global _configured
+    if _configured:
+        if force:
+            logging.getLogger("api_agent").setLevel(
+                (level or os.getenv("LOG_LEVEL", "INFO")).upper())
+        return
+    _configured = True
+    _install_record_factory()
+    root = logging.getLogger("api_agent")
+    root.setLevel((level or os.getenv("LOG_LEVEL", "INFO")).upper())
+    root.propagate = False  # our handlers own the format; don't double-print via the root logger
+    fmt = logging.Formatter(_FMT, datefmt="%H:%M:%S")
+    console = logging.StreamHandler()
+    console.setFormatter(fmt)
+    root.addHandler(console)
+    path = file or os.getenv("LOG_FILE", "")
+    if path:
+        fh = logging.FileHandler(path, encoding="utf-8")
+        fh.setFormatter(fmt)
+        root.addHandler(fh)
+
+
+def get_logger(name: str) -> logging.Logger:
+    setup()
+    return logging.getLogger(name)
+
+
+def new_run_id() -> str:
+    """Mint + activate a fresh correlation id for one Agent.run() (returns it for reuse)."""
+    rid = uuid.uuid4().hex[:8]
+    _run_id.set(rid)
+    return rid
+
+
+def trunc(obj, limit: int | None = None) -> str:
+    """A payload as a single log-safe string, truncated to LOG_PAYLOAD_CHARS (marker shows
+    how much was cut). ``limit`` overrides; 0/negative = unlimited."""
+    s = obj if isinstance(obj, str) else repr(obj)
+    s = s.replace("\n", "\\n")
+    lim = payload_chars() if limit is None else limit
+    if lim <= 0 or len(s) <= lim:
+        return s
+    return f"{s[:lim]}…(+{len(s) - lim:,} chars)"