Contexta

Local-first observability for ML systems.

Quickstart | Product Surface | Docs Map

Contexta is a local-first ML observability library. It provides one canonical import root, one canonical CLI, one canonical workspace, and one consistent contract for writing, storing, querying, comparing, and recovering observability data — without a cloud backend.

Why Contexta

• One product surface Start from from contexta import Contexta instead of stitching together separate tools.
• Canonical local workspace Keep metadata, records, artifacts, reports, and recovery state in a local .contexta/ workspace.
• Read-oriented investigation Query runs, compare outcomes, inspect diagnostics, follow lineage, and build reports from canonical data.
• Recovery built in Replay, backup, restore, and artifact transfer are first-class features, not separate utilities.
• Framework-agnostic Works alongside scikit-learn, PyTorch, HuggingFace Transformers, vLLM, or any other ML stack.

Quickstart

Install

pip install contexta

or with uv:

uv add contexta

Run your first example

The fastest way to see Contexta in action is the sklearn tabular example — no GPU required:

pip install contexta "scikit-learn>=1.6"
uv run python examples/quickstart/qs01_sklearn_tabular.py

This trains an SVM and a Random Forest on the UCI Wine dataset, logs CV fold metrics and evaluation metrics to a local .contexta/ workspace, then compares the two runs and registers the best model as a deployment.

For deep learning and LLM examples see examples/quickstart/.

Minimal usage

from datetime import datetime, timezone
from contexta import Contexta
from contexta.config import UnifiedConfig, WorkspaceConfig
from contexta.contract import (
    Project, Run, StageExecution,
    MetricPayload, MetricRecord, RecordEnvelope,
)

ctx = Contexta(config=UnifiedConfig(
    project_name="my-project",
    workspace=WorkspaceConfig(root_path=".contexta"),
))
store = ctx.metadata_store

now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

store.projects.put_project(Project(project_ref="project:my-project", name="my-project", created_at=now))
store.runs.put_run(Run(run_ref="run:my-project.run-01", project_ref="project:my-project",
                       name="run-01", status="completed", started_at=now, ended_at=now))

ctx.record_store.append(MetricRecord(
    envelope=RecordEnvelope(
        record_ref="record:my-project.run-01.r00001", record_type="metric",
        recorded_at=now, observed_at=now, producer_ref="my-script",
        run_ref="run:my-project.run-01",
        completeness_marker="complete", degradation_marker="none",
    ),
    payload=MetricPayload(metric_key="accuracy", value=0.95, value_type="float64"),
))

snapshot = ctx.get_run_snapshot("run:my-project.run-01")
report   = ctx.build_snapshot_report("run:my-project.run-01")
print(report.title)

store.close()

Optional dependencies

Contexta's core runtime only requires duckdb. Install framework extras only for what you use:

pip install "contexta[sklearn]"       # + scikit-learn
pip install "contexta[torch]"         # + PyTorch
pip install "contexta[transformers]"  # + HuggingFace Transformers + PyTorch
pip install "contexta[all-integrations]"  # all of the above

Product Surface

The internal namespaces contexta.api, contexta.runtime, contexta.common, and contexta.surfaces are not public API targets.

Documentation Map

Core Entry Points

• README.md — product overview, install, quickstart
• docs/index.md — document hub

User Guide

• docs/user-guide/getting-started.md
• docs/user-guide/key-features.md
• docs/user-guide/tools-and-surfaces.md
• docs/user-guide/core-concepts.md
• docs/user-guide/common-workflows.md
• docs/user-guide/advanced.md
• docs/user-guide/case-studies.md

Reference

• docs/reference/api-reference.md
• docs/reference/cli-reference.md

Operations And Contribution

• docs/operations.md
• docs/faq.md
• CONTRIBUTING.md
• SECURITY.md

Examples

• examples/quickstart/ — qs01 (sklearn), qs02 (PyTorch CNN), qs03 (BERT), qs04 (vLLM RAG)
• examples/case_studies/ — 12 real-world observability scenarios
• examples/recovery/ — operator-oriented recovery workflows

Design Notes

• local-first: all data stays on your machine
• schema-first: every record follows a canonical contract
• reproducibility-oriented: environment snapshots and provenance are first-class
• explicit about degraded or incomplete states

Internally, Contexta separates truth-owning planes for metadata, records, and artifact bodies, then builds query, report, and recovery surfaces over those planes.