mirror of
https://github.com/cloudstack-llc/mlx-knife.git
synced 2026-07-19 14:43:36 -04:00
The BROKE Cluster Team
9261bc0c4e
- Clone Feature (Issue #29): Complete workspace-based workflow with ADR-007 - Pull Preflight (Issue #30): Prevents cache pollution from gated/private repos - Lenient MLX Detection (Issue #31): Framework detection beyond mlx-community - Multi-shard Health (Issue #27): Strict completeness validation - Full JSON API 0.1.4: Complete schema for all 10 commands - Test Suite: 254/254 passed, comprehensive validation See CHANGELOG.md fnd TESTING.md or technical implementation details.
282 lines
9.2 KiB
JSON
282 lines
9.2 KiB
JSON
{
|
|
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
"$id": "https://example.com/mlxk-json-api.schema.json",
|
|
"title": "MLX-Knife 2.0 JSON API (current)",
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"status": {"type": "string", "enum": ["success", "error"]},
|
|
"command": {"type": "string", "enum": ["list", "show", "health", "pull", "rm", "clone", "version", "push", "run", "server"]},
|
|
"api_version": {"type": "string", "pattern": "^json-[0-9]+\\.[0-9]+\\.[0-9]+$"},
|
|
"data": {"type": ["object", "null"]},
|
|
"error": {
|
|
"type": ["object", "null"],
|
|
"properties": {
|
|
"type": {"type": "string"},
|
|
"message": {"type": "string"},
|
|
"matches": {"type": "array", "items": {"type": "string"}},
|
|
"available_hashes": {"type": "array", "items": {"type": "string"}}
|
|
},
|
|
"additionalProperties": true
|
|
}
|
|
},
|
|
"required": ["status", "command", "data", "error"],
|
|
"allOf": [
|
|
{"$ref": "#/definitions/byCommand"}
|
|
],
|
|
"definitions": {
|
|
"hash40": {"type": "string", "pattern": "^[A-Za-z0-9]{40}$"},
|
|
"isoUtcZ": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$"},
|
|
"healthEntry": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {"type": "string"},
|
|
"status": {"type": "string", "enum": ["healthy", "unhealthy"]},
|
|
"reason": {"type": "string"}
|
|
},
|
|
"required": ["name", "status", "reason"],
|
|
"additionalProperties": false
|
|
},
|
|
"modelObject": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"name": {"type": "string"},
|
|
"hash": {"anyOf": [{"$ref": "#/definitions/hash40"}, {"type": "null"}]},
|
|
"size_bytes": {"type": "integer", "minimum": 0},
|
|
"last_modified": {"$ref": "#/definitions/isoUtcZ"},
|
|
"framework": {"type": "string", "enum": ["MLX", "GGUF", "PyTorch", "Unknown"]},
|
|
"model_type": {"type": "string", "enum": ["chat", "embedding", "base", "unknown"]},
|
|
"capabilities": {
|
|
"type": "array",
|
|
"items": {"type": "string", "enum": ["text-generation", "chat", "embeddings", "completion"]}
|
|
},
|
|
"health": {"type": "string", "enum": ["healthy", "unhealthy"]},
|
|
"cached": {"type": "boolean"}
|
|
},
|
|
"required": [
|
|
"name", "hash", "size_bytes", "last_modified", "framework",
|
|
"model_type", "capabilities", "health", "cached"
|
|
]
|
|
},
|
|
"fileEntry": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"name": {"type": "string"},
|
|
"size": {"type": "string"},
|
|
"type": {"type": "string"}
|
|
},
|
|
"required": ["name", "size", "type"]
|
|
},
|
|
"byCommand": {
|
|
"allOf": [
|
|
{
|
|
"if": {
|
|
"allOf": [
|
|
{"properties": {"status": {"const": "success"}}},
|
|
{"properties": {"command": {"const": "version"}}}
|
|
]
|
|
},
|
|
"then": {
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"cli_version": {"type": "string"},
|
|
"json_api_spec_version": {"type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"}
|
|
},
|
|
"required": ["cli_version", "json_api_spec_version"]
|
|
}
|
|
}
|
|
},
|
|
"else": {}
|
|
},
|
|
{
|
|
"if": {
|
|
"allOf": [
|
|
{"properties": {"status": {"const": "success"}}},
|
|
{"properties": {"command": {"const": "list"}}}
|
|
]
|
|
},
|
|
"then": {
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"models": {"type": "array", "items": {"$ref": "#/definitions/modelObject"}},
|
|
"count": {"type": "integer", "minimum": 0}
|
|
},
|
|
"required": ["models", "count"]
|
|
}
|
|
}
|
|
},
|
|
"else": {}
|
|
},
|
|
{
|
|
"if": {
|
|
"allOf": [
|
|
{"properties": {"status": {"const": "success"}}},
|
|
{"properties": {"command": {"const": "show"}}}
|
|
]
|
|
},
|
|
"then": {
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"model": {"$ref": "#/definitions/modelObject"},
|
|
"metadata": {"type": ["object", "null"]},
|
|
"files": {"type": "array", "items": {"$ref": "#/definitions/fileEntry"}},
|
|
"config": {"type": ["object", "null"]}
|
|
},
|
|
"required": ["model"]
|
|
}
|
|
}
|
|
},
|
|
"else": {}
|
|
},
|
|
{
|
|
"if": {
|
|
"allOf": [
|
|
{"properties": {"status": {"const": "success"}}},
|
|
{"properties": {"command": {"const": "health"}}}
|
|
]
|
|
},
|
|
"then": {
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": false,
|
|
"properties": {
|
|
"healthy": {
|
|
"type": "array",
|
|
"items": {"$ref": "#/definitions/healthEntry"}
|
|
},
|
|
"unhealthy": {
|
|
"type": "array",
|
|
"items": {"$ref": "#/definitions/healthEntry"}
|
|
},
|
|
"summary": {
|
|
"type": "object",
|
|
"properties": {
|
|
"total": {"type": "integer", "minimum": 0},
|
|
"healthy_count": {"type": "integer", "minimum": 0},
|
|
"unhealthy_count": {"type": "integer", "minimum": 0}
|
|
},
|
|
"required": ["total", "healthy_count", "unhealthy_count"],
|
|
"additionalProperties": false
|
|
}
|
|
},
|
|
"required": ["healthy", "unhealthy", "summary"]
|
|
}
|
|
}
|
|
},
|
|
"else": {}
|
|
},
|
|
{
|
|
"if": {
|
|
"allOf": [
|
|
{"properties": {"status": {"const": "success"}}},
|
|
{"properties": {"command": {"const": "pull"}}}
|
|
]
|
|
},
|
|
"then": {
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"model": {"type": ["string", "null"]},
|
|
"download_status": {"type": "string"},
|
|
"message": {"type": "string"},
|
|
"expanded_name": {"type": ["string", "null"]}
|
|
},
|
|
"required": ["download_status", "message"]
|
|
}
|
|
}
|
|
},
|
|
"else": {}
|
|
},
|
|
{
|
|
"if": {
|
|
"allOf": [
|
|
{"properties": {"status": {"const": "success"}}},
|
|
{"properties": {"command": {"const": "rm"}}}
|
|
]
|
|
},
|
|
"then": {
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"model": {"type": ["string", "null"]},
|
|
"action": {"type": "string"},
|
|
"message": {"type": "string"}
|
|
},
|
|
"required": ["action"]
|
|
}
|
|
}
|
|
},
|
|
"else": {}
|
|
},
|
|
{
|
|
"if": {
|
|
"allOf": [
|
|
{"properties": {"status": {"const": "success"}}},
|
|
{"properties": {"command": {"const": "push"}}}
|
|
]
|
|
},
|
|
"then": {
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"repo_id": {"type": "string"},
|
|
"branch": {"type": "string"},
|
|
"commit_sha": {"type": ["string", "null"]},
|
|
"repo_url": {"type": "string"},
|
|
"uploaded_files_count": {"type": ["integer", "null"], "minimum": 0},
|
|
"experimental": {"type": "boolean"},
|
|
"disclaimer": {"type": "string"}
|
|
},
|
|
"required": ["repo_id", "branch", "repo_url"]
|
|
}
|
|
}
|
|
},
|
|
"else": {}
|
|
},
|
|
{
|
|
"if": {
|
|
"allOf": [
|
|
{"properties": {"status": {"const": "success"}}},
|
|
{"properties": {"command": {"const": "run"}}}
|
|
]
|
|
},
|
|
"then": {
|
|
"properties": {
|
|
"data": {
|
|
"type": "object",
|
|
"additionalProperties": true,
|
|
"properties": {
|
|
"model": {"type": "string"},
|
|
"prompt": {"type": "string"},
|
|
"response": {"type": "string"},
|
|
"tokens_generated": {"type": "integer"},
|
|
"generation_time_s": {"type": "number"}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"else": {}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|