Recipe

CBOR Primer

CBOR (Concise Binary Object Representation, RFC 8949) is the binary wire format Meridian uses for its model-routing payloads. It is JSON-shaped, but smaller, faster to parse, and lossless for binary data. This primer shows you the three things you actually need to know to ship CBOR-encoded requests against the Meridian gateway.

1. Why CBOR over JSON

Meridian batches embeddings, tool-call payloads, and streaming deltas. Each of those workloads pays a penalty in JSON: floats stringify to 17 characters, byte arrays need base64, and the parser walks every character. CBOR encodes a float64 in 9 bytes, a 1KB byte string in 1KB plus a 3-byte header, and skips length-prefixed regions in constant time. On a typical embedding batch you save roughly 35 percent on the wire and 4x on parse latency.

2. The five major types

CBOR has a 3-bit major type packed into the first byte of every value. You only need to recognise five of them in practice: unsigned int (0), negative int (1), byte string (2), text string (3), and array (4). Map (5) and tagged values (6) appear in tool-call envelopes, and floats (7) appear in logits. The decoder reads the major type, reads the length, then reads the payload — recursion is straightforward.

3. Encoding a Meridian request

Use the cbor2 library in Python or cbor-x in Node. Set the Content-Type header to application/cbor and the gateway will decode, route, and re-encode the response in the same format.

import cbor2, requests

payload = {
    "model": "azure/model-router",
    "messages": [
        {"role": "user", "content": "Explain CBOR"}
    ],
    "max_tokens": 512,
}

body = cbor2.dumps(payload)
r = requests.post(
    "https://llm.getnimbus.net/v1/chat/completions",
    data=body,
    headers={
        "Content-Type": "application/cbor",
        "Accept": "application/cbor",
        "Authorization": "Bearer $MERIDIAN_KEY",
    },
)
reply = cbor2.loads(r.content)
print(reply["choices"][0]["message"]["content"])