Raven

https://raven-ml.dev/docs
Admin
Raven is an OCaml ecosystem for numerical computing, machine learning, and data science that brings...
Tokens:387,420
Snippets:3,317
Trust Score:6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Execute Example

Source: https://raven-ml.dev/docs/brot/examples/special-tokens

Command to run the special tokens example.

```bash
dune exec brot/examples/06-special-tokens/main.exe
```

--------------------------------

### Install Talon

Source: https://raven-ml.dev/docs/talon/getting-started

Instructions for installing Talon via OPAM or building from source.

```bash
opam install talon
```

```bash
git clone https://github.com/raven-ml/raven.git
cd raven
opam install . --deps-only
dune build
```

--------------------------------

### Execute Infix Arithmetic Example

Source: https://raven-ml.dev/docs/nx/examples/infix-and-arithmetic

Run the main executable for the 02-infix-and-arithmetic example.

```shell
dune exec nx/examples/02-infix-and-arithmetic/main.exe
```

--------------------------------

### Execute Decoder Example

Source: https://raven-ml.dev/docs/brot/examples/decoders

Run the decoder example project using dune.

```bash
dune exec brot/examples/08-decoders/main.exe
```

--------------------------------

### Execute Reshaping and Broadcasting Example

Source: https://raven-ml.dev/docs/nx/examples/reshaping-and-broadcasting

Run the main example for reshaping and broadcasting.

```bash
dune exec nx/examples/04-reshaping-and-broadcasting/main.exe
```

--------------------------------

### Execute Array Creation Example

Source: https://raven-ml.dev/docs/nx/examples/creating-arrays

Run the provided example project to see array creation in action.

```bash
dune exec nx/examples/01-creating-arrays/main.exe
```

--------------------------------

### Execute Training Example

Source: https://raven-ml.dev/docs/brot/examples/training

Run the training example using the dune build system.

```bash
dune exec brot/examples/09-training/main.exe
```

--------------------------------

### Run the indexing and slicing example

Source: https://raven-ml.dev/docs/nx/examples/indexing-and-slicing

Execute the provided example project to see indexing operations in action.

```bash
dune exec nx/examples/03-indexing-and-slicing/main.exe
```

--------------------------------

### Execute Example Program

Source: https://raven-ml.dev/docs/nx/examples/random-numbers

Command to run the random numbers example project.

```bash
dune exec nx/examples/06-random-numbers/main.exe
```

--------------------------------

### Run the BPE tokenizer example

Source: https://raven-ml.dev/docs/brot/examples/encode-decode

Execute the provided example program using the dune build system.

```bash
dune exec brot/examples/01-encode-decode/main.exe
```

--------------------------------

### Execute Padding and Truncation Example

Source: https://raven-ml.dev/docs/brot/examples/padding-truncation

Run the padding and truncation example using dune.

```shell
dune exec brot/examples/07-padding-truncation/main.exe
```

--------------------------------

### Execute Image Processing Example

Source: https://raven-ml.dev/docs/nx/examples/image-processing

Run the compiled example executable.

```bash
dune exec nx/examples/09-image-processing/main.exe
```

--------------------------------

### Install Fehu

Source: https://raven-ml.dev/docs/fehu/getting-started

Installation instructions for the Fehu library.

```bash
opam install fehu
```

```bash
git clone https://github.com/raven-ml/raven
cd raven && dune build fehu
```

--------------------------------

### Execute Normalization Example

Source: https://raven-ml.dev/docs/brot/examples/normalizers

Run the provided normalization example using the dune build system.

```bash
dune exec brot/examples/03-normalizers/main.exe
```

--------------------------------

### Execute GPT-2 Tokenizer Example

Source: https://raven-ml.dev/docs/brot/examples/x-gpt2-tokenizer

Run the example to download GPT-2 vocabulary and merges, build the BPE pipeline, and demonstrate encoding/decoding.

```shell
dune exec brot/examples/x-gpt2-tokenizer/main.exe

```

--------------------------------

### Execute Pre-tokenizer Example

Source: https://raven-ml.dev/docs/brot/examples/pre-tokenizers

This command executes a pre-tokenizer example using Dune.

```shell
dune exec brot/examples/04-pre-tokenizers/main.exe
```

--------------------------------

### Execute Reduction Example

Source: https://raven-ml.dev/docs/nx/examples/reductions-and-statistics

Command to run the reduction and statistics example project.

```bash
dune exec nx/examples/05-reductions-and-statistics/main.exe
```

--------------------------------

### Install Brot Library

Source: https://raven-ml.dev/docs/brot/getting-started

Commands to install the library via opam or build it from source.

```bash
opam install brot
```

```bash
git clone https://github.com/raven-ml/raven
cd raven && dune build brot
```

--------------------------------

### Execute Signal Processing Example

Source: https://raven-ml.dev/docs/nx/examples/signal-processing

Run the main executable for the signal processing example.

```shell
dune exec nx/examples/08-signal-processing/main.exe

```

--------------------------------

### Install hugin via opam

Source: https://raven-ml.dev/docs/hugin/getting-started

Standard installation command for the hugin package.

```bash
opam install hugin
```

--------------------------------

### Train XOR Classifier with Kaun

Source: https://raven-ml.dev/docs/kaun/getting-started

This example demonstrates training a small neural network to classify XOR inputs using Kaun. It covers dataset creation, model definition, trainer setup, training loop, and prediction.

