agenttic 1.0.0__py3-none-any.whl

agenttic/__init__.py

@@ -0,0 +1,128 @@
+"""agenttic — the public, supported entry point to the Agenttic platform.
+
+This umbrella package is a **semver'd promise** (SPEC-8 Hard Rule 36): every
+name it exports is a stable, supported surface. The implementation lives in the
+internal ``agenttic.*`` package, which is not part of the public contract and may
+change without notice. Import from here, never from ``ascore``.
+
+The whole point of Agenttic distribution: a developer who has never seen it can
+
+    pip install agenttic
+
+add one line
+
+    from agenttic import trace
+    agent = trace(my_agent)          # wraps LangGraph / OpenAI Agents / anything
+
+or certify from the shell
+
+    agenttic certify --mock          # → a signed safety grade, no API key
+
+The base install pulls **no framework SDK** and imports none (Hard Rule 37):
+``import agenttic`` works with zero of LangGraph/OpenAI-Agents/LangChain
+present. Framework support is optional and lazy — ``agenttic[langgraph]``,
+``agenttic[openai]``, ``agenttic[all]`` — and is imported only when you actually
+wrap a matching object.
+
+Public surface (exactly ``__all__``; a test fails if anything else leaks):
+
+* :func:`trace`      — auto-detecting wrapper for any agent framework
+* :func:`instrument` — decorator (and :func:`session` context manager) for
+  custom/homegrown agents
+* :func:`certify`    — certify an agent against a profile → evidence dossier
+* :func:`verify`     — recompute a dossier's hashes offline (signed-grade check)
+* :class:`Trace`, :class:`Span` — the canonical run type the pipeline consumes
+"""
+# NB: no ``from __future__ import annotations`` — it would bind the name
+# ``annotations`` into this namespace and leak it past the public-surface test.
+# Aliased private so it never leaks into the public surface (Hard Rule 36).
+from typing import Any as _Any
+
+# Version: single source of truth for the package. `agenttic` is now both the
+# public umbrella and the internal engine (the former `ascore` package was
+# folded in during the rename), so the version lives here directly. The
+# distribution `version` in pyproject.toml is kept in lock-step (asserted by a
+# test).
+__version__ = "1.0.0"
+
+# Certification surface — re-exported directly (core, no framework SDKs).
+from agenttic.certification.certify import certify as certify
+from agenttic.certification.dossier import verify as verify
+
+# The canonical run type the ingest/certification pipeline consumes.
+from agenttic.schema.trace import Span as Span
+from agenttic.schema.trace import Trace as Trace
+
+__all__ = [
+    "trace",
+    "instrument",
+    "session",
+    "certify",
+    "verify",
+    "Trace",
+    "Span",
+]
+
+
+# ---------------------------------------------------------------------------
+# The framework-facing surface (trace / instrument / session) is defined in the
+# internal submodules ``agenttic._detect`` and ``agenttic._decorator``. We
+# forward to them lazily so that ``import agenttic`` never pulls a framework SDK
+# (Hard Rule 37) and so the umbrella imports cleanly regardless of which extras
+# are present. The lazy import is per-call and cheap.
+# ---------------------------------------------------------------------------
+def trace(agent: _Any, *args: _Any, **kwargs: _Any) -> _Any:
+    """Wrap any agent so its runs emit a canonical Agenttic run.
+
+    Auto-detects the framework from the object's public shape and dispatches to
+    the right adapter — no need to name the framework:
+
+        from agenttic import trace
+        agent = trace(compiled_langgraph_graph)     # → LangGraph adapter
+        agent = trace(openai_agents_agent)          # → OpenAI Agents adapter
+        agent = trace(my_plain_callable)            # → generic OTel wrapper
+
+    Wrapping is **behavior-identical** (Hard Rule 38): the returned object
+    delegates everything to the original and returns byte-identical outputs;
+    it only observes. Spans go to ``target`` (falling back to the
+    ``AGENTTIC_TARGET`` / ``OTEL_EXPORTER_OTLP_ENDPOINT`` env vars); with no
+    target configured it is a no-op that logs where to set one — it never
+    phones home. ``enforce=True`` opts into the SPEC-4 gateway at the ramp's
+    non-blocking default posture. See :func:`agenttic._detect.trace`.
+    """
+    from ._detect import trace as _impl
+    return _impl(agent, *args, **kwargs)
+
+
+def instrument(*args: _Any, **kwargs: _Any) -> _Any:
+    """Decorate a custom ``query -> response`` function to emit a canonical run.
+
+        from agenttic import instrument
+
+        @instrument
+        def my_agent(query: str) -> str:
+            ...
+
+    Captures input, output and timing. If it can see into a supported LLM/tool
+    client called inside, it records the tool trajectory; otherwise it marks the
+    trajectory ``partial`` and logs why — it never fabricates tool calls
+    (Hard Rule 39). Same target/enforce and no-phone-home semantics as
+    :func:`trace`. See :func:`agenttic._decorator.instrument`.
+    """
+    from ._decorator import instrument as _impl
+    return _impl(*args, **kwargs)
+
+
+def session(*args: _Any, **kwargs: _Any) -> _Any:
+    """Context-manager form of :func:`instrument` for code that isn't a single
+    function::
+
+        with agenttic.session(agent_id="my-agent") as run:
+            run.input = query
+            run.output = do_work(query)
+
+    Produces the same canonical run as the decorator. See
+    :func:`agenttic._decorator.session`.
+    """
+    from ._decorator import session as _impl
+    return _impl(*args, **kwargs)

