failproofai-sdk 0.0.1b1__py3-none-any.whl

failproofai_sdk/__init__.py

@@ -0,0 +1,131 @@
+"""Telemetry for AI agents: emit events, spool them, let the daemon ship them.
+
+Three surfaces, in the order most people meet them:
+
+* **Scopes** — `session()`, `agent()`, `tool_call()`. Context managers that bind
+  run identity and, for the latter two, bracket a run with its own events. Work
+  under `with` and `async with`.
+* **Adapters** — `instrument()`. Auto-detects LangChain/LangGraph, CrewAI,
+  LlamaIndex and Pydantic AI in the process and wires them to the scopes above.
+* **`event.*`** — the 15 event methods, for anything the adapters do not cover.
+
+`session_id` and `agent_id` are optional on every event method: omitted, they
+resolve from the enclosing scope. Nothing bound and nothing passed is an error,
+never a silent drop — ingest skips an event with no session and answers 200.
+"""
+
+from typing import Any
+
+from failproofai_sdk._version import __version__
+from failproofai_sdk._environment import set_environment
+from failproofai_sdk._resolver import set_base_dir
+from failproofai_sdk._context import Identity, current, propagate
+from failproofai_sdk._runtime import event
+from failproofai_sdk._scopes import agent, session, tool_call
+from failproofai_sdk._environment import _reject_comma
+from failproofai_sdk._writer import _validated_interval
+from failproofai_sdk import _runtime
+
+__all__ = [
+    "__version__",
+    "configure",
+    "event",
+    "session",
+    "agent",
+    "tool_call",
+    "current",
+    "Identity",
+    "propagate",
+    "instrument",
+    "uninstrument",
+    "_writer",
+]
+
+
+def configure(
+    *,
+    base_dir=None,
+    flush_interval: float = 0.5,
+    environment: str | None = None,
+) -> None:
+    """Configure the SDK. Call once at startup before any event.* calls.
+
+    Args:
+        base_dir: Override the spool root. Pass None to resolve it to
+                  ~/.failproofai/custom-agents (honouring $FAILPROOFAI_HOME,
+                  which moves the umbrella but cannot take the spool outside
+                  it — the `custom-agents` segment is always appended).
+
+                  This is the ONLY way to spool anywhere else. No environment
+                  variable redirects it; $AGENTEYE_HOME used to and no longer
+                  does, because exporting it for the one component that still
+                  reads it (the older `agenteye-collector`) moved this SDK's
+                  spool as an unasked-for side effect.
+
+                  The default moved here from ~/.agenteye. `failproofaid`
+                  watches both roots, so on a host running it this only
+                  changes which directory the files appear in, and batches
+                  already spooled under the old root are still collected.
+                  On a host running only `agenteye-collector`, give that
+                  collector AGENTEYE_HOME=~/.failproofai/custom-agents so it
+                  watches where this SDK writes — or pass base_dir here.
+        flush_interval: Seconds between flush cycles. Default 0.5 (500ms).
+        environment: Deployment environment label (e.g. "production", "staging").
+                     Can also be set via the AGENTEYE_ENVIRONMENT env var.
+                     Defaults to "dev" when neither is set.
+
+    Raises:
+        ValueError: if `flush_interval` is not a finite number greater than zero.
+            Checked here, before anything is applied, so a rejected call leaves
+            the SDK exactly as it was rather than with a new base_dir and the old
+            interval.
+    """
+    # BOTH validations before ANY application. `set_environment` raises on a
+    # comma, and it used to run last — so `configure(base_dir=..., environment=
+    # "prod,eu")` raised having already moved the spool and the flush interval,
+    # which is precisely the half-applied state the docstring above promises is
+    # impossible. A caller who wraps startup in `except ValueError` (a reasonable
+    # thing to do for a telemetry library that must not crash the agent) was left
+    # shipping from a directory they did not choose.
+    flush_interval = _validated_interval(flush_interval)
+    if environment:
+        _reject_comma(environment, "configure(environment=...)")
+    set_base_dir(base_dir)
+    _runtime.writer.set_flush_interval(flush_interval)
+    set_environment(environment)
+
+
+def instrument(framework: str | None = None, **options: Any):
+    """Install the framework adapters.
+
+    With no argument, auto-detects the frameworks already imported in this
+    process. Pass a name (`"langchain"`, `"crewai"`, `"llama_index"`,
+    `"pydantic_ai"`) to install exactly one.
+
+    The import is inside the function on purpose: `failproofai_sdk.integrations`
+    reaches for framework packages, and `import failproofai_sdk` is
+    contractually zero-dependency — a promise `tests/test_zero_dependencies.py`
+    enforces both by scanning the core modules and by launching a fresh
+    interpreter to prove no framework lands in `sys.modules`.
+    """
+    from failproofai_sdk.integrations import instrument as _impl
+
+    return _impl(framework, **options)
+
+
+def uninstrument(framework: str | None = None):
+    """Reverse `instrument()`, restoring the original attributes.
+
+    Lazy-imported for the same reason as `instrument()`.
+    """
+    from failproofai_sdk.integrations import uninstrument as _impl
+
+    return _impl(framework)
+
+
+# MUST be last: any `import failproofai_sdk.<sub>` binds the *module* onto this
+# package as `failproofai_sdk._writer`. Rebinding it here to the instance is what
+# keeps the published `failproofai_sdk._writer.flush_now()` recipe working — and
+# is why a test reaching for the MODULE has to go through
+# `sys.modules["failproofai_sdk._writer"]`.
+_writer = _runtime.writer

