Skip to content
Get packs

guidance

A Python library for steering language models so their output follows a set structure.

GitHub Download 0.3.2
Stars
21.8k
Forks
1.2k
Licence
MIT
Language
Jupyter Notebook
Last update
6 months ago
Type
Library

What it is

Guidance is a Python library for controlling how a language model writes its output. Instead of only writing a prompt and hoping for the right format, you can constrain generation with patterns like regular expressions or grammars, and mix in plain code such as conditionals, loops, and tool use. The README says this aims to give structured, higher-quality output while reducing latency and cost compared with conventional prompting or fine-tuning.

  • Force a model to answer with one item from a fixed list using select()
  • Constrain a number field with a regular expression such as \d+
  • Build reusable Python functions that call a model and return structured results
  • Check candidate strings against a grammar locally before running a model

Great for

  • Python developers who need model output in a predictable format, such as JSON-like or fixed-choice answers
  • Developers who want to run a model locally through backends like Transformers or llama.cpp
  • People building multi-step model workflows that mix generation with ordinary code
  • Developers who want to test grammars offline using the included Mock model

Not ideal for

  • Users who only use hosted chat interfaces and do not write Python, since it is a code library
  • Projects that need a model backend without the required backend installed, because the README says you need the backend for your model first
  • Teams needing a stable API, since the latest release is 0.3.2 and the README does not describe stability guarantees
Step-by-step guide: how to use guidanceInstall, first run, examples, tips and FAQs
DSPy vs guidance

How to get it

  1. 1

    Install with a package manager

    You'll need: Python · A supported model backend such as Transformers, llama.cpp, or OpenAI

    Install from PyPI

    pip install guidance
  2. 2

    Run it

    • Install the package with pip install guidance
    • Load a model backend, for example Transformers with microsoft/Phi-4-mini-instruct as shown in the README
    • Use gen() or select() inside a with assistant() block to produce constrained output
    • Read the result with lm['name'] after naming the generation
  3. 3

    Get the most out of it

    • Use the Mock model to test grammars without calling a model API, as shown in the README
    • Name your gen() and select() calls so you can read captured values easily
    • Wrap reusable logic in @guidance functions and compose them into larger grammars
    • Use the Jupyter widget for a richer view of output when working in notebooks

Downloads

Source code (.zip)main branch · straight from GitHubRelease 0.3.2Release notes and source

Strengths

  • Constrained generation lets you guarantee output syntax, per the README
  • Works with several backends, including Transformers, llama.cpp, and OpenAI
  • MIT licensed with an active repository and a large star count

Trade-offs

  • You must have a supported model backend set up, which adds setup effort
  • The README notes constraint support depends on the backend LLM having full Guidance support
  • Documentation shown in the README is partial, since it is truncated

Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.