agenttic/__main__.py

@@ -0,0 +1,6 @@
+"""Run the CLI with ``python -m agenttic`` (equivalent to the ``agenttic``
+console script; ``ascore`` remains as a deprecated alias)."""
+from agenttic.cli import app
+
+if __name__ == "__main__":
+    app()

agenttic/_decorator.py

@@ -0,0 +1,133 @@
+"""@instrument decorator + session() context manager (SPEC-8 Step 42).
+
+For custom / homegrown agents that aren't a supported framework: wrap any
+``query -> response`` function (or an arbitrary block of code) so it emits a
+canonical Agenttic run — input, output, timing.
+
+    from agenttic import instrument, session
+
+    @instrument                       # or @instrument(agent_id="my-agent")
+    def my_agent(query: str) -> str:
+        ...
+
+    with session(agent_id="my-agent") as run:   # for code that isn't one fn
+        run.input = query
+        run.output = do_work(query)
+
+Honest degradation (Hard Rule 39): when the tool trajectory can't be observed
+(the general case for an opaque callable), the run is marked ``partial`` with a
+logged reason — Agenttic never invents tool calls. Same target/enforce and
+no-silent-phone-home semantics as :func:`agenttic.trace` (Hard Rule 38): with no
+target configured, wrapping runs the code unchanged and emits nothing, logging
+where to configure a target.
+"""
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+from agenttic.ingest.emit import SpanEmitter
+
+# The generic-run mechanism is shared with the auto-detecting trace() fallback:
+# @instrument and trace(plain_callable) produce the same canonical run.
+from ._detect import (
+    _GENERIC_PARTIAL_REASON,
+    _guidance_once,
+    _resolve_enforce,
+    _resolve_target,
+    _wrap_callable,
+)
+
+log = logging.getLogger("agenttic")
+
+DEFAULT_AGENT_ID = "instrumented-agent"
+_SCOPE = "agenttic_instrument"
+
+
+def instrument(fn: Any = None, *, agent_id: str = DEFAULT_AGENT_ID,
+               target: str | None = None, enforce: Any = False,
+               agent_config_hash: str = "", sink: list | None = None,
+               reg: Any = None, cfg: Any = None):
+    """Decorate a ``query -> response`` function so each call emits a canonical
+    run. Usable bare (``@instrument``) or parameterized
+    (``@instrument(agent_id=...)``). Sync and async functions are both
+    supported; the wrapper is behavior-identical (returns byte-identical output,
+    re-raises the same exception)."""
+    def decorate(func: Any):
+        endpoint = _resolve_target(target, cfg)
+        posture = _resolve_enforce(enforce, cfg)
+        if endpoint is None and sink is None:
+            _guidance_once()
+        return _wrap_callable(
+            func, agent_id=agent_id, agent_config_hash=agent_config_hash,
+            endpoint=endpoint, auth_header=None, sink=sink, enforce=posture,
+            reg=reg, cfg=cfg, scope_name=_SCOPE)
+
+    if fn is not None:            # @instrument
+        return decorate(fn)
+    return decorate               # @instrument(...) / instrument(...)(fn)
+
+
+class _Session:
+    """The object yielded by :func:`session`. Set ``.input`` and ``.output``;
+    on exit, one canonical (partial) run is emitted."""
+
+    def __init__(self, *, agent_id: str, agent_config_hash: str,
+                 endpoint: str | None, auth_header: str | None,
+                 sink: list | None, enforce: Any, reg: Any, cfg: Any,
+                 input: Any = None):
+        self.agent_id = agent_id
+        self.input = input
+        self.output: Any = None
+        self._agent_config_hash = agent_config_hash
+        self._endpoint = endpoint
+        self._auth_header = auth_header
+        self._sink = sink
+        self._enforce = enforce
+        self._reg = reg
+        self._cfg = cfg
+        self._t0: int | None = None
+        self._guard = None
+
+    def __enter__(self) -> "_Session":
+        self._t0 = time.time_ns()
+        if self._enforce:
+            from agenttic.enforce.adapter_guard import build_enforce_guard
+            self._guard = build_enforce_guard(
+                self.agent_id, self._enforce, reg=self._reg, cfg=self._cfg)
+            self._guard.begin()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        latency_ms = (time.time_ns() - (self._t0 or time.time_ns())) / 1e6
+        emitter = SpanEmitter(
+            self.agent_id, agent_config_hash=self._agent_config_hash,
+            endpoint=self._endpoint, auth_header=self._auth_header,
+            sink=self._sink, scope_name=_SCOPE)
+        emitter.emit_agent_run(
+            input=self.input,
+            output=(None if exc_type else self.output),
+            latency_ms=latency_ms, partial=True,
+            reason=(f"raised {exc_type.__name__}: {exc}" if exc_type
+                    else _GENERIC_PARTIAL_REASON))
+        emitter.flush()
+        if self._guard is not None:
+            self._guard.end()
+        return False  # never suppress the caller's exception (behavior-identical)
+
+
+def session(*, agent_id: str = DEFAULT_AGENT_ID, target: str | None = None,
+            enforce: Any = False, agent_config_hash: str = "",
+            sink: list | None = None, reg: Any = None, cfg: Any = None,
+            input: Any = None) -> _Session:
+    """Context-manager form of :func:`instrument` for code that isn't a single
+    function. Produces the same canonical run as the decorator."""
+    endpoint = _resolve_target(target, cfg)
+    posture = _resolve_enforce(enforce, cfg)
+    if endpoint is None and sink is None:
+        _guidance_once()
+    return _Session(
+        agent_id=agent_id, agent_config_hash=agent_config_hash,
+        endpoint=endpoint, auth_header=None, sink=sink, enforce=posture,
+        reg=reg, cfg=cfg, input=input)