```ocaml
open Kaun

let () =
  Nx.Rng.run ~seed:42 @@ fun () ->

  (* XOR dataset: 4 examples, 2 features each *)
  let x = Nx.create Nx.Float32 [| 4; 2 |] [| 0.; 0.; 0.; 1.; 1.; 0.; 1.; 1. |] in
  let y = Nx.create Nx.Float32 [| 4; 1 |] [| 0.; 1.; 1.; 0. |] in

  (* Model: 2 -> 4 -> 1 with tanh activation *)
  let model =
    Layer.sequential
      [
        Layer.linear ~in_features:2 ~out_features:4 ();
        Layer.tanh ();
        Layer.linear ~in_features:4 ~out_features:1 ();
      ]
  in

  (* Create a trainer: model + optimizer *)
  let trainer =
    Train.make ~model
      ~optimizer:(Optim.adam ~lr:(Optim.Schedule.constant 0.01) ())
  in

  (* Initialize training state (model vars + optimizer state) *)
  let st = Train.init trainer ~dtype:Nx.Float32 in

  (* Train for 1000 steps on the same data *)
  let st = 
    Train.fit trainer st
      ~report:(fun ~step ~loss _st ->
        if step mod 200 = 0 then
          Printf.printf "step %4d  loss %.6f\n" step loss) 
      (Data.repeat 1000 (x, fun pred -> Loss.binary_cross_entropy pred y))
  in

  (* Predict *)
  let pred = Train.predict trainer st x |> Nx.sigmoid in
  Printf.printf "\npredictions (expected 0 1 1 0):\n";
  for i = 0 to 3 do
    Printf.printf "  [%.0f, %.0f] -> %.3f\n"
      (Nx.item [ i; 0 ] x)
      (Nx.item [ i; 1 ] x)
      (Nx.item [ i; 0 ] pred)
  done

```

--------------------------------

### Install Raven Ecosystem via Opam

Source: https://raven-ml.dev/docs/installation

Install the entire Raven ML ecosystem using opam. This command fetches and installs all core Raven libraries.

```bash
opam install raven

```

--------------------------------

### Install Quill

Source: https://raven-ml.dev/docs/quill/getting-started

Install the package via opam or build directly from the source repository.

```bash
opam install quill
```

```bash
git clone https://github.com/raven-ml/raven
cd raven && dune build quill
```

--------------------------------

### Install Rune with Opam

Source: https://raven-ml.dev/docs/rune/getting-started

Use the opam package manager to install Rune. This is the recommended method for most users.

```bash
opam install rune
```

--------------------------------

### Array Creation Examples

Source: https://raven-ml.dev/docs/nx/examples/creating-arrays

Illustrative examples of creating different types of arrays using Nx functions.

```APIDOC
## Array Creation Examples

This section provides examples of how to create arrays using various Nx functions.

### Creating Arrays from Scratch

Build arrays from scratch — constants, ranges, grids, and custom data. This example walks through the most common ways to create arrays in Nx.

```bash
dune exec nx/examples/01-creating-arrays/main.exe
```

### Output Walkthrough

When you run this example, you'll see arrays printed in a compact format:

```
zeros (2×3):
[[0, 0, 0],
 [0, 0, 0]]

arange 0..9:
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

5×5 multiplication table:
[[1, 2, 3, 4, 5],
 [2, 4, 6, 8, 10],
 [3, 6, 9, 12, 15],
 [4, 8, 12, 16, 20],
 [5, 10, 15, 20, 25]]
```

The multiplication table is built with `init`, which calls a function with the index array for each element:

```ocaml
init int32 [| 5; 5 |] (fun idx ->
    Int32.of_int ((idx.(0) + 1) * (idx.(1) + 1)))
```

`meshgrid` builds a pair of 2D coordinate grids from two 1D arrays — useful for evaluating functions over a grid:

```
meshgrid X:
[[0, 1, 2],
 [0, 1, 2]]
meshgrid Y:
[[0, 0, 0],
 [1, 1, 1]]
```
```

--------------------------------

### Install Kaun via opam

Source: https://raven-ml.dev/docs/kaun/getting-started

Use this command to install the Kaun library using the opam package manager.

```bash
opam install kaun

```

--------------------------------

### Install Hugin Dependencies on Ubuntu/Debian

Source: https://raven-ml.dev/docs/hugin

Use apt to install the Cairo and SDL2 development libraries, necessary for Hugin.

```bash
# Ubuntu/Debian
apt install libcairo2-dev libsdl2-dev
```

--------------------------------

### Execute Linear Algebra Example

Source: https://raven-ml.dev/docs/nx/examples/linear-algebra

Command to run the linear algebra demonstration project.

```bash
dune exec nx/examples/07-linear-algebra/main.exe
```

--------------------------------

### Install Sowilo using Opam

Source: https://raven-ml.dev/docs/sowilo/getting-started

Use this command to install Sowilo via the Opam package manager.

```bash
opam install sowilo
```

--------------------------------

### Install Kaun Board

Source: https://raven-ml.dev/docs/kaun/kaun-board

Install the kaun-board package using opam. Add `kaun` and `kaun-board` to your dune file's libraries.

```bash
opam install kaun-board

```

```dune
(executable
 (name main)
 (libraries kaun kaun-board))

```

--------------------------------

### Execute Encoding Example

Source: https://raven-ml.dev/docs/brot/examples/encoding-fields

Command to run the encoding demonstration via dune.

```bash
dune exec brot/examples/02-encoding-fields/main.exe
```

--------------------------------

### Execute BERT Pipeline Example

Source: https://raven-ml.dev/docs/brot/examples/bert-pipeline

Command to run the BERT pipeline example using dune.

```bash
dune exec brot/examples/10-bert-pipeline/main.exe
```

--------------------------------

### Optimizer Examples

