ContextQMD
Back to Baml

Python

fern/01-guide/02-languages/python.mdx

0.222.06.2 KB
Original Source

<Note>You can check out this repo: https://github.com/BoundaryML/baml-examples/tree/main/python-fastapi-starter</Note>

To set up BAML with Python do the following:

<Steps> ### Install BAML VSCode/Cursor Extension https://marketplace.visualstudio.com/items?itemName=boundary.baml-extension 
  - syntax highlighting
  - testing playground
  - prompt previews

  <Tip>
  In your VSCode User Settings, highly recommend adding this to get better autocomplete for python in general, not just BAML.

  ```json
  {
    "python.analysis.typeCheckingMode": "basic"
  }
  ```
  </Tip>

Install BAML

  <Tabs>
    <Tab title="pip" language="pip">
      ```bash pip
      pip install baml-py
      ```
    </Tab>

    <Tab title="poetry" language="poetry">
      ```bash poetry
      poetry add baml-py
      ```
    </Tab>

    <Tab title="uv" language="uv">
      ```bash uv
      uv add baml-py
      ```
    </Tab>
  </Tabs>

Add BAML to your existing project

  This will give you some starter BAML code in a `baml_src` directory.

  <Tabs>
    <Tab title="pip" language="pip">
      ```bash pip
      baml-cli init
      ```
    </Tab>

    <Tab title="poetry" language="poetry">
      ```bash poetry
      poetry run baml-cli init
      ```
    </Tab>

    <Tab title="uv" language="uv">
      ```bash uv
      uv run baml-cli init
      ```
    </Tab>
  </Tabs>

Generate the baml_client python module from .baml files

One of the files in your baml_src directory will have a generator block. The next commmand will auto-generate the baml_client directory, which will have auto-generated python code to call your BAML functions.

Any types defined in .baml files will be converted into Pydantic models in the baml_client directory.

  <Tabs>
    <Tab title="pip" language="pip">
      ```bash pip
      baml-cli generate
      ```
    </Tab>

    <Tab title="poetry" language="poetry">
      ```bash poetry
      poetry run baml-cli generate
      ```
    </Tab>

    <Tab title="uv" language="uv">
      ```bash uv
      uv run baml-cli generate
      ```
    </Tab>
  </Tabs>

  See [What is baml_client](/guide/introduction/baml_client) to learn more about how this works.


<Tip>
  If you set up the [VSCode extension](https://marketplace.visualstudio.com/items?itemName=Boundary.baml-extension), it will automatically run `baml-cli generate` on saving a BAML file.
</Tip>

Use a BAML function in Python!

<Error>If `baml_client` doesn't exist, make sure to run the previous step! </Error>

  <Tabs>
  <Tab title="Sync" language="python">
  ```python main.py 
  from baml_client.sync_client import b
  from baml_client.types import Resume

  def example(raw_resume: str) -> Resume: 
    # BAML's internal parser guarantees ExtractResume
    # to be always return a Resume type
    response = b.ExtractResume(raw_resume)
    return response

  def example_stream(raw_resume: str) -> Resume:
    stream = b.stream.ExtractResume(raw_resume)
    for msg in stream:
      print(msg) # This will be a PartialResume type
    
    # This will be a Resume type
    final = stream.get_final_response()

    return final
  ```
  </Tab>

  <Tab title="Async" language="python">
  ```python async_main.py
  from baml_client.async_client import b
  from baml_client.types import Resume

  async def example(raw_resume: str) -> Resume: 
    # BAML's internal parser guarantees ExtractResume
    # to be always return a Resume type
    response = await b.ExtractResume(raw_resume)
    return response

  async def example_stream(raw_resume: str) -> Resume:
    stream = b.stream.ExtractResume(raw_resume)
    async for msg in stream:
      print(msg) # This will be a PartialResume type
    
    # This will be a Resume type
    final = await stream.get_final_response()

    return final
  ```
  </Tab>
  </Tabs>
</Steps>

BAML with Jupyter Notebooks

You can use the baml_client in a Jupyter notebook.

One of the common problems is making sure your code changes are picked up by the notebook without having to restart the whole kernel (and re-run all the cells)

To make sure your changes in .baml files are reflected in your notebook you must do these steps:

<Steps> ### Setup the autoreload extension
python
%load_ext autoreload
%autoreload 2

This will make sure to reload imports, such as baml_client's "b" object before every cell runs.

Import baml_client module in your notebook

Note it's different from how we import in python.

python
# Assuming your baml_client is inside a dir called app/
import app.baml_client as client # you can name this "llm" or "baml" or whatever you want

Usually we import things as from baml_client import b, and we can call our functions using b, but the %autoreload notebook extension does not work well with from...import statements.

Call BAML functions using the module name as a prefix

python
raw_resume = "Here's some resume text"
client.b.ExtractResume(raw_resume)

Now your changes in .baml files are reflected in your notebook automatically, without needing to restart the Jupyter kernel.

<Note> If you want to keep using the `from baml_client import b` style, you'll just need to re-import it everytime you regenerate the baml_client. </Note> <Warning> Pylance will complain about any schema changes you make in .baml files. You can ignore these errors. If you want it to pick up your new types, you'll need to restart the kernel. This auto-reload approach works best if you're only making changes to the prompts. </Warning> </Steps>

You're all set! Continue on to the Deployment Guides for your language to learn how to deploy your BAML code or check out the Interactive Examples to see more examples.