Contexta

Local-first observability for ML systems & Harness Engineering.

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. It is designed as the perfect infrastructure for both human engineers and autonomous AI coding agents — MUST-HAVE for Harness Engineering.

Why Contexta

• One product surface Start from from contexta import Contexta instead of stitching together separate tools.
• Canonical local workspace (Agent-Ready) Keep metadata, records, artifacts, reports, and recovery state in a local .contexta/ workspace—perfectly isolated for autonomous agent worktrees and context resets.
• Read-oriented investigation & Evaluator Loops Query runs, compare outcomes, inspect diagnostics, follow lineage, and build reports from canonical data. Structured specifically to support QA agents and Generator-Evaluator loops.
• 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

Open the Getting Started guide for complete copy-and-run examples covering Machine Learning, Deep Learning, and LLM workflows. Each example starts from the installed library and writes inspectable evidence into a local .contexta/ workspace.

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:

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

Product Surface

Surface	Status	Role	When To Start Here
Contexta	Stable	Unified facade	Default starting point
contexta.config	Stable	Config models, profiles, env overrides	When you need explicit config control
contexta.contract	Stable	Canonical models, validation, serialization	When you work directly with schema-level types
contexta.capture	Stable	Runtime capture scopes and emissions	When facade-level capture is not enough
contexta.store.metadata	Stable	Metadata truth plane	Advanced store access
contexta.store.records	Stable	Record truth plane	Replay, scan, export, integrity workflows
contexta.store.artifacts	Stable	Artifact truth plane	Artifact ingest, verify, export, import
contexta.interpretation	Stable	Query, compare, diagnostics, lineage, reports	Read and investigation flows
contexta.recovery	Advanced	Replay, backup, restore	Operator and recovery work

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/tutorials/getting-started.md
• docs/key-features.md
• docs/tools-and-surfaces.md
• docs/core-concepts.md
• docs/tutorials/common-workflows.md
• docs/user-guide/advanced.md
• docs/case-studies/index.md

Reference

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

Operations And Contribution

• docs/user-guide/operations.md
• docs/faq.md
• CONTRIBUTING.md
• SECURITY.md

Documented Programs

• docs/tutorials/getting-started.md - copy-and-run ML, DL, and LLM onboarding
• docs/case-studies/ - 12 scenarios with their complete displayed programs
• docs/user-guide/operations.md - operator programs for backup, replay, and transfer

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.