Source: https://raven-ml.dev/docs/kaun/training

Examples of common optimizers like SGD with momentum, Adam, AdamW, RMSprop, and Adagrad. Each optimizer requires a learning-rate schedule.

```ocaml
(* SGD with momentum *)
Optim.sgd ~lr:(Optim.Schedule.constant 0.1) ~momentum:0.9 ()
```

```ocaml
(* Adam *)
Optim.adam ~lr:(Optim.Schedule.constant 1e-3) ()
```

```ocaml
(* AdamW with weight decay *)
Optim.adamw ~lr:(Optim.Schedule.constant 1e-3) ~weight_decay:0.01 ()
```

```ocaml
(* RMSprop *)
Optim.rmsprop ~lr:(Optim.Schedule.constant 1e-3) ()
```

```ocaml
(* Adagrad *)
Optim.adagrad ~lr:(Optim.Schedule.constant 0.01) ()
```

--------------------------------

### Install Raven ML using Opam

Source: https://raven-ml.dev/docs/nx/getting-started

Use this command to install the nx package via Opam.

```bash
opam install nx

```

--------------------------------

### Example of fixed-data training

Source: https://raven-ml.dev/docs/kaun/api/Kaun/Train

Demonstrates how to use `Data.repeat` with `Train.fit` for training with the same input data at each step.

```ocaml
  Train.fit trainer st (Data.repeat 1000 (x, loss_fn))
```

--------------------------------

### Reset Environment

Source: https://raven-ml.dev/docs/fehu/gymnasium-comparison

Demonstrates how to reset an environment and get initial observations and info.

```python
obs, info = env.reset(seed=42)
```

```ocaml
let (obs, info) = Env.reset env ()
```

--------------------------------

### Watch Mode Output Example

Source: https://raven-ml.dev/docs/quill/execution-modes

Example of the timestamped output printed when a file change is detected in watch mode.

```text
[14:32:05] File changed, re-evaluating...
```

--------------------------------

### Full Random Numbers Example

Source: https://raven-ml.dev/docs/nx/examples/random-numbers

A comprehensive example demonstrating dice simulation, distributions, Monte Carlo estimation, synthetic data generation, reproducibility, and shuffling.

```ocaml
(** Implicit RNG with reproducible scopes — generate distributions, sample, and
    shuffle.

    Roll dice, estimate pi with Monte Carlo, and generate noisy training data.
    Every result is reproducible inside an [Rng.run] scope: same seed, same
    numbers. Outside any scope the global fallback provides convenient but
    non-reproducible randomness. *)

open Nx
open Nx.Infix

let () =
  (* --- Dice simulation: roll 10 six-sided dice --- *)
  let dice = randint Int32 ~high:7 [| 10 |] 1 in
  Printf.printf "10 dice rolls: %s\n\n" (data_to_string dice);

  (* --- Uniform random floats in [0, 1) --- *)
  let uniform = rand Float64 [| 5 |] in
  Printf.printf "Uniform [0,1): %s\n\n" (data_to_string uniform);

  (* --- Normal distribution (mean=0, std=1) --- *)
  let normal = randn Float64 [| 5 |] in
  Printf.printf "Normal(0,1):   %s\n\n" (data_to_string normal);

  (* --- Monte Carlo pi estimation ---

     Drop N random points in a unit square. The fraction landing inside the unit
     circle (distance from origin < 1) approximates pi/4. *)
  let n = 100_000 in
  let xs = rand float64 [| n |] in
  let ys = rand float64 [| n |] in
  let inside = less_s ((xs * xs) + (ys * ys)) 1.0 in
  let count = sum (cast Float64 inside) in
  let pi_est = item [] count *. 4.0 /. Float.of_int n in
  Printf.printf "Monte Carlo pi (%d points): %.4f  (actual: %.4f)\n\n" n pi_est
    Float.pi;

  (* --- Synthetic training data: y = 3x + 2 + noise --- *)
  let x = rand Float64 [| 8 |] in
  let noise = randn Float64 [| 8 |] *$ 0.1 in
  let y = (x *$ 3.0) +$ 2.0 + noise in
  Printf.printf "x:     %s\n" (data_to_string x);
  Printf.printf "y ~ 3x+2: %s\n\n" (data_to_string y);

  (* --- Reproducibility: Rng.run ~seed gives the same result --- *)
  let a = Rng.run ~seed:99 (fun () -> randn Float64 [| 3 |]) in
  let b = Rng.run ~seed:99 (fun () -> randn Float64 [| 3 |]) in
  Printf.printf "Same seed, run 1: %s\n" (data_to_string a);
  Printf.printf "Same seed, run 2: %s\n" (data_to_string b);
  Printf.printf "Identical? %b\n\n" (item [] (all (equal a b)));

  (* --- Shuffle: random permutation of a dataset --- *)
  let data = arange int32 0 8 1 in
  let shuffled = shuffle data in
  Printf.printf "Original:  %s\n" (data_to_string data);
  Printf.printf "Shuffled:  %s\n" (data_to_string shuffled)
```

--------------------------------

### Run Tokenization Algorithm Comparison

Source: https://raven-ml.dev/docs/brot/examples/algorithms

Executes the main example program for comparing tokenization algorithms.

```shell
dune exec brot/examples/05-algorithms/main.exe

```

--------------------------------

### Install system dependencies

Source: https://raven-ml.dev/docs/hugin/getting-started

Required system-level libraries for macOS and Ubuntu/Debian environments.

```bash
# macOS
brew install cairo sdl2

# Ubuntu/Debian
apt install libcairo2-dev libsdl2-dev
```

