mirror of https://github.com/cloudstack-llc/mlx-knife.git synced 2026-07-15 12:55:42 -04:00

Files

T

The BROKE Team c5777a3e7a MLX-Knife 2.0 Session 2 Complete + Session 3 Major Progress: Production-Ready Alpha

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>

2025-08-27 21:36:35 +02:00

2.1 KiB

Raw Permalink Blame History

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

2.1 KiB Raw Permalink Blame History