traceact 0.1.0__py3-none-any.whl

traceact/__init__.py

@@ -0,0 +1,43 @@
+# __init__.py
+#
+# Public API for the traceact package.
+#
+# Everything a developer needs to use TraceAct is exported from here. Importing
+# from the submodules directly (e.g. from traceact.trace import ActionTrace) is
+# supported but not the intended pattern — this file is the stable public surface.
+#
+# Public API (v1):
+#
+#   ActionTrace   — the live trace object. Use with ActionTrace.start() for manual
+#                   tracing inside a with-block.
+#
+#   TraceConfig   — settings object. Pass to configure() or to @traced_action.
+#
+#   TraceBudget   — limits object. Pass to configure() or to @traced_action.
+#
+#   configure()   — set package-wide defaults for all future traces.
+#
+#   reset_config()— restore package defaults (use in test teardown).
+#
+#   traced_action — decorator. The primary way to add tracing to a function.
+#
+#   JsonlSink     — writes traces to a .jsonl file.
+#
+#   ConsoleSink   — prints traces to stdout.
+
+from traceact.config import configure, reset_config, TraceConfig
+from traceact.budget import TraceBudget
+from traceact.trace import ActionTrace
+from traceact.decorators import traced_action
+from traceact.sinks import JsonlSink, ConsoleSink
+
+__all__ = [
+    "ActionTrace",
+    "TraceConfig",
+    "TraceBudget",
+    "configure",
+    "reset_config",
+    "traced_action",
+    "JsonlSink",
+    "ConsoleSink",
+]

traceact/budget.py

@@ -0,0 +1,103 @@
+# budget.py
+#
+# Defines TraceBudget — the limits object that controls how much TraceAct
+# records before stopping and flagging budget_hit on the trace.
+#
+# Why a separate budget from config?
+# Config controls *behaviour* (is tracing on? what mode? strict or not?).
+# Budget controls *volume* (how many events? how deep? what size payloads?).
+# Keeping them separate makes it easy to tune one without touching the other,
+# and makes the inherited-vs-overridden distinction clear at each trace boundary.
+#
+# How budget inheritance works:
+# Like TraceConfig, TraceBudget uses None to mean "not specified." When a child
+# trace specifies TraceBudget(max_events=300), only max_events is overridden —
+# all other fields are inherited from the parent trace or the package default.
+#
+# This is key because a specific trace (say, an agent loop) might need more
+# events than the default, but still wants the global max_depth and
+# always_trace_errors settings to apply.
+
+from typing import Optional
+
+
+class TraceBudget:
+    """
+    Controls the recording limits for a trace.
+
+    All fields default to None, which means "not specified — inherit from the
+    parent trace or use the package default." See _resolve_budget() in trace.py
+    for how inheritance is applied.
+
+    Fields:
+        max_events:
+            Maximum number of events to record in a single trace. Once this
+            limit is reached, further calls to trace.event() are silently
+            dropped and budget_hit is set to True on the trace. The wrapped
+            function continues to run normally.
+
+        max_steps:
+            Maximum number of steps to record. Same behaviour as max_events
+            once the limit is hit.
+
+        max_depth:
+            Maximum nesting depth for child traces. If a @traced_action
+            decorator would create a trace at depth > max_depth, the decorator
+            behaves as if tracing is disabled for that call. The function still
+            runs normally; it just produces no trace record.
+
+        max_payload_bytes:
+            Maximum size (in bytes, after JSON serialisation) of any single
+            captured value — an input field, an event result field, or an
+            output field. Values that exceed this are replaced with a
+            "[truncated: N chars]" summary.
+
+        sample_rate:
+            The fraction of successful traces to record. 1.0 means record
+            everything. 0.1 means record approximately 10% of traces. Failed
+            traces (status="failed") are always recorded when always_trace_errors
+            is True, regardless of sample_rate.
+
+            Sampling happens before a trace object is created. If a trace is
+            sampled out, the ContextVar is set to a skip sentinel so that any
+            nested @traced_action calls are also skipped. Nothing is written.
+
+        always_trace_errors:
+            When True (default), failed traces are always recorded even if
+            sample_rate would otherwise drop them. This ensures that errors are
+            never silently lost because of sampling.
+    """
+
+    def __init__(
+        self,
+        max_events: Optional[int] = None,
+        max_steps: Optional[int] = None,
+        max_depth: Optional[int] = None,
+        max_payload_bytes: Optional[int] = None,
+        sample_rate: Optional[float] = None,
+        always_trace_errors: Optional[bool] = None,
+    ) -> None:
+        self.max_events = max_events
+        self.max_steps = max_steps
+        self.max_depth = max_depth
+        self.max_payload_bytes = max_payload_bytes
+        self.sample_rate = sample_rate
+        self.always_trace_errors = always_trace_errors
+
+
+# ---------------------------------------------------------------------------
+# Package-level defaults
+# ---------------------------------------------------------------------------
+#
+# These are the values used when no package config and no trace-level override
+# specifies a budget field. They are intentionally generous so that TraceAct
+# works well in small local tools without any configuration at all.
+
+BUDGET_DEFAULTS = {
+    "max_events": 100,
+    "max_steps": 50,
+    "max_depth": 10,
+    "max_payload_bytes": 8192,
+    "sample_rate": 1.0,
+    "always_trace_errors": True,
+}