--------------------------------

### Initialize and Step a CartPole Environment in Fehu

Source: https://raven-ml.dev/docs/ecosystem-overview

Demonstrates basic environment setup and a single step execution using a sampled action.

```OCaml
open Fehu

let env = Fehu_envs.cartpole () in
let obs, _info = Env.reset env in
let obs, reward, terminated, truncated, _info =
  Env.step env (Space.sample (Env.action_space env))
```

--------------------------------

### make

Source: https://raven-ml.dev/docs/fehu/api/Fehu_envs/Random_walk

Initializes the random walk environment.

```APIDOC
## make

### Description
Initializes a new instance of the one-dimensional random walk environment.

### Parameters
#### Optional Parameters
- **render_mode** (Fehu.Env.render_mode) - Optional - The rendering mode for the environment (e.g., 'ansi').

### Request Example
make ~render_mode:`ansi` ()

### Response
- **env** ((obs, act, render) Fehu.Env.t) - The initialized environment instance.
```

--------------------------------

### Create Environment

Source: https://raven-ml.dev/docs/fehu/gymnasium-comparison

Compares environment creation syntax between Gymnasium/SB3 and Fehu.

```python
gym.make("CartPole-v1")
```

```ocaml
Env.create ~observation_space ~action_space ~reset ~step ()
```

--------------------------------

### Quick Start Image Processing Pipeline

Source: https://raven-ml.dev/docs/sowilo

Demonstrates loading an image, applying grayscale conversion, Gaussian blur, and Canny edge detection, then saving the result.

```OCaml
open Sowilo

let () =
  (* Load image and convert to float32 [0, 1] *)
  let img = Nx_io.load_image "photo.png" |> to_float in

  (* Process: grayscale, blur, edge detection *)
  let edges =
    img
    |> to_grayscale
    |> gaussian_blur ~sigma:1.0
    |> canny ~low:0.2 ~high:0.6
  in

  (* Save result *)
  Nx_io.save_image (to_uint8 edges) "edges.png"
```

--------------------------------

### Demonstrate Composed Pre-tokenizers

Source: https://raven-ml.dev/docs/brot/examples/pre-tokenizers

Illustrates how to compose multiple pre-tokenizers using `Pre_tokenizer.sequence`. This example chains whitespace splitting with punctuation isolation.

```ocaml
Printf.printf "=== Composition ===\n\n";

let composed = 
  Pre_tokenizer.sequence
    [
      Pre_tokenizer.whitespace_split ();
      Pre_tokenizer.punctuation ~behavior:`Isolated ();
    ]
inshow "whitespace + punctuation" composed text
```

--------------------------------

### Tokenize, Build, and Train a Model with Raven Libraries

Source: https://raven-ml.dev/docs/brot/examples/01-encode-decode

Demonstrates tokenizing text using Brot, building a neural network model with Kaun, and initiating training with Rune's automatic differentiation. Ensure 'tokenizer.json' exists and 'train_data' is defined.

```ocaml
open Kaun

(* Tokenize text with Brot *)
let tokenizer = Brot.from_file "tokenizer.json" |> Result.get_ok
let encode text = Brot.encode_ids tokenizer text

(* Build a model with Kaun *)
let model = Layer.sequential [
  Layer.embedding ~vocab_size:30522 ~embed_dim:128 ();
  Layer.relu ();
  Layer.linear ~in_features:128 ~out_features:2 ();
]

(* Train with automatic differentiation — Rune under the hood *)
let trainer = Train.make ~model
  ~optimizer:(Optim.adam ~lr:(Optim.Schedule.constant 1e-3) ())
let st = Train.init trainer ~dtype:Nx.Float32
let st = Train.fit trainer st train_data

```

--------------------------------

### Build Kaun from Source

Source: https://raven-ml.dev/docs/kaun/getting-started

Clone the Raven ML repository and build the Kaun library from source.

```bash
git clone https://github.com/raven-ml/raven
cd raven && dune build kaun

```

--------------------------------

### Learning-Rate Schedule Examples

Source: https://raven-ml.dev/docs/kaun/training

Demonstrates various learning-rate schedules including constant, cosine decay, linear warmup, cosine warmup, and exponential decay. These map step numbers to learning rates.

```ocaml
(* Fixed learning rate *)
Optim.Schedule.constant 1e-3
```

```ocaml
(* Cosine decay from 1e-3 to 0 over 10000 steps *)
Optim.Schedule.cosine_decay ~init_value:1e-3 ~decay_steps:10000 ()
```

```ocaml
(* Cosine decay with minimum alpha *)
Optim.Schedule.cosine_decay ~init_value:1e-3 ~decay_steps:10000 ~alpha:1e-5 ()
```

```ocaml
(* Linear warmup from 0 to 1e-3 over 1000 steps *)
Optim.Schedule.warmup_linear ~init_value:0. ~peak_value:1e-3 ~warmup_steps:1000
```

```ocaml
(* Cosine warmup *)
Optim.Schedule.warmup_cosine ~init_value:0. ~peak_value:1e-3 ~warmup_steps:1000
```

```ocaml
(* Exponential decay *)
Optim.Schedule.exponential_decay ~init_value:1e-3 ~decay_rate:0.96 ~decay_steps:1000
```

--------------------------------

### Load Pretrained Model Weights and Configuration

Source: https://raven-ml.dev/docs/kaun/checkpoints-and-pretrained

Demonstrates the typical workflow for loading pretrained weights: build model from config, initialize parameters, load weights, map them to the parameter tree, and prepare for inference.

```ocaml
(* 1. Build model from config *)
let config = Kaun_hf.load_config ~model_id:"bert-base-uncased" () in
let model = build_bert_model config in

