zenthrix 0.1.2__tar.gz → 0.1.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. {zenthrix-0.1.2 → zenthrix-0.1.3}/CHANGELOG.md +13 -1
  2. {zenthrix-0.1.2 → zenthrix-0.1.3}/PKG-INFO +18 -1
  3. {zenthrix-0.1.2 → zenthrix-0.1.3}/README.md +17 -0
  4. {zenthrix-0.1.2 → zenthrix-0.1.3}/pyproject.toml +1 -1
  5. {zenthrix-0.1.2 → zenthrix-0.1.3}/python/zenthrix/__init__.py +1 -1
  6. {zenthrix-0.1.2 → zenthrix-0.1.3}/python/zenthrix/adapters/gguf_loader.py +2 -2
  7. {zenthrix-0.1.2 → zenthrix-0.1.3}/python/zenthrix/adapters/onnx_loader.py +2 -1
  8. {zenthrix-0.1.2 → zenthrix-0.1.3}/python/zenthrix/cli.py +33 -7
  9. {zenthrix-0.1.2 → zenthrix-0.1.3}/python/zenthrix/engine.py +15 -5
  10. zenthrix-0.1.3/python/zenthrix/runtime.py +53 -0
  11. {zenthrix-0.1.2 → zenthrix-0.1.3}/tests/test_cli.py +26 -3
  12. {zenthrix-0.1.2 → zenthrix-0.1.3}/tests/test_engine.py +23 -0
  13. {zenthrix-0.1.2 → zenthrix-0.1.3}/tests/test_validation.py +1 -1
  14. {zenthrix-0.1.2 → zenthrix-0.1.3}/uv.lock +1 -1
  15. {zenthrix-0.1.2 → zenthrix-0.1.3}/.github/CODEOWNERS +0 -0
  16. {zenthrix-0.1.2 → zenthrix-0.1.3}/.github/ISSUE_TEMPLATE/bug_report.yml +0 -0
  17. {zenthrix-0.1.2 → zenthrix-0.1.3}/.github/ISSUE_TEMPLATE/config.yml +0 -0
  18. {zenthrix-0.1.2 → zenthrix-0.1.3}/.github/ISSUE_TEMPLATE/feature_request.yml +0 -0
  19. {zenthrix-0.1.2 → zenthrix-0.1.3}/.github/SECURITY.md +0 -0
  20. {zenthrix-0.1.2 → zenthrix-0.1.3}/.github/SUPPORT.md +0 -0
  21. {zenthrix-0.1.2 → zenthrix-0.1.3}/.github/dependabot.yml +0 -0
  22. {zenthrix-0.1.2 → zenthrix-0.1.3}/.github/pull_request_template.md +0 -0
  23. {zenthrix-0.1.2 → zenthrix-0.1.3}/.github/workflows/ci.yml +0 -0
  24. {zenthrix-0.1.2 → zenthrix-0.1.3}/.github/workflows/release.yml +0 -0
  25. {zenthrix-0.1.2 → zenthrix-0.1.3}/.gitignore +0 -0
  26. {zenthrix-0.1.2 → zenthrix-0.1.3}/CONTRIBUTING.md +0 -0
  27. {zenthrix-0.1.2 → zenthrix-0.1.3}/LICENSE +0 -0
  28. {zenthrix-0.1.2 → zenthrix-0.1.3}/python/zenthrix/adapters/__init__.py +0 -0
  29. {zenthrix-0.1.2 → zenthrix-0.1.3}/python/zenthrix/adapters/pytorch_loader.py +0 -0
  30. {zenthrix-0.1.2 → zenthrix-0.1.3}/python/zenthrix/config.py +0 -0
  31. {zenthrix-0.1.2 → zenthrix-0.1.3}/python/zenthrix/exceptions.py +0 -0
  32. {zenthrix-0.1.2 → zenthrix-0.1.3}/python/zenthrix/validation.py +0 -0
