letify 1.0.0__py3-none-any.whl

letify/__init__.py

@@ -0,0 +1,82 @@
+"""letify: declarations that become infrastructure.
+
+Declare what a function needs and it runs there:
+
+    import letify
+
+    let = letify.Launcher()
+    colab = let.providers.colab_a
+
+    @let.function(device=colab.G4, host=letify.Host.remote)
+    def train(lr, bs):
+        ...
+
+    train(lr=1e-4, bs=32)
+
+A declaration places two things. ``device`` says where the device is, carrying the provider
+and the account with it. ``host`` says where the host code runs: ``local``, the default,
+keeps Python here and forwards only CUDA calls, and ``remote`` ships the function to the
+machine that holds the device.
+
+A session ends with the call that needed it. ``lifetime="process"`` keeps it, so a run of
+separate calls does not pay session start each time. Nothing has to be torn down by hand.
+
+Nothing here imports a provider's optional dependency, so ``import letify`` works with
+the base install and a provider whose package is missing reports itself unavailable.
+"""
+
+from __future__ import annotations
+
+from .declare.env import Env
+from .declare.function import Function
+from .declare.instance import AnyInstance, Host, Instance, Lifetime
+from .declare.sweep import Sweep, grid
+from .declare.sweep import zip_ as zip
+from .errors import (
+    ConfigError,
+    HandleScopeError,
+    LetifyError,
+    ProtocolError,
+    ProviderUnavailable,
+    RemoteError,
+    RuntimeFailure,
+    RuntimeLost,
+    UnknownInstance,
+    UnknownProvider,
+    UnsupportedMode,
+)
+from .launcher import Launcher, Providers
+from .protocol.handle import Blob, Handle, RemoteFile
+from .store.volume import Volume
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AnyInstance",
+    "Blob",
+    "ConfigError",
+    "Env",
+    "Function",
+    "Handle",
+    "HandleScopeError",
+    "Host",
+    "Instance",
+    "Launcher",
+    "LetifyError",
+    "Lifetime",
+    "ProtocolError",
+    "ProviderUnavailable",
+    "Providers",
+    "RemoteError",
+    "RemoteFile",
+    "RuntimeFailure",
+    "RuntimeLost",
+    "Sweep",
+    "UnknownInstance",
+    "UnknownProvider",
+    "UnsupportedMode",
+    "Volume",
+    "__version__",
+    "grid",
+    "zip",
+]

letify/cli.py