(* 2. Initialize to get tree structure *)
let vars = Layer.init model ~dtype:Nx.Float32 in

(* 3. Load and map weights *)
let weights = Kaun_hf.load_weights ~model_id:"bert-base-uncased" () in
let params = map_weights_to_ptree weights (Layer.params vars) in
let vars = Layer.with_params vars params in

(* 4. Use for inference *)
let trainer = Train.make ~model
  ~optimizer:(Optim.adam ~lr:(Optim.Schedule.constant 1e-5) ())
in
let st = Train.make_state trainer vars in
let logits = Train.predict trainer st input_ids
```

--------------------------------

### Install Hugin Dependencies on macOS

Source: https://raven-ml.dev/docs/hugin

Use Homebrew to install Cairo and SDL2, required for Hugin rendering and display.

```bash
# macOS
brew install cairo sdl2
```

--------------------------------

### Creating a BPE Tokenizer from Scratch

Source: https://raven-ml.dev/docs/brot/api/Brot

Illustrates how to create a Byte Pair Encoding (BPE) tokenizer with a custom vocabulary and no merges.

```APIDOC
## Create BPE Tokenizer from Scratch

### Description
Creates a BPE tokenizer with a predefined vocabulary and an empty set of merges. It then encodes and decodes a sample text.

### Method
`Brot.bpe` followed by `Brot.encode` and `Brot.decode`

### Endpoint
N/A (In-memory operation)

### Parameters
#### Request Body
- **vocab** (list of (string * int)) - Required - A list of token-vocabulary pairs.
- **merges** (list) - Optional - A list of merge rules (empty in this example).

### Request Example
```ocaml
let tokenizer = Brot.bpe ~vocab:[("hello", 0); ("world", 1); ("[PAD]", 2)] ~merges:[] ()
in let encoding = Brot.encode tokenizer "hello world"
let _text = Brot.decode tokenizer (Encoding.ids encoding)
```

### Response
#### Success Response (200)
- **tokenizer** (Brot.t) - The created BPE tokenizer.
- **encoding** (Encoding.t) - The result of encoding "hello world".
- **_text** (string) - The result of decoding the token IDs back to text.

#### Response Example
(Output depends on the vocabulary and input text)
```

--------------------------------

### Build hugin from source

Source: https://raven-ml.dev/docs/hugin/getting-started

Commands to clone the repository and build the project using dune.

```bash
git clone https://github.com/raven-ml/raven
cd raven
dune pkg lock && dune build hugin
```

--------------------------------

### Implement PPO training iteration

Source: https://raven-ml.dev/docs/fehu/collection-and-evaluation

A standard workflow combining rollout collection, advantage computation, and policy evaluation.

```OCaml
open Fehu

(* 1. Collect rollout *)
let trajectory = Collect.rollout env
  ~policy:(fun obs ->
    let act, log_prob, value = nn_policy obs in
    (act, Some log_prob, Some value))
  ~n_steps:2048

(* 2. Compute advantages *)
let last_value = estimate_value model last_obs in
let advantages, returns = Gae.compute_from_values
  ~rewards:trajectory.rewards
  ~values:(Option.get trajectory.values)
  ~terminated:trajectory.terminated
  ~truncated:trajectory.truncated
  ~last_value
  ~gamma:0.99 ~lambda:0.95

let advantages = Gae.normalize advantages

(* 3. Update policy using trajectory data + advantages *)
(* ... your PPO update here ... *)

(* 4. Evaluate *)
let stats = Eval.run env
  ~policy:(fun obs -> greedy_action model obs)
  ~n_episodes:10 ()
```

--------------------------------

### Loss Function Examples

Source: https://raven-ml.dev/docs/kaun/training

Examples of common loss functions for multi-class classification (cross-entropy, sparse cross-entropy), binary classification, and regression (MSE, MAE).

```ocaml
(* Multi-class: logits [batch; num_classes], one-hot labels [batch; num_classes] *)
Loss.cross_entropy logits one_hot_labels
```

```ocaml
(* Multi-class with integer labels: logits [batch; num_classes], labels [batch] *)
Loss.cross_entropy_sparse logits class_indices
```

```ocaml
(* Binary: raw logits (not sigmoid), labels in {0, 1} *)
Loss.binary_cross_entropy logits labels
```

```ocaml
(* Regression *)
Loss.mse predictions targets
```

```ocaml
Loss.mae predictions targets
```

--------------------------------

### Get Sub-tensor using Indexing

Source: https://raven-ml.dev/docs/nx/array-operations

Extract a sub-tensor (view) from a tensor using `get` by indexing from the outermost dimension inward. This operation does not create a copy.

```ocaml
open Nx

let () = 
  let x = create Int32 [|2; 3|] [|1l; 2l; 3l; 4l; 5l; 6l|] in
  let row = get [1] x in      (* second row: [4, 5, 6] *)
  print_data row

```

--------------------------------

### Install Hugin System Dependencies

Source: https://raven-ml.dev/docs/installation

Install system dependencies for the Hugin library on macOS using Homebrew or on Ubuntu/Debian using apt. Hugin requires Cairo and SDL2.

```bash
brew install cairo sdl2

```

```bash
apt install libcairo2-dev libsdl2-dev

```

--------------------------------

### Create Triangular Matrices in Nx

Source: https://raven-ml.dev/docs/nx/examples/creating-arrays

Use `tril` to get the lower triangle of a matrix and `triu` to get the upper triangle. These functions preserve the original matrix shape.

```ocaml
open Nx

