tailtune 0.0.1__py3-none-any.whl

tailtune/__init__.py

@@ -0,0 +1,46 @@
+"""tailtune: fine-tune LLMs with far less forgetting, and prove it.
+
+0.0.1 ships two tools that need no GPU and no torch:
+
+- ``tailtune.doctor()`` reports what this machine can run, and at which support tier.
+- ``tailtune.estimate(model)`` prices every training route in GPU and host memory,
+  from the model's ``config.json`` alone.
+
+Every memory figure is computed from shapes and has not yet been checked against
+hardware. Gate 1 of the plan calibrates it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from tailtune._core.errors import TailtuneDeprecationWarning, TailtuneError
+
+__version__ = "0.0.1"
+
+if TYPE_CHECKING:
+    from tailtune.hardware.doctor import DoctorReport
+    from tailtune.hardware.estimate import Estimate
+
+
+def doctor(*, deep: bool = False) -> DoctorReport:
+    """Run the machine checks (D01 to D18). Makes no network calls."""
+    from tailtune.hardware.doctor import run_doctor
+
+    return run_doctor(deep=deep)
+
+
+def estimate(model: str, **kwargs: Any) -> Estimate:
+    """Estimate GPU and host memory per route. See ``tailtune.hardware.estimate.estimate``."""
+    from tailtune.hardware.estimate import estimate as _estimate
+
+    return _estimate(model, **kwargs)
+
+
+__all__ = [
+    "TailtuneDeprecationWarning",
+    "TailtuneError",
+    "__version__",
+    "doctor",
+    "estimate",
+]

tailtune/__main__.py

@@ -0,0 +1,6 @@
+"""`python -m tailtune` runs the command-line interface."""
+
+from tailtune.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tailtune/_core/__init__.py

@@ -0,0 +1 @@
+"""Private support layer. Imports nothing else from tailtune."""

tailtune/_core/errors.py

@@ -0,0 +1,177 @@
+"""Exception hierarchy, stable error codes and the exit-code contract.
+
+Exit codes (README contract, docs/plan/04-api-and-ux.md section 4.1):
+
+    0    success
+    1    internal or unexpected error, Hub unreachable, declined confirmation
+    2    blocking data validation failure
+    3    regression gate failed
+    4    refused by a pre-flight check, including model access and policy refusals
+    5    invalid configuration or usage
+    130  interrupted with Ctrl-C
+
+Only the classes that 0.0.1 raises are defined here. The full tree is in
+docs/plan/02-architecture.md section 10.
+"""
+
+from __future__ import annotations
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_DATA = 2
+EXIT_REGRESSION = 3
+EXIT_REFUSED = 4
+EXIT_USAGE = 5
+EXIT_INTERRUPTED = 130
+
+DOCS_ERRORS = (
+    "https://github.com/inboxpraveen/tailtune/blob/main/docs/plan/04-api-and-ux.md"
+    "#8-error-message-catalogue"
+)
+
+
+class TailtuneDeprecationWarning(FutureWarning):
+    """Raised for deprecated tailtune behaviour. Subclasses FutureWarning so users see it."""
+
+
+class TailtuneError(Exception):
+    """Base class. Every error carries a stable code, a message, a cause and a fix."""
+
+    exit_code: int = EXIT_ERROR
+    default_code: str = "TT-X000"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        cause: str | None = None,
+        fix: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code or self.default_code
+        self.cause = cause
+        self.fix = fix
+
+    def render(self) -> str:
+        """Format the error in the catalogue's shape, for stderr."""
+        lines = [f"error[{self.code}] {self.message}"]
+        if self.cause:
+            lines.append(f"  cause  {self.cause}")
+        if self.fix:
+            lines.append(f"  fix    {self.fix}")
+        lines.append(f"  docs   {DOCS_ERRORS}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "code": self.code,
+            "exit_code": self.exit_code,
+            "message": self.message,
+            "cause": self.cause,
+            "fix": self.fix,
+        }
+
+
+class ConfigError(TailtuneError):
+    """A bad value, an unknown key or an out-of-range option (TT-C001, TT-C003)."""
+
+    exit_code = EXIT_USAGE
+    default_code = "TT-C003"
+
+
+class UsageError(ConfigError):
+    """A command line that could not be parsed. Click's exit code 2 is remapped to 5."""
+
+    default_code = "TT-C003"
+
+
+class ModelAccessError(TailtuneError):
+    """A model tailtune cannot access, or will not load under its policy (D-08)."""
+
+    exit_code = EXIT_REFUSED
+
+
+class GatedModelError(ModelAccessError):
+    default_code = "TT-M001"
+
+
+class MissingTokenError(ModelAccessError):
+    default_code = "TT-M002"
+
+
+class RemoteCodeRequiredError(ModelAccessError):
+    default_code = "TT-M003"
+
+
+class UnsafeWeightsError(ModelAccessError):
+    default_code = "TT-M004"
+
+
+class HubUnavailableError(TailtuneError):
+    """The Hugging Face Hub could not be reached and nothing usable was cached."""
+
+    exit_code = EXIT_ERROR
+    default_code = "TT-M005"
+
+
+class RefusedError(TailtuneError):
+    """A pre-flight refusal. Nothing was loaded or changed."""
+
+    exit_code = EXIT_REFUSED
+
+
+class DoesNotFitError(RefusedError):
+    default_code = "TT-H001"
+
+
+class TargetTypeError(RefusedError):
+    """Conv1D or quantized trainable targets (TT-T002, TT-T003)."""
+
+    default_code = "TT-T003"
+
+
+class UnsupportedModelError(RefusedError):
+    """An architecture whose shapes this version cannot read reliably."""
+
+    default_code = "TT-T004"
+
+
+class DoctorStrictError(RefusedError):
+    """`doctor --strict` found at least one failed check."""
+
+    default_code = "TT-H006"
+
+
+class InternalError(TailtuneError):
+    """An invariant broke. Always a bug."""
+
+    default_code = "TT-X001"
+
+
+__all__ = [
+    "EXIT_DATA",
+    "EXIT_ERROR",
+    "EXIT_INTERRUPTED",
+    "EXIT_OK",
+    "EXIT_REFUSED",
+    "EXIT_REGRESSION",
+    "EXIT_USAGE",
+    "ConfigError",
+    "DoctorStrictError",
+    "DoesNotFitError",
+    "GatedModelError",
+    "HubUnavailableError",
+    "InternalError",
+    "MissingTokenError",
+    "ModelAccessError",
+    "RefusedError",
+    "RemoteCodeRequiredError",
+    "TailtuneDeprecationWarning",
+    "TailtuneError",
+    "TargetTypeError",
+    "UnsafeWeightsError",
+    "UnsupportedModelError",
+    "UsageError",
+]

