runtime-labs-sdk 0.1.0__py3-none-any.whl

runtime_labs/__init__.py

@@ -0,0 +1,6 @@
+"""Runtime Labs local Python SDK. Call init before constructing clients or graphs."""
+
+from .propagation import continue_trace, inject_context
+from .sdk import SDK, init
+
+__all__ = ["SDK", "continue_trace", "init", "inject_context"]

runtime_labs/binding.py

@@ -0,0 +1,204 @@
+"""Conservative, immutable source indexes. This module never imports application code."""
+
+import dis
+import hashlib
+import marshal
+import sys
+import warnings
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from threading import RLock
+from types import CodeType, MappingProxyType
+
+from deployment_contracts import DeploymentManifest
+
+
+@dataclass(frozen=True)
+class Entity:
+    node_id: str
+    kind: str
+    qualified_symbol: str
+    path: str
+    source_digest: str
+    start: tuple[int, int]
+    end: tuple[int, int]
+    provider: str | None
+    operation: str | None
+
+
+def normalized_code(code):
+    """Keep constants, closures, flags and positions; only checkout filenames differ."""
+    return code.replace(
+        co_filename="<verified-source>",
+        co_consts=tuple(normalized_code(c) if isinstance(c, CodeType) else c
+                        for c in code.co_consts),
+    )
+
+
+def fingerprint(code):
+    return hashlib.sha256(marshal.dumps(normalized_code(code))).digest()
+
+
+def codes(code):
+    yield code
+    for constant in code.co_consts:
+        if isinstance(constant, CodeType):
+            yield from codes(constant)
+
+
+def call_position(frame):
+    # Include inline CACHE instructions: suspended sync calls and async SEND/RESUME
+    # positions then retain the exact UTF-8 byte range, even for same-line calls.
+    instructions = [i for i in dis.get_instructions(frame.f_code, show_caches=True)
+                    if i.offset <= frame.f_lasti]
+    instruction = next((i for i in reversed(instructions) if i.opname in {
+        "CALL", "CALL_KW", "CALL_FUNCTION_EX",
+    }), None)
+    p = instruction.positions if instruction else None
+    if p and None not in (p.lineno, p.col_offset, p.end_lineno, p.end_col_offset):
+        return (p.lineno, p.col_offset), (p.end_lineno, p.end_col_offset)
+    return None
+
+
+class SourceIndex:
+    def __init__(self, path, diagnose, *, manifest=None):
+        self._diagnose = diagnose
+        self._lock = RLock()
+        self._compiled = {}  # Bounded by files from the manifest, not request count.
+        self._json = None
+        entities = ()
+        if path is None and manifest is None:
+            diagnose("manifest_missing")
+        else:
+            try:
+                manifest = (DeploymentManifest.model_validate(manifest.model_dump())
+                            if manifest is not None else
+                            DeploymentManifest.model_validate_json(path.read_bytes()))
+                self._json = manifest.model_dump_json()
+                entities = tuple(Entity(
+                    e.node_id, e.kind, e.qualified_symbol, e.source.path, e.source.source_digest,
+                    (e.source.location.start_line, e.source.location.start_col),
+                    (e.source.location.end_line, e.source.location.end_col),
+                    e.provider, e.operation,
+                ) for e in manifest.entities)
+            except Exception:
+                diagnose("manifest_invalid")
+        self.entities = entities
+        grouped = {}
+        for entity in entities:
+            key = (entity.kind, entity.qualified_symbol)
+            grouped.setdefault(key, []).append(entity)
+        self.by_symbol = MappingProxyType({key: tuple(value) for key, value in grouped.items()})
+        self.node_ids = frozenset(e.node_id for e in entities)
+
+    @property
+    def manifest(self):
+        """A detached validated copy; changes cannot affect the attribution index."""
+        return DeploymentManifest.model_validate_json(self._json) if self._json else None
+
+    def candidates(self, code, globals_, kind):
+        module = globals_.get("__name__", "")
+        qualname = code.co_qualname.replace(".<locals>.", ".")
+        suffix = "" if qualname == "<module>" else "." + qualname
+        if module == "__main__":
+            spec_name = getattr(globals_.get("__spec__"), "name", None)
+            if spec_name and spec_name != "__main__":
+                module = spec_name
+            else:
+                # A directly executed script has no import name. Derive it only
+                # from complete canonical paths in this manifest, then prove the
+                # actual path/digest/code below. Never search by basename.
+                return tuple(e for e in self.entities if e.kind == kind
+                             and e.qualified_symbol == ".".join(
+                                 PurePosixPath(e.path).with_suffix("").parts
+                             ).removesuffix(".__init__") + suffix)
+        return self.by_symbol.get((kind, module + suffix), ())
+
+    def _proof(self, code, globals_, entity):
+        actual = Path(code.co_filename).resolve()
+        module_file = globals_.get("__file__")
+        relative = PurePosixPath(entity.path)
+        # Both module identity and every manifest path component must agree. No
+        # basename search, checkout paths from scanner metadata, or sys.path guessing.
+        if (not module_file or actual != Path(module_file).resolve()
+                or actual.parts[-len(relative.parts):] != relative.parts):
+            self._diagnose("source_path_mismatch")
+            return False
+        try:
+            raw = actual.read_bytes()
+            if hashlib.sha256(raw).hexdigest() != entity.source_digest:
+                self._diagnose("source_digest_mismatch")
+                return False
+            with self._lock:
+                expected = self._compiled.get(entity.source_digest)
+                if expected is None:
+                    # compile, never exec: compare loaded code to the verified bytes.
+                    # Compiler warnings can echo source lines. Verification must
+                    # never print source bodies or alter application warnings.
+                    with warnings.catch_warnings(record=True):
+                        warnings.simplefilter("ignore")
+                        tree = compile(raw, str(actual), "exec", dont_inherit=True,
+                                       optimize=sys.flags.optimize)
+                    expected = frozenset(fingerprint(c) for c in codes(tree))
+                    self._compiled[entity.source_digest] = expected
+            if fingerprint(code) not in expected:
+                self._diagnose("loaded_code_mismatch")
+                return False
+            return True
+        except Exception:
+            self._diagnose("source_unavailable")
+            return False
+
+    def match(self, code, globals_, kind, position=None):
+        candidates = self.candidates(code, globals_, kind)
+        if kind == "ModelCallSite":
+            candidates = tuple(e for e in candidates if position == (e.start, e.end))
+        elif kind == "Workflow":
+            candidates = tuple(e for e in candidates if position is not None
+                               and e.start <= position[0] < position[1] <= e.end)
+        else:
+            # Functions can have decorators before the def range.
+            candidates = tuple(e for e in candidates if e.start[0] <= code.co_firstlineno
+                               <= e.end[0])
+        if len(candidates) != 1:
+            if self.entities:
+                self._diagnose("source_ambiguous" if candidates else "source_unmatched")
+            return None
+        entity = candidates[0]
+        return entity if self._proof(code, globals_, entity) else None
+
+    def frame(self, frame, kind):
+        if frame is None:
+            return None
+        return self.match(frame.f_code, frame.f_globals, kind, call_position(frame))
+
+    def call_site(self, frame, depth=32):
+        """The model call a provider request belongs to.
+
+        That is the innermost frame whose current call is a verified call site. A
+        wrapper that forwards its caller's prompt is not one, so the walk continues
+        to the caller that built it. Frames outside the manifest are skipped quietly;
+        only a request no frame accounts for is diagnosed.
+        """
+        current = frame
+        while current is not None and depth:
+            position = call_position(current)
+            candidates = tuple(
+                e for e in self.candidates(current.f_code, current.f_globals, "ModelCallSite")
+                if position == (e.start, e.end)
+            )
+            if len(candidates) > 1:
+                self._diagnose("source_ambiguous")
+                return None
+            if candidates:
+                entity = candidates[0]
+                return entity if self._proof(current.f_code, current.f_globals, entity) else None
+            current, depth = current.f_back, depth - 1
+        if frame is not None and self.entities:
+            self._diagnose("source_unmatched")
+        return None
+
+    def function(self, function, kind):
+        if not hasattr(function, "__code__"):
+            return None
+        return self.match(function.__code__, function.__globals__, kind)

