BEP — BAML Enhancement Proposals

BEPs are design proposals for evolving the BAML language and core tooling.

Below is an auto-generated index of all BEPs.

⚠️ Do not edit the table below by hand. Run the BEP update script instead (see instructions at the bottom).

Status	Meaning
	Work in progress, not ready for review
	Ready for review and discussion
	Approved for implementation
	Feature is live in BAML
	Decided against
	Replaced by another BEP

<table> <thead> <tr> <th>BEP</th> </tr> </thead> <tbody> <tr> <td><a href="./proposals/BEP-001-exceptions/"><strong>BEP-001</strong>: Exception Handling</a>  

<span style='font-size:0.8em; color:gray'>Shepherd(s): Vaibhav Gupta [email protected]</span></td> </tr> <tr> <td><a href="./proposals/BEP-002-match/"><strong>BEP-002</strong>: match</a>

<span style='font-size:0.8em; color:gray'>Shepherd(s): hellovai [email protected], rossirpaulo [email protected]</span></td> </tr> <tr> <td><a href="./proposals/BEP-005-prompt-optimization/"><strong>BEP-005</strong>: Prompt Optimization</a>

baml-cli supports a new command called optimize that writes and improves prompts for you, similar to DSPy. - Prompt optimization attempts to maximize the number of passing BAML test cases, and optionally minimize tokens and latency. - The optimizer is based on the GEPA algorithm, which is partially encoded as BAML functions that you can tweak.

<span style='font-size:0.8em; color:gray'>Shepherd(s): Greg Hale [email protected]</span></td> </tr> <tr> <td><a href="./proposals/BEP-006-compiler-errors/"><strong>BEP-006</strong>: compiler-errors</a>

Uniform user-facing experience for compiler errors.

<span style='font-size:0.8em; color:gray'>Shepherd(s): Greg Hale [email protected]</span></td> </tr> <tr> <td><a href="./proposals/BEP-007-mir/"><strong>BEP-007</strong>: Mid-level Intermediate Representation (MIR)</a>

This proposal introduces a Mid-level Intermediate Representation (MIR) between THIR and bytecode generation in the BAML compiler pipeline. MIR is a Control Flow Graph (CFG) based representation that simplifies the compilation of complex control flow constructs like match statements and error handling (catch expressions). By lowering high-level constructs into basic blocks connected by explicit jumps, MIR bridges the semantic gap between the tree-structured THIR and the linear bytecode, making codegen simpler, more maintainable, and easier to extend with new language features.

<span style='font-size:0.8em; color:gray'>Shepherd(s): Antonio Sarosi [email protected]</span></td> </tr>

</tbody> </table>

Management

Scripts are self-contained Python scripts using uv. Ensure uv is installed.

Creating a new BEP

To create a new proposal:

bash

mise run bep:new -- "Feature Name"

This will:

Create a new directory beps/BEP-XXX-feature-name/
Create a README.md template inside it with the next available BEP ID.

Updating the Index

After modifying any BEP, update this README table:

bash

mise run bep:readme

Managing BEPs

To update a BEP's status or timestamp:

Touch (Update Timestamp):

bash

mise run bep:update 001
# OR
mise run bep:update BEP-001-exceptions

Change Status:

bash

mise run bep:update 001 --status Proposed

(Valid statuses: Draft, Proposed, Accepted, Implemented, Rejected, Superseded)