zenthrix 0.2.0__tar.gz → 0.2.1__tar.gz

{zenthrix-0.2.0 → zenthrix-0.2.1}/.github/workflows/ci.yml

@@ -9,6 +9,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
@@ -17,7 +18,8 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - run: python -m pip install --upgrade pip
-      - run: python -m pip install pytest ruff mypy build
+      - run: python -m pip install pytest ruff mypy build tomli
+      - run: python -m pip install -e .
       - run: python -m ruff check .
       - run: python -m mypy python
       - run: python -m pytest

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

@@ -5,6 +5,19 @@ 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.1] - 2026-11-04
+
+### Added
+
+- Added JSON output for `zenthrix plugins` with runtime names and adapter paths.
+- Added project configuration documentation and compile defaults from
+  `zenthrix.toml`, including clear errors for malformed configuration.
+- GGUF inspection now reports the tensor count stored in the file header.
+
+### Changed
+
+- Bumped the package and public API version to `0.2.1`.
+
 ## [0.2.0] - 2026-09-23
 
 ### Added
@@ -83,3 +96,4 @@ and this project follows [Semantic Versioning](https://semver.org/).
 [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
+[0.2.1]: https://github.com/withbrian-technologies/zenthrix/releases/tag/v0.2.1

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zenthrix
-Version: 0.2.0
+Version: 0.2.1
 Summary: Hardware-adaptive edge neural graph compiler frontend
 Author: WithBrian Technologies
 License:                                  Apache License
@@ -353,6 +353,28 @@ failures are emitted as a JSON object with `error` and `message` fields:
 ```
 
 Successful inference uses `text`, `ttft_ms`, and `tokens_per_second` fields.
+The `plugins --json` command emits a JSON array containing each installed
+runtime's `name` and importable `adapter` path.
+
+### Project Configuration
+
+Create `zenthrix.toml` in the project directory to provide compile and run
+defaults. CLI arguments override values from the file:
+
+```toml
+[compile]
+model_format = "onnx"
+target = "auto"
+quantization = "int4"
+output = "./build/model.zx"
+
+[run]
+max_tokens = 256
+temperature = 0.2
+```
+
+The configuration file is discovered in the current directory or its parents.
+Malformed configuration is reported as a CLI error.
 
 ## Supported Target Architectures
 

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

@@ -138,6 +138,28 @@ failures are emitted as a JSON object with `error` and `message` fields:
 ```
 
 Successful inference uses `text`, `ttft_ms`, and `tokens_per_second` fields.
+The `plugins --json` command emits a JSON array containing each installed
+runtime's `name` and importable `adapter` path.
+
+### Project Configuration
+
+Create `zenthrix.toml` in the project directory to provide compile and run
+defaults. CLI arguments override values from the file:
+
+```toml
+[compile]
+model_format = "onnx"
+target = "auto"
+quantization = "int4"
+output = "./build/model.zx"
+
+[run]
+max_tokens = 256
+temperature = 0.2
+```
+
+The configuration file is discovered in the current directory or its parents.
+Malformed configuration is reported as a CLI error.
 
 ## Supported Target Architectures
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "zenthrix"
-version = "0.2.0"
+version = "0.2.1"
 description = "Hardware-adaptive edge neural graph compiler frontend"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -26,6 +26,7 @@ dev = [
   "mypy",
   "pytest",
   "ruff",
+  "tomli",
 ]
 
 [project.scripts]
@@ -47,6 +48,5 @@ target-version = "py310"
 select = ["E", "F", "I", "UP"]
 
 [tool.mypy]
-python_version = "3.10"
 strict = true
 mypy_path = "python"

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

@@ -4,7 +4,7 @@ from .engine import Engine, InferenceResult
 from .exceptions import EngineUnavailableError, InputValidationError, ZenthrixError
 from .metadata import ModelMetadata, TensorInfo
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = [
     "Engine",

{zenthrix-0.2.0 → zenthrix-0.2.1}/python/zenthrix/cli.py

@@ -12,7 +12,7 @@ if TYPE_CHECKING:
 
 from . import __version__
 from .engine import Engine
-from .exceptions import EngineUnavailableError, ZenthrixError
+from .exceptions import EngineUnavailableError, InputValidationError, ZenthrixError
 from .validation import (
     validate_compile_options,
     validate_compiled_model_path,
@@ -28,10 +28,10 @@ def build_parser() -> argparse.ArgumentParser:
 
     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("--format", default=None, dest="model_format")
+    compile_parser.add_argument("--target", default=None)
     compile_parser.add_argument("--quantization", default=None)
-    compile_parser.add_argument("--output", required=True)
+    compile_parser.add_argument("--output", default=None)
     compile_parser.add_argument("--json", action="store_true")
 
     inspect_parser = commands.add_parser(
@@ -48,14 +48,29 @@ def build_parser() -> argparse.ArgumentParser:
     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")
+    plugins_parser = commands.add_parser(
+        "plugins", help="List installed runtime plugins"
+    )
+    plugins_parser.add_argument("--json", action="store_true")
 
     return parser
 
 
 def _compile(args: argparse.Namespace) -> int:
+    if args.model_format is None:
+        raise InputValidationError(
+            "compile requires --format or model_format in zenthrix.toml"
+        )
+    if args.output is None:
+        raise InputValidationError(
+            "compile requires --output or output in zenthrix.toml"
+        )
     validate_model_input(args.model, args.model_format)
-    validate_compile_options(args.target, args.quantization, args.output)
+    validate_compile_options(
+        args.target if args.target is not None else "auto",
+        args.quantization,
+        args.output,
+    )
     raise ZenthrixError(
         "The native compiler engine is not installed. "
         "The public frontend cannot produce a .zx binary yet."
@@ -101,8 +116,8 @@ def _print_metadata(meta: ModelMetadata) -> None:
         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.tensor_count is not None:
+        lines.append(f"  Tensors:        {meta.tensor_count}")
     if meta.extra:
         for key, value in sorted(meta.extra.items()):
             lines.append(f"  {key}:  {value}")
@@ -142,10 +157,26 @@ def _run(args: argparse.Namespace) -> int:
     return 0
 
 
-def _plugins(_args: argparse.Namespace) -> int:
+def _plugins(args: argparse.Namespace) -> int:
     from .runtime import discover_runtimes
 
     runtimes = discover_runtimes()
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    {
+                        "name": name,
+                        "adapter": (
+                            f"{adapter_cls.__module__}:{adapter_cls.__qualname__}"
+                        ),
+                    }
+                    for name, adapter_cls in runtimes
+                ]
+            )
+        )
+        return 0
+
     if not runtimes:
         print("No runtime plugins installed.")
         print()
@@ -164,10 +195,10 @@ 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:
+        # Merge config-file defaults for compile/run when available
+        _apply_config_defaults(args)
+
         if args.command == "compile":
             return _compile(args)
         if args.command == "inspect":
@@ -203,10 +234,7 @@ def _apply_config_defaults(args: argparse.Namespace) -> None:
     if config_path is None:
         return
 
-    try:
-        config = load_config(config_path)
-    except Exception:
-        return  # silently skip broken config during CLI execution
+    config = load_config(config_path)
 
     command = getattr(args, "command", None)
     section = config.get(command, {}) if command else {}

{zenthrix-0.2.0 → zenthrix-0.2.1}/python/zenthrix/metadata.py

@@ -41,6 +41,7 @@ class ModelMetadata:
     estimated_memory_mb: float = 0.0
     architecture: str = ""
     extra: dict[str, str] = field(default_factory=dict)
+    tensor_count: int | None = None
 
     def to_dict(self) -> dict[str, Any]:
         """Serialize to a JSON-compatible dictionary."""
@@ -51,7 +52,11 @@ class ModelMetadata:
             "parameter_count": self.parameter_count,
             "estimated_memory_mb": round(self.estimated_memory_mb, 2),
             "architecture": self.architecture,
-            "tensor_count": len(self.tensors),
+            "tensor_count": (
+                len(self.tensors)
+                if self.tensor_count is None
+                else self.tensor_count
+            ),
             "extra": dict(self.extra),
         }
 
@@ -246,6 +251,7 @@ def _parse_gguf_header(path: Path) -> ModelMetadata:
         architecture=architecture,
         extra=extra,
         tensors=(),
+        tensor_count=tensor_count,
     )
 
 

{zenthrix-0.2.0 → zenthrix-0.2.1}/python/zenthrix/settings.py

@@ -19,7 +19,7 @@ if sys.version_info >= (3, 11):
     import tomllib
 else:
     try:
-        import tomli as tomllib  # type: ignore[import-not-found]
+        import tomli as tomllib
     except ModuleNotFoundError as exc:
         raise ImportError(
             "zenthrix requires the 'tomli' package on Python < 3.11. "
@@ -62,7 +62,7 @@ def load_config(path: Path) -> dict[str, Any]:
     """
     try:
         with open(path, "rb") as fh:
-            return tomllib.load(fh)  # type: ignore[no-any-return]
+            return tomllib.load(fh)
     except Exception as exc:
         raise InputValidationError(
             f"Failed to parse {path}: {exc}"

{zenthrix-0.2.0 → zenthrix-0.2.1}/tests/test_cli.py

@@ -81,6 +81,17 @@ def test_inspect_source_model_json_output(capsys, tmp_path: Path) -> None:
     assert payload["parameter_count"] == 12
 
 
+def test_inspect_gguf_reports_tensor_count(capsys, tmp_path: Path) -> None:
+    import struct
+
+    model = tmp_path / "model.gguf"
+    model.write_bytes(struct.pack("<IIQQ", 0x46475547, 3, 7, 0))
+
+    assert main(["inspect", str(model), "--json"]) == 0
+    payload = json.loads(capsys.readouterr().out)
+    assert payload["tensor_count"] == 7
+
+
 def test_compile_reports_missing_native_engine(tmp_path: Path, capsys) -> None:
     model = tmp_path / "model.onnx"
     model.write_bytes(b"placeholder")
@@ -102,6 +113,39 @@ def test_compile_reports_missing_native_engine(tmp_path: Path, capsys) -> None:
     assert "native compiler engine" in capsys.readouterr().err
 
 
+def test_compile_uses_config_defaults(
+    tmp_path: Path, monkeypatch, capsys
+) -> None:
+    model = tmp_path / "model.onnx"
+    model.write_bytes(b"placeholder")
+    (tmp_path / "zenthrix.toml").write_text(
+        "[compile]\n"
+        "model_format = 'onnx'\n"
+        "target = 'apple'\n"
+        "output = 'model.zx'\n"
+    )
+    monkeypatch.chdir(tmp_path)
+
+    assert main(["compile", "--model", str(model)]) == 2
+    assert "native compiler engine" in capsys.readouterr().err
+
+
+def test_compile_requires_config_or_cli_values(tmp_path: Path, capsys) -> None:
+    model = tmp_path / "model.onnx"
+    model.write_bytes(b"placeholder")
+
+    assert main(["compile", "--model", str(model)]) == 2
+    assert "--format" in capsys.readouterr().err
+
+
+def test_malformed_config_is_reported(tmp_path: Path, monkeypatch, capsys) -> None:
+    (tmp_path / "zenthrix.toml").write_text("[[[[invalid toml")
+    monkeypatch.chdir(tmp_path)
+
+    assert main(["plugins"]) == 2
+    assert "Failed to parse" in capsys.readouterr().err
+
+
 def test_compile_rejects_invalid_output_extension(tmp_path: Path, capsys) -> None:
     model = tmp_path / "model.onnx"
     model.write_bytes(b"placeholder")
@@ -127,3 +171,8 @@ def test_plugins_shows_no_plugins(capsys) -> None:
     assert main(["plugins"]) == 0
     output = capsys.readouterr().out
     assert "No runtime plugins installed" in output
+
+
+def test_plugins_json_output(capsys) -> None:
+    assert main(["plugins", "--json"]) == 0
+    assert json.loads(capsys.readouterr().out) == []

{zenthrix-0.2.0 → zenthrix-0.2.1}/tests/test_metadata.py

@@ -120,12 +120,14 @@ class TestExtractGgufMetadata:
 
         assert meta.format == "gguf"
         assert meta.architecture == "llama"
+        assert meta.tensor_count == 5
         assert meta.file_size_bytes > 0
 
     def test_version_in_extra(self, tmp_path):
         model = _write_gguf(tmp_path / "model.gguf", version=3)
         meta = extract_metadata(model)
         assert meta.extra.get("version") == "3"
+        assert meta.to_dict()["tensor_count"] == 5
 
     def test_bad_magic_rejected(self, tmp_path):
         model = tmp_path / "bad.gguf"

{zenthrix-0.2.0 → zenthrix-0.2.1}/uv.lock

@@ -487,8 +487,11 @@ wheels = [
 
 [[package]]
 name = "zenthrix"
-version = "0.1.3"
+version = "0.2.0"
 source = { editable = "." }
+dependencies = [
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+]
 
 [package.dev-dependencies]
 dev = [
@@ -496,9 +499,11 @@ dev = [
     { name = "mypy" },
     { name = "pytest" },
     { name = "ruff" },
+    { name = "tomli" },
 ]
 
 [package.metadata]
+requires-dist = [{ name = "tomli", marker = "python_full_version < '3.11'", specifier = ">=2.0" }]
 
 [package.metadata.requires-dev]
 dev = [
@@ -506,6 +511,7 @@ dev = [
     { name = "mypy" },
     { name = "pytest" },
     { name = "ruff" },
+    { name = "tomli" },
 ]
 
 [[package]]