precisionai-pace 0.0.1__tar.gz

precisionai_pace-0.0.1/.coveragerc-adapters

@@ -0,0 +1,20 @@
+# Coverage for the framework adapters only, used by the `adapters` job in
+# .github/workflows/unit-test.yml. The core matrix runs without Lightning or
+# Transformers installed, so pyproject.toml leaves these two modules out of its
+# coverage run and this file measures them where the frameworks are present.
+[run]
+include =
+    */precisionai/pace/lightning.py
+    */precisionai/pace/transformers.py
+branch = true
+relative_files = true
+
+[report]
+fail_under = 90
+show_missing = true
+exclude_lines =
+    pragma: no cover
+    if __name__ == .__main__.:
+    raise ImportError
+    except ImportError
+    if TYPE_CHECKING:

precisionai_pace-0.0.1/.gitattributes

@@ -0,0 +1,12 @@
+# Normalize line endings to LF on commit, regardless of editor/OS settings.
+* text=auto eol=lf
+
+# Treat binary files as binary (no line-ending conversion).
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.JPG binary
+*.JPEG binary
+*.svg binary
+*.pdf binary
+*.ipynb text eol=lf

precisionai_pace-0.0.1/.gitignore

@@ -0,0 +1,135 @@
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Sphinx documentation
+docs/_build/
+docs/readme.md
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+
+# PyTorch / Machine Learning artefacts
+*.pth
+*.pt
+*.ckpt
+*.pkl
+*.h5
+*.hdf5
+*.onnx
+*.pb
+*.tflite
+*.tfl
+checkpoints/
+models/
+weights/
+wandb/
+mlruns/
+.neptune/
+
+# OS files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+*~
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo

precisionai_pace-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,47 @@
+repos:
+  # ── File hygiene ────────────────────────────────────────────────────────────
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        args: ["--maxkb=1800"]
+      - id: check-yaml
+      - id: check-json
+      - id: check-toml
+      - id: end-of-file-fixer
+        exclude: ^\.github/badges/
+      - id: trailing-whitespace
+        exclude: ^\.github/badges/
+      - id: check-merge-conflict
+      - id: detect-private-key
+      - id: debug-statements
+      - id: fix-byte-order-marker
+
+  # ── Ruff: lint + format + import sorting ───────────────────────────────────
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.17
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+
+  # ── Type checking (pyright / pylance engine) ────────────────────────────────
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: python -m pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+
+  # ── Tests + coverage (≥ 90%) ────────────────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest (coverage ≥ 90%)
+        entry: python -m pytest
+        language: system
+        args: ["tests/", "-q", "--tb=short", "--no-header"]
+        pass_filenames: false
+        always_run: true

precisionai_pace-0.0.1/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.0.1] - 2026-11-03
+
+### Added
+
+- Package scaffold for `precisionai-pace`, with no runtime dependencies and support for Python 3.8 and later.
+- Design document for the logger, the progress line format and the completion-forecast rules.
+- `logger` with `debug`, `info`, `success`, `warning`, `error`, `critical` and `exception`, writing to stdout by default, falling back to plain ASCII on terminals that cannot show Unicode, and never raising into your code.
+- Progress reporting with `track`, `progress`, `timed`, `phase` and `plan`, written as readable lines that also carry a `[pace:1 ...]` trailer a scheduler can read.
+- A live progress bar on terminals, and rate-limited progress lines everywhere else, so a long run writes a few lines a minute however many steps it has.
+- `capture_logging()` to route the standard library's `logging` (and so PyTorch's and Transformers') through Pace.
+- `parse_line` and `LineSplitter` for programs that read Pace output, with shared conformance fixtures.
+- Time-remaining estimates (`ScopeForecast`, `JobForecast`) shared by the terminal display and by schedulers.
+- Callbacks for PyTorch Lightning (`precisionai.pace.lightning.PaceCallback`) and Hugging Face Transformers and TRL (`precisionai.pace.transformers.PaceCallback`), installed with the `[lightning]`, `[transformers]` or `[all]` extras.
+- `skills/adopt-pace/`, a Claude Code skill that adds Pace to a repository and checks the result with `verify.py`.
+- Runnable examples, one per style of logging and progress (plain loops, epochs, concurrent work, phases and a plan, resuming, unknown totals, nested scopes, `logging` capture, distributed ranks, and reading the output).
+- User documentation: getting started, logging, progress, framework integrations, migration guides (`print`, `tqdm`, Loguru, `logging`), configuration, a guide for programs that read Pace output, and a FAQ.
+
+[Unreleased]: https://github.com/Precision-AI-Inc/pace/compare/v0.0.1...HEAD
+[0.0.1]: https://github.com/Precision-AI-Inc/pace/releases/tag/v0.0.1