let () = 
  let m = ones float64 [| 4; 4 |] in
  Printf.printf "tril (lower triangle):\n%s\n" (data_to_string (tril m));
  Printf.printf "triu (upper triangle):\n%s\n" (data_to_string (triu m))
```

--------------------------------

### Try It Yourself

Source: https://raven-ml.dev/docs/nx/examples/creating-arrays

Exercises to practice creating arrays using different Nx functions.

```APIDOC
## Try It Yourself

1. Create a 10-element `linspace` from -1.0 to 1.0 and print it.
2. Use `init` to build a 4×4 matrix where each element is the sum of its row and column index.
3. Try `eye ~k:(-1) float64 4` to see the subdiagonal.
```

--------------------------------

### Create Geometrically Spaced Values

Source: https://raven-ml.dev/docs/nx/api/Nx

Generates geometrically spaced values between a start and stop point. Ensures that the ratio between consecutive elements is constant. Raises Invalid_argument if start or stop is not positive.

```text
# geomspace float32 1. 1000. 4
  - : (float, float32_elt) t = [1, 10, 100, 1000]
```

--------------------------------

### Get DataFrame Column Names and Types in Pandas

Source: https://raven-ml.dev/docs/talon/pandas-comparison

Access column names using `df.columns` and data types with `df.dtypes`. Check DataFrame emptiness with `df.empty` and get the number of rows with `len(df)`.

```python
df.columns
df.dtypes
len(df)
df.empty
```

--------------------------------

### Create Range Tensor (Floats)

Source: https://raven-ml.dev/docs/nx/api/Nx

Similar to `arange`, but for floating-point numbers. It generates a 1-D tensor with values starting from `start`, incrementing by `step`, up to (but not including) `stop`. A step of 0.0 will raise an Invalid_argument error.

```ocaml
# arange_f float32 0. 1. 0.2
- : (float, float32_elt) t = [0, 0.2, 0.4, 0.6, 0.8]
```

--------------------------------

### Build Sowilo from Source

Source: https://raven-ml.dev/docs/sowilo/getting-started

Clone the repository and build Sowilo from source using Dune.

```bash
git clone https://github.com/raven-ml/raven
cd raven && dune build sowilo
```

--------------------------------

### Install Individual Raven Libraries via Opam

Source: https://raven-ml.dev/docs/installation

Install specific Raven ML libraries individually using opam. Choose libraries based on your project's needs, such as 'nx' for arrays or 'kaun' for neural networks.

```bash
opam install nx          # just arrays
opam install rune        # arrays + autodiff
opam install kaun        # arrays + autodiff + neural networks
opam install brot        # tokenization
opam install talon       # dataframes

```

--------------------------------

### GET /tensor/get

Source: https://raven-ml.dev/docs/nx/api/Nx

Retrieves a sub-tensor at specified indices.

```APIDOC
## GET /tensor/get

### Description
Retrieves the sub-tensor at the provided indices, indexing from the outermost dimension inward. Returns a scalar tensor if all dimensions are indexed, otherwise returns a view.

### Parameters
#### Path Parameters
- **indices** (int list) - Required - The list of indices to access.
- **t** (('a, 'b) t) - Required - The source tensor.
```

--------------------------------

### Build Image Processing Pipeline

Source: https://raven-ml.dev/docs/sowilo/getting-started

Demonstrates building a processing pipeline by chaining operations using the `|>` operator. This example loads an image, converts it to grayscale, applies a Gaussian blur, and then detects edges using the Canny algorithm. Finally, it saves the resulting edge map.

```ocaml
open Sowilo

let () =
  let img = Nx_io.load_image "photo.png" |> to_float in

  let edges =
    img
    |> to_grayscale                  (* RGB -> single channel *)
    |> gaussian_blur ~sigma:1.0      (* smooth noise *)
    |> canny ~low:0.2 ~high:0.6     (* detect edges *)
  in

  (* Save: convert back to uint8, then to Nx for I/O *)
  Nx_io.save_image (to_uint8 edges) "edges.png"
```

--------------------------------

### Logical All Operation

Source: https://raven-ml.dev/docs/nx/api/Nx

Examples of checking if all elements in a tensor are non-zero.

```OCaml
  # create int32 [| 3 |] [| 1l; 2l; 3l |]
    |> all |> item []
  - : bool = true
  # create int32 [| 3 |] [| 1l; 0l; 3l |]
    |> all |> item []
  - : bool = false
```

--------------------------------

### Initialize Available Environments

Source: https://raven-ml.dev/docs/fehu/getting-started

Factory methods for built-in environments.

```ocaml
let env = Fehu_envs.Cartpole.make ()
```

```ocaml
let env = Fehu_envs.Mountain_car.make ()
```

```ocaml
let env = Fehu_envs.Grid_world.make ()
```

```ocaml
let env = Fehu_envs.Random_walk.make ()
```

--------------------------------

### Calculating Mean

Source: https://raven-ml.dev/docs/nx/api/Nx

Example of calculating the arithmetic mean of a tensor.

```OCaml
  # create float32 [| 4 |] [| 1.; 2.; 3.; 4. |]
    |> mean |> item []
  - : float = 2.5
```

--------------------------------

### Calculating Product

Source: https://raven-ml.dev/docs/nx/api/Nx

Example of calculating the product of elements in a tensor.

```OCaml
  # create int32 [| 3 |] [| 2l; 3l; 4l |]
    |> prod |> item []
  - : int32 = 24l