traceact/config.py

@@ -0,0 +1,198 @@
+# config.py
+#
+# Defines TraceConfig — the settings object that controls how TraceAct behaves —
+# and the package-level configure() / reset_config() functions.
+#
+# Why a separate config module?
+# Configuration is shared across the whole package. Every trace, decorator, and
+# sink needs to read the same settings. Centralising them here means there is one
+# place to look when a setting needs to change, and one place to reset when a
+# test has left state behind.
+#
+# How config inheritance works:
+# TraceConfig uses None to mean "not specified". A None field means "inherit from
+# the parent trace's config, or fall back to the package default." This allows a
+# single decorator to override only the fields it cares about, rather than
+# replacing the entire config object.
+#
+# The resolution order (lowest to highest priority) is:
+#   Package defaults → package-level configure() → parent trace config → decorator override
+#
+# See trace.py for the _resolve_config() function that applies this ordering.
+
+from typing import Any, List, Optional
+
+
+class TraceConfig:
+    """
+    Controls the behaviour of TraceAct tracing.
+
+    All fields default to None, which means "not specified — use the package
+    default or inherit from the parent trace." Only fields you explicitly set
+    will override the inherited value.
+
+    Fields:
+        enabled:
+            Whether tracing is active. When False, @traced_action decorators
+            run their wrapped function with almost no overhead — no trace is
+            created, no context is touched, no sink is called. This is the
+            global kill switch.
+
+        sink_mode:
+            Controls when traces are written to sinks.
+            "blocking"  — write immediately when a trace finishes. Best for
+                          local development and tests.
+            "buffered"  — accumulate finished traces in memory and flush them
+                          later (or on program exit). Best default for small apps.
+            "disabled"  — never write anything, regardless of sink configuration.
+                          Use as a performance kill switch that still leaves
+                          decorators in place.
+
+        strict:
+            When True, any exception raised inside TraceAct's own tracing logic
+            (not inside the function being traced) will propagate into the
+            application. When False (default), tracing failures are silently
+            swallowed so the app is never broken by its own observability layer.
+
+        redact_by_default:
+            When True, field names that match known sensitive patterns (such as
+            "password", "token", "secret", "api_key") are replaced with the
+            string "[redacted]" before being stored in inputs, events, or outputs.
+            This applies to both automatic input capture and manual trace.event()
+            calls.
+
+        capture_inputs:
+            Controls the automatic input-capture behaviour of @traced_action.
+
+            None / not set  — use the package default, which is False (no capture).
+            False           — disable automatic capture globally. When set at the
+                              package level via configure(), individual decorators
+                              cannot re-enable automatic capture. Manual
+                              trace.input() calls still work.
+            True            — capture all named function arguments automatically,
+                              applying redaction and payload limits.
+            list of strings — capture only the named arguments in the list.
+                              This is the safest opt-in form: you choose exactly
+                              which fields are recorded.
+
+        capture_outputs:
+            When True (default), calls to trace.output() are recorded on the
+            trace. When False, trace.output() is a no-op.
+    """
+
+    def __init__(
+        self,
+        enabled: Optional[bool] = None,
+        sink_mode: Optional[str] = None,
+        strict: Optional[bool] = None,
+        redact_by_default: Optional[bool] = None,
+        capture_inputs: Any = None,
+        capture_outputs: Optional[bool] = None,
+    ) -> None:
+        self.enabled = enabled
+        self.sink_mode = sink_mode
+        self.strict = strict
+        self.redact_by_default = redact_by_default
+        self.capture_inputs = capture_inputs
+        self.capture_outputs = capture_outputs
+
+
+# ---------------------------------------------------------------------------
+# Package-level state
+# ---------------------------------------------------------------------------
+#
+# These three variables hold the current package-wide configuration, budget,
+# and list of sinks. They start as None / empty, which means "use defaults."
+# configure() sets them. reset_config() clears them back to None / empty.
+#
+# Why module-level variables instead of a class?
+# A module is itself a singleton in Python — imported once and cached. Module-
+# level variables are the simplest, most readable way to hold package state
+# without introducing a global object that callers must instantiate.
+
+_package_config: Optional[TraceConfig] = None
+_package_budget: Any = None          # Optional[TraceBudget] — typed as Any to avoid circular import
+_package_sinks: List[Any] = []       # List[Sink]
+
+
+def configure(
+    config: Optional[TraceConfig] = None,
+    budget: Any = None,
+    sinks: Optional[List[Any]] = None,
+) -> None:
+    """
+    Set package-wide defaults for all future traces.
+
+    Call this once at application startup. Settings applied here become the
+    baseline for every trace unless a specific trace or decorator overrides them.
+
+    Args:
+        config:  A TraceConfig instance. Only non-None fields are applied; the
+                 rest keep their current values (or package defaults).
+        budget:  A TraceBudget instance. Only non-None fields are applied.
+        sinks:   A list of sink objects (JsonlSink, ConsoleSink, etc.). Replaces
+                 the current sink list entirely.
+
+    Example:
+        configure(
+            config=TraceConfig(enabled=True, sink_mode="buffered"),
+            budget=TraceBudget(max_events=200),
+            sinks=[JsonlSink("traces.jsonl")],
+        )
+    """
+    global _package_config, _package_budget, _package_sinks
+
+    if config is not None:
+        _package_config = config
+
+    if budget is not None:
+        _package_budget = budget
+
+    if sinks is not None:
+        _package_sinks = list(sinks)
+
+
+def reset_config() -> None:
+    """
+    Restore all package-level state to its initial defaults.
+
+    Use this in test teardown to prevent one test's configure() call from
+    leaking into the next test. reset_config() also clears the active trace
+    ContextVar so no orphaned trace context carries over between tests.
+
+    What it resets:
+        - TraceConfig → package defaults (enabled, buffered, strict=False, etc.)
+        - TraceBudget → package defaults
+        - Sink list   → empty (no sinks)
+        - Active trace ContextVar → None (no active trace)
+
+    What it does NOT reset:
+        - Traces that have already been written to a sink. Those are gone.
+        - Files on disk. JsonlSink output is not deleted.
+    """
+    global _package_config, _package_budget, _package_sinks
+
+    _package_config = None
+    _package_budget = None
+    _package_sinks = []
+
+    # Clear the active trace context so tests start with a clean slate.
+    # The deferred import avoids a circular dependency at module load time
+    # (context.py does not import config.py).
+    from traceact.context import _active_trace
+    _active_trace.set(None)
+
+
+def get_package_config() -> Optional[TraceConfig]:
+    """Return the package-level TraceConfig, or None if not set."""
+    return _package_config
+
+
+def get_package_budget() -> Any:
+    """Return the package-level TraceBudget, or None if not set."""
+    return _package_budget
+
+
+def get_package_sinks() -> List[Any]:
+    """Return the current list of configured sinks."""
+    return _package_sinks

