@huggingface/transformers-structured-output

Experimental constrained-generation helpers for Transformers.js.

This dependency-free package exports StructuredOutputProcessor, which constrains Transformers.js generation to a JSON schema, JSON object, or regular expression.

The constraint engine is implemented specifically for Transformers.js and has no runtime dependencies.

import { StructuredOutputProcessor } from "@huggingface/transformers-structured-output";

const processor = new StructuredOutputProcessor(tokenizer, {
  type: "json_schema",
  json_schema: {
    type: "object",
    properties: {
      answer: { type: "string" },
    },
    required: ["answer"],
    additionalProperties: false,
  },
});

await model.generate({
  ...inputs,
  logits_processor: processor,
});

Constraints currently support a single generated sequence at a time. Generation throws when the logical batch size is not 1 rather than sharing mutable grammar state across sequences.

Supported constraints

The JSON engine implements a practical JSON Schema 2020-12 profile. This includes deep const and enum, exact decimal bounds and multipleOf, tuple and homogeneous arrays, contains, deep uniqueItems, object property and dependency assertions, allOf/anyOf/oneOf/not, conditionals, local $ref, recursive $defs, draft-07 compatibility, and root-level x-guidance separators. String pattern and recognized format assertions are rejected because they cannot be enforced incrementally; unknown format names remain annotations. External and dynamic references and unevaluated-property/item assertions also remain unsupported.

The regex engine performs full-string matching and supports literals, UTF-8 literals, alternation, groups, character classes, ., \\d, \\s, \\w, anchors, and greedy *, +, ?, and {m,n} quantifiers. Lookarounds, backreferences, lazy quantifiers, and Unicode character classes are intentionally unsupported.

When the generated bytes satisfy the constraint, the processor allows the tokenizer's EOS token. Transformers.js then stops generation through its built-in EOS stopping criterion, so the model generation config and tokenizer must use the same eos_token_id.

Regex constraints

Use type: "regex" to constrain generation to a regular expression. For example, this only allows ISO-like dates in YYYY-MM-DD format:

import { StructuredOutputProcessor } from "@huggingface/transformers-structured-output";

const processor = new StructuredOutputProcessor(tokenizer, {
  type: "regex",
  regex: "\\d{4}-\\d{2}-\\d{2}",
});

const output = await model.generate({
  ...inputs,
  logits_processor: processor,
});