@@ -5,7 +5,18 @@ All notable changes to Zenthrix are documented here.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project follows [Semantic Versioning](https://semver.org/).
7
7
 
8
- ## [Unreleased]
8
+ ## [0.1.3] - 2026-09-18
9
+
10
+ ### Changed
11
+
12
+ - Added an injectable runtime adapter boundary so provisioned native runtimes
13
+ can implement inference without changing the public `Engine` API.
14
+ - Added opt-in JSON output for CLI inference results and expected errors.
15
+ - `zenthrix inspect` now returns a non-zero error when the native engine is
16
+ unavailable instead of reporting a successful but incomplete inspection.
17
+ - ONNX and GGUF adapter path errors now use the public
18
+ `InputValidationError` type consistently.
19
+ - Bumped the package and public API version to `0.1.3`.
9
20
 
10
21
  ## [0.1.2] - 2026-09-18
11
22
 
@@ -54,3 +65,4 @@ and this project follows [Semantic Versioning](https://semver.org/).
54
65
  [0.1.0]: https://github.com/withbrian-technologies/zenthrix/releases/tag/v0.1.0
55
66
  [0.1.1]: https://github.com/withbrian-technologies/zenthrix/releases/tag/v0.1.1
56
67
  [0.1.2]: https://github.com/withbrian-technologies/zenthrix/releases/tag/v0.1.2
68
+ [0.1.3]: https://github.com/withbrian-technologies/zenthrix/releases/tag/v0.1.3
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: zenthrix
3
- Version: 0.1.2
3
+ Version: 0.1.3
4
4
  Summary: Hardware-adaptive edge neural graph compiler frontend
5
5
  Author: WithBrian Technologies
6
6
  License: Apache License
@@ -217,6 +217,7 @@ Description-Content-Type: text/markdown
217
217
  **Hardware-Adaptive Edge Neural Graph Compiler**
218
218
 
219
219
  [![PyPI](https://img.shields.io/badge/pypi-zenthrix-blue)](https://pypi.org/project/zenthrix/)
220
+ [![Release](https://img.shields.io/github/v/release/withbrian-technologies/zenthrix?label=release)](https://github.com/withbrian-technologies/zenthrix/releases/latest)
220
221
  [![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
221
222
  [![CI](https://img.shields.io/badge/CI-passing-brightgreen)](.github/workflows/ci.yml)
222
223
 
@@ -329,6 +330,22 @@ print(f"Time to First Token (TTFT): {output.ttft_ms} ms")
329
330
  print(f"Throughput: {output.tokens_per_second} tokens/sec")
330
331
  ```
331
332
 
333
+ ### Automation and Runtime Availability
334
+
335
+ The public package does not include the proprietary native compiler/runtime.
336
+ `compile`, `inspect`, and `run` therefore return a non-zero status until a
337
+ compatible runtime is provisioned; they never create placeholder artifacts or
338
+ claim successful inference.
339
+
340
+ For automation, add `--json` to `run`, `inspect`, or `compile`. Expected
341
+ failures are emitted as a JSON object with `error` and `message` fields:
342
+
343
+ ```json
344
+ {"error": "EngineUnavailableError", "message": "..."}
345
+ ```
346
+
347
+ Successful inference uses `text`, `ttft_ms`, and `tokens_per_second` fields.
348
+
332
349
  ## Supported Target Architectures
333
350
 
334
351
  | Silicon Target | Optimization Backend | Compute Units |
@@ -3,6 +3,7 @@
3
3
  **Hardware-Adaptive Edge Neural Graph Compiler**
4
4
 
5
5
  [![PyPI](https://img.shields.io/badge/pypi-zenthrix-blue)](https://pypi.org/project/zenthrix/)
6
+ [![Release](https://img.shields.io/github/v/release/withbrian-technologies/zenthrix?label=release)](https://github.com/withbrian-technologies/zenthrix/releases/latest)
6
7
  [![License](https://img.shields.io/badge/license-Apache%202.0-green)](LICENSE)
7
8
  [![CI](https://img.shields.io/badge/CI-passing-brightgreen)](.github/workflows/ci.yml)
8
9
 
@@ -115,6 +116,22 @@ print(f"Time to First Token (TTFT): {output.ttft_ms} ms")
115
116
  print(f"Throughput: {output.tokens_per_second} tokens/sec")
116
117
  ```
117
118
 
119
+ ### Automation and Runtime Availability
120
+
121
+ The public package does not include the proprietary native compiler/runtime.
122
+ `compile`, `inspect`, and `run` therefore return a non-zero status until a
123
+ compatible runtime is provisioned; they never create placeholder artifacts or
124
+ claim successful inference.
125
+
126
+ For automation, add `--json` to `run`, `inspect`, or `compile`. Expected
127
+ failures are emitted as a JSON object with `error` and `message` fields:
128
+
129
+ ```json
130
+ {"error": "EngineUnavailableError", "message": "..."}
131
+ ```
132
+
133
+ Successful inference uses `text`, `ttft_ms`, and `tokens_per_second` fields.
134
+
118
135
  ## Supported Target Architectures
119
136
 
120
137
  | Silicon Target | Optimization Backend | Compute Units |
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "zenthrix"
7
- version = "0.1.2"
7
+ version = "0.1.3"
8
8
  description = "Hardware-adaptive edge neural graph compiler frontend"
9
9
  readme = "README.md"
10
10
  license = { file = "LICENSE" }
@@ -3,7 +3,7 @@
3
3
  from .engine import Engine, InferenceResult
4
4
  from .exceptions import EngineUnavailableError, InputValidationError, ZenthrixError
5
5
 
6
- __version__ = "0.1.2"
6
+ __version__ = "0.1.3"
7
7
 
8
8
  __all__ = [
9
9
  "Engine",
@@ -2,6 +2,7 @@
2
2
 
3
3
  from pathlib import Path
4
4
 
5
+ from ..exceptions import InputValidationError
5
6
  from ..validation import validate_model_path
6
7
 
7
8
 
@@ -9,6 +10,5 @@ def validate_gguf(path: str | Path) -> Path:
9
10
  """Validate a GGUF model path."""
10
11
  model_path = validate_model_path(path)
11
12
  if model_path.suffix.lower() != ".gguf":
12
- raise ValueError(f"Expected a .gguf file, got: {model_path}")
13
+ raise InputValidationError(f"Expected a .gguf file, got: {model_path}")
13
14
  return model_path
14
-
@@ -2,6 +2,7 @@
2
2
 
3
3
  from pathlib import Path
4
4
 
5
+ from ..exceptions import InputValidationError
5
6
  from ..validation import validate_model_path
6
7
 
7
8
 
@@ -9,5 +10,5 @@ def validate_onnx(path: str | Path) -> Path:
9
10
  """Validate an ONNX model path without importing optional ONNX tooling."""
10
11
  model_path = validate_model_path(path)
11
12
  if model_path.suffix.lower() != ".onnx":
12
- raise ValueError(f"Expected an .onnx file, got: {model_path}")
13
+ raise InputValidationError(f"Expected an .onnx file, got: {model_path}")
13
14
  return model_path
@@ -1,11 +1,12 @@
1
1
  """Command-line interface for the Zenthrix frontend."""
2
2
 
3
3
  import argparse
4
+ import json
4
5
  import sys
5
6
 
6
7
  from . import __version__
7
8
  from .engine import Engine
8
- from .exceptions import ZenthrixError
9
+ from .exceptions import EngineUnavailableError, ZenthrixError
9
10
  from .validation import (
10
11
  validate_compile_options,
11
12
  validate_compiled_model_path,
@@ -25,16 +26,19 @@ def build_parser() -> argparse.ArgumentParser:
25
26
  compile_parser.add_argument("--target", default="auto")
26
27
  compile_parser.add_argument("--quantization")
27
28
  compile_parser.add_argument("--output", required=True)
29
+ compile_parser.add_argument("--json", action="store_true")
28
30
 
29
31
  inspect_parser = commands.add_parser("inspect", help="Inspect a compiled model")
30
32
  inspect_parser.add_argument("model")
31
33
  inspect_parser.add_argument("--memory-profile", action="store_true")
34
+ inspect_parser.add_argument("--json", action="store_true")
32
35
 
33
36
  run_parser = commands.add_parser("run", help="Run inference")
34
37
  run_parser.add_argument("--model", required=True)
35
38
  run_parser.add_argument("--prompt", required=True)
36
39
  run_parser.add_argument("--max-tokens", type=int, default=128)
37
40
  run_parser.add_argument("--temperature", type=float, default=0.2)
41
+ run_parser.add_argument("--json", action="store_true")
38
42
  return parser
39
43
 
40
44
 
@@ -48,10 +52,11 @@ def _compile(args: argparse.Namespace) -> int:
48
52
 
49
53
 
50
54
  def _inspect(args: argparse.Namespace) -> int:
51
- model_path = validate_compiled_model_path(args.model)
52
- print(f"Model: {model_path}")
53
- print("Memory profile: unavailable until the native engine is installed")
54
- return 0
55
+ validate_compiled_model_path(args.model)
56
+ raise EngineUnavailableError(
57
+ "The Zenthrix native engine is not installed. "
58
+ "Install the platform runtime before inspecting compiled models."
59
+ )
55
60
 
56
61
 
57
62
  def _run(args: argparse.Namespace) -> int:
@@ -60,7 +65,18 @@ def _run(args: argparse.Namespace) -> int:
60
65
  temperature=args.temperature,
61
66
  max_tokens=args.max_tokens,
62
67
  )
63
- print(result.text)
68
+ if args.json:
69
+ print(
70
+ json.dumps(
71
+ {
72
+ "text": result.text,
73
+ "ttft_ms": result.ttft_ms,
74
+ "tokens_per_second": result.tokens_per_second,
75
+ }
76
+ )
77
+ )
78
+ else:
79
+ print(result.text)
64
80
  return 0
65
81
 
66
82
 
@@ -75,7 +91,17 @@ def main(argv: list[str] | None = None) -> int:
75
91
  if args.command == "run":
76
92
  return _run(args)
77
93
  except (ZenthrixError, ValueError) as error:
78
- print(f"zenthrix: error: {error}", file=sys.stderr)
94
+ if getattr(args, "json", False):
95
+ print(
96
+ json.dumps(
97
+ {
98
+ "error": type(error).__name__,
99
+ "message": str(error),
100
+ }
101
+ )
102
+ )
103
+ else:
104
+ print(f"zenthrix: error: {error}", file=sys.stderr)
79
105
  return 2
80
106
  return 0
81
107
 
@@ -4,7 +4,7 @@ from dataclasses import dataclass
4
4
  from math import isfinite
5
5
  from pathlib import Path
6
6
 
7
- from .exceptions import EngineUnavailableError
7
+ from .runtime import RuntimeAdapter, default_runtime
8
8
  from .validation import validate_compiled_model_path
9
9
 
10
10
 
@@ -25,8 +25,11 @@ class Engine:
25
25
  until that engine is provisioned.
26
26
  """
27
27
 
28
- def __init__(self, model_path: str | Path) -> None:
28
+ def __init__(
29
+ self, model_path: str | Path, *, runtime: RuntimeAdapter | None = None
30
+ ) -> None:
29
31
  self.model_path = validate_compiled_model_path(model_path)
32
+ self._runtime = runtime if runtime is not None else default_runtime()
30
33
 
31
34
  def generate(
32
35
  self,
@@ -42,7 +45,14 @@ class Engine:
42
45
  raise ValueError("temperature must be a finite non-negative number")
43
46
  if max_tokens < 1:
44
47
  raise ValueError("max_tokens must be at least 1")
45
- raise EngineUnavailableError(
46
- "The Zenthrix native engine is not installed. "
47
- "Install the platform runtime before calling Engine.generate()."
48
+ result = self._runtime.generate(
49
+ self.model_path,
50
+ prompt,
51
+ temperature=temperature,
52
+ max_tokens=max_tokens,
53
+ )
54
+ return InferenceResult(
55
+ text=result.text,
56
+ ttft_ms=result.ttft_ms,
57
+ tokens_per_second=result.tokens_per_second,
48
58
  )
@@ -0,0 +1,53 @@
1
+ """Runtime adapter boundary for the separately distributed native engine."""
2
+
3
+ from dataclasses import dataclass
4
+ from pathlib import Path
5
+ from typing import Protocol
6
+
7
+ from .exceptions import EngineUnavailableError
8
+
9
+
10
+ class RuntimeAdapter(Protocol):
11
+ """Operations supplied by an installed native runtime."""
12
+
13
+ def generate(
14
+ self,
15
+ model_path: Path,
16
+ prompt: str,
17
+ *,
18
+ temperature: float,
19
+ max_tokens: int,
20
+ ) -> "RuntimeResult":
21
+ """Generate text for a compiled model."""
22
+
23
+
24
+ @dataclass(frozen=True, slots=True)
25
+ class RuntimeResult:
26
+ """Runtime-neutral inference result."""
27
+
28
+ text: str
29
+ ttft_ms: float
30
+ tokens_per_second: float
31
+
32
+
33
+ class UnavailableRuntime:
34
+ """Runtime implementation used when the native engine is not provisioned."""
35
+
36
+ def generate(
37
+ self,
38
+ model_path: Path,
39
+ prompt: str,
40
+ *,
41
+ temperature: float,
42
+ max_tokens: int,
43
+ ) -> RuntimeResult:
44
+ del model_path, prompt, temperature, max_tokens
45
+ raise EngineUnavailableError(
46
+ "The Zenthrix native engine is not installed. "
47
+ "Install the platform runtime before calling inference."
48
+ )
49
+
50
+
51
+ def default_runtime() -> RuntimeAdapter:
52
+ """Return the provisioned runtime or an explicit unavailable boundary."""
53
+ return UnavailableRuntime()
@@ -1,3 +1,4 @@
1
+ import json
1
2
  from pathlib import Path
2
3
 
3
4
  from zenthrix.cli import build_parser, main
@@ -19,12 +20,34 @@ def test_parser_accepts_compile_options() -> None:
19
20
  assert args.model_format == "onnx"
20
21
 
21
22
 
22
- def test_inspect_reports_existing_model(capsys, tmp_path: Path) -> None:
23
+ def test_inspect_reports_missing_native_engine(capsys, tmp_path: Path) -> None:
23
24
  model = tmp_path / "model.zx"
24
25
  model.write_bytes(b"placeholder")
25
26
 
26
- assert main(["inspect", str(model), "--memory-profile"]) == 0
27
- assert "Memory profile" in capsys.readouterr().out
27
+ assert main(["inspect", str(model), "--memory-profile"]) == 2
28
+ assert "native engine" in capsys.readouterr().err
29
+
30
+
31
+ def test_run_reports_json_error(capsys, tmp_path: Path) -> None:
32
+ model = tmp_path / "model.zx"
33
+ model.write_bytes(b"placeholder")
34
+
35
+ assert (
36
+ main(
37
+ [
38
+ "run",
39
+ "--model",
40
+ str(model),
41
+ "--prompt",
42
+ "hello",
43
+ "--json",
44
+ ]
45
+ )
46
+ == 2
47
+ )
48
+ payload = json.loads(capsys.readouterr().out)
49
+ assert payload["error"] == "EngineUnavailableError"
50
+ assert "native engine" in payload["message"]
28
51
 
29
52
 
30
53
  def test_inspect_rejects_non_compiled_model(capsys, tmp_path: Path) -> None:
@@ -2,6 +2,16 @@ from pathlib import Path
2
2
 
3
3
  import pytest
4
4
  from zenthrix import Engine, EngineUnavailableError
5
+ from zenthrix.runtime import RuntimeResult
6
+
7
+
8
+ class FakeRuntime:
9
+ def generate(self, model_path, prompt, *, temperature, max_tokens):
10
+ assert model_path.name == "model.zx"
11
+ assert prompt == "hello"
12
+ assert temperature == 0.2
13
+ assert max_tokens == 4
14
+ return RuntimeResult("generated", 10.0, 20.0)
5
15
 
6
16
 
7
17
  def test_engine_validates_model_path(tmp_path: Path) -> None:
@@ -18,6 +28,19 @@ def test_engine_reports_missing_runtime(tmp_path: Path) -> None:
18
28
  Engine(model).generate("hello")
19
29
 
20
30
 
31
+ def test_engine_delegates_to_injected_runtime(tmp_path: Path) -> None:
32
+ model = tmp_path / "model.zx"
33
+ model.write_bytes(b"placeholder")
34
+
35
+ result = Engine(model, runtime=FakeRuntime()).generate(
36
+ "hello", max_tokens=4
37
+ )
38
+
39
+ assert result.text == "generated"
40
+ assert result.ttft_ms == 10.0
41
+ assert result.tokens_per_second == 20.0
42
+
43
+
21
44
  def test_engine_rejects_non_finite_temperature(tmp_path: Path) -> None:
22
45
  model = tmp_path / "model.zx"
23
46
  model.write_bytes(b"placeholder")
@@ -33,7 +33,7 @@ def test_validate_model_input_uses_declared_adapter(tmp_path: Path) -> None:
33
33
  def test_validate_model_input_rejects_mismatched_extension(tmp_path: Path) -> None:
34
34
  model = tmp_path / "model.bin"
35
35
  model.write_bytes(b"placeholder")
36
- with pytest.raises(ValueError, match="Expected a .gguf file"):
36
+ with pytest.raises(InputValidationError, match="Expected a .gguf file"):
37
37
  validate_model_input(model, "gguf")
38
38
 
39
39
 
@@ -487,7 +487,7 @@ wheels = [
487
487
 
488
488
  [[package]]
489
489
  name = "zenthrix"
490
- version = "0.1.2"
490
+ version = "0.1.3"
491
491
  source = { editable = "." }
492
492
 
493
493
  [package.dev-dependencies]
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes