contexta 0.1.1__py3-none-any.whl

contexta/__init__.py

@@ -0,0 +1,6 @@
+"""Public root package for Contexta."""
+
+from .api import Contexta, __version__
+from .common.errors import ContextaError
+
+__all__ = ["Contexta", "ContextaError", "__version__"]

contexta/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for python -m contexta."""
+
+import sys
+
+from contexta.surfaces.cli.main import main
+
+sys.exit(main())

contexta/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Internal optional adapter namespace for Contexta.
+
+This package is the home for optional integrations that are not required for
+the base local-first runtime path.
+
+Built-in lightweight adapters (no external vendor dependencies):
+- ``export``   — CSV export helpers (stdlib only)
+- ``html``     — HTML rendering helpers (stdlib only)
+- ``notebook`` — Notebook display surface (IPython optional, degrades cleanly)
+- ``dataframes`` — pandas/polars metadata query adapters (optional deps)
+
+Vendor-gated adapters (raise DependencyError when deps are absent):
+- ``otel``   — OpenTelemetry bridge (requires opentelemetry-api extra)
+- ``mlflow`` — MLflow bridge (requires mlflow extra)
+"""
+
+__all__ = ["dataframes", "export", "html", "mlflow", "notebook", "otel"]

contexta/adapters/dataframes/__init__.py

@@ -0,0 +1,9 @@
+"""Optional dataframe adapter namespace for Contexta.
+
+The current dataframe hooks are backed by metadata inspection adapters and are
+re-exported here so future adapter-owned code can converge on this namespace.
+"""
+
+from ...store.metadata.adapters.frame import FrameAdapterProtocol, PandasAdapter, PolarsAdapter
+
+__all__ = ["FrameAdapterProtocol", "PandasAdapter", "PolarsAdapter"]

contexta/adapters/export/__init__.py

@@ -0,0 +1,21 @@
+"""Built-in export adapter namespace for Contexta.
+
+Provides lightweight CSV export helpers that require only stdlib (csv, io).
+These are the canonical import home for export-oriented integrations.
+
+    from contexta.adapters.export import export_run_list_csv, export_trend_csv
+"""
+
+from ...surfaces.export import (
+    export_anomaly_csv,
+    export_comparison_csv,
+    export_run_list_csv,
+    export_trend_csv,
+)
+
+__all__ = [
+    "export_anomaly_csv",
+    "export_comparison_csv",
+    "export_run_list_csv",
+    "export_trend_csv",
+]

contexta/adapters/html/__init__.py

@@ -0,0 +1,29 @@
+"""Built-in HTML adapter namespace for Contexta.
+
+Re-exports the HTML delivery surface for embedding run data in web UIs,
+static reports, or custom dashboards. Requires only stdlib (html, string).
+
+    from contexta.adapters.html import render_html_run_detail, render_html_trend
+"""
+
+from ...surfaces.html import (
+    DashboardConfig,
+    render_html_comparison,
+    render_html_dashboard,
+    render_html_run_detail,
+    render_html_run_list,
+    render_html_trend,
+    render_line_chart,
+    render_status_bar,
+)
+
+__all__ = [
+    "DashboardConfig",
+    "render_html_comparison",
+    "render_html_dashboard",
+    "render_html_run_detail",
+    "render_html_run_list",
+    "render_html_trend",
+    "render_line_chart",
+    "render_status_bar",
+]

contexta/adapters/mlflow/__init__.py

@@ -0,0 +1,12 @@
+"""Optional MLflow adapter namespace for Contexta.
+
+MLflow bridge code should enter through this package and remain outside the
+base runtime dependency path.
+
+Raises ``DependencyError`` at construction time when ``mlflow``
+is not installed. Install it with: pip install 'contexta[mlflow]'
+"""
+
+from ._sink import MLflowSink
+
+__all__ = ["MLflowSink"]

contexta/adapters/mlflow/_sink.py

@@ -0,0 +1,179 @@
+"""MLflow bridge sink — exports Contexta capture payloads to MLflow Tracking."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ...capture.sinks.protocol import BaseSink, SinkCaptureReceipt
+from ...capture.results import PayloadFamily
+from ...common.errors import DependencyError
+
+if TYPE_CHECKING:
+    from ...contract import (
+        DegradedRecord,
+        MetricRecord,
+        StructuredEventRecord,
+    )
+
+_MLFLOW_TAG_MAX_LEN = 5000
+
+
+def _load_mlflow():
+    """Lazy import of mlflow — raises DependencyError if absent."""
+    try:
+        import mlflow
+        return mlflow
+    except ImportError as exc:
+        raise DependencyError(
+            "mlflow is required for MLflowSink. "
+            "Install it with: pip install 'contexta[mlflow]'",
+            code="mlflow_not_ready",
+            cause=exc,
+        ) from exc
+
+
+class MLflowSink(BaseSink):
+    """Export Contexta capture payloads to the MLflow Tracking API.
+
+    Implements the ``Sink`` protocol so it can be passed directly to
+    ``Contexta(sinks=[MLflowSink(...)])``.
+
+    Raises ``DependencyError`` on construction when ``mlflow``
+    is not installed.
+
+    Thread safety: tag-write cache is not thread-safe.
+    Use one instance per thread or protect externally.
+    """
+
+    def __init__(
+        self,
+        *,
+        run_id: str | None = None,
+        name: str = "mlflow",
+    ) -> None:
+        super().__init__(
+            name=name,
+            supported_families=(PayloadFamily.RECORD,),
+        )
+        # Eager import check — fail loudly on construction, not on first capture.
+        _load_mlflow()
+
+        self._run_id = run_id
+        # Track which tags have already been written to avoid write amplification.
+        # Keyed by the full tag key string.
+        self._written_tags: set[str] = set()
+        # Track whether the global run_ref tag has been set.
+        self._run_ref_written: bool = False
+
+    # ------------------------------------------------------------------
+    # Sink protocol
+    # ------------------------------------------------------------------
+
+    def capture(self, *, family: PayloadFamily | str, payload: object) -> SinkCaptureReceipt:
+        from ...contract import (
+            DegradedRecord,
+            MetricRecord,
+            StructuredEventRecord,
+        )
+
+        if not self.supports(family):
+            return SinkCaptureReceipt.success(detail="family not handled by MLflowSink")
+
+        if isinstance(payload, MetricRecord):
+            self._export_metric(payload)
+            return SinkCaptureReceipt.success(
+                detail=f"logged metric {payload.payload.metric_key}",
+                metadata={"metric_key": payload.payload.metric_key},
+            )
+
+        if isinstance(payload, StructuredEventRecord):
+            self._export_event(payload)
+            return SinkCaptureReceipt.success(
+                detail=f"tagged event {payload.payload.event_key}",
+                metadata={"event_key": payload.payload.event_key},
+            )
+
+        if isinstance(payload, DegradedRecord):
+            self._export_degraded(payload)
+            return SinkCaptureReceipt.success(
+                detail=f"tagged degraded {payload.payload.issue_key}",
+                metadata={"issue_key": payload.payload.issue_key},
+            )
+
+        return SinkCaptureReceipt.success(detail="unrecognised record type; skipped")
+
+    # ------------------------------------------------------------------
+    # Export helpers
+    # ------------------------------------------------------------------
+
+    def _log_metric(self, key: str, value: float) -> None:
+        mlflow = _load_mlflow()
+        if self._run_id is not None:
+            mlflow.log_metric(key, value, run_id=self._run_id)
+        else:
+            mlflow.log_metric(key, value)
+
+    def _set_tag(self, key: str, value: str) -> None:
+        mlflow = _load_mlflow()
+        if self._run_id is not None:
+            mlflow.set_tag(key, value, run_id=self._run_id)
+        else:
+            mlflow.set_tag(key, value)
+
+    def _set_tag_once(self, key: str, value: str) -> None:
+        """Write a tag only on the first call for this key."""
+        if key not in self._written_tags:
+            self._written_tags.add(key)
+            self._set_tag(key, value)
+
+    def _ensure_run_ref_tag(self, run_ref: Any) -> None:
+        if not self._run_ref_written:
+            self._run_ref_written = True
+            self._set_tag_once("contexta.run_ref", str(run_ref))
+
+    def _export_metric(self, record: "MetricRecord") -> None:
+        payload = record.payload
+        envelope = record.envelope
+
+        self._ensure_run_ref_tag(envelope.run_ref)
+        if envelope.stage_execution_ref is not None:
+            self._set_tag_once("contexta.stage_ref", str(envelope.stage_execution_ref))
+
+        # Write unit tag once per metric key (not per observation)
+        if payload.unit:
+            unit_tag = f"contexta.metric_unit.{payload.metric_key}"
+            self._set_tag_once(unit_tag, payload.unit)
+
+        # Write metric tags once per metric key
+        if payload.tags:
+            for k, v in payload.tags.items():
+                tag_key = f"contexta.tag.{k}"
+                self._set_tag_once(tag_key, str(v))
+
+        self._log_metric(payload.metric_key, float(payload.value))
+
+    def _export_event(self, record: "StructuredEventRecord") -> None:
+        payload = record.payload
+        envelope = record.envelope
+
+        self._ensure_run_ref_tag(envelope.run_ref)
+
+        message = str(payload.message)[:_MLFLOW_TAG_MAX_LEN]
+        self._set_tag(f"contexta.event.{payload.event_key}", message)
+        self._set_tag_once(
+            f"contexta.event_level.{payload.event_key}",
+            payload.level,
+        )
+
+    def _export_degraded(self, record: "DegradedRecord") -> None:
+        payload = record.payload
+        envelope = record.envelope
+
+        self._set_tag(
+            f"contexta.degraded.{payload.issue_key}",
+            f"{payload.category}:{payload.severity}",
+        )
+        self._set_tag_once("contexta.degraded_run_ref", str(envelope.run_ref))
+
+
+__all__ = ["MLflowSink"]

contexta/adapters/notebook/__init__.py

@@ -0,0 +1,29 @@
+"""Optional notebook adapter namespace for Contexta.
+
+Re-exports the notebook delivery surface so that notebook-aware code can
+import from this canonical adapter boundary rather than from internal surfaces.
+
+    from contexta.adapters.notebook import NotebookSurface, display_run_snapshot
+"""
+
+from ...surfaces.notebook import (
+    NotebookFragment,
+    NotebookSurface,
+    display_metric_trend,
+    display_run_comparison,
+    display_run_snapshot,
+    render_html_fragment,
+    to_pandas,
+    to_polars,
+)
+
+__all__ = [
+    "NotebookFragment",
+    "NotebookSurface",
+    "display_metric_trend",
+    "display_run_comparison",
+    "display_run_snapshot",
+    "render_html_fragment",
+    "to_pandas",
+    "to_polars",
+]

contexta/adapters/otel/__init__.py

@@ -0,0 +1,12 @@
+"""Optional OpenTelemetry adapter namespace for Contexta.
+
+OTel integration code should enter through this package and remain outside the
+base runtime dependency path.
+
+Raises ``DependencyError`` at construction time when ``opentelemetry-api``
+is not installed. Install it with: pip install 'contexta[otel]'
+"""
+
+from ._sink import OTelSink
+
+__all__ = ["OTelSink"]

contexta/adapters/otel/_sink.py

@@ -0,0 +1,272 @@
+"""OTel bridge sink — exports Contexta capture payloads to OpenTelemetry."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ...capture.sinks.protocol import BaseSink, SinkCaptureReceipt
+from ...capture.results import PayloadFamily
+from ...common.errors import DependencyError
+
+if TYPE_CHECKING:
+    from ...contract import (
+        DegradedRecord,
+        MetricRecord,
+        StructuredEventRecord,
+        TraceSpanRecord,
+    )
+
+
+def _load_otel_trace():
+    """Lazy import of opentelemetry.trace — raises DependencyError if absent."""
+    try:
+        import opentelemetry.trace as otel_trace
+        return otel_trace
+    except ImportError as exc:
+        raise DependencyError(
+            "opentelemetry-api is required for OTelSink. "
+            "Install it with: pip install 'contexta[otel]'",
+            code="otel_api_not_ready",
+            cause=exc,
+        ) from exc
+
+
+def _load_otel_metrics():
+    """Lazy import of opentelemetry.metrics — raises DependencyError if absent."""
+    try:
+        import opentelemetry.metrics as otel_metrics
+        return otel_metrics
+    except ImportError as exc:
+        raise DependencyError(
+            "opentelemetry-api is required for OTelSink. "
+            "Install it with: pip install 'contexta[otel]'",
+            code="otel_api_not_ready",
+            cause=exc,
+        ) from exc
+
+
+def _map_span_kind(contexta_kind: str) -> Any:
+    otel_trace = _load_otel_trace()
+    mapping = {
+        "operation": otel_trace.SpanKind.INTERNAL,
+        "internal": otel_trace.SpanKind.INTERNAL,
+        "io": otel_trace.SpanKind.CLIENT,
+        "network": otel_trace.SpanKind.CLIENT,
+        "process": otel_trace.SpanKind.PRODUCER,
+    }
+    return mapping.get(contexta_kind, otel_trace.SpanKind.INTERNAL)
+
+
+def _map_status_code(contexta_status: str) -> Any:
+    otel_trace = _load_otel_trace()
+    if contexta_status == "ok":
+        return otel_trace.StatusCode.OK
+    return otel_trace.StatusCode.ERROR
+
+
+class OTelSink(BaseSink):
+    """Export Contexta capture payloads to the OpenTelemetry API.
+
+    Implements the ``Sink`` protocol so it can be passed directly to
+    ``Contexta(sinks=[OTelSink(...)])``.
+
+    Raises ``DependencyError`` on construction when ``opentelemetry-api``
+    is not installed.
+
+    Thread safety: metric instrument cache is not thread-safe.
+    Use one instance per thread or protect externally.
+    """
+
+    def __init__(
+        self,
+        *,
+        service_name: str = "contexta",
+        tracer_provider: Any = None,
+        meter_provider: Any = None,
+        name: str = "otel",
+    ) -> None:
+        super().__init__(
+            name=name,
+            supported_families=(PayloadFamily.RECORD,),
+        )
+        # Eager import check — fail loudly on construction, not on first capture.
+        _load_otel_trace()
+        _load_otel_metrics()
+
+        self._service_name = service_name
+        self._tracer_provider = tracer_provider
+        self._meter_provider = meter_provider
+        self._tracer: Any = None
+        self._meter: Any = None
+        # (metric_name, unit) → Histogram instrument
+        self._histograms: dict[tuple[str, str], Any] = {}
+
+    # ------------------------------------------------------------------
+    # Sink protocol
+    # ------------------------------------------------------------------
+
+    def capture(self, *, family: PayloadFamily | str, payload: object) -> SinkCaptureReceipt:
+        from ...contract import (
+            DegradedRecord,
+            MetricRecord,
+            StructuredEventRecord,
+            TraceSpanRecord,
+        )
+
+        if not self.supports(family):
+            return SinkCaptureReceipt.success(detail="family not handled by OTelSink")
+
+        if isinstance(payload, TraceSpanRecord):
+            self._export_span(payload)
+            return SinkCaptureReceipt.success(
+                detail=f"exported span {payload.payload.span_name}",
+                metadata={"span_name": payload.payload.span_name},
+            )
+
+        if isinstance(payload, MetricRecord):
+            self._export_metric(payload)
+            return SinkCaptureReceipt.success(
+                detail=f"recorded metric {payload.payload.metric_key}",
+                metadata={"metric_key": payload.payload.metric_key},
+            )
+
+        if isinstance(payload, StructuredEventRecord):
+            self._export_event(payload)
+            return SinkCaptureReceipt.success(
+                detail=f"added event {payload.payload.event_key}",
+                metadata={"event_key": payload.payload.event_key},
+            )
+
+        if isinstance(payload, DegradedRecord):
+            self._export_degraded(payload)
+            return SinkCaptureReceipt.success(
+                detail=f"added degraded event {payload.payload.issue_key}",
+                metadata={"issue_key": payload.payload.issue_key},
+            )
+
+        return SinkCaptureReceipt.success(detail="unrecognised record type; skipped")
+
+    # ------------------------------------------------------------------
+    # Lazy tracer / meter
+    # ------------------------------------------------------------------
+
+    def _get_tracer(self) -> Any:
+        if self._tracer is None:
+            otel_trace = _load_otel_trace()
+            provider = self._tracer_provider or otel_trace.get_tracer_provider()
+            self._tracer = provider.get_tracer(self._service_name)
+        return self._tracer
+
+    def _get_meter(self) -> Any:
+        if self._meter is None:
+            otel_metrics = _load_otel_metrics()
+            provider = self._meter_provider or otel_metrics.get_meter_provider()
+            self._meter = provider.get_meter(self._service_name)
+        return self._meter
+
+    def _get_histogram(self, metric_name: str, unit: str) -> Any:
+        key = (metric_name, unit)
+        if key not in self._histograms:
+            self._histograms[key] = self._get_meter().create_histogram(
+                name=metric_name,
+                unit=unit,
+                description=f"Contexta metric: {metric_name}",
+            )
+        return self._histograms[key]
+
+    # ------------------------------------------------------------------
+    # Export helpers
+    # ------------------------------------------------------------------
+
+    def _export_span(self, record: "TraceSpanRecord") -> None:
+        otel_trace = _load_otel_trace()
+        payload = record.payload
+        envelope = record.envelope
+
+        attrs: dict[str, Any] = {
+            "contexta.run_ref": str(envelope.run_ref),
+            "contexta.record_ref": str(envelope.record_ref),
+            "contexta.span_kind": payload.span_kind,
+            "contexta.span_id": payload.span_id,
+            "contexta.trace_id": payload.trace_id,
+        }
+        if envelope.stage_execution_ref is not None:
+            attrs["contexta.stage_ref"] = str(envelope.stage_execution_ref)
+        if payload.parent_span_id is not None:
+            attrs["contexta.parent_span_id"] = payload.parent_span_id
+        if payload.attributes:
+            for k, v in payload.attributes.items():
+                attrs[f"contexta.span.{k}"] = str(v)
+
+        span_kind = _map_span_kind(payload.span_kind)
+        status_code = _map_status_code(payload.status)
+
+        span = self._get_tracer().start_span(
+            payload.span_name,
+            kind=span_kind,
+            attributes=attrs,
+        )
+        try:
+            span.set_status(status_code)
+        finally:
+            span.end()
+
+    def _export_metric(self, record: "MetricRecord") -> None:
+        payload = record.payload
+        envelope = record.envelope
+
+        metric_name = f"contexta.{payload.metric_key}"
+        unit = payload.unit or "1"
+
+        attrs: dict[str, Any] = {
+            "contexta.run_ref": str(envelope.run_ref),
+            "contexta.aggregation_scope": payload.aggregation_scope,
+            "contexta.value_type": payload.value_type,
+        }
+        if envelope.stage_execution_ref is not None:
+            attrs["contexta.stage_ref"] = str(envelope.stage_execution_ref)
+        if payload.tags:
+            for k, v in payload.tags.items():
+                attrs[f"contexta.tag.{k}"] = v
+
+        histogram = self._get_histogram(metric_name, unit)
+        histogram.record(float(payload.value), attributes=attrs)
+
+    def _export_event(self, record: "StructuredEventRecord") -> None:
+        otel_trace = _load_otel_trace()
+        payload = record.payload
+        envelope = record.envelope
+
+        attrs: dict[str, Any] = {
+            "contexta.run_ref": str(envelope.run_ref),
+            "contexta.event_level": payload.level,
+            "contexta.event_message": payload.message,
+        }
+        if envelope.stage_execution_ref is not None:
+            attrs["contexta.stage_ref"] = str(envelope.stage_execution_ref)
+        if payload.attributes:
+            for k, v in payload.attributes.items():
+                attrs[f"contexta.event.{k}"] = str(v)
+
+        current_span = otel_trace.get_current_span()
+        current_span.add_event(payload.event_key, attributes=attrs)
+
+    def _export_degraded(self, record: "DegradedRecord") -> None:
+        otel_trace = _load_otel_trace()
+        payload = record.payload
+        envelope = record.envelope
+
+        attrs: dict[str, Any] = {
+            "contexta.run_ref": str(envelope.run_ref),
+            "contexta.issue_key": payload.issue_key,
+            "contexta.degradation_category": payload.category,
+            "contexta.severity": payload.severity,
+        }
+        if envelope.stage_execution_ref is not None:
+            attrs["contexta.stage_ref"] = str(envelope.stage_execution_ref)
+
+        current_span = otel_trace.get_current_span()
+        current_span.add_event("contexta.degraded", attributes=attrs)
+
+
+__all__ = ["OTelSink"]

contexta/api/__init__.py

@@ -0,0 +1,5 @@
+"""Internal facade assembly package for Contexta."""
+
+from .client import Contexta, __version__
+
+__all__ = ["Contexta", "__version__"]