[feat] `bamlproject.toml` instead of `baml_src/`

[Elijas]

Use case

I use step-based prototyping (step 1, step2, etc.)
this makes prototypes super readable

Problem

however this means that I HAVE to always hold everything in baml_src, I think it's not as elegant once you start mixing baml files with the rest of the codebase (if you know what you're doing and why holding everything in a dedicated baml_src would still make most sense for most projects)

I do however understand the value of baml_src pattern, it makes browsing 3rd party baml projects really easy

Solution spec

1. Treat baml_src/ and */ the same if folder */ has */bamlproject.toml (the same way how pyproject.toml signifies the root of a python project instead of python_src/). Keep the file empty, or you can make it bamlproject.baml, where it would be included like any other baml file.
2. Ignore nested baml project folders (baml_src would ignore all baml_src/**/baml_src/ folders, and X folders where baml_src/**/X/bamlproject.toml)

(TL;DR all I'm asking is for VSCode support for this alternate convention)
(P.S. Now that I think about it, I could probably symlink a x/* folder to a gitignored .baml/baml_src/x/*, and VSCode should pick it up (?))

[linear]

BAML-394 [feat] `bamlproject.toml` instead of `baml_src/`

[aaronvg]

we really like this idea -- but we would probably just choose one approach and not 2. And the reason is that once you have more than 1 way of configuring things you start venturing into dangerous territory. But we could potentially help people initialize baml projects with the right baml_src delineation using a .toml file

[htxryan]

I love this idea! I am facing this problem right now, and am solving it in the meantime by shadow-copying from multiple directories into one (to avoid my root python app from having to be in one big "baml_src" directory). Works for my situation, but very hacky, so I would welcome a better solution!

[Elijas]

Note

I fully support keeping baml_src/ as a recommended convention for the name of the directory containing BAML files, just let's not have its presence be the discovery mechanism.

TL;DR Let's decouple the discovery mechanism from a fixed directory name

---

you have more than 1 way of configuring things you start venturing into dangerous territory.

This is a valid concern. However, with a clear auto-transition to a bamlproject.toml marker file and a defined deprecation timeline, the risk of persistent dual configurations (the "dangerous territory") is very low.

• Primary Discovery: Tools will primarily search for **/bamlproject.toml. The directory containing each bamlproject.toml will be treated as a BAML source root. All *.baml files within this directory (and its subdirectories) will be included.
• Legacy Fallback (Temporary): If during baml-cli generate tools encounter a baml_src/ directory that does not contain a bamlproject.toml file inside it, this baml_src/ directory will still be recognized as a BAML source root. Auto-migration will be initiated:
  • A one-time notification will inform the user of this auto-generation (if it fails for any reason, gracefully print a deprecation warning for cli, or show notification toast for vscode).
  • Automatically create an empty bamlproject.toml file inside that baml_src/ directory (i.e., at path/to/baml_src/bamlproject.toml).
  • The generated .toml file will be empty of directives but contain a comment explaining its purpose:

# This file marks this directory as a BAML source root.
#
# It was automatically generated to ensure compatibility with future BAML versions,
# which will rely on 'bamlproject.toml' for discovering BAML files.
# All '*.baml' files in this directory and its subdirectories are included.

• Final Deprecation (e.g., 24 months from now, or with BAML v1.0):
  • The legacy fallback for baml_src/ directories without an internal bamlproject.toml will be removed.
  • Tools will only discover BAML source roots by looking for **/bamlproject.toml.

---

P.S. FAQ
Q: Why use the .toml file extension?
A: It's a simple marker now, but .toml is chosen so future features (like linter settings) can be added easily, without the BAML team needing to introduce a new config system.

[hellovai]

+1 on this! we've talked about this internally and are actually already aligned here. We think this is way :)