traceact/context.py

@@ -0,0 +1,130 @@
+# context.py
+#
+# Manages the active trace using Python's contextvars.ContextVar.
+#
+# Why ContextVar?
+# Python's contextvars module (introduced in 3.7) provides context-local
+# storage that is automatically isolated across:
+#   - Threads (each thread gets its own copy)
+#   - asyncio Tasks (each task gets its own copy, inherited from its parent)
+#   - Nested function calls (the ContextVar token mechanism allows exact restore)
+#
+# This makes it the right tool for tracking "which trace is currently running"
+# without requiring the developer to pass a trace object through every function
+# call manually.
+#
+# The public API never exposes the ContextVar directly. Developers interact with
+# traces through @traced_action and ActionTrace.start(), not through this module.
+#
+# How the skip sentinel works:
+# When a trace is sampled out (sample_rate < 1.0 decides to skip it), we still
+# set the ContextVar — but we set it to the SKIP sentinel rather than to a real
+# ActionTrace. Any nested @traced_action call checks the ContextVar first: if it
+# sees SKIP, it also skips. This ensures that a sampled-out parent silently
+# suppresses all its children without requiring any coordination between traces.
+#
+# Without the skip sentinel, a sampled-out parent would leave the ContextVar
+# empty, and a nested @traced_action would see "no active parent" and create a
+# new root trace — which would then appear in the sink without its parent, making
+# the output confusing and incomplete.
+
+from contextvars import ContextVar
+from typing import Any, Optional
+
+
+# ---------------------------------------------------------------------------
+# Skip sentinel
+# ---------------------------------------------------------------------------
+#
+# A sentinel is a unique object used as a special signal value. We use a class
+# rather than a string like "SKIP" so that nothing can accidentally match it.
+
+class _SkipSentinel:
+    """
+    Marker placed in the ContextVar when a trace has been sampled out.
+
+    Any code that reads the ContextVar and finds this object should treat the
+    current execution context as "tracing suppressed" and do nothing.
+    """
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "<TraceAct: sampled out>"
+
+
+# The single instance of the skip sentinel. This is what gets stored in the
+# ContextVar when a trace is sampled out.
+SKIP: _SkipSentinel = _SkipSentinel()
+
+
+def is_skip(value: Any) -> bool:
+    """Return True if the given value is the skip sentinel."""
+    return isinstance(value, _SkipSentinel)
+
+
+# ---------------------------------------------------------------------------
+# The ContextVar
+# ---------------------------------------------------------------------------
+#
+# This variable holds one of three things at any point in time:
+#   None          — no active trace (we are outside any traced function)
+#   ActionTrace   — a live trace that @traced_action or ActionTrace.start() created
+#   SKIP          — we are inside a sampled-out trace; everything is suppressed
+#
+# The variable is module-level so it is truly global (one per interpreter), but
+# ContextVar ensures each asyncio Task and each thread sees its own independent
+# value. Two concurrent requests will never interfere with each other's active
+# trace.
+
+_active_trace: ContextVar[Optional[Any]] = ContextVar(
+    "traceact_active_trace",
+    default=None,
+)
+
+
+def get_active_trace() -> Optional[Any]:
+    """
+    Return whatever is currently stored in the active trace ContextVar.
+
+    Returns:
+        None           — no active trace
+        ActionTrace    — the currently running trace
+        SKIP sentinel  — we are inside a sampled-out parent
+    """
+    return _active_trace.get()
+
+
+def push_trace(trace_or_skip: Any) -> Any:
+    """
+    Set a new value as the active trace and return a token for restoring the
+    previous value later.
+
+    Args:
+        trace_or_skip: Either an ActionTrace or the SKIP sentinel.
+
+    Returns:
+        A ContextVar Token. Pass this to pop_trace() when the trace finishes
+        to restore whatever was active before.
+
+    How the token mechanism works:
+        Python's ContextVar.set() returns a Token object that remembers the
+        previous value. Calling ContextVar.reset(token) restores that exact
+        previous value — even if something else has changed the ContextVar in
+        between. This is what makes nested traces work correctly: each level
+        saves its own token and restores independently.
+    """
+    return _active_trace.set(trace_or_skip)
+
+
+def pop_trace(token: Any) -> None:
+    """
+    Restore the active trace to whatever it was before the matching push_trace()
+    call.
+
+    Args:
+        token: The Token returned by the corresponding push_trace() call.
+
+    This should always be called in a finally block so that the context is
+    restored even if the traced function raises an exception.
+    """
+    _active_trace.reset(token)