mlxsmith 0.1.0__tar.gz

mlxsmith-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mlxsmith-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: mlxsmith
+Version: 0.1.0
+Summary: Apple Silicon MLX fine-tuning and OpenAI-compatible serving (SFT stable; preference/RL experimental).
+Author-email: Shannon Labs <hmbown@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Hmbown/MLXSmith
+Project-URL: Repository, https://github.com/Hmbown/MLXSmith
+Project-URL: Issues, https://github.com/Hmbown/MLXSmith/issues
+Keywords: mlx,apple-silicon,llm,fine-tuning,lora,openai-compatible
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: MacOS :: MacOS X
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pydantic-settings>=2.2.1
+Requires-Dist: tomli>=2.0.1; python_version < "3.11"
+Requires-Dist: huggingface_hub>=1.3.4
+Requires-Dist: jsonschema>=4.21.0
+Provides-Extra: mlx
+Requires-Dist: mlx>=0.30.4; extra == "mlx"
+Provides-Extra: llm
+Requires-Dist: mlx-lm>=0.30.5; extra == "llm"
+Requires-Dist: transformers>=5.0.0; extra == "llm"
+Requires-Dist: datasets>=3.0.0; extra == "llm"
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.128.0; extra == "serve"
+Requires-Dist: uvicorn>=0.40.0; extra == "serve"
+Requires-Dist: httpx>=0.28.0; extra == "serve"
+Provides-Extra: zmlx
+Requires-Dist: zmlx; extra == "zmlx"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0.0; extra == "dev"
+Requires-Dist: ruff>=0.14.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: mlx>=0.30.4; extra == "all"
+Requires-Dist: mlx-lm>=0.30.5; extra == "all"
+Requires-Dist: transformers>=5.0.0; extra == "all"
+Requires-Dist: datasets>=3.0.0; extra == "all"
+Requires-Dist: fastapi>=0.128.0; extra == "all"
+Requires-Dist: uvicorn>=0.40.0; extra == "all"
+Requires-Dist: httpx>=0.28.0; extra == "all"
+Dynamic: license-file
+
+# mlxsmith
+
+Apple Silicon MLX fine-tuning and OpenAI-compatible serving.
+SFT + serving are stable. Preference/RL/RLM features are experimental.
+
+Status: alpha (2026-02-02).
+
+## Stable features
+- Project init, config, data tools, HF auth, model pull/convert.
+- SFT (LoRA/QLoRA) training with run tracking and adapters.
+- Inference and OpenAI-compatible /v1/chat/completions serving.
+- Basic eval/bench and verifier plumbing (regex/jsonschema/pytest).
+
+## Experimental features
+- Preference tuning (DPO/ORPO).
+- GRPO-style RFT.
+- RLM self-play loop (research).
+- Distill/OPD and orchestrated RLM.
+
+## Install
+
+MLX is only available on Apple Silicon. Other platforms can still use data tools
+and mock backends, but MLX training and serving require macOS on Apple Silicon.
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -U pip
+
+# Core CLI
+pip install mlxsmith
+
+# Apple Silicon training + serving
+pip install "mlxsmith[mlx,llm,serve]"
+```
+
+## Quickstart
+
+```bash
+mlxsmith init myproj
+cd myproj
+mlxsmith doctor
+```
+
+## HF auth (optional)
+
+```bash
+mlxsmith auth login --token "$HF_TOKEN"
+mlxsmith auth status
+mlxsmith auth logout
+```
+
+## Pull + convert a model (HF -> MLX)
+
+```bash
+mlxsmith pull Qwen/Qwen3-4B-Instruct-2507
+# outputs to cache/mlx/Qwen__Qwen3-4B-Instruct-2507
+```
+
+Optional quantization:
+
+```bash
+mlxsmith pull Qwen/Qwen3-4B-Instruct-2507 --quantize --q-bits 4
+```
+
+## SFT (LoRA/QLoRA)
+
+```bash
+mlxsmith sft --model cache/mlx/Qwen__Qwen3-4B-Instruct-2507 --data data/sft
+```
+
+## Serve (OpenAI-compatible)
+
+```bash
+mlxsmith serve --model runs/sft_0001/adapter --port 8080
+```
+
+Sample request:
+
+```bash
+curl http://localhost:8080/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{"messages":[{"role":"user","content":"Hello"}],"max_tokens":64}'
+```
+
+To enable the optional UI/monitor dashboard, set `serve.ui: true` in `mlxsmith.yaml`.
+
+## Experimental commands
+
+- `mlxsmith pref` (DPO/ORPO)
+- `mlxsmith rft` (GRPO-style)
+- `mlxsmith rlm` / `mlxsmith pipeline` (self-play loop)
+- `mlxsmith distill` (offline/OPD)
+- `mlxsmith eval` / `mlxsmith bench`
+
+## Docs
+
+- `docs/PROJECT_FORMAT.md` for project layout and artifacts.
+- `docs/VERIFIERS.md` for verifier API and sandbox behavior.
+- `docs/COMPATIBILITY.md` for tested versions and model families.
+- `docs/ENVIRONMENTS.md` for the environment plugin system.
+- `docs/ROADMAP.md` for product direction and milestones.
+- `docs/README.md` for the full docs index.
+
+## License
+
+MIT

mlxsmith-0.1.0/README.md

@@ -0,0 +1,106 @@
+# mlxsmith
+
+Apple Silicon MLX fine-tuning and OpenAI-compatible serving.
+SFT + serving are stable. Preference/RL/RLM features are experimental.
+
+Status: alpha (2026-02-02).
+
+## Stable features
+- Project init, config, data tools, HF auth, model pull/convert.
+- SFT (LoRA/QLoRA) training with run tracking and adapters.
+- Inference and OpenAI-compatible /v1/chat/completions serving.
+- Basic eval/bench and verifier plumbing (regex/jsonschema/pytest).
+
+## Experimental features
+- Preference tuning (DPO/ORPO).
+- GRPO-style RFT.
+- RLM self-play loop (research).
+- Distill/OPD and orchestrated RLM.
+
+## Install
+
+MLX is only available on Apple Silicon. Other platforms can still use data tools
+and mock backends, but MLX training and serving require macOS on Apple Silicon.
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -U pip
+
+# Core CLI
+pip install mlxsmith
+
+# Apple Silicon training + serving
+pip install "mlxsmith[mlx,llm,serve]"
+```
+
+## Quickstart
+
+```bash
+mlxsmith init myproj
+cd myproj
+mlxsmith doctor
+```
+
+## HF auth (optional)
+
+```bash
+mlxsmith auth login --token "$HF_TOKEN"
+mlxsmith auth status
+mlxsmith auth logout
+```
+
+## Pull + convert a model (HF -> MLX)
+
+```bash
+mlxsmith pull Qwen/Qwen3-4B-Instruct-2507
+# outputs to cache/mlx/Qwen__Qwen3-4B-Instruct-2507
+```
+
+Optional quantization:
+
+```bash
+mlxsmith pull Qwen/Qwen3-4B-Instruct-2507 --quantize --q-bits 4
+```
+
+## SFT (LoRA/QLoRA)
+
+```bash
+mlxsmith sft --model cache/mlx/Qwen__Qwen3-4B-Instruct-2507 --data data/sft
+```
+
+## Serve (OpenAI-compatible)
+
+```bash
+mlxsmith serve --model runs/sft_0001/adapter --port 8080
+```
+
+Sample request:
+
+```bash
+curl http://localhost:8080/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{"messages":[{"role":"user","content":"Hello"}],"max_tokens":64}'
+```
+
+To enable the optional UI/monitor dashboard, set `serve.ui: true` in `mlxsmith.yaml`.
+
+## Experimental commands
+
+- `mlxsmith pref` (DPO/ORPO)
+- `mlxsmith rft` (GRPO-style)
+- `mlxsmith rlm` / `mlxsmith pipeline` (self-play loop)
+- `mlxsmith distill` (offline/OPD)
+- `mlxsmith eval` / `mlxsmith bench`
+
+## Docs
+
+- `docs/PROJECT_FORMAT.md` for project layout and artifacts.
+- `docs/VERIFIERS.md` for verifier API and sandbox behavior.
+- `docs/COMPATIBILITY.md` for tested versions and model families.
+- `docs/ENVIRONMENTS.md` for the environment plugin system.
+- `docs/ROADMAP.md` for product direction and milestones.
+- `docs/README.md` for the full docs index.
+
+## License
+
+MIT

