zenthrix 0.1.3__tar.gz → 0.2.0__tar.gz

{zenthrix-0.1.3 → zenthrix-0.2.0}/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to Zenthrix are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/).
 
+## [0.2.0] - 2026-09-23
+
+### Added
+
+- **SafeTensors format support**: Added `.safetensors` model input format adapter alongside ONNX, GGUF, and PyTorch.
+- **Model metadata inspection**: Extract tensor names, shapes, dtypes, parameter counts, and estimated memory footprint directly from SafeTensors, GGUF, and ONNX source model files without requiring the native engine or loading full weights into RAM.
+- **Configuration file support (`zenthrix.toml`)**: Added project-level defaults for compilation (`target`, `quantization`, `output`) and inference (`max_tokens`, `temperature`) resolved hierarchically with CLI override precedence.
+- **Runtime plugin discovery**: Dynamic discovery of third-party or native runtime adapters registered through the `zenthrix.runtimes` entry point group.
+- **`zenthrix plugins` CLI command**: Inspect and list all discovered runtime plugins in the current Python environment.
+- Exported `ModelMetadata` and `TensorInfo` in the public API.
+
+### Changed
+
+- Bumped the package and public API version to `0.2.0`.
+- Added conditional dependency on `tomli` for Python < 3.11.
+
 ## [0.1.3] - 2026-09-18
 
 ### Changed