@@ -0,0 +1,281 @@
+"""Command line entry points.
+
+Enough to answer what comes up before any code is written: which providers are declared,
+what they offer, what is running right now, whether a machine answers, and whether
+forwarding CUDA calls to it is worth doing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .config import login
+from .errors import LetifyError
+from .launcher import Launcher
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="letify", description="Declarations that become infrastructure."
+    )
+    parser.add_argument("--version", action="version", version=f"letify {__version__}")
+    parser.add_argument("--config", help="path to a .letify file")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("providers", help="list declared providers and their storage")
+    sub.add_parser("devices", help="list the accelerators each provider offers")
+    sub.add_parser("status", help="show live runtimes and what they are costing")
+
+    usage = sub.add_parser("usage", help="show what each account has left")
+    usage.add_argument("alias", nargs="?", help="one provider instead of all of them")
+    usage.add_argument("--json", action="store_true", help="print the records unformatted")
+
+    utilization = sub.add_parser(
+        "utilization", help="show how hard each instance's accelerator is working"
+    )
+    utilization.add_argument("alias", nargs="?", help="one provider instead of all of them")
+    utilization.add_argument("--json", action="store_true", help="print the records unformatted")
+
+    log_in = sub.add_parser("login", help="declare an account and reference it here")
+    log_in.add_argument("kind", help="provider kind: shell, tunnel, colab, modal, elice")
+    log_in.add_argument("alias", nargs="?", help="name to reach it by; defaults to the kind")
+    log_in.add_argument("--address", help="machine address, for shell and tunnel")
+    log_in.add_argument("--user", help="SSH user")
+    log_in.add_argument("--port", type=int, help="SSH port")
+    log_in.add_argument("--key", help="SSH private key path")
+    log_in.add_argument(
+        "--auth",
+        choices=login.AUTH_METHODS,
+        help="how to authenticate; key is the default and the only one that works unattended",
+    )
+    log_in.add_argument(
+        "--persistent",
+        action="store_true",
+        default=None,
+        help="the machine keeps its disk between sessions",
+    )
+    log_in.add_argument("--zone-id", dest="zone_id", help="Elice zone id")
+    log_in.add_argument("--machine-id", dest="machine_id", help="Elice machine id")
+    log_in.add_argument("--endpoint", help="API endpoint, where it is not the default")
+    log_in.add_argument("--account", help="account email, for Colab")
+    log_in.add_argument("--workspace", help="workspace name, for Modal")
+    log_in.add_argument(
+        "--token", help="credential to file in the OS keyring rather than in any file"
+    )
+    log_in.add_argument(
+        "--no-input",
+        dest="interactive",
+        action="store_false",
+        help="fail rather than prompt, for a script",
+    )
+    log_in.add_argument(
+        "--skip-key-install",
+        dest="install_key",
+        action="store_false",
+        help="the key is already on the machine, so only confirm it",
+    )
+
+    log_out = sub.add_parser("logout", help="remove an account from this machine")
+    log_out.add_argument("alias", help="provider alias to forget")
+
+    check = sub.add_parser("check", help="check that a provider answers")
+    check.add_argument("alias", help="provider alias from the configuration")
+
+    probe = sub.add_parser("probe", help="measure whether host='local' is worth using")
+    probe.add_argument("host", nargs="?", help="host name to measure the round trip to")
+
+    efficiency = sub.add_parser(
+        "efficiency", help="expected fraction of a direct run, from measured terms"
+    )
+    efficiency.add_argument("step_seconds", type=float, help="GPU time per step")
+    efficiency.add_argument("syncs", type=int, help="host synchronizations per step")
+    efficiency.add_argument("round_trip_ms", type=float, help="network round trip")
+
+    return parser
+
+
+def _describe_usage(row: dict) -> str:
+    """One line for a usage row, saying plainly when there is no number."""
+    if row.get("unmetered"):
+        return "unmetered"
+    unit = row.get("unit") or ""
+    parts = []
+    if row.get("remaining") is not None:
+        left = f"{row['remaining']:g} {unit} left"
+        if row.get("limit"):
+            left += f" of {row['limit']:g}"
+        parts.append(left)
+    if row.get("rate_per_hour") is not None:
+        parts.append(f"{row['rate_per_hour']:g} {unit}/hour running now")
+    return ", ".join(parts) or f"not reported ({row.get('source')})"
+
+
+def _describe_device(device: dict) -> str:
+    """One line for a device reading, leaving out what the card did not report."""
+    load = (
+        f"{device['utilization_percent']:.0f}% busy"
+        if device.get("utilization_percent") is not None
+        else "load unknown"
+    )
+    parts = [f"gpu{device['index']}", str(device["name"]), load]
+    if device.get("memory_total_gb"):
+        used = device.get("memory_used_gb") or 0.0
+        parts.append(f"{used:.1f}/{device['memory_total_gb']:.1f} GiB")
+    if device.get("temperature_c") is not None:
+        parts.append(f"{device['temperature_c']:.0f}C")
+    if device.get("power_w") is not None:
+        parts.append(f"{device['power_w']:.0f}W")
+    return " ".join(parts)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "efficiency":
+        from .remoting import efficiency as compute
+
+        share = compute(args.step_seconds, args.syncs, args.round_trip_ms)
+        print(f"{share * 100:.1f}% of a direct run")
+        return 0
+
+    if args.command == "login":
+        alias = args.alias or args.kind
+        answers = login.Answers(
+            alias=alias,
+            kind=args.kind,
+            values={
+                "address": args.address,
+                "user": args.user,
+                "port": args.port,
+                "key": args.key,
+                "auth": args.auth,
+                "persistent": args.persistent,
+                "zone_id": args.zone_id,
+                "machine_id": args.machine_id,
+                "endpoint": args.endpoint,
+                "account": args.account,
+                "workspace": args.workspace,
+            },
+            token=args.token,
+            interactive=args.interactive,
+            install_key=args.install_key,
+        )
+        try:
+            fresh, home, project = login.log_in(answers, project=args.config)
+        except LetifyError as exc:
+            print(exc, file=sys.stderr)
+            return 1
+        if fresh:
+            print(f"{alias} declared in {home}")
+        else:
+            print(f"{alias} was already declared in {home}, so nothing was asked for")
+        print(f"{alias} referenced in {project}, which is safe to commit")
+        return 0
+
+    if args.command == "logout":
+        removed, forgotten = login.log_out(args.alias)
+        if not removed:
+            print(
+                f"{args.alias} is not declared in {login.home_path()}",
+                file=sys.stderr,
+            )
+            return 1
+        detail = " and its keyring entry" if forgotten else ""
+        print(f"{args.alias} removed from {login.home_path()}{detail}")
+        print("The project reference is left alone, because this repository still needs it")
+        return 0
+
+    let = Launcher(args.config, announce=False)
+
+    if args.command == "providers":
+        for alias in let.config.order:
+            try:
+                provider = let.provider(alias)
+            except Exception as exc:
+                print(f"{alias:20} unavailable: {exc}")
+                continue
+            row = f"{alias:20} {provider.kind:10} {provider.persistence:11}"
+            channel = "persistent" if provider.persistent_channel else "one-shot"
+            print(f"{row} channel={channel}")
+        return 0
+
+    if args.command == "devices":
+        print(json.dumps(let.providers.devices, indent=2, sort_keys=True))
+        return 0
+
+    if args.command == "status":
+        print(json.dumps(let.status(), indent=2))
+        return 0
+
+    if args.command == "usage":
+        rows = let.usage(args.alias)
+        if args.json:
+            print(json.dumps(rows, indent=2))
+            return 0
+        for row in rows:
+            alias = str(row["alias"])
+            if "unavailable" in row:
+                print(f"{alias:20} unavailable: {row['unavailable']}")
+                continue
+            line = f"{alias:20} {row['kind']!s:10} {_describe_usage(row)}"
+            print(line)
+            if row.get("note"):
+                print(f"{'':20} {row['note']}")
+        return 0
+
+    if args.command == "utilization":
+        rows = let.utilization(args.alias)
+        if args.json:
+            print(json.dumps(rows, indent=2))
+            return 0
+        for row in rows:
+            alias = str(row["alias"])
+            if "unavailable" in row:
+                print(f"{alias:20} unavailable: {row['unavailable']}")
+                continue
+            head = f"{alias}.{row['accelerator']}"
+            devices = row.get("devices") or []
+            if not devices:
+                print(f"{head:28} {row.get('reason') or 'nothing reported'}")
+                continue
+            for device in devices:
+                print(f"{head:28} {_describe_device(device)}")
+        return 0
+
+    if args.command == "check":
+        provider = let.provider(args.alias)
+        checker = getattr(provider, "check", None)
+        if checker is None:
+            print(f"{args.alias} has no check step", file=sys.stderr)
+            return 1
+        print(checker())
+        return 0
+
+    if args.command == "probe":
+        from .remoting import probe as run_probe
+
+        capability = run_probe(args.host)
+        print(
+            json.dumps(
+                {
+                    "platform": capability.platform,
+                    "core": capability.core,
+                    "agent": capability.agent,
+                    "round_trip_ms": capability.round_trip_ms,
+                    "usable": capability.usable,
+                    "costly": capability.costly,
+                    "reason": capability.explain(),
+                },
+                indent=2,
+            )
+        )
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

letify/config/__init__.py

@@ -0,0 +1,129 @@
+"""Reading ``.letify``.
+
+Two files are merged. ``~/.letify`` holds accounts and connection details, which
+belong to the machine, and the project's ``.letify`` holds defaults that are safe to
+commit. The project file refines what the home file declared, so a repository can be
+cloned by someone else and run under their own accounts.
+
+Credentials are never read from the file itself. A field names an environment
+variable or a keyring entry, and the value is resolved when it is used.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from ..errors import ConfigError
+from . import inventory, login, writer
+from .schema import RESERVED_ALIASES, Config, ProviderConfig
+from .secrets import from_keyring, resolve_secret
+
+CONFIG_NAME = ".letify"
+
+#: A project entry carrying this and nothing else is a reference to an account in the home
+#: file, written by ``letify login``. It is not a connection detail and never reaches a
+#: provider.
+REFERENCE_FIELD = "from_home"
+
+
+def load(path: str | Path | None = None, *, home: bool = True) -> Config:
+    """Read the configuration files and merge them.
+
+    ``path`` overrides the project file. Set ``home`` to false to ignore ``~/.letify``,
+    which is what tests do to stay isolated from the developer's own accounts.
+    """
+    config = Config()
+    files: list[Path] = []
+    if home:
+        files.append(Path.home() / CONFIG_NAME)
+    files.append(Path(path) if path else Path.cwd() / CONFIG_NAME)
+
+    counter = 0
+    # Aliases the project file expects to find in the home file, so a reference to an
+    # account this machine does not have can name the command that fixes it.
+    referenced: dict[str, tuple[str, Path]] = {}
+    declared: set[str] = set()
+    home_file = files[0] if home else None
+    for file in files:
+        if not file.is_file():
+            continue
+        config.sources.append(file)
+        raw = _parse(file)
+
+        defaults = raw.pop("defaults", None)
+        if isinstance(defaults, dict):
+            config.defaults.update(defaults)
+
+        for alias, body in raw.items():
+            if not isinstance(body, dict):
+                continue
+            _check_alias(alias, file)
+            kind = body.get("kind")
+            if not isinstance(kind, str):
+                raise ConfigError(f"{file}: provider {alias!r} has no 'kind' field")
+            options = {
+                key: value for key, value in body.items() if key not in ("kind", REFERENCE_FIELD)
+            }
+            if body.get(REFERENCE_FIELD) is True:
+                referenced.setdefault(alias, (kind, file))
+            if file == home_file:
+                declared.add(alias)
+            existing = config.providers.get(alias)
+            if existing is None:
+                config.providers[alias] = ProviderConfig(alias, kind, options, counter)
+                counter += 1
+            else:
+                # The project file refines what the home file declared.
+                existing.kind = kind
+                existing.options.update(options)
+
+    for alias, (kind, file) in referenced.items():
+        if alias in declared:
+            continue
+        raise ConfigError(
+            f"{file}: {alias!r} refers to an account in ~/.letify that is not there. "
+            f"Run 'letify login {kind} {alias}' to declare it on this machine."
+        )
+
+    # The local machine is always available and needs no declaration.
+    if "local" not in config.providers:
+        config.providers["local"] = ProviderConfig("local", "local", {}, counter)
+    return config
+
+
+def _parse(file: Path) -> dict[str, Any]:
+    try:
+        return tomllib.loads(file.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"{file} is not valid TOML: {exc}") from exc
+
+
+def _check_alias(alias: str, file: Path) -> None:
+    if alias in RESERVED_ALIASES:
+        raise ConfigError(
+            f"{file}: {alias!r} is reserved. Pick another alias, because "
+            f"let.providers.{alias} already means something else."
+        )
+    if not alias.isidentifier():
+        hint = f" Try {alias.replace('-', '_')!r}." if "-" in alias else ""
+        raise ConfigError(
+            f"{file}: alias {alias!r} is not a Python identifier, so "
+            f"let.providers.{alias} cannot work.{hint}"
+        )
+
+
+__all__ = [
+    "CONFIG_NAME",
+    "REFERENCE_FIELD",
+    "RESERVED_ALIASES",
+    "Config",
+    "ProviderConfig",
+    "from_keyring",
+    "inventory",
+    "load",
+    "login",
+    "resolve_secret",
+    "writer",
+]

letify/config/inventory.py

@@ -0,0 +1,153 @@
+"""What accelerators a provider account has, and how many of each.
+
+This is the only thing that bounds how much letify runs at once. Three facts force that,
+and no single number on the launcher can express any of them.
+
+A Colab account's available accelerators depend on its tier and its compute unit balance,
+so the kinds are per account and they change without letify being told.
+
+A shared department machine holds several cards in one box, and which indices are free
+moves with whoever else is logged in. So an entry names the indices it may use and letify
+takes only those that are actually free when a session starts.
+
+A run can take more than one card. On a four card machine, a run taking two is two
+concurrent sessions rather than four, which a number bounding sessions cannot say.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from ..errors import ConfigError
+
+
+def read_indices(value: Any) -> tuple[int, ...]:
+    """Read declared device indices, as ``"0-3"``, ``"0-1,6-7"`` or ``[0, 1, 6]``.
+
+    A range because that is how a shared box is described by whoever hands it out: cards
+    zero through three are yours. Returned sorted and without duplicates, because the order
+    a user wrote them in is not a preference letify can honour once cards are busy.
+    """
+    if isinstance(value, (list, tuple)):
+        found = []
+        for item in value:
+            if isinstance(item, bool) or not isinstance(item, int):
+                raise ConfigError(f"device indices must be whole numbers, not {item!r}")
+            found.append(item)
+        return _checked(found, value)
+
+    if not isinstance(value, str) or not value.strip():
+        raise ConfigError(
+            f"device indices must be a range such as '0-3' or a list such as [0, 1], not {value!r}"
+        )
+
+    found = []
+    for part in value.split(","):
+        piece = part.strip()
+        if not piece:
+            raise ConfigError(f"device indices {value!r} has an empty entry")
+        if "-" in piece:
+            low, _, high = piece.partition("-")
+            if not low.strip().isdigit() or not high.strip().isdigit():
+                raise ConfigError(f"device indices {value!r} is not a range of numbers")
+            first, last = int(low), int(high)
+            if last < first:
+                raise ConfigError(f"device indices {value!r} counts backwards")
+            found.extend(range(first, last + 1))
+        elif piece.isdigit():
+            found.append(int(piece))
+        else:
+            raise ConfigError(f"device indices {value!r} is not a number or a range")
+    return _checked(found, value)
+
+
+def _checked(found: list[int], original: Any) -> tuple[int, ...]:
+    if not found:
+        raise ConfigError(f"device indices {original!r} names none")
+    if any(index < 0 for index in found):
+        raise ConfigError(f"device indices {original!r} has a negative index")
+    return tuple(sorted(set(found)))
+
+
+@dataclass(frozen=True, slots=True)
+class Devices:
+    """How many of one accelerator an account has, and which indices if it chooses them."""
+
+    accelerator: str
+    count: int = 1
+    indices: tuple[int, ...] = ()
+
+    @property
+    def chooses_indices(self) -> bool:
+        """Whether letify picks the physical device, rather than the provider assigning it."""
+        return bool(self.indices)
+
+    @classmethod
+    def read(cls, accelerator: str, body: Any) -> Devices:
+        """Read one entry of a ``devices`` table.
+
+        ``indices`` alone gives the count. ``count`` alone is a provider that assigns the
+        device itself. Neither is one of that accelerator. Both are accepted only when they
+        agree, because two statements of one fact leave no way to tell which was meant.
+        """
+        if body is None or body is True:
+            return cls(accelerator)
+        if isinstance(body, int) and not isinstance(body, bool):
+            return cls(accelerator, count=_positive(accelerator, body))
+        if not isinstance(body, dict):
+            raise ConfigError(
+                f"devices.{accelerator} must be a table such as "
+                f'{{ indices = "0-3" }} or {{ count = 2 }}, not {body!r}'
+            )
+
+        unknown = set(body) - {"count", "indices"}
+        if unknown:
+            named = ", ".join(sorted(unknown))
+            raise ConfigError(
+                f"devices.{accelerator} has no field {named}. It takes 'count' and 'indices'."
+            )
+
+        indices = read_indices(body["indices"]) if "indices" in body else ()
+        declared = body.get("count")
+        if declared is None:
+            return cls(accelerator, count=len(indices) or 1, indices=indices)
+
+        count = _positive(accelerator, declared)
+        if indices and count != len(indices):
+            raise ConfigError(
+                f"devices.{accelerator} declares count {count} and {len(indices)} indices. "
+                f"Drop the count, because the indices already say how many there are."
+            )
+        return cls(accelerator, count=count, indices=indices)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"count": self.count, "indices": list(self.indices)}
+
+
+def _positive(accelerator: str, value: Any) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise ConfigError(f"devices.{accelerator} count must be a whole number, not {value!r}")
+    if value < 1:
+        raise ConfigError(f"devices.{accelerator} count must be at least one, not {value}")
+    return value
+
+
+def read_table(options: dict[str, Any]) -> dict[str, Devices]:
+    """Read a provider entry's inventory.
+
+    ``devices`` is the full form. ``gpus`` is the older list, which means one of each with
+    no indices chosen, and stays because an entry that only needs to name its accelerators
+    should not have to write a table.
+    """
+    table = options.get("devices")
+    if isinstance(table, dict) and table:
+        return {str(name): Devices.read(str(name), body) for name, body in table.items()}
+
+    declared = options.get("gpus")
+    if isinstance(declared, (list, tuple)) and declared:
+        return {str(name): Devices(str(name)) for name in declared}
+    return {}
+
+
+__all__ = ["Devices", "read_indices", "read_table"]