Introduction

Contexta is a local-first observability library for ML systems. It gives a project one Python import root, one CLI, one local workspace, and one evidence model for writing, storing, querying, comparing, and recovering ML observability data.

The short version: Contexta helps you keep enough structured evidence around an ML run that someone can understand it later without reconstructing the story from memory, scattered logs, or dashboard screenshots.

Install

pip install contexta

or with uv:

uv add contexta

Contexta's core runtime only requires duckdb. Framework integrations are optional and installed only when you need them.

Run Your First Capture

Start with Getting Started, which provides complete copy-and-run examples for Machine Learning, Deep Learning, and LLM workflows. Each example creates a local .contexta/ workspace and captures inspectable evidence without requiring repository files.

What Contexta Tracks

Contexta organizes observability data as durable evidence:

• projects, runs, stages, batches, samples, and deployments
• structured events, metrics, traces, and degraded markers
• artifacts, manifests, hashes, imports, exports, and retention records
• lineage, provenance, environment, comparison, diagnostics, trend, and report outputs

The model is intentionally local-first. Your workspace lives beside your project, which makes it suitable for notebooks, CI jobs, offline review, and autonomous agent worktrees.

Where To Go Next

• Getting Started expands the quickstart into a fuller onboarding path.
• Core Concepts explains the evidence model.
• Tools and Surfaces shows the public API boundaries.
• API Reference documents the Python surface.
• Operations Guide covers backup, restore, replay, and transfer workflows.
• Case Studies connects captured evidence to real operational scenarios.

Product Surface

Surface	Role
Contexta	Default facade for user workflows
contexta.config	Configuration models, profiles, and environment overrides
contexta.contract	Canonical models, validation, serialization, and refs
contexta.capture	Runtime capture scopes and emissions
contexta.store.*	Metadata, record, and artifact truth planes
contexta.interpretation	Query, comparison, diagnostics, lineage, trend, alert, and report services
contexta.recovery	Backup, restore, replay, and transfer operations

Start with Contexta unless you need an exact lower-level boundary.