contexta 0.1.1__tar.gz

contexta-0.1.1/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local-only internal ops docs
+OpsDoc/
+.claude
+.codex-meeting

contexta-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,337 @@
+# Contributing To Contexta
+
+This guide explains how to work on `Contexta` in the current repository.
+
+The most important rule is simple:
+
+- contribute against the documented public product surface
+- avoid turning internal implementation paths into accidental public contracts
+
+## Development Setup
+
+Clone the repository and install the development environment:
+
+```powershell
+uv sync --dev
+```
+
+For ad-hoc local scripts and public examples in the source tree, use:
+
+```powershell
+$env:PYTHONPATH = "src"
+```
+
+Current prototype note:
+
+- canonical public docs, package metadata, and CLI naming now use `Contexta` / `contexta`
+
+## Repository Layout
+
+Key areas:
+
+- `src/contexta/`
+  - product code
+- `tests/`
+  - repository test suites
+- `docs/`
+  - public documentation
+- `examples/`
+  - executable public examples
+## Public Boundary Rules
+
+Safe public targets for docs, examples, and new user-facing code:
+
+- `contexta`
+- `contexta.config`
+- `contexta.contract`
+- `contexta.capture`
+- `contexta.store.metadata`
+- `contexta.store.records`
+- `contexta.store.artifacts`
+- `contexta.interpretation`
+- `contexta.recovery`
+
+Do not introduce new examples or docs that anchor on:
+
+- `contexta.api`
+- `contexta.runtime`
+- `contexta.common`
+- `contexta.surfaces`
+
+Those modules exist, but they are not the public contract we want contributors to normalize.
+
+## Documentation Rules
+
+When editing public docs:
+
+- use canonical product names first
+- prefer task-oriented guidance over internal architecture narration
+- point to executable examples whenever possible
+- avoid promising behavior that is not already implemented or tested
+
+Public docs should describe:
+
+- stable product usage
+- current prototype caveats when they matter
+
+Public docs should not expose:
+
+- WBS progress
+- internal scratch notes
+- accidental internal import paths as if they were supported APIs
+
+## Example Rules
+
+Examples in `examples/` are part of the public documentation surface.
+
+That means they should:
+
+- use public imports only
+- run from a normal repository checkout
+- match the docs that point to them
+- have regression coverage when practical
+
+If you change:
+
+- `examples/quickstart/`
+  - rerun `uv run pytest tests/e2e/test_quickstart_examples.py -q`
+- `examples/recovery/`
+  - rerun `uv run pytest tests/e2e/test_recovery_examples.py -q`
+
+## Testing
+
+The project uses `pytest`.
+
+Broad validation:
+
+```powershell
+uv run pytest -q
+```
+
+Smaller targeted suites you will likely use often:
+
+```powershell
+uv run pytest tests/e2e/test_quickstart_examples.py -q
+uv run pytest tests/e2e/test_recovery_examples.py -q
+uv run pytest tests/e2e/test_capture_to_report.py -q
+```
+
+When choosing tests:
+
+- run the smallest suite that proves your change
+- expand to broader suites when public behavior moved
+- keep examples and docs tied to executable evidence
+
+## Code And Change Style
+
+When making code changes:
+
+- preserve canonical naming in public-facing code paths
+- prefer explicit, typed models over loose ad-hoc payload handling
+- respect the separation between metadata, records, and artifacts as truth-owning planes
+- keep recovery flows explicit about warnings, degradation, and loss notes
+
+When making documentation changes:
+
+- keep wording honest about prototype limitations
+- update hubs and entry pages when new docs appear
+- avoid leaving “planned” language behind once a page exists
+
+## Submitting Changes
+
+Before you consider a change ready:
+
+- confirm the changed docs or examples still match reality
+- run the nearest relevant test suite
+- check that new public examples avoid internal imports
+- update adjacent navigation pages when you add a new public document
+
+If you touch public behavior, consider whether these also need updates:
+
+- `README.md`
+- `docs/index.md`
+- `docs/user-guide/index.md`
+- reference pages
+- examples
+
+## Versioning Policy
+
+Contexta uses [Semantic Versioning](https://semver.org) with PEP 440 pre-release identifiers.
+
+**Single source of truth:** `[project].version` in `pyproject.toml`.
+`contexta.__version__` reads this at runtime via `importlib.metadata` — do not duplicate it.
+
+### Version scheme
+
+| Version form | When to use |
+|---|---|
+| `0.MINOR.PATCH` | Current pre-1.0 series |
+| `0.MINOR.0` | New public API surface; may include breaking changes (pre-1.0 convention) |
+| `0.x.PATCH` | Bug fixes only, no breaking changes |
+| `1.0.0` | Stable public API contract — requires full REL sign-off |
+
+### Pre-release identifiers (PEP 440)
+
+| Identifier | Example | Use for |
+|---|---|---|
+| alpha | `0.2.0a1` | Early preview, incomplete features |
+| beta | `0.2.0b1` | Feature complete, stabilizing |
+| rc | `0.2.0rc1` | Release candidate, final validation |
+
+### Bumping the version
+
+Use `uv version` to update `pyproject.toml` in one command:
+
+```powershell
+uv version --bump patch              # 0.1.0 -> 0.1.1
+uv version --bump minor              # 0.1.0 -> 0.2.0
+uv version --bump minor --bump rc   # 0.1.0 -> 0.2.0rc1
+uv version 0.2.0                     # set explicitly
+```
+
+After bumping:
+
+```powershell
+git add pyproject.toml
+git commit -m "chore: bump version to $(uv version --short)"
+git tag "v$(uv version --short)"
+```
+
+### Git tag convention
+
+Tags use a `v` prefix: `v0.1.0`, `v0.2.0rc1`.
+The release workflow (REL-026) triggers on `v*` tag pushes.
+
+## Release Process
+
+This section describes how to cut a release. Steps 1–5 are the pre-release gate; steps 6–8 are the actual publish.
+
+### 1. Confirm the release gate passes
+
+```powershell
+uv run pytest --tb=short -q
+```
+
+All tests must pass (0 failures). Also confirm CI is green on `main`.
+
+### 2. Bump the version
+
+```powershell
+uv version --bump minor              # new features
+uv version --bump patch              # bug fixes only
+uv version --bump minor --bump rc   # release candidate
+```
+
+Verify the bump:
+
+```powershell
+uv version --short   # prints the new version
+```
+
+### 3. Build and verify distributions
+
+```powershell
+uv build
+```
+
+Spot-check the wheel in a clean environment:
+
+```powershell
+uv venv /tmp/ctx-release-check
+/tmp/ctx-release-check/Scripts/pip install dist/contexta-*.whl --quiet
+/tmp/ctx-release-check/Scripts/python -c "from contexta import __version__; print(__version__)"
+/tmp/ctx-release-check/Scripts/contexta --help
+```
+
+### 4. Generate checksums
+
+```powershell
+uv run python -c "
+import hashlib, pathlib
+for f in sorted(pathlib.Path('dist').glob('contexta-*')):
+    h = hashlib.sha256(f.read_bytes()).hexdigest()
+    print(f'{h}  {f.name}')
+"
+```
+
+Paste the output into `.github/RELEASE_NOTES_v{VERSION}.md`.
+
+### 5. Commit and tag
+
+```powershell
+git add pyproject.toml
+git commit -m "chore: bump version to $(uv version --short)"
+git tag "v$(uv version --short)"
+```
+
+### 6. Push the tag
+
+```powershell
+git push origin main "v$(uv version --short)"
+```
+
+Pushing the tag triggers the `release.yml` workflow (REL-026), which builds distributions and uploads them to the GitHub Release automatically.
+
+### 7. Create the GitHub Release
+
+In GitHub: **Releases → Draft a new release**
+
+- Tag: select the tag you just pushed (e.g. `v0.2.0`)
+- Title: `Contexta {VERSION}`
+- Body: paste the content of `.github/RELEASE_NOTES_v{VERSION}.md`
+- Attach `dist/contexta-{VERSION}-py3-none-any.whl` and `dist/contexta-{VERSION}.tar.gz`
+- For pre-releases (`rc`, `alpha`, `beta`): check **Set as a pre-release**
+
+### 8. Post-release
+
+- Verify the release page looks correct
+- Confirm PyPI upload succeeded (if applicable — see REL-025)
+- Delete the local `/tmp/ctx-release-check` venv
+
+## CI Workflows
+
+Four GitHub Actions workflows run on every push and pull request:
+
+| Workflow | File | Runs on |
+|---|---|---|
+| CI | `.github/workflows/ci.yml` | push / PR → main, master |
+| Test Matrix | `.github/workflows/test-matrix.yml` | push / PR → main, master + nightly |
+| Packaging | `.github/workflows/packaging.yml` | push / PR → main, master |
+| Docs and Examples | `.github/workflows/examples.yml` | push / PR → main, master |
+
+**Release gate** — the command every workflow mirrors locally:
+
+```powershell
+uv run pytest --tb=short -q
+```
+
+All 544 tests must pass with 0 failures before any release.
+
+## Branch Protection (main)
+
+The following checks are **required** before a PR can merge into `main`:
+
+- `CI / Test (Python 3.14)` — full test suite + import smoke + CLI smoke
+- `Packaging / Build wheel + sdist` — build succeeds, wheel contents are clean
+- `Packaging / Install from wheel + smoke` — wheel installs and imports correctly in a clean venv
+
+The following checks are **informational** (not blocking):
+
+- `Test Matrix / pytest / Python 3.14 / ubuntu-latest`
+- `Test Matrix / pytest / Python 3.14 / windows-latest`
+- `Docs and Examples / Internal link check`
+- `Docs and Examples / Quickstart examples`
+- `Docs and Examples / Recovery examples`
+
+To configure branch protection in GitHub:
+
+1. Go to **Settings → Branches → Add rule** for `main`
+2. Enable **Require status checks to pass before merging**
+3. Search for and add the three required check names above
+4. Enable **Require branches to be up to date before merging**
+
+## Where To Go Next
+
+- product docs: [docs/index.md](./docs/index.md)
+- user guide: [docs/user-guide/index.md](./docs/user-guide/index.md)
+- examples: [examples/quickstart/README.md](./examples/quickstart/README.md), [examples/recovery/README.md](./examples/recovery/README.md)

contexta-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

contexta-0.1.1/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: contexta
+Version: 0.1.1
+Summary: Local-first observability for ML systems
+Project-URL: Homepage, https://github.com/your-org/contexta
+Project-URL: Documentation, https://your-org.github.io/contexta
+Project-URL: Repository, https://github.com/your-org/contexta
+Project-URL: Bug Tracker, https://github.com/your-org/contexta/issues
+Author: Kim
+License: MIT
+License-File: LICENSE
+Keywords: machine-learning,ml-observability,mlops,monitoring,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.14
+Requires-Dist: duckdb>=1.5.1
+Provides-Extra: all-integrations
+Requires-Dist: mlflow>=2.0; extra == 'all-integrations'
+Requires-Dist: opentelemetry-api>=1.20; extra == 'all-integrations'
+Requires-Dist: pandas>=2.0; extra == 'all-integrations'
+Requires-Dist: polars>=0.20; extra == 'all-integrations'
+Requires-Dist: scikit-learn>=1.6; extra == 'all-integrations'
+Requires-Dist: torch>=2.5; extra == 'all-integrations'
+Requires-Dist: transformers>=4.40; extra == 'all-integrations'
+Provides-Extra: dataframes
+Requires-Dist: pandas>=2.0; extra == 'dataframes'
+Requires-Dist: polars>=0.20; extra == 'dataframes'
+Provides-Extra: mlflow
+Requires-Dist: mlflow>=2.0; extra == 'mlflow'
+Provides-Extra: notebook
+Requires-Dist: ipython>=8.0; extra == 'notebook'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
+Provides-Extra: sklearn
+Requires-Dist: scikit-learn>=1.6; extra == 'sklearn'
+Provides-Extra: torch
+Requires-Dist: torch>=2.5; extra == 'torch'
+Provides-Extra: transformers
+Requires-Dist: torch>=2.5; extra == 'transformers'
+Requires-Dist: transformers>=4.40; extra == 'transformers'
+Description-Content-Type: text/markdown
+
+<h1 align="center">Contexta</h1>
+
+<p align="center">
+  <strong>Local-first observability for ML systems.</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.14%2B-2563EB" alt="python 3.14+">
+  <img src="https://img.shields.io/badge/stack-Python%20%7C%20uv%20%7C%20pytest-1F2937" alt="project stack">
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/status-prototype-D97706" alt="prototype status">
+  <img src="https://img.shields.io/badge/focus-local--first-0F766E" alt="local-first">
+</p>
+
+<p align="center">
+  <a href="https://github.com/eastlighting1/Contexta/actions/workflows/ci.yml"><img src="https://github.com/eastlighting1/Contexta/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/eastlighting1/Contexta/actions/workflows/test-matrix.yml"><img src="https://github.com/eastlighting1/Contexta/actions/workflows/test-matrix.yml/badge.svg" alt="Test Matrix"></a>
+  <a href="https://github.com/eastlighting1/Contexta/actions/workflows/examples.yml"><img src="https://github.com/eastlighting1/Contexta/actions/workflows/examples.yml/badge.svg" alt="Docs and Examples"></a>
+  <a href="https://github.com/eastlighting1/Contexta/actions/workflows/packaging.yml"><img src="https://github.com/eastlighting1/Contexta/actions/workflows/packaging.yml/badge.svg" alt="Packaging"></a>
+</p>
+
+<p align="center">
+  <a href="#quickstart">Quickstart</a> |
+  <a href="#product-surface">Product Surface</a> |
+  <a href="#documentation-map">Docs Map</a>
+</p>
+
+`Contexta` brings the six legacy library roles into one product surface. The intended developer experience is one canonical Python import root, one canonical CLI, one canonical workspace, and one consistent contract for writing, storing, querying, comparing, and recovering observability data.
+
+> [!NOTE]
+> `Contexta` is in a prototype-to-product transition. The canonical public identity is already `Contexta` and `contexta`, but some packaging and CLI alignment work is still in progress. This README uses the final product language first and calls out transitional behavior only where it matters.
+
+## Why Contexta
+
+- **One product surface**
+  Start from `from contexta import Contexta` instead of stitching together separate package roots.
+- **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 part of the product direction, not separate utilities.
+
+## Quickstart
+
+The shortest fully verified prototype path is:
+
+1. Install the project in editable mode.
+2. Run the verified quickstart example.
+3. Inspect the generated report and workspace output.
+
+### 1. Install
+
+For local development inside this repository:
+
+```powershell
+uv sync --dev
+```
+
+Or with `pip`:
+
+```powershell
+python -m pip install -e .
+```
+
+After installation, the canonical import is:
+
+```python
+from contexta import Contexta
+```
+
+### 2. Run The Verified Quickstart Example
+
+```powershell
+$env:PYTHONPATH = "src"
+uv run python examples/quickstart/verified_quickstart.py
+```
+
+The example source lives at [`examples/quickstart/verified_quickstart.py`](./examples/quickstart/verified_quickstart.py).
+
+It creates a temporary workspace, writes minimal canonical data, queries the resulting run, and saves a markdown snapshot report.
+
+### 3. What This Confirms
+
+- the `contexta` import path is live
+- a canonical `.contexta/` workspace can be created locally
+- canonical metadata and records can be written
+- the unified facade can query that workspace and build a report
+- the quickstart example is executable and regression-covered
+
+## Runtime Capture Preview
+
+The runtime capture surface is already part of the product direction:
+
+```powershell
+$env:PYTHONPATH = "src"
+uv run python examples/quickstart/runtime_capture_preview.py
+```
+
+The preview source lives at [`examples/quickstart/runtime_capture_preview.py`](./examples/quickstart/runtime_capture_preview.py).
+
+The verified README quickstart intentionally uses the currently proven query/report path. The runtime capture preview is included separately so new users can see the scope API without over-promising the current onboarding workflow.
+
+## 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 documented as public import targets.
+
+## Documentation Map
+
+The public documentation set is being built in the following structure:
+
+### Core Entry Points
+
+- `README.md`
+  - product overview, install, quickstart, migration note
+- `docs/index.md`
+  - document hub
+
+### User Guide
+
+- `docs/user-guide/index.md`
+- `docs/user-guide/key-features.md`
+- `docs/user-guide/tools-and-surfaces.md`
+- `docs/user-guide/core-concepts.md`
+- `docs/user-guide/getting-started.md`
+- `docs/user-guide/common-workflows.md`
+- `docs/user-guide/advanced.md`
+- `docs/user-guide/testing.md`
+
+### Reference
+
+- `docs/reference/api-reference.md`
+- `docs/reference/cli-reference.md`
+- `docs/reference/http-reference.md`
+
+### Operations And Contribution
+
+- `docs/operations.md`
+- `docs/faq.md`
+- `CONTRIBUTING.md`
+
+### Examples
+
+- `examples/quickstart/`
+  - verified quickstart and runtime capture preview
+- `examples/recovery/`
+  - operator-oriented recovery workflows
+
+## Design Notes
+
+The product direction is:
+
+- local-first
+- schema-first
+- reproducibility-oriented
+- explicit about degraded or incomplete states
+
+Internally, `Contexta` keeps separate truth-owning planes for:
+
+- metadata and relations
+- records
+- artifact bodies and bindings
+
+and then builds query/report/recovery surfaces over those planes.
+
+## Current Caveats
+
+- Some prototype-to-release packaging polish is still in progress.
+- Source-tree example runs still commonly use `PYTHONPATH=src`.
+
+These are release-alignment issues, not a change in the canonical product identity.