diff --git a/CHANGELOG.md b/CHANGELOG.md index 0bb5081..56ae9d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,55 @@ # Changelog +## 2.0.0 — 2025-11-06 + +**Stable Release**: MLX Knife 2.0 replaces 1.x as the primary version. Full feature parity with 1.1.1 achieved plus major enhancements. + +### License Change + +- **MIT → Apache License 2.0**: Better patent protection, industry-standard licensing +- See [MIGRATION.md](MIGRATION.md) for details on license change and user impact + +### Highlights + +- **Full 1.x Feature Parity**: All commands from 1.1.1 available (`list`, `show`, `pull`, `rm`, `run`, `server`, `health`) +- **JSON API**: Machine-readable output for automation (`--json` flag on all commands) +- **Enhanced Error Handling**: Structured errors with request IDs, logging levels, JSON logs +- **Runtime Compatibility Checks**: Pre-flight validation prevents loading incompatible models +- **Improved Stop Token Detection**: Multi-EOS support (MXFP4, Qwen, Llama) +- **Better Human Output**: Improved formatting, relative timestamps, runtime status + +### Package Changes + +- **Package name**: `mlx-knife` (unchanged from 1.x) +- **Primary command**: `mlxk` (replaces `mlxk2` from beta) +- **Aliases**: `mlxk-json`, `mlxk2` (backwards compatibility) + +### Breaking Changes + +- **Lock file handling**: `mlxk rm` requires `--force` flag when models have active locks (safety improvement) +- See [MIGRATION.md](MIGRATION.md) for complete migration guide from 1.x + +### Installation + +```bash +# PyPI (recommended) +pip install mlx-knife + +# GitHub release +pip install https://github.com/mzau/mlx-knife/releases/download/v2.0.0/mlx_knife-2.0.0-py3-none-any.whl + +# Upgrade from 1.x +pip install --upgrade mlx-knife +``` + +### Testing + +- 297 passed, 20 skipped (317 total tests) +- Python 3.9-3.13 compatibility verified +- Apple Silicon (M1/M2) tested + +--- + ## 2.0.0-beta.6 — 2025-10-22 ### Fixed diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f985b2..3889865 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,19 +6,17 @@ First off, thank you for considering contributing to MLX Knife! It's people like We're a small team passionate about making MLX models accessible and easy to use on Apple Silicon. We welcome contributions from everyone who shares this vision. -## 2.0 Alpha (JSON CLI) – Contributor Notes +## 2.0 Stable – Contributor Notes -- Code path: `mlxk2/` (entry points: `mlxk2`, `mlxk-json`). -- Default output: human-friendly tables/text; pass `--json` to emit the exact JSON API (spec v0.1.2). -- Supported commands: `list`, `health`, `show`, `pull`, `rm` (no server/run in 2.0 yet — use `mlxk` 1.x for those). -- Tests: default suite is `tests_2.0/` (see `pytest.ini`); legacy `tests/` on demand. -- Human output options: - - `list`: `--all` (all frameworks), `--health` (add column), `--verbose` (full org/model names). - - Compact default: MLX-only, compact names (strip `mlx-community/`), no Framework column. -- Cache safety: tests use isolated temp caches; read-only ops are safe; coordinate `pull`/`rm` when using a shared user cache. -- Spec discipline: JSON schema/spec changes require a version bump in `mlxk2/spec.py` (see CLAUDE.md and docs/). - -These 2.0 alpha changes do not affect 1.x (`mlx_knife/`) behavior. +- **Code path:** `mlxk2/` (entry points: `mlxk`, `mlxk-json`, `mlxk2`) +- **Default output:** Human-friendly tables/text; pass `--json` for machine-readable JSON API +- **Full feature parity:** All commands available (`list`, `health`, `show`, `pull`, `rm`, `run`, `serve`) +- **Tests:** Primary suite is `tests_2.0/` (see `pytest.ini`) +- **Human output options:** + - `list`: `--all` (all frameworks), `--health` (add column), `--verbose` (full org/model names) + - Compact default: MLX-only, compact names (strip `mlx-community/`), no Framework column +- **Cache safety:** Tests use isolated temp caches; read-only ops are safe; coordinate `pull`/`rm` when using a shared user cache +- **Spec discipline:** JSON schema/spec changes require a version bump in `mlxk2/spec.py` (see docs/) ## How Can I Contribute? @@ -241,10 +239,19 @@ Feel free to open an issue with the "question" label or start a discussion. We'r ## License -- For 2.x (`mlxk2`, this branch): By contributing, you agree that your contributions will be licensed under the Apache License, Version 2.0. -- For 1.x (`main`): By contributing, you agree that your contributions will be licensed under the MIT License. +**Important:** MLX Knife 2.0+ is licensed under the **Apache License, Version 2.0**. -Please ensure you have the right to contribute the code under these terms. We recommend including a Developer Certificate of Origin (DCO) “Signed-off-by” line in commits. +By contributing to MLX Knife, you agree that: +1. Your contributions will be licensed under the Apache License, Version 2.0 +2. You have the right to contribute the code under these terms +3. You grant the project maintainers a perpetual, worldwide, non-exclusive, royalty-free license to use, reproduce, modify, and distribute your contributions + +**Legacy 1.x versions** (MIT License) are maintained in the `1.x-legacy` branch for reference only. All new contributions go to the main branch (Apache 2.0). + +We recommend including a Developer Certificate of Origin (DCO) "Signed-off-by" line in your commits: +```bash +git commit -s -m "Your commit message" +``` --- diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..d2dd28d --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,285 @@ +# Migration Guide: MLX Knife 1.x → 2.0 + +This guide helps you transition from MLX Knife 1.x (MIT License) to 2.0 (Apache License 2.0). + +## License Change: MIT → Apache 2.0 + +**Important:** MLX Knife 2.0 changes the license from MIT to Apache License 2.0. + +### What This Means for Users + +**Practical Impact:** +- ✅ Still **free and open source** +- ✅ Still **commercial use allowed** +- ✅ Still **modification allowed** +- ⚠️ **Attribution required** (include NOTICE file in distributions) +- ⚠️ **Patent grant** (explicit patent protection for users) + +**Key Differences:** +| Aspect | MIT (1.x) | Apache 2.0 (2.0+) | +|--------|-----------|-------------------| +| Use | ✅ Free | ✅ Free | +| Modify | ✅ Allowed | ✅ Allowed | +| Commercial | ✅ Allowed | ✅ Allowed | +| Attribution | Optional | **Required** (NOTICE file) | +| Patent Grant | Implicit | **Explicit** (better protection) | + +### Why Apache 2.0? + +1. **Better Patent Protection:** Explicit patent grant protects users from patent litigation +2. **Industry Standard:** Used by major projects (Kubernetes, TensorFlow, Apache projects) +3. **Clear Contribution Terms:** Explicit contributor licensing for future contributions + +### For Users: What You Need to Do + +**If you just use MLX Knife CLI:** +- ✅ Nothing! Just upgrade: `pip install --upgrade mlx-knife` +- The license change doesn't affect CLI usage + +**If you distribute MLX Knife in your product:** +- ⚠️ Include the `LICENSE` file from the mlx-knife package +- ⚠️ Include the `mlxk2/NOTICE` file in your distribution +- Example: If bundling mlx-knife in a Mac app, include both files in your "Licenses" folder + +**If you're a 1.x user and prefer MIT:** +- 🔒 Version 1.1.1 remains available under MIT License +- Install specific version: `pip install mlx-knife==1.1.1` +- Security updates will focus on 2.x (Apache 2.0) + +## Behavior Changes + +### `rm` Command: Lock File Handling + +The `rm` command now handles HuggingFace lock files more safely: + +**1.x Behavior:** +```bash +$ mlxk rm Phi-3-mini +Delete entire model mlx-community/Phi-3-mini-4k-instruct-4bit? [y/N] y +Model mlx-community/Phi-3-mini-4k-instruct-4bit completely deleted. +Clean up cache files? [Y/n] y +Cache files cleaned up (3 files). +``` + +**2.0 Behavior:** +```bash +# Models with active locks require --force +$ mlxk rm Phi-3-mini +Error: Model has active locks. Use --force to override. + +# With --force, deletion + lock cleanup happen automatically +$ mlxk rm Phi-3-mini --force +rm: mlx-community/Phi-3-mini-4k-instruct-4bit — deleted: Deleted entire model mlx-community/Phi-3-mini-4k-instruct-4bit +``` + +**Why the change?** +- **Safety:** Prevents accidental deletion of models that may be in use +- **Simplicity:** One confirmation instead of two separate prompts +- **Clarity:** Explicit `--force` makes automation intent clear +- **Automatic cleanup:** Lock files are cleaned silently (no separate prompt) + +**Note:** Lock file cleanup count is available in `--json` output (`lock_files_cleaned` field). + +**Migration for scripts:** +- Interactive usage: No change needed (you'll get a clear error message if locks exist) +- Automation: Add `--force` if your scripts delete models programmatically + +## New Features in 2.0 + +### 1. JSON API for Automation + +All commands now support `--json` for machine-readable output: + +```bash +mlxk list --json +mlxk show Phi-3-mini --json +mlxk rm Phi-3-mini --force --json +``` + +**Example:** +```bash +# Extract model names for scripting +mlxk list --json | jq -r '.data.models[] | .name' + +# Check lock cleanup count +mlxk rm test-model --force --json | jq '.data.lock_files_cleaned' +``` + +### 2. Enhanced Error Handling & Logging + +- **Structured errors** with request IDs for debugging +- **Log levels:** `--log-level debug|info|warning|error` +- **JSON logs:** `--log-json` or `MLXK2_LOG_JSON=1` +- **Auto-redaction:** HF tokens and user paths automatically hidden + +```bash +# Debug mode +mlxk run Phi-3-mini "test" --log-level debug + +# JSON logs for production +mlxk server --log-json --log-level info +``` + +### 3. Runtime Compatibility Checks + +Pre-flight validation catches issues before model loading: + +```bash +$ mlxk show Phi-3-mini +Model: Phi-3-mini-4k-instruct-4bit +Health: healthy +Runtime: compatible + +$ mlxk show legacy-model +Model: legacy-model +Health: healthy (files OK) +Runtime: incompatible +Reason: Legacy format not supported by mlx-lm +``` + +### 4. Better Stop Token Detection + +Fixed issues with multi-EOS models: +- No more visible stop tokens (`<|end|>`) +- No more "self-conversation" (model continuing after response) +- Works with MXFP4, Qwen, Llama models + +### 5. Improved Human Output Formatting + +- Shorter model names (strip `mlx-community/` prefix by default) +- Relative timestamps ("2 days ago") +- Better alignment and readability +- Use `--verbose` for full names and details + +## Command Compatibility + +| Command | 1.x | 2.0 | Notes | +|---------|-----|-----|-------| +| `mlxk list` | ✅ | ✅ | Improved formatting, add `--verbose` for full names | +| `mlxk show ` | ✅ | ✅ | Added `runtime_compatible` field | +| `mlxk pull ` | ✅ | ✅ | Better error messages | +| `mlxk rm ` | ✅ | ⚠️ | Lock files require `--force` (safer) | +| `mlxk run ` | ✅ | ✅ | Better stop token handling | +| `mlxk server` | ✅ | ✅ | Added `--log-level`, `--log-json` | +| `mlxk health` | ✅ | ✅ | Added runtime compatibility checks | + +## Package & Command Names + +- **PyPI Package:** `mlx-knife` (unchanged) +- **Primary Command:** `mlxk` (unchanged) +- **Aliases:** `mlxk-json`, `mlxk2` (for backwards compatibility) + +```bash +# All three commands are identical +mlxk --version # → 2.0.0 +mlxk-json --version # → 2.0.0 +mlxk2 --version # → 2.0.0 +``` + +## Installation & Upgrade + +### Upgrade from 1.x + +```bash +# Simple upgrade +pip install --upgrade mlx-knife + +# Verify version +mlxk --version # Should show: mlxk 2.0.0 +``` + +### Fresh Installation + +```bash +# Install from PyPI +pip install mlx-knife + +# Or from GitHub release +pip install https://github.com/mzau/mlx-knife/releases/download/v2.0.0/mlx_knife-2.0.0-py3-none-any.whl +``` + +### Staying on 1.x (MIT License) + +```bash +# Pin to 1.x version +pip install mlx-knife==1.1.1 + +# Or in requirements.txt +mlx-knife==1.1.1 +``` + +## Data & Cache Compatibility + +✅ **Your model cache is 100% compatible** + +- Same HuggingFace cache: `~/.cache/huggingface/hub` +- All 1.x models work in 2.0 immediately +- No re-download required +- No migration needed + +## Testing Before Upgrade + +```bash +# Test 2.0 in a virtual environment +python3 -m venv test-mlxk2 +source test-mlxk2/bin/activate +pip install mlx-knife + +# Verify your workflow +mlxk list +mlxk run YourFavoriteModel "test prompt" +mlxk rm test-model --force # Note: --force for locks + +# If satisfied, upgrade +deactivate +pip install --upgrade mlx-knife +``` + +## Upgrade Checklist for Automation Scripts + +If you have scripts using mlxk: + +- [ ] **Add `--force` to `mlxk rm` commands** (if deleting programmatically) +- [ ] **Replace output parsing with `--json`** (don't parse human output) +- [ ] **Test in virtual environment first** +- [ ] **Update error handling** for structured error responses +- [ ] **Consider `--log-json`** for production logging + +## FAQ + +**Q: Will my 1.x scripts break?** +A: Only `mlxk rm` scripts that delete models with active locks without `--force`. This is a safety improvement. + +**Q: Why does `rm` need `--force` for locks?** +A: To prevent accidental deletion of models that may be in use. Locks indicate active downloads or usage. + +**Q: Can I still use interactive deletion?** +A: Yes! Without `--force`, you'll get clear error messages about locks and can decide whether to use `--force`. + +**Q: Do I need to re-download models?** +A: No! All cached models from 1.x work immediately. + +**Q: What about the web chat interface?** +A: `simple_chat.html` works with both 1.x and 2.0 (OpenAI API unchanged). + +**Q: Can I contribute to 1.x?** +A: 1.x is in maintenance mode. New contributions go to 2.x (Apache 2.0). + +**Q: Where's the 1.x source code?** +A: The `1.x-legacy` branch contains the final MIT version (1.1.1). + +## Need Help? + +- **Issues:** https://github.com/mzau/mlx-knife/issues +- **Discussions:** https://github.com/mzau/mlx-knife/discussions +- **Documentation:** https://github.com/mzau/mlx-knife + +## Timeline + +- **1.1.1 (MIT):** Final 1.x release - September 2025 +- **2.0.0 (Apache 2.0):** Stable release - November 2025 +- **1.x Support:** Security fixes only + +--- + +**The BROKE Team** 🦫 diff --git a/README.md b/README.md index 18ecdc8..9c36073 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ -# BROKE Logo MLX-Knife 2.0.0-beta.6 +# BROKE Logo MLX-Knife 2.0

