Kiln Documentation

Serving

HF next-token request schema

Define the source, model, rendered prompt, continuation prefix, and candidates for an independent Hugging Face next-token comparison.

Exact input contract for an independent eager Hugging Face next-token comparison. It binds the source revision, model bytes, rendered prompt, continuation prefix, and disputed Kiln and vLLM candidates; the oracle result is recorded separately.

Schema identity

Property Value
Title Kiln Hugging Face Next-Token Request v1
$id https://ericflo.github.io/kiln/schemas/hf-next-token-request-v1.schema.json
Dialect https://json-schema.org/draft/2020-12/schema
Root type object
Root object closed

Root fields

Field Required Type Constraints and default Description
schema yes any const "kiln.hf-next-token-request.v1" Schema identifier for this request format.
id yes string pattern ^[a-z0-9][a-z0-9._-]{2,127}$ Stable, path-safe identifier for this attribution request.
source yes object closed object Source revision and qualification receipts that produced the two disputed candidate tokens.
model_identity yes modelIdentity - Content identity of the exact model, tokenizer, chat template, configuration, and weight shards used for attribution.
prompt yes object closed object Single-user prompt recipe and the exact rendered token sequence before the continuation prefix is appended.
continuation_prefix yes array<token> minimum items 1; maximum items 64 Ordered token sequence forced after the rendered prompt to reproduce the first divergent next-token state.
input_token_ids yes tokenIds - Complete oracle input: the rendered prompt token IDs followed by the continuation-prefix token IDs.
input_token_ids_sha256 yes sha256 - SHA-256 identity of the canonical complete input-token sequence.
candidates yes array minimum items 2; maximum items 2 Exactly two disputed next-token candidates, ordered as Kiln first and vLLM second.

Definitions

sha256Lowercase SHA-256 digest with the `sha256:` algorithm prefix.0 fields

Type: string. Constraints: pattern ^sha256:[0-9a-f]{64}$.

tokenIdTokenizer vocabulary ID for the bound Qwen3.5-4B model identity.0 fields

Type: integer. Constraints: minimum 0; maximum 248319.

tokenIdsBounded, nonempty sequence of tokenizer vocabulary IDs.0 fields

Type: array<tokenId>. Constraints: minimum items 1; maximum items 4096.

tokenOne continuation token represented by both vocabulary ID and decoded text.2 fields

Type: object. Constraints: closed object.

Field Required Type Constraints and default Description
token_id yes tokenId - Vocabulary ID of this continuation token.
text yes string - Tokenizer-decoded text for this token; it may be empty or contain nonprinting content.
candidateOne engine's disputed next-token prediction at the bound prompt and continuation state.3 fields

Type: object. Constraints: closed object.

Field Required Type Constraints and default Description
engine yes any enum "kiln", "vllm" Candidate-producing inference engine.
token_id yes tokenId - Vocabulary ID predicted by the named engine.
text yes string - Tokenizer-decoded text for the predicted token.
receiptReferenceRepository-relative qualification receipt with hashes of both its file bytes and canonical content.3 fields

Type: object. Constraints: closed object.

Field Required Type Constraints and default Description
path yes string minimum length 1 Repository-relative path to the retained receipt.
file_sha256 yes sha256 - SHA-256 identity of the receipt file's exact bytes.
content_sha256 yes sha256 - SHA-256 identity of the receipt's canonical content, excluding incidental serialization differences.
weightFileOne model weight shard and its exact size and content identity.3 fields

Type: object. Constraints: closed object.

Field Required Type Constraints and default Description
path yes string minimum length 1 Path or stable shard name within the bound model source.
bytes yes integer minimum 1 Exact weight-shard size in bytes.
sha256 yes sha256 - SHA-256 identity of the shard's exact bytes.
modelIdentityComplete content identity for the model inputs used by every candidate and oracle process.6 fields

Type: object. Constraints: closed object.

Field Required Type Constraints and default Description
id yes string minimum length 1 Human-readable model identifier recorded alongside the content hashes.
content_sha256 yes sha256 - Aggregate content identity for the complete model source.
config_hash yes sha256 - SHA-256 identity of the effective model configuration.
tokenizer_hash yes sha256 - SHA-256 identity of the tokenizer inputs.
chat_template_hash yes sha256 - SHA-256 identity of the chat template used to render the prompt.
weight_files yes array<weightFile> minimum items 1 Complete ordered inventory of model weight shards.