```

--------------------------------

### Main Execution: GPT-2 Text Generation

Source: https://raven-ml.dev/docs/kaun/examples/gpt2

Initializes the GPT-2 model and tokenizer, then demonstrates next-token prediction for 'Hello world' and generates text continuations for several prompts using greedy decoding.

```ocaml
let () =
  let model_id = "gpt2" in
  let dtype = Nx.float32 in

  (* Load tokenizer and model *)
  Printf.printf "Loading %s...\n%!" model_id;
  let tokenizer = load_tokenizer model_id in
  let cfg, params = Gpt2.from_pretrained ~model_id () in
  Printf.printf "  vocab=%d  n_embd=%d  layers=%d  heads=%d\n\n" cfg.vocab_size
    cfg.n_embd cfg.n_layer cfg.n_head;

  let model = Gpt2.for_causal_lm cfg () in
  let vars = Layer.make_vars ~params ~state:Ptree.empty ~dtype in

  (* --- What does the model predict after "Hello world"? --- *)
  Printf.printf "=== Next-token predictions ===\n";
  Printf.printf "  Prompt: \"Hello world\"\n";
  Printf.printf "  Top 5 continuations:\n";
  let hello_ids = encode tokenizer "Hello world" in
  let hello = Nx.create Nx.int32 [| 1; Array.length hello_ids |] hello_ids in
  print_top_k ~k:5 model vars hello ~pos:(Array.length hello_ids - 1);

  (* --- Greedy generation from several prompts --- *)
  Printf.printf "\n=== Greedy generation (30 tokens each) ===\n\n";
  let prompts =
    [ "The meaning of life is"; "Once upon a time"; "The quick brown fox" ]
  in
  List.iter
    (fun text ->
      let prompt = encode tokenizer text in
      let generated = generate model vars ~max_tokens:30 prompt in
      let continuation =
        Array.sub generated (Array.length prompt)
          (Array.length generated - Array.length prompt)
      in
      Printf.printf "  \"%s\" ->\n" text;
      Printf.printf "    %s\n\n" (decode tokenizer continuation))
    prompts

```

--------------------------------

### Sample Operation

Source: https://raven-ml.dev/docs/talon/api/Talon

Get a random sample of rows from a dataframe.

```APIDOC
## SAMPLE

### Description
Returns a random sample of rows from the dataframe. Exactly one of `n` (exact number) or `frac` (fraction) must be specified.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
- **n** (int) - Optional - Exact number of rows to sample
- **frac** (float) - Optional - Fraction of rows to sample (between 0.0 and 1.0)
- **replace** (bool) - Optional - If true, sample with replacement (default: false)
- **seed** (int) - Optional - Random seed for reproducible sampling

### Request Example
```
let df = create [("id", Col.int32 [|1l; 2l; 3l; 4l; 5l|])]
let sample1 = sample df ~n:3 ~seed:42 ()
let sample2 = sample df ~frac:0.6 ()
```

### Response
#### Success Response (200)
- **dataframe** (t) - The dataframe containing the random sample of rows.

#### Response Example
```json
{
  "dataframe": "..."
}
```

### Error Handling
- **Invalid_argument**: if both `n` and `frac` are specified, or neither, or if `frac` is outside `0, 1`, or if `n` > rows when `replace=false`.
```

--------------------------------

### Get a sub-tensor using indices

Source: https://raven-ml.dev/docs/nx/api/Nx

Use `get` to extract a sub-tensor by specifying indices from the outermost dimension inward. Returns a scalar tensor if all dimensions are indexed, otherwise a view of the remaining dimensions. Negative indices count from the end. Raises `Invalid_argument` if any index is out of bounds.

```ocaml
let x =
  create int32 [| 2; 3 |]
    [| 1l; 2l; 3l; 4l; 5l; 6l |]
in
get [ 1 ] x
```

--------------------------------

### Train a model on the XOR problem

Source: https://raven-ml.dev/docs/kaun

Demonstrates the basic workflow of defining a sequential model, initializing a trainer with an optimizer, and fitting the model to data.

```ocaml
open Kaun

let () =
  Nx.Rng.run ~seed:42 @@ fun () ->
  let x = Nx.create Nx.Float32 [| 4; 2 |] [| 0.; 0.; 0.; 1.; 1.; 0.; 1.; 1. |] in
  let y = Nx.create Nx.Float32 [| 4; 1 |] [| 0.; 1.; 1.; 0. |] in

  let model = Layer.sequential [
    Layer.linear ~in_features:2 ~out_features:4 ();
    Layer.tanh ();
    Layer.linear ~in_features:4 ~out_features:1 ();
  ] in

  let trainer = Train.make ~model
    ~optimizer:(Optim.adam ~lr:(Optim.Schedule.constant 0.01) ())
  in
  let st = Train.init trainer ~dtype:Nx.Float32 in
  let st = Train.fit trainer st
    (Data.repeat 1000 (x, fun pred -> Loss.binary_cross_entropy pred y))
  in
  let pred = Train.predict trainer st x |> Nx.sigmoid in
  for i = 0 to 3 do
    Printf.printf "[%.0f, %.0f] -> %.3f\n"
      (Nx.item [ i; 0 ] x) (Nx.item [ i; 1 ] x) (Nx.item [ i; 0 ] pred)
  done
```

--------------------------------

### Finding Argmax

Source: https://raven-ml.dev/docs/nx/api/Nx

Example of finding the index of the maximum value in a tensor.

```OCaml
  # create int32 [| 5 |] [| 3l; 1l; 4l; 1l; 5l |]
    |> argmax |> item []
  - : int32 = 4l
