etude-sdk 0.1.0__tar.gz

etude_sdk-0.1.0/.github/dependabot.yml

@@ -0,0 +1,21 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        update-types:
+          - minor
+          - patch
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      actions:
+        update-types:
+          - minor
+          - patch

etude_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,95 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  merge_group:
+
+# A new PR head supersedes its old proof. Main and merge-group runs keep their
+# own identity so independent integration proofs do not cancel each other.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # Scratch belongs to work in progress. Delivery clears it before publishing a
+  # landing candidate; queue and main runs never accept that exemption.
+  scratch-clear:
+    runs-on: ubuntu-latest
+    outputs:
+      candidate: ${{ steps.scratch.outputs.candidate }}
+    steps:
+      - uses: actions/checkout@v5
+      - name: Select landing candidates and enforce scratch cleanup
+        id: scratch
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+        run: |
+          if [ ! -d scratch ]; then
+            echo "scratch/ is missing"
+            exit 1
+          fi
+          EXTRA=$(find scratch -mindepth 1 ! -path 'scratch/.gitkeep' -print)
+          if [ -n "$EXTRA" ]; then
+            if [ "$EVENT_NAME" = "pull_request" ]; then
+              echo "Checkpoint: checks are deferred until scratch/ is clear." | tee -a "$GITHUB_STEP_SUMMARY"
+              echo "candidate=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+            echo "scratch/ must be clear before landing"
+            echo "$EXTRA"
+            exit 1
+          fi
+          echo "candidate=true" >> "$GITHUB_OUTPUT"
+
+  client-lint:
+    needs: [scratch-clear]
+    if: ${{ !cancelled() && needs.scratch-clear.outputs.candidate == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --locked
+      - run: uv run --no-sync ruff check .
+      - run: uv run --no-sync ruff format --check .
+      - run: uv run --no-sync mypy
+
+  client-test:
+    needs: [scratch-clear]
+    if: ${{ !cancelled() && needs.scratch-clear.outputs.candidate == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --locked
+      - name: Run the client tests with the outside network denied
+        run: uv run --no-sync python scripts/test_network.py uv run --no-sync pytest
+        timeout-minutes: 15
+
+  tests-result:
+    # A skipped check is not proof. Only PR checkpoints may skip the aggregate;
+    # a failed classifier must still produce a failing required check.
+    if: ${{ always() && (github.event_name != 'pull_request' || needs.scratch-clear.result != 'success' || needs.scratch-clear.outputs.candidate != 'false') }}
+    runs-on: ubuntu-latest
+    needs: [scratch-clear, client-lint, client-test]
+    steps:
+      - name: Aggregate check results
+        env:
+          SCRATCH_CLEAR: ${{ needs.scratch-clear.result }}
+          CLIENT_LINT: ${{ needs.client-lint.result }}
+          CLIENT_TEST: ${{ needs.client-test.result }}
+        run: |
+          failures=0
+          check_result() {
+            if [ "$2" = success ]; then
+              echo "PASS  $1"
+            else
+              echo "FAIL  $1 ($2)"
+              failures=1
+            fi
+          }
+          check_result scratch-clear "$SCRATCH_CLEAR"
+          check_result client-lint "$CLIENT_LINT"
+          check_result client-test "$CLIENT_TEST"
+          exit "$failures"

etude_sdk-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,39 @@
+name: Release
+
+# Pushing a tag vX.Y.Z publishes that version of etude-sdk to PyPI. PyPI trusts
+# this workflow by name (trusted publishing), so no token is stored anywhere.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - name: Refuse a tag that does not match the package version
+        run: |
+          version=$(uv version --short)
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "tag $GITHUB_REF_NAME does not match version $version in pyproject.toml"
+            exit 1
+          fi
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

etude_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+.etude/
+.lf/prompts/
+.lf/tmp/

etude_sdk-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

etude_sdk-0.1.0/AGENTS.md

@@ -0,0 +1,172 @@
+# Etude
+
+Conventions for people and coding agents working on this repository.
+
+## Units
+
+Use steps for scientific cadence and preserve absolute continuation coordinates.
+Use hours and dollars for machine rental windows, credentials, watchdogs and budgets.
+Distinguish training steps, learner transitions and optimizer updates/exposures.
+
+## Design
+
+Design around the domain's data structures and public APIs, with one code
+concept per real concept. Keep core types and entry points easy to find. Start
+with the smallest types and APIs that are right; every line must earn its place.
+
+A redesign deletes what it replaces, in the same change. Keep one
+implementation and one owner for each fact: no `_old`, `_new`, `v2_` or backup
+variants, and no compatibility shims unless a released database or a published
+API with outside users requires one. Git holds old versions.
+
+When code fails because it assumed a fixed context, prefer adapting to the
+context over adding a guard, allowlist or precondition that refuses.
+
+Name things for what they are (`Checkpoint`, not `CheckpointHelper`). Action
+functions start with a verb. Private helpers start with an underscore.
+
+## Python
+
+Use Python 3.12 and uv for every Python command (`uv run pytest`, never bare
+`python` or `pip`), in docs and scripts as well.
+
+Write fully typed Python: annotate parameters and returns on every function
+and method, including private helpers and tests, with `-> None` where it
+applies. Use 3.12 forms (`list[T]`, `T | None`). Represent structured domain
+data with named types; do not pass untyped dictionaries or positional tuples
+across application boundaries. Prefer precise unions and literals to `Any`. At
+untyped library or JSON boundaries, validate once and expose a typed
+interface; keep a necessary cast or suppression local, with its reason. Do not
+weaken a type to silence the checker.
+
+A nullable annotation means `None` is a real value; a default decides whether
+an argument may be omitted. Return `None` for expected absence only where the
+API defines it. Raise for violated invariants and impossible states, and never
+disguise a failure as an empty result.
+
+Put imports at the top and import explicitly from the defining module. There
+are two exceptions, each with a comment saying why. An optional dependency is
+imported where it is used. A command line or other top-level entry point
+imports what one command needs inside that command, so starting the program
+loads only what that command runs; keep these entry points as fast to start
+as possible, and keep the rule everywhere below them. Declare dependencies in
+`pyproject.toml`.
+
+## Comments and docs
+
+Give a substantial module a short opening note: its purpose, principal types
+and entry points, and any non-obvious ownership or data flow. Explain intent,
+invariants, units and algorithmic choices beside the code that depends on
+them. Keep docstrings short; include non-obvious contracts, side effects and
+failure behaviour. No `Args:`/`Returns:` sections that repeat a signature, no
+comments that restate code, and no comments that narrate a change.
+
+Wrong documentation is worse than none: update it with the behaviour or delete
+it. In user-facing docs, lead with an example and keep prose terse around it;
+tables are for lookup, not teaching.
+
+## Tests
+
+Test behaviour a user would care about, and assert on results. Mock side
+effects (network, subprocesses, paid services) but never assert on how a mock
+was called. Do not reshape production code for a test: no interface, factory
+or extra parameter that exists only for test doubles. Delete a flaky test
+instead of adding retries.
+
+## Development
+
+Before calling work done, review it as a sceptical maintainer would: can it be
+explained in one screen, does the API map to the real thing or to an accident
+of implementation, what breaks at 2 a.m. and will the logs say why, is each
+dependency and knob earning its keep, and would deleting code make it more
+true. Fix what that finds or record it.
+
+Make small coherent pull requests with useful descriptions and focused checks.
+Linux account/permission tests use a disposable container’s native filesystem,
+not macOS bind mounts (which can present different permission behavior). Keep
+fixture inputs below its private root home, then copy journals out after execution.
+Worker deadline tests resolve runner dependencies from the fixture image's local
+wheelhouse with networking disabled; downloading packages must not consume the
+short execution window used to test partial-output retention.
+
+Commit messages say what changed and why in a sentence to a paragraph, not a
+list of edits. Never add Co-Authored-By or other AI attribution footers.
+
+Keep secrets out of code, output and artifacts. Prefer running a command with
+the secret injected to reading the value. A raw value must never reach a
+terminal, log or chat: consume it inline or redirect it. If one leaks, say so
+and flag it for rotation without quoting it again.
+
+Launcher records use frozen Pydantic models with named constructor fields and
+model-owned JSON serialization. Keep `providers/runpod/http.py`,
+`providers/runpod/pod.py`, `providers/package.py` and `environment.py`
+standard-library-only: the RunPod guardian must start before
+client dependency installation. The client and each job use separate environments.
+
+Check before pushing: `uv run pytest`, `uv run mypy`, `uv run ruff check .` and
+`uv run ruff format --check .`. CI runs the tests with the outside network
+denied (`scripts/test_network.py`).
+
+## Code style
+
+Readability matters more now that code is cheap to write: optimise for the
+person reading it.
+
+**Names.** Prefer clarity over cleverness. Use one word per concept and use it
+everywhere. Every word in a path or name should be different from its
+neighbours and tell the reader something: `etude.launch.scheduler`, not
+`etude.launch.launcher`. Avoid words that say nothing, such as engine, service,
+contract, api, util or manager. Before choosing a name, an interface or a
+layout, look at what established tools call the same thing and say what you
+found.
+
+**Imports.** Write every import as a full path from the module that defines the
+name. Relative imports are a lint error. Put every import at the top of its
+module: an import inside a function is a lint error too. If that makes two
+modules import each other, move the shared part or pass it in; do not hide the
+cycle inside a function. Keep every `__init__.py` empty, so importing one
+module never loads the rest.
+
+**Layout.** Add a folder only when it has a rule a test can enforce, such as
+"nothing in here imports the scheduler". A theme is not a reason for a folder.
+
+**Records.** Anything stored or sent between machines is a frozen Pydantic
+model. Do not keep a second kind of record beside them.
+
+**Command line.** Use Typer. Every input is a `--flag`; do not add positional
+conventions a person has to remember, such as a bare `--` or `name=value`.
+Keep output plain, because agents and logs read it.
+
+**Python is the interface.** Work is described in Python, not in a config
+format. A command-line command is a thin way to call the same functions.
+
+**Dependencies.** Manage them with uv. The launcher and tracking use one set of
+versions for every dependency, from one lock file, whether they ship as one
+package or several. Each must work without the other being used. Code Etude runs on someone else's
+machine gets its own environment, separate from the job's. The one exception
+is anything that must start before an install can finish, such as the process
+that deletes a rented machine at its deadline: that stays standard library
+only.
+
+**Consequential actions are explicit.** Spending money, deleting something or
+publishing something is never a side effect of a command that reads as doing
+something else.
+
+**What a command may wait on.** Every command is one of three kinds and says
+which. A read answers from the database, at once, and says how fresh its answer
+is. An ask records what is wanted and returns with an id. Only a wait may
+depend on another machine, and it has a time limit. A command needs only what
+its kind implies: a read must work with no provider key and no network.
+
+**Measure by counting.** Machine load makes timings unreliable, so tests count
+what matters to a user: calls to a provider, a bucket, SSH and git, database
+queries, and modules imported at start-up. Pin those numbers in tests. A change
+to a path that reaches another machine comes with a counting test.
+
+Launcher vocabulary: Machine owns acquisition and provider facts; Rental owns
+only a paid window, keyed by its machine; RunAttempt is the allocation on any
+machine. Session is internal: one start of Etude's process on a machine, and its
+journal folder. The process itself is the worker (`etude worker`). Use rent and
+terminate for making and deleting paid machines. A record refers to another by
+its name or id as a plain `str`. While the launcher is a prototype its database
+has no migrations: change the schema version and refuse older files.

etude_sdk-0.1.0/LICENSE

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

etude_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.5
+Name: etude-sdk
+Version: 0.1.0
+Summary: Launch training runs on your own or rented machines and track what they record
+Project-URL: Repository, https://github.com/loopflowstudio/etude
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: numpy<3,>=1.26
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: typer<1,>=0.27
+Provides-Extra: s3
+Requires-Dist: boto3<2,>=1.35; extra == 's3'
+Description-Content-Type: text/markdown
+
+# Etude
+
+Launch training runs on your own or rented machines, and track what they record.
+
+```python
+# job.py
+from etude.launch.records import Job
+
+
+def runs() -> Job:
+    return Job(command="uv run python train.py", max_hours=2)
+```
+
+```python
+# train.py
+from etude.track.records import Step
+from etude.track.run import init
+
+run = init(experiment="capacity-pilot", clocks=[Step("updates", "optimizer updates")])
+for update in range(1, 1001):
+    loss = train_one_update()
+    run.log({"loss": loss}, updates=update)
+    if update % 500 == 0:
+        run.checkpoint(save_model(), updates=update)
+run.finish()
+```
+
+```sh
+etude launch job.py          # run it on this computer, an SSH host or a rented GPU
+etude status                 # where runs stand
+etude logs RUN               # what a run wrote
+etude reports write --open   # charts of every run, as one HTML file per experiment
+```
+
+Everything a run records goes to your own directory or S3 bucket. There is no
+server to run and no account to make. A run that loses its machine resumes from
+its last checkpoint on another, and reads back as one run.
+
+## Install
+
+Etude needs Python 3.12 and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv tool install etude-sdk          # the `etude` command
+uv add etude-sdk                   # the library, in a training project
+uv add 'etude-sdk[s3]'             # with S3 storage
+```
+
+## Read more
+
+- [Tracking](docs/tracking.md): runs, clocks, checkpoints, evaluations, reports.
+- [The launcher](docs/launcher.md): pools, SSH hosts, rented machines, cohorts,
+  limits and recovery.
+
+## Develop
+
+```sh
+uv sync
+uv run pytest
+uv run mypy
+uv run ruff check . && uv run ruff format --check .
+```
+
+[AGENTS.md](AGENTS.md) holds the conventions, for people and coding agents.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

etude_sdk-0.1.0/README.md

@@ -0,0 +1,68 @@
+# Etude
+
+Launch training runs on your own or rented machines, and track what they record.
+
+```python
+# job.py
+from etude.launch.records import Job
+
+
+def runs() -> Job:
+    return Job(command="uv run python train.py", max_hours=2)
+```
+
+```python
+# train.py
+from etude.track.records import Step
+from etude.track.run import init
+
+run = init(experiment="capacity-pilot", clocks=[Step("updates", "optimizer updates")])
+for update in range(1, 1001):
+    loss = train_one_update()
+    run.log({"loss": loss}, updates=update)
+    if update % 500 == 0:
+        run.checkpoint(save_model(), updates=update)
+run.finish()
+```
+
+```sh
+etude launch job.py          # run it on this computer, an SSH host or a rented GPU
+etude status                 # where runs stand
+etude logs RUN               # what a run wrote
+etude reports write --open   # charts of every run, as one HTML file per experiment
+```
+
+Everything a run records goes to your own directory or S3 bucket. There is no
+server to run and no account to make. A run that loses its machine resumes from
+its last checkpoint on another, and reads back as one run.
+
+## Install
+
+Etude needs Python 3.12 and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv tool install etude-sdk          # the `etude` command
+uv add etude-sdk                   # the library, in a training project
+uv add 'etude-sdk[s3]'             # with S3 storage
+```
+
+## Read more
+
+- [Tracking](docs/tracking.md): runs, clocks, checkpoints, evaluations, reports.
+- [The launcher](docs/launcher.md): pools, SSH hosts, rented machines, cohorts,
+  limits and recovery.
+
+## Develop
+
+```sh
+uv sync
+uv run pytest
+uv run mypy
+uv run ruff check . && uv run ruff format --check .
+```
+
+[AGENTS.md](AGENTS.md) holds the conventions, for people and coding agents.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).