trashpanda 0.1.0

A Rust library for contextual multi-armed bandits
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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

# TrashPanda 🦝

[![Crates.io](https://img.shields.io/crates/v/trashpanda)](https://crates.io/crates/trashpanda)
[![docs.rs](https://img.shields.io/docsrs/trashpanda)](https://docs.rs/trashpanda)
[![CI](https://github.com/mjkoo/trashpanda/actions/workflows/test.yml/badge.svg)](https://github.com/mjkoo/trashpanda/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/mjkoo/trashpanda/branch/main/graph/badge.svg)](https://codecov.io/gh/mjkoo/trashpanda)
[![GitHub License](https://img.shields.io/github/license/mjkoo/trashpanda)](LICENSE-MIT)


A high-performance Rust implementation of contextual multi-armed bandits, inspired by Python's [MABWiser](https://github.com/fidelity/mabwiser) library.

TrashPanda provides a type-safe, memory-efficient framework for implementing multi-armed bandit algorithms with excellent performance characteristics. It offers both contextual and non-contextual bandit algorithms with a clean, idiomatic Rust API.

## Algorithms

### Non-Contextual Bandits
- **Random**: Uniform random selection (baseline)
- **Epsilon-Greedy**: Classic exploration-exploitation trade-off
- **UCB (Upper Confidence Bound)**: Optimism in the face of uncertainty
- **Thompson Sampling**: Bayesian approach with Beta distributions

### Contextual Bandits
- **LinUCB**: Linear Upper Confidence Bound for contextual problems
- **LinGreedy**: Contextual epsilon-greedy with linear reward modeling
- **LinTS**: Linear Thompson Sampling with posterior sampling

## Installation

Add TrashPanda to your `Cargo.toml`:

```toml
[dependencies]
trashpanda = "0.1.0"
```

## Quick Start

### Non-Contextual Bandit

```rust
use trashpanda::{Bandit, policies::EpsilonGreedy};
use rand::thread_rng;

// Create a bandit with three arms
let mut bandit = Bandit::new(
    vec!["red", "green", "blue"],
    EpsilonGreedy::new(0.1)
).unwrap();

// Train with historical data
let decisions = vec!["red", "blue", "red"];
let rewards = vec![1.0, 0.5, 0.8];
bandit.fit_simple(&decisions, &rewards).unwrap();

// Make a prediction
let mut rng = thread_rng();
let choice = bandit.predict_simple(&mut rng).unwrap();
println!("Recommended arm: {}", choice);

// Get expected rewards for all arms
let expectations = bandit.predict_expectations_simple(&mut rng);
for (arm, reward) in expectations {
    println!("{}: {:.3}", arm, reward);
}
```

### Contextual Bandit

```rust
use trashpanda::{Bandit, policies::LinUcb};
use rand::thread_rng;

// Create a contextual bandit
let mut bandit = Bandit::new(
    vec!["ad_1", "ad_2", "ad_3"],
    LinUcb::new(1.0, 1.0, 2)  // alpha, l2_reg, context_dim
).unwrap();

// Train with contexts and rewards
let contexts = vec![
    vec![1.0, 0.0],
    vec![0.0, 1.0],
    vec![0.5, 0.5],
];
let decisions = vec!["ad_1", "ad_2", "ad_1"];
let rewards = vec![1.0, 0.8, 0.6];

for ((context, decision), reward) in contexts.iter()
    .zip(decisions.iter())
    .zip(rewards.iter()) 
{
    bandit.partial_fit(decision, context, *reward).unwrap();
}

// Make predictions with new context
let mut rng = thread_rng();
let new_context = vec![0.7, 0.3];
let choice = bandit.predict(&new_context, &mut rng).unwrap();
println!("Recommended ad: {}", choice);
```

### Batch Operations

```rust
use trashpanda::Bandit;
use trashpanda::policies::EpsilonGreedy;
use rand::thread_rng;

let mut bandit = Bandit::epsilon_greedy(vec![1, 2, 3], 0.1).unwrap();

// Batch training
bandit.fit_simple(&[1, 2, 1, 3], &[1.0, 0.5, 0.8, 0.9]).unwrap();

// Batch predictions
let mut rng = thread_rng();
let predictions = bandit.predict_batch_simple(10, &mut rng).unwrap();
println!("Batch predictions: {:?}", predictions);
```

## Examples

Explore the examples directory for more detailed usage:

```bash
# Compare different algorithms
cargo run --example algorithm_comparison

# Demonstrate batch operations
cargo run --example batch_operations

# Contextual bandits with LinUCB
cargo run --example contextual_bandits
```
## License

This project is dual-licensed under either:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Acknowledgments

- Inspired by [MABWiser](https://github.com/fidelity/mabwiser) from Fidelity Investments