runtime_labs/bootstrap.py

@@ -0,0 +1,60 @@
+"""Fetch a validated manifest at initialization; never persist credentials or remote data."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import httpx
+from deployment_contracts import DeploymentManifest
+from repository_identity import git_identity, normalize_git_url
+
+
+@dataclass(frozen=True)
+class RuntimeManifest:
+    manifest: DeploymentManifest
+    ingestion_url: str
+
+
+def _request_manifest(api_url, api_key, git_url, commit_sha):
+    with httpx.Client(timeout=5, follow_redirects=False, trust_env=False) as client:
+        response = client.post(
+            api_url.rstrip("/") + "/api/sdk/manifest",
+            json={"git_url": git_url, "commit_sha": commit_sha},
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+        response.raise_for_status()
+        return response.json()
+
+
+def fetch_runtime_manifest(config, diagnose):
+    try:
+        remote, commit = git_identity(Path.cwd())
+    except Exception:
+        diagnose("repository_identity_unavailable")
+        return None
+    try:
+        body = _request_manifest(config.api_url, config.api_key, remote, commit)
+        if normalize_git_url(body["git_url"]) != remote:
+            raise ValueError("Repository identity mismatch")
+        manifest = DeploymentManifest.model_validate(body["manifest"])
+        if commit and len(manifest.commit_sha) == 40 and manifest.commit_sha != commit:
+            diagnose("manifest_revision_mismatch")
+            return None
+        # The API returns a relative ingestion route, never an arbitrary credential destination.
+        path = body["ingestion_path"]
+        if (
+            not isinstance(path, str)
+            or not path.startswith("/api/repositories/")
+            or ":" in path
+            or "?" in path
+            or "#" in path
+            or ".." in path
+        ):
+            raise ValueError("Invalid ingestion path")
+        base = config.api_url.rstrip("/")
+        if urlsplit(base).scheme not in {"http", "https"}:
+            raise ValueError("Invalid API URL")
+        return RuntimeManifest(manifest, base + path)
+    except Exception:
+        diagnose("manifest_fetch_failed")
+        return None

runtime_labs/config.py

@@ -0,0 +1,42 @@
+"""Read runtime API settings and explicit offline overrides without environment mutation."""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from dotenv import dotenv_values
+
+from .correlation import allowlist
+
+
+@dataclass(frozen=True)
+class Configuration:
+    api_key: str = field(repr=False)
+    manifest_path: Path | None
+    capture_payloads: bool = True
+    api_url: str = "http://127.0.0.1:8000"
+    correlation_keys: tuple = field(default_factory=allowlist)
+
+
+def configuration(api_key: str, capture_payloads: bool = True, api_url: str | None = None,
+                  correlation_keys=None) -> Configuration:
+    cwd = Path.cwd()
+    env_file = next((p / ".env" for p in (cwd, *cwd.parents) if (p / ".env").is_file()), None)
+    # No interpolation: do not resolve or copy unrelated application/scanner secrets.
+    value = os.environ.get("RUNTIME_LABS_MANIFEST_PATH")
+    base = cwd
+    if value is None and env_file is not None:
+        value = dotenv_values(env_file, interpolate=False).get("RUNTIME_LABS_MANIFEST_PATH")
+        base = env_file.parent
+    path = Path(value).expanduser() if value else None
+    if path is not None:
+        path = (base / path).resolve()
+    settings = dotenv_values(env_file, interpolate=False) if env_file else {}
+    endpoint = api_url or os.environ.get("RUNTIME_LABS_API_URL") or settings.get("RUNTIME_LABS_API_URL") or "http://127.0.0.1:8000"
+    keys = allowlist(
+        correlation_keys,
+        os.environ.get("RUNTIME_LABS_CORRELATION_KEYS")
+        or settings.get("RUNTIME_LABS_CORRELATION_KEYS")
+        or "",
+    )
+    return Configuration(api_key, path, capture_payloads, endpoint.rstrip("/"), keys)

runtime_labs/correlation.py

@@ -0,0 +1,64 @@
+"""Record framework correlation identifiers verbatim; meaning is assigned downstream.
+
+The SDK never decides what an identifier is (a conversation, a session, a run).
+Each framework adapter says where that framework keeps run-scoped identifiers, and
+only allowlisted keys are copied, because applications often keep user IDs and
+secrets in the same configuration. Values become span attributes named
+``runtime_labs.ctx.<framework>.<key>``; Runtime Labs pipelines normalize them.
+
+Extend the allowlist without code: ``RUNTIME_LABS_CORRELATION_KEYS=langgraph.tenant,
+langgraph.session`` or ``init(correlation_keys={"langgraph": ["tenant"]})``.
+"""
+
+import os
+from collections.abc import Iterable, Mapping
+from uuid import UUID
+
+PREFIX = "runtime_labs.ctx."
+MAX_VALUE_LENGTH = 256
+DEFAULT_KEYS = {
+    # LangGraph keeps conversation and checkpoint identity in config["configurable"];
+    # run_id is a top-level RunnableConfig key.
+    "langgraph": ("thread_id", "checkpoint_id", "checkpoint_ns", "run_id"),
+}
+
+
+def allowlist(extra: Mapping[str, Iterable[str]] | None = None, environment=None):
+    """Frozen ``((framework, (keys...)), ...)`` so configurations stay comparable."""
+    merged = {framework: set(keys) for framework, keys in DEFAULT_KEYS.items()}
+    for framework, keys in (extra or {}).items():
+        merged.setdefault(framework, set()).update(keys)
+    for item in (environment if environment is not None else _environment()).split(","):
+        framework, _, key = item.strip().partition(".")
+        if framework and key:
+            merged.setdefault(framework, set()).add(key)
+    return tuple(sorted((framework, tuple(sorted(keys))) for framework, keys in merged.items()))
+
+
+def _environment():
+    return os.environ.get("RUNTIME_LABS_CORRELATION_KEYS", "")
+
+
+def capture(framework: str, values: Mapping, allowed) -> dict[str, str]:
+    """Copy allowlisted scalar identifiers; anything else is ignored, never stringified."""
+    keys = dict(allowed).get(framework, ())
+    attributes = {}
+    for key in keys:
+        value = values.get(key)
+        if isinstance(value, bool) or value is None:
+            continue
+        if isinstance(value, (str, int, UUID)):
+            text = str(value)
+            if text:
+                attributes[f"{PREFIX}{framework}.{key}"] = text[:MAX_VALUE_LENGTH]
+    return attributes
+
+
+def langgraph(config, allowed) -> dict[str, str]:
+    if not isinstance(config, Mapping):
+        return {}
+    configurable = config.get("configurable")
+    values = dict(configurable) if isinstance(configurable, Mapping) else {}
+    if "run_id" in config:
+        values["run_id"] = config["run_id"]
+    return capture("langgraph", values, allowed)

runtime_labs/export.py

@@ -0,0 +1,109 @@
+"""Standard OTel exporters for local tracing and eval payloads."""
+
+import json
+import sys
+from threading import RLock
+
+from opentelemetry.sdk.trace import SpanProcessor
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor, SpanExporter, SpanExportResult
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+SCOPE = "runtime_labs"
+
+
+class LocalExporter(SpanExporter):
+    """One JSON object per finished SDK span; no resource/environment dump."""
+
+    def __init__(self, stream=None):
+        self.stream = stream if stream is not None else sys.stdout
+        self._lock = RLock()
+
+    def export(self, spans):
+        with self._lock:
+            for span in spans:
+                value = {
+                    "name": span.name,
+                    "trace_id": format(span.context.trace_id, "032x"),
+                    "span_id": format(span.context.span_id, "016x"),
+                    "parent_span_id": format(span.parent.span_id, "016x") if span.parent else None,
+                    "attributes": dict(span.attributes or {}),
+                    "status": span.status.status_code.name,
+                    "start_time_ns": span.start_time,
+                    "end_time_ns": span.end_time,
+                    "duration_ns": span.end_time - span.start_time,
+                }
+                self.stream.write(json.dumps(value) + "\n")
+            self.stream.flush()
+        return SpanExportResult.SUCCESS
+
+    def shutdown(self):
+        pass
+
+    def force_flush(self, timeout_millis=30000):
+        self.stream.flush()
+        return True
+
+
+class GuardedExporter(SpanExporter):
+    def __init__(self, exporter, diagnose):
+        self.exporter = exporter
+        self.diagnose = diagnose
+
+    def export(self, spans):
+        try:
+            result = self.exporter.export(spans)
+            if result != SpanExportResult.SUCCESS:
+                self.diagnose("export_failed")
+            return result
+        except Exception:
+            self.diagnose("export_failed")
+            return SpanExportResult.FAILURE
+
+    def force_flush(self, timeout_millis=30000):
+        try:
+            return self.exporter.force_flush(timeout_millis=timeout_millis)
+        except Exception:
+            self.diagnose("export_flush_failed")
+            return False
+
+    def shutdown(self):
+        try:
+            self.exporter.shutdown()
+        except Exception:
+            self.diagnose("export_shutdown_failed")
+
+
+class ScopedProcessor(SpanProcessor):
+    """Reusable attachment on application providers; never exports their other scopes."""
+
+    def __init__(self):
+        self.delegate = None
+        self.exporter = None
+        self._lock = RLock()
+
+    def configure(self, exporter, diagnose):
+        with self._lock:
+            self.exporter = GuardedExporter(exporter, diagnose)
+            self.delegate = SimpleSpanProcessor(self.exporter)
+
+    def on_start(self, span, parent_context=None):
+        pass
+
+    def on_end(self, span):
+        with self._lock:
+            if self.delegate and span.instrumentation_scope.name == SCOPE:
+                self.delegate.on_end(span)
+
+    def force_flush(self, timeout_millis=30000):
+        with self._lock:
+            return self.exporter.force_flush(timeout_millis) if self.exporter else True
+
+    def shutdown(self):
+        with self._lock:
+            delegate, self.delegate = self.delegate, None
+            self.exporter = None
+            if delegate:
+                delegate.shutdown()
+
+
+__all__ = ["InMemorySpanExporter", "LocalExporter"]