agenttic/_detect.py

@@ -0,0 +1,325 @@
+"""Auto-detecting ``trace()`` (SPEC-8 Step 41).
+
+One import for everyone::
+
+    from agenttic import trace
+    agent = trace(anything)
+
+``trace`` inspects the object's **public shape** and dispatches to the right
+adapter without the caller ever naming the framework:
+
+* a LangGraph compiled graph  → the ``agenttic-langgraph`` adapter
+* an OpenAI Agents SDK agent   → the ``agenttic-openai-agents`` adapter
+* anything else callable       → a generic OTel-emitting wrapper (Step 42's
+  mechanism, :func:`agenttic._decorator` — a partial-trajectory canonical run)
+
+Detection is duck-typed on documented type/attribute signatures — we never
+import a framework's private modules, and we never import the framework SDK just
+to *detect* (so a fixture that merely mimics the shape dispatches correctly, and
+a missing SDK is simply "not this one"). Loading the matched adapter is behind
+``try/except ImportError``: if the object looks like LangGraph but
+``agenttic-langgraph`` isn't installed, we fall back to the generic wrapper
+rather than crash. The resolution order and the matched adapter are logged at
+DEBUG.
+
+Guarantees: behavior-identical wrapping (Hard Rule 38 — observe, never block or
+mutate), and no telemetry by default (Hard Rule 38 — with no target configured
+it is a no-op that logs where to set one; it never phones home). ``enforce=True``
+opts into the SPEC-4 gateway at the ramp's non-blocking default posture.
+"""
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+from typing import Any
+
+log = logging.getLogger("agenttic")
+
+_GUIDANCE_LOGGED = False
+
+
+# --- target resolution / no-phone-home guidance (Hard Rule 38) -------------
+def _config_get(cfg: Any, *keys: str) -> Any:
+    """Read cfg['distribution'][key] from a passed dict, else from the config
+    file named by AGENTTIC_CONFIG, else None. Never raises."""
+    for key in keys:
+        if isinstance(cfg, dict):
+            val = (cfg.get("distribution") or {}).get(key)
+            if val:
+                return val
+    path = os.environ.get("AGENTTIC_CONFIG")
+    if path and os.path.exists(path):
+        try:
+            from agenttic.config import load_config
+            dist = (load_config(path).get("distribution") or {})
+            for key in keys:
+                if dist.get(key):
+                    return dist[key]
+        except Exception:  # noqa: BLE001 — config is best-effort for the library
+            return None
+    return None
+
+
+def _resolve_target(target: str | None, cfg: Any = None) -> str | None:
+    """Where spans go, in priority order: explicit ``target`` arg → the
+    AGENTTIC_TARGET / OTEL_EXPORTER_OTLP_ENDPOINT env vars → the ``distribution.
+    target`` config key (dict or AGENTTIC_CONFIG file). None => don't emit."""
+    if target:
+        return target
+    env = (os.environ.get("AGENTTIC_TARGET")
+           or os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT"))
+    if env:
+        return env
+    return _config_get(cfg, "target")
+
+
+# Non-blocking postures only — blocking ones (enforce_reads/enforce_all) must be
+# ramped up deliberately server-side, never turned on by a library flag (Rules
+# 31, 35). build_enforce_guard rejects a blocking posture loudly; we surface the
+# same contract here so `trace(enforce=...)` fails fast with a clear message.
+_NON_BLOCKING_POSTURES = {"observe", "shadow"}
+
+
+def _resolve_enforce(enforce: Any, cfg: Any = None) -> Any:
+    """Resolve the opt-in enforce posture. ``False`` → off. ``True`` → the
+    configured ``distribution.enforce_posture`` (default ``shadow``). An explicit
+    string is validated as non-blocking. Returns the posture string, or False."""
+    if not enforce:
+        return False
+    posture = (_config_get(cfg, "enforce_posture") or "shadow") \
+        if enforce is True else str(enforce)
+    if posture not in _NON_BLOCKING_POSTURES:
+        raise ValueError(
+            f"agenttic.trace: enforce posture {posture!r} is blocking; the "
+            "library only permits non-blocking postures "
+            f"({', '.join(sorted(_NON_BLOCKING_POSTURES))}). Ramp up blocking "
+            "enforcement deliberately via the gateway, not a library flag.")
+    return posture
+
+
+def _guidance_once() -> None:
+    """Log — exactly once — how to configure a target. No silent phone-home:
+    with no target and no sink, wrapping still runs the agent but emits nothing,
+    and the user is told how to turn telemetry on (Hard Rule 38)."""
+    global _GUIDANCE_LOGGED
+    if _GUIDANCE_LOGGED:
+        return
+    log.warning(
+        "agenttic.trace: no target configured — the wrapped agent runs normally "
+        "but NO telemetry is emitted (nothing leaves this process). To send runs "
+        "to your Agenttic instance, pass target='https://your-agenttic/v1/traces' "
+        "or set the AGENTTIC_TARGET (or OTEL_EXPORTER_OTLP_ENDPOINT) env var.")
+    _GUIDANCE_LOGGED = True
+
+
+# --- framework detection (public shape only; never a private import) -------
+def _type_name(obj: Any) -> str:
+    try:
+        return type(obj).__name__
+    except Exception:  # pragma: no cover - exotic objects
+        return ""
+
+
+def is_langgraph(obj: Any) -> bool:
+    """A LangGraph compiled graph: the public ``CompiledStateGraph`` / ``Pregel``
+    type name, or the LangChain Runnable shape (``invoke`` + ``stream`` +
+    ``get_graph`` callables) that a compiled graph exposes."""
+    if _type_name(obj) in {"CompiledStateGraph", "CompiledGraph", "Pregel"}:
+        return True
+    return all(callable(getattr(obj, m, None))
+               for m in ("invoke", "stream", "get_graph"))
+
+
+def is_openai_agent(obj: Any) -> bool:
+    """An OpenAI Agents SDK ``Agent``: its public attribute shape
+    (``instructions`` + ``tools`` + ``handoffs`` + ``name``). ``Runner`` is
+    separate; users pass the agent."""
+    if _type_name(obj) == "Agent" and hasattr(obj, "instructions") \
+            and hasattr(obj, "tools"):
+        return True
+    return (hasattr(obj, "instructions") and hasattr(obj, "tools")
+            and hasattr(obj, "handoffs") and hasattr(obj, "name"))
+
+
+def _missing_extra(framework: str, extra: str, type_name: str) -> ImportError:
+    """A recognized framework object with no adapter installed: an actionable
+    error (install the extra), never an opaque crash."""
+    return ImportError(
+        f"agenttic.trace: this looks like a {framework} object ({type_name}), "
+        f"but the {framework} adapter isn't installed. Install it with:  "
+        f"pip install 'agenttic[{extra}]'")
+
+
+def _load_adapter(module_name: str):
+    """Import a framework adapter, or return None if it isn't installed
+    (a missing SDK is "not available", never a crash)."""
+    try:
+        return importlib.import_module(module_name)
+    except ImportError:
+        return None
+
+
+# --- the one public entry point -------------------------------------------
+def trace(agent: Any, *, target: str | None = None, enforce: Any = False,
+          agent_id: str | None = None, agent_config_hash: str = "",
+          auth_header: str | None = None, sink: list | None = None,
+          reg: Any = None, cfg: Any = None) -> Any:
+    """Wrap ``agent`` so its runs emit a canonical Agenttic run — dispatching to
+    the matching framework adapter by shape, or to a generic wrapper.
+
+    ``target`` selects where spans go (defaults to the AGENTTIC_TARGET /
+    OTEL_EXPORTER_OTLP_ENDPOINT env vars); with nothing configured wrapping is a
+    logged no-op that never phones home. ``enforce=True`` routes tool calls
+    through the SPEC-4 gateway at the ramp's non-blocking default posture (opt-in
+    only). ``sink`` captures the OTLP payload in-process (tests / air-gapped)."""
+    endpoint = _resolve_target(target, cfg)
+    enforce = _resolve_enforce(enforce, cfg)
+    if enforce:
+        log.debug("agenttic.trace: enforce posture = %s (non-blocking, opt-in)",
+                  enforce)
+    if endpoint is None and sink is None:
+        _guidance_once()
+
+    if is_langgraph(agent):
+        adapter = _load_adapter("agenttic_langgraph")
+        if adapter is not None:
+            log.debug("agenttic.trace: matched LangGraph adapter for %s",
+                      _type_name(agent))
+            return adapter.trace(
+                agent, agent_id=agent_id or "langgraph-agent",
+                agent_config_hash=agent_config_hash, endpoint=endpoint,
+                auth_header=auth_header, sink=sink, enforce=enforce,
+                reg=reg, cfg=cfg)
+        if not callable(agent):
+            raise _missing_extra("LangGraph", "langgraph", _type_name(agent))
+        log.debug("agenttic.trace: %s looks like LangGraph but agenttic-langgraph "
+                  "is not installed — using the generic wrapper", _type_name(agent))
+    elif is_openai_agent(agent):
+        adapter = _load_adapter("agenttic_openai_agents")
+        if adapter is not None:
+            log.debug("agenttic.trace: matched OpenAI Agents adapter for %s",
+                      _type_name(agent))
+            return adapter.trace(
+                agent, agent_id=agent_id or "openai-agent",
+                agent_config_hash=agent_config_hash, endpoint=endpoint,
+                auth_header=auth_header, sink=sink, enforce=enforce,
+                reg=reg, cfg=cfg)
+        if not callable(agent):
+            raise _missing_extra("OpenAI Agents", "openai", _type_name(agent))
+        log.debug("agenttic.trace: %s looks like OpenAI Agents but "
+                  "agenttic-openai-agents is not installed — using the generic "
+                  "wrapper", _type_name(agent))
+
+    log.debug("agenttic.trace: no known framework matched %s — generic OTel "
+              "wrapper (partial trajectory)", _type_name(agent))
+    return _generic_trace(
+        agent, agent_id=agent_id or "agent",
+        agent_config_hash=agent_config_hash, endpoint=endpoint,
+        auth_header=auth_header, sink=sink, enforce=enforce, reg=reg, cfg=cfg)
+
+
+# --- generic fallback: wrap an arbitrary callable --------------------------
+_GENERIC_PARTIAL_REASON = (
+    "the wrapped function's internal tool/LLM calls are not observable from "
+    "outside, so the tool trajectory is recorded as partial (never fabricated)")
+
+
+def _wrap_callable(fn: Any, *, agent_id: str, agent_config_hash: str = "",
+                   endpoint: str | None = None, auth_header: str | None = None,
+                   sink: list | None = None, enforce: Any = False,
+                   reg: Any = None, cfg: Any = None, scope_name: str = "agenttic_generic"):
+    """Return a behavior-identical wrapper around ``fn`` that emits one
+    partial-trajectory canonical run per call. Shared by the generic ``trace()``
+    fallback and the ``@instrument`` decorator (Step 42)."""
+    import functools
+    import time
+
+    from agenttic.ingest.emit import SpanEmitter
+
+    def _emit(inp: Any, out: Any, err: Exception | None, t0: int) -> None:
+        latency_ms = (time.time_ns() - t0) / 1e6
+        emitter = SpanEmitter(agent_id, agent_config_hash=agent_config_hash,
+                              endpoint=endpoint, auth_header=auth_header,
+                              sink=sink, scope_name=scope_name)
+        emitter.emit_agent_run(
+            input=inp, output=(None if err else out), latency_ms=latency_ms,
+            partial=True,
+            reason=(f"raised {type(err).__name__}: {err}" if err
+                    else _GENERIC_PARTIAL_REASON))
+        emitter.flush()
+
+    def _guard():
+        if not enforce:
+            return None
+        from agenttic.enforce.adapter_guard import build_enforce_guard
+        return build_enforce_guard(agent_id, enforce, reg=reg, cfg=cfg)
+
+    is_async = _is_coro(fn)
+
+    if is_async:
+        @functools.wraps(fn)
+        async def awrapper(*args: Any, **kwargs: Any) -> Any:
+            guard = _guard()
+            if guard is not None:
+                guard.begin()
+            t0 = time.time_ns()
+            out = None
+            err: Exception | None = None
+            try:
+                out = await fn(*args, **kwargs)
+                return out
+            except Exception as e:  # behavior-identical: observe then re-raise
+                err = e
+                raise
+            finally:
+                _emit(_first_arg(args, kwargs), out, err, t0)
+                if guard is not None:
+                    guard.end()
+        return awrapper
+
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        guard = _guard()
+        if guard is not None:
+            guard.begin()
+        t0 = time.time_ns()
+        out = None
+        err = None
+        try:
+            out = fn(*args, **kwargs)
+            return out
+        except Exception as e:  # behavior-identical: observe then re-raise
+            err = e
+            raise
+        finally:
+            _emit(_first_arg(args, kwargs), out, err, t0)
+            if guard is not None:
+                guard.end()
+    return wrapper
+
+
+def _generic_trace(fn: Any, **kw: Any):
+    if not callable(fn):
+        raise TypeError(
+            "agenttic.trace: don't know how to trace a "
+            f"{type(fn).__name__!r}; pass a LangGraph graph, an OpenAI Agents "
+            "agent, or a callable (query -> response).")
+    return _wrap_callable(fn, **kw)
+
+
+def _is_coro(fn: Any) -> bool:
+    import asyncio
+    if asyncio.iscoroutinefunction(fn):
+        return True
+    call = getattr(fn, "__call__", None)
+    return call is not None and asyncio.iscoroutinefunction(call)
+
+
+def _first_arg(args: tuple, kwargs: dict) -> Any:
+    """The agent's query: the first positional arg, else the first kwarg."""
+    if args:
+        return args[0]
+    if kwargs:
+        return next(iter(kwargs.values()))
+    return None

agenttic/_env.py

@@ -0,0 +1,76 @@
+"""Environment-variable back-compat shim for the ``ascore`` → ``agenttic`` rename.
+
+Every variable that used to be read as ``ASCORE_<NAME>`` is now read
+``AGENTTIC_<NAME>``-first, falling back to the legacy ``ASCORE_<NAME>`` (with a
+``DeprecationWarning``) so existing deployments keep working unchanged.
+
+This is load-bearing in production: node1's ``.env`` supplies
+``ASCORE_CERT_SIGNING_KEY`` and ``ASCORE_PASSPORT_SIGNING_KEY``. If the renamed
+code stopped honoring the ``ASCORE_*`` names, cert/passport signing would fail
+closed and the app would 502. Do NOT rename those vars on the host; the shim
+keeps reading them (while nudging operators toward ``AGENTTIC_*``).
+
+Precedence, for a shimmed name ``X``:
+
+    AGENTTIC_X  >  ASCORE_X (deprecated)  >  default
+
+Only names that already start with ``ASCORE_`` / ``AGENTTIC_`` participate in
+the dance; any other name (``ANTHROPIC_API_KEY``, ``FI_API_KEY``, …) is read
+verbatim, exactly like ``os.environ.get``.
+"""
+
+from __future__ import annotations
+
+import os
+import warnings
+from typing import Mapping
+
+_NEW_PREFIX = "AGENTTIC_"
+_OLD_PREFIX = "ASCORE_"
+
+
+def _suffix(name: str) -> str | None:
+    """The bare suffix of a shimmed var (``ASCORE_DB``/``AGENTTIC_DB`` → ``DB``),
+    or ``None`` if ``name`` is not part of the rename shim."""
+    if name.startswith(_NEW_PREFIX):
+        return name[len(_NEW_PREFIX):]
+    if name.startswith(_OLD_PREFIX):
+        return name[len(_OLD_PREFIX):]
+    return None
+
+
+def candidate_names(name: str) -> tuple[str, str | None]:
+    """Return ``(new_name, old_name)`` for a shimmed var, or ``(name, None)`` for
+    a name that does not participate in the rename shim."""
+    suf = _suffix(name)
+    if suf is None:
+        return name, None
+    return _NEW_PREFIX + suf, _OLD_PREFIX + suf
+
+
+def warn_legacy(old: str, new: str, *, stacklevel: int = 3) -> None:
+    """Emit the deprecation nudge for reading a legacy ``ASCORE_*`` var."""
+    warnings.warn(
+        f"Environment variable {old} is deprecated; set {new} instead "
+        f"({old} is still honored for backward compatibility).",
+        DeprecationWarning,
+        stacklevel=stacklevel,
+    )
+
+
+def get_env(name: str, default: str | None = None, *,
+            environ: Mapping[str, str] | None = None) -> str | None:
+    """Drop-in for ``os.environ.get(name, default)`` with rename back-compat.
+
+    For an ``ASCORE_*``/``AGENTTIC_*`` name: prefer ``AGENTTIC_<X>``; else fall
+    back to ``ASCORE_<X>`` (emitting a ``DeprecationWarning``); else return
+    ``default``. For any other name, behaves exactly like ``os.environ.get``.
+    """
+    env = os.environ if environ is None else environ
+    new, old = candidate_names(name)
+    if new in env:
+        return env[new]
+    if old is not None and old in env:
+        warn_legacy(old, new)
+        return env[old]
+    return default