- MLX Knife Demo + MLX Knife Demo

-**Stable Version: 1.1.1** +**Current Stable Version: 2.0.0** -[![GitHub Release](https://img.shields.io/badge/version-2.0.0--beta.6-orange.svg)](https://github.com/mzau/mlx-knife/releases) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![GitHub Release](https://img.shields.io/badge/version-2.0.0-green.svg)](https://github.com/mzau/mlx-knife/releases) +[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) -[![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-M1%2FM2%2FM3-green.svg)](https://support.apple.com/en-us/HT211814) +[![Apple Silicon](https://img.shields.io/badge/Apple%20Silicon-green.svg)](https://support.apple.com/en-us/HT211814) [![MLX](https://img.shields.io/badge/MLX-Latest-orange.svg)](https://github.com/ml-explore/mlx) @@ -25,7 +25,7 @@ - **Privacy & Network**: No background network or telemetry; only explicit Hugging Face interactions when you run pull or the experimental push. ### Requirements -- macOS with Apple Silicon (M1/M2/M3) +- macOS with Apple Silicon - Python 3.9+ (native macOS version or newer) - 8GB+ RAM recommended + RAM to run LLM @@ -39,14 +39,24 @@ MLX Knife has been comprehensively tested and verified on: ## Installation -### Beta Release Installation (Recommended) +### Via PyPI (Recommended) ```bash -# Install latest beta release directly from GitHub -pip install https://github.com/mzau/mlx-knife/releases/download/v2.0.0-beta.6/mlxk_json-2.0.0b6-py3-none-any.whl +# Install stable release from PyPI +pip install mlx-knife # Verify installation -mlxk2 --version # → mlxk2 2.0.0b6 +mlxk --version # → mlxk 2.0.0 +``` + +### Via GitHub Release + +```bash +# Install latest release from GitHub +pip install https://github.com/mzau/mlx-knife/releases/download/v2.0.0/mlx_knife-2.0.0-py3-none-any.whl + +# Verify installation +mlxk --version # → mlxk 2.0.0 ``` ### Development Installation @@ -55,13 +65,12 @@ mlxk2 --version # → mlxk2 2.0.0b6 # Clone and install from source git clone https://github.com/mzau/mlx-knife.git cd mlx-knife -git checkout feature/2.0.0-alpha.1 # Install with all development dependencies (required for testing and code quality) pip install -e ".[dev,test]" # Verify installation -mlxk2 --version # → mlxk2 2.0.0-beta.6 +mlxk --version # → mlxk 2.0.0 # Run tests and quality checks (before committing) pytest -v @@ -71,29 +80,33 @@ mypy mlxk2/ **Note:** For minimal user installation without dev tools: `pip install -e .` +### Migrating from 1.x + +If you're upgrading from MLX Knife 1.x, see [MIGRATION.md](MIGRATION.md) for important information about the license change (MIT → Apache 2.0) and behavior changes. + ## Quick Start ```bash # List models (human-readable) -mlxk2 list -mlxk2 list --health -mlxk2 list --verbose --health +mlxk list +mlxk list --health +mlxk list --verbose --health # Check cache health -mlxk2 health +mlxk health # Show model details -mlxk2 show "mlx-community/Phi-3-mini-4k-instruct-4bit" +mlxk show "mlx-community/Phi-3-mini-4k-instruct-4bit" # Pull a model -mlxk2 pull "mlx-community/Llama-3.2-3B-Instruct-4bit" +mlxk pull "mlx-community/Llama-3.2-3B-Instruct-4bit" # Run interactive chat -mlxk2 run "Phi-3-mini" -c +mlxk run "Phi-3-mini" -c # Start OpenAI-compatible server -mlxk2 serve --port 8080 +mlxk serve --port 8080 ``` @@ -124,9 +137,9 @@ All commands support both human-readable and JSON output (`--json` flag) for aut All commands support JSON output via `--json` flag: ```bash -mlxk2 list --json | jq '.data.models[].name' -mlxk2 health --json | jq '.data.summary' -mlxk2 show "Phi-3-mini" --json | jq '.data.model' +mlxk list --json | jq '.data.models[].name' +mlxk health --json | jq '.data.summary' +mlxk show "Phi-3-mini" --json | jq '.data.model' ``` **Response Format:** @@ -143,7 +156,7 @@ mlxk2 show "Phi-3-mini" --json | jq '.data.model' #### List Models ```bash -mlxk2 list --json +mlxk list --json # Output: { "status": "success", @@ -172,7 +185,7 @@ mlxk2 list --json #### Health Check ```bash -mlxk2 health --json +mlxk health --json # Output: { "status": "success", @@ -194,7 +207,7 @@ mlxk2 health --json #### Show Model Details ```bash -mlxk2 show "Phi-3-mini" --json --files +mlxk show "Phi-3-mini" --json --files # Output (simplified): { "status": "success", @@ -228,9 +241,9 @@ mlxk2 show "Phi-3-mini" --json --files All commands support `@hash` syntax for specific model versions: ```bash -mlxk2 health "Qwen3@e96" --json # Check specific hash -mlxk2 show "model@3df9bfd" --json # Short hash matching -mlxk2 rm "Phi-3@e967" --json --force # Delete specific version +mlxk health "Qwen3@e96" --json # Check specific hash +mlxk show "model@3df9bfd" --json # Short hash matching +mlxk rm "Phi-3@e967" --json --force # Delete specific version ``` ### Integration Examples @@ -238,39 +251,39 @@ mlxk2 rm "Phi-3@e967" --json --force # Delete specific version #### Broke-Cluster Integration ```bash # Get available model names for scheduling -MODELS=$(mlxk2 list --json | jq -r '.data.models[].name') +MODELS=$(mlxk list --json | jq -r '.data.models[].name') # Check cache health before deployment -HEALTH=$(mlxk2 health --json | jq '.data.summary.healthy_count') +HEALTH=$(mlxk health --json | jq '.data.summary.healthy_count') if [ "$HEALTH" -eq 0 ]; then echo "No healthy models available" exit 1 fi # Download required models -mlxk2 pull "mlx-community/Phi-3-mini-4k-instruct-4bit" --json +mlxk pull "mlx-community/Phi-3-mini-4k-instruct-4bit" --json ``` #### CI/CD Pipeline Usage ```bash # Verify model integrity in CI -mlxk2 health --json | jq -e '.data.summary.unhealthy_count == 0' +mlxk health --json | jq -e '.data.summary.unhealthy_count == 0' # Clean up CI artifacts -mlxk2 rm "test-model-*" --json --force +mlxk rm "test-model-*" --json --force # Pre-warm cache for deployment -mlxk2 pull "production-model" --json +mlxk pull "production-model" --json ``` #### Model Management Automation ```bash # Find models by pattern -LARGE_MODELS=$(mlxk2 list --json | jq -r '.data.models[] | select(.name | contains("30B")) | .name') +LARGE_MODELS=$(mlxk list --json | jq -r '.data.models[] | select(.name | contains("30B")) | .name') # Show detailed info for analysis for model in $LARGE_MODELS; do - mlxk2 show "$model" --json --config | jq '.data.model_config' + mlxk show "$model" --json --config | jq '.data.model_config' done ``` @@ -282,10 +295,10 @@ MLX Knife provides rich human-readable output by default (without `--json` flag) ### Basic Usage ```bash -mlxk2 list -mlxk2 list --health -mlxk2 health -mlxk2 show "mlx-community/Phi-3-mini-4k-instruct-4bit" +mlxk list +mlxk list --health +mlxk health +mlxk show "mlx-community/Phi-3-mini-4k-instruct-4bit" ``` ### List Filters @@ -315,21 +328,21 @@ The `--health` flag adds health status information to the output: ```bash # Compact health view -mlxk2 list --health +mlxk list --health # Output: # Name | Hash | Size | Modified | Type | Health # Llama-3.2-3B-Instruct | a1b2c3d | 2.1GB | 2d ago | chat | healthy # Qwen2-7B-Instruct | 1a2b3c4 | 4.8GB | 3d ago | chat | healthy* # Verbose health view with details -mlxk2 list --verbose --health +mlxk list --verbose --health # Output: # Name | Hash | Size | Modified | Framework | Type | Integrity | Runtime | Reason # Llama-3.2-3B-Instruct | a1b2c3d | 2.1GB | 2d ago | MLX | chat | healthy | yes | - # Qwen2-7B-Instruct | 1a2b3c4 | 4.8GB | 3d ago | PyTorch | chat | healthy | no | Incompatible: PyTorch # All frameworks with health status -mlxk2 list --all --health +mlxk list --all --health # Output: # Name | Hash | Size | Modified | Framework | Type | Health # Llama-3.2-3B-Instruct | a1b2c3d | 2.1GB | 2d ago | MLX | chat | healthy @@ -355,16 +368,16 @@ Control verbosity with `--log-level` (server mode): ```bash # Default: Show startup, model loading, and errors -mlxk2 serve --log-level info +mlxk serve --log-level info # Quiet: Only warnings and errors -mlxk2 serve --log-level warning +mlxk serve --log-level warning # Silent: Only errors -mlxk2 serve --log-level error +mlxk serve --log-level error # Verbose: All logs including HTTP requests -mlxk2 serve --log-level debug +mlxk serve --log-level debug ``` **Log Level Behavior:** @@ -379,10 +392,10 @@ Enable structured JSON output for log aggregation tools: ```bash # JSON logs (recommended - CLI flag) -mlxk2 serve --log-json +mlxk serve --log-json # JSON logs (alternative - environment variable) -MLXK2_LOG_JSON=1 mlxk2 serve +MLXK2_LOG_JSON=1 mlxk serve ``` **Note:** `--log-json` also formats Uvicorn access logs as JSON for consistent output. @@ -435,14 +448,14 @@ MLX-Knife 2.0 respects standard HuggingFace cache structure and practices: ### Example Safe Workflow ```bash # Check what's in cache (always safe) -mlxk2 list --json | jq '.data.count' +mlxk list --json | jq '.data.count' # Maintenance window - coordinate with team -mlxk2 rm "corrupted-model" --json --force -mlxk2 pull "replacement-model" --json +mlxk rm "corrupted-model" --json --force +mlxk pull "replacement-model" --json # Back to normal operations -mlxk2 health --json | jq '.data.summary' +mlxk health --json | jq '.data.summary' ``` @@ -450,7 +463,7 @@ mlxk2 health --json | jq '.data.summary' ### `clone` - Model Workspace Creation -`mlxk2 clone` is a hidden alpha feature. Enable with `MLXK2_ENABLE_ALPHA_FEATURES=1`. It creates a local workspace from a cached model for modification and development. +`mlxk clone` is a hidden alpha feature. Enable with `MLXK2_ENABLE_ALPHA_FEATURES=1`. It creates a local workspace from a cached model for modification and development. - Creates isolated workspace from cached models - Supports APFS copy-on-write optimization on same-volume scenarios @@ -463,12 +476,12 @@ Example: export MLXK2_ENABLE_ALPHA_FEATURES=1 # Clone model to workspace -mlxk2 clone org/model ./workspace +mlxk clone org/model ./workspace ``` ### `push` - Upload to Hub -`mlxk2 push` is a hidden alpha feature. Enable with `MLXK2_ENABLE_ALPHA_FEATURES=1`. It uploads a local folder to a Hugging Face model repository using `huggingface_hub/upload_folder`. +`mlxk push` is a hidden alpha feature. Enable with `MLXK2_ENABLE_ALPHA_FEATURES=1`. It uploads a local folder to a Hugging Face model repository using `huggingface_hub/upload_folder`. - Requires `HF_TOKEN` (write-enabled). - Default branch: `main` (explicitly override with `--branch`). @@ -491,7 +504,7 @@ Example: export MLXK2_ENABLE_ALPHA_FEATURES=1 # Use push command -mlxk2 push --private ./workspace org/model --create --commit "init" +mlxk push --private ./workspace org/model --create --commit "init" ``` These features are not final and may change or be removed in future releases. @@ -571,6 +584,6 @@ Apache License 2.0 — see `LICENSE` (root) and `mlxk2/NOTICE`.

Made with ❤️ by The BROKE team BROKE Logo
- Version 2.0.0-beta.6 | October 2025
+ Version 2.0.0 | November 2025
🔮 Next: BROKE Cluster for multi-node deployments

diff --git a/mlxk2/__init__.py b/mlxk2/__init__.py index d8d520a..76fd534 100644 --- a/mlxk2/__init__.py +++ b/mlxk2/__init__.py @@ -7,4 +7,4 @@ import warnings # Issue parity with 1.1.0 (Issue #22) warnings.filterwarnings('ignore', message='urllib3 v2 only supports OpenSSL 1.1.1+') -__version__ = "2.0.0b6" +__version__ = "2.0.0" diff --git a/pyproject.toml b/pyproject.toml index 35dc187..872b4cb 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,9 +3,9 @@ requires = ["setuptools>=61.0", "wheel"] build-backend = "setuptools.build_meta" [project] -name = "mlxk-json" +name = "mlx-knife" dynamic = ["version"] -description = "MLX-Knife 2.0 - JSON-first model management for automation" +description = "HuggingFace model management for MLX on Apple Silicon" readme = "README.md" requires-python = ">=3.9" license = {text = "Apache-2.0"} @@ -13,12 +13,12 @@ authors = [ {name = "The BROKE team", email = "broke@gmx.eu"}, ] classifiers = [ - "Development Status :: 3 - Alpha", + "Development Status :: 5 - Production/Stable", "Intended Audience :: Developers", "Topic :: Scientific/Engineering :: Artificial Intelligence", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.9", - "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", @@ -38,6 +38,7 @@ dependencies = [ ] [project.scripts] +mlxk = "mlxk2.cli:main" mlxk-json = "mlxk2.cli:main" mlxk2 = "mlxk2.cli:main"