letify 2.4.7__tar.gz → 2.5.0__tar.gz

letify-2.5.0/CLAUDE.md

@@ -0,0 +1,157 @@
+# CLAUDE.md
+
+Guidance for AI agents working in this repository. Read this before writing code, documentation or commits.
+
+## Hard rules
+
+These are not preferences. Breaking one means the change gets reverted.
+
+1. **Never add a co-author trailer.** Do not add `Co-Authored-By` lines for Claude or any other agent. Commits are authored by the repository owner alone.
+2. **Never use an em-dash.** Not in code, comments, docstrings, documentation, commit messages or pull request bodies. Use a hyphen, a comma, a colon or a second sentence instead. This applies to the en-dash used as punctuation as well.
+3. **Code comments and docstrings are English only.** No exceptions, including in files whose documentation is Korean. Identifiers, log messages and error strings are English too.
+4. **Commit subjects use a capitalized type prefix followed by a colon.** For example `Feat: Add the Colab provider`, `Fix: Release the session lock when exec raises`, `Docs: Describe the blob store layout`. Use the imperative mood and name the thing that changed. Allowed prefixes: `Feat`, `Fix`, `Docs`, `Refactor`, `Test`, `Perf`, `Chore`, `Build`.
+5. **Never commit secrets.** Access tokens, SSH private keys and account credentials belong in the environment or in `~/.letify/accounts`, never in tracked files. The project's `.letify/` holds project defaults only.
+
+## How this project is built
+
+Spec driven and test driven, in that order. The sequence for any change that is not a
+typo fix is: settle the spec, write the test that would prove it, then write the code.
+
+### Spec first
+
+`docs/SPEC.md` is the single source of truth for what the system does. Code follows it,
+not the other way round.
+
+1. **Change the spec before the code.** If a change alters behaviour, edit the section of
+   `docs/SPEC.md` that describes it first. If no section describes it, add one. A change
+   with no spec entry has nowhere to be checked against.
+2. **A spec change is a hypothesis, not a settled requirement.** In research, whether a
+   design is right is decided by the experiment. So a design changing experiment edits the
+   spec on its own branch, and the verdict on the pull request, adopted or rejected, is
+   what decides whether that spec change reaches `develop`.
+3. **The spec records decisions only.** What the system does, the formula it uses, the
+   value chosen. Derivations, measurement tables and comparisons go in the pull request
+   body, and the spec links to it.
+4. **`docs/INTENT.md` sits above the spec.** It holds the claims the design is meant to
+   prove, with stable ids (`N1`, `N2`, ...). An experiment lists the claim it tests. When
+   evidence contradicts a claim, say so and propose the edit rather than leaving it
+   standing.
+
+### Test driven
+
+A test is written to state the expected behaviour before the code that satisfies it
+exists. The cycle is red, then green, then tidy.
+
+1. **Write the failing test first.** It names the behaviour, so the name reads as a
+   sentence: `test_a_handle_from_another_runtime_is_refused`. Run it and watch it fail for
+   the reason you expect, because a test that passes before the code is written is testing
+   nothing.
+2. **Write the smallest code that makes it pass.** Then clean up with the test as the net.
+3. **Every test traces to a spec section.** If you cannot say which section a test is
+   pinning, either the spec is missing an entry or the test is asserting an accident of the
+   implementation. Both are worth fixing.
+4. **A bug gets a failing test before a fix.** That is how it is shown to be real, and how
+   it stays fixed.
+5. **Exercise the real code path.** The `Local` provider starts the same worker behind the
+   same framed protocol a remote runtime uses, so anything testable through it should be.
+   A fake belongs only where the real thing needs a live account, a network or a GPU, and
+   it goes in `tests/conftest.py` rather than being written twice.
+6. **Coverage is a smoke detector, not a goal.** A line with no test is a question to ask.
+   Chasing a percentage with tests that assert nothing makes the suite worse, and a line
+   that genuinely needs a live service is marked `# pragma: no cover` with the reason.
+
+### What this rules out
+
+- Writing the implementation first and the tests afterwards to match whatever it happened
+  to do. That blesses accidents as behaviour.
+- Changing behaviour without touching the spec. The next reader then has two sources of
+  truth that disagree.
+- Deleting or loosening a test to make a change pass. If the test was wrong, say why in
+  the commit; if the behaviour changed on purpose, the spec changes with it.
+
+## Writing style
+
+Everything written here is read by people first. Documentation, pull request bodies and commit messages follow the same rules.
+
+- Lead with the conclusion, then the evidence.
+- One idea per sentence. If a sentence needs a second read, split it.
+- Name the concrete thing: the function, the file, the setting, the number. No metaphors and no personification.
+- Numbers carry units and a comparison. Not `latency 150` but `round trip 150 ms, measured from Seoul to a Colab runtime in the United States`.
+- Define every label the first time it appears.
+- Keep it as short as it can be while still complete.
+
+## Documentation layout
+
+| File | Holds |
+|---|---|
+| `README.md` | What letify is and how to use it, for a first-time reader |
+| `docs/locales/README_ko.md` | Korean translation of `README.md`, kept in sync |
+| `PROJECT.md` | The feature set and the public API surface |
+| `docs/INTENT.md` | Problem, goals, claims (`N1`, `N2`, ...), constraints, non-goals, open decisions |
+| `docs/SPEC.md` | The current design. Decisions only, one feature per section, each section opening with a one-line summary |
+| `docs/COMPONENT.md` | Class relationships, responsibilities and the vocabulary of the project |
+| `docs/NETWORK.md` | Transport paths, measured latency and throughput, tunnel selection |
+| `docs/guide/` | Task-oriented guides, English in `docs/guide/`, Korean in `docs/guide/ko/` |
+
+Rules for these documents:
+
+- `docs/SPEC.md` records only the current state. No "previously we used", no "tried and rejected". History lives in Git and in pull request bodies.
+- Derivations, measurement tables and comparisons go in the experiment pull request. The spec links to it.
+- Section titles name features and stay stable. Before renaming one, give the heading an id comment so its history continues.
+- Keep the English and Korean documentation in step. A change to one is incomplete until the other matches.
+
+## ResearchTree conventions
+
+This repository uses [ResearchTree](https://darkpyonix.github.io/researchtree/) for performance work. One branch is one experiment and one pull request is its lab note.
+
+- Root branch: `develop`. Experiment branch prefix: `feat/`. Both are set in `.researchtree`.
+- Never open an experiment pull request against `main`.
+- One hypothesis per branch. Two ideas are two branches.
+- Give each experiment its own `git worktree`. Do not switch branches in a checkout that has a job running.
+- The first YAML block at the top of the pull request body is the record. Keep it valid and first.
+- Reuse existing metric keys so experiments stay comparable: `efficiency_pct`, `rtt_ms`, `step_s`, `syncs_per_step`, `setup_s`, `transfer_mbps`.
+- Do not merge, close, tag or push to `develop` unless the owner asks.
+
+## Code layout
+
+The Python package is pure Python and links no Python extension. The package lives in `letify/` at the repository root. letify-core, the Rust workspace in `letify-core/`, is built in CI and shipped as plain binaries in `letify/remoting/lib/` inside platform wheels.
+
+```
+letify/
+  __init__.py       Public surface. Everything a user needs is re-exported here
+  errors.py         Exception hierarchy
+  launcher.py       Launcher, the public entry point
+  cli.py            The letify command line
+  stubs.py          Provider type stubs for editor completion
+  config/           .letify/config.toml loading, schema, login and credential files
+  declare/          Env, Instance and the @let.function callable
+  protocol/         Codec, framing, reference types, the remote worker and driver
+  runtime/          Channel, session, pool, lease, bootstrap and telemetry
+  store/            Content addressed blob store, volumes and backends
+  providers/        Provider base class and one module per provider
+  remoting/         CUDA API forwarding, used only where a low-latency path exists
+  _vendor/          Vendored third party code
+letify-ext/         VS Code extension (TypeScript) showing quota and GPU activity from the CLI's --json output
+```
+
+Conventions:
+
+- Every module has a docstring saying what it owns and what it does not.
+- Type hints on every public function. `from __future__ import annotations` at the top of each module.
+- No provider-specific import at package import time. A missing optional dependency disables that provider and nothing else.
+- Errors distinguish infrastructure failure from user code failure. Infrastructure failure may be retried, user code failure never is.
+- Never fall back to local execution silently. Raise instead.
+
+## Versions and releases
+
+There is one version for the Python package, letify-core, the VS Code extension and the tag. `pyproject.toml` `[project].version` is the source of truth. Change it only with `python scripts/version.py set <version>`, commit that as `Chore: Set the version to <version>`, and tag `v<version>`. CI fails when any file or the tag disagrees. The files and the release workflow are in `docs/SPEC.md`, Versioning and releases, and the steps in `docs/guide/08-releasing.md`.
+
+## Dependencies
+
+There is one install and no extras:
+
+```
+uv add letify
+```
+
+letify installs cloudpickle and blake3 only, because it lives inside researchers' repositories. Provider tools run out of process through uv, never in the user's `.venv`: Colab through `uv tool run --from google-colab-cli colab`, Modal through a separate uv environment. Elice and the GCS blob store use the standard library HTTP client. Do not add a dependency to `pyproject.toml`.

{letify-2.4.7 → letify-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: letify
-Version: 2.4.7
+Version: 2.5.0
 Summary: Declarations that become infrastructure.
 Project-URL: Homepage, https://github.com/DarkPyonix/letify
 Project-URL: Documentation, https://github.com/DarkPyonix/letify/tree/main/docs

letify-2.5.0/PROJECT.md

@@ -0,0 +1,301 @@
+# PROJECT
+
+> The feature set and the public API of letify. For why each decision is what it is, see [docs/SPEC.md](docs/SPEC.md); for the vocabulary, see [docs/COMPONENT.md](docs/COMPONENT.md).
+
+## What letify is
+
+A declarative infrastructure library for Python. You declare what a function needs and where it belongs, and letify arranges the session, the environment, the data and the teardown.
+
+```python
+import letify
+
+let = letify.Launcher()
+colab = let.providers.colab_a
+
+@let.function(device=colab.G4, host="remote")
+def train(lr, bs):
+    ...
+
+train(lr=1e-4, bs=32)
+```
+
+## Features
+
+### Placements, no mechanisms
+
+A declaration says where the accelerator is and where the host code runs. It never names a transport or a mode. How long a session lives is the `keep_alive` block around the calls.
+
+| Argument | Says | Default |
+|---|---|---|
+| `device` | which provider, account, accelerator and how many of it | required |
+| `host` | where the host code runs: `"local"` or `"remote"` | `"local"` |
+
+Core count and memory are not arguments. They arrive with the shape the provider registered, and a provider offering several sizes registers them as separate shapes. `lab.A100 * 2` is the same shape taking two cards.
+
+There is no width argument and no session ceiling. A provider entry declares what the account has, and that inventory is the only thing bounding how much runs at once:
+
+```toml
+[lab_a100.devices]
+A100 = { indices = "0-3" }   # four cards in a shared box are ours
+
+[colab_pro.devices]
+G4 = { count = 2 }           # two concurrent sessions on this account
+```
+
+`indices` is for a machine letify shares with other people: it takes only those registered indices that are actually free when a session starts, and sets the session's visible devices so the code inside sees its cards as 0 upward. `count` is for a provider that assigns the device itself.
+
+### Providers
+
+Four kinds, three of them remote. A provider object is one account on one kind of infrastructure, declared once in a configuration file and reached by alias.
+
+| Provider | Kind | Storage | Session created by |
+|---|---|---|---|
+| `Local` | `local` | persistent | a subprocess of this machine |
+| `Modal` | `modal` | persistent | a Modal sandbox |
+| `Colab` | `colab` | ephemeral | `colab new` through the official CLI |
+| `Shell` | `shell` | ephemeral, overridable | SSH |
+| `Tunnel` | `tunnel` | ephemeral, overridable | Tailscale or frp, then SSH |
+| `Elice` | `elice` | persistent | an allocation on the Elice Cloud API |
+
+`Shell` is the base for every machine letify reaches by running commands on it. `Colab`, `Tunnel` and `Elice` are its subclasses and differ only in how the connection is obtained.
+
+Multiple accounts are supported for every provider. Each configuration entry is one account, and several entries of the same kind coexist, which is how a user with more than one Colab account gets more concurrent sessions.
+
+### Persistent sessions
+
+A session is one worker process kept alive behind a framed pipe, which is what makes three things work.
+
+A value a declared body stores with `letify.session_cache("model", load_model)` stays in the session's worker process, so a later call in the same session gets it without building it again. Each session has its own cache, and a one-shot channel keeps nothing between calls. A large argument is hashed and offered by digest, so the same tensor passed to ten calls crosses the network once. Files written into a session survive between calls, so a volume can materialize an environment archive or a checkpoint.
+
+### Session pooling
+
+Runtimes are pooled by instance and environment, so two declarations that agree on both share a session with nothing said about it. Provider boot, environment installation and the first data transfer are all billed as GPU time, which is the reason the pool exists.
+
+### Teardown with nothing to call
+
+A call ends its own session. `with let.keep_alive():` keeps sessions for the length of a block, and they end when the outermost block exits. Nothing ends a session on a timer, because a timer would overrule the block that asked to keep it.
+
+A call whose devices cannot be allocated raises `letify.InsufficientDevices` at once instead of waiting. It waits only while a session in this process that holds that accelerator is serving a call.
+
+A heartbeat lease covers the one case nothing else can: a process killed outright says nothing to anybody. The worker exits on its own, which frees the card. Whether that also stops the billing depends on what the provider charges for, and letify states that per provider rather than implying a guarantee it cannot make. See [docs/SPEC.md](docs/SPEC.md).
+
+There is no release call, no shutdown call and no detached mode. Durability comes from checkpoints in the store rather than from a session that outlives you.
+
+### Content addressed storage
+
+A volume is a blob store where contents are named by their hash and mutable names live in a separate namespace of refs. Concurrent sessions cannot overwrite each other, a transfer that already happened is skipped by name, and a tree of small files is packed into one archive so that thousands of round trips become one.
+
+Backends are `filesystem`, `gcs` and `modal`, chosen by the provider rather than stated in the declaration.
+
+### Concurrency from repeated calls
+
+Many configurations are many calls. Inside `with let.keep_alive():`, `asyncio.gather` over an `async def` declaration runs them at once and returns results in call order, and `asyncio.as_completed` yields them as they finish. The inventory bounds how many run; a call beyond it waits for a card.
+
+### Environment from a uv lock file
+
+`Env` is keyed by the hash of `uv.lock`. One lock file resolves for every platform, so a Windows or macOS client drives a Linux runtime. Packages in the lock file are installed remotely by name; the project's own code travels with the call.
+
+### PyTorch forwarding
+
+`host="local"` keeps Python, the data and the libraries here and runs PyTorch operators on the runtime's GPU, through PyTorch's own `__torch_dispatch__` extension point. Code written for `"cuda"` runs unchanged, with any local PyTorch build including a CPU one. Operators are queued and sent in batches and only a read of a value waits for the runtime, so the round trip count is the number of host synchronizations rather than the number of operators. `letify.remoting.device.current_client().stats` reports both counts from inside the function.
+
+## Public API
+
+Everything a user needs is on `letify` itself.
+
+### `letify.Launcher`
+
+```python
+Launcher(
+    config=None,        # a .letify directory or its config.toml; defaults to the project and home ones
+    name=None,          # session and app name; defaults to the pyproject project name
+    stream_logs=True,   # write remote stdout and stderr live to the local ones
+    announce=True,      # say when a session starts, because that is when money starts
+    home=True,          # read ~/.letify/config.toml
+)
+```
+
+| Member | Does |
+|---|---|
+| `let.providers.<alias>` | Return the provider declared under that alias |
+| `let.providers.any.<DEVICE>` | Request an accelerator without naming a provider |
+| `let.providers.devices` | Accelerators every provider offers |
+| `let.providers.active` | Providers that currently hold a session |
+| `let.providers.aliases` | Declared aliases, in configuration order |
+| `let.provider(alias)` | Same as attribute access, for a computed alias |
+| `let.function(...)` | Declare a function, returning a decorator |
+| `with let.keep_alive():` | Keep sessions alive between calls for the length of the block |
+| `let.status()` | How many sessions are live and busy against the ceiling, and what each one is |
+| `let.usage(alias=None)` | What is left on each account, or why it is not reported |
+| `let.utilization(alias=None)` | How busy each instance's accelerator is right now |
+
+### `let.function`
+
+```python
+@let.function(
+    device=colab.G4,       # an Instance, carrying provider, account and accelerator
+    host="remote",         # letify.local forwards PyTorch operators, letify.remote ships the function
+    env=env,               # an Env; defaults to Env()
+    volumes=[cache],       # volumes to attach
+    timeout=None,          # seconds one call may take; no default deadline
+    retries=1,             # retries on infrastructure failure, never on user code failure
+)
+def train(lr, bs): ...
+```
+
+Sync or async is taken from the `def`. A plain `def` blocks; an `async def` returns a plain coroutine.
+
+| Call form | Returns |
+|---|---|
+| `train(lr=1e-4)` on a `def` | the value |
+| `await train(lr=1e-4)` on an `async def` | the value |
+| `await asyncio.gather(*(train(lr=x) for x in lrs))` | a list, in call order |
+| `train.local(lr=1e-4)` | runs the body in this process |
+
+### `letify.Env`
+
+```python
+env = letify.Env()                       # uv.lock
+env = letify.Env.from_lock("other.lock")
+env = env.pip_install("flash-attn")      # packages the lock file does not carry
+env = env.run("apt-get install -y git")  # commands after installation
+env = env.vars(HF_HOME="/opt/cache")     # environment variables in the session
+env = env.ship("mypkg")                  # send this module by value, overriding inference
+```
+
+### Instances
+
+```python
+colab.G4                          # registered shape
+colab.device("G4")                # same, for a computed name
+colab.instances                   # everything this account offers
+colab.refresh()                   # ask the provider again
+let.providers.any.A100            # deferred provider choice
+```
+
+Colab accepts `T4`, `L4`, `G4`, `A100`, `H100`, plus the TPUs `v5e1` and `v6e1`. `G4` is the RTX PRO 6000 Blackwell part, and `RTX_PRO_6000` is accepted as an alias for it.
+
+### Volumes
+
+```python
+cache = colab.volume("hf-cache")                    # backend from the provider
+cache = colab.volume("hf-cache", bucket="my-bucket")
+
+cache.cached_env(env)                  # digest of a prebuilt environment archive
+cache.cache_env(env, "/opt/venv")      # pack one from this machine
+cache.cache_env_from(runtime, env, path)   # pack one installed inside a session
+cache.put_checkpoint("run-1", path)    # store and move the ref
+cache.absorb(runtime, path, "run-1")   # pull one out of a session
+cache.fetch_checkpoint("run-1", target)
+cache.resume(runtime, "run-1", path)   # put the newest one inside a session
+```
+
+### Types
+
+| Name | Is |
+|---|---|
+| `Launcher`, `Providers` | the entry point and its provider view |
+| `Instance`, `AnyInstance` | an accelerator shape, and a deferred one |
+| `local`, `remote` | the two values `host` takes |
+| `Env` | an environment declaration |
+| `Volume` | a content addressed store on a provider |
+| `session_cache` | a value built once per session, keyed by name |
+| `Blob`, `RemoteFile` | references to something that lives in a session |
+| `Function` | what the decorator returns |
+
+### Errors
+
+| Error | Means | Retryable |
+|---|---|---|
+| `ConfigError` | The configuration file is malformed or names an unknown kind | no |
+| `ProviderUnavailable` | A provider's optional dependency or setting is missing | no |
+| `UnknownProvider`, `UnknownInstance` | No such alias or accelerator | no |
+| `RuntimeFailure`, `RuntimeLost` | The session misbehaved | yes |
+| `ProtocolError` | The remote process died before producing a result | yes |
+| `RemoteError` | The shipped function raised; carries the remote traceback | no |
+| `UnsupportedMode` | The requested mode cannot work here | no |
+| `InsufficientDevices` | The devices a call asks for cannot be allocated; names what holds them | no |
+
+### Command line
+
+```bash
+letify login <kind> [alias]   # declare an account at home, reference it here
+letify logout <alias>         # remove the account from this machine
+letify providers              # declared providers, storage, channel kind
+letify devices                # accelerators each provider offers
+letify status                 # live sessions and what they are costing
+letify usage [alias]          # what is left on each account
+letify utilization [alias]    # how busy each instance's accelerator is
+letify check <alias>          # confirm a machine answers
+letify probe <host>           # whether host="local" is worth using
+letify efficiency 0.5 3 150   # expected share of a direct run
+letify stubs                  # write typings/letify_providers.pyi for editor completion
+```
+
+## Configuration
+
+Configuration is a directory. `~/.letify/config.toml` holds accounts, the project's `.letify/config.toml` holds defaults and the aliases it uses, and neither holds a secret.
+
+An account in `~/.letify/config.toml` is available in a project only when the project's `.letify/config.toml` names its alias, even as an empty `[colab_pro]` table, when the home entry sets `global = true`, or when it is `local`. A named alias takes every home setting and the project's own fields override them one by one. With no project `.letify/` at all, only global accounts and `local` exist.
+
+`letify login <kind> [alias]` writes both. The account goes to `~/.letify/config.toml`, which belongs to the machine, and any credential it collects goes to `~/.letify/accounts/<alias>/`. `letify logout <alias>` deletes that account directory. The project file gets the alias as an empty table and nothing else, which is safe to commit and tells a teammate which accounts the repository needs. An account already declared is not asked for again, so `letify login` in a second repository writes only the table. An alias the project names that this machine does not have is a configuration error naming the command that fixes it.
+
+SSH authenticates by key, because letify opens sessions with `ssh -o BatchMode=yes`: a session is started by the pool in the background, with nobody present to answer a password prompt. So `letify login shell` generates an ed25519 key if there is none, asks for the password once to install it, drops the password, and confirms the key works before declaring the alias. It then runs `nvidia-smi` on the machine once, asks which indices of each accelerator letify may use, and writes them to `[<alias>.devices]` in the home file, so editor completion knows the names. `--indices NAME=SPEC` chooses them in a script, `--detect-devices` asks an already declared machine again, and a machine where `nvidia-smi` does not answer is logged in with no table. Nothing about the password is written to a file or the environment. A machine whose administrator forbids key authentication can use `--auth password`, which reads the password from `~/.letify/accounts/<alias>/password` and drives `sshpass`; it is refused on Windows, where that tool does not exist.
+
+Everything letify writes on a remote machine lives under one directory per account, the workspace root: the project `.venv`, materialized volume data, temporary files and the worker's working directory. An account in `~/.letify/config.toml` sets it with `workspace = "<path>"`, a path that starts with `/` or `~`, expanded on the machine. A project file cannot set it. The default is `~/.letify-runtime` for `shell`, `tunnel` and `elice`, `/content/letify` for `colab`, and `/letify` for `modal`, where a Modal volume is mounted so the root persists across sandboxes. `letify login shell` and `letify login tunnel` ask for it, take `--workspace PATH` in a script, and check over SSH that the path can be created and written without root before anything is written. `letify check <alias>` reports whether the root is writable.
+
+`letify login modal <alias>` runs Modal's own `modal token new` through `uv tool run`, with `MODAL_CONFIG_PATH` pointing at `~/.letify/accounts/<alias>/modal.toml`, and approves in the browser. The Modal provider and the `modal` volume backend never import `modal` in the letify process: they drive a small adapter, `letify/providers/modal_adapter.py`, run with `uv run --no-project --with "modal>=1.0,<2"` as that account and spoken to in JSON lines.
+
+```toml
+[defaults]
+name = "nvfp4"
+
+[colab_a]
+kind = "colab"
+account = "someone@example.com"
+
+[lab_a100]
+kind = "shell"
+address = "gpu.lab.example.edu"
+user = "researcher"
+key = "~/.ssh/id_ed25519"
+persistent = true
+workspace = "/workspace/researcher/letify"
+
+[elice_a100]
+kind = "elice"
+zone_id = "..."
+price_type = "ondemand"        # or "spot"; letify creates the machine through eci on first use
+access_token_env = "ELICE_ACCESS_TOKEN"
+```
+
+An alias must be a Python identifier, because providers are reached by attribute. `any`, `devices` and `active` are reserved. Declaration order sets the priority for `let.providers.any`.
+
+`letify usage` reads each account from its own service: Colab compute units from `ccu-info`, Elice credit in KRW from the billing API at `billing_endpoint`, Modal's month against `monthly_credit` (30 USD by default), and Kaggle GPU hours per week. A machine reached by SSH has no quota. Providers are asked at once, each waited on for `usage_timeout` seconds (20 by default). An entry can instead name a command that prints the figure: `usage_command` is run when `letify usage` asks, `usage_unit` names what it counts and `usage_limit` gives the ceiling. The last number in the output is read as the remaining amount. Without a command, `usage_limit` is the plan allowance for the provider's own reading, which gives a Colab balance a percentage. The output is one block per account: a gauge of used against the limit, the amount left, a countdown to the reset and the hourly rate, coloured only on a terminal without `NO_COLOR`.
+
+A credential never enters `config.toml`. It is resolved in order: the environment variable named by `<name>_env`, then the file `~/.letify/accounts/<alias>/<name>` (mode 0600, written by `letify login`), then a literal value. The OS keyring is not used.
+
+Provider types for editor completion are written to `typings/letify_providers.pyi` at the project root, automatically when the configuration loads or on demand with `letify stubs`. `[tool.letify] typings = "<path>"` in `pyproject.toml` moves it.
+
+## Installation
+
+```bash
+uv add letify
+```
+
+That is the only install. `letify` installs cloudpickle and blake3 and nothing else. Provider tools run out of process through uv, never in the user's `.venv`, so uv must be installed. letify finds it from the `UV` environment variable, then `PATH`, and raises a clear error if it is absent.
+
+`host="local"` additionally needs PyTorch 2.1 or newer in the project, locally and in the runtime's environment, with the same major.minor version on both sides. letify never installs it: torch is the project's own dependency.
+
+## How this project is built
+
+Spec driven and test driven. [docs/SPEC.md](docs/SPEC.md) is the source of truth, a change edits it before the code, and every test traces to a section of it. The rules are in [CLAUDE.md](CLAUDE.md).
+
+## What is not implemented yet
+
+Stated plainly so nobody builds on a promise. The same list, with detail, is at the end of [docs/SPEC.md](docs/SPEC.md).
+
+- `host="local"` forwards to one device per session and does not provide CUDA streams, events, graphs or generator state. Custom CUDA extensions compiled in this process cannot run on the runtime.
+- `Modal` and `Elice` follow each service's published interface but have not been run against the live services.
+- Whether `ssh -L` works over `colab ssh --proxy-mode` is unverified.
+- Persistence detection by marker file is a decision in the spec, not yet code.