failproofai_sdk/_context.py

@@ -0,0 +1,218 @@
+"""Ambient run identity, carried on contextvars.
+
+Before this module the SDK had no ambient session: every `event.*` call took
+`session_id` and `agent_id` as required keyword arguments and nothing propagated
+them. Threading both through every function that might emit an event is what makes
+instrumentation sprawl into a diff nobody wants to review.
+
+Two contextvars carry it instead. Read them through `current()`, or let
+`failproofai_sdk._events` fall back to them when a caller omits the identity.
+
+Why a tuple and not a list
+--------------------------
+`_AGENT_STACK` holds a **tuple**. A `ContextVar[list]` is shared *by reference*
+across tasks and threads, so `.append()` in one task mutates the value every other
+task sees — which is exactly the cross-run event mixing contextvars are here to
+prevent, wearing a contextvars costume. It passes every single-threaded test.
+Push is `set(stack + (aid,))`; pop is `reset(token)`.
+
+There is deliberately no `_AGENT_ID` var: the top of the stack *is* the current
+agent id, so the two cannot drift apart, and `parent_id` is `stack[-2]`.
+"""
+
+import contextvars
+import functools
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+# The agent_id used when events are emitted with a session bound but no agent
+# scope. "main" is the convention the skill and the reference integration already
+# teach, so an un-scoped event lands somewhere sensible rather than raising.
+DEFAULT_AGENT_ID = "main"
+
+_SESSION_ID: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "failproofai_sdk_session_id", default=None
+)
+_AGENT_STACK: contextvars.ContextVar[tuple[str, ...]] = contextvars.ContextVar(
+    "failproofai_sdk_agent_stack", default=()
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Identity:
+    """The run identity in scope. Never None — check `session_id is None` instead."""
+
+    session_id: str | None
+    agent_id: str | None
+    parent_id: str | None
+    depth: int
+
+
+def current() -> Identity:
+    """The identity bound to the current context.
+
+    `failproofai_sdk.current().session_id is None` means nothing is bound — either no
+    scope was entered, or this is a fresh thread that did not inherit one (see
+    `propagate`).
+    """
+    stack = _AGENT_STACK.get()
+    return Identity(
+        session_id=_SESSION_ID.get(),
+        agent_id=stack[-1] if stack else None,
+        parent_id=stack[-2] if len(stack) >= 2 else None,
+        depth=len(stack),
+    )
+
+
+def session_id() -> str | None:
+    """The bound session id, or None. Hot path — allocates no Identity."""
+    return _SESSION_ID.get()
+
+
+def agent_id() -> str:
+    """The current agent id, falling back to DEFAULT_AGENT_ID."""
+    stack = _AGENT_STACK.get()
+    return stack[-1] if stack else DEFAULT_AGENT_ID
+
+
+def parent_agent_id() -> str | None:
+    """The enclosing agent id, or None at depth 0 or 1."""
+    stack = _AGENT_STACK.get()
+    return stack[-2] if len(stack) >= 2 else None
+
+
+def bind_session(sid: str) -> contextvars.Token:
+    return _SESSION_ID.set(sid)
+
+
+def push_agent(aid: str) -> contextvars.Token:
+    return _AGENT_STACK.set(_AGENT_STACK.get() + (aid,))
+
+
+def reset(token: contextvars.Token | None) -> bool:
+    """Restore a contextvar to its pre-`set` value, tolerating a cross-context token.
+
+    `ContextVar.reset()` raises `ValueError: Token was created in a different
+    Context` when the token was minted in another thread *or another asyncio task*.
+    That happens when a scope is entered in one task and exited in another — not
+    always the caller's bug, as this used to say: asyncio finalizes an abandoned
+    async generator from a task of its own, so an `agent()` scope around a
+    `yield` gets its `__aexit__` run somewhere the token is foreign through no
+    fault of the code that wrote it.
+
+    Returns True when the token-based restore succeeded. It is a `bool` rather
+    than `None` so the caller can repair the values directly instead of leaving
+    a closed span on someone's stack; swallowing the error was never enough on
+    its own.
+    """
+    if token is None:
+        return True
+    try:
+        token.var.reset(token)
+        return True
+    except ValueError:
+        # WARNING, once, not a debug line. The consequence is not cosmetic: the
+        # frame this scope pushed stays bound in whatever context it was set in,
+        # so identity is wrong for everything that follows there. The caller
+        # cannot discover that any other way — there is no exception, and the
+        # events look plausible.
+        #
+        # It cannot always be repaired, either. When the set and the reset happen
+        # in different asyncio TASKS — the async-generator case in `agent()`'s
+        # docstring — `ContextVar.set` from this task cannot reach the context
+        # the value is bound in, so the caller has to change the code. Saying so
+        # once is the most this layer can do.
+        global _warned_cross_context
+        if not _warned_cross_context:
+            _warned_cross_context = True
+            logger.warning(
+                "failproofai_sdk: a scope was entered in one context and exited in "
+                "another, so its identity could not be unwound and later events in "
+                "the entering context may be attributed to it. The usual cause is an "
+                "`agent()`/`session()` scope spanning a `yield` in an async generator; "
+                "pass session_id=/agent_id= explicitly there instead.",
+                exc_info=True,
+            )
+        return False
+
+
+def discard_agent(agent_id: str) -> None:
+    """Remove ONE frame for `agent_id` from the current stack, innermost first.
+
+    The fallback for a token that cannot be reset. Removes a single occurrence
+    rather than every match, because the same `agent_id` may legitimately be on
+    the stack twice (a recursive agent), and dropping both would corrupt the
+    outer one to fix the inner.
+    """
+    stack = _AGENT_STACK.get()
+    for i in range(len(stack) - 1, -1, -1):
+        if stack[i] == agent_id:
+            _AGENT_STACK.set(stack[:i] + stack[i + 1 :])
+            return
+
+
+def restore_session(session_id: str | None) -> None:
+    """Put the session id back to a value captured before the scope was entered."""
+    _SESSION_ID.set(session_id)
+
+
+#: Deduplicates the cross-context warning above — it fires from a scope exit,
+#: which in a streaming server is per request.
+_warned_cross_context = False
+
+
+Snapshot = tuple[str | None, tuple[str, ...]]
+
+
+def snapshot() -> Snapshot:
+    """Capture the identity *values* currently bound."""
+    return (_SESSION_ID.get(), _AGENT_STACK.get())
+
+
+def restore(snap: Snapshot) -> tuple[contextvars.Token, contextvars.Token]:
+    """Bind a snapshot into the calling context."""
+    sid, stack = snap
+    return (_SESSION_ID.set(sid), _AGENT_STACK.set(stack))
+
+
+def discard(tokens: tuple[contextvars.Token, contextvars.Token] | None) -> None:
+    if tokens is None:
+        return
+    for token in reversed(tokens):
+        reset(token)
+
+
+def propagate(fn: Callable[..., Any]) -> Callable[..., Any]:
+    """Wrap `fn` so it runs with the identity bound *right now*.
+
+        pool.submit(failproofai_sdk.propagate(work), x)
+        pool.map(failproofai_sdk.propagate(work), items)
+        threading.Thread(target=failproofai_sdk.propagate(work)).start()
+        loop.run_in_executor(None, failproofai_sdk.propagate(work), x)
+
+    contextvars propagate into asyncio tasks automatically but **not into new
+    threads** — a thread starts with an empty context, so without this every event
+    a worker emits is dropped (or, since this change, raises TypeError).
+
+    This deliberately snapshots *values* rather than doing
+    `functools.partial(contextvars.copy_context().run, fn)`. A `Context` object
+    cannot be entered by two threads at once (`RuntimeError: cannot enter context:
+    ... is already entered`), so the copy_context form crashes the caller's worker
+    on any reuse — `pool.map`, a retried submit. Mutations made inside `ctx.run`
+    also persist in that Context, so a reused one leaks the previous call's agent
+    stack into the next.
+    """
+    snap = snapshot()
+
+    @functools.wraps(fn)
+    def _failproofai_propagated(*args: Any, **kwargs: Any) -> Any:
+        tokens = restore(snap)
+        try:
+            return fn(*args, **kwargs)
+        finally:
+            discard(tokens)
+
+    return _failproofai_propagated

failproofai_sdk/_environment.py

@@ -0,0 +1,78 @@
+import logging
+
+_DEFAULT_ENVIRONMENT = "dev"
+_environment: str | None = None
+
+#: Set once the comma warning below has been emitted. `get_environment()` runs
+#: from `to_dict()`, i.e. once per event on the caller's own thread, and the
+#: warning had no once-flag at all — so an `AGENTEYE_ENVIRONMENT` with a comma
+#: put one WARNING line into the host application's log for every event emitted,
+#: for the life of the process. At the SDK's documented ceiling that is a
+#: logging-driven throughput collapse in a library whose first constraint is not
+#: to disrupt the host agent. The comment two lines below already promised
+#: "Warn once"; this is what makes that true.
+_warned_comma = False
+
+logger = logging.getLogger("failproofai_sdk")
+
+
+def _reject_comma(env: str, source: str) -> None:
+    """A comma in `environment` makes ingest skip EVERY event carrying it.
+
+    The endpoint splits this field on commas to build its filter facets, so a
+    line whose `environment` contains one is discarded — the whole line, not the
+    field. It answers 200 with `{"accepted":0,"skipped":N}`, the daemon deletes
+    the delivered batch, and the run that produced it is simply never in the
+    dashboard: no exception here, nothing in the agent's output, and an empty
+    session list that looks exactly like an agent nobody ran.
+
+    `failproofaid` already refuses a comma in `collector.environment` for this
+    reason (`crates/fpai-collect/src/config.rs`). The SDK is the other writer of
+    the same field and did not, so `AGENTEYE_ENVIRONMENT="prod,eu"` — a wholly
+    reasonable thing to type — silently threw away everything the process
+    emitted.
+    """
+    if "," in env:
+        raise ValueError(
+            f"environment must not contain a comma (got {env!r} from {source}). "
+            "The ingest endpoint skips every event whose environment has one, so "
+            "this would silently discard all telemetry from this process. Use a "
+            "single label, e.g. 'prod-eu'."
+        )
+
+
+def get_environment() -> str:
+    if _environment is not None:
+        return _environment
+    import os
+
+    raw = os.environ.get("AGENTEYE_ENVIRONMENT")
+    if not raw:
+        return _DEFAULT_ENVIRONMENT
+    if "," in raw:
+        # Raising here would blow up inside `to_dict()` on an arbitrary event,
+        # far from the thing that set it, and take the caller's agent down with
+        # it — a telemetry library must not do that. Warn once and fall back to
+        # a label ingest will actually accept, so the events land under a
+        # visibly-wrong environment instead of vanishing.
+        global _warned_comma
+        if not _warned_comma:
+            _warned_comma = True
+            logger.warning(
+                "failproofai_sdk: AGENTEYE_ENVIRONMENT=%r contains a comma, which makes "
+                "the ingest endpoint skip every event carrying it. Falling back to %r. "
+                "Use a single label, e.g. 'prod-eu'.",
+                raw,
+                _DEFAULT_ENVIRONMENT,
+            )
+        return _DEFAULT_ENVIRONMENT
+    return raw
+
+
+def set_environment(env: str | None) -> None:
+    global _environment, _warned_comma
+    if env:
+        _reject_comma(env, "configure(environment=...)")
+    _environment = env if env else None
+    # A new label means the env var may be worth complaining about again.
+    _warned_comma = False