mirror of
https://github.com/cloudstack-llc/mlx-knife.git
synced 2026-07-21 18:15:37 -04:00
The BROKE Team
c5777a3e7a
Session 2 Achievements (100% Complete): • All 5 operations implemented: list, health, show, pull, rm • CLI compatibility: fuzzy matching, @hash syntax, short names • Lock detection: New safety feature replacing interactive prompts • Pull corruption recovery: Clean rm→pull workflow • Hash fuzzy matching: show "model@3df9bfd" works with short hashes Session 3 Major Progress (70% Complete): • JSON API Specification v0.1.1: Complete and production-ready • Full SHA hashes: 40-char hashes in list output for broke-cluster • Show command: --files and --config options fully implemented • JSON-flag enforcement: --json required in alpha for correct usage Key Features: • Broke-cluster integration ready with enforced --json flag • Real-world tested: rm→pull workflow validated with corrupted cache • Lock cleanup: 9 lock files properly cleaned during rm operations • Sanitized JSON: No cache paths or implementation details exposed Testing Status: Basic unit tests implemented, manual validation successful Note: Test suite requires update for JSON API Specification v0.1.1 Package: Installable as mlxk-json alongside 1.1.0 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
67 lines
2.1 KiB
Markdown
67 lines
2.1 KiB
Markdown
# MLX-Knife Model Naming Specification
|
|
|
|
## Fundamental Mapping Rules
|
|
|
|
### Basic Conversion
|
|
**Universal conversion:** `--` ↔ `/` (all occurrences)
|
|
|
|
**External → Internal:** `org/sub/model` becomes `models--org--sub--model`
|
|
**Internal → External:** `models--org--sub--model` becomes `org/sub/model`
|
|
|
|
### Character Constraints (Clean Names)
|
|
|
|
**External names (clean):**
|
|
- ✅ Maximum **one `-`** consecutive (single dashes allowed)
|
|
- ✅ `/` as path separators
|
|
- ❌ Never `--` (double dashes forbidden)
|
|
|
|
**Internal cache (clean):**
|
|
- ✅ Maximum **two `-`** consecutive (`--` as separators only)
|
|
- ✅ Single `-` within names
|
|
- ❌ Never `---` or more (triple+ dashes forbidden)
|
|
|
|
### Why These Rules?
|
|
|
|
```
|
|
✅ Clean conversion:
|
|
External: org-name/model-v1
|
|
Internal: models--org-name--model-v1
|
|
|
|
❌ Rule violation creates chaos:
|
|
External: org--invalid/model (double dash = forbidden!)
|
|
Internal: models--org----model (quadruple dash = chaos!)
|
|
```
|
|
|
|
## Examples (Clean Names)
|
|
|
|
| External | Internal Cache Directory |
|
|
|----------|--------------------------|
|
|
| `microsoft/DialoGPT-small` | `models--microsoft--DialoGPT-small` |
|
|
| `org/sub/model` | `models--org--sub--model` |
|
|
| `single-model` | `models--single-model` |
|
|
|
|
## MLX-Knife Implementation: Tolerant Handling
|
|
|
|
### Robustness Philosophy
|
|
**"Be liberal in what you accept"** - MLX-Knife handles rule violations gracefully.
|
|
|
|
### Error Handling for Corrupted Cache
|
|
**When reading entries that violate rules:** Mechanical 1:1 conversion without validation
|
|
|
|
```
|
|
Cache: models--microsoft--DialogGPT---small (3 dashes = rule violation)
|
|
↓ Mechanical conversion: ALL "--" → "/"
|
|
External: microsoft/DialogGPT/-small (empty path segment visible)
|
|
```
|
|
|
|
**Benefits:**
|
|
- ✅ System remains functional (no crashes)
|
|
- ⚠️ Problems become visible (user sees `DialogGPT/-small`)
|
|
- 🔍 User can identify and fix corrupted entries
|
|
- 🛠️ No complex error handling required
|
|
|
|
## Compatibility
|
|
|
|
✅ **HuggingFace Hub:** Compatible with standard `org/model` format
|
|
✅ **Future-proof:** Supports deeper hierarchies like `org/sub/model`
|
|
✅ **Robust:** Converts corrupted cache entries without failing |