A high-performance inference engine for AI models
Move in docs (#760)
uuuvn2828c792d52a
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex ac6ade3ca..11a77a5af 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -251,10 +251,10 @@ jobs:# ---------------------------------------------------------------# Commit + tag locally now, while the workspace only contains- # sync/build output. Publishes below write credential files and- # clone other repos into the workspace, which would otherwise be- # swept into `git add -A`. The push happens at the very end,- # after every publish step has succeeded.+ # sync/build output. Publishes below write credential files into+ # the workspace, which would otherwise be swept into `git add -A`.+ # The push happens at the very end, after every publish step has+ # succeeded.# ---------------------------------------------------------------- name: "Release: Commit and tag"run: |@@ -323,51 +323,6 @@ jobs:run: |uv publish workspace/release/python-pypi/*.whl- # ---------------------------------------------------------------- # Publish Docs- # ---------------------------------------------------------------- - name: "Publish Docs: Generate GitHub App token"- id: docs-token- uses: actions/create-github-app-token@v2- with:- app-id: ${{ vars.GH_APP_ID }}- private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}- owner: trymirai- repositories: docs-- - name: "Publish Docs: Checkout repo"- uses: actions/checkout@v6- with:- repository: trymirai/docs- ref: main- token: ${{ steps.docs-token.outputs.token }}- path: docs-repo- persist-credentials: false-- - name: "Publish Docs: Sync"- run: |- set -euo pipefail- rsync -a --delete \- --exclude '.git' --exclude '.git/*' \- workspace/release/docs/ docs-repo/snippets/generated/-- - name: "Publish Docs: Commit and push changes"- env:- GH_TOKEN: ${{ steps.docs-token.outputs.token }}- run: |- set -euo pipefail- cd docs-repo- git config user.name "github-actions[bot]"- git config user.email "github-actions[bot]@users.noreply.github.com"- git add -A- if git diff --staged --quiet; then- echo "No docs changes to commit"- else- git commit -m "Release ${VERSION}"- git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/trymirai/docs.git"- git push origin HEAD:main- fi-# ---------------------------------------------------------------# Push the release commit and tag now that every publish has# succeeded. The commit and tag were created locally before anydiff --git a/Cargo.lock b/Cargo.lockindex efea1730d..3a8203ce0 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -981,6 +981,7 @@ dependencies = ["heck","ignore","indexmap 2.14.0",+ "itertools 0.14.0","minijinja","regex","serde",@@ -988,6 +989,7 @@ dependencies = ["syn 2.0.118","toml 1.1.2+spec-1.1.0","toml_edit 0.25.12+spec-1.1.0",+ "walkdir",][[package]]diff --git a/crates/legacy/cli-tools/Cargo.toml b/crates/legacy/cli-tools/Cargo.tomlindex 527f1ea7d..c6e48e241 100644--- a/crates/legacy/cli-tools/Cargo.toml+++ b/crates/legacy/cli-tools/Cargo.toml@@ -15,6 +15,8 @@ path = "src/main.rs"[dependencies]clap.workspace = trueignore.workspace = true+itertools.workspace = true+walkdir.workspace = trueheck.workspace = truesyn.workspace = trueserde.workspace = truediff --git a/crates/legacy/cli-tools/src/configs/paths.rs b/crates/legacy/cli-tools/src/configs/paths.rsindex 5690eedf0..a2c7db74f 100644--- a/crates/legacy/cli-tools/src/configs/paths.rs+++ b/crates/legacy/cli-tools/src/configs/paths.rs@@ -107,10 +107,6 @@ impl Paths {self.release_workspace_path().join("platform")}- pub fn release_docs_path(&self) -> PathBuf {- self.release_workspace_path().join("docs")- }-pub fn release_binaries_path(&self) -> PathBuf {self.release_workspace_path().join("binaries")}diff --git a/crates/legacy/cli-tools/src/release/docs.rs b/crates/legacy/cli-tools/src/release/docs.rsdeleted file mode 100644index 348cab65f..000000000--- a/crates/legacy/cli-tools/src/release/docs.rs+++ /dev/null@@ -1,31 +0,0 @@-use std::fs;--use anyhow::Result;--use crate::configs::{Paths, PlatformsConfig};--pub fn stage_docs(- paths: &Paths,- platforms: &PlatformsConfig,-) -> Result<()> {- let examples_root = paths.release_docs_path().join("examples");- if examples_root.exists() {- fs::remove_dir_all(&examples_root)?;- }-- for (language, language_config) in &platforms.languages {- let language_dir = examples_root.join(language.name());- fs::create_dir_all(&language_dir)?;-- let source_root = paths.root_path.join(&language_config.examples_path);- for example_name in platforms.examples.keys() {- let converted_name = language.convert_file_name(example_name);- let source_path = source_root.join(format!("{converted_name}.{}", language.file_extension()));- let body = fs::read_to_string(&source_path)?;- let mdx = format!("```{}\n{}\n```\n", language.code_fence(), body.trim_end());- fs::write(language_dir.join(format!("{example_name}.mdx")), mdx)?;- }- }-- Ok(())-}diff --git a/crates/legacy/cli-tools/src/release/mod.rs b/crates/legacy/cli-tools/src/release/mod.rsindex 11ac9093b..63b72f39e 100644--- a/crates/legacy/cli-tools/src/release/mod.rs+++ b/crates/legacy/cli-tools/src/release/mod.rs@@ -1,5 +1,4 @@mod binaries;-mod docs;mod platform;mod version;@@ -36,7 +35,6 @@ pub fn run_release(version: &str) -> Result<()> {fs::create_dir_all(&release_path)?;platform::stage_platform(&paths, &platforms)?;- docs::stage_docs(&paths, &platforms)?;binaries::stage_binaries(&paths, &platforms)?;for language in platforms.languages.keys() {diff --git a/crates/legacy/cli-tools/src/sync/docs.rs b/crates/legacy/cli-tools/src/sync/docs.rsnew file mode 100644index 000000000..a534ff5ba--- /dev/null+++ b/crates/legacy/cli-tools/src/sync/docs.rs@@ -0,0 +1,66 @@+use std::{collections::BTreeSet, ffi::OsStr, fs, path::Path};++use anyhow::{Context, Result, anyhow};+use itertools::Itertools;+use walkdir::WalkDir;++use crate::configs::PlatformsConfig;++pub fn sync_docs(+ platforms: &PlatformsConfig,+ root_path: &Path,+ check: bool,+) -> Result<()> {+ let examples_root = root_path.join("docs").join("snippets").join("generated").join("examples");++ let mut existing: BTreeSet<_> = if examples_root.exists() {+ WalkDir::new(&examples_root)+ .into_iter()+ .map(|entry| entry.map(|entry| entry.into_path()))+ .filter_ok(|path| path.is_file() && path.file_name() != Some(OsStr::new(".DS_Store")))+ .try_collect()?+ } else {+ BTreeSet::new()+ };++ let mut check_errors = Vec::new();++ for language in platforms.languages.keys() {+ let source_root = platforms.examples_path_for_language(*language)?;+ for example_name in platforms.examples.keys() {+ let converted_name = language.convert_file_name(example_name);+ let source_path = source_root.join(format!("{converted_name}.{}", language.file_extension()));+ let body = fs::read_to_string(&source_path)+ .with_context(|| format!("Failed to read example: {}", source_path.display()))?;+ let mdx = format!("```{}\n{}\n```\n", language.code_fence(), body.trim_end());+ let path = examples_root.join(language.name()).join(format!("{example_name}.mdx"));++ if check {+ if !existing.remove(&path) {+ check_errors.push(format!("Missing generated docs snippet: {}", path.display()));+ } else if fs::read_to_string(&path)? != mdx {+ check_errors.push(format!("The file is out of sync: {}", path.display()));+ }+ } else {+ existing.remove(&path);+ if let Some(parent) = path.parent() {+ fs::create_dir_all(parent)?;+ }+ fs::write(&path, mdx)?;+ }+ }+ }++ if check {+ check_errors.extend(existing.iter().map(|path| format!("Stale generated docs snippet: {}", path.display())));+ if !check_errors.is_empty() {+ return Err(anyhow!("Docs snippets are out of sync:\n{}", check_errors.join("\n")));+ }+ } else {+ for path in existing {+ fs::remove_file(path)?;+ }+ }++ Ok(())+}diff --git a/crates/legacy/cli-tools/src/sync/mod.rs b/crates/legacy/cli-tools/src/sync/mod.rsindex f6fb96cf5..60dbb8306 100644--- a/crates/legacy/cli-tools/src/sync/mod.rs+++ b/crates/legacy/cli-tools/src/sync/mod.rs@@ -1,5 +1,6 @@use std::path::Path;+mod docs;mod jsr;mod license;mod package_json;@@ -96,5 +97,7 @@ pub fn run_sync(check: bool) -> Result<()> {PlaygroundSyncTask.run(&platforms, &workspace, &root_path.join("apps/playground/Project.swift"), check)?;+ docs::sync_docs(&platforms, root_path, check)?;+Ok(())}diff --git a/docs/docs.json b/docs/docs.jsonnew file mode 100644index 000000000..437b25657--- /dev/null+++ b/docs/docs.json@@ -0,0 +1,84 @@+{+ "$schema": "https://mintlify.com/docs.json",+ "theme": "mint",+ "name": "Mirai Docs",+ "colors": {+ "primary": "#0A0A0A",+ "light": "#FCFCFC",+ "dark": "#0A0A0A"+ },+ "favicon": "/favicon.png",+ "navigation": {+ "groups": [+ {+ "group": "Overview",+ "pages": [+ "index"+ ]+ },+ {+ "group": "Quick start",+ "pages": [+ "quick-start/chat",+ "quick-start/chat-cloud",+ "quick-start/chat-structured-output"+ ]+ }+ ],+ "global": {+ "anchors": [+ {+ "anchor": "GitHub",+ "href": "https://github.com/trymirai",+ "icon": "github"+ },+ {+ "anchor": "Community",+ "href": "https://discord.com/invite/trymirai",+ "icon": "discord"+ },+ {+ "anchor": "Blog",+ "href": "https://trymirai.com/blog",+ "icon": "newspaper"+ }+ ]+ }+ },+ "navbar": {+ "links": [+ {+ "label": "Write Us",+ "href": "mailto:[email protected]"+ }+ ],+ "primary": {+ "type": "button",+ "label": "Platform",+ "href": "https://platform.trymirai.com"+ }+ },+ "logo": {+ "light": "/logo/light.png",+ "dark": "/logo/dark.png"+ },+ "contextual": {+ "options": [+ "copy",+ "view",+ "chatgpt",+ "claude",+ "perplexity",+ "mcp",+ "cursor",+ "vscode"+ ]+ },+ "footer": {+ "socials": {+ "github": "https://github.com/trymirai",+ "x": "https://x.com/trymirai",+ "linkedin": "https://linkedin.com/company/trymirai"+ }+ }+}diff --git a/docs/favicon.png b/docs/favicon.pngnew file mode 100644index 000000000..6a6c635c3Binary files /dev/null and b/docs/favicon.png differdiff --git a/docs/images/headers/cli.jpg b/docs/images/headers/cli.jpgnew file mode 100644index 000000000..b3b338518Binary files /dev/null and b/docs/images/headers/cli.jpg differdiff --git a/docs/images/headers/lalamo.jpg b/docs/images/headers/lalamo.jpgnew file mode 100644index 000000000..120c06d87Binary files /dev/null and b/docs/images/headers/lalamo.jpg differdiff --git a/docs/images/headers/uzu.jpg b/docs/images/headers/uzu.jpgnew file mode 100644index 000000000..35a1e283eBinary files /dev/null and b/docs/images/headers/uzu.jpg differdiff --git a/docs/images/quick-start/xcode-new-project.png b/docs/images/quick-start/xcode-new-project.pngnew file mode 100644index 000000000..b90558829Binary files /dev/null and b/docs/images/quick-start/xcode-new-project.png differdiff --git a/docs/index.mdx b/docs/index.mdxnew file mode 100644index 000000000..728da4523--- /dev/null+++ b/docs/index.mdx@@ -0,0 +1,102 @@+---+title: 'About'+---++<Tip>+Looking for an instant start? Check out the drop-in snippets:++<Tabs>+ <Tab title="Python">+ <Columns cols={2}>+ <Card href="/quick-start/chat#python">+ Chat+ </Card>+ <Card href="/quick-start/chat-structured-output#python">+ Structured output+ </Card>+ <Card href="/quick-start/chat-cloud#python">+ Cloud+ </Card>+ </Columns>+ </Tab>+ <Tab title="Swift">+ <Columns cols={2}>+ <Card href="/quick-start/chat#swift">+ Chat+ </Card>+ <Card href="/quick-start/chat-structured-output#swift">+ Structured output+ </Card>+ <Card href="/quick-start/chat-cloud#swift">+ Cloud+ </Card>+ </Columns>+ </Tab>+ <Tab title="TypeScript">+ <Columns cols={2}>+ <Card href="/quick-start/chat#typescript">+ Chat+ </Card>+ <Card href="/quick-start/chat-structured-output#typescript">+ Structured output+ </Card>+ <Card href="/quick-start/chat-cloud#typescript">+ Cloud+ </Card>+ </Columns>+ </Tab>+ <Tab title="Rust">+ <Columns cols={2}>+ <Card href="/quick-start/chat#rust">+ Chat+ </Card>+ <Card href="/quick-start/chat-structured-output#rust">+ Structured output+ </Card>+ <Card href="/quick-start/chat-cloud#rust">+ Cloud+ </Card>+ </Columns>+ </Tab>+</Tabs>++</Tip>++[**Mirai**](https://trymirai.com/) lets you add high-performance AI right into your app with zero latency, full data privacy, and no inference costs. You don’t need an ML team or weeks of setup anymore. One developer can get it all running in minutes. To achieve this, we offer the following key products:++<Columns cols={3}>+ <Card title="uzu" img="/images/headers/uzu.jpg" href="https://github.com/trymirai/uzu">+ A Rust inference engine built to run AI with hardware specifics in mind.+ </Card>+ <Card title="lalamo" img="/images/headers/lalamo.jpg" href="https://github.com/trymirai/lalamo">+ A set of tools to optimize and convert models for on-device use.+ </Card>+ <Card title="cli" img="/images/headers/cli.jpg" href="https://github.com/trymirai/uzu#cli">+ A command-line tool to chat with models and serve them as a local API.+ </Card>+</Columns>++<Tip>+ If you run into a problem and don’t find an answer here, feel free to reach out in our [Discord](https://discord.com/invite/trymirai) community. We can even debug the issue with you over voice chat, or you can [book a call](https://calendar.google.com/calendar/u/0/appointments/schedules/AcZssZ0RkTVFVCqRHJdidCc0aRAr4T44KeO58N01tMrNBkjbNFndBAaTf6rKdtTTEryPo8JB_UNQ8Lx6) with our engineers ❤️.+</Tip>++## FAQ++<AccordionGroup>+ <Accordion title="Is this project open source?">+ <Check>+ The [**uzu**](https://github.com/trymirai/uzu) and [**lalamo**](https://github.com/trymirai/lalamo) libraries are fully open source under the MIT license.+ </Check>+ </Accordion>+ <Accordion title="Is it free to use?">+ <Check>+ The [**uzu**](https://github.com/trymirai/uzu) and [**lalamo**](https://github.com/trymirai/lalamo) libraries are completly free to use.+ </Check>+ </Accordion>+ <Accordion title="Which devices are supported?">+ <Info>Currently, only Apple Silicon (iOS/macOS) devices are supported.</Info>+ </Accordion>+ <Accordion title="Which models are supported?">+ <Info>The full list of supported models is available [here](https://trymirai.com/local-models).</Info>+ </Accordion>+</AccordionGroup>diff --git a/docs/logo/dark.png b/docs/logo/dark.pngnew file mode 100644index 000000000..b243c3c54Binary files /dev/null and b/docs/logo/dark.png differdiff --git a/docs/logo/light.png b/docs/logo/light.pngnew file mode 100644index 000000000..42d13eb0cBinary files /dev/null and b/docs/logo/light.png differdiff --git a/docs/quick-start/chat-cloud.mdx b/docs/quick-start/chat-cloud.mdxnew file mode 100644index 000000000..385e4e198--- /dev/null+++ b/docs/quick-start/chat-cloud.mdx@@ -0,0 +1,39 @@+---+title: "Cloud"+---++import StepsPython from '/snippets/quick-start/python-steps.mdx';+import StepsSwift from '/snippets/quick-start/swift-steps.mdx';+import StepsTypeScript from '/snippets/quick-start/typescript-steps.mdx';+import StepsRust from '/snippets/quick-start/rust-steps.mdx';+import CodePython from '/snippets/generated/examples/python/chat-cloud.mdx';+import CodeSwift from '/snippets/generated/examples/swift/chat-cloud.mdx';+import CodeTypeScript from '/snippets/generated/examples/typescript/chat-cloud.mdx';+import CodeRust from '/snippets/generated/examples/rust/chat-cloud.mdx';++<Tip>+ In this example, we will get a reply to a specific list of messages from a cloud model.+</Tip>++<Tabs>+ <Tab title="Python">+ <Steps>+ <StepsPython/>+ </Steps>+ </Tab>+ <Tab title="Swift">+ <Steps>+ <StepsSwift/>+ </Steps>+ </Tab>+ <Tab title="TypeScript">+ <Steps>+ <StepsTypeScript/>+ </Steps>+ </Tab>+ <Tab title="Rust">+ <Steps>+ <StepsRust/>+ </Steps>+ </Tab>+</Tabs>diff --git a/docs/quick-start/chat-structured-output.mdx b/docs/quick-start/chat-structured-output.mdxnew file mode 100644index 000000000..aebd72f50--- /dev/null+++ b/docs/quick-start/chat-structured-output.mdx@@ -0,0 +1,39 @@+---+title: "Structured output"+---++import StepsPython from '/snippets/quick-start/python-steps.mdx';+import StepsSwift from '/snippets/quick-start/swift-steps.mdx';+import StepsTypeScript from '/snippets/quick-start/typescript-steps.mdx';+import StepsRust from '/snippets/quick-start/rust-steps.mdx';+import CodePython from '/snippets/generated/examples/python/chat-structured-output.mdx';+import CodeSwift from '/snippets/generated/examples/swift/chat-structured-output.mdx';+import CodeTypeScript from '/snippets/generated/examples/typescript/chat-structured-output.mdx';+import CodeRust from '/snippets/generated/examples/rust/chat-structured-output.mdx';++<Tip>+ Sometimes you want the generated output to be valid JSON with predefined fields. You can use `Grammar` to manually specify a JSON schema for the response you want to receive.+</Tip>++<Tabs>+ <Tab title="Python">+ <Steps>+ <StepsPython/>+ </Steps>+ </Tab>+ <Tab title="Swift">+ <Steps>+ <StepsSwift/>+ </Steps>+ </Tab>+ <Tab title="TypeScript">+ <Steps>+ <StepsTypeScript/>+ </Steps>+ </Tab>+ <Tab title="Rust">+ <Steps>+ <StepsRust/>+ </Steps>+ </Tab>+</Tabs>diff --git a/docs/quick-start/chat.mdx b/docs/quick-start/chat.mdxnew file mode 100644index 000000000..66443ff53--- /dev/null+++ b/docs/quick-start/chat.mdx@@ -0,0 +1,43 @@+---+title: "Chat"+---++import StepsPython from '/snippets/quick-start/python-steps.mdx';+import StepsSwift from '/snippets/quick-start/swift-steps.mdx';+import StepsTypeScript from '/snippets/quick-start/typescript-steps.mdx';+import StepsRust from '/snippets/quick-start/rust-steps.mdx';+import CodePython from '/snippets/generated/examples/python/chat.mdx';+import CodeSwift from '/snippets/generated/examples/swift/chat.mdx';+import CodeTypeScript from '/snippets/generated/examples/typescript/chat.mdx';+import CodeRust from '/snippets/generated/examples/rust/chat.mdx';++<Tip>+ In this example, we will download a model and get a reply to a specific list of messages.+</Tip>++<Tabs>+ <Tab title="Python">+ <Steps>+ <StepsPython/>+ </Steps>+ </Tab>+ <Tab title="Swift">+ <Steps>+ <StepsSwift/>+ </Steps>+ </Tab>+ <Tab title="TypeScript">+ <Steps>+ <StepsTypeScript/>+ </Steps>+ </Tab>+ <Tab title="Rust">+ <Steps>+ <StepsRust/>+ </Steps>+ </Tab>+</Tabs>++<Info>+ Once loaded, the same `ChatSession` can be reused for multiple requests until you drop it. Each model may consume a significant amount of RAM, so it's important to keep only one session loaded at a time. For iOS apps, we recommend adding the [Increased Memory Capability](https://developer.apple.com/documentation/bundleresources/entitlements/com.apple.developer.kernel.increased-memory-limit) entitlement to ensure your app can allocate the required memory.+</Info>\ No newline at end of filediff --git a/docs/snippets/generated/examples/python/chat-cloud.mdx b/docs/snippets/generated/examples/python/chat-cloud.mdxnew file mode 100644index 000000000..b5624aeb2--- /dev/null+++ b/docs/snippets/generated/examples/python/chat-cloud.mdx@@ -0,0 +1,29 @@+```python+import asyncio++from uzu import ChatConfig, ChatMessage, ChatReplyConfig, Engine, EngineConfig, ReasoningEffort+++async def main() -> None:+ engine_config = EngineConfig.create().with_openai_api_key("OPENAI_API_KEY")+ engine = await Engine.create(engine_config)+ model = await engine.model("gpt-5")+ if model is None:+ raise RuntimeError("Model not found")++ messages = [+ ChatMessage.system().with_reasoning_effort(ReasoningEffort.Low),+ ChatMessage.user().with_text("How LLMs work"),+ ]++ session = await engine.chat(model, ChatConfig.create())+ replies = await session.reply(messages, ChatReplyConfig.create())+ if replies:+ message = replies[0].message+ print(f"Reasoning: {message.reasoning}")+ print(f"Text: {message.text}")+++if __name__ == "__main__":+ asyncio.run(main())+```diff --git a/docs/snippets/generated/examples/python/chat-shared-instance.mdx b/docs/snippets/generated/examples/python/chat-shared-instance.mdxnew file mode 100644index 000000000..4b67a3c82--- /dev/null+++ b/docs/snippets/generated/examples/python/chat-shared-instance.mdx@@ -0,0 +1,46 @@+```python+import asyncio++from uzu import ChatConfig, ChatMessage, ChatReplyConfig, Engine, EngineConfig+++async def main() -> None:+ engine_config = EngineConfig.create()+ engine = await Engine.create(engine_config)++ model = await engine.model("alibaba:qwen3.5:0.8b:mirai:mirai-m:4")+ if model is None:+ raise RuntimeError("Model not found")++ async for update in (await engine.download(model)).iterator():+ print(f"\rDownload progress: {update.progress:.2%}", end="", flush=True)+ print()++ # The chat_instance owns the loaded model and can be shared between sessions.+ chat_instance = await engine.chat_instance(model, ChatConfig.create())++ first_session = await engine.chat_with_instance(chat_instance)+ replies = await first_session.reply(+ [ChatMessage.user().with_text("Tell me a short, funny story about a robot")],+ ChatReplyConfig.create(),+ )+ if replies:+ message = replies[-1].message+ print(f"First session reasoning: {message.reasoning}")+ print(f"First session text: {message.text}")++ # The second session reuses the already-loaded weights instead of loading the model again.+ second_session = await engine.chat_with_instance(chat_instance)+ replies = await second_session.reply(+ [ChatMessage.user().with_text("What is the capital of France?")],+ ChatReplyConfig.create(),+ )+ if replies:+ message = replies[-1].message+ print(f"\nSecond session reasoning: {message.reasoning}")+ print(f"Second session text: {message.text}")+++if __name__ == "__main__":+ asyncio.run(main())+```diff --git a/docs/snippets/generated/examples/python/chat-structured-output.mdx b/docs/snippets/generated/examples/python/chat-structured-output.mdxnew file mode 100644index 000000000..9528007f7--- /dev/null+++ b/docs/snippets/generated/examples/python/chat-structured-output.mdx@@ -0,0 +1,64 @@+```python+import asyncio+import json++from pydantic import BaseModel++from uzu import (+ ChatConfig,+ ChatMessage,+ ChatReplyConfig,+ Engine,+ EngineConfig,+ Grammar,+ ReasoningEffort,+)+++class Country(BaseModel):+ name: str+ capital: str+++class CountryList(BaseModel):+ countries: list[Country]+++def structured_response(response: str | None, model_type: type[BaseModel]) -> BaseModel | None:+ if not response:+ return None+ return model_type.model_validate_json(response)+++async def main() -> None:+ engine_config = EngineConfig.create()+ engine = await Engine.create(engine_config)++ model = await engine.model("alibaba:qwen3.5:0.8b:mirai:mirai-m:4")+ if model is None:+ raise RuntimeError("Model not found")+ async for update in (await engine.download(model)).iterator():+ print(f"\rDownload progress: {update.progress:.2%}", end="", flush=True)+ print()++ schema_string = json.dumps(CountryList.model_json_schema())+ messages = [+ ChatMessage.system().with_reasoning_effort(ReasoningEffort.Disabled),+ ChatMessage.user().with_text(+ "Give me a JSON object containing a list of 3 countries, where each country has name and capital fields"+ ),+ ]++ session = await engine.chat(model, ChatConfig.create())+ replies = await session.reply(+ messages,+ ChatReplyConfig.create().with_grammar(Grammar.JsonSchema(schema_string)),+ )+ if replies:+ countries = structured_response(replies[0].message.text, CountryList)+ print(countries)+++if __name__ == "__main__":+ asyncio.run(main())+```diff --git a/docs/snippets/generated/examples/python/chat.mdx b/docs/snippets/generated/examples/python/chat.mdxnew file mode 100644index 000000000..dac636538--- /dev/null+++ b/docs/snippets/generated/examples/python/chat.mdx@@ -0,0 +1,48 @@+```python+import asyncio++from uzu import (+ ChatConfig,+ ChatMessage,+ ChatReplyConfig,+ ChatSessionStreamChunk,+ Engine,+ EngineConfig,+)+++async def main() -> None:+ engine_config = EngineConfig.create()+ engine = await Engine.create(engine_config)++ model = await engine.model("alibaba:qwen3.5:0.8b:mirai:mirai-m:4")+ if model is None:+ raise RuntimeError("Model not found")+ async for update in (await engine.download(model)).iterator():+ print(f"\rDownload progress: {update.progress:.2%}", end="", flush=True)+ print()++ messages = [+ ChatMessage.system().with_text("You are a helpful assistant"),+ ChatMessage.user().with_text("Tell me a short, funny story about a robot"),+ ]+ session = await engine.chat(model, ChatConfig.create())+ stream = await session.reply_with_stream(messages, ChatReplyConfig.create())+ message: ChatMessage | None = None+ async for chunk in stream.iterator():+ if isinstance(chunk, ChatSessionStreamChunk.Replies):+ replies = chunk.replies+ if replies:+ reply = replies[0]+ message = reply.message+ print(f"Generated tokens: {reply.stats.tokens_count_output}")+ elif isinstance(chunk, ChatSessionStreamChunk.Error):+ print(f"Error: {chunk.error}")+ if message is not None:+ print(f"Reasoning: {message.reasoning}")+ print(f"Text: {message.text}")+++if __name__ == "__main__":+ asyncio.run(main())+```diff --git a/docs/snippets/generated/examples/python/quick-start.mdx b/docs/snippets/generated/examples/python/quick-start.mdxnew file mode 100644index 000000000..67710ad23--- /dev/null+++ b/docs/snippets/generated/examples/python/quick-start.mdx@@ -0,0 +1,37 @@+```python+import asyncio++from uzu import ChatConfig, ChatMessage, ChatReplyConfig, Engine, EngineConfig+++async def main() -> None:+ engine_config = EngineConfig.create()+ engine = await Engine.create(engine_config)++ model = await engine.model("alibaba:qwen3.5:0.8b:mirai:mirai-m:4")+ if model is None:+ return++ async for update in (await engine.download(model)).iterator():+ print(f"\rDownload progress: {update.progress:.2%}", end="", flush=True)+ print()++ session = await engine.chat(model, ChatConfig.create())++ messages = [+ ChatMessage.system().with_text("You are a helpful assistant"),+ ChatMessage.user().with_text("Tell me a short, funny story about a robot"),+ ]++ replies = await session.reply(messages, ChatReplyConfig.create())+ if not replies:+ return++ message = replies[-1].message+ print(f"Reasoning: {message.reasoning}")+ print(f"Text: {message.text}")+++if __name__ == "__main__":+ asyncio.run(main())+```diff --git a/docs/snippets/generated/examples/python/tool-calls.mdx b/docs/snippets/generated/examples/python/tool-calls.mdxnew file mode 100644index 000000000..304a6d1a1--- /dev/null+++ b/docs/snippets/generated/examples/python/tool-calls.mdx@@ -0,0 +1,78 @@+```python+import asyncio+from typing import Annotated++from pydantic import BaseModel++from uzu import (+ ChatConfig,+ ChatMessage,+ ChatReplyConfig,+ Engine,+ EngineConfig,+ SamplingMethod,+ SamplingPolicy,+ uzu_tool_function,+)+++class Coordinate(BaseModel):+ """A geographic coordinate.++ Attributes:+ latitude: Latitude in decimal degrees.+ longitude: Longitude in decimal degrees.+ """++ latitude: float+ longitude: Annotated[float, "Longitude in decimal degrees."]+++@uzu_tool_function(name="get_location", description="Return the current location in coordinates")+def get_current_location() -> Coordinate:+ return Coordinate(latitude=51.5074, longitude=-0.1278)+++@uzu_tool_function+def get_current_temperature(+ latitude: float,+ longitude: Annotated[float, "Longitude in decimal degrees."],+) -> float:+ """Return the temperature at the provided coordinates.++ Args:+ latitude: Latitude in decimal degrees.+ longitude: This is overridden by the Annotated description.+ """+ _ = latitude, longitude+ return 25.0+++async def main() -> None:+ engine = await Engine.create(EngineConfig.create())+ model = await engine.model("alibaba:qwen3.5:0.8b:mirai:mirai-m:4")+ if model is None:+ raise RuntimeError("Model not found")+ async for update in (await engine.download(model)).iterator():+ print(f"\rDownload progress: {update.progress:.2%}", end="", flush=True)+ print()++ session = await engine.chat(model, ChatConfig.create())+ await session.add_tool(get_current_location)+ await session.add_tool(get_current_temperature)++ messages = [+ ChatMessage.system().with_text("You are a helpful assistant"),+ ChatMessage.user().with_text("What temperature is it now at my location?"),+ ]+ config = ChatReplyConfig.create().with_sampling_policy(SamplingPolicy.Custom(method=SamplingMethod.Greedy()))+ replies = await session.reply(messages, config)+ if replies:+ message = replies[-1].message+ print(f"Reasoning: {message.reasoning or ''}")+ print(f"Text: {message.text or ''}")+++if __name__ == "__main__":+ asyncio.run(main())+```diff --git a/docs/snippets/generated/examples/rust/chat-cloud.mdx b/docs/snippets/generated/examples/rust/chat-cloud.mdxnew file mode 100644index 000000000..e98fc876d--- /dev/null+++ b/docs/snippets/generated/examples/rust/chat-cloud.mdx@@ -0,0 +1,31 @@+```rust+use uzu::{+ engine::{Engine, EngineConfig},+ types::{+ basic::ReasoningEffort,+ session::chat::{ChatConfig, ChatMessage, ChatReplyConfig},+ },+};++#[tokio::main]+async fn main() -> Result<(), Box<dyn std::error::Error>> {+ let engine_config = EngineConfig::default().with_openai_api_key("OPENAI_API_KEY".to_string());+ let engine = Engine::new(engine_config).await?;++ let model = engine.model("gpt-5".to_string()).await?.ok_or("Model not found")?;++ let messages = vec![+ ChatMessage::system().with_reasoning_effort(ReasoningEffort::Low),+ ChatMessage::user().with_text("How LLMs work".to_string()),+ ];++ let session = engine.chat(model, ChatConfig::default()).await?;+ let replies = session.reply(messages, ChatReplyConfig::default()).await?;+ if let Some(reply) = replies.first() {+ println!("Reasoning: {}", reply.message.reasoning().unwrap_or_default());+ println!("Text: {}", reply.message.text().unwrap_or_default());+ }++ Ok(())+}+```diff --git a/docs/snippets/generated/examples/rust/chat-shared-instance.mdx b/docs/snippets/generated/examples/rust/chat-shared-instance.mdxnew file mode 100644index 000000000..a11460fe5--- /dev/null+++ b/docs/snippets/generated/examples/rust/chat-shared-instance.mdx@@ -0,0 +1,52 @@+```rust+use std::io::{self, Write};++use uzu::{+ engine::{Engine, EngineConfig},+ types::session::chat::{ChatConfig, ChatMessage, ChatReplyConfig},+};++#[tokio::main]+async fn main() -> Result<(), Box<dyn std::error::Error>> {+ let engine_config = EngineConfig::default();+ let engine = Engine::new(engine_config).await?;++ let model = engine.model("alibaba:qwen3.5:0.8b:mirai:mirai-m:4".to_string()).await?.ok_or("Model not found")?;+ let downloader = engine.download(&model).await?;+ while let Some(update) = downloader.next().await {+ print!("\r\u{001B}[2KDownload progress: {:.2}%", update.progress() * 100.0);+ io::stdout().flush()?;+ }+ println!();++ // The chat_instance owns the loaded model and can be shared between sessions+ let chat_instance = engine.chat_instance(model, ChatConfig::default()).await?;++ let first_session = engine.chat_with_instance(&chat_instance).await?;+ let replies = first_session+ .reply(+ vec![ChatMessage::user().with_text("Tell me a short, funny story about a robot".to_string())],+ ChatReplyConfig::default(),+ )+ .await?;+ if let Some(reply) = replies.last() {+ println!("First session reasoning: {}", reply.message.reasoning().unwrap_or_default());+ println!("First session text: {}", reply.message.text().unwrap_or_default());+ }++ // The second session reuses the already-loaded weights instead of loading the model again+ let second_session = engine.chat_with_instance(&chat_instance).await?;+ let replies = second_session+ .reply(+ vec![ChatMessage::user().with_text("What is the capital of France?".to_string())],+ ChatReplyConfig::default(),+ )+ .await?;+ if let Some(reply) = replies.last() {+ println!("\nSecond session reasoning: {}", reply.message.reasoning().unwrap_or_default());+ println!("Second session text: {}", reply.message.text().unwrap_or_default());+ }++ Ok(())+}+```diff --git a/docs/snippets/generated/examples/rust/chat-structured-output.mdx b/docs/snippets/generated/examples/rust/chat-structured-output.mdxnew file mode 100644index 000000000..a3756c22a--- /dev/null+++ b/docs/snippets/generated/examples/rust/chat-structured-output.mdx@@ -0,0 +1,61 @@+```rust+use std::io::{self, Write};++use schemars::{JsonSchema, schema_for};+use serde::{Deserialize, Serialize};+use uzu::{+ engine::{Engine, EngineConfig},+ types::{+ basic::{Grammar, ReasoningEffort},+ session::chat::{ChatConfig, ChatMessage, ChatReplyConfig},+ },+};++#[derive(Debug, Serialize, Deserialize, JsonSchema)]+struct Country {+ name: String,+ capital: String,+}++#[derive(Debug, Serialize, Deserialize, JsonSchema)]+struct CountryList {+ countries: Vec<Country>,+}++#[tokio::main]+async fn main() -> Result<(), Box<dyn std::error::Error>> {+ let engine_config = EngineConfig::default();+ let engine = Engine::new(engine_config).await?;++ let model = engine.model("alibaba:qwen3.5:0.8b:mirai:mirai-m:4".to_string()).await?.ok_or("Model not found")?;+ let downloader = engine.download(&model).await?;+ while let Some(update) = downloader.next().await {+ print!("\r\u{001B}[2KDownload progress: {:.2}%", update.progress() * 100.0);+ io::stdout().flush()?;+ }+ println!();++ let schema_string = serde_json::to_string(&schema_for!(CountryList))?;+ let messages = vec![+ ChatMessage::system().with_reasoning_effort(ReasoningEffort::Disabled),+ ChatMessage::user().with_text(+ "Give me a JSON object containing a list of 3 countries, where each country has name and capital fields"+ .to_string(),+ ),+ ];++ let session = engine.chat(model, ChatConfig::default()).await?;+ let chat_reply_config = ChatReplyConfig::default().with_grammar(Some(Grammar::JsonSchema {+ schema: schema_string,+ }));+ let replies = session.reply(messages, chat_reply_config).await?;+ if let Some(reply) = replies.first()+ && let Some(text) = reply.message.text()+ {+ let parsed: CountryList = serde_json::from_str(&text)?;+ println!("{parsed:#?}");+ }++ Ok(())+}+```diff --git a/docs/snippets/generated/examples/rust/chat.mdx b/docs/snippets/generated/examples/rust/chat.mdxnew file mode 100644index 000000000..c4d3cf338--- /dev/null+++ b/docs/snippets/generated/examples/rust/chat.mdx@@ -0,0 +1,54 @@+```rust+use std::io::{self, Write};++use uzu::{+ engine::{Engine, EngineConfig},+ session::chat::ChatSessionStreamChunk,+ types::session::chat::{ChatConfig, ChatMessage, ChatReplyConfig},+};++#[tokio::main]+async fn main() -> Result<(), Box<dyn std::error::Error>> {+ let engine_config = EngineConfig::default();+ let engine = Engine::new(engine_config).await?;++ let model = engine.model("alibaba:qwen3.5:0.8b:mirai:mirai-m:4".to_string()).await?.ok_or("Model not found")?;+ let downloader = engine.download(&model).await?;+ while let Some(update) = downloader.next().await {+ print!("\r\u{001B}[2KDownload progress: {:.2}%", update.progress() * 100.0);+ io::stdout().flush()?;+ }+ println!();++ let messages = vec![+ ChatMessage::system().with_text("You are a helpful assistant".to_string()),+ ChatMessage::user().with_text("Tell me a short, funny story about a robot".to_string()),+ ];+ let session = engine.chat(model, ChatConfig::default()).await?;+ let stream = session.reply_with_stream(messages, ChatReplyConfig::default()).await;+ let mut last_message: Option<ChatMessage> = None;+ while let Some(chunk) = stream.next().await {+ match chunk {+ ChatSessionStreamChunk::Replies {+ replies,+ } => {+ if let Some(reply) = replies.first() {+ last_message = Some(reply.message.clone());+ println!("Generated tokens: {}", reply.stats.tokens_count_output.unwrap_or_default());+ }+ },+ ChatSessionStreamChunk::Error {+ error,+ } => {+ println!("Error: {error}");+ },+ }+ }+ if let Some(message) = last_message {+ println!("Reasoning: {}", message.reasoning().unwrap_or_default());+ println!("Text: {}", message.text().unwrap_or_default());+ }++ Ok(())+}+```diff --git a/docs/snippets/generated/examples/rust/quick-start.mdx b/docs/snippets/generated/examples/rust/quick-start.mdxnew file mode 100644index 000000000..2ca376faf--- /dev/null+++ b/docs/snippets/generated/examples/rust/quick-start.mdx@@ -0,0 +1,37 @@+```rust+use std::io::{self, Write};++use uzu::{+ engine::{Engine, EngineConfig},+ types::session::chat::{ChatConfig, ChatMessage, ChatReplyConfig},+};++#[tokio::main]+async fn main() -> Result<(), Box<dyn std::error::Error>> {+ let engine_config = EngineConfig::default();+ let engine = Engine::new(engine_config).await?;++ let model = engine.model("alibaba:qwen3.5:0.8b:mirai:mirai-m:4".to_string()).await?.ok_or("Model not found")?;+ let downloader = engine.download(&model).await?;+ while let Some(update) = downloader.next().await {+ print!("\r\u{001B}[2KDownload progress: {:.2}%", update.progress() * 100.0);+ io::stdout().flush()?;+ }+ println!();++ let session = engine.chat(model, ChatConfig::default()).await?;++ let messages = vec![+ ChatMessage::system().with_text("You are a helpful assistant".to_string()),+ ChatMessage::user().with_text("Tell me a short, funny story about a robot".to_string()),+ ];++ let replies = session.reply(messages, ChatReplyConfig::default()).await?;+ if let Some(reply) = replies.last() {+ println!("Reasoning: {}", reply.message.reasoning().unwrap_or_default());+ println!("Text: {}", reply.message.text().unwrap_or_default());+ }++ Ok(())+}+```diff --git a/docs/snippets/generated/examples/rust/tool-calls.mdx b/docs/snippets/generated/examples/rust/tool-calls.mdxnew file mode 100644index 000000000..d629341e9--- /dev/null+++ b/docs/snippets/generated/examples/rust/tool-calls.mdx@@ -0,0 +1,77 @@+```rust+use std::io::{self, Write};++use nagare::tool::{func_def::ErrorFuture, uzu_tool_closure, uzu_tool_function};+use schemars::JsonSchema;+use serde::{Deserialize, Serialize};+use shoji::types::{+ basic::{SamplingMethod, SamplingPolicy},+ session::chat::{ChatConfig, ChatMessage, ChatReplyConfig},+};+use uzu::engine::{Engine, EngineConfig};++/// A geographic coordinate.+#[derive(Serialize, Deserialize, JsonSchema)]+struct Coordinate {+ /// Latitude in decimal degrees.+ latitude: f64,+ /// Longitude in decimal degrees.+ longitude: f64,+}++/// Returns current location in coordinates+#[uzu_tool_function]+fn get_current_location() -> Result<Coordinate, ErrorFuture> {+ Ok(Coordinate {+ latitude: 51.5074,+ longitude: -0.1278,+ })+}++#[tokio::main]+async fn main() -> Result<(), Box<dyn std::error::Error>> {+ let engine = Engine::new(EngineConfig::default()).await?;+ let model = engine.model("alibaba:qwen3.5:0.8b:mirai:mirai-m:4".to_string()).await?.ok_or("Model not found")?;+ let downloader = engine.download(&model).await?;+ while let Some(update) = downloader.next().await {+ print!("\r\u{001B}[2KDownload progress: {:.2}%", update.progress() * 100.0);+ io::stdout().flush()?;+ }+ println!();++ let mut session = engine.chat(model, ChatConfig::default()).await?;+ session.add_tool(get_current_location).await?;+ session+ .add_tool(uzu_tool_closure! {+ /// Returns temperature in provided location+ get_current_temperature: |+ /// Latitude in decimal degrees.+ _latitude: f64,+ /// Longitude in decimal degrees.+ _longitude: f64+ | -> Result<f64, ErrorFuture> {+ Ok(25.0)+ }+ })+ .await?;++ let messages = vec![+ ChatMessage::system().with_text("You are a helpful assistant".to_string()),+ ChatMessage::user().with_text("What temperature is it now at my location?".to_string()),+ ];++ let config = ChatReplyConfig {+ sampling_policy: SamplingPolicy::Custom {+ method: SamplingMethod::Greedy {},+ },+ ..ChatReplyConfig::default()+ };+ let replies = session.reply(messages.clone(), config).await?;+ if let Some(reply) = replies.last() {+ println!("Reasoning: {}", reply.message.reasoning().unwrap_or_default());+ println!("Text: {}", reply.message.text().unwrap_or_default());+ }++ Ok(())+}+```diff --git a/docs/snippets/generated/examples/swift/chat-cloud.mdx b/docs/snippets/generated/examples/swift/chat-cloud.mdxnew file mode 100644index 000000000..d78773c04--- /dev/null+++ b/docs/snippets/generated/examples/swift/chat-cloud.mdx@@ -0,0 +1,26 @@+```swift+import Uzu++public func runChatCloud() async throws {+ let engineConfig = EngineConfig.create().withOpenaiApiKey(openaiApiKey: "OPENAI_API_KEY")+ let engine = try await Engine.create(config: engineConfig)++ guard let model = try await engine.model(identifier: "gpt-5") else {+ return+ }++ let messages = [+ ChatMessage.system().withReasoningEffort(reasoningEffort: .low),+ ChatMessage.user().withText(text: "How LLMs work")+ ]++ let session = try await engine.chat(model: model, config: .create())+ let reply = try await session.reply(input: messages, config: .create())+ guard let message = reply.last?.message else {+ return+ }++ print("Reasoning: \(message.reasoning() ?? "empty")")+ print("Text: \(message.text() ?? "empty")")+}+```diff --git a/docs/snippets/generated/examples/swift/chat-shared-instance.mdx b/docs/snippets/generated/examples/swift/chat-shared-instance.mdxnew file mode 100644index 000000000..8a9be0821--- /dev/null+++ b/docs/snippets/generated/examples/swift/chat-shared-instance.mdx@@ -0,0 +1,42 @@+```swift+import Foundation+import Uzu++public func runChatSharedInstance() async throws {+ let engineConfig = EngineConfig.create()+ let engine = try await Engine.create(config: engineConfig)++ guard let model = try await engine.model(identifier: "alibaba:qwen3.5:0.8b:mirai:mirai-m:4") else {+ return+ }+ for try await update in try await engine.download(model: model).iterator() {+ print(String(format: "\r\u{001B}[2KDownload progress: %.2f%%", update.progress() * 100), terminator: "")+ fflush(stdout)+ }+ print()++ // The chatInstance owns the loaded model and can be shared between sessions.+ let chatInstance = try await engine.chatInstance(model: model, config: .create())++ let firstSession = try await engine.chatWithInstance(instance: chatInstance)+ let replies = try await firstSession.reply(+ input: [ChatMessage.user().withText(text: "Tell me a short, funny story about a robot")],+ config: .create()+ )+ if let message = replies.last?.message {+ print("First session reasoning: \(message.reasoning() ?? "")")+ print("First session text: \(message.text() ?? "")")+ }++ // The second session reuses the already-loaded weights instead of loading the model again.+ let secondSession = try await engine.chatWithInstance(instance: chatInstance)+ let secondReplies = try await secondSession.reply(+ input: [ChatMessage.user().withText(text: "What is the capital of France?")],+ config: .create()+ )+ if let message = secondReplies.last?.message {+ print("\nSecond session reasoning: \(message.reasoning() ?? "")")+ print("Second session text: \(message.text() ?? "")")+ }+}+```diff --git a/docs/snippets/generated/examples/swift/chat-structured-output.mdx b/docs/snippets/generated/examples/swift/chat-structured-output.mdxnew file mode 100644index 000000000..c0bf34ec2--- /dev/null+++ b/docs/snippets/generated/examples/swift/chat-structured-output.mdx@@ -0,0 +1,40 @@+```swift+import Foundation+import FoundationModels+import Uzu++@Generable()+struct Country: Codable {+ let name: String+ let capital: String+}++public func runChatStructuredOutput() async throws {+ let engineConfig = EngineConfig.create()+ let engine = try await Engine.create(config: engineConfig)++ guard let model = try await engine.model(identifier: "alibaba:qwen3.5:0.8b:mirai:mirai-m:4") else {+ return+ }+ for try await update in try await engine.download(model: model).iterator() {+ print(String(format: "\r\u{001B}[2KDownload progress: %.2f%%", update.progress() * 100), terminator: "")+ fflush(stdout)+ }+ print()++ let messages = [+ ChatMessage.system().withReasoningEffort(reasoningEffort: .disabled),+ ChatMessage.user().withText(text: "Give me a JSON object containing a list of 3 countries, where each country has name and capital fields")+ ]++ let session = try await engine.chat(model: model, config: .create())+ let reply = try await session.reply(input: messages, config: .create().withGrammar(grammar: .fromType([Country].self)))+ guard let message = reply.last?.message else {+ return+ }+ guard let countries: [Country] = message.textDecoded() else {+ return+ }+ print(countries)+}+```diff --git a/docs/snippets/generated/examples/swift/chat.mdx b/docs/snippets/generated/examples/swift/chat.mdxnew file mode 100644index 000000000..9eb8f172e--- /dev/null+++ b/docs/snippets/generated/examples/swift/chat.mdx@@ -0,0 +1,38 @@+```swift+import Foundation+import Uzu++public func runChat() async throws {+ let engineConfig = EngineConfig.create()+ let engine = try await Engine.create(config: engineConfig)++ guard let model = try await engine.model(identifier: "alibaba:qwen3.5:0.8b:mirai:mirai-m:4") else {+ return+ }+ for try await update in try await engine.download(model: model).iterator() {+ print(String(format: "\r\u{001B}[2KDownload progress: %.2f%%", update.progress() * 100), terminator: "")+ fflush(stdout)+ }+ print()++ let messages = [+ ChatMessage.system().withText(text: "You are a helpful assistant"),+ ChatMessage.user().withText(text: "Tell me a short, funny story about a robot")+ ]+ let session = try await engine.chat(model: model, config: .create())+ let stream = await session.replyWithStream(input: messages, config: .create())+ var message: ChatMessage? = nil+ for try await update in stream.iterator() {+ switch update {+ case .replies(let replies):+ let reply = replies.last+ message = reply?.message+ print("Generated tokens: \(reply?.stats.tokensCountOutput ?? 0)")+ case .error(let error):+ print("Error: \(error)")+ }+ }+ print("Reasoning: \(message?.reasoning() ?? "empty")")+ print("Text: \(message?.text() ?? "empty")")+}+```diff --git a/docs/snippets/generated/examples/swift/quick-start.mdx b/docs/snippets/generated/examples/swift/quick-start.mdxnew file mode 100644index 000000000..c73c9c00c--- /dev/null+++ b/docs/snippets/generated/examples/swift/quick-start.mdx@@ -0,0 +1,34 @@+```swift+import Foundation+import Uzu++public func runQuickStart() async throws {+ let engineConfig = EngineConfig.create()+ let engine = try await Engine.create(config: engineConfig)++ guard let model = try await engine.model(identifier: "alibaba:qwen3.5:0.8b:mirai:mirai-m:4") else {+ return+ }++ for try await update in try await engine.download(model: model).iterator() {+ print(String(format: "\r\u{001B}[2KDownload progress: %.2f%%", update.progress() * 100), terminator: "")+ fflush(stdout)+ }+ print()++ let session = try await engine.chat(model: model, config: .create())++ let messages = [+ ChatMessage.system().withText(text: "You are a helpful assistant"),+ ChatMessage.user().withText(text: "Tell me a short, funny story about a robot")+ ]++ let reply = try await session.reply(input: messages, config: .create())+ guard let message = reply.last?.message else {+ return+ }++ print("Reasoning: \(message.reasoning() ?? "empty")")+ print("Text: \(message.text() ?? "empty")")+}+```diff --git a/docs/snippets/generated/examples/swift/tool-calls.mdx b/docs/snippets/generated/examples/swift/tool-calls.mdxnew file mode 100644index 000000000..b145431a6--- /dev/null+++ b/docs/snippets/generated/examples/swift/tool-calls.mdx@@ -0,0 +1,68 @@+```swift+import Foundation+import FoundationModels+import Uzu++@Generable+private struct Coordinate: Codable, Sendable {+ @Guide(description: "Latitude in decimal degrees.")+ let latitude: Double++ @Guide(description: "Longitude in decimal degrees.")+ let longitude: Double+}++private struct GetCurrentLocation: Tool {+ let description = "Returns current location in coordinates"++ @Generable+ struct Arguments {+ }++ func call(arguments: Arguments) async throws -> Coordinate {+ Coordinate(latitude: 51.5074, longitude: -0.1278)+ }+}++private struct GetCurrentTemperature: Tool {+ let description = "Returns temperature in provided location"++ func call(arguments: Coordinate) async throws -> Double {+ _ = arguments+ return 25.0+ }+}++public func runToolCalls() async throws {+ let engine = try await Engine.create(config: .create())+ guard let model = try await engine.model(identifier: "alibaba:qwen3.5:0.8b:mirai:mirai-m:4") else {+ throw ToolCallsExampleError.modelNotFound+ }+ for try await update in try await engine.download(model: model).iterator() {+ print(String(format: "\r\u{001B}[2KDownload progress: %.2f%%", update.progress() * 100), terminator: "")+ fflush(stdout)+ }+ print()++ let session = try await engine.chat(model: model, config: .create())+ try await session.addTool(GetCurrentLocation())+ try await session.addTool(GetCurrentTemperature())++ let messages = [+ ChatMessage.system().withText(text: "You are a helpful assistant"),+ ChatMessage.user().withText(text: "What temperature is it now at my location?"),+ ]+ let reply_config = ChatReplyConfig.create().withSamplingMethod(samplingMethod: .greedy)+ let replies = try await session.reply(input: messages, config: reply_config)+ guard let message = replies.last?.message else {+ return+ }++ print("Reasoning: \(message.reasoning() ?? "")")+ print("Text: \(message.text() ?? "")")+}++private enum ToolCallsExampleError: Swift.Error {+ case modelNotFound+}+```diff --git a/docs/snippets/generated/examples/typescript/chat-cloud.mdx b/docs/snippets/generated/examples/typescript/chat-cloud.mdxnew file mode 100644index 000000000..794b67551--- /dev/null+++ b/docs/snippets/generated/examples/typescript/chat-cloud.mdx@@ -0,0 +1,30 @@+```ts+import { ChatConfig, ChatMessage, ChatReplyConfig, Engine, EngineConfig, ReasoningEffort } from '@trymirai/uzu';++async function main() {+ let engineConfig = EngineConfig.create().withOpenaiApiKey('OPENAI_API_KEY');+ let engine = await Engine.create(engineConfig);++ let model = await engine.model('gpt-5');+ if (!model) {+ throw new Error('Model not found');+ }++ let messages = [+ ChatMessage.system().withReasoningEffort("Low" as ReasoningEffort),+ ChatMessage.user().withText('How LLMs work')+ ];++ let session = await engine.chat(model, ChatConfig.create());+ let reply = await session.reply(messages, ChatReplyConfig.create());+ let message = reply[0]?.message;+ if (message) {+ console.log('Reasoning: ', message.reasoning);+ console.log('Text: ', message.text);+ }+}++main().catch((error) => {+ console.error(error);+});+```diff --git a/docs/snippets/generated/examples/typescript/chat-shared-instance.mdx b/docs/snippets/generated/examples/typescript/chat-shared-instance.mdxnew file mode 100644index 000000000..b639e351f--- /dev/null+++ b/docs/snippets/generated/examples/typescript/chat-shared-instance.mdx@@ -0,0 +1,47 @@+```ts+import { ChatConfig, ChatMessage, ChatReplyConfig, Engine, EngineConfig } from '@trymirai/uzu';++async function main() {+ let engineConfig = EngineConfig.create();+ let engine = await Engine.create(engineConfig);++ let model = await engine.model('alibaba:qwen3.5:0.8b:mirai:mirai-m:4');+ if (!model) {+ throw new Error('Model not found');+ }+ for await (const update of await engine.download(model)) {+ process.stdout.write(`\rDownload progress: ${(update.progress * 100).toFixed(2)}%`);+ }+ console.log();++ // The chat instance owns the loaded model and can be shared between sessions.+ let chatInstance = await engine.chatInstance(model, ChatConfig.create());++ let firstSession = await engine.chatWithInstance(chatInstance);+ let replies = await firstSession.reply(+ [ChatMessage.user().withText('Tell me a short, funny story about a robot')],+ ChatReplyConfig.create(),+ );+ let reply = replies[replies.length - 1];+ if (reply) {+ console.log('First session reasoning: ', reply.message.reasoning);+ console.log('First session text: ', reply.message.text);+ }++ // The second session reuses the already-loaded weights instead of loading the model again.+ let secondSession = await engine.chatWithInstance(chatInstance);+ replies = await secondSession.reply(+ [ChatMessage.user().withText('What is the capital of France?')],+ ChatReplyConfig.create(),+ );+ reply = replies[replies.length - 1];+ if (reply) {+ console.log('\nSecond session reasoning: ', reply.message.reasoning);+ console.log('Second session text: ', reply.message.text);+ }+}++main().catch((error) => {+ console.error(error);+});+```diff --git a/docs/snippets/generated/examples/typescript/chat-structured-output.mdx b/docs/snippets/generated/examples/typescript/chat-structured-output.mdxnew file mode 100644index 000000000..a7c524563--- /dev/null+++ b/docs/snippets/generated/examples/typescript/chat-structured-output.mdx@@ -0,0 +1,50 @@+```ts+import { ChatConfig, ChatMessage, ChatReplyConfig, Engine, EngineConfig, GrammarJsonSchema, ReasoningEffort } from '@trymirai/uzu';+import * as z from "zod";++const CountryType = z.object({+ name: z.string(),+ capital: z.string(),+});+const CountryListType = z.array(CountryType);++function structuredResponse<T extends z.ZodType>(response: string | null | undefined, type: T): z.infer<T> | undefined {+ if (!response) {+ return undefined;+ }+ const data = JSON.parse(response);+ const result = type.parse(data);+ return result;+}++async function main() {+ let engineConfig = EngineConfig.create();+ let engine = await Engine.create(engineConfig);++ let model = await engine.model('alibaba:qwen3.5:0.8b:mirai:mirai-m:4');+ if (!model) {+ throw new Error('Model not found');+ }+ for await (const update of await engine.download(model)) {+ process.stdout.write(`\rDownload progress: ${(update.progress * 100).toFixed(2)}%`);+ }+ console.log();++ let schema = z.toJSONSchema(CountryListType);+ let schemaString = JSON.stringify(schema);+ let messages = [+ ChatMessage.system().withReasoningEffort("Disabled" as ReasoningEffort),+ ChatMessage.user().withText('Give me a JSON object containing a list of 3 countries, where each country has name and capital fields')+ ];++ let session = await engine.chat(model, ChatConfig.create());+ let reply = await session.reply(messages, ChatReplyConfig.create().withGrammar(new GrammarJsonSchema(schemaString)));+ let message = reply[0]?.message;+ let countries = structuredResponse(message?.text, CountryListType);+ console.log(countries);+}++main().catch((error) => {+ console.error(error);+});+```diff --git a/docs/snippets/generated/examples/typescript/chat.mdx b/docs/snippets/generated/examples/typescript/chat.mdxnew file mode 100644index 000000000..5c0a2be3b--- /dev/null+++ b/docs/snippets/generated/examples/typescript/chat.mdx@@ -0,0 +1,47 @@+```ts+import {+ ChatConfig,+ ChatMessage,+ ChatReplyConfig,+ ChatSessionStreamChunkError,+ ChatSessionStreamChunkReplies,+ Engine,+ EngineConfig+} from '@trymirai/uzu';++async function main() {+ let engineConfig = EngineConfig.create();+ let engine = await Engine.create(engineConfig);++ let model = await engine.model('alibaba:qwen3.5:0.8b:mirai:mirai-m:4');+ if (!model) {+ throw new Error('Model not found');+ }+ for await (const update of await engine.download(model)) {+ process.stdout.write(`\rDownload progress: ${(update.progress * 100).toFixed(2)}%`);+ }+ console.log();++ let messages = [+ ChatMessage.system().withText('You are a helpful assistant'),+ ChatMessage.user().withText('Tell me a short, funny story about a robot')+ ];+ let session = await engine.chat(model, ChatConfig.create());+ let stream = await session.replyWithStream(messages, ChatReplyConfig.create());+ let message: ChatMessage | undefined;+ for await (const chunk of stream) {+ if (chunk instanceof ChatSessionStreamChunkReplies) {+ message = chunk.replies[0]?.message;+ console.log('Generated tokens: ', chunk.replies[0]?.stats.tokensCountOutput);+ } else if (chunk instanceof ChatSessionStreamChunkError) {+ console.error('Error: ', chunk.error);+ }+ }+ console.log('Reasoning: ', message?.reasoning);+ console.log('Text: ', message?.text);+}++main().catch((error) => {+ console.error(error);+});+```diff --git a/docs/snippets/generated/examples/typescript/quick-start.mdx b/docs/snippets/generated/examples/typescript/quick-start.mdxnew file mode 100644index 000000000..dc783f7c1--- /dev/null+++ b/docs/snippets/generated/examples/typescript/quick-start.mdx@@ -0,0 +1,37 @@+```ts+import { ChatConfig, ChatMessage, ChatReplyConfig, Engine, EngineConfig } from '@trymirai/uzu';++async function main() {+ let engineConfig = EngineConfig.create();+ let engine = await Engine.create(engineConfig);++ let model = await engine.model('alibaba:qwen3.5:0.8b:mirai:mirai-m:4');+ if (!model) {+ throw new Error('Model not found');+ }++ for await (const update of await engine.download(model)) {+ process.stdout.write(`\rDownload progress: ${(update.progress * 100).toFixed(2)}%`);+ }+ console.log();++ let session = await engine.chat(model, ChatConfig.create());++ let messages = [+ ChatMessage.system().withText('You are a helpful assistant'),+ ChatMessage.user().withText('Tell me a short, funny story about a robot')+ ];++ let reply = await session.reply(messages, ChatReplyConfig.create());+ let message = reply[0]?.message;++ if (message) {+ console.log('Reasoning: ', message.reasoning);+ console.log('Text: ', message.text);+ }+}++main().catch((error) => {+ console.error(error);+});+```diff --git a/docs/snippets/generated/examples/typescript/tool-calls.mdx b/docs/snippets/generated/examples/typescript/tool-calls.mdxnew file mode 100644index 000000000..c13882f67--- /dev/null+++ b/docs/snippets/generated/examples/typescript/tool-calls.mdx@@ -0,0 +1,84 @@+```ts+import {+ ChatConfig,+ ChatMessage,+ ChatReplyConfig,+ Engine,+ EngineConfig,+ SamplingMethodGreedy,+ SamplingPolicyCustom,+ uzuToolFunction,+} from '@trymirai/uzu';+import * as z from 'zod';+++const Coordinate = z.object({+ latitude: z.number().describe('Latitude in decimal degrees.'),+ longitude: z.number().describe('Longitude in decimal degrees.'),+});++type Coordinate = z.infer<typeof Coordinate>;+++const getCurrentLocation = uzuToolFunction({+ name: 'get_location',+ description: 'Return the current location in coordinates',+ parameters: z.object({}),+ returns: Coordinate,+ handler: (): Coordinate => ({+ latitude: 51.5074,+ longitude: -0.1278,+ }),+});+++async function calculateCurrentTemperature({latitude, longitude}: Coordinate): Promise<number> {+ if (!Number.isFinite(Math.hypot(latitude, longitude))) {+ throw new RangeError('Coordinates must be finite');+ }+ return 25;+}++const getCurrentTemperature = uzuToolFunction({+ name: 'get_current_temperature',+ description: 'Return the temperature at the provided coordinates',+ parameters: Coordinate,+ returns: z.number(),+ handler: calculateCurrentTemperature,+});+++async function main() {+ const engine = await Engine.create(EngineConfig.create());+ const model = await engine.model('alibaba:qwen3.5:0.8b:mirai:mirai-m:4');+ if (!model) {+ throw new Error('Model not found');+ }+ for await (const update of await engine.download(model)) {+ process.stdout.write(`\rDownload progress: ${(update.progress * 100).toFixed(2)}%`);+ }+ process.stdout.write('\n');++ const session = await engine.chat(model, ChatConfig.create());+ await session.addTool(getCurrentLocation);+ await session.addTool(getCurrentTemperature);++ const messages = [+ ChatMessage.system().withText('You are a helpful assistant'),+ ChatMessage.user().withText('What temperature is it now at my location?'),+ ];+ const config = ChatReplyConfig.create().withSamplingPolicy(+ new SamplingPolicyCustom(new SamplingMethodGreedy()),+ );+ const replies = await session.reply(messages, config);+ const message = replies[replies.length - 1]?.message;+ if (message) {+ console.log('Reasoning:', message.reasoning ?? '');+ console.log('Text:', message.text ?? '');+ }+}++main().catch((error: unknown) => {+ console.error(error);+});+```diff --git a/docs/snippets/quick-start/python-steps.mdx b/docs/snippets/quick-start/python-steps.mdxnew file mode 100644index 000000000..3d0c1ff78--- /dev/null+++ b/docs/snippets/quick-start/python-steps.mdx@@ -0,0 +1,18 @@+<Step title="Create a new project">+```sh+uv init demo && cd demo+```+</Step>+<Step title="Install dependencies">+```sh+uv add uzu+```+</Step>+<Step title="Paste into main.py">+<CodePython />+</Step>+<Step title="Run the snippet">+```sh+uv run main.py+```+</Step>\ No newline at end of filediff --git a/docs/snippets/quick-start/rust-steps.mdx b/docs/snippets/quick-start/rust-steps.mdxnew file mode 100644index 000000000..e39a518f6--- /dev/null+++ b/docs/snippets/quick-start/rust-steps.mdx@@ -0,0 +1,19 @@+<Step title="Create a new project">+```sh+cargo new demo && cd demo+```+</Step>+<Step title="Install dependencies">+```sh+cargo add uzu --git https://github.com/trymirai/uzu+cargo add tokio --features full+```+</Step>+<Step title="Paste into src/main.rs">+<CodeRust />+</Step>+<Step title="Run the snippet">+```sh+cargo run --release+```+</Step>\ No newline at end of filediff --git a/docs/snippets/quick-start/swift-steps.mdx b/docs/snippets/quick-start/swift-steps.mdxnew file mode 100644index 000000000..ab1c0ac4e--- /dev/null+++ b/docs/snippets/quick-start/swift-steps.mdx@@ -0,0 +1,26 @@+<Step title="Create a new SwiftUI project">+ +</Step>+<Step title="Add the SDK">+ Add this package through SPM:+ ```sh+ https://github.com/trymirai/uzu.git+ ```+</Step>+<Step title="Paste the snippet">+ <CodeSwift/>+</Step>+<Step title="Add the snippet call">+ ```swift+ var body: some View {+ VStack {+ Text("On-device AI")+ }+ .onAppear() {+ Task {+ try await runExampleName()+ }+ }+ }+ ```+</Step>\ No newline at end of filediff --git a/docs/snippets/quick-start/typescript-steps.mdx b/docs/snippets/quick-start/typescript-steps.mdxnew file mode 100644index 000000000..f6b533e7f--- /dev/null+++ b/docs/snippets/quick-start/typescript-steps.mdx@@ -0,0 +1,44 @@+<Step title="Make a new project folder">+```sh+mkdir demo && cd demo+```+</Step>+<Step title="Initialize with pnpm">+```sh+pnpm init+```+</Step>+<Step title="Install dependencies">+```sh+pnpm add typescript ts-node @types/node -D+pnpm add @trymirai/uzu+```+</Step>+<Step title="Initialize a tsconfig.json">+```json+{+ "compilerOptions": {+ "target": "es2020",+ "module": "commonjs",+ "moduleResolution": "node",+ "strict": true,+ "esModuleInterop": true,+ "outDir": "dist",+ "types": [+ "node"+ ]+ },+ "include": [+ "*.ts"+ ]+}+```+</Step>+<Step title="Create main.ts">+<CodeTypeScript />+</Step>+<Step title="Run the snippet">+```sh+pnpm ts-node main.ts+```+</Step>\ No newline at end of file