tailtune/_core/hub.py

@@ -0,0 +1,186 @@
+"""Model config access: a local path or a Hugging Face Hub id.
+
+Downloads `config.json` only, never weights. Maps Hub failures to tailtune's
+error codes: gated or tokenless access, pickle-only weights and remote code are
+refusals (exit 4); an unknown id or revision is a usage error (exit 5).
+"""
+
+from __future__ import annotations
+
+import json
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from tailtune._core.errors import (
+    ConfigError,
+    GatedModelError,
+    HubUnavailableError,
+    MissingTokenError,
+    UnsafeWeightsError,
+    UnsupportedModelError,
+)
+
+PICKLE_SUFFIXES = (".bin", ".pt", ".pth", ".ckpt", ".pkl")
+SAFE_SUFFIX = ".safetensors"
+
+
+@dataclass(frozen=True)
+class ModelSource:
+    """Where a model's config came from."""
+
+    ref: str
+    kind: Literal["hub", "local", "hub-cache"]
+    config: dict[str, Any]
+    revision: str | None = None
+    weight_files: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def label(self) -> str:
+        if self.kind == "local":
+            return self.ref
+        rev = self.revision[:12] if self.revision else "unresolved revision"
+        suffix = " (from local cache, Hub unreachable)" if self.kind == "hub-cache" else ""
+        return f"{self.ref} @ {rev}{suffix}"
+
+
+def check_weight_formats(ref: str, files: list[str]) -> None:
+    """Refuse a model whose only weights are pickle files (D-08, TT-M004)."""
+    names = [f.lower() for f in files]
+    has_safe = any(n.endswith(SAFE_SUFFIX) for n in names)
+    has_pickle = any(n.endswith(PICKLE_SUFFIXES) for n in names)
+    if has_pickle and not has_safe:
+        raise UnsafeWeightsError(
+            f"{ref} has no safetensors weights. tailtune does not load pickle files.",
+            cause="Only .bin, .pt or similar pickle checkpoints were found (D-08).",
+            fix="Use a safetensors revision, or convert the weights yourself in an "
+            "isolated environment.",
+        )
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ConfigError(
+            f'Invalid value for MODEL: "{path}". The config file could not be read as JSON.',
+            cause=str(exc),
+        ) from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f'Invalid value for MODEL: "{path}". config.json must hold an object.')
+    return data
+
+
+def _load_local(ref: str, path: Path) -> ModelSource:
+    if path.is_file():
+        return ModelSource(ref=ref, kind="local", config=_read_json(path))
+    cfg = path / "config.json"
+    if not cfg.is_file():
+        raise ConfigError(
+            f'Invalid value for MODEL: "{ref}". The directory has no config.json.',
+            fix="Pass a model directory saved by Transformers, a config.json file, or a Hub id.",
+        )
+    files = [p.name for p in path.iterdir() if p.is_file()]
+    check_weight_formats(ref, files)
+    return ModelSource(
+        ref=ref, kind="local", config=_read_json(cfg), weight_files=tuple(sorted(files))
+    )
+
+
+def _has_token() -> bool:
+    from huggingface_hub import get_token
+
+    return get_token() is not None
+
+
+def _gated(ref: str) -> Exception:
+    if _has_token():
+        return GatedModelError(
+            f"{ref} is gated, and this account has not been granted access.",
+            fix="Accept the licence on the model's Hugging Face page with the same account, "
+            "then rerun.",
+        )
+    return MissingTokenError(
+        f"{ref} requires a Hugging Face token, and none was found.",
+        fix="Set HF_TOKEN, or log in with the Hugging Face CLI. In notebooks, add HF_TOKEN "
+        "to Colab or Kaggle secrets.",
+    )
+
+
+def _load_hub(ref: str, revision: str | None) -> ModelSource:
+    from huggingface_hub import HfApi, hf_hub_download
+    from huggingface_hub.errors import (
+        EntryNotFoundError,
+        GatedRepoError,
+        HFValidationError,
+        LocalEntryNotFoundError,
+        RepositoryNotFoundError,
+        RevisionNotFoundError,
+    )
+
+    try:
+        info = HfApi().model_info(ref, revision=revision)
+    except HFValidationError as exc:
+        raise ConfigError(
+            f'Invalid value for MODEL: "{ref}". It is neither a local path nor a valid Hub id.',
+            cause=str(exc).splitlines()[0],
+        ) from exc
+    except GatedRepoError as exc:
+        raise _gated(ref) from exc
+    except RevisionNotFoundError as exc:
+        raise ConfigError(
+            f'Invalid value for --revision: "{revision}". {ref} has no such branch, tag or commit.'
+        ) from exc
+    except RepositoryNotFoundError as exc:
+        hint = "" if _has_token() else " If it is private, set HF_TOKEN."
+        raise ConfigError(
+            f'Invalid value for MODEL: "{ref}". No such model on the Hugging Face Hub.{hint}'
+        ) from exc
+    except Exception as exc:  # network failure: fall back to the local cache
+        try:
+            path = hf_hub_download(ref, "config.json", revision=revision, local_files_only=True)
+        except (LocalEntryNotFoundError, OSError, ValueError):
+            raise HubUnavailableError(
+                f"Could not reach the Hugging Face Hub to read {ref}, and its config is not "
+                "cached.",
+                cause=f"{type(exc).__name__}: {exc}",
+                fix="Check the network or proxy settings, or pass a local model directory.",
+            ) from exc
+        return ModelSource(ref=ref, kind="hub-cache", config=_read_json(Path(str(path))))
+
+    files = [s.rfilename for s in (info.siblings or [])]
+    check_weight_formats(ref, files)
+    try:
+        path = hf_hub_download(ref, "config.json", revision=info.sha)
+    except GatedRepoError as exc:
+        raise _gated(ref) from exc
+    except EntryNotFoundError as exc:
+        raise UnsupportedModelError(
+            f"{ref} has no config.json, so tailtune cannot read its shapes.",
+            fix="Use a model repository saved by Transformers.",
+        ) from exc
+    except Exception as exc:
+        raise HubUnavailableError(
+            f"Could not download config.json for {ref}.",
+            cause=f"{type(exc).__name__}: {exc}",
+            fix="Check the network or proxy settings, then rerun.",
+        ) from exc
+    return ModelSource(
+        ref=ref,
+        kind="hub",
+        config=_read_json(Path(str(path))),
+        revision=info.sha,
+        weight_files=tuple(sorted(files)),
+    )
+
+
+def load_config(model: str, revision: str | None = None) -> ModelSource:
+    """Read a model's config from a local path or the Hub, without weights."""
+    path = Path(model).expanduser()
+    if path.exists():
+        return _load_local(model, path)
+    with warnings.catch_warnings():
+        # The Hub client warns on Windows without symlink support; caching still works.
+        warnings.filterwarnings("ignore", message=r".*cache-system uses symlinks.*")
+        return _load_hub(model, revision)

