Before writing BAML, read the entirety of this tutorial to learn the general project structure

At a high level, you will define your AI prompts/interfaces in BAML files, which will then compile into generated Python (soon TS) code that you can use.

Here is the typical project structure:

├── baml_client/ # Generated code
├── baml_src/ # Prompts live here
│   ├── __tests__/ # Tests loaded by playground
│   │   └── YourAIFunction/
│   │       └── test_1.json
│   ├── main.baml
│   ├── any_directory/
│   │   └── baz.baml
│   └── foo.baml
# The rest of your project (not generated nor used by BAML)
├── app/
│  ├──
│  └──
├── pyproject.toml
└── poetry.lock

  1. baml_src is the directory where you write your BAML files with the AI function declarations, prompts, retry policies, etc. It also contains generator blocks which configure how and where to transpile your BAML code.
  2. baml_client is the directory where the generated python or TS client code lives. This is the code that you import into your python or TS program like this:
from baml_client import baml as b

await b.YourAIFunction()
  1. baml_src/__tests__/ are where your unit tests live. The .json files store the test inputs that can be loaded, deleted, created, and ran using the BAML VSCode extension. You can also write programmatic python/TS tests anywhere you like. See here for more information.

You should never edit any files inside baml_client directory as the whole directory gets regenerated on every baml build (auto runs on save if using the VSCode extension).

If you ever run into any issues with the generated code (like merge conflicts), you can always delete the baml_client directory and it will get regenerated automatically once you fix any other conflicts in your .baml files.


BAML by default has global imports. Every entity declared in any .baml file is available to all other .baml files under the same baml_src directory. You can have multiple baml_src directories, but no promises on how the VSCode extension will behave (yet).