guidance vs instructor: shaping output during generation or validating it afterwards

One library shapes the stream, the other checks the answer

Both projects are MIT licensed Python libraries for turning a language model response into something a program can use, and both sit in the same place in your code: between the model client and the business logic that wants typed data. The difference is when they act. guidance intervenes during generation. It hands the model a constraint, a regular expression, a fixed list of choices or a context free grammar, and the model is steered toward legal output while it writes, so the shape never appears broken in the first place. instructor intervenes after generation. It sends the request, receives whatever the provider returned, runs it through Pydantic validation, and when validation fails it feeds the error message back and tries again. That makes them closer to complements than head-to-head rivals. The test is not which library is newer. It is whether you can describe the shape of the answer before you call the model. If you can, guidance fits. If the answer only becomes a record after you have read it, instructor fits.

guidance holds the model inside a grammar while it writes

The guidance model object is immutable, and its API is built from context managers. `system()`, `user()` and `assistant()` scope the role of each piece of text, and `lm += gen(...)` appends to a copy of the model rather than mutating the original. The constraint lives inside `gen()`. A regular expression attaches directly, a `select()` call narrows the answer to one entry from a list you supply, and the README states that any context free grammar can be enforced so long as the backend has full support for guidance. Two details matter for a reader choosing between the libraries. The enforcement happens at token selection time, so the model never emits an illegal value that has to be caught later. And guidance ships a `Mock` model, which lets you match candidate strings against a grammar and run a whole flow without a model API call, so iterating on a grammar costs no tokens. The limit is the one the README names: when the backend does not honour the constraint system, the guarantee weakens, which makes the backend part of your design decision.

instructor hands back a validated Pydantic object

The instructor entry point is a client wrapper. `instructor.from_provider("openai/gpt-4o-mini")` returns a client whose `chat.completions.create()` call takes `response_model=User` instead of a hand-written JSON schema, and the call returns an instance of that Pydantic model rather than a string. When validation fails, instructor retries with the error message, and the README shows this driven by `max_retries=3`. Nested models go through the same path, and `Partial[User]` produces a stream of half-built objects as the fields arrive. The provider layer is where this library differs most from guidance. The README lists OpenAI, Anthropic, Google, Ollama and Groq behind the same `from_provider` string, and an API key can be passed inline rather than read from the environment. The README also draws a line for larger ambitions: use instructor for fast extraction, and move to PydanticAI when the application needs typed tools, replayable datasets, evals or production dashboards. That boundary is stated by the project itself.

Getting each library running for the first time

Both install with pip, and both assume you already have a model you can reach. The guidance README says a plain `pip install guidance` is enough when you already have the backend your model needs, and it names Transformers, llama.cpp and OpenAI among the backends. The first script is short: create a model object, wrap the conversation in the role blocks, and read the named result back out. The instructor README gives `pip install instructor` and also `uv add instructor` and `poetry add instructor`, then a single call that takes a provider string and a Pydantic model. Setup cost is close. What differs is what has to exist before the first call runs. instructor asks for a provider string and a key. guidance asks you to choose a backend and, if you want the grammar features, to install the matching optional extra. Our analysis of guidance says to verify on your own machine which extra matches your backend and whether that backend honours the constraint system, because that check decides whether the guarantees hold at all.

Where guidance stops and instructor keeps going

The two libraries fail in opposite directions, and that is the practical way to choose between them. guidance is the stronger choice when the shape of the answer is known before the call and must hold exactly, because it enforces the shape during generation and can produce one value from a fixed list of options. It is the weaker choice the moment you want free-form text, or when your provider is not among the supported backends, since the README's own condition is that grammar support holds only while the backend has full support. instructor is the stronger choice for the opposite problem: text in, records out, with fields and types decided by a Pydantic model your editor can check. It is the weaker choice when the answer has to arrive in one pass, since a failed attempt costs another round trip. Scaling follows from that. guidance costs per token and stays inside your process. instructor costs per attempt, so a high validation failure rate turns into latency and spend at the same time.

Same MIT licence, and a maintenance gap worth naming

Licence is not a differentiator. Both projects are MIT, so either can ship inside a commercial product, and neither carries the copyleft obligation that would change how you host a service. Maintenance is where the two diverge. The last push to instructor was on 2026-10-01, with three tagged releases between June and September 2026. The last push to guidance was on 2026-05-21, and its most recent release was 0.3.2 on 2026-03-18. That gap does not make guidance a dead project, but it is a fair question to ask before you bind a grammar to a release cycle. It does mean instructor is the safer default for a team that wants a package with a current patch release behind it. If you pick guidance, pin the version, and read the release notes for the backend you use, because a grammar that works against one backend's constraint support is not portable to another.

Which one to pick for a concrete job

Pick instructor when the answer is a record with named fields and you would rather not write the JSON schema, the parser and the retry loop yourself. That is the common case: document parsing, form extraction, routing a support ticket into a typed case, pulling a structure out of a long transcript. Pick guidance when the output is consumed by another machine rather than by a person, and that machine is strict. A date in a fixed format, a numeric field, a label from a fixed set, a fragment of a larger grammar for a downstream parser: these are the cases where being right the first time matters more than being flexible. The wrong choice is easier to spot than the right one. Choosing guidance for free-form writing adds machinery nobody asked for. Choosing instructor for a grammar that must be obeyed exactly accepts that a retry might still fail. If both are on the table for one application, generate the constrained text with guidance, validate the record with instructor, and accept the extra layer.

Bottom line

Start with instructor if the work is extraction, because it returns a validated object and ships current releases, and check the provider string against the version you install. Move to guidance when the output must satisfy a grammar at generation time, and confirm your backend enforces it. If only one can be adopted, instructor is the shorter path now.

Sources

1. guidance-ai/guidance repository
2. guidance-ai/guidance README
3. 567-labs/instructor repository
4. 567-labs/instructor README