Outlines Library

Outlines compiles a target schema—such as a JSON Schema or Pydantic model—directly into a deterministic finite-state machine. This FSM tracks the exact state of the generation sequence and defines the set of permissible next tokens at each step.

• Guaranteed validity: The output is mathematically constrained to conform to the schema.
• No retries needed: Unlike prompt-based methods, invalid tokens are never generated.
• Schema types supported: JSON Schema, Pydantic, Context-Free Grammars, and regular expressions.

Instead of modifying logit probabilities, Outlines uses token masking by building a pre-computed index that maps each FSM state to the exact set of valid token IDs. During generation, only these valid tokens are considered.

• Zero probability for invalid tokens: The model's logits for out-of-schema tokens are physically masked.
• Deterministic execution: The same schema and prompt always produce the same structural path.
• Performance: The index lookup is O(1), adding negligible latency to the generation loop.

Outlines provides first-class support for Pydantic v2 models, allowing developers to define complex, nested data structures using Python type hints. The library automatically generates the corresponding FSM.

• Type safety: Generated output is a fully validated Pydantic object instance.
• Complex types: Supports Optional, Union, Literal, nested models, and custom validators.
• Example: Define a UserProfile model with name: str, age: int, and skills: list[str]—Outlines guarantees the model outputs exactly that structure.

Beyond structured data, Outlines can constrain generation to any pattern definable by a regular expression. The regex is compiled into an FSM, ensuring every character generated matches the specified pattern.

• Use cases: Generating phone numbers, email addresses, classification labels, or any fixed-format string.
• Example: The regex [A-Z]{3}-\d{4} guarantees output like ABC-1234.
• Composability: Regex constraints can be combined with other schema types for hybrid control.

Outlines operates at the tokenizer and logit processor level, making it compatible with a wide range of model backends without requiring model-specific modifications.

• Supported frameworks: Hugging Face Transformers, llama.cpp, vLLM, and MLX.
• Consistent API: The same structured generation code works across different model architectures.
• Integration: Works as a logit processor plugin, intercepting the generation loop transparently.

Outlines provides a choice function that restricts generation to a predefined set of string options, useful for classification tasks and slot filling. The library compiles the options into a trie-based FSM.

• Guaranteed selection: The model can only output one of the specified choices.
• Efficiency: The trie structure allows efficient token matching even for large option sets.
• Example: outlines.generate.choice(model, ["positive", "negative", "neutral"]) forces a sentiment label output.

The core computational backbone of the Outlines library. An FSM tracks the current valid state of an output sequence and dynamically determines the set of permissible next tokens. During guided decoding, the FSM transitions between states as each token is generated, physically masking invalid tokens by setting their logits to negative infinity. This guarantees that the final output string is a valid path through the state machine, ensuring 100% schema compliance without any post-processing or retry logic.

The process of forcing a language model's output to conform to a formal grammar, such as a Context-Free Grammar (CFG) or GBNF Grammar. Outlines compiles a user-provided schema into an indexable FSM that represents every valid string. During generation:

• The model's raw logits are filtered against the current FSM state
• Only tokens that lead to valid continuations are allowed
• This eliminates the need for output parsing and schema validation as separate steps, since the output is syntactically correct by construction

A declarative vocabulary for annotating and validating JSON documents. Outlines accepts a JSON Schema as input and automatically compiles it into an FSM for constrained generation. The schema defines:

• Required and optional properties
• Data types (string, integer, array, object)
• Enum constraints and pattern matching
• Nested object structures This allows developers to specify complex output structures like {"name": "string", "age": "integer"} and receive guaranteed valid JSON without writing custom parsers.

A Python data validation library that uses type hints to define data schemas. Outlines integrates natively with Pydantic models, allowing developers to define structured output using familiar Python classes:

• class User(BaseModel): name: str; age: int
• The Pydantic model is converted to a JSON Schema internally
• The FSM is compiled from that schema
• The generated output is automatically validated and deserialized into a Pydantic object instance This tight integration eliminates boilerplate and ensures type safety throughout the pipeline.

An umbrella term for techniques that constrain the token generation process to adhere to a predefined structure. Unlike output parsing which fixes errors after generation, guided decoding prevents errors from occurring. Key approaches include:

• Token masking: Setting invalid token probabilities to zero at each step
• Logit bias: Adjusting scores to suppress or encourage specific tokens
• Constrained beam search: Pruning beams that violate structural rules Outlines implements index-based guided decoding, which pre-computes the FSM transition table for O(1) token validation at each generation step.

A model generation result that is perfectly reproducible given the same input, seed, and constraints. Outlines achieves determinism through two mechanisms:

• Temperature zero: Eliminates randomness in token selection by always choosing the most probable valid token
• FSM constraints: The set of allowed tokens is deterministic based on the current state Combined, these ensure that the same prompt and schema always produce identical structured output, which is critical for data contracts, testing, and production pipelines where non-determinism is unacceptable.