use serde_json::{json, Value};
fn string() -> Value {
json!({"type": "string"})
}
fn target_source() -> Value {
json!({
"type": "string",
"enum": ["argv", "stdin", "active"],
"description": "where the target came from; absent when the verb has no single target",
})
}
fn number() -> Value {
json!({"type": "number"})
}
fn integer() -> Value {
json!({"type": "integer"})
}
fn boolean() -> Value {
json!({"type": "boolean"})
}
fn envelope_base() -> Value {
json!({
"schema_version": string(),
"correlation_id": string(),
})
}
fn with_base(extra: Value) -> Value {
let mut props = envelope_base();
let map = props.as_object_mut().expect("object");
for (k, v) in extra.as_object().expect("object") {
map.insert(k.clone(), v.clone());
}
props
}
fn object(required: &[&str], properties: Value, description: &str) -> Value {
json!({
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"description": description,
"required": required,
"properties": properties,
})
}
pub fn all() -> Vec<(&'static str, Value)> {
vec![
("transcribe", transcribe()),
("transcribe-summary", transcribe_summary()),
("transcribe-dry-run", transcribe_dry_run()),
("inspect", inspect()),
("models-list", models_list()),
("models-download", models_download()),
("models-path", models_path()),
("models-remove", models_remove()),
("models-verify", models_verify()),
("doctor", doctor()),
("config-path", config_path()),
("config-list", config_list()),
("config-get", config_get()),
("config-set", config_set()),
("config-unset", config_unset()),
("schema", schema_doc()),
("commands", commands()),
("version", version()),
("licenses", licenses()),
("locale-show", locale_show()),
("locale-set", locale_set()),
("locale-clear", locale_clear()),
("error", error()),
]
}
pub fn names() -> Vec<&'static str> {
all().into_iter().map(|(name, _)| name).collect()
}
pub fn get(name: &str) -> Option<Value> {
all().into_iter().find(|(n, _)| *n == name).map(|(_, v)| v)
}
fn segment() -> Value {
json!({
"type": "object",
"required": ["start", "end", "text"],
"properties": {
"start": {"type": "number", "description": "seconds from the start of the audio"},
"end": {"type": "number", "description": "seconds from the start of the audio"},
"text": string(),
}
})
}
fn transcribe() -> Value {
object(
&[
"schema_version",
"correlation_id",
"target_resolved",
"target_source",
"file",
"language",
"language_source",
"model",
"device",
"duration_seconds",
"text",
"vad_chunks",
"hallucinations_removed",
"processing_time_ms",
"cold_load",
],
with_base(json!({
"target_resolved": string(),
"target_source": target_source(),
"file": string(),
"language": string(),
"language_source": {"type": "string", "enum": ["argv", "config", "default", "detection"]},
"model": string(),
"device": integer(),
"duration_seconds": number(),
"text": string(),
"segments": {
"type": "array",
"description": "present only with --timestamps",
"items": segment(),
},
"vad_chunks": integer(),
"hallucinations_removed": integer(),
"processing_time_ms": integer(),
"cold_load": {
"type": "boolean",
"description": "true when this pass loaded the model rather than reusing it",
},
})),
"One transcription result. In a batch this is one NDJSON line per input file.",
)
}
fn transcribe_summary() -> Value {
object(
&[
"schema_version",
"correlation_id",
"summary",
"ok",
"failed",
"total",
],
with_base(json!({
"summary": {"type": "boolean", "const": true},
"ok": integer(),
"failed": integer(),
"total": {
"type": "integer",
"description": "always equal to ok plus failed",
},
})),
"Final NDJSON line of a batch, tallying results.",
)
}
fn transcribe_dry_run() -> Value {
object(
&[
"schema_version",
"correlation_id",
"dry_run",
"would_transcribe",
],
with_base(json!({
"dry_run": {"type": "boolean", "const": true},
"target_resolved": string(),
"target_source": target_source(),
"would_transcribe": {
"type": "object",
"required": ["files", "model", "language", "beam_size", "device", "concurrency", "vad"],
"properties": {
"files": integer(),
"model": string(),
"language": string(),
"beam_size": integer(),
"device": integer(),
"concurrency": integer(),
"vad": number(),
}
},
})),
"Plan of a transcription that was not executed.",
)
}
fn inspect() -> Value {
object(
&[
"schema_version",
"correlation_id",
"file",
"format",
"duration_seconds",
],
with_base(json!({
"target_resolved": string(),
"target_source": target_source(),
"file": string(),
"format": string(),
"sample_rate": integer(),
"channels": integer(),
"duration_seconds": number(),
"is_video": boolean(),
"text": {"type": "null", "description": "always null; inspect never transcribes"},
})),
"Container facts read from a media file header.",
)
}
fn models_list() -> Value {
object(
&["schema_version", "correlation_id", "models"],
with_base(json!({
"models": {
"type": "array",
"items": {
"type": "object",
"required": ["name", "filename", "present", "verified", "size_bytes", "sha1", "url"],
"properties": {
"name": string(),
"filename": string(),
"present": {"type": "boolean", "description": "on disk with the declared size"},
"verified": {"type": "boolean", "description": "digest matched"},
"size_bytes": integer(),
"sha1": {"type": "string", "pattern": "^[0-9a-f]{40}$"},
"url": string(),
}
}
},
})),
"The model catalog and what is cached locally.",
)
}
fn models_download() -> Value {
object(
&[
"schema_version",
"correlation_id",
"target_resolved",
"model",
"action",
"path",
],
with_base(json!({
"target_resolved": string(),
"target_source": target_source(),
"model": string(),
"action": {"type": "string", "const": "download"},
"path": string(),
})),
"A model fetched and verified into the cache.",
)
}
fn models_path() -> Value {
object(
&[
"schema_version",
"correlation_id",
"target_resolved",
"path",
],
with_base(json!({
"target_resolved": string(),
"target_source": target_source(),
"path": string(),
})),
"Where a cached model lives.",
)
}
fn models_remove() -> Value {
object(
&[
"schema_version",
"correlation_id",
"target_resolved",
"model",
"action",
"removed",
],
with_base(json!({
"target_resolved": string(),
"target_source": target_source(),
"model": string(),
"action": {"type": "string", "const": "remove"},
"removed": {
"type": "boolean",
"description": "whether a cached file was actually deleted; false means it was already absent, which is still a success",
},
})),
"A model deleted from the cache.",
)
}
fn models_verify() -> Value {
object(
&[
"schema_version",
"correlation_id",
"target_resolved",
"ok",
"sha1",
],
with_base(json!({
"target_resolved": string(),
"target_source": target_source(),
"ok": {"type": "boolean", "const": true},
"sha1": {"type": "string", "pattern": "^[0-9a-f]{40}$"},
})),
"The measured digest of a cached model.",
)
}
fn doctor() -> Value {
object(
&[
"schema_version",
"correlation_id",
"gpu_present",
"toolkit",
"checks",
"engine",
],
with_base(json!({
"gpu_present": boolean(),
"gpu_name": string(),
"driver": string(),
"free_bytes": {
"type": ["integer", "null"],
"description": "null when the probe could not measure; never read as unlimited",
},
"total_bytes": {"type": ["integer", "null"]},
"device": integer(),
"device_source": {
"type": "string",
"enum": ["argv", "config", "default"],
"description": "where the device index came from",
},
"device_count": integer(),
"toolkit": boolean(),
"engine": {"type": "string", "enum": ["cuda", "cpu", "stub", "none"]},
"suggested_model": {"type": ["string", "null"]},
"checks": {
"type": "array",
"items": {
"type": "object",
"required": ["name", "ok"],
"properties": {"name": string(), "ok": boolean(), "detail": {}},
}
},
})),
"Host readiness report. Written before the verb fails, so a broken host still gets one.",
)
}
fn config_path() -> Value {
object(
&["schema_version", "correlation_id", "path"],
with_base(json!({"path": string()})),
"Where the configuration file lives.",
)
}
fn config_list() -> Value {
object(
&["schema_version", "correlation_id", "keys"],
with_base(json!({
"keys": {
"type": "array",
"items": {
"type": "object",
"required": ["key", "value"],
"properties": {"key": string(), "value": {}},
}
},
})),
"Every configuration key and its effective value.",
)
}
fn config_get() -> Value {
object(
&[
"schema_version",
"correlation_id",
"target_resolved",
"key",
"value",
],
with_base(json!({
"target_resolved": string(),
"target_source": target_source(),
"key": string(),
"value": {},
})),
"One configuration value.",
)
}
fn config_set() -> Value {
object(
&[
"schema_version",
"correlation_id",
"target_resolved",
"key",
"value",
"action",
],
with_base(json!({
"target_resolved": string(),
"target_source": target_source(),
"key": string(),
"value": {},
"action": {"type": "string", "const": "set"},
})),
"A configuration value written to disk.",
)
}
fn config_unset() -> Value {
object(
&[
"schema_version",
"correlation_id",
"target_resolved",
"key",
"action",
],
with_base(json!({
"target_resolved": string(),
"target_source": target_source(),
"key": string(),
"value": {"description": "the value after removal, which is the default"},
"action": {"type": "string", "const": "unset"},
})),
"A configuration key returned to its default.",
)
}
fn schema_doc() -> Value {
let mut doc = object(
&["schema_version", "correlation_id"],
with_base(json!({
"name": string(),
"schema": {"type": "object"},
"schemas": {
"type": "array",
"description": "present when no name was asked for",
"items": string(),
},
})),
"A published contract, or the list of them.",
);
doc["oneOf"] = json!([
{"required": ["name", "schema"], "description": "one contract, asked for by name"},
{"required": ["schemas"], "description": "the list, when no name was asked for"},
]);
doc
}
fn commands() -> Value {
object(
&["schema_version", "correlation_id", "commands"],
with_base(json!({
"commands": {"type": "array", "items": string()},
})),
"Every verb this binary accepts.",
)
}
fn version() -> Value {
object(
&[
"schema_version",
"correlation_id",
"name",
"version",
"contract",
"engine",
],
with_base(json!({
"name": string(),
"version": string(),
"contract": string(),
"engine": {
"type": "string",
"enum": ["cuda", "cpu", "stub", "none"],
"description": "which inference backend was compiled in",
},
})),
"Identity of this binary, including which engine it can actually run.",
)
}
fn licenses() -> Value {
object(
&["schema_version", "correlation_id", "licenses"],
with_base(json!({
"licenses": {"type": "array", "items": string()},
})),
"Licences of this product and of what it embeds.",
)
}
fn locale_show() -> Value {
object(
&["schema_version", "correlation_id", "locale"],
with_base(json!({"locale": string()})),
"The interface language in effect.",
)
}
fn locale_set() -> Value {
object(
&[
"schema_version",
"correlation_id",
"target_resolved",
"locale",
"action",
],
with_base(json!({
"target_resolved": string(),
"target_source": target_source(),
"locale": string(),
"action": {"type": "string", "const": "set"},
})),
"The interface language written to disk.",
)
}
fn locale_clear() -> Value {
object(
&["schema_version", "correlation_id", "locale", "action"],
with_base(json!({
"locale": {"description": "the language after removal, which is the host default"},
"action": {"type": "string", "const": "clear"},
})),
"The interface language returned to the host default.",
)
}
fn error() -> Value {
object(
&[
"schema_version",
"correlation_id",
"error",
"ok",
"code",
"message",
],
with_base(json!({
"error": {"type": "boolean", "const": true},
"ok": {"type": "boolean", "const": false},
"code": {"type": "integer", "description": "the process exit code"},
"category": string(),
"message": string(),
"hint": string(),
"retryable": {
"type": "boolean",
"description": "false means retrying the same invocation cannot help",
},
"target_resolved": {
"type": "string",
"description": "the argv slot this failure belongs to; absent for verbs with no target",
},
"target_source": target_source(),
})),
"Failure envelope. Never suppressed by output shaping.",
)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn every_name_resolves_and_is_unique() {
let names = names();
let mut sorted = names.clone();
sorted.sort_unstable();
sorted.dedup();
assert_eq!(sorted.len(), names.len(), "schema names must be unique");
for name in names {
let doc = get(name).unwrap_or_else(|| panic!("{name} must resolve"));
assert_eq!(doc["type"], "object", "{name} must describe an object");
assert!(
doc["required"].as_array().is_some_and(|r| !r.is_empty()),
"{name} must declare required properties"
);
}
}
#[test]
fn an_unknown_name_does_not_resolve() {
assert!(get("not-a-contract").is_none());
}
#[test]
fn every_contract_requires_the_common_envelope() {
for (name, doc) in all() {
let required: Vec<&str> = doc["required"]
.as_array()
.expect("required")
.iter()
.filter_map(|v| v.as_str())
.collect();
assert!(
required.contains(&"schema_version") && required.contains(&"correlation_id"),
"{name} must require schema_version and correlation_id"
);
}
}
}