feat(ai): builtin ai/provider packages + @spec desugar for LLM functions

baml_language/.cargo/size-gate.toml

@@ -55,14 +55,17 @@ max_file_bytes = "22.5 MiB"
 kind = "pack"
 policy.max_delta_pct = 3.0
 
+# Bumped ~3% above the Aug 2026 baselines when the builtin ai/provider
+# stdlib packages landed (PR #4352): the packed program carries their
+# bytecode (~700 KB).
 [artifacts.packed-program.platform.aarch64-apple-darwin]
-max_file_bytes = "13.6 MiB"
+max_file_bytes = "14.3 MiB"
 
 [artifacts.packed-program.platform.x86_64-unknown-linux-gnu]
-max_file_bytes = "17.4 MiB"
+max_file_bytes = "18.3 MiB"
 
 [artifacts.packed-program.platform.x86_64-pc-windows-msvc]
-max_file_bytes = "14.5 MiB"
+max_file_bytes = "15.3 MiB"
 
 [artifacts.packed-program.pack]
 cli_package = "baml_cli"

baml_language/.ci/size-gate/aarch64-apple-darwin.toml

@@ -8,5 +8,5 @@ stripped_bytes = "20.3 MiB"
 gzip_bytes = "9.7 MiB"
 
 [artifacts.packed-program]
-file_bytes = "13.2 MiB"
-gzip_bytes = "6.1 MiB"
+file_bytes = "13.8 MiB"
+gzip_bytes = "6.3 MiB"

baml_language/.ci/size-gate/x86_64-pc-windows-msvc.toml

@@ -8,5 +8,5 @@ stripped_bytes = "21.9 MiB"
 gzip_bytes = "9.9 MiB"
 
 [artifacts.packed-program]
-file_bytes = "14.1 MiB"
-gzip_bytes = "6.2 MiB"
+file_bytes = "14.8 MiB"
+gzip_bytes = "6.4 MiB"

baml_language/.ci/size-gate/x86_64-unknown-linux-gnu.toml

@@ -8,5 +8,5 @@ stripped_bytes = "26.1 MiB"
 gzip_bytes = "11.1 MiB"
 
 [artifacts.packed-program]
-file_bytes = "16.9 MiB"
-gzip_bytes = "7.0 MiB"
+file_bytes = "17.7 MiB"
+gzip_bytes = "7.2 MiB"

baml_language/crates/baml_base/src/core_types.rs

@@ -180,7 +180,7 @@ impl TypePath {
         Self(vec![name])
     }
 