@@ -66,3 +82,4 @@ and this project follows [Semantic Versioning](https://semver.org/).
 [0.1.1]: https://github.com/withbrian-technologies/zenthrix/releases/tag/v0.1.1
 [0.1.2]: https://github.com/withbrian-technologies/zenthrix/releases/tag/v0.1.2
 [0.1.3]: https://github.com/withbrian-technologies/zenthrix/releases/tag/v0.1.3
+[0.2.0]: https://github.com/withbrian-technologies/zenthrix/releases/tag/v0.2.0

{zenthrix-0.1.3 → zenthrix-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zenthrix
-Version: 0.1.3
+Version: 0.2.0
 Summary: Hardware-adaptive edge neural graph compiler frontend
 Author: WithBrian Technologies
 License:                                  Apache License
@@ -210,6 +210,7 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Requires-Python: >=3.10
+Requires-Dist: tomli>=2.0; python_version < '3.11'
 Description-Content-Type: text/markdown
 
 # Zenthrix
@@ -239,7 +240,7 @@ Zenthrix is an edge-native model compiler frontend for compiling open-weight neu
 
 ## Key Features
 
-- **Direct Ingestion** — Native loaders for ONNX, PyTorch Export (AOTInductor), and GGUF architectures, with no intermediate format conversion required.
+- **Direct Ingestion** — Native loaders for SafeTensors, ONNX, PyTorch Export (AOTInductor), and GGUF architectures, with no intermediate format conversion required.
 - **Unified Memory Tiling** — Schedules compute passes against unified memory architectures, reducing peak active RAM allocation by up to 40%.
 - **Zero-Copy Runtime** — Emits standalone, relocatable `.zx` binaries that execute locally without a heavy Python runtime dependency.
 - **Privacy-First Compilation** — Models compile entirely on-device; weights and computational graphs never leave the local environment.
@@ -291,9 +292,16 @@ zenthrix compile \
   --output ./llama-3.2-1b.zx
 ```
 
-### 2. Inspect Graph Optimizations
+### 2. Inspect Models & Graph Optimizations
 
-Analyze operator fusions and projected memory footprints prior to compilation:
+Inspect uncompiled source models (`.safetensors`, `.gguf`, `.onnx`) directly to view parameter counts, tensor shapes, and estimated memory footprint without requiring the native engine:
+
+```bash
+zenthrix inspect ./model.safetensors
+zenthrix inspect ./model.gguf --json
+```
+
+For compiled `.zx` binaries, inspect projected memory profiles and operator fusions:
 
 ```bash
 zenthrix inspect ./llama-3.2-1b.zx --memory-profile

{zenthrix-0.1.3 → zenthrix-0.2.0}/README.md

@@ -25,7 +25,7 @@ Zenthrix is an edge-native model compiler frontend for compiling open-weight neu
 
 ## Key Features
 
-- **Direct Ingestion** — Native loaders for ONNX, PyTorch Export (AOTInductor), and GGUF architectures, with no intermediate format conversion required.
+- **Direct Ingestion** — Native loaders for SafeTensors, ONNX, PyTorch Export (AOTInductor), and GGUF architectures, with no intermediate format conversion required.
 - **Unified Memory Tiling** — Schedules compute passes against unified memory architectures, reducing peak active RAM allocation by up to 40%.
 - **Zero-Copy Runtime** — Emits standalone, relocatable `.zx` binaries that execute locally without a heavy Python runtime dependency.
 - **Privacy-First Compilation** — Models compile entirely on-device; weights and computational graphs never leave the local environment.
@@ -77,9 +77,16 @@ zenthrix compile \
   --output ./llama-3.2-1b.zx
 ```
 
-### 2. Inspect Graph Optimizations
+### 2. Inspect Models & Graph Optimizations
 
-Analyze operator fusions and projected memory footprints prior to compilation:
+Inspect uncompiled source models (`.safetensors`, `.gguf`, `.onnx`) directly to view parameter counts, tensor shapes, and estimated memory footprint without requiring the native engine:
+
+```bash
+zenthrix inspect ./model.safetensors
+zenthrix inspect ./model.gguf --json
+```
+
+For compiled `.zx` binaries, inspect projected memory profiles and operator fusions:
 
 ```bash
 zenthrix inspect ./llama-3.2-1b.zx --memory-profile

{zenthrix-0.1.3 → zenthrix-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "zenthrix"
-version = "0.1.3"
+version = "0.2.0"
 description = "Hardware-adaptive edge neural graph compiler frontend"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -16,7 +16,9 @@ classifiers = [
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
 ]
-dependencies = []
+dependencies = [
+  "tomli>=2.0; python_version < '3.11'",
+]
 
 [dependency-groups]
 dev = [

{zenthrix-0.1.3 → zenthrix-0.2.0}/python/zenthrix/__init__.py

@@ -2,14 +2,17 @@
 
 from .engine import Engine, InferenceResult
 from .exceptions import EngineUnavailableError, InputValidationError, ZenthrixError
+from .metadata import ModelMetadata, TensorInfo
 
-__version__ = "0.1.3"
+__version__ = "0.2.0"
 
 __all__ = [
     "Engine",
     "EngineUnavailableError",
     "InferenceResult",
     "InputValidationError",
+    "ModelMetadata",
+    "TensorInfo",
     "ZenthrixError",
     "__version__",
 ]

{zenthrix-0.1.3 → zenthrix-0.2.0}/python/zenthrix/adapters/__init__.py

@@ -3,6 +3,12 @@
 from .gguf_loader import validate_gguf
 from .onnx_loader import validate_onnx
 from .pytorch_loader import validate_pytorch_export
+from .safetensors_loader import validate_safetensors
 
-__all__ = ["validate_gguf", "validate_onnx", "validate_pytorch_export"]
+__all__ = [
+    "validate_gguf",
+    "validate_onnx",
+    "validate_pytorch_export",
+    "validate_safetensors",
+]
 

zenthrix-0.2.0/python/zenthrix/adapters/safetensors_loader.py

@@ -0,0 +1,16 @@
+"""SafeTensors input validation."""
+
+from pathlib import Path
+
+from ..exceptions import InputValidationError
+from ..validation import validate_model_path
+
+
+def validate_safetensors(path: str | Path) -> Path:
+    """Validate a SafeTensors model path."""
+    model_path = validate_model_path(path)
+    if model_path.suffix.lower() != ".safetensors":
+        raise InputValidationError(
+            f"Expected a .safetensors file, got: {model_path}"
+        )
+    return model_path

zenthrix-0.2.0/python/zenthrix/cli.py

@@ -0,0 +1,227 @@
+"""Command-line interface for the Zenthrix frontend."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .metadata import ModelMetadata
+
+from . import __version__
+from .engine import Engine
+from .exceptions import EngineUnavailableError, ZenthrixError
+from .validation import (
+    validate_compile_options,
+    validate_compiled_model_path,
+    validate_model_input,
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the command-line parser."""
+    parser = argparse.ArgumentParser(prog="zenthrix")
+    parser.add_argument("--version", action="version", version=__version__)
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    compile_parser = commands.add_parser("compile", help="Compile a model")
+    compile_parser.add_argument("--model", required=True)
+    compile_parser.add_argument("--format", required=True, dest="model_format")
+    compile_parser.add_argument("--target", default="auto")
+    compile_parser.add_argument("--quantization", default=None)
+    compile_parser.add_argument("--output", required=True)
+    compile_parser.add_argument("--json", action="store_true")
+
+    inspect_parser = commands.add_parser(
+        "inspect", help="Inspect a compiled or source model"
+    )
+    inspect_parser.add_argument("model")
+    inspect_parser.add_argument("--memory-profile", action="store_true")
+    inspect_parser.add_argument("--json", action="store_true")
+
+    run_parser = commands.add_parser("run", help="Run inference")
+    run_parser.add_argument("--model", required=True)
+    run_parser.add_argument("--prompt", required=True)
+    run_parser.add_argument("--max-tokens", type=int, default=None)
+    run_parser.add_argument("--temperature", type=float, default=None)
+    run_parser.add_argument("--json", action="store_true")
+
+    commands.add_parser("plugins", help="List installed runtime plugins")
+
+    return parser
+
+
+def _compile(args: argparse.Namespace) -> int:
+    validate_model_input(args.model, args.model_format)
+    validate_compile_options(args.target, args.quantization, args.output)
+    raise ZenthrixError(
+        "The native compiler engine is not installed. "
+        "The public frontend cannot produce a .zx binary yet."
+    )
+
+
+def _inspect(args: argparse.Namespace) -> int:
+    # Source model inspection — works without native engine
+    model_path = args.model
+    suffix = model_path.rsplit(".", 1)[-1].lower() if "." in model_path else ""
+
+    if suffix == "zx":
+        validate_compiled_model_path(model_path)
+        raise EngineUnavailableError(
+            "The Zenthrix native engine is not installed. "
+            "Install the platform runtime before inspecting compiled models."
+        )
+
+    # Inspect a source model (safetensors, gguf, onnx)
+    from .metadata import extract_metadata
+
+    meta = extract_metadata(model_path)
+
+    if args.json:
+        print(json.dumps(meta.to_dict()))
+    else:
+        _print_metadata(meta)
+    return 0
+
+
+def _print_metadata(meta: ModelMetadata) -> None:
+    """Pretty-print model metadata to stdout."""
+
+    lines = [
+        "",
+        f"  Model:          {meta.path}",
+        f"  Format:         {meta.format}",
+        f"  File size:      {_format_size(meta.file_size_bytes)}",
+    ]
+    if meta.parameter_count:
+        lines.append(f"  Parameters:     {meta.parameter_count:,}")
+    if meta.estimated_memory_mb:
+        lines.append(f"  Est. memory:    {meta.estimated_memory_mb:.1f} MB")
+    if meta.architecture:
+        lines.append(f"  Architecture:   {meta.architecture}")
+    if meta.tensors:
+        lines.append(f"  Tensors:        {len(meta.tensors)}")
+    if meta.extra:
+        for key, value in sorted(meta.extra.items()):
+            lines.append(f"  {key}:  {value}")
+    lines.append("")
+    print("\n".join(lines))
+
+
+def _format_size(size_bytes: int) -> str:
+    """Format byte count as a human-readable string."""
+    if size_bytes >= 1_073_741_824:
+        return f"{size_bytes / 1_073_741_824:.1f} GB"
+    if size_bytes >= 1_048_576:
+        return f"{size_bytes / 1_048_576:.1f} MB"
+    if size_bytes >= 1024:
+        return f"{size_bytes / 1024:.1f} KB"
+    return f"{size_bytes} B"
+
+
+def _run(args: argparse.Namespace) -> int:
+    result = Engine(args.model).generate(
+        args.prompt,
+        temperature=args.temperature if args.temperature is not None else 0.2,
+        max_tokens=args.max_tokens if args.max_tokens is not None else 128,
+    )
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "text": result.text,
+                    "ttft_ms": result.ttft_ms,
+                    "tokens_per_second": result.tokens_per_second,
+                }
+            )
+        )
+    else:
+        print(result.text)
+    return 0
+
+
+def _plugins(_args: argparse.Namespace) -> int:
+    from .runtime import discover_runtimes
+
+    runtimes = discover_runtimes()
+    if not runtimes:
+        print("No runtime plugins installed.")
+        print()
+        print("Install a compatible runtime package, or see:")
+        print("  https://github.com/withbrian-technologies/zenthrix#plugins")
+        return 0
+
+    print("Installed runtimes:")
+    for name, adapter_cls in runtimes:
+        module = f"{adapter_cls.__module__}:{adapter_cls.__qualname__}"
+        print(f"  • {name} ({module})")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI and return a process exit code."""
+    args = build_parser().parse_args(argv)
+
+    # Merge config-file defaults for compile/run when available
+    _apply_config_defaults(args)
+
+    try:
+        if args.command == "compile":
+            return _compile(args)
+        if args.command == "inspect":
+            return _inspect(args)
+        if args.command == "run":
+            return _run(args)
+        if args.command == "plugins":
+            return _plugins(args)
+    except (ZenthrixError, ValueError) as error:
+        if getattr(args, "json", False):
+            print(
+                json.dumps(
+                    {
+                        "error": type(error).__name__,
+                        "message": str(error),
+                    }
+                )
+            )
+        else:
+            print(f"zenthrix: error: {error}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def _apply_config_defaults(args: argparse.Namespace) -> None:
+    """Load zenthrix.toml and fill in missing CLI arguments."""
+    try:
+        from .settings import find_config, load_config
+    except ImportError:
+        return
+
+    config_path = find_config()
+    if config_path is None:
+        return
+
+    try:
+        config = load_config(config_path)
+    except Exception:
+        return  # silently skip broken config during CLI execution
+
+    command = getattr(args, "command", None)
+    section = config.get(command, {}) if command else {}
+    if not isinstance(section, dict):
+        return
+
+    for key, value in section.items():
+        # CLI arguments take precedence — only fill in None values
+        current = getattr(args, key, _SENTINEL)
+        if current is None:
+            setattr(args, key, value)
+
+
+_SENTINEL = object()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())