modelport-cli 0.1.0__py3-none-any.whl

modelport/__init__.py

@@ -0,0 +1,3 @@
+"""ModelPort: prepare models for Flutter apps."""
+
+__version__ = "0.1.0"

modelport/bundle.py

@@ -0,0 +1,83 @@
+"""A bundle folder: modelport.json plus the files it points to."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .hashing import sha256_file
+from .manifest import MANIFEST_FILENAME, FileRef, Manifest
+
+_SAFE_CHECK_SHA = "0" * 64
+
+
+class Bundle:
+    """Write and check the files of one model bundle."""
+
+    def __init__(self, root: str | Path) -> None:
+        self.root = Path(root)
+
+    def path(self, relative: str) -> Path:
+        """Absolute path for a bundle-relative path. Rejects unsafe paths."""
+        FileRef(path=relative, size=1, sha256=_SAFE_CHECK_SHA)  # validates the path rules
+        return self.root / relative
+
+    def add(self, relative: str) -> FileRef:
+        """Reference a file that is already inside the bundle."""
+        target = self.path(relative)
+        if not target.is_file():
+            raise FileNotFoundError(f"{target} does not exist")
+        return FileRef(path=relative, size=target.stat().st_size, sha256=sha256_file(target))
+
+    def write_bytes(self, relative: str, data: bytes) -> FileRef:
+        target = self.path(relative)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_bytes(data)
+        return self.add(relative)
+
+    def write_text(self, relative: str, text: str) -> FileRef:
+        return self.write_bytes(relative, text.encode("utf-8"))
+
+    @property
+    def manifest_path(self) -> Path:
+        return self.root / MANIFEST_FILENAME
+
+    def write_manifest(self, manifest: Manifest) -> Path:
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.manifest_path.write_text(manifest.to_json(), encoding="utf-8")
+        return self.manifest_path
+
+    def read_manifest(self) -> Manifest:
+        return Manifest.from_file(self.manifest_path)
+
+    def problems(self, manifest: Manifest) -> list[str]:
+        """Bundle files that are missing or do not match their size or sha256."""
+        found: list[str] = []
+        for ref in manifest.files():
+            if ref.path is None:
+                continue
+            target = self.root / ref.path
+            if not target.is_file():
+                found.append(f"{ref.path}: missing")
+            elif target.stat().st_size != ref.size:
+                found.append(
+                    f"{ref.path}: size is {target.stat().st_size}, manifest says {ref.size}"
+                )
+            elif sha256_file(target) != ref.sha256:
+                found.append(f"{ref.path}: sha256 does not match")
+        return found
+
+    def refresh(self, manifest: Manifest) -> Manifest:
+        """Recompute size and sha256 of every bundle file the manifest points to."""
+        data = manifest.model_dump(by_alias=True, exclude_none=True, mode="json")
+        return Manifest.model_validate(self._refresh_refs(data))
+
+    def _refresh_refs(self, node: Any) -> Any:
+        if isinstance(node, dict):
+            if "path" in node and "sha256" in node and "size" in node:
+                ref = self.add(node["path"])
+                return {**node, "size": ref.size, "sha256": ref.sha256}
+            return {key: self._refresh_refs(value) for key, value in node.items()}
+        if isinstance(node, list):
+            return [self._refresh_refs(item) for item in node]
+        return node

modelport/cli.py

@@ -0,0 +1,527 @@
+"""The `modelport` command line tool."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import ValidationError
+from rich.console import Console
+from rich.table import Table
+
+from . import __version__
+from .doctor import collect_report
+from .errors import ModelPortError
+from .inspection import ModelInfo, TensorInfo, inspect_model
+from .manifest import MANIFEST_FILENAME, Manifest
+from .manifest.schema import render_schema
+
+app = typer.Typer(
+    name="modelport",
+    help="Prepare PyTorch, Hugging Face, and GGUF models for Flutter apps.",
+    no_args_is_help=True,
+    add_completion=False,
+    pretty_exceptions_show_locals=False,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        console.print(f"modelport {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_print_version,
+            is_eager=True,
+            help="Show the version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Prepare PyTorch, Hugging Face, and GGUF models for Flutter apps."""
+
+
+@app.command()
+def schema(
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="File or folder to write manifest.schema.json to. Prints to stdout if omitted.",
+        ),
+    ] = None,
+) -> None:
+    """Print or write the JSON Schema for modelport.json."""
+    text = render_schema()
+    if output is None:
+        typer.echo(text, nl=False)
+        return
+    target = output / "manifest.schema.json" if output.is_dir() else output
+    target.write_text(text, encoding="utf-8")
+    err_console.print(f"Wrote {target}")
+
+
+@app.command()
+def validate(
+    paths: Annotated[
+        list[Path],
+        typer.Argument(help="modelport.json files, or bundle folders that contain one."),
+    ],
+) -> None:
+    """Check that manifests follow the spec. Exits with code 1 if any is invalid."""
+    failed = 0
+    for path in paths:
+        file = path / MANIFEST_FILENAME if path.is_dir() else path
+        try:
+            manifest = Manifest.from_file(file)
+        except ValidationError as error:
+            failed += 1
+            console.print(f"[red]✗[/red] {file}")
+            for issue in error.errors():
+                where = ".".join(str(part) for part in issue["loc"]) or "(root)"
+                console.print(f"    {where}: {issue['msg']}", markup=False, highlight=False)
+        except (OSError, ValueError) as error:
+            failed += 1
+            console.print(f"[red]✗[/red] {file}")
+            console.print(f"    {error}", markup=False, highlight=False)
+        else:
+            console.print(
+                f"[green]✓[/green] {file}  {manifest.id} {manifest.version}, "
+                f"{manifest.task}, {len(manifest.variants)} variant(s)"
+            )
+    if failed:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def doctor() -> None:
+    """Check Python, optional packages, and disk space."""
+    report = collect_report()
+    summary = Table.grid(padding=(0, 2))
+    summary.add_row("modelport", report.modelport_version)
+    summary.add_row("python", report.python_version)
+    summary.add_row("platform", report.platform)
+    summary.add_row("free disk", f"{report.free_disk_bytes / 1000**3:.1f} GB")
+    console.print(summary)
+    console.print()
+
+    table = Table(title="Optional packages", title_justify="left", show_edge=False)
+    table.add_column("package")
+    table.add_column("extra")
+    table.add_column("version")
+    for package in report.packages:
+        version = package.version or "[yellow]not installed[/yellow]"
+        table.add_row(package.name, package.extra, version)
+    console.print(table)
+
+    for problem in report.problems:
+        console.print(f"[red]![/red] {problem}", highlight=False)
+    if report.hints:
+        console.print("\nTo enable more formats:")
+        for hint in report.hints:
+            console.print(f"  {hint}", markup=False, highlight=False)
+    if not report.problems and not report.hints:
+        console.print("\n[green]Everything is installed.[/green]")
+
+
+@app.command()
+def export(
+    source: Annotated[
+        str,
+        typer.Argument(
+            help="Model to export: torchvision:<name>, hf:<repo or folder>, or file:<script.py>."
+        ),
+    ],
+    target: Annotated[
+        list[str],
+        typer.Option(
+            "--target", "-t", help="Format to export: onnx, executorch. Repeat or comma-separate."
+        ),
+    ] = ["onnx"],  # noqa: B006 - Typer reads list defaults
+    out: Annotated[Path, typer.Option("--out", "-o", help="Folder for bundles.")] = Path("dist"),
+    license: Annotated[
+        str | None, typer.Option(help="SPDX license of the weights, if the source has none.")
+    ] = None,
+    version: Annotated[str, typer.Option(help="Version of this bundle.")] = "1.0.0",
+    sample_image: Annotated[
+        Path | None,
+        typer.Option(
+            "--sample-image", help="Picture used for golden data. A fixed one by default."
+        ),
+    ] = None,
+    force: Annotated[bool, typer.Option("--force", help="Replace an existing bundle.")] = False,
+    image_size: Annotated[
+        int | None,
+        typer.Option("--image-size", help="Square input size for detectors that accept any size."),
+    ] = None,
+) -> None:
+    """Convert a model and write a bundle with modelport.json and golden test data."""
+    from .pipeline import export_bundle
+    from .preprocess import load_image
+    from .sources import load_source
+
+    targets = [t.strip() for item in target for t in item.split(",") if t.strip()]
+    try:
+        with console.status(f"Loading {source}"):
+            model = load_source(source, license=license, image_size=image_size)
+        image = load_image(sample_image) if sample_image else None
+        with console.status(f"Exporting {model.id} to {', '.join(targets)}"):
+            bundle, manifest = export_bundle(
+                model, out, targets, image=image, version=version, overwrite=force
+            )
+    except ModelPortError as error:
+        err_console.print(f"[red]Error:[/red] {error}", highlight=False)
+        raise typer.Exit(code=1) from error
+
+    table = Table(title=f"Wrote {bundle.root}", title_justify="left", show_edge=False)
+    table.add_column("file")
+    table.add_column("size", justify="right")
+    for ref in manifest.files():
+        if ref.path is not None:
+            table.add_row(ref.path, _format_size(ref.size))
+    table.add_row("modelport.json", _format_size(bundle.manifest_path.stat().st_size))
+    console.print(table)
+    console.print(f"\nNext: modelport verify {bundle.root}", highlight=False)
+
+
+@app.command()
+def verify(
+    bundle: Annotated[Path, typer.Argument(help="Bundle folder that contains modelport.json.")],
+) -> None:
+    """Run every variant on the golden input and compare with the expected output."""
+    from .verify import verify_bundle
+
+    try:
+        with console.status(f"Verifying {bundle}"):
+            results = verify_bundle(bundle)
+    except ModelPortError as error:
+        err_console.print(f"[red]Error:[/red] {error}", highlight=False)
+        raise typer.Exit(code=1) from error
+
+    table = Table(show_edge=False)
+    table.add_column("variant", no_wrap=True)
+    for column in ("output", "max diff", "cosine", "top-1", "result"):
+        table.add_column(column, no_wrap=True)
+    for result in results:
+        if result.skipped:
+            table.add_row(result.variant_id, "", "", "", "", "[yellow]skipped[/]")
+            continue
+        for check in result.outputs:
+            ok = check.within_tolerance and check.top1_match is not False
+            top1 = {None: "", True: "same", False: "[red]different[/]"}[check.top1_match]
+            table.add_row(
+                result.variant_id,
+                check.name,
+                f"{check.max_abs_diff:.2e}",
+                f"{check.cosine:.6f}",
+                top1,
+                "[green]pass[/]" if ok else "[red]fail[/]",
+            )
+    console.print(table)
+    for result in results:
+        if result.skipped:
+            console.print(f"[yellow]![/] {result.variant_id}: {result.skipped}", highlight=False)
+
+    failed = [r for r in results if not r.passed and r.skipped is None]
+    if failed or not any(r.passed for r in results):
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def quantize(
+    bundle: Annotated[Path, typer.Argument(help="Bundle folder with an onnx fp32 variant.")],
+    fp16: Annotated[
+        bool, typer.Option("--fp16", help="Add an fp16 variant (about half size).")
+    ] = False,
+    int8: Annotated[
+        bool, typer.Option("--int8", help="Add an int8 variant of MatMul and Gemm weights.")
+    ] = False,
+    allow_top1_change: Annotated[
+        bool, typer.Option(help="Keep a variant even if it changes the golden top-1 class.")
+    ] = False,
+) -> None:
+    """Add smaller ONNX variants and record how far they drift from the original."""
+    from .quantize import Kind, quantize_bundle
+
+    kinds: list[Kind] = []
+    if fp16:
+        kinds.append("fp16")
+    if int8:
+        kinds.append("int8")
+    if not kinds:
+        err_console.print("Choose at least one of --fp16 or --int8.")
+        raise typer.Exit(code=2)
+    try:
+        with console.status(f"Quantizing {bundle}"):
+            results = quantize_bundle(bundle, kinds, allow_top1_change=allow_top1_change)
+    except ModelPortError as error:
+        err_console.print(f"[red]Error:[/red] {error}", highlight=False)
+        raise typer.Exit(code=1) from error
+
+    table = Table(show_edge=False)
+    for column in ("variant", "size", "of fp32", "max |diff|", "tolerance", "top-1"):
+        table.add_column(column)
+    for result in results:
+        variant = result.variant
+        top1 = {None: "", True: "same", False: "[red]different[/]"}[result.top1_match]
+        tolerance = variant.tolerance.atol if variant.tolerance else ""
+        table.add_row(
+            variant.id,
+            _format_size(variant.file.size),
+            f"{result.size_ratio:.0%}",
+            f"{result.max_abs_diff:.2e}",
+            str(tolerance),
+            top1,
+        )
+    console.print(table)
+    console.print(f"\nNext: modelport verify {bundle}", highlight=False)
+
+
+@app.command()
+def pack(
+    bundle: Annotated[Path, typer.Argument(help="Bundle folder that contains modelport.json.")],
+) -> None:
+    """Refresh file sizes and hashes after manual edits, and list unlisted files."""
+    from .pack import pack_bundle
+
+    try:
+        result = pack_bundle(bundle)
+    except ModelPortError as error:
+        err_console.print(f"[red]Error:[/red] {error}", highlight=False)
+        raise typer.Exit(code=1) from error
+    for path in result.changed:
+        console.print(f"updated hash: {path}", highlight=False)
+    for path in result.stray:
+        console.print(
+            f"[yellow]![/] not in manifest, will not be published: {path}", highlight=False
+        )
+    console.print(
+        f"[green]✓[/green] {result.manifest.id} {result.manifest.version}, "
+        f"{_format_size(result.total_bytes)} in {len(result.manifest.files())} files"
+    )
+
+
+@app.command()
+def publish(
+    bundle: Annotated[Path, typer.Argument(help="Bundle folder that contains modelport.json.")],
+    hf: Annotated[
+        str | None, typer.Option("--hf", help="Hugging Face repo id, like org/name.")
+    ] = None,
+    github: Annotated[
+        str | None,
+        typer.Option("--github", help="GitHub repo, like owner/name. Uploads release assets."),
+    ] = None,
+    tag: Annotated[str, typer.Option(help="Release tag for --github.")] = "models",
+    private: Annotated[bool, typer.Option(help="Create the Hugging Face repo as private.")] = False,
+) -> None:
+    """Upload a bundle to the Hugging Face Hub or to a GitHub release.
+
+    For Hugging Face, log in first with `hf auth login`. For GitHub, log in with `gh auth login`.
+    """
+    from .publish import publish_bundle, publish_to_github
+
+    if (hf is None) == (github is None):
+        err_console.print("Choose exactly one of --hf or --github.")
+        raise typer.Exit(code=2)
+    try:
+        with console.status(f"Uploading {bundle}"):
+            if github is not None:
+                result = publish_to_github(bundle, github, tag)
+            else:
+                assert hf is not None
+                result = publish_bundle(bundle, hf, private=private)
+    except ModelPortError as error:
+        err_console.print(f"[red]Error:[/red] {error}", highlight=False)
+        raise typer.Exit(code=1) from error
+    console.print(f"[green]✓[/green] Uploaded {len(result.files)} files to {result.url}")
+    console.print(f"Load it in Flutter with: {result.location}", highlight=False)
+
+
+@app.command("import-gguf")
+def import_gguf(
+    source: Annotated[
+        str,
+        typer.Argument(
+            help="Hugging Face repo like Qwen/Qwen2.5-0.5B-Instruct-GGUF, or a .gguf file."
+        ),
+    ],
+    quant: Annotated[
+        list[str],
+        typer.Option("--quant", "-q", help="Quantizations to include, in order of preference."),
+    ] = ["q4_k_m"],  # noqa: B006 - Typer reads list defaults
+    context: Annotated[int, typer.Option(help="Context window to allocate on device.")] = 4096,
+    license: Annotated[str | None, typer.Option(help="SPDX license, if the repo has none.")] = None,
+    model_id: Annotated[
+        str | None, typer.Option("--id", help="Bundle id. Taken from the source by default.")
+    ] = None,
+    revision: Annotated[str | None, typer.Option(help="Repo branch, tag, or commit.")] = None,
+    out: Annotated[Path, typer.Option("--out", "-o", help="Folder for bundles.")] = Path("dist"),
+    force: Annotated[bool, typer.Option("--force", help="Replace an existing bundle.")] = False,
+) -> None:
+    """Describe a ready-made GGUF language model with a manifest.
+
+    Hub files are not downloaded: the manifest points at them with pinned URLs.
+    """
+    import shutil
+
+    from .bundle import Bundle
+    from .gguf_import import import_from_file, import_from_hub
+
+    quants = [q.strip() for item in quant for q in item.split(",") if q.strip()]
+    local = Path(source)
+    try:
+        if local.is_file():
+            if license is None:
+                raise ModelPortError("local GGUF files need --license")
+            shutil.rmtree(out / ".import", ignore_errors=True)
+            staging = Bundle(out / ".import")
+            result = import_from_file(
+                local, staging, context=context, license=license, model_id=model_id
+            )
+            root = out / result.manifest.id
+        else:
+            repo = source.removeprefix("hf:")
+            with console.status(f"Reading {repo} from the Hugging Face Hub"):
+                result = import_from_hub(
+                    repo,
+                    quants,
+                    revision=revision,
+                    context=context,
+                    license=license,
+                    model_id=model_id,
+                )
+            root = out / result.manifest.id
+            staging = None
+        if root.exists() and any(root.iterdir()):
+            if not force:
+                raise ModelPortError(f"{root} already exists. Use --force to replace it.")
+            shutil.rmtree(root)
+        if staging is not None:
+            root.parent.mkdir(parents=True, exist_ok=True)
+            staging.root.rename(root)
+        bundle = Bundle(root)
+        bundle.write_manifest(result.manifest)
+    except ModelPortError as error:
+        err_console.print(f"[red]Error:[/red] {error}", highlight=False)
+        raise typer.Exit(code=1) from error
+
+    console.print(f"Wrote {bundle.manifest_path}", highlight=False)
+    table = Table(show_edge=False)
+    table.add_column("variant", no_wrap=True)
+    table.add_column("size", justify="right")
+    table.add_column("min RAM", justify="right")
+    for variant in result.manifest.variants:
+        table.add_row(variant.id, _format_size(variant.file.size), f"{variant.min_ram_mb} MB")
+    console.print(table)
+    for warning in result.warnings:
+        console.print(f"[yellow]![/] {warning}", highlight=False)
+    console.print(
+        f"\nNext: modelport publish {bundle.root} --hf <your-org>/<name>", highlight=False
+    )
+
+
+@app.command("gen-dart")
+def gen_dart(
+    manifest_path: Annotated[
+        Path, typer.Argument(help="modelport.json, or a bundle folder that contains one.")
+    ],
+    out: Annotated[Path, typer.Option("--out", "-o", help="Folder for the .dart file.")] = Path(
+        "lib/models"
+    ),
+    location: Annotated[
+        str | None,
+        typer.Option(help="Default location for load(), such as hf://org/name."),
+    ] = None,
+) -> None:
+    """Generate a typed Dart wrapper with named inputs and outputs."""
+    from .codegen.dart import file_name, format_with_dart, generate_dart
+    from .manifest import MANIFEST_FILENAME, Manifest
+
+    path = manifest_path / MANIFEST_FILENAME if manifest_path.is_dir() else manifest_path
+    try:
+        manifest = Manifest.from_file(path)
+        source = generate_dart(manifest, location=location)
+        formatted = format_with_dart(source)
+    except (ModelPortError, ValueError, OSError) as error:
+        err_console.print(f"[red]Error:[/red] {error}", highlight=False)
+        raise typer.Exit(code=1) from error
+    out.mkdir(parents=True, exist_ok=True)
+    target = out / file_name(manifest.id)
+    target.write_text(formatted or source, encoding="utf-8")
+    console.print(f"Wrote {target}", highlight=False)
+    if formatted is None:
+        console.print("Dart is not installed, so the file was not formatted.", highlight=False)
+
+
+@app.command("inspect")
+def inspect_command(
+    path: Annotated[Path, typer.Argument(help="A .onnx, .pte, or .gguf model file.")],
+    as_json: Annotated[bool, typer.Option("--json", help="Print machine-readable JSON.")] = False,
+) -> None:
+    """Show a model file's inputs, outputs, and metadata."""
+    try:
+        info = inspect_model(path)
+    except ModelPortError as error:
+        err_console.print(f"[red]Error:[/red] {error}", highlight=False)
+        raise typer.Exit(code=1) from error
+
+    if as_json:
+        data = asdict(info)
+        data["path"] = str(info.path)
+        typer.echo(json.dumps(data, indent=2))
+        return
+    _print_model_info(info)
+
+
+def _format_size(size: int) -> str:
+    value = float(size)
+    for unit in ("B", "KB", "MB", "GB"):
+        if value < 1000 or unit == "GB":
+            return f"{value:.1f} {unit}" if unit != "B" else f"{size} B"
+        value /= 1000
+    raise AssertionError("unreachable")
+
+
+def _tensor_table(title: str, tensors: list[TensorInfo]) -> Table:
+    table = Table(title=title, title_justify="left", show_edge=False)
+    table.add_column("name")
+    table.add_column("dtype")
+    table.add_column("shape")
+    for tensor in tensors:
+        table.add_row(tensor.name, tensor.dtype, str(tensor.shape))
+    return table
+
+
+def _print_model_info(info: ModelInfo) -> None:
+    summary = Table.grid(padding=(0, 2))
+    summary.add_row("file", str(info.path))
+    summary.add_row("format", info.format)
+    summary.add_row("size", f"{_format_size(info.size)} ({info.size:,} bytes)")
+    summary.add_row("sha256", info.sha256)
+    console.print(summary)
+    if info.inputs:
+        console.print()
+        console.print(_tensor_table("Inputs", info.inputs))
+    if info.outputs:
+        console.print()
+        console.print(_tensor_table("Outputs", info.outputs))
+    if info.metadata:
+        console.print()
+        meta = Table(title="Metadata", title_justify="left", show_edge=False)
+        meta.add_column("key")
+        meta.add_column("value")
+        for key, value in info.metadata.items():
+            meta.add_row(key, value)
+        console.print(meta)

modelport/codegen/__init__.py

@@ -0,0 +1 @@
+"""Code generation from manifests."""