-    /// Build a `TypePath` from a compile-time dotted literal like `"baml.llm.Client"`.
+    /// Build a `TypePath` from a compile-time dotted literal like `"ai.Prompt"`.
     /// Use only at synthetic construction sites; runtime input should come from
     /// already-segmented data (e.g., parser tokens).
     pub fn from_dotted(s: &str) -> Self {

baml_language/crates/baml_base/src/qualified_name.rs

@@ -12,7 +12,7 @@ use crate::Name;
 /// Prefix used for standard library items in qualified names.
 ///
 /// All `Namespace::BamlStd` and standard `Namespace::Builtin` items
-/// are displayed with this prefix (e.g., `baml.llm.call_llm_function`).
+/// are displayed with this prefix (e.g., `baml.prompt.render_output_format`).
 pub const BAML_STD_PREFIX: &str = "baml.";
 
 /// FQN (as a display string) of the recursive `json` type alias defined in
@@ -22,6 +22,14 @@ pub const BAML_STD_PREFIX: &str = "baml.";
 /// recursion for output-format rendering, SAP streaming, and Python codegen.
 pub const BAML_JSON_JSON: &str = "baml.json.json";
 
+/// Canonical host-facing typed AI stream. Compiler synthesis, engine handle
+/// lifting, and SDK generators must share this identity rather than carrying
+/// independent string literals.
+pub const AI_STREAM_STREAM: &str = "ai.stream.Stream";
+
+/// Canonical nominal end-of-stream marker used by AI streams.
+pub const AI_STREAM_DONE: &str = "ai.stream.Done";
+
 /// A qualified name that unambiguously identifies an item.
 ///
 /// Combines a namespace (where the item lives) with a name (what the item

baml_language/crates/baml_builtins2/baml_std/ai/journal.baml

@@ -0,0 +1,33 @@
+// The Journal: the append-only typed record of one run.
+//
+// The event types themselves live in root.events, and the content blocks they
+// carry live in root.content. Journal stays at the package root because it is
+// one of the nine names the BEP's flow diagram names directly.
+//
+// Mirrors _planv2/pages/02_guides/04_the_journal.md.
+
+// The COMPLETE record. Repair attempts, feedback, failures — everything that
+// happened is an event.
+class Journal {
+    log: root.events.Event[],
+
+    function entries(self) -> root.events.Event[] {
+        self.log
+    }
+
+    // A journal for one run of a spec, with RunStarted appended.
+    function new<Out>(spec: FunctionSpec<Out>) -> Journal {
+        Journal {
+            log: [
+                root.events.RunStarted { spec_name: spec.name(), arguments: spec.arguments() },
+            ],
+        }
+    }
+
+    // The driving runner is the only writer; clients and tools never append.
+    function append_all(self, events: root.events.Event[]) -> void {
+        for (let e in events) {
+            self.log.push(e);
+        }
+    }
+}

baml_language/crates/baml_builtins2/baml_std/ai/ns_clients/clients.baml

@@ -0,0 +1,190 @@
+// Reliability composes at the client boundary: wrapper clients.
+// Mirrors _planv2/pages/02_guides/03_clients/04_reliability.md.
+
+// The default judgment: a request the provider rejected does not become
+// valid by resending.
+function default_retry_judgment(f: root.errors.Failure) -> bool {
+    match (f) {
+        let r: root.errors.Refused => false,
+        let i: root.errors.InvalidRequest => false,
+        let p: root.errors.ParseFailed => false,
+        _ => true,
+    }
+}
+
+class Backoff {
+    initial_ms: int,
+    multiplier: int,
+    max_ms: int,
+
+    function new(initial_ms: int = 250, multiplier: int = 2, max_ms: int = 10000) -> Backoff {
+        Backoff { initial_ms: initial_ms, multiplier: multiplier, max_ms: max_ms }
+    }
+
+    // The delay before attempt N (first retry is attempt 1). A
+    // root.errors.RateLimited.retry_after_ms hint overrides the computed value.
+    function delay_ms(self, attempt: int, f: root.errors.Failure) -> int {
+        let hinted = match (f) {
+            let r: root.errors.RateLimited => r.retry_after_ms,
+            _ => null,
+        };
+        if let h: int = hinted {
+            h
+        } else {
+            let d = self.initial_ms;
+            let i = 1;
+            while (i < attempt) {
+                d = d * self.multiplier;
+                i = i + 1;
+            }
+            if (d > self.max_ms) {
+                self.max_ms
+            } else {
+                d
+            }
+        }
+    }
+}
+
+class Retry {
+    inner: root.Client,
+    max_attempts: int,
+    retry_if: (root.errors.Failure) -> bool throws never,
+    backoff: Backoff,
+
+    function new(
+        inner: root.Client,
+        max_attempts: int = 3,
+        retry_if: ((root.errors.Failure) -> bool throws never)? = null,
+        backoff: Backoff? = null,
+    ) -> Retry {
+        Retry {
+            inner: inner,
+            max_attempts: max_attempts,
+            retry_if: retry_if ?? default_retry_judgment,
+            backoff: backoff ?? Backoff.new(),
+        }
+    }
+
+    function _attempt(self, input: root.ModelTurnInput, remaining: int) -> root.ModelTurn {
+        self.inner.invoke(input) catch_all (e) {
+            let f: root.errors.Failure => {
+                // the safety gate is not overridable; the judgment is
+                if (
+                    remaining > 1
+                        && f.retry_safety() == root.errors.RetrySafety.Safe
+                        && self.retry_if(f)
+                ) {
+                    let attempt = self.max_attempts - remaining + 1;
+                    let _ = baml.sys.sleep(
+                        baml.time.Duration.from_milliseconds(self.backoff.delay_ms(attempt, f)),
+                    ) catch_all (se) {
+                        _ => null,
+                    };
+                    self._attempt(input, remaining - 1)
+                } else {
+                    throw e
+                }
+            },
+            _ => throw e, // untyped failures are never retried
+        }
+    }
+
+    implements root.Client {
+        function id(self) -> string {
+            self.inner.id()
+        }
+
+        function invoke(self, input: root.ModelTurnInput) -> root.ModelTurn {
+            self._attempt(input, self.max_attempts) catch_all (e) {
+                _ => throw root.errors.normalize(e),
+            }
+        }
+    }
+}
+
+// Rotates invocations across members. Replaces the legacy round-robin
+// provider: distribution is a client-boundary concern, exactly like Retry
+// and Fallback. The counter mutates on the shared value, so every call
+// site holding this client participates in one rotation.
+class RoundRobin {
+    members: root.Client[],
+    counter: int,
+
+    function new(members: root.Client[]) -> RoundRobin {
+        if (members.length() == 0) {
+            throw baml.errors.InvalidArgument { message: "RoundRobin needs at least one member" }
+        }
+        RoundRobin { members: members, counter: 0 }
+    }
+
+    implements root.Client {
+        function id(self) -> string {
+            if let c: root.Client = self.members.at(0) {
+                c.id()
+            } else {
+                "round-robin"
+            }
+        }
+
+        function invoke(self, input: root.ModelTurnInput) -> root.ModelTurn {
+            {
+                let index = self.counter % self.members.length();
+                self.counter = self.counter + 1;
+                match (self.members.at(index)) {
+                    let c: root.Client => c.invoke(input),
+                    null => {
+                        throw baml.errors.InvalidArgument { message: "RoundRobin needs at least one member" }
+                    },
+                }
+            } catch_all (e) {
+                _ => throw root.errors.normalize(e),
+            }
+        }
+    }
+}
+
+class Fallback {
+    members: root.Client[],
+
+    function _try(self, input: root.ModelTurnInput, index: int) -> root.ModelTurn {
+        match (self.members.at(index)) {
+            let c: root.Client => {
+                c.invoke(input) catch_all (e) {
+                    let f: root.errors.Failure => {
+                        if (
+                            index + 1 < self.members.length()
+                                && f.retry_safety() == root.errors.RetrySafety.Safe
+                        ) {
+                            self._try(input, index + 1)
+                        } else {
+                            throw e
+                        }
+                    },
+                    _ => throw e,
+                }
+            },
+            null => {
+                throw baml.errors.InvalidArgument { message: "Fallback needs at least one member" }
+            },
+        }
+    }
+
+    implements root.Client {
+        function id(self) -> string {
+            // NOTE: `?.method()` on an interface-typed optional trips a VM bug;
+            // if-let is the reliable form.
+            if let c: root.Client = self.members.at(0) {
+                c.id()
+            } else {
+                "fallback"
+            }
+        }
+
+        function invoke(self, input: root.ModelTurnInput) -> root.ModelTurn {
+            self._try(input, 0) catch_all (e) {
+                _ => throw root.errors.normalize(e),
+            }
+        }
+    }
+}

baml_language/crates/baml_builtins2/baml_std/ai/ns_content/content.baml

@@ -0,0 +1,32 @@
+// Canonical assistant content: what a model turn produced, normalized away
+// from any one provider's envelope. Clients build these; the journal records
+// them inside root.events.AssistantMessage.
+//
+// Mirrors _planv2/pages/04_reference/01_api.md (the `ai.content` namespace).
+
+// A model turn is structured blocks, never a bare string and never an HTTP
+// envelope.
+class Text {
+    text: string,
+}
+
+class Reasoning {
+    summary: string,
+}
+
+class ToolUse {
+    id: string,
+    name: string,
+    args: map<string, unknown>,
+}
+
+type Block = Text | Reasoning | ToolUse;
+
+// Why the model stopped. `ToolUse` means the turn ended with tool calls the
+// runner must execute before the next turn.
+enum StopReason {
+    Complete,
+    ToolUse,
+    MaxTokens,
+    Refused,
+}