{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://onefrontier.ai/schema/launch-card.schema.json", "title": "Launch card", "description": "The artifact between a Hugging Face weight path and a running GPU: which checkpoints are servable, how to serve them, on what hardware. Binds to the HF path. Directory path shadows huggingface.co//.", "type": "object", "required": ["schema", "hf", "checkpoints", "envs", "hardware", "performance", "gaps"], "additionalProperties": false, "properties": { "schema": { "const": "onefrontier.launch-card/v1", "description": "Version tag. A shape change bumps this and moves every card in the same round." }, "hf": { "type": "object", "required": ["repo", "revision", "modality"], "additionalProperties": false, "description": "The binding to Hugging Face. Everything here is read from the HF API, not asserted.", "properties": { "repo": { "type": "string", "pattern": "^[^/]+/[^/]+$", "description": "org/model exactly as HF spells it. This is the card's identity." }, "revision": { "type": "string", "description": "The commit sha the card was built against. A card without a revision describes a moving target." }, "license": { "type": ["string", "null"] }, "gated": { "type": ["boolean", "null"], "description": "true = access request required; null = HF did not say." }, "params_b": { "type": ["number", "null"], "description": "Total parameters in billions, from the HF metadata or the repo's safetensors index." }, "modality": { "type": "array", "items": { "type": "string" }, "description": "text, vision, image, video, audio — HF pipeline_tag plus the card's own read." }, "weight_gib": { "type": ["number", "null"], "description": "Sum of the repo's checkpoint bytes, at this revision. Null when the repo is a pointer or unmeasured." }, "last_modified": { "type": ["string", "null"] }, "downloads": { "type": ["integer", "null"], "description": "HF 30-day downloads at capture. The popularity rank the sweep ordered by." } } }, "checkpoints": { "type": "array", "description": "Every servable variant in or beside the repo. Empty only when the repo has no servable weights at all (a GGUF-only repo).", "items": { "type": "object", "required": ["name", "format"], "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The card's handle for this checkpoint: bf16, fp8, nvfp4, gguf-q4_k_m, pruned-1.5. Used by envs[].checkpoint." }, "format": { "enum": ["bf16", "fp16", "fp8", "nvfp4", "mxfp4", "mxfp8", "int4", "gguf", "awq", "gptq", "unknown"] }, "subdir": { "type": ["string", "null"], "description": "Path inside the repo when the variant is a subdirectory; null when it is the repo root." }, "source_repo": { "type": ["string", "null"], "description": "A different HF repo when the variant lives elsewhere (a gated twin, a community quant). Null when it is this repo." }, "resident_gib": { "type": ["number", "null"], "description": "VRAM-resident weight size after load, when known. Distinct from weight_gib: some checkpoints keep a host tier." }, "host_gib": { "type": ["number", "null"], "description": "Bytes that stay host-resident (Engram-style tables). Null when all of it loads to VRAM." }, "gated": { "type": ["boolean", "null"] }, "notes": { "type": ["string", "null"] } } } }, "envs": { "type": "array", "description": "One entry per engine+checkpoint combination with a published launch. A claim with a citation; never a guess.", "items": { "type": "object", "required": ["engine", "checkpoint", "argv", "source"], "additionalProperties": false, "properties": { "engine": { "enum": ["vllm", "sglang", "llama-cpp", "tensorrt-llm", "lmdeploy", "trtllm", "comfyui", "other"] }, "checkpoint": { "type": "string", "description": "Refers to checkpoints[].name." }, "engine_version": { "type": ["string", "null"], "description": "The engine release the recipe targets, e.g. '0.24.0+'." }, "image": { "type": ["string", "null"], "description": "Container image, with its tag. Digest when the source pins one." }, "argv": { "type": "array", "items": { "type": "string" }, "description": "The command as an array — the form a wrapper execs. Never a shell string." }, "command": { "type": ["string", "null"], "description": "The same command as the source printed it, for human reading." }, "env": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Environment the recipe requires." }, "validated_hardware": { "type": "array", "items": { "type": "string" }, "description": "The hardware keys the source marks verified, e.g. h200, b200, mi355x." }, "notes": { "type": ["string", "null"] }, "source": { "type": "object", "required": ["kind", "url"], "additionalProperties": false, "properties": { "kind": { "enum": ["vllm-recipes", "sglang-cookbook", "hf-model-card", "hf-readme", "kit-catalog", "observed-launch", "other"] }, "url": { "type": "string" }, "fetched_at": { "type": ["string", "null"] } } } } } }, "hardware": { "type": "object", "description": "Every aspect a box must satisfy. A launch failing on the third requirement wasted the first two.", "required": ["min_gpus", "tp_rule"], "additionalProperties": false, "properties": { "gpu_models": { "type": "array", "items": { "type": "string" }, "description": "Card names the recipe was validated on." }, "gpu_arch": { "type": "array", "items": { "enum": ["hopper", "blackwell", "ada", "ampere", "cdna3", "cdna4", "unknown"] } }, "min_gpus": { "type": "integer", "minimum": 1 }, "tp_rule": { "type": "string", "description": "Why the width cannot be narrower — head counts, MLA groups, a memory floor. Prose, because the constraint is usually a sentence." }, "min_vram_per_gpu_gib": { "type": ["number", "null"] }, "min_total_vram_gib": { "type": ["number", "null"] }, "min_disk_gib": { "type": ["number", "null"], "description": "Weights plus compile/cache headroom." }, "min_host_ram_gib": { "type": ["number", "null"] }, "interconnect": { "type": ["null", "nvlink", "pcie"], "description": "nvlink only when TP>1 genuinely demands it." }, "cuda_min": { "type": ["string", "null"] }, "driver_min": { "type": ["string", "null"] }, "context_tokens": { "type": ["integer", "null"], "description": "The window the stated flags actually deliver, which is often below the model's maximum." } } }, "performance": { "type": "string", "format": "uri", "description": "https://onefrontier.ai///performance — the page rendering measured cells for this weight path. A link, not a fact: performance is per cell, the card is per model." }, "evidence": { "type": "array", "description": "Everything the card was assembled from, so a reader can check it.", "items": { "type": "object", "required": ["kind", "url"], "additionalProperties": false, "properties": { "kind": { "type": "string" }, "url": { "type": "string" }, "fetched_at": { "type": ["string", "null"] } } } }, "gaps": { "type": "array", "description": "What the card could not fill. First-class: a named gap is honest, an invented field is a trap. Also the work queue — every entry is a launch nobody has done.", "items": { "type": "object", "required": ["field", "why"], "additionalProperties": false, "properties": { "field": { "type": "string" }, "why": { "type": "string" } } } }, "captured_at": { "type": ["string", "null"] }, "captured_by": { "type": ["string", "null"], "description": "The technique that produced the card, e.g. 'hf-api + vllm-recipes + sglang-cookbook'." } } }