modelport-cli 0.1.0__py3-none-any.whl

modelport/codegen/dart.py

@@ -0,0 +1,227 @@
+"""Generate a typed Dart wrapper for a tensor model's inputs and outputs.
+
+The wrapper turns tensor names into named parameters and fields, so a typo in an
+input name is a compile error instead of a runtime one.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ..errors import ModelPortError
+from ..manifest import InputSpec, Manifest, OutputSpec, Task, TensorSpec
+
+# Dart keywords and built-in identifiers that cannot be parameter or field names.
+_RESERVED = set(
+    [
+        "abstract",
+        "as",
+        "assert",
+        "async",
+        "await",
+        "base",
+        "break",
+        "case",
+        "catch",
+        "class",
+        "const",
+        "continue",
+        "covariant",
+        "default",
+        "deferred",
+        "do",
+        "dynamic",
+        "else",
+        "enum",
+        "export",
+        "extends",
+        "extension",
+        "external",
+        "factory",
+        "false",
+        "final",
+        "finally",
+        "for",
+        "function",
+        "get",
+        "hide",
+        "if",
+        "implements",
+        "import",
+        "in",
+        "interface",
+        "is",
+        "late",
+        "library",
+        "mixin",
+        "new",
+        "null",
+        "of",
+        "on",
+        "operator",
+        "part",
+        "required",
+        "rethrow",
+        "return",
+        "sealed",
+        "set",
+        "show",
+        "static",
+        "super",
+        "switch",
+        "sync",
+        "this",
+        "throw",
+        "true",
+        "try",
+        "type",
+        "typedef",
+        "var",
+        "void",
+        "when",
+        "while",
+        "with",
+        "yield",
+    ]
+)
+
+
+def _words(text: str) -> list[str]:
+    return [w for w in re.split(r"[^A-Za-z0-9]+", text) if w]
+
+
+def class_name(model_id: str) -> str:
+    """'mobilenet_v3_small' -> 'MobilenetV3Small'."""
+    name = "".join(w[:1].upper() + w[1:] for w in _words(model_id))
+    return name if name[:1].isalpha() else f"Model{name}"
+
+
+def member_name(tensor: str) -> str:
+    """'pixel_values' -> 'pixelValues'."""
+    words = _words(tensor) or ["value"]
+    name = words[0][:1].lower() + words[0][1:] + "".join(w[:1].upper() + w[1:] for w in words[1:])
+    if not name[:1].isalpha():
+        name = f"t{name}"
+    return f"{name}_" if name in _RESERVED else name
+
+
+def file_name(model_id: str) -> str:
+    """'qwen2.5-0.5b' -> 'qwen2_5_0_5b.dart'."""
+    return "_".join(w.lower() for w in _words(model_id)) + ".dart"
+
+
+def _doc(spec: TensorSpec) -> str:
+    # Backticks keep dartdoc from reading the shape as a reference.
+    return f"`{spec.name}`: {spec.dtype.value} `{spec.shape}`"
+
+
+def _unique(names: list[str], what: str) -> None:
+    if len(set(names)) != len(names):
+        raise ModelPortError(f"two {what} names map to the same Dart name: {names}")
+
+
+def generate_dart(manifest: Manifest, *, location: str | None = None) -> str:
+    """Dart source for a typed wrapper around `TensorModel`."""
+    if manifest.task is Task.TEXT_GENERATION:
+        raise ModelPortError("text-generation models have no tensors; use TextGenerator in Dart")
+    name = class_name(manifest.id)
+    inputs: list[InputSpec] = list(manifest.inputs)
+    outputs: list[OutputSpec] = list(manifest.outputs)
+    in_names = [member_name(i.name) for i in inputs]
+    out_names = [member_name(o.name) for o in outputs]
+    _unique(in_names, "input")
+    _unique(out_names, "output")
+
+    lines: list[str] = [
+        f"// Generated by `modelport gen-dart` from {manifest.id} {manifest.version}.",
+        "// Do not edit by hand; run gen-dart again after the manifest changes.",
+        "",
+        "import 'package:modelport/modelport.dart';",
+        "",
+        f"/// Typed access to {manifest.name or manifest.id} ({manifest.task.value}).",
+    ]
+    if manifest.description:
+        lines.append(f"///\n/// {manifest.description}")
+    lines += [f"class {name}Model {{", f"  {name}Model._(this.model);", ""]
+    if location is not None:
+        lines += [
+            "  /// Where the bundle is published.",
+            f"  static const defaultLocation = '{location}';",
+            "",
+        ]
+    for spec, member in zip(inputs, in_names, strict=True):
+        lines += [
+            f"  /// Shape of input {_doc(spec)}.",
+            f"  static const {member}Shape = <int>{spec.shape};",
+            "",
+        ]
+
+    lines.append("  /// Downloads (if needed), verifies, and opens the model.")
+    if location is not None:
+        lines += [f"  static Future<{name}Model> load({{", "    String location = defaultLocation,"]
+    else:
+        lines += [f"  static Future<{name}Model> load(", "    String location, {"]
+    lines += [
+        "    String? variantId,",
+        "    void Function(DownloadProgress)? onProgress,",
+        "  }) async =>",
+        f"      {name}Model._(",
+        "        await ModelPort.load(location, variantId: variantId, onProgress: onProgress),",
+        "      );",
+        "",
+        "  /// The underlying model, for golden checks and raw access.",
+        "  final TensorModel model;",
+        "",
+        "  /// Runs the model.",
+        "  ///",
+    ]
+    for spec in inputs:
+        lines.append(f"  /// * {_doc(spec)}")
+    params = "".join(f"required Tensor {m}, " for m in in_names).rstrip(", ")
+    lines += [
+        f"  Future<{name}Outputs> run({{{params}}}) async {{",
+        "    final outputs = await model.run({",
+    ]
+    for spec, member in zip(inputs, in_names, strict=True):
+        lines.append(f"      '{spec.name}': {member},")
+    lines += ["    });", f"    return {name}Outputs("]
+    for spec, member in zip(outputs, out_names, strict=True):
+        lines.append(f"      {member}: outputs['{spec.name}']!,")
+    lines += ["    );", "  }", "", "  Future<void> close() => model.close();", "}", ""]
+
+    lines += [
+        f"/// Outputs of {name}Model.run.",
+        f"class {name}Outputs {{",
+        f"  const {name}Outputs({{",
+    ]
+    for member in out_names:
+        lines.append(f"    required this.{member},")
+    lines += ["  });", ""]
+    for spec, member in zip(outputs, out_names, strict=True):
+        lines += [f"  /// {_doc(spec)}.", f"  final Tensor {member};", ""]
+    lines[-1] = "}"
+    return "\n".join(lines) + "\n"
+
+
+def format_with_dart(source: str) -> str | None:
+    """Format Dart source with `dart format`, or return None if Dart is not installed."""
+    import shutil
+    import subprocess
+    import tempfile
+    from pathlib import Path
+
+    dart = shutil.which("dart")
+    if dart is None:
+        return None
+    with tempfile.TemporaryDirectory() as tmp:
+        path = Path(tmp) / "generated.dart"
+        path.write_text(source, encoding="utf-8")
+        result = subprocess.run(
+            [dart, "format", "--output=write", str(path)],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if result.returncode != 0:
+            raise ModelPortError(f"dart format failed on generated code:\n{result.stderr}")
+        return path.read_text(encoding="utf-8")

modelport/doctor.py

@@ -0,0 +1,88 @@
+"""Check the local environment for what each CLI feature needs."""
+
+from __future__ import annotations
+
+import platform
+import shutil
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from importlib import metadata
+from pathlib import Path
+
+from . import __version__
+
+# extra name -> packages it installs, in the order shown to users
+EXTRAS: dict[str, tuple[str, ...]] = {
+    "onnx": ("onnx", "onnxruntime", "onnxscript", "torch"),
+    "executorch": ("executorch", "torch"),
+    "gguf": ("gguf",),
+    "torchvision": ("torchvision", "torch"),
+    "hf": ("transformers", "huggingface-hub", "torch"),
+}
+
+LOW_DISK_BYTES = 5 * 1000**3
+
+
+@dataclass(frozen=True)
+class PackageStatus:
+    name: str
+    extra: str
+    version: str | None
+
+    @property
+    def installed(self) -> bool:
+        return self.version is not None
+
+
+@dataclass(frozen=True)
+class DoctorReport:
+    modelport_version: str
+    python_version: str
+    platform: str
+    free_disk_bytes: int
+    packages: list[PackageStatus]
+    problems: list[str] = field(default_factory=list)
+    hints: list[str] = field(default_factory=list)
+
+
+def installed_version(name: str) -> str | None:
+    try:
+        return metadata.version(name)
+    except metadata.PackageNotFoundError:
+        return None
+
+
+def collect_report(
+    folder: Path | None = None,
+    version_of: Callable[[str], str | None] = installed_version,
+) -> DoctorReport:
+    """Gather versions and disk space. Never imports heavy packages such as torch."""
+    packages = [
+        PackageStatus(name=name, extra=extra, version=version_of(name))
+        for extra, names in EXTRAS.items()
+        for name in names
+    ]
+    free = shutil.disk_usage(folder or Path.cwd()).free
+
+    problems: list[str] = []
+    hints: list[str] = []
+    for extra, names in EXTRAS.items():
+        statuses = [p for p in packages if p.name in names]
+        missing = [p.name for p in statuses if not p.installed]
+        if missing and len(missing) < len(statuses):
+            problems.append(f"'{extra}' is only partly installed, missing: {', '.join(missing)}")
+        if missing:
+            hints.append(f"pip install 'modelport-cli[{extra}]'")
+    if free < LOW_DISK_BYTES:
+        problems.append(f"Only {free / 1000**3:.1f} GB free. Exports and LLM downloads need more.")
+
+    return DoctorReport(
+        modelport_version=__version__,
+        python_version=platform.python_version(),
+        platform=f"{platform.system()} {platform.machine()} ({sys.platform})",
+        free_disk_bytes=free,
+        packages=packages,
+        problems=problems,
+        hints=hints,
+    )

modelport/errors.py

@@ -0,0 +1,18 @@
+"""Errors that the CLI turns into short messages instead of tracebacks."""
+
+from __future__ import annotations
+
+
+class ModelPortError(Exception):
+    """Base class for expected, user-facing errors."""
+
+
+class MissingDependencyError(ModelPortError):
+    """An optional package needed for this feature is not installed."""
+
+    def __init__(self, feature: str, extra: str) -> None:
+        super().__init__(
+            f"{feature} needs extra packages. "
+            f"Install them with: pip install 'modelport-cli[{extra}]'"
+        )
+        self.extra = extra

modelport/exporters/__init__.py

@@ -0,0 +1,55 @@
+"""Turn a SourceModel into model files for each target runtime."""
+
+from __future__ import annotations
+
+import contextlib
+import io
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass, field
+
+from ..bundle import Bundle
+from ..errors import ModelPortError
+from ..manifest import Runtime
+from ..sources import SourceModel
+
+
+class ExportError(ModelPortError):
+    """A model could not be exported."""
+
+
+@dataclass(frozen=True)
+class ExportedVariant:
+    """Files written for one variant, as bundle-relative paths."""
+
+    id: str
+    runtime: Runtime
+    precision: str
+    main_file: str
+    extra_files: list[str] = field(default_factory=list)
+    backend: str | None = None
+
+
+Exporter = Callable[[SourceModel, Bundle], ExportedVariant]
+
+
+@contextlib.contextmanager
+def quiet_output() -> Iterator[io.StringIO]:
+    """Capture the progress lines that exporters print, to show them only on failure."""
+    buffer = io.StringIO()
+    with contextlib.redirect_stdout(buffer), contextlib.redirect_stderr(buffer):
+        yield buffer
+
+
+def get_exporter(target: str) -> Exporter:
+    if target == "onnx":
+        from .onnx import export_onnx
+
+        return export_onnx
+    if target == "executorch":
+        from .executorch import export_executorch
+
+        return export_executorch
+    raise ExportError(f"unknown export target '{target}'. Available: onnx, executorch")
+
+
+__all__ = ["ExportError", "ExportedVariant", "Exporter", "get_exporter", "quiet_output"]

modelport/exporters/executorch.py

@@ -0,0 +1,46 @@
+"""Export to an ExecuTorch program (.pte) delegated to XNNPACK."""
+
+from __future__ import annotations
+
+from ..bundle import Bundle
+from ..errors import MissingDependencyError
+from ..manifest import Runtime
+from ..sources import SourceModel
+from . import ExportedVariant, ExportError, quiet_output
+
+VARIANT_ID = "executorch-xnnpack-fp32"
+MODEL_PATH = f"{VARIANT_ID}/model.pte"
+
+
+def export_executorch(source: SourceModel, bundle: Bundle) -> ExportedVariant:
+    try:
+        import torch
+        from executorch.backends.xnnpack.partition.xnnpack_partitioner import (
+            XnnpackPartitioner,
+        )
+        from executorch.exir import to_edge_transform_and_lower
+    except ImportError as error:
+        raise MissingDependencyError("Exporting to ExecuTorch", "executorch") from error
+
+    # ExecuTorch records the memory layout of example inputs. A channels_last example
+    # makes the program reject ordinary NCHW tensors at run time (found in Phase 0).
+    example = tuple(t.contiguous() for t in source.example_inputs)
+    with quiet_output() as log, torch.no_grad():
+        try:
+            exported = torch.export.export(source.module, example)
+            program = to_edge_transform_and_lower(
+                exported, partitioner=[XnnpackPartitioner()]
+            ).to_executorch()
+        except Exception as error:
+            raise ExportError(f"ExecuTorch export failed: {error}\n{log.getvalue()}") from error
+
+    target = bundle.path(MODEL_PATH)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(program.buffer)
+    return ExportedVariant(
+        id=VARIANT_ID,
+        runtime=Runtime.EXECUTORCH,
+        precision="fp32",
+        backend="xnnpack",
+        main_file=MODEL_PATH,
+    )

modelport/exporters/onnx.py

@@ -0,0 +1,63 @@
+"""Export to ONNX with the torch.export-based (dynamo) exporter."""
+
+from __future__ import annotations
+
+from ..bundle import Bundle
+from ..errors import MissingDependencyError
+from ..manifest import Runtime
+from ..sources import SourceModel
+from . import ExportedVariant, ExportError, quiet_output
+
+VARIANT_ID = "onnx-fp32"
+MODEL_PATH = f"{VARIANT_ID}/model.onnx"
+# ONNX protobuf files cannot exceed 2 GB, so larger weights go to a side file.
+EXTERNAL_DATA_BYTES = 1_800_000_000
+
+
+def export_onnx(source: SourceModel, bundle: Bundle) -> ExportedVariant:
+    try:
+        import onnx
+        import torch
+    except ImportError as error:
+        raise MissingDependencyError("Exporting to ONNX", "onnx") from error
+
+    target = bundle.path(MODEL_PATH)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    weight_bytes = sum(p.numel() * p.element_size() for p in source.module.parameters())
+    external = weight_bytes > EXTERNAL_DATA_BYTES
+    # Contiguous inputs keep the exported graph in plain NCHW memory layout.
+    example = tuple(t.contiguous() for t in source.example_inputs)
+
+    with quiet_output() as log, torch.no_grad():
+        try:
+            torch.onnx.export(
+                source.module,
+                example,
+                str(target),
+                dynamo=True,
+                input_names=[spec.name for spec in source.inputs],
+                output_names=source.output_names,
+                external_data=external,
+            )
+        except Exception as error:
+            raise ExportError(f"ONNX export failed: {error}\n{log.getvalue()}") from error
+
+    onnx.checker.check_model(str(target))
+    graph = onnx.load(str(target), load_external_data=False).graph
+    initializers = {init.name for init in graph.initializer}
+    got_inputs = [v.name for v in graph.input if v.name not in initializers]
+    got_outputs = [v.name for v in graph.output]
+    if got_inputs != [s.name for s in source.inputs] or got_outputs != source.output_names:
+        raise ExportError(
+            f"exported names {got_inputs} -> {got_outputs} do not match "
+            f"{[s.name for s in source.inputs]} -> {source.output_names}"
+        )
+
+    extra = [f"{MODEL_PATH}.data"] if bundle.path(f"{MODEL_PATH}.data").is_file() else []
+    return ExportedVariant(
+        id=VARIANT_ID,
+        runtime=Runtime.ONNX,
+        precision="fp32",
+        main_file=MODEL_PATH,
+        extra_files=extra,
+    )

modelport/gguf_import.py

@@ -0,0 +1,197 @@
+"""Describe ready-made GGUF language models with a manifest.
+
+Large GGUF files are not copied: the manifest points at them with pinned
+Hugging Face URLs, so a bundle is just modelport.json.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .bundle import Bundle
+from .errors import MissingDependencyError, ModelPortError
+from .manifest import FileRef, LlmConfig, Manifest, Runtime, Task, Variant
+from .sources import model_id as make_id
+
+_QUANT = re.compile(r"[-_.]((?:i?q\d\w*)|bf16|f16|f32)\.gguf$", re.IGNORECASE)
+_SPLIT = re.compile(r"-\d{5}-of-\d{5}\.gguf$", re.IGNORECASE)
+
+
+class GgufImportError(ModelPortError):
+    """A GGUF model could not be described."""
+
+
+@dataclass(frozen=True)
+class GgufImport:
+    manifest: Manifest
+    warnings: list[str] = field(default_factory=list)
+
+
+def quant_of(filename: str) -> str | None:
+    """'qwen2.5-0.5b-instruct-q4_k_m.gguf' -> 'q4_k_m'."""
+    match = _QUANT.search(filename)
+    return match.group(1).lower() if match else None
+
+
+def estimate_min_ram_mb(size_bytes: int, context: int) -> int:
+    """A rough lower bound: weights, a KV cache for `context`, and runtime overhead."""
+    mib = size_bytes / 2**20 * 1.1 + 256 + context / 1024 * 32
+    return int(math.ceil(mib / 256) * 256)
+
+
+def _bundle_id(name: str) -> str:
+    base = make_id(name)
+    return base[: -len("-gguf")] if base.endswith("-gguf") else base
+
+
+def import_from_hub(
+    repo: str,
+    quants: list[str],
+    *,
+    revision: str | None = None,
+    context: int = 4096,
+    license: str | None = None,
+    model_id: str | None = None,
+) -> GgufImport:
+    """Build a manifest for GGUF files in a Hugging Face repo, without downloading them."""
+    try:
+        from huggingface_hub import HfApi
+    except ImportError as error:
+        raise MissingDependencyError("Importing GGUF models from the Hub", "hf") from error
+
+    api = HfApi()
+    try:
+        info = api.model_info(repo, revision=revision, files_metadata=True)
+        summary = getattr(api.model_info(repo, revision=revision, expand=["gguf"]), "gguf", None)
+    except Exception as error:
+        raise GgufImportError(
+            f"could not read {repo} from the Hugging Face Hub: {error}"
+        ) from error
+
+    files: dict[str, Any] = {}
+    for sibling in info.siblings or []:
+        name = sibling.rfilename
+        if not name.endswith(".gguf") or _SPLIT.search(name):
+            continue
+        quant = quant_of(Path(name).name)
+        if quant and quant not in files:
+            files[quant] = sibling
+    if not files:
+        raise GgufImportError(f"{repo} has no single-file GGUF models")
+
+    warnings: list[str] = []
+    gguf = summary if isinstance(summary, dict) else {}
+    trained = gguf.get("context_length")
+    if trained and context > trained:
+        warnings.append(f"context {context} is above the trained {trained}; using {trained}")
+        context = int(trained)
+    if not gguf.get("chat_template"):
+        warnings.append("the GGUF has no chat template, so chat may not work")
+
+    license = license or _card_license(info)
+    if not license:
+        raise GgufImportError(f"no license found for {repo}. Pass it with --license")
+
+    variants = []
+    for quant in [q.lower() for q in quants]:
+        sibling = files.get(quant)
+        if sibling is None:
+            raise GgufImportError(
+                f"{repo} has no {quant} file. Available: {', '.join(sorted(files))}"
+            )
+        sha256 = _lfs_sha256(sibling)
+        if sha256 is None or not sibling.size:
+            raise GgufImportError(f"{sibling.rfilename} has no size or sha256 on the Hub")
+        url = f"https://huggingface.co/{repo}/resolve/{info.sha}/{sibling.rfilename}"
+        variants.append(
+            Variant(
+                id=f"gguf-{quant}",
+                runtime=Runtime.LLAMACPP,
+                precision=quant,
+                file=FileRef(url=url, size=sibling.size, sha256=sha256),
+                min_ram_mb=estimate_min_ram_mb(sibling.size, context),
+            )
+        )
+
+    manifest = Manifest(
+        id=model_id or _bundle_id(repo),
+        version="1.0.0",
+        task=Task.TEXT_GENERATION,
+        license=license,
+        name=repo.split("/")[-1],
+        description=f"{gguf.get('architecture', 'GGUF')} model from {repo}.",
+        source=f"hf:{repo}@{(info.sha or '')[:12]}",
+        variants=variants,
+        llm=LlmConfig(context_length=context),
+    )
+    return GgufImport(manifest, warnings)
+
+
+def import_from_file(
+    path: str | Path,
+    bundle: Bundle,
+    *,
+    context: int = 4096,
+    license: str,
+    model_id: str | None = None,
+) -> GgufImport:
+    """Copy a local GGUF file into a bundle and describe it."""
+    from .inspection import inspect_model
+
+    source = Path(path)
+    info = inspect_model(source)
+    if info.format != "gguf":
+        raise GgufImportError(f"{source} is not a GGUF file")
+    quant = quant_of(source.name) or info.metadata.get("quantization", "unknown").lower()
+    warnings: list[str] = []
+    trained = info.metadata.get("context_length", "")
+    if trained.isdigit() and context > int(trained):
+        warnings.append(f"context {context} is above the trained {trained}; using {trained}")
+        context = int(trained)
+    if info.metadata.get("chat_template") != "yes":
+        warnings.append("the GGUF has no chat template, so chat may not work")
+
+    variant_id = f"gguf-{quant}"
+    relative = f"{variant_id}/model.gguf"
+    target = bundle.path(relative)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(source, target)
+    manifest = Manifest(
+        id=model_id or _bundle_id(info.metadata.get("name", source.stem)),
+        version="1.0.0",
+        task=Task.TEXT_GENERATION,
+        license=license,
+        name=info.metadata.get("name"),
+        source=f"file:{source.name}",
+        variants=[
+            Variant(
+                id=variant_id,
+                runtime=Runtime.LLAMACPP,
+                precision=quant,
+                file=bundle.add(relative),
+                min_ram_mb=estimate_min_ram_mb(info.size, context),
+            )
+        ],
+        llm=LlmConfig(context_length=context),
+    )
+    return GgufImport(manifest, warnings)
+
+
+def _card_license(info: Any) -> str | None:
+    card = getattr(info, "card_data", None)
+    value = getattr(card, "license", None) if card is not None else None
+    if isinstance(value, list):
+        value = value[0] if value else None
+    return str(value) if value else None
+
+
+def _lfs_sha256(sibling: Any) -> str | None:
+    lfs = getattr(sibling, "lfs", None)
+    if lfs is None:
+        return None
+    return lfs.get("sha256") if isinstance(lfs, dict) else getattr(lfs, "sha256", None)