feat: move REST API out of preview (#1818)

Fix #1765 
<!-- ELLIPSIS_HIDDEN -->

----

> [!IMPORTANT]
> Removes `--preview` flag from BAML CLI, stabilizing REST API, and
updates related documentation, tests, and build scripts.
> 
>   - **Behavior**:
> - Removes `--preview` flag from `DevArgs` in `dev.rs` and `ServeArgs`
in `serve/mod.rs`, making REST API stable by default.
> - Removes associated warnings and error messages related to the
`--preview` flag in `dev.rs` and `serve/mod.rs`.
>   - **Documentation**:
> - Updates `dev.mdx` and `serve.mdx` to remove references to the
`--preview` flag and preview warnings.
>   - **Testing**:
> - Adds a print statement in `test_streaming()` in `test_functions.py`
for debugging.
>   - **Dependencies**:
>     - Adds `types-assertpy` to `uv.lock` for type checking in tests.
>   - **Build Script**:
> - Updates `tools/build` to run specific tests in `test_functions.py`
when in test mode.
> 
> <sup>This description was created by </sup>[<img alt="Ellipsis"
src="https://img.shields.io/badge/Ellipsis-blue?color=175173">](https://www.ellipsis.dev?ref=BoundaryML%2Fbaml&utm_source=github&utm_medium=referral)<sup>
for d176229. You can
[customize](https://app.ellipsis.dev/BoundaryML/settings/summaries) this
summary. It will automatically update as commits are pushed.</sup>

<!-- ELLIPSIS_HIDDEN -->

Author: sxlijin

engine/baml-runtime/src/cli/dev.rs

@@ -14,41 +14,10 @@ pub struct DevArgs {
     pub from: PathBuf,
     #[arg(long, help = "port to expose BAML on", default_value = "2024")]
     port: u16,
-    #[arg(long, help = "turn on preview features", default_value = "false")]
-    preview: bool,
 }
 
 impl DevArgs {
     pub fn run(&self, defaults: crate::RuntimeCliDefaults) -> Result<()> {
-        if !self.preview {
-            log::warn!(
-                r#"Development mode is a preview feature.
-                
-Please run with --preview, like so:
-
-    {} dev --preview
-
-Please provide feedback and let us know if you run into any issues:
-
-    - join our Discord at https://docs.boundaryml.com/discord, or
-    - comment on https://github.com/BoundaryML/baml/issues/892
-
-We expect to stabilize this feature over the next few weeks, but we need
-your feedback to do so.
-
-Thanks for trying out BAML!
-"#,
-                if matches!(
-                    std::env::var("npm_lifecycle_event").ok().as_deref(),
-                    Some("npx")
-                ) {
-                    "npx @boundaryml/baml"
-                } else {
-                    "baml-cli"
-                }
-            );
-            anyhow::bail!("--preview is not set")
-        }
         baml_log::info!("Starting BAML development server on port {}", self.port);
 
         let t = BamlRuntime::get_tokio_singleton()?;
@@ -75,21 +44,6 @@ Thanks for trying out BAML!
 
         // print all events and errors
         t.block_on(async {
-            log::warn!(
-                r#"Development mode is a preview feature.
-
-Please provide feedback and let us know if you run into any issues:
-
-    - join our Discord at https://docs.boundaryml.com/discord, or
-    - comment on https://github.com/BoundaryML/baml/issues/892
-
-We expect to stabilize this feature over the next few weeks, but we need
-your feedback to do so.
-
-Thanks for trying out BAML!
-"#
-            );
-
             for result in rx {
                 match result {
                     Ok(events) => {

engine/baml-runtime/src/cli/serve/mod.rs

@@ -47,8 +47,6 @@ pub struct ServeArgs {
     pub from: PathBuf,
     #[arg(long, help = "port to expose BAML on", default_value = "2024")]
     port: u16,
-    #[arg(long, help = "turn on preview features", default_value = "false")]
-    preview: bool,
     #[arg(
         long,
         help = "Generate baml_client without checking for version mismatch",
@@ -64,51 +62,6 @@ pub struct BamlOptions {
 
 impl ServeArgs {
     pub fn run(&self) -> Result<()> {
-        if !self.preview {
-            log::warn!(
-                r#"BAML-over-HTTP API is a preview feature.
-
-Please run with --preview, like so:
-
-    {} serve --preview
-
-Please provide feedback and let us know if you run into any issues:
-
-    - join our Discord at https://docs.boundaryml.com/discord, or
-    - comment on https://github.com/BoundaryML/baml/issues/892
-
-We expect to stabilize this feature over the next few weeks, but we need
-your feedback to do so.
-
-Thanks for trying out BAML!
-"#,
-                if matches!(
-                    std::env::var("npm_lifecycle_event").ok().as_deref(),
-                    Some("npx")
-                ) {
-                    "npx @boundaryml/baml"
-                } else {
-                    "baml-cli"
-                }
-            );
-            anyhow::bail!("--preview is not set")
-        }
-
-        log::warn!(
-            r#"BAML-over-HTTP is a preview feature.
-
-Please provide feedback and let us know if you run into any issues:
-
-    - join our Discord at https://docs.boundaryml.com/discord, or
-    - comment on https://github.com/BoundaryML/baml/issues/892
-
-We expect to stabilize this feature over the next few weeks, but we need
-your feedback to do so.
-
-Thanks for trying out BAML!
-"#
-        );
-
         let t: Arc<tokio::runtime::Runtime> = BamlRuntime::get_tokio_singleton()?;
 
         let (server, tcp_listener) = t.block_on(Server::new(self.from.clone(), self.port))?;
@@ -229,7 +182,7 @@ impl Server {
         };
 
         if !password.starts_with("sk-baml") {
-            log::warn!("We recommend using BAML_PASSWORD=sk-baml-... so that static analysis tools can detect if you accidentally commit and push your password.")
+            baml_log::warn!("We recommend using BAML_PASSWORD=sk-baml-... so that static analysis tools can detect if you accidentally commit and push your password.")
         }
 
         if let Some(XBamlApiKey(baml_api_key)) = baml_api_key {

fern/03-reference/baml-cli/dev.mdx

@@ -1,17 +1,12 @@
-The `dev` command starts a development server that watches your BAML source files for changes and automatically reloads the BAML runtime. This feature is designed to streamline the development process by providing real-time updates as you modify your BAML configurations.
-
-
-<Warning>
-  **Warning: Preview Feature**
-  
-  1. You must include the `--preview` flag when running the `dev` command.
-  2. Be aware that this feature is still being stabilized and may change in future releases.
-</Warning>
+The `dev` command starts a development server that watches your BAML source
+files for changes and automatically reloads the BAML runtime. This feature is
+designed to streamline the development process by providing real-time updates as
+you modify your BAML configurations.
 
 ## Usage
 
 ```
-baml-cli dev [OPTIONS] --preview
+baml-cli dev [OPTIONS]
 ```
 
 ## Details

fern/03-reference/baml-cli/serve.mdx

@@ -1,22 +1,18 @@
-The `serve` command starts a BAML-over-HTTP API server that exposes your BAML functions via HTTP endpoints. This feature allows you to interact with your BAML functions through a RESTful API interface.
-
-<Warning>
-  **Warning: Preview Feature**
-  
-  1. You must include the `--preview` flag when running the `dev` command.
-  2. Be aware that this feature is still being stabilized and may change in future releases.
-</Warning>
+The `serve` command starts a BAML-over-HTTP API server that exposes your BAML
+functions via HTTP endpoints. This feature allows you to interact with your BAML
+functions through a RESTful API interface.
 
 ## Usage
 
 ```
-baml-cli serve [OPTIONS] --preview
+baml-cli serve [OPTIONS]
 ```
 
 <Tip>
-If you're actively developing, you can use the `dev` command to include hotreload functionality:
+If you're actively developing, you can use the `dev` command to include
+hot-reload functionality:
 ```
-baml-cli dev [OPTIONS] --preview
+baml-cli dev [OPTIONS]
 ```
 
 [See more](./dev)
@@ -29,7 +25,6 @@ baml-cli dev [OPTIONS] --preview
 | `--from <PATH>` | Path to the `baml_src` directory | `./baml_src` |
 | `--port <PORT>` | Port to expose BAML on | `2024` |
 | `--no-version-check` | Generate `baml_client` without checking for version mismatch | `false` |
-| `--preview` | Enable the preview feature | |
 
 ## Description
 
@@ -41,14 +36,43 @@ The `serve` command performs the following actions:
 ## Endpoints
 
 
-- `POST /call/:function_name`: Call a BAML function
+`POST /call/:function_name`: Call a BAML function
+
+```bash curl
+curl \
+  -X POST \
+  "http://localhost:2024/call/MyFunctionName" \
+  -H "Content-Type: application/json" \
+  -d '{"arg1": "value1", "arg2": "value2"}'
+```
+
+`POST /stream/:function_name`: Stream results from a BAML function
+
+```bash curl
+curl \
+  -X POST \
+  "http://localhost:2024/stream/MyFunctionName" \
+  -H "Content-Type: application/json" \
+  -d '{"arg1": "value1", "arg2": "value2"}'
+```
 
 **Debugging**
 - `GET /docs`: Interactive API documentation (Swagger UI)
 - `GET /openapi.json`: OpenAPI specification for the BAML functions
 - `GET /_debug/ping`: Health check endpoint
 - `GET /_debug/status`: Server status and authentication check
 
+## Stability
+
+`baml-cli serve` is currently in Tier 2 stability. This means that the CLI and
+the HTTP APIs are stable, but there are a number of features which are
+not yet available:
+
+   - the [TypeBuilder API](/ref/baml_client/type-builder)
+   - the [Collector API](/guide/baml-advanced/collector-track-tokens)
+   - the [Modular API](/guide/baml-advanced/modular-api)
+   - custom trace annotations for [Boundary Studio](/guide/boundary-cloud/observability/tracking-usage)
+
 ## Authentication
 
 We support the header: `x-baml-api-key`
@@ -78,12 +102,19 @@ To test the server, you can use the following `curl` commands:
 
 2. Call a function:
    ```bash
-   curl -X POST http://localhost:2024/call/MyFunctionName -d '{"arg1": "value1", "arg2": "value2"}'
+   curl -X POST \
+      http://localhost:2024/call/MyFunctionName \
+      -H "Content-Type: application/json" \
+      -d '{"arg1": "value1", "arg2": "value2"}'
    ```
 
    ```bash API Key
-    curl -X POST http://localhost:2024/call/MyFunctionName -H "x-baml-api-key: ${BAML_PASSWORD}" -d '{"arg1": "value1", "arg2": "value2"}'
-    ```
+   curl -X POST \
+      http://localhost:2024/call/MyFunctionName \
+      -H "Content-Type: application/json" \
+      -H "x-baml-api-key: ${BAML_PASSWORD}" \
+      -d '{"arg1": "value1", "arg2": "value2"}'
+   ```
 
 3. Access the API documentation:
    Open `http://localhost:2024/docs` in your web browser.

integ-tests/python/tests/test_functions.py

@@ -628,6 +628,7 @@ async def test_streaming():
     last_msg_time = start_time
     first_msg_time = start_time + 10
     async for msg in stream:
+        print("stream event", msg)
         msgs.append(str(msg))
         if len(msgs) == 1:
             first_msg_time = asyncio.get_event_loop().time()

integ-tests/python/uv.lock

@@ -194,8 +194,9 @@ case "$_path" in
     command="${command} && uv run baml-cli generate --from ${_repo_root}/integ-tests/baml_src"
     if [ "$_test_mode" -eq 1 ]; then
       #command="${command} && BAML_LOG=trace infisical run --env=test -- uv run python baml_example_tracing.py"
-      # command="${command} && BAML_LOG=debug,baml_runtime=trace infisical run --env=test -- uv run pytest -s tests/test_functions.py::test_should_work_with_image_url"
-      command="${command} && BAML_LOG=info infisical run --env=test -- uv run pytest"
+      # command="${command} && BAML_LOG=debug,baml_runtime=trace infisical run --env=test -- uv run pytest -s tests/test_functions.py::test_streaming"
+      command="${command} && BAML_LOG=debug,baml_runtime=trace  uv run pytest -s tests/test_functions.py::test_streaming"
+      # command="${command} && BAML_LOG=info infisical run --env=test -- uv run pytest"
     fi
     if [ "$_watch_mode" -eq 1 ]; then
       npx nodemon \