# Guidance — Constrained Generation in Python

> Guidance gives you constrained generation (regex, select lists, grammars) in Python. `pip install guidance`, then run with Transformers or other backends.

## Install

Save as a script file and run:

# Guidance — Constrained Generation in Python

> Guidance gives you constrained generation (regex, select lists, grammars) in Python. `pip install guidance`, then run with Transformers or other backends.

## Quick Use

1. Install:
   ```bash
   pip install guidance
   ```
2. Run:
   ```bash
   python -c "import guidance; print('guidance installed')"
   ```
3. Verify:
   - Run a constrained `gen(regex=...)` and confirm the output matches the regex every time


---

## Intro

Guidance gives you constrained generation (regex, select lists, grammars) in Python. `pip install guidance`, then run with Transformers or other backends.

- **Best for:** teams who need controllable formats (IDs, enums, templates) and want stronger guarantees than best-effort prompting
- **Works with:** Python, Guidance primitives (`gen`, `select`), model backends like Transformers/LlamaCpp/OpenAI (per repo)
- **Setup time:** 10 minutes


### Quantitative Notes

- Install command: `pip install guidance` (repo)
- Setup time ~10 minutes
- GitHub stars (verified): see Source & Thanks


---

## Practical Notes

Use Guidance as a safety layer when you can't afford invalid formats. Start with simple constraints (regex for numbers/IDs, `select()` for enums), then graduate to richer grammars. In agent pipelines, put constraints right before boundaries: DB writes, API calls, tool arguments, and routing decisions.

**Safety note:** Constraints can increase compute; budget latency by keeping grammars small and prompts focused.

### FAQ

**Q: What is constrained generation?**
A: You restrict the model to outputs that match a pattern (regex), belong to a list, or follow a grammar—reducing invalid responses.

**Q: Do I need a specific model?**
A: No. The repo mentions multiple backends; you pick one that fits your environment (local Transformers, llama.cpp, hosted APIs).

**Q: Where does it help most?**
A: Any step that must be parseable: routing labels, IDs, enums, JSON-like fields, or template-bound strings.

---

## Source & Thanks

> GitHub: https://github.com/guidance-ai/guidance
> Owner avatar: https://avatars.githubusercontent.com/u/142035062?v=4
> License (SPDX): MIT
> GitHub stars (verified via `api.github.com/repos/guidance-ai/guidance`): 21,453


---

<!-- ZH -->

# Guidance——Python 约束生成与可控输出

> Guidance 用 Python 语法做约束生成（regex、候选集选择、语法约束），让输出更可控。`pip install guidance` 后可接 Transformers 等多种后端。

## 快速使用

1. 安装：
   ```bash
   pip install guidance
   ```
2. 运行：
   ```bash
   python -c "import guidance; print('guidance installed')"
   ```
3. 验证：
   - Run a constrained `gen(regex=...)` and confirm the output matches the regex every time


---

## 简介

Guidance 用 Python 语法做约束生成（regex、候选集选择、语法约束），让输出更可控。`pip install guidance` 后可接 Transformers 等多种后端。

- **适合谁（Best for）:** 需要可控格式（ID、枚举、模板）的团队，希望获得比「尽量按要求输出」更强的约束保证
- **兼容工具（Works with）:** Python、Guidance 原语（`gen`/`select`）、Transformers/LlamaCpp/OpenAI 等后端（仓库说明）
- **安装时间（Setup time）:** 10 分钟


### 量化信息

- 安装命令：`pip install guidance`（仓库）
- 装机约 10 分钟
- GitHub stars（已核验）：见「来源与感谢」


---

## 实战要点

当你无法接受「格式不对」时，把 Guidance 当作安全层：先从简单约束开始（数字/ID 用 regex、枚举用 `select()`），再扩展到更复杂的语法约束。在 agent 流水线里，把约束放在边界之前：写 DB、调 API、构造工具参数、做路由决策之前最有价值。

**安全提示：** 约束会增加计算开销；通过缩小语法/聚焦 prompt 来控制延迟预算。

### FAQ

**Q: 什么是约束生成？**
A: 就是把模型输出限制在满足某个规则的集合里：例如必须匹配 regex、必须从候选列表中选、或遵循语法，从而减少不合法输出。

**Q: 必须用特定模型吗？**
A: 不需要。仓库提到多种后端；你按环境选择本地 Transformers、llama.cpp 或托管 API 即可。

**Q: 最适合用在哪？**
A: 任何需要可解析/可落库的环节：路由标签、ID、枚举、类 JSON 字段或严格模板输出。

---

## 来源与感谢

> GitHub：https://github.com/guidance-ai/guidance
> Owner avatar：https://avatars.githubusercontent.com/u/142035062?v=4
> 许可证（SPDX）：MIT
> GitHub stars（已通过 `api.github.com/repos/guidance-ai/guidance` 核验）：21,453


---
Source: https://tokrepo.com/en/workflows/guidance-constrained-generation-in-python
Author: Agent Toolkit