ambi 0.3.6

A flexible, multi-backend, customizable AI agent framework, entirely based on Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

# WebAssembly (WASM)


Ambi compiles to WASM32 and runs in browsers. This is a first-class target, not an afterthought.

## Limitations compared to native


| Feature | Native | WASM |
|---------|--------|------|
| llama.cpp inference | Yes | **No** (compile-time blocked) |
| OpenAI API | Yes | Yes (browser fetch) |
| **Streaming API** | Yes (tokio) | **Yes** (native `fetch` + `ReadableStream`) |
| Custom engine | Yes | Yes |
| `spawn_blocking` | Thread pool | Inline execution |
| `Send + Sync` bounds | Enforced | Relaxed (single-threaded) |
| GPU acceleration | Yes | No |

The `llama-cpp` feature is blocked at compile time for WASM:

```rust
#[cfg(all(target_arch = "wasm32", feature = "llama-cpp"))]

compile_error!("llama-cpp not supported on wasm32");
```

Only `openai-api` or custom engines work on WASM.

## Building for WASM


```bash
cargo build --target wasm32-unknown-unknown --no-default-features --features openai-api
```

Or use `wasm-pack` for a browser-ready package:

```bash
wasm-pack build --target web --no-default-features --features openai-api
```

## Runtime polyfills


The `runtime` module replaces Tokio-specific calls with WASM-compatible alternatives:

- **`spawn()`** → `wasm_bindgen_futures::spawn_local()`
- **`spawn_blocking()`** → direct synchronous execution (single-threaded)
- **`sleep()`** → `gloo_timers::future::sleep()`
- **`timeout()`** → future race against a timer
- **`SendSync` trait** → empty marker (no-op in single-threaded context)

You don't need to change any code – the polyfills are applied automatically based on `#[cfg(target_arch = "wasm32")]`.

## Cargo.toml for WASM


```toml
[dependencies]
ambi = { version = "0.3", default-features = false, features = ["openai-api"] }
tokio = { version = "1", features = ["sync", "macros"] }    # no rt-multi-thread
wasm-bindgen = "0.2"
wasm-bindgen-futures = "0.4"
```

Note: `rt-multi-thread` is not needed (and won't compile) for WASM.

## Streaming in the browser


The OpenAI provider for WASM uses native `fetch` and `ReadableStream` APIs for true streaming.
The same `chat_stream()` API works identically in the browser:

```rust
use futures::StreamExt;

let mut stream = runner.chat_stream(&agent, &state, "Tell me a story").await?;
while let Some(chunk) = stream.next().await {
    if let Ok(text) = chunk {
        // append to DOM
    }
}
```

No special WASM polyfills are needed – the `runtime` module automatically swaps Tokio
internals for WASM-compatible alternatives.

## Example


See [`examples/webAssembly`](https://github.com/maskviva/ambi/tree/main/examples/webAssembly)
for a complete browser-ready setup with a UI toggle demoing real-time streaming text generation.