Skip to content

Envelope schema (v1)

The canonical schema for the signed envelope. The machine-readable JSON Schema lives at envelope/schema/envelope.v1.json in the repository.

Top-level fields

Field Type Required Description
envelope_version string yes Literal "v1".
suite_id string yes Suite identifier, e.g. llm.inference.
suite_version string yes Plugin SemVer (e.g. 1.0.0).
run_id string yes UUIDv7, sortable by timestamp.
timestamp string yes RFC 3339 UTC.
model object yes See ModelConfig.
engine object yes See EngineConfig.
quantization object | null no See Quantization.
hardware_fingerprint object yes See HardwareFingerprint.
software_provenance object yes See SoftwareProvenance.
dataset object yes See DatasetSpec.
seed integer yes Explicit integer seed.
driver_options object no Free-form driver config.
metrics object yes At least one metric. Per-suite keys.
distributions object no Pointers to distribution data.
slo_template string no SLO template id.
warnings array no Non-fatal warnings.
signature object | null no Sigstore signature bundle. null for unsigned envelopes.

ModelConfig

Field Type Description
id string Provider-prefixed model id (meta-llama/Llama-4-Maverick).
revision string Git SHA or HF revision (7–40 chars).
provider string vllm-local, together, anthropic, ...
endpoint_hash string SHA-256 of the endpoint configuration.

EngineConfig

Field Type Description
name string vllm, sglang, trtllm, ...
version string Engine SemVer.
config_hash string SHA-256 of the engine config.
image_digest string OCI image digest if containerized; empty otherwise.

Quantization

Field Type Description
format string bf16, fp16, fp8, nvfp4, awq-int4, gptq-int4, gguf-q4_k_m, ...
method string Free-form description of the quant method.

HardwareFingerprint

Field Type Description
fingerprint_sha256 string SHA-256 of the canonical body.
dmi_uuid string DMI product UUID.
gpus array Per-GPU detail.
cpu object {model, microcode}.
memory object {channels, speed_mts, ecc}.
bios object {version, resizable_bar, above_4g}.
numa object Canonical NUMA topology.
driver string GPU driver version.
cuda string CUDA toolkit version.
nccl string NCCL version.

GPU

Field Type Description
model string Marketing name, e.g. H100-SXM5-80GB.
pci_id string PCI bus id (0000:1b:00.0).
serial string GPU serial.
vbios string VBIOS version.

SoftwareProvenance

Field Type Description
image_digest string OCI image digest; empty if running natively.
pip_freeze_hash string SHA-256 of pip freeze output.
git_commit string Git commit of the harness.
nvidia_smi_q_hash string SHA-256 of nvidia-smi -q; empty on non-NVIDIA.

DatasetSpec

Field Type Description
id string Dataset id (e.g. sharegpt-v3).
hash string SHA-256 of the canonical-ordered dataset.

Signature

Field Type Description
method string sigstore-cosign or dev-key.
certificate string PEM-encoded certificate.
rekor_log_index integer Rekor transparency log index; -1 for dev mode.
bundle string Full Sigstore bundle (base64).

Content hash

The content hash is the SHA-256 of the canonical JSON body, excluding the signature block:

body = envelope.model_dump(exclude={"signature"}, mode="json")
canonical = json.dumps(body, sort_keys=True, separators=(",", ":"), default=str)
content_hash = hashlib.sha256(canonical.encode("utf-8")).hexdigest()

This is the value Sigstore signs.

Forward compatibility

The schema tolerates unknown fields (extra="allow" in the Pydantic models). Old clients can read newer envelopes, ignoring fields they do not understand. Breaking changes bump envelope_version and ship a migration.

See also