visin 0.1.0__tar.gz

visin-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+.mypy_cache/
+site/

visin-0.1.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this package are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Until 1.0, a minor version may change
+the public API; a patch version never does.
+
+The release workflow writes each version's entry from the conventional commits since the previous
+one, together with anything written by hand under Unreleased.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-26
+
+### Added
+
+- `visin.init()`, the one call most scripts need: registers a run, or attaches to the one
+  `VISIN_TRAINING_UUID` names, and reports nothing when no server is configured.
+- `Run.log_epoch`, `log_test_results`, `log_benchmark`, `log_config`, `upload_visualization` and
+  `update`, sent from a background thread in the order they were made.
+- `train=` and `val=` on `log_epoch`, for the two curves Visin's charts read.
+- Safe retries: epochs and test results carry their own UUIDs, and a POST without one is repeated
+  only when it provably never reached the server.
+- Store and forward: reports wait on disk while Visin is unreachable and are sent when it answers.
+  `VISIN_MODE=offline` keeps every report on disk for a machine with no route to Visin.
+- `visin sync` and `visin.sync()`, which send kept reports, resume where they stopped, and never
+  send a benchmark or config twice.
+- `visin check`, which tests the connection and the token, and with `--write` creates and deletes
+  a test run.
+- `visin runs` and `visin.Api`, for reading projects, runs, epochs, test results and benchmarks,
+  with `Api.epochs_frame` for a pandas DataFrame.
+- `system_info()` for benchmarks and `system_metrics()` for the run's System tab, including GPUs
+  through PyTorch or `nvidia-smi`.
+- Keras and PyTorch Lightning callbacks.
+- Conversion of NumPy and PyTorch scalars; NaN and infinity are sent as gaps.
+- Only rank zero of a distributed job reports.
+- A crashed or terminated run still sends its epochs and is marked failed.
+- `Run.attach(..., mark_status=False)`, for a test or benchmark script that reports into a
+  training's run without changing its status.
+- `epoch_uuid=` on `log_test_results`, `log_benchmark` and `upload_visualization`, to name an epoch
+  directly, such as the one a checkpoint's file name records.
+- `Run.resumed`, and a resumed run is marked running again while it trains.
+- A warning when an epoch logged again is kept at its first recorded values.
+- `visin.enable_console_logging()`.
+
+### Fixed
+
+- github release flow
+
+[Unreleased]: https://github.com/visin-platform/visin-py/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/visin-platform/visin-py/releases/tag/v0.1.0

