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