```

--------------------------------

### Finding Maximum Value

Source: https://raven-ml.dev/docs/nx/api/Nx

Example of finding the maximum value in a tensor.

```OCaml
  # create float32 [| 2; 3 |]
      [| 1.; 2.; 3.; 4.; 5.; 6. |]
    |> max |> item []
  - : float = 6.
```

--------------------------------

### Implement BPE tokenization in OCaml

Source: https://raven-ml.dev/docs/brot/examples/encode-decode

A complete example showing the creation of a BPE tokenizer, encoding text, and performing a round-trip decode.

```ocaml
(* Encode and decode.

   The simplest possible tokenization: convert text to token IDs and back.
   Demonstrates creating a BPE tokenizer from an inline vocabulary and merge
   rules, encoding text, inspecting tokens and IDs, and decoding. *)

open Brot

let () =
  (* Build a small BPE tokenizer. The vocabulary maps token strings to IDs.
     Merge rules define which character pairs to combine, in priority order. *)
  let vocab =
    [
      ("h", 0);
      ("e", 1);
      ("l", 2);
      ("o", 3);
      (" ", 4);
      ("w", 5);
      ("r", 6);
      ("d", 7);
      ("he", 8);
      ("ll", 9);
      ("llo", 10);
      ("hello", 11);
      ("wo", 12);
      ("rl", 13);
      ("rld", 14);
      ("world", 15);
    ]
  in
  let merges =
    [
      ("h", "e");
      ("l", "l");
      ("ll", "o");
      ("he", "llo");
      ("w", "o");
      ("r", "l");
      ("rl", "d");
      ("wo", "rld");
    ]
  in
  let tokenizer = bpe ~vocab ~merges () in

  (* Encode text into an Encoding *)
  let text = "hello world" in
  let encoding = encode tokenizer text in
  let ids = Encoding.ids encoding in
  let tokens = Encoding.tokens encoding in

  Printf.printf "Text:    %S\n" text;
  Printf.printf "Tokens:  [%s]\n"
    (String.concat "; "
       (List.map (fun s -> Printf.sprintf "%S" s) (Array.to_list tokens)));
  Printf.printf "IDs:     [%s]\n"
    (String.concat "; " (Array.to_list (Array.map string_of_int ids)));

  (* Decode token IDs back to text *)
  let decoded = decode tokenizer ids in
  Printf.printf "Decoded: %S\n\n" decoded;

  Printf.printf "Round-trip matches: %b\n\n" (String.equal text decoded);

  (* Try another text -- unknown characters become individual tokens *)
  let text2 = "hello" in
  let enc2 = encode tokenizer text2 in
  Printf.printf "Text:    %S\n" text2;
  Printf.printf "Tokens:  [%s]\n"
    (String.concat "; "
       (List.map
          (fun s -> Printf.sprintf "%S" s)
          (Array.to_list (Encoding.tokens enc2))));
  Printf.printf "IDs:     [%s]\n"
    (String.concat "; " (Array.to_list (Array.map string_of_int (Encoding.ids enc2))))
```

--------------------------------

### Create and Initialize Arrays in Nx

Source: https://raven-ml.dev/docs/nx/getting-started

Demonstrates various ways to create arrays, including from explicit values, filled arrays, ranges, sequences, random arrays, and special matrices like identity.

```ocaml
open Nx

let () =
  (* From explicit values: provide dtype, shape, and flat data *)
  let a = create Float32 [|2; 3|] [|1.; 2.; 3.; 4.; 5.; 6.|] in
  print_data a;

  (* Filled arrays *)
  let z = zeros Float32 [|3; 3|] in
  let o = ones Int32 [|5|] in
  let f = full Float64 [|2; 2|] 3.14 in
  ignore (z, o, f);

  (* Ranges and sequences *)
  let r = arange Int32 0 10 1 in          (* [0, 1, ..., 9] *)
  let l = linspace Float32 0. 1. 5 in     (* 5 points in [0, 1] *)
  ignore (r, l);

  (* Random arrays *)
  let x = rand Float32 [|3; 4|] in
  let y = randn Float32 [|3; 4|] in
  ignore (x, y);

  (* Special matrices *)
  let i = eye Float32 3 in               (* 3×3 identity *)
  print_data i

```

--------------------------------

### Get Trajectory Length

Source: https://raven-ml.dev/docs/fehu/api/Fehu/Collect

Returns the number of transitions in a given trajectory.

```ocaml
val length : ('obs, 'act) t -> int
```

--------------------------------

### Create Environments

Source: https://raven-ml.dev/docs/fehu/gymnasium-comparison

Instantiate environments using a registry or direct constructor.

```python
env = gym.make("CartPole-v1", render_mode="human")
```

```ocaml
let env =
  Env.create
    ~id:"CartPole-v1"
    ~observation_space:(Space.Box.create
      ~low:[| -4.8; Float.neg_infinity; -0.418; Float.neg_infinity |]
      ~high:[| 4.8; Float.infinity; 0.418; Float.infinity |])
    ~action_space:(Space.Discrete.create 2)
    ~render_mode:`Human
    ~render_modes:["human"; "rgb_array"]
    ~reset:(fun _env ?options:_ () ->
      let obs = (* initial state *) in
      (obs, Info.empty))
    ~step:(fun _env action ->
      let obs = (* next state *) in
      Env.step_result ~observation:obs ~reward:1.0 ())
    ()
```

--------------------------------

### Calculate element-wise sign

Source: https://raven-ml.dev/docs/nx/api/Nx

Example of determining the sign of elements in a float32 tensor.

```ocaml
  # create float32 [| 3 |] [| -2.; 0.; 3.5 |]
    |> sign
  - : (float, float32_elt) t = [-1, 0, 1]
```
Tokens:
Raw