tailtune/_core/versions.py

@@ -0,0 +1,80 @@
+"""Installed package versions, compared with the ranges tailtune is tested against.
+
+Reads metadata only. Nothing here imports the packages it reports on.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import metadata
+from typing import Literal
+
+from packaging.version import InvalidVersion, Version
+
+Standing = Literal["tested", "newer", "older", "unsupported", "missing", "unknown"]
+
+
+@dataclass(frozen=True)
+class TestedRange:
+    """`low <= v < high` is tested. Below `floor` is unsupported outright."""
+
+    package: str
+    low: str
+    high: str
+    floor: str | None = None
+
+
+# The ranges v0.1 will be tested against (docs/plan/11-engineering-and-release.md section 2).
+# 0.0.1 requires none of these packages; doctor reports them so users can see where they stand.
+TESTED: dict[str, TestedRange] = {
+    "torch": TestedRange("torch", "2.14", "2.16", floor="2.14"),
+    "transformers": TestedRange("transformers", "5.22", "5.23", floor="5.0"),
+    "accelerate": TestedRange("accelerate", "1.14", "2.0", floor="1.14"),
+    "peft": TestedRange("peft", "0.21.2", "0.22"),
+    "trl": TestedRange("trl", "1.17", "1.18"),
+}
+
+
+@dataclass(frozen=True)
+class Installed:
+    package: str
+    version: str | None
+    standing: Standing
+
+
+def installed_version(package: str) -> str | None:
+    try:
+        return metadata.version(package)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def _release(v: Version) -> Version:
+    """Drop local and pre-release parts, so `2.14.1+cu130` compares as `2.14.1`."""
+    return Version(v.base_version)
+
+
+def standing(package: str, version: str | None = None) -> Installed:
+    """Where an installed version sits against TESTED. `version` overrides the lookup."""
+    found = version if version is not None else installed_version(package)
+    if found is None:
+        return Installed(package, None, "missing")
+    rng = TESTED.get(package)
+    if rng is None:
+        return Installed(package, found, "unknown")
+    try:
+        v = _release(Version(found))
+    except InvalidVersion:
+        return Installed(package, found, "unknown")
+    if rng.floor is not None and v < Version(rng.floor):
+        return Installed(package, found, "unsupported")
+    if v < Version(rng.low):
+        return Installed(package, found, "older")
+    if v >= Version(rng.high):
+        return Installed(package, found, "newer")
+    return Installed(package, found, "tested")
+
+
+def describe_range(package: str) -> str:
+    rng = TESTED[package]
+    return f">={rng.low},<{rng.high}"

tailtune/cli/__init__.py

@@ -0,0 +1,85 @@
+"""Command-line entry point: exit-code mapping and Ctrl-C handling.
+
+Click exits with 2 on a parse error, which would collide with tailtune's code 2
+(data validation). Every parse error is remapped to 5 here.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+import traceback
+
+
+def _configure_streams() -> None:
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            with contextlib.suppress(OSError, ValueError):
+                reconfigure(errors="replace")
+
+
+def _click_like(exc: BaseException) -> bool:
+    """A Click exception. Typer 0.28+ vendors Click, older Typer uses the click package,
+    so the classes are matched by shape rather than imported."""
+    return hasattr(exc, "format_message") and hasattr(exc, "exit_code")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI and return its exit code."""
+    from tailtune._core.errors import (
+        EXIT_ERROR,
+        EXIT_INTERRUPTED,
+        EXIT_OK,
+        EXIT_USAGE,
+        InternalError,
+        TailtuneError,
+        UsageError,
+    )
+    from tailtune.cli.app import app
+
+    _configure_streams()
+    args = sys.argv[1:] if argv is None else argv
+    verbose = "-v" in args or "--verbose" in args
+    try:
+        result = app(args=args, prog_name="tailtune", standalone_mode=False)
+    except KeyboardInterrupt:
+        print("Interrupted.", file=sys.stderr)
+        return EXIT_INTERRUPTED
+    except TailtuneError as exc:
+        print(exc.render(), file=sys.stderr)
+        return exc.exit_code
+    except Exception as exc:
+        name = type(exc).__name__
+        if name == "Abort":  # Click turns Ctrl-C at a prompt into Abort
+            print("Interrupted.", file=sys.stderr)
+            return EXIT_INTERRUPTED
+        if name == "NoArgsIsHelpError" and _click_like(exc):
+            print(exc.format_message())  # type: ignore[attr-defined]
+            return EXIT_OK
+        if _click_like(exc) and getattr(exc, "exit_code", None) == 2:
+            ctx = getattr(exc, "ctx", None)
+            path = getattr(ctx, "command_path", "tailtune")
+            err = UsageError(
+                f"Invalid usage: {exc.format_message()}",  # type: ignore[attr-defined]
+                fix=f"Run `{path} --help` for the options.",
+            )
+            print(err.render(), file=sys.stderr)
+            return EXIT_USAGE
+        if _click_like(exc):
+            print(f"error: {exc.format_message()}", file=sys.stderr)  # type: ignore[attr-defined]
+            return EXIT_ERROR
+        err = InternalError(
+            f"Internal error: {name}: {exc}",
+            fix="This is a bug. Rerun with --verbose and attach the output to an issue.",
+        )
+        print(err.render(), file=sys.stderr)
+        if verbose:
+            traceback.print_exc()
+        return EXIT_ERROR
+    if isinstance(result, int):
+        return result
+    return EXIT_OK
+
+
+__all__ = ["main"]