precisionai_pace-0.0.1/CLAUDE.md

@@ -0,0 +1,293 @@
+# Pace — Project Standards
+
+Apply these standards when writing, reviewing, or refactoring code in Pace. Read [docs/design.md](docs/design.md) before changing behaviour: it is the specification for the logger, the progress line format and the forecasting rules.
+
+---
+
+## Environment
+
+- Python 3.8+ is supported; develop on 3.9+ (pre-commit needs it), managed with `python -m venv .venv` (never conda)
+- Install: `pip install -e ".[dev]"` → installs all deps including pre-commit
+- Register hooks once: `pre-commit install`
+- CI runs the tests on 3.8 through 3.13. 3.8 runs on `ubuntu-22.04`, because `actions/setup-python` has no 3.8 build for `ubuntu-latest`.
+
+---
+
+## The rules that matter most
+
+1. **The core has no runtime dependencies.** `precisionai.pace` imports only the standard library. It is installed into users' training images and into other packages, and must never add to them. A framework adapter imports its framework only inside its own module, behind an extra (`[lightning]`, `[transformers]`).
+2. **The line format is a public contract.** Anything a consumer parses (the `[pace:N ...]` trailer) changes only as documented in `docs/design.md`: new optional keys within a major version, anything else is a new major version. A format change updates `docs/design.md` and the fixtures in `tests/fixtures/protocol/` in the same PR. The readable text before the trailer is for people and may change freely; never make a consumer depend on it.
+3. **Python 3.8 compatible.** See [Type hints](#type-hints) for what that rules out.
+4. **Never log secrets on the package's own initiative.** Pace never writes environment variables, configuration or credentials by itself, and labels stay short and are not repeated on every update.
+5. **Parsing is defensive.** Log lines are untrusted input. The parser bounds every size and value, never evaluates anything, and ignores (never raises on) a malformed or unsupported line.
+
+---
+
+## Project layout
+
+```
+precisionai/pace/
+  core.py, _env.py, _render.py, capture.py   # the logger
+  scopes.py        # track, progress, timed, phase, plan
+  protocol.py      # Record, the [pace:1 ...] trailer, parse_line, LineSplitter
+  forecast.py      # ScopeForecast, JobForecast
+  lightning.py, transformers.py, _adapters.py   # framework callbacks (extras only)
+  version.py       # installed package version
+  __init__.py      # re-exports only — no logic
+docs/              # Sphinx (HTML + LaTeX/PDF); design.md is the specification
+skills/adopt-pace/ # Claude Code skill that adds Pace to a repo; verify.py checks a log
+examples/          # runnable examples
+tests/             # mirrors package structure; fixtures/protocol/ holds format conformance cases
+```
+
+`precisionai` is a fixed, namespace-only top-level package (no logic, just an SPDX header) shared by Precision AI Python projects, which is what makes `precisionai.<namespace>.*` imports consistent across them.
+
+---
+
+## pyproject.toml — canonical config
+
+```toml
+[project]
+dynamic = ["version"]   # version comes from the git tag via setuptools-scm, never hardcoded
+requires-python = ">=3.8"
+dependencies = []       # see "The rules that matter most"
+
+[tool.setuptools_scm]
+version_scheme = "no-guess-dev"
+local_scheme = "no-local-version"
+fallback_version = "0.0.0"
+
+[tool.ruff]
+line-length = 120
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E","W","F","I","UP","B","SIM","N","C90","D","PT","RUF","PL","ANN","PERF","S","FA"]
+ignore = [
+    "E501",    # enforced by ruff-format
+    "SIM108",  # ternary readability
+    "D100","D104",          # module/package docstrings optional
+    "D203","D213",          # pydocstyle conflicts — always ignore these two
+    "PLR0913","PLR2004",    # arg count (progress scopes take several optional fields) + magic values in tests
+    "ANN401",              # Any is allowed for genuinely dynamic types
+]
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["F401"]
+"tests/**"       = ["D","PLR","ANN","S"]
+"docs/conf.py"   = ["E402","UP031","ANN","S","FA"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"          # enforces NumPy docstring style
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.lint.isort]
+known-first-party = ["precisionai"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true  # formats code blocks inside docstrings
+
+[tool.pytest.ini_options]
+addopts = "--cov=precisionai --cov-report=term-missing --cov-fail-under=90"
+
+[tool.coverage.report]
+fail_under = 90
+exclude_lines = ["pragma: no cover","if __name__ == .__main__.:",
+                 "raise ImportError","except ImportError","if TYPE_CHECKING:"]
+
+[tool.pyright]
+pythonVersion = "3.8"
+typeCheckingMode = "standard"
+reportMissingImports = false
+reportMissingModuleSource = false
+```
+
+---
+
+## pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks: [check-added-large-files (--maxkb=1800), check-yaml, check-json,
+            check-toml, end-of-file-fixer, trailing-whitespace,
+            check-merge-conflict, detect-private-key, debug-statements,
+            fix-byte-order-marker]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.17
+    hooks: [ruff (--fix), ruff-format]
+
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: python -m pyright
+        language: system
+        types: [python]
+        pass_filenames: false
+
+  - repo: local
+    hooks:
+      - id: pytest
+        entry: python -m pytest
+        language: system
+        args: [tests/, -q, --tb=short, --no-header]
+        always_run: true
+```
+
+---
+
+## Code style
+
+### License header
+- Every `.py` file starts with a two-line SPDX header, followed by a blank line before the module docstring (if any):
+  ```python
+  # Copyright 2026 Precision AI
+  # SPDX-License-Identifier: Apache-2.0
+  ```
+- No "CONFIDENTIAL" or proprietary banners — this codebase is Apache 2.0 licensed; any such banner is a bug.
+
+### Imports
+- All imports at the **top of the file** — never inside functions
+- Optional framework deps (adapters only): module-level `try/except ImportError` with a flag variable
+- No silent fallbacks unless mathematically equivalent (document why)
+- `__init__.py` re-exports only — no logic, no comments between import blocks
+- `__all__` must be **alphabetically sorted**
+
+```python
+# optional dep pattern (adapter modules only — never in the core)
+try:
+    import lightning.pytorch as pl  # type: ignore[import]
+    _LIGHTNING_AVAILABLE = True
+except ImportError:
+    _LIGHTNING_AVAILABLE = False
+
+# inside the class/function that needs it
+if not _LIGHTNING_AVAILABLE:
+    raise ImportError("lightning is required: pip install precisionai-pace[lightning]") from None
+```
+
+### Docstrings
+- **NumPy style** on all public functions, classes, and modules
+- Module docstrings: plain English, no prefixes (no P0/P1/P2, no "original", no labels)
+- One-line summary in **imperative mood** ("Compute …", "Return …", "Save …")
+- Blank line between summary and extended description (D205)
+
+### Type hints
+- Required on **all** function signatures (public and private) — enforced by ruff (`ANN`) and pyright
+- Every module with annotations starts with `from __future__ import annotations` (enforced by ruff `FA`). With it, `X | Y` and `list[int]` are fine **in annotations** on 3.8.
+- **Outside annotations**, code runs on 3.8: no `X | Y` in `isinstance`, casts or type aliases evaluated at runtime, no `match`, no `str.removeprefix`, no parenthesised context managers, no `dataclass(slots=True)` or `kw_only`. Use `isinstance(x, (A, B))`, `typing.Union`/`Optional` in runtime aliases, and `typing.TYPE_CHECKING` for import-only types.
+- Use `Any` from `typing` for genuinely dynamic types — don't use `object` when methods will be called on it
+- pyright config lives in `[tool.pyright]` in `pyproject.toml` — never pass type-checker flags inline
+
+### Comments
+- Only when the **why** is non-obvious
+- No section-divider comments that describe what the code already says
+- No cryptic labels, no TODO/FIXME without a ticket reference
+
+### Exception handling
+- Always `raise X from err` or `raise X from None` inside `except` blocks (B904)
+- Logging and progress calls never raise into user code because of a formatting or I/O problem; they degrade (drop the record, fall back to plain text) instead
+
+### General
+- `len()` returns `int` — never `int(len(...))`
+- Loop variables not used in the body → rename to `_`
+- `assert a and b` in tests → split into separate asserts
+- `@pytest.fixture` not `@pytest.fixture()`
+- `pytest.raises` always includes `match=` parameter
+- No `# type: ignore[attr-defined]` when `Any` already covers the attribute
+- Rates and intervals use `time.monotonic()`; wall-clock time is only for the printed timestamp
+
+---
+
+## README is the PyPI page
+
+`README.md` is published as the PyPI project description, where relative paths do not resolve. Every link and image in it is an absolute `https://github.com/Precision-AI-Inc/pace/blob/main/...` or `https://raw.githubusercontent.com/Precision-AI-Inc/pace/main/...` URL (enforced by `tests/test_readme.py`). Those URLs only load for anonymous visitors once the repository is public.
+
+---
+
+## Docs (Sphinx)
+
+```
+docs/
+  conf.py          # version from git tag, logo, LaTeX/fancyhdr, enumitem fix
+  index.rst        # toctrees: user guide, reading output, reference
+  design.md        # the specification — update it with any behaviour or format change
+  modules.rst      # autodoc for all public submodules
+  requirements.txt # sphinx, sphinx-rtd-theme, myst-parser, sphinx-autodoc-typehints
+  Makefile         # make html | make latexpdf | make clean
+  assets/logo.png
+```
+
+- `conf.py` copies root `README.md` → `docs/readme.md` at build time
+- Version read from `git describe --tags --exact-match`, falls back to `0.0.0`
+
+---
+
+## Testing
+
+- Mirror package structure: `tests/test_<module>.py`
+- Shared fixtures in `tests/conftest.py`
+- 90% coverage hard minimum — enforced by pytest and pre-commit
+- Format conformance cases live in `tests/fixtures/protocol/` as input lines plus expected parse results; consumers run the same files
+- Tests that depend on time use an injected clock, never `sleep`
+- Integration tests marked `@pytest.mark.integration` and excluded from default runs
+
+---
+
+## Repository files
+
+Besides the source layout above, the repository carries:
+
+```
+.gitattributes              # normalize line endings to LF; declare binary assets
+CHANGELOG.md                # Keep a Changelog format + Semantic Versioning
+CODE_OF_CONDUCT.md          # Contributor Covenant v2.1
+MANIFEST.in                 # sdist packaging — include docs/license/changelog, exclude tests/examples
+.github/
+  dependabot.yml            # weekly pip + github-actions update checks
+  ISSUE_TEMPLATE/
+    bug_report.yml
+    feature_request.yml
+    config.yml               # blank_issues_enabled: false + link to SECURITY.md
+  PULL_REQUEST_TEMPLATE.md
+  workflows/
+    ci.yml                   # dispatches to pre-commit.yml + unit-test.yml
+    pre-commit.yml
+    unit-test.yml
+    release.yml               # tag push → build, PyPI publish, GitHub Release
+```
+
+## Releasing
+
+- Versions are **never hardcoded** — `setuptools-scm` derives the package version from the current git tag (see the `pyproject.toml` block above). Tag with `vX.Y.Z`.
+- Update `CHANGELOG.md` under `[Unreleased]` as you go; move those entries to a new `## [X.Y.Z] - YYYY-MM-DD` section when cutting a release.
+- Pushing a `v*.*.*` tag triggers `.github/workflows/release.yml`: runs the full test matrix, builds the sdist/wheel, verifies the built version matches the tag, publishes to PyPI via trusted publishing (`id-token: write`, no stored API tokens), and creates a GitHub Release with generated notes.
+- CI checkout steps that build from git history (release builds, docs version detection) must use `fetch-depth: 0` — a shallow checkout has no tags for `setuptools-scm` or `git describe` to find.
+
+---
+
+## What to avoid
+
+| Pattern | Instead |
+|---|---|
+| A new entry in `dependencies` | Put it behind an extra, imported only by the adapter module |
+| Parsing the readable part of a progress line | Parse only the `[pace:N ...]` trailer |
+| Changing or removing a trailer key in place | New optional key, or a new major version (see `docs/design.md`) |
+| `isinstance(x, A \| B)`, `match`, other 3.10+ runtime syntax | `isinstance(x, (A, B))` and 3.8-compatible equivalents |
+| `time.time()` for rates or intervals | `time.monotonic()` |
+| `int(len(x))` | `len(x)` |
+| `assert a and b` (tests) | two separate asserts |
+| `@pytest.fixture()` | `@pytest.fixture` |
+| `pytest.raises(ValueError)` | `pytest.raises(ValueError, match="…")` |
+| `raise X` inside except | `raise X from None` or `raise X from err` |
+| Deferred imports inside functions | Module-level try/except with flag |
+| Cryptic prefixes (P0–P4, "original") | Plain descriptive names |
+| `# type: ignore[attr-defined]` on `Any` | Remove — redundant |
+| `# noqa` suppression | Fix the underlying issue |
+| Silent fallback for optional dep | Raise `ImportError` with install hint |

precisionai_pace-0.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,47 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at michael@precision.ai. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1.
+
+[homepage]: https://www.contributor-covenant.org

precisionai_pace-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+Thank you for your interest in contributing to Pace.
+
+## Setup
+
+Requires Python 3.8+ to use, and Python 3.9+ to run the pre-commit hooks.
+
+```bash
+git clone <repo-url>
+cd pace
+
+python -m venv .venv
+source .venv/bin/activate       # Windows: .venv\Scripts\activate
+
+pip install -e ".[dev]"
+pre-commit install
+```
+
+`pip install -e ".[dev]"` installs all dependencies including test tooling and pre-commit. `pre-commit install` registers the hooks so they run automatically on every commit.
+
+## Making changes
+
+1. Create a branch from `main`.
+2. Make your changes.
+3. Add or update tests — coverage must remain at or above 90%. Code must run on Python 3.8, and the core package must not gain a runtime dependency.
+4. Commit. Pre-commit hooks run automatically and will block the commit if any check fails.
+
+If a hook auto-fixes files (ruff lint/format), stage the changes and commit again.
+
+## Pre-commit hooks
+
+| Hook | What it checks |
+|---|---|
+| File hygiene | Large files (>1800 KB), trailing whitespace, merge conflicts, private keys, debug statements, BOM removal |
+| `ruff` | Linting and import sorting (auto-fix); includes `ANN` rules that enforce PEP 484 annotations |
+| `ruff-format` | Code formatting (auto-fix) |
+| `pyright` | Static type checking (pylance engine) — config in `[tool.pyright]` in `pyproject.toml` |
+| `pytest` | Full test suite with ≥ 90% coverage |
+
+Run all hooks manually without committing:
+
+```bash
+pre-commit run --all-files
+```
+
+## Code style
+
+- **Formatter / linter:** ruff (`line-length = 120`, Python 3.8 target).
+- **Type hints:** all functions (public and private) must have complete PEP 484 type annotations. Enforced at lint time by ruff (`ANN` rules) and statically by pyright. `Any` is allowed for genuinely dynamic types; explicit `Any` is preferred over `object` when methods will be called on a value.
+- **Docstrings:** NumPy style for all public functions, classes, and modules.
+- **Comments:** only where the _why_ is non-obvious. No inline narration of what the code does.
+
+See [CLAUDE.md](CLAUDE.md) for the full standard.
+
+## Tests
+
+```bash
+pytest                          # run all tests with coverage report
+pytest tests/test_version.py    # run a specific file
+pytest -k "version"             # run tests matching a pattern
+```
+
+Tests live in `tests/` and mirror the package structure. The coverage threshold (90%) is enforced both by `pytest` directly and by the pre-commit hook.
+
+## Pull requests
+
+- Keep PRs focused — one logical change per PR.
+- A change to the progress line format must update `docs/design.md` and the protocol fixtures in the same PR.
+- Write a clear description of what changed and why.
+- All pre-commit hooks must pass before requesting review.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the Apache License, Version 2.0.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).