zenthrix 0.1.2__tar.gz → 0.2.0__tar.gz

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

@@ -5,7 +5,34 @@ 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/).
 
-## [Unreleased]
+## [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
+
+- Added an injectable runtime adapter boundary so provisioned native runtimes
+  can implement inference without changing the public `Engine` API.
+- Added opt-in JSON output for CLI inference results and expected errors.
+- `zenthrix inspect` now returns a non-zero error when the native engine is
+  unavailable instead of reporting a successful but incomplete inspection.
+- ONNX and GGUF adapter path errors now use the public
+  `InputValidationError` type consistently.
+- Bumped the package and public API version to `0.1.3`.
 
 ## [0.1.2] - 2026-09-18
 
@@ -54,3 +81,5 @@ and this project follows [Semantic Versioning](https://semver.org/).
 [0.1.0]: https://github.com/withbrian-technologies/zenthrix/releases/tag/v0.1.0
 [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.2 → zenthrix-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zenthrix
-Version: 0.1.2
+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
@@ -217,6 +218,7 @@ Description-Content-Type: text/markdown
 **Hardware-Adaptive Edge Neural Graph Compiler**
 
 [![PyPI](https://img.shields.io/badge/pypi-zenthrix-blue)](https://pypi.org/project/zenthrix/)
+[![Release](https://img.shields.io/github/v/release/withbrian-technologies/zenthrix?label=release)](https://github.com/withbrian-technologies/zenthrix/releases/latest)
 [![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
 [![CI](https://img.shields.io/badge/CI-passing-brightgreen)](.github/workflows/ci.yml)
 
@@ -238,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.
@@ -290,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
@@ -329,6 +338,22 @@ print(f"Time to First Token (TTFT): {output.ttft_ms} ms")
 print(f"Throughput: {output.tokens_per_second} tokens/sec")
 ```
 
+### Automation and Runtime Availability
+
+The public package does not include the proprietary native compiler/runtime.
+`compile`, `inspect`, and `run` therefore return a non-zero status until a
+compatible runtime is provisioned; they never create placeholder artifacts or
+claim successful inference.
+
+For automation, add `--json` to `run`, `inspect`, or `compile`. Expected
+failures are emitted as a JSON object with `error` and `message` fields:
+
+```json
+{"error": "EngineUnavailableError", "message": "..."}
+```
+
+Successful inference uses `text`, `ttft_ms`, and `tokens_per_second` fields.
+
 ## Supported Target Architectures
 
 | Silicon Target | Optimization Backend | Compute Units |

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

@@ -3,6 +3,7 @@
 **Hardware-Adaptive Edge Neural Graph Compiler**
 
 [![PyPI](https://img.shields.io/badge/pypi-zenthrix-blue)](https://pypi.org/project/zenthrix/)
+[![Release](https://img.shields.io/github/v/release/withbrian-technologies/zenthrix?label=release)](https://github.com/withbrian-technologies/zenthrix/releases/latest)
 [![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
 [![CI](https://img.shields.io/badge/CI-passing-brightgreen)](.github/workflows/ci.yml)
 
@@ -24,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.
@@ -76,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
@@ -115,6 +123,22 @@ print(f"Time to First Token (TTFT): {output.ttft_ms} ms")
 print(f"Throughput: {output.tokens_per_second} tokens/sec")
 ```
 
+### Automation and Runtime Availability
+
+The public package does not include the proprietary native compiler/runtime.
+`compile`, `inspect`, and `run` therefore return a non-zero status until a
+compatible runtime is provisioned; they never create placeholder artifacts or
+claim successful inference.
+
+For automation, add `--json` to `run`, `inspect`, or `compile`. Expected
+failures are emitted as a JSON object with `error` and `message` fields:
+
+```json
+{"error": "EngineUnavailableError", "message": "..."}
+```
+
+Successful inference uses `text`, `ttft_ms`, and `tokens_per_second` fields.
+
 ## Supported Target Architectures
 
 | Silicon Target | Optimization Backend | Compute Units |

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "zenthrix"
-version = "0.1.2"
+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.2 → 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.2"
+__version__ = "0.2.0"
 
 __all__ = [
     "Engine",
     "EngineUnavailableError",
     "InferenceResult",
     "InputValidationError",
+    "ModelMetadata",
+    "TensorInfo",
     "ZenthrixError",
     "__version__",
 ]

{zenthrix-0.1.2 → 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.1.2 → zenthrix-0.2.0}/python/zenthrix/adapters/gguf_loader.py

@@ -2,6 +2,7 @@
 
 from pathlib import Path
 
+from ..exceptions import InputValidationError
 from ..validation import validate_model_path
 
 
@@ -9,6 +10,5 @@ def validate_gguf(path: str | Path) -> Path:
     """Validate a GGUF model path."""
     model_path = validate_model_path(path)
     if model_path.suffix.lower() != ".gguf":
-        raise ValueError(f"Expected a .gguf file, got: {model_path}")
+        raise InputValidationError(f"Expected a .gguf file, got: {model_path}")
     return model_path
-

{zenthrix-0.1.2 → zenthrix-0.2.0}/python/zenthrix/adapters/onnx_loader.py

@@ -2,6 +2,7 @@
 
 from pathlib import Path
 
+from ..exceptions import InputValidationError
 from ..validation import validate_model_path
 
 
@@ -9,5 +10,5 @@ def validate_onnx(path: str | Path) -> Path:
     """Validate an ONNX model path without importing optional ONNX tooling."""
     model_path = validate_model_path(path)
     if model_path.suffix.lower() != ".onnx":
-        raise ValueError(f"Expected an .onnx file, got: {model_path}")
+        raise InputValidationError(f"Expected an .onnx file, got: {model_path}")
     return model_path

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())

{zenthrix-0.1.2 → zenthrix-0.2.0}/python/zenthrix/engine.py

@@ -4,7 +4,7 @@ from dataclasses import dataclass
 from math import isfinite
 from pathlib import Path
 
-from .exceptions import EngineUnavailableError
+from .runtime import RuntimeAdapter, default_runtime
 from .validation import validate_compiled_model_path
 
 
@@ -25,8 +25,11 @@ class Engine:
     until that engine is provisioned.
     """
 
-    def __init__(self, model_path: str | Path) -> None:
+    def __init__(
+        self, model_path: str | Path, *, runtime: RuntimeAdapter | None = None
+    ) -> None:
         self.model_path = validate_compiled_model_path(model_path)
+        self._runtime = runtime if runtime is not None else default_runtime()
 
     def generate(
         self,
@@ -42,7 +45,14 @@ class Engine:
             raise ValueError("temperature must be a finite non-negative number")
         if max_tokens < 1:
             raise ValueError("max_tokens must be at least 1")
-        raise EngineUnavailableError(
-            "The Zenthrix native engine is not installed. "
-            "Install the platform runtime before calling Engine.generate()."
+        result = self._runtime.generate(
+            self.model_path,
+            prompt,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        return InferenceResult(
+            text=result.text,
+            ttft_ms=result.ttft_ms,
+            tokens_per_second=result.tokens_per_second,
         )