mlxsmith-0.1.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mlxsmith"
+version = "0.1.0"
+description = "Apple Silicon MLX fine-tuning and OpenAI-compatible serving (SFT stable; preference/RL experimental)."
+readme = {file = "README.md", content-type = "text/markdown"}
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name="Shannon Labs", email="hmbown@gmail.com"}]
+keywords = ["mlx", "apple-silicon", "llm", "fine-tuning", "lora", "openai-compatible"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: MacOS :: MacOS X",
+]
+dependencies = [
+  "typer>=0.9.0",
+  "rich>=13.7.0",
+  "pyyaml>=6.0.1",
+  "pydantic>=2.5.0",
+  "pydantic-settings>=2.2.1",
+  "tomli>=2.0.1; python_version < '3.11'",
+  "huggingface_hub>=1.3.4",
+  "jsonschema>=4.21.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Hmbown/MLXSmith"
+Repository = "https://github.com/Hmbown/MLXSmith"
+Issues = "https://github.com/Hmbown/MLXSmith/issues"
+
+[project.optional-dependencies]
+mlx = ["mlx>=0.30.4"]
+llm = [
+  "mlx-lm>=0.30.5",
+  "transformers>=5.0.0",
+  "datasets>=3.0.0",
+]
+serve = [
+  "fastapi>=0.128.0",
+  "uvicorn>=0.40.0",
+  "httpx>=0.28.0",
+]
+zmlx = ["zmlx"]
+dev = ["pytest>=9.0.0", "ruff>=0.14.0"]
+all = [
+  "mlx>=0.30.4",
+  "mlx-lm>=0.30.5",
+  "transformers>=5.0.0",
+  "datasets>=3.0.0",
+  "fastapi>=0.128.0",
+  "uvicorn>=0.40.0",
+  "httpx>=0.28.0",
+]
+
+[project.scripts]
+mlxsmith = "mlxsmith.cli:app"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+license-files = ["LICENSE"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

mlxsmith-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mlxsmith-0.1.0/src/mlxsmith/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ['__version__']
+__version__ = '0.1.0'

mlxsmith-0.1.0/src/mlxsmith/accel/__init__.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+from .none import NoneBackend
+from .zmlx_backend import ZMLXBackend
+
+def get_backend(name: str):
+    if name == "none":
+        return NoneBackend()
+    if name == "zmlx":
+        return ZMLXBackend()
+    raise ValueError(f"Unknown accel backend: {name}")

mlxsmith-0.1.0/src/mlxsmith/accel/base.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Protocol
+
+@dataclass
+class AccelStats:
+    backend: str
+    compiled: int = 0
+    cache_hits: int = 0
+    notes: Dict[str, Any] | None = None
+
+class AccelBackend(Protocol):
+    name: str
+    def patch(self) -> None: ...
+    def warmup(self, model: Any, example_batch: Any) -> Dict[str, Any]: ...
+    def stats(self) -> AccelStats: ...

mlxsmith-0.1.0/src/mlxsmith/accel/none.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+from .base import AccelStats
+
+class NoneBackend:
+    name = "none"
+    def patch(self) -> None:
+        return
+    def warmup(self, model: Any, example_batch: Any) -> Dict[str, Any]:
+        return {"warmup": "skipped"}
+    def stats(self) -> AccelStats:
+        return AccelStats(backend="none")

mlxsmith-0.1.0/src/mlxsmith/accel/zmlx_backend.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any, Dict
+from .base import AccelStats
+
+class ZMLXBackend:
+    name = "zmlx"
+
+    def __init__(self):
+        self._available = False
+        self._notes = {}
+        try:
+            import zmlx  # type: ignore
+            self._available = True
+            self._notes["zmlx_version"] = getattr(zmlx, "__version__", None)
+        except Exception as e:
+            self._available = False
+            self._notes["error"] = f"{type(e).__name__}: {e}"
+
+    def patch(self) -> None:
+        if not self._available:
+            # soft fail; caller should report status
+            return
+        # ZMLX can patch ops/modules. We keep this intentionally minimal and safe.
+        try:
+            import zmlx  # type: ignore
+            # If ZMLX provides a global patch hook, call it; otherwise, no-op.
+            patch_fn = getattr(zmlx, "patch", None)
+            if callable(patch_fn):
+                patch_fn()
+                self._notes["patched"] = True
+            else:
+                self._notes["patched"] = False
+                self._notes["hint"] = "No zmlx.patch() found; implement patch hook or integrate per-module."
+        except Exception as e:
+            self._notes["patched_error"] = f"{type(e).__name__}: {e}"
+
+    def warmup(self, model: Any, example_batch: Any) -> Dict[str, Any]:
+        return {"warmup": "not_implemented", "notes": self._notes}
+
+    def stats(self) -> AccelStats:
+        return AccelStats(backend="zmlx", notes=self._notes)

mlxsmith-0.1.0/src/mlxsmith/adapters.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Iterable, Optional
+
+from .util import ensure_dir, copytree, now_ts
+
+
+def merge_adapters(
+    base_model: str,
+    adapters: Iterable[Path],
+    out_dir: Path,
+    *,
+    weights: Optional[list[float]] = None,
+) -> Path:
+    adapter_list = [Path(a) for a in adapters]
+    if not adapter_list:
+        raise RuntimeError("No adapters provided")
+    ensure_dir(out_dir)
+
+    try:
+        from mlx_lm.tuner import utils as tuner_utils  # type: ignore
+
+        if hasattr(tuner_utils, "merge_adapters"):
+            tuner_utils.merge_adapters(
+                base_model,
+                [str(p) for p in adapter_list],
+                str(out_dir),
+                weights=weights,
+            )
+            return out_dir
+    except Exception:
+        pass
+
+    # Fallback: copy the first adapter and record metadata.
+    copytree(adapter_list[0], out_dir)
+    meta = {
+        "base_model": base_model,
+        "merged_from": [str(p) for p in adapter_list],
+        "weights": weights,
+        "merged_at": now_ts(),
+        "note": "merge_adapters fallback: copied first adapter (mlx_lm merge unavailable)",
+    }
+    (out_dir / "adapter_merge.json").write_text(json.dumps(meta, indent=2), encoding="utf-8")
+    return out_dir

mlxsmith-0.1.0/src/mlxsmith/api/__init__.py

@@ -0,0 +1,48 @@
+"""MLXSmith API handlers and schemas."""
+
+from .schemas import (
+    ChatMessage,
+    ChatRequest,
+    ChatResponse,
+    ChatCompletionChunk,
+    RolloutRequest,
+    RolloutResponse,
+    AdapterReloadRequest,
+    AdapterReloadResponse,
+    RLMState,
+    RLMHistoryEntry,
+    ModelInfo,
+    ModelsListResponse,
+    ModelPullRequest,
+    ModelPullResponse,
+    HFTokenRequest,
+    HFTokenResponse,
+    HealthResponse,
+    ErrorResponse,
+)
+from .handlers import create_router, InternalAuthMiddleware
+
+__all__ = [
+    # Schemas
+    "ChatMessage",
+    "ChatRequest",
+    "ChatResponse",
+    "ChatCompletionChunk",
+    "RolloutRequest",
+    "RolloutResponse",
+    "AdapterReloadRequest",
+    "AdapterReloadResponse",
+    "RLMState",
+    "RLMHistoryEntry",
+    "ModelInfo",
+    "ModelsListResponse",
+    "ModelPullRequest",
+    "ModelPullResponse",
+    "HFTokenRequest",
+    "HFTokenResponse",
+    "HealthResponse",
+    "ErrorResponse",
+    # Handlers
+    "create_router",
+    "InternalAuthMiddleware",
+]