forgesight-core 0.1.0__py3-none-any.whl

forgesight_core/__init__.py

@@ -0,0 +1,72 @@
+"""ForgeSight runtime — instrumentation scopes, context propagation, dispatch.
+
+Most users import the ``forgesight`` facade rather than this package directly.
+Adapter authors (feat-019) use the context primitives and scopes here.
+"""
+
+from __future__ import annotations
+
+from .adapters import BaseAdapter, ScopeBridge, in_tool_call, tool_call_active
+from .config import register, resolve
+from .context import (
+    TelemetryContext,
+    current_context,
+    new_run_id,
+    new_span_id,
+)
+from .cost import PricingTable, TablePricingProvider
+from .decorator import instrument
+from .exporters import ConsoleExporter, InMemoryExporter
+from .facade import Telemetry, configure, telemetry
+from .interceptors import ContentCaptureGate, PIIRedactionInterceptor
+from .metrics import AttributionMetricsConfig, MetricConfig, MetricsSubsystem
+from .processor import Runtime, RuntimeConfig, get_runtime, reset_runtime
+from .scope import (
+    LLMScope,
+    MCPScope,
+    RunScope,
+    StepScope,
+    ToolScope,
+    WorkflowScope,
+    current_run_scope,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AttributionMetricsConfig",
+    "BaseAdapter",
+    "ConsoleExporter",
+    "ContentCaptureGate",
+    "InMemoryExporter",
+    "LLMScope",
+    "MCPScope",
+    "MetricConfig",
+    "MetricsSubsystem",
+    "PIIRedactionInterceptor",
+    "PricingTable",
+    "RunScope",
+    "Runtime",
+    "RuntimeConfig",
+    "ScopeBridge",
+    "StepScope",
+    "TablePricingProvider",
+    "Telemetry",
+    "TelemetryContext",
+    "ToolScope",
+    "WorkflowScope",
+    "__version__",
+    "configure",
+    "current_context",
+    "current_run_scope",
+    "get_runtime",
+    "in_tool_call",
+    "instrument",
+    "new_run_id",
+    "new_span_id",
+    "register",
+    "reset_runtime",
+    "resolve",
+    "telemetry",
+    "tool_call_active",
+]

forgesight_core/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Adapter base + scope-bridge shared by every framework adapter (feat-019)."""
+
+from __future__ import annotations
+
+from .base import BaseAdapter
+from .bridge import ScopeBridge
+from .guard import in_tool_call, tool_call_active
+
+__all__ = ["BaseAdapter", "ScopeBridge", "in_tool_call", "tool_call_active"]

forgesight_core/adapters/base.py

@@ -0,0 +1,43 @@
+"""``BaseAdapter`` — the idempotent ``instrument`` / ``uninstrument`` bookkeeping.
+
+A concrete adapter subclasses this, sets ``name``, and implements ``_subscribe`` /
+``_unsubscribe`` (the framework-specific hook wiring). The guard here makes double
+``instrument()`` a no-op and ``uninstrument()`` safe to call any time — the lifecycle
+invariants the conformance suite (feat-011) checks. Satisfies the
+:class:`~forgesight_api.FrameworkAdapter` Protocol structurally.
+"""
+
+from __future__ import annotations
+
+
+class BaseAdapter:
+    """Lifecycle bookkeeping for a framework adapter; subclasses do the hook wiring."""
+
+    name: str = "base"
+
+    def __init__(self) -> None:
+        self._instrumented = False
+
+    def instrument(self) -> None:
+        if self._instrumented:
+            return
+        self._subscribe()
+        self._instrumented = True
+
+    def uninstrument(self) -> None:
+        if not self._instrumented:
+            return
+        self._unsubscribe()
+        self._instrumented = False
+
+    def is_instrumented(self) -> bool:
+        return self._instrumented
+
+    # --- subclass hooks ---------------------------------------------------
+    def _subscribe(self) -> None:
+        """Register the framework's native listeners. Override in a concrete adapter."""
+        raise NotImplementedError
+
+    def _unsubscribe(self) -> None:
+        """Unregister the framework's native listeners. Override in a concrete adapter."""
+        raise NotImplementedError

forgesight_core/adapters/bridge.py

@@ -0,0 +1,84 @@
+"""``ScopeBridge`` — translate a framework's start/end callbacks onto SDK scopes.
+
+Frameworks signal work as *start* then *end* callbacks, not ``with`` blocks. This bridge
+opens the matching SDK scope on start and closes it on end, manually driving the scope's
+context-manager protocol so nesting rides the SDK's ``TelemetryContext`` (contextvars) —
+exactly as the runtime intends. Two addressing modes:
+
+* **keyed** — frameworks that give each unit a run id (LangChain's ``run_id``): look the
+  open scope up by key on the end callback.
+* **stacked** — frameworks without ids (the CrewAI event bus): per-kind LIFO, matching the
+  strictly-nested sequential execution order.
+
+The bridge holds no framework types; the adapter constructs the scope and hands it over.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+from typing import Any, Protocol
+
+
+class _ManagedScope(Protocol):
+    def __enter__(self) -> Any: ...
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> Any: ...
+    def record_error(self, exc: BaseException, *, code: str | None = None) -> None: ...
+
+
+class ScopeBridge:
+    """Open/close SDK scopes from start/end callbacks; nests via the runtime's contextvars."""
+
+    def __init__(self) -> None:
+        self._by_key: dict[Hashable, _ManagedScope] = {}
+        self._stacks: dict[str, list[_ManagedScope]] = {}
+
+    # --- keyed (frameworks with run ids) ---------------------------------
+    def enter_keyed(self, key: Hashable, scope: _ManagedScope) -> _ManagedScope:
+        scope.__enter__()
+        self._by_key[key] = scope
+        return scope
+
+    def get_keyed(self, key: Hashable) -> _ManagedScope | None:
+        return self._by_key.get(key)
+
+    def exit_keyed(
+        self, key: Hashable, *, error: BaseException | None = None
+    ) -> _ManagedScope | None:
+        return self._close(self._by_key.pop(key, None), error)
+
+    # --- stacked (frameworks without ids — per-kind LIFO) ----------------
+    def enter_stacked(self, kind: str, scope: _ManagedScope) -> _ManagedScope:
+        scope.__enter__()
+        self._stacks.setdefault(kind, []).append(scope)
+        return scope
+
+    def peek_stacked(self, kind: str) -> _ManagedScope | None:
+        stack = self._stacks.get(kind)
+        return stack[-1] if stack else None
+
+    def exit_stacked(
+        self, kind: str, *, error: BaseException | None = None
+    ) -> _ManagedScope | None:
+        stack = self._stacks.get(kind)
+        scope = stack.pop() if stack else None
+        return self._close(scope, error)
+
+    # --- cleanup ----------------------------------------------------------
+    def close_all(self) -> None:
+        """Close every still-open scope (innermost first) — used on uninstrument."""
+        leftovers = list(self._by_key.values())
+        for stack in self._stacks.values():
+            leftovers.extend(stack)
+        for scope in reversed(leftovers):
+            self._close(scope, None)
+        self._by_key.clear()
+        self._stacks.clear()
+
+    @staticmethod
+    def _close(scope: _ManagedScope | None, error: BaseException | None) -> _ManagedScope | None:
+        if scope is None:
+            return None
+        if error is not None:
+            scope.record_error(error)
+        scope.__exit__(None, None, None)
+        return scope

forgesight_core/adapters/guard.py

@@ -0,0 +1,32 @@
+"""Re-entrancy guard so a framework adapter never double-instruments a tool call.
+
+When an inner span already covers a tool execution — an MCP ``tools/call`` (feat-016) or a
+native ``tool_call`` — a framework adapter observing the *same* call must defer to that span
+instead of opening a second ``execute_tool`` (otel mapping §4.3). The in-flight span marks
+this contextvar; adapters check :func:`in_tool_call` on their tool-start hook and skip.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+_IN_TOOL_CALL: contextvars.ContextVar[bool] = contextvars.ContextVar(
+    "forgesight_in_tool_call", default=False
+)
+
+
+def in_tool_call() -> bool:
+    """True while a tool span is already open on this context (adapters defer to it)."""
+    return _IN_TOOL_CALL.get()
+
+
+@contextmanager
+def tool_call_active() -> Iterator[None]:
+    """Mark a tool span in flight so an adapter observing the same call defers (no double-span)."""
+    token = _IN_TOOL_CALL.set(True)
+    try:
+        yield
+    finally:
+        _IN_TOOL_CALL.reset(token)

forgesight_core/config.py

@@ -0,0 +1,180 @@
+"""Configuration: the named-integration registry + layered file/env loading.
+
+Resolves names (``"console"``, ``"otel"``, ``"langfuse"``, …) to implementations via
+an in-process registry plus the ``forgesight.<group>`` entry points (the plug-and-play
+seam, P2). A name that resolves to nothing raises the matching ``*NotRegisteredError``
+at ``configure()`` — fail-fast, never a silent mid-run drop (architecture §8).
+
+Settings are layered file → env → kwargs (last wins); ``${VAR}`` / ``${VAR:-default}``
+in the YAML file are interpolated from the environment. Implemented with dataclasses +
+manual validation (no Pydantic) to keep the core dependency-light (P1).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from collections.abc import Callable, Mapping
+from importlib import metadata
+from typing import Any
+
+import yaml
+
+from forgesight_api import (
+    EventListenerNotRegisteredError,
+    ExporterNotRegisteredError,
+    InterceptorNotRegisteredError,
+    PricingProviderNotRegisteredError,
+)
+
+from .cost import TablePricingProvider
+from .exporters import ConsoleExporter, InMemoryExporter
+from .interceptors import ContentCaptureGate, PIIRedactionInterceptor
+
+_log = logging.getLogger("forgesight.config")
+
+_ERRORS: dict[str, type[LookupError]] = {
+    "exporters": ExporterNotRegisteredError,
+    "interceptors": InterceptorNotRegisteredError,
+    "listeners": EventListenerNotRegisteredError,
+    "pricing": PricingProviderNotRegisteredError,
+}
+_REGISTRY: dict[str, dict[str, Callable[..., Any]]] = {group: {} for group in _ERRORS}
+# Adapters resolve like the other groups but never fail-fast — a missing framework warns
+# and is skipped (feat-019), so "adapters" has a registry slot but no entry in _ERRORS.
+_REGISTRY["adapters"] = {}
+
+# Built-in implementations resolve by name with no privileged path.
+_REGISTRY["exporters"]["console"] = ConsoleExporter
+_REGISTRY["exporters"]["in-memory"] = InMemoryExporter
+_REGISTRY["interceptors"]["content-gate"] = ContentCaptureGate
+_REGISTRY["interceptors"]["pii-redaction"] = PIIRedactionInterceptor
+_REGISTRY["pricing"]["default"] = TablePricingProvider.from_vendored
+
+_ENV_PATTERN = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}")
+
+
+def register(group: str, name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator: register an in-process factory under a group, resolvable by name."""
+    if group not in _REGISTRY:
+        raise ValueError(f"unknown registration group {group!r}; expected one of {list(_ERRORS)}")
+
+    def decorator(factory: Callable[..., Any]) -> Callable[..., Any]:
+        _REGISTRY[group][name] = factory
+        return factory
+
+    return decorator
+
+
+def resolve(group: str, name: str, config: Mapping[str, object] | None = None) -> object:
+    """Resolve ``name`` in ``group`` to an instance, or raise the group's error."""
+    factory = _REGISTRY[group].get(name) or _load_entry_point(group, name)
+    if factory is None:
+        raise _ERRORS[group](
+            f"No {group[:-1]} registered under name {name!r}. Expected an entry point in "
+            f"group 'forgesight.{group}' (did you `pip install` the integration package?)."
+        )
+    return factory(**dict(config)) if config else factory()
+
+
+def _load_entry_point(group: str, name: str) -> Callable[..., Any] | None:
+    try:
+        entry_points = metadata.entry_points(group=f"forgesight.{group}")
+    except Exception:  # pragma: no cover - importlib metadata edge
+        return None
+    for entry_point in entry_points:
+        if entry_point.name == name:
+            loaded: Callable[..., Any] = entry_point.load()
+            return loaded
+    return None
+
+
+def load_adapters(settings: Mapping[str, Any]) -> list[Any]:
+    """Instantiate + instrument the adapters named in the ``adapters:`` config block (feat-019).
+
+    Driven by explicit config (not "instrument every installed adapter") so the SDK's own
+    process is never silently auto-instrumented. A named adapter resolves via the in-process
+    registry or the ``forgesight.adapters`` entry point; one whose framework isn't importable
+    warns and is skipped — never raises (P6). With ``auto_instrument: false`` the adapters are
+    created but left inert for the app to ``instrument()`` itself.
+    """
+    block = settings.get("adapters")
+    if not isinstance(block, Mapping):
+        return []
+    auto_instrument = bool(block.get("auto_instrument", True))
+    adapters: list[Any] = []
+    for name, opts in block.items():
+        if name == "auto_instrument":
+            continue
+        if isinstance(opts, Mapping) and not opts.get("enabled", True):
+            continue
+        factory = _REGISTRY["adapters"].get(name) or _load_entry_point("adapters", name)
+        if factory is None:
+            _log.warning("adapter %r is enabled but not installed; skipping", name)
+            continue
+        try:
+            adapter = factory()
+            if auto_instrument:
+                adapter.instrument()
+        except Exception:  # a framework that won't import must never fail configure() (P6)
+            _log.warning("adapter %r failed to load/instrument; skipping", name, exc_info=True)
+            continue
+        adapters.append(adapter)
+    return adapters
+
+
+def interpolate(value: object, env: Mapping[str, str]) -> object:
+    """Substitute ``${VAR}`` / ``${VAR:-default}`` in strings, recursing into dicts/lists."""
+    if isinstance(value, str):
+        return _ENV_PATTERN.sub(lambda m: _sub(m, env), value)
+    if isinstance(value, dict):
+        return {k: interpolate(v, env) for k, v in value.items()}
+    if isinstance(value, list):
+        return [interpolate(v, env) for v in value]
+    return value
+
+
+def _sub(match: re.Match[str], env: Mapping[str, str]) -> str:
+    var, default = match.group(1), match.group(2)
+    if var in env:
+        return env[var]
+    if default is not None:
+        return default
+    raise ValueError(f"config references ${{{var}}} which is not set and has no default")
+
+
+def load_settings(
+    config_file: str | None = None, env: Mapping[str, str] | None = None
+) -> dict[str, Any]:
+    """Load the file layer (YAML + ``${ENV}``) then overlay ``FORGESIGHT_*`` env scalars."""
+    env = os.environ if env is None else env
+    settings: dict[str, Any] = {}
+    path = config_file or env.get("FORGESIGHT_CONFIG")
+    if path is None and os.path.exists("forgesight.yaml"):
+        path = "forgesight.yaml"
+    if path and os.path.exists(path):
+        with open(path, encoding="utf-8") as handle:
+            raw = yaml.safe_load(handle) or {}
+        loaded = interpolate(raw, env)
+        if isinstance(loaded, dict):
+            settings.update(loaded)
+    _env_overlay(settings, env)
+    return settings
+
+
+def _env_overlay(settings: dict[str, Any], env: Mapping[str, str]) -> None:
+    if "FORGESIGHT_SERVICE_NAME" in env:
+        settings["service_name"] = env["FORGESIGHT_SERVICE_NAME"]
+    if "FORGESIGHT_EXPORTERS" in env:
+        settings["exporters"] = [
+            s.strip() for s in env["FORGESIGHT_EXPORTERS"].split(",") if s.strip()
+        ]
+    if "FORGESIGHT_CAPTURE_CONTENT" in env:
+        settings["capture_content"] = _as_bool(env["FORGESIGHT_CAPTURE_CONTENT"])
+    if "FORGESIGHT_SAMPLE_RATE" in env:
+        settings["sample_rate"] = float(env["FORGESIGHT_SAMPLE_RATE"])
+
+
+def _as_bool(value: str) -> bool:
+    return value.strip().lower() in ("1", "true", "yes", "on")

forgesight_core/context.py

@@ -0,0 +1,75 @@
+"""Per-run ambient state, propagated via ``contextvars``.
+
+A :class:`TelemetryContext` carries the ids and accumulated run/step-scope metadata
+for the active run. It rides on a :class:`~contextvars.ContextVar`, so it survives
+``await`` boundaries and is *copied* into ``asyncio.gather`` / ``create_task``
+children — which is what makes concurrent leaf calls attach to the right parent
+without racing each other's ``current_span_id`` (P9, feat-002 §4.3).
+"""
+
+from __future__ import annotations
+
+import contextvars
+import os
+from dataclasses import dataclass, field
+
+from forgesight_api import new_ulid
+
+_SPAN_ID_BYTES = 8  # OTel span id is 8 bytes / 16 hex chars
+
+
+@dataclass(slots=True)
+class TelemetryContext:
+    """Ambient state for the active run. Read by every scope on enter."""
+
+    run_id: str
+    trace_id: str
+    parent_run_id: str | None = None
+    current_span_id: str | None = None  # the parent span for the next child opened
+    context_id: str | None = None
+    metadata: dict[str, object] = field(default_factory=dict)
+
+    def child(self, *, current_span_id: str) -> TelemetryContext:
+        """A copy with a new ``current_span_id`` and a *copied* metadata dict.
+
+        Used when entering a nested scope so a sibling scope's metadata writes never
+        leak across, while inherited run-scope metadata is preserved.
+        """
+        return TelemetryContext(
+            run_id=self.run_id,
+            trace_id=self.trace_id,
+            parent_run_id=self.parent_run_id,
+            current_span_id=current_span_id,
+            context_id=self.context_id,
+            metadata=dict(self.metadata),
+        )
+
+
+_CURRENT: contextvars.ContextVar[TelemetryContext | None] = contextvars.ContextVar(
+    "forgesight_current_context", default=None
+)
+
+
+def current_context() -> TelemetryContext | None:
+    """Return the active :class:`TelemetryContext`, or ``None`` outside any run."""
+    return _CURRENT.get()
+
+
+def set_current_context(ctx: TelemetryContext | None) -> contextvars.Token[TelemetryContext | None]:
+    """Bind ``ctx`` as the active context; returns a token to restore the previous one."""
+    return _CURRENT.set(ctx)
+
+
+def reset_current_context(token: contextvars.Token[TelemetryContext | None]) -> None:
+    """Restore the context that was active before the matching :func:`set_current_context`."""
+    _CURRENT.reset(token)
+
+
+def new_run_id() -> str:
+    """Mint a ULID run id — the single place run ids are created (feat-001 format)."""
+    return new_ulid()
+
+
+def new_span_id() -> str:
+    """Mint a 16-hex-char (8-byte) span id."""
+    return os.urandom(_SPAN_ID_BYTES).hex()

forgesight_core/cost/__init__.py

@@ -0,0 +1,7 @@
+"""ForgeSight cost model — token → USD via a vendored, refreshable pricing table."""
+
+from __future__ import annotations
+
+from .table import ModelRates, PricingTable, TablePricingProvider
+
+__all__ = ["ModelRates", "PricingTable", "TablePricingProvider"]

forgesight_core/cost/data/prices.json

@@ -0,0 +1,66 @@
+{
+  "updated_at": "2026-06-14T00:00:00Z",
+  "models": {
+    "anthropic/claude-sonnet-4-5": {
+      "provider": "anthropic",
+      "input_cost_per_token": 3e-06,
+      "output_cost_per_token": 1.5e-05,
+      "cache_read_input_token_cost": 3e-07,
+      "cache_creation_input_token_cost": 3.75e-06,
+      "tiers": [
+        {
+          "name": "above-200k",
+          "priority": 1,
+          "when": { "input_tokens": { "gt": 200000 } },
+          "input_cost_per_token": 6e-06,
+          "output_cost_per_token": 2.25e-05
+        }
+      ]
+    },
+    "anthropic/claude-opus-4-1": {
+      "provider": "anthropic",
+      "input_cost_per_token": 1.5e-05,
+      "output_cost_per_token": 7.5e-05,
+      "cache_read_input_token_cost": 1.5e-06,
+      "cache_creation_input_token_cost": 1.875e-05
+    },
+    "anthropic/claude-haiku-4-5": {
+      "provider": "anthropic",
+      "input_cost_per_token": 1e-06,
+      "output_cost_per_token": 5e-06,
+      "cache_read_input_token_cost": 1e-07,
+      "cache_creation_input_token_cost": 1.25e-06
+    },
+    "openai/gpt-4o": {
+      "provider": "openai",
+      "input_cost_per_token": 2.5e-06,
+      "output_cost_per_token": 1e-05,
+      "cache_read_input_token_cost": 1.25e-06
+    },
+    "openai/gpt-4o-mini": {
+      "provider": "openai",
+      "input_cost_per_token": 1.5e-07,
+      "output_cost_per_token": 6e-07,
+      "cache_read_input_token_cost": 7.5e-08
+    },
+    "google/gemini-2.5-pro": {
+      "provider": "google",
+      "input_cost_per_token": 1.25e-06,
+      "output_cost_per_token": 1e-05,
+      "tiers": [
+        {
+          "name": "above-200k",
+          "priority": 1,
+          "when": { "input_tokens": { "gt": 200000 } },
+          "input_cost_per_token": 2.5e-06,
+          "output_cost_per_token": 1.5e-05
+        }
+      ]
+    }
+  },
+  "aliases": {
+    "claude-sonnet-4-5-latest": "anthropic/claude-sonnet-4-5",
+    "claude-sonnet-4-5": "anthropic/claude-sonnet-4-5",
+    "gpt-4o": "openai/gpt-4o"
+  }
+}