visin-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,100 @@
+# Contributing
+
+Thanks for helping. This page covers setting up, the checks a change has to pass, and how a release
+happens.
+
+## Set up
+
+```sh
+git clone https://github.com/visin-platform/visin-py
+cd visin-py
+make install          # .venv with every tool, plus the pre-commit hooks
+```
+
+`make help` lists every target. Each one runs the same command CI runs.
+
+## Before you open a pull request
+
+```sh
+make check
+```
+
+This runs, in order:
+
+| Target | What it checks |
+| --- | --- |
+| `make lint` | `ruff check` and `ruff format --check`. `make format` fixes most findings. |
+| `make typecheck` | `mypy --strict` over the package. |
+| `make coverage` | The whole test suite, failing if coverage drops below the floor in `pyproject.toml`. |
+| `make build` | Builds the sdist and wheel, and checks their metadata with `twine check --strict`. |
+| `make docs` | Builds the documentation site with `mkdocs build --strict`, so a broken link or reference fails. |
+
+`make contract` checks every request the package sends against Visin's API spec. It reads the spec
+from `VISIN_OPENAPI`, or from a Visin checkout next to this one at `../visin`. CI runs it against
+Visin's main branch.
+
+The coverage floor sits just below current coverage. Raise it when you add tests, and never lower it
+to make a change pass.
+
+## Where things are
+
+The package's layout, and the reasoning behind its main decisions, are in
+[How it is built](https://visin-platform.github.io/visin-py/architecture/). The tests mirror the package, and
+[tests/README.md](https://github.com/visin-platform/visin-py/blob/main/tests/README.md) says what each file covers.
+
+## Writing a change
+
+- **Keep the loop safe.** Nothing in `Run` may raise into a training loop unless `strict=True` is
+  set. Report problems through `_handle`.
+- **New request fields** must exist in Visin's API. The contract test fails on a field the server
+  would strip.
+- **Support Python 3.9.** CI tests 3.9 to 3.14. `from __future__ import annotations` makes the
+  newer annotation syntax safe. Runtime expressions such as `isinstance(x, int | str)` are not.
+- **No new runtime dependencies** without a strong reason. The package goes into any training image,
+  and `requests` is its only dependency. Optional features belong behind an extra.
+- **Test what the change promises**, through the public API where you can, using the fakes in
+  `tests/fakes.py`. No test may touch the network or `~/.visin`; `tests/conftest.py` enforces this.
+- **Documentation:** a user-facing change updates the relevant page under `docs/`, and docstrings
+  feed the API reference.
+
+## Commit messages
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/), because the release
+workflow builds the changelog and picks the version from them:
+
+| Prefix | Changelog section | Version bump |
+| --- | --- | --- |
+| `feat:` | Added | minor |
+| `fix:` | Fixed | patch |
+| `perf:` | Changed | patch |
+| `feat!:`, or a `BREAKING CHANGE:` footer | Breaking changes | major (minor before 1.0) |
+| `docs:`, `test:`, `ci:`, `chore:`, `refactor:`, `build:`, `style:` | not listed | patch, when released |
+
+For anything a user should know that a commit subject cannot say, add a line under `## [Unreleased]`
+in `CHANGELOG.md`. The release keeps it.
+
+## Releasing
+
+A maintainer runs the **Release** workflow from the Actions tab, and that one run does everything:
+
+1. runs the full CI suite;
+2. works out the version from the commits since the last tag, or uses the one given
+   (`patch`, `minor`, `major` or `1.4.0`);
+3. writes `src/visin/_version.py` and the `CHANGELOG.md` entry, commits `chore(release): X.Y.Z`
+   and tags `vX.Y.Z`;
+4. builds, and publishes to PyPI through trusted publishing, so no API token is stored anywhere;
+5. creates the GitHub release with the changelog entry and the built files attached;
+6. publishes the documentation.
+
+Choose `testpypi` as the target to rehearse this. That builds and publishes to TestPyPI, and commits,
+tags and releases nothing.
+
+`python scripts/release.py --dry-run` shows locally what the next release would be.
+
+### One-time setup
+
+- On PyPI and TestPyPI, add a trusted publisher for `visin-platform/visin-py`, workflow `release.yml`,
+  with the environments `pypi` and `testpypi`.
+- In the repository settings, create those two environments. Adding required reviewers to `pypi`
+  makes every release wait for approval.
+- Under **Pages**, set the source to **GitHub Actions**.

visin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toomas Tahves
+
+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.

visin-0.1.0/Makefile

@@ -0,0 +1,57 @@
+# Every check CI runs, runnable here. `make check` is the one to run before a PR.
+#
+# Uses .venv when it exists (make install creates it), the PATH otherwise, which
+# is how CI runs the same targets.
+
+VENV ?= .venv
+BIN := $(if $(wildcard $(VENV)/bin/python),$(VENV)/bin/,)
+PYTHON ?= python3
+
+.DEFAULT_GOAL := help
+.PHONY: help install lint format typecheck test coverage contract build docs docs-serve check clean
+
+help: ## List the targets
+	@grep -E '^[a-z-]+:.*## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*## "}; {printf "  make %-11s %s\n", $$1, $$2}'
+
+install: ## Create .venv with every dev tool, and install the git hooks
+	$(PYTHON) -m venv $(VENV)
+	$(VENV)/bin/pip install --upgrade pip
+	$(VENV)/bin/pip install -e '.[dev]'
+	$(VENV)/bin/pre-commit install
+
+lint: ## Lint and check formatting (ruff)
+	$(BIN)ruff check .
+	$(BIN)ruff format --check .
+
+format: ## Fix formatting and the lint findings ruff can fix
+	$(BIN)ruff format .
+	$(BIN)ruff check --fix .
+
+typecheck: ## Type-check the package (mypy, strict)
+	$(BIN)mypy
+
+test: ## Run the tests
+	$(BIN)pytest
+
+coverage: ## Run the tests with coverage; fails under the floor in pyproject.toml
+	$(BIN)pytest --cov --cov-report=term-missing --cov-report=xml
+
+contract: ## Check every request against Visin's API spec (needs VISIN_OPENAPI or ../visin)
+	VISIN_REQUIRE_CONTRACT=1 $(BIN)pytest tests/contract
+
+build: ## Build the sdist and wheel, and check their metadata
+	rm -rf dist
+	$(BIN)python -m build
+	$(BIN)twine check --strict dist/*
+
+docs: ## Build the documentation site, failing on any warning
+	$(BIN)mkdocs build --strict
+
+docs-serve: ## Serve the documentation with live reload
+	$(BIN)mkdocs serve
+
+check: lint typecheck coverage build docs ## Everything CI checks
+	@echo "all checks passed"
+
+clean: ## Remove build, test and docs output
+	rm -rf dist site .coverage coverage.xml .pytest_cache .mypy_cache .ruff_cache

visin-0.1.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: visin
+Version: 0.1.0
+Summary: Report training runs, epochs, test results, benchmarks and prediction frames to Visin, and read them back.
+Project-URL: Homepage, https://github.com/visin-platform/visin-py
+Project-URL: Source, https://github.com/visin-platform/visin-py
+Project-URL: Issues, https://github.com/visin-platform/visin-py/issues
+Project-URL: Changelog, https://github.com/visin-platform/visin-py/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/visin-platform/visin-py#readme
+Author: Toomas Tahves
+License-Expression: MIT
+License-File: LICENSE
+Keywords: computer-vision,experiment-tracking,machine-learning,mlops,visin
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: coverage>=7.10; extra == 'dev'
+Requires-Dist: jsonschema>=4.18; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'dev'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pandas>=1.3; extra == 'dev'
+Requires-Dist: pre-commit>=3.5; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=6.1; extra == 'dev'
+Requires-Dist: types-requests; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.3; extra == 'pandas'
+Provides-Extra: system
+Requires-Dist: psutil>=5.8; extra == 'system'
+Provides-Extra: test
+Requires-Dist: coverage>=7.10; extra == 'test'
+Requires-Dist: jsonschema>=4.18; extra == 'test'
+Requires-Dist: pandas>=1.3; extra == 'test'
+Requires-Dist: pytest-cov>=5; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# visin
+
+[![CI](https://github.com/visin-platform/visin-py/actions/workflows/ci.yml/badge.svg)](https://github.com/visin-platform/visin-py/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/visin)](https://pypi.org/project/visin/)
+[![Python](https://img.shields.io/pypi/pyversions/visin)](https://pypi.org/project/visin/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/visin-platform/visin-py/blob/main/LICENSE)
+
+Send training runs to [Visin](https://github.com/visin-platform/visin): epochs, test results,
+benchmarks, prediction frames and configs. Read them back for analysis.
+
+```sh
+pip install visin
+```
+
+```python
+import visin
+
+with visin.init("unet baseline", project="road-seg") as run:
+    for epoch in range(1, 21):
+        train_loss, val_loss, val_iou = train_one_epoch()
+        run.log_epoch(epoch, train={"loss": train_loss}, val={"loss": val_loss, "mean_iou": val_iou})
+```
+
+Point it at your Visin with two environment variables. Without them, the same script runs and
+reports nothing.
+
+```sh
+export VISIN_URL=https://vision-api.example.com
+export VISIN_TOKEN=…            # a project token, from the project's Settings → API Tokens
+visin check --write             # confirm this machine can report
+```
+
+## What it does for you
+
+- **Never stops your training.** Reports go out from a background thread, and failures are logged,
+  never raised.
+- **Retries safely.** Epochs and test results carry their own ids, so a retried request is never
+  stored twice.
+- **Survives the network.** Reports wait on disk while Visin is unreachable, and are sent when it
+  answers. With `VISIN_MODE=offline`, a compute node with no route to Visin keeps everything for
+  `visin sync`.
+- **Keeps crashed runs.** A run that crashes, or that the scheduler terminates, still sends its
+  epochs and is marked failed.
+- **Takes metrics as they are.** NumPy and PyTorch scalars are converted, and NaN becomes a gap in
+  the chart.
+- **Reports once in distributed jobs.** Only rank zero reports.
+
+## More than epochs
+
+```python
+run.log_test_results(12, {"day": {"car": {"iou": 0.74}}, "night": {"car": {"iou": 0.61}}})
+run.log_benchmark({"device": "cuda", "batch_size": 1, "fps": 119.0})  # machine details filled in
+run.upload_visualization(12, "renders/overlay_0001.png", kind="overlay")
+run.log_config(args)  # argparse, dataclass, pydantic, Hydra…
+```
+
+## Frameworks
+
+```python
+from visin.integrations.lightning import VisinCallback  # or visin.integrations.keras
+
+trainer = L.Trainer(callbacks=[VisinCallback(name="segformer b2", project="road-seg")])
+```
+
+## Reading runs back
+
+```python
+api = visin.Api()
+for run in api.trainings(project="road-seg", status="completed"):
+    frame = api.epochs_frame(run)  # pip install 'visin[pandas]'
+```
+
+## Documentation
+
+**[visin-platform.github.io/visin-py](https://visin-platform.github.io/visin-py/)** has the
+getting-started guide, guides to offline use and each framework, and the API reference.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/visin-platform/visin-py/blob/main/CONTRIBUTING.md). In
+short: `make install`, then `make check` before a pull request. Changes are listed in the
+[changelog](https://github.com/visin-platform/visin-py/blob/main/CHANGELOG.md).
+
+## License
+
+MIT

visin-0.1.0/README.md

@@ -0,0 +1,86 @@
+# visin
+
+[![CI](https://github.com/visin-platform/visin-py/actions/workflows/ci.yml/badge.svg)](https://github.com/visin-platform/visin-py/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/visin)](https://pypi.org/project/visin/)
+[![Python](https://img.shields.io/pypi/pyversions/visin)](https://pypi.org/project/visin/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/visin-platform/visin-py/blob/main/LICENSE)
+
+Send training runs to [Visin](https://github.com/visin-platform/visin): epochs, test results,
+benchmarks, prediction frames and configs. Read them back for analysis.
+
+```sh
+pip install visin
+```
+
+```python
+import visin
+
+with visin.init("unet baseline", project="road-seg") as run:
+    for epoch in range(1, 21):
+        train_loss, val_loss, val_iou = train_one_epoch()
+        run.log_epoch(epoch, train={"loss": train_loss}, val={"loss": val_loss, "mean_iou": val_iou})
+```
+
+Point it at your Visin with two environment variables. Without them, the same script runs and
+reports nothing.
+
+```sh
+export VISIN_URL=https://vision-api.example.com
+export VISIN_TOKEN=…            # a project token, from the project's Settings → API Tokens
+visin check --write             # confirm this machine can report
+```
+
+## What it does for you
+
+- **Never stops your training.** Reports go out from a background thread, and failures are logged,
+  never raised.
+- **Retries safely.** Epochs and test results carry their own ids, so a retried request is never
+  stored twice.
+- **Survives the network.** Reports wait on disk while Visin is unreachable, and are sent when it
+  answers. With `VISIN_MODE=offline`, a compute node with no route to Visin keeps everything for
+  `visin sync`.
+- **Keeps crashed runs.** A run that crashes, or that the scheduler terminates, still sends its
+  epochs and is marked failed.
+- **Takes metrics as they are.** NumPy and PyTorch scalars are converted, and NaN becomes a gap in
+  the chart.
+- **Reports once in distributed jobs.** Only rank zero reports.
+
+## More than epochs
+
+```python
+run.log_test_results(12, {"day": {"car": {"iou": 0.74}}, "night": {"car": {"iou": 0.61}}})
+run.log_benchmark({"device": "cuda", "batch_size": 1, "fps": 119.0})  # machine details filled in
+run.upload_visualization(12, "renders/overlay_0001.png", kind="overlay")
+run.log_config(args)  # argparse, dataclass, pydantic, Hydra…
+```
+
+## Frameworks
+
+```python
+from visin.integrations.lightning import VisinCallback  # or visin.integrations.keras
+
+trainer = L.Trainer(callbacks=[VisinCallback(name="segformer b2", project="road-seg")])
+```
+
+## Reading runs back
+
+```python
+api = visin.Api()
+for run in api.trainings(project="road-seg", status="completed"):
+    frame = api.epochs_frame(run)  # pip install 'visin[pandas]'
+```
+
+## Documentation
+
+**[visin-platform.github.io/visin-py](https://visin-platform.github.io/visin-py/)** has the
+getting-started guide, guides to offline use and each framework, and the API reference.
+
+## Contributing
+
+See [CONTRIBUTING.md](https://github.com/visin-platform/visin-py/blob/main/CONTRIBUTING.md). In
+short: `make install`, then `make check` before a pull request. Changes are listed in the
+[changelog](https://github.com/visin-platform/visin-py/blob/main/CHANGELOG.md).
+
+## License
+
+MIT

visin-0.1.0/SECURITY.md

@@ -0,0 +1,22 @@
+# Security
+
+## Reporting a vulnerability
+
+Please don't open a public issue. Report it privately through GitHub's
+[security advisories](https://github.com/visin-platform/visin-py/security/advisories/new) for this
+repository. Include what you found, how to reproduce it, and which version you tested.
+
+You will get a reply within a week. A fix is released as a patch version, and the advisory is
+published with it.
+
+## Supported versions
+
+Fixes go into the latest release. Upgrading is the fix for older versions.
+
+## What this package does with your credentials
+
+- The token is sent only as an `Authorization: Bearer` header, and only to the configured `VISIN_URL`.
+- File uploads go to a signed URL from a separate HTTP session, which never carries the token.
+- The token is never written to disk. Reports kept for `visin sync` hold request bodies only, and
+  `sync` sends them with the credentials configured when it runs.
+- TLS verification is on unless `VISIN_VERIFY_SSL=0` is set.

visin-0.1.0/docs/architecture.md

@@ -0,0 +1,91 @@
+# How it is built
+
+This page is for people working on the package. It covers where each thing lives and why it works
+the way it does.
+
+## The files
+
+```text
+src/visin/
+├── __init__.py          the public API: everything a user imports comes from here
+├── run.py               Run and init: everything a training script writes
+├── api.py               Api: reading runs back
+├── offline.py           sync() and pending(): sending reports kept on disk
+├── system.py            system_info() and system_metrics()
+├── errors.py            VisinError and its subclasses
+├── cli.py, __main__.py  the `visin` command
+├── integrations/
+│   ├── keras.py         Keras callback
+│   ├── lightning.py     PyTorch Lightning callback
+│   └── _metrics.py      sorting flat metric names into train/val/test
+├── _internal/           machinery; not public, may change in any release
+│   ├── config.py        settings from the environment and arguments
+│   ├── transport.py     HTTP: retries, response unwrapping, signed uploads
+│   ├── serialize.py     NumPy/tensors/NaN into JSON Visin accepts
+│   ├── reports.py       what each kind of report is, and how it is delivered
+│   ├── sender.py        the background thread reports are sent from
+│   └── spool.py         reports on disk: the file format and syncing it
+└── _version.py          the version, and the only place it is written
+```
+
+The rule of thumb: a module at the top level is something a user touches, and `_internal` is how it
+works.
+
+## One report, from call to server
+
+```text
+run.log_epoch(...)                       run.py: validate, convert to JSON, build an op
+   │   {"op": "epoch", "body": {...}}
+   ▼
+Sender queue ──► background thread       sender.py: one thread, so order is kept
+   │
+   ▼
+deliver(client, op)                      reports.py: POST /epochs/upload; a 409 counts as delivered
+   │
+   ├─ delivered ──────────────► done
+   ├─ refused (4xx, 500) ─────► logged and counted; retrying would not help
+   └─ unreachable (5xx/down) ─► spool.py: appended to ~/.visin/runs/<uuid>.jsonl,
+                                  sent by the run once Visin answers, or by `visin sync`
+```
+
+Every write is first an **op**: a small JSON dict naming its kind and carrying its request body.
+Because an op is data, the same op can be sent at once, written to disk, and sent from disk a week
+later by `visin sync`, and all three go through the one `deliver` function. There is a single code
+path for sending.
+
+## Decisions worth knowing
+
+**Nothing raises into the training loop.** A metrics backend is not worth a training job. Failures
+are logged and counted, and `finish` summarises them. `strict=True` exists for tests.
+
+**Retries depend on the request, not on its method.** `transport.py` retries on its own terms
+instead of leaving it to urllib3, because a POST is only safe to repeat if it carries its own id.
+Runs, epochs and test results do: epoch UUIDs are `uuid5(run, epoch)`, and a repeat is answered 409.
+Benchmarks and configs do not, so they are retried only when the request provably never reached
+the server: the connection failed, or the rate limiter or auth refused it before any handler ran.
+500 is never retried, as Visin documents.
+
+**One sender thread.** Writes depend on each other: a run is created before its epochs, and an
+epoch before its test results. Keeping them in order costs less than recovering when they arrive
+out of order.
+
+**The run is created synchronously.** `init` returns only once the server has the run, or once it
+is known to be unreachable and the creation has been kept on disk. So an epoch can never arrive
+before its run.
+
+**Files are copied at the call.** Scripts render each epoch's frames under the same names, so the
+original may hold the next epoch's image by the time a queued upload runs.
+
+**SIGTERM becomes SystemExit**, but only if nobody else handles it. Otherwise a scheduler's
+termination skips `atexit`, and the run loses its queued epochs and stays "running" forever.
+
+**No default server.** Unset means disabled. A hard-coded address once sent a copied script's runs
+to somebody else's Visin.
+
+## The API contract
+
+`tests/contract/test_openapi.py` runs every public entry point against a fake server and checks each
+request against Visin's published OpenAPI spec. A request that fails its schema, hits a path that no
+longer exists, or carries a field the server would silently strip, fails the test. CI runs it
+against Visin's main branch weekly, so an API change that would break this package shows up without
+anyone having to remember it.

visin-0.1.0/docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

visin-0.1.0/docs/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"