README.md

---
tags:
  - transformers.js
  - webassembly
  - browser-llm
  - function-calling
  - gorilla
  - local-ai
license: mit
language: en
pipeline_tag: text-generation
library_name: transformers.js
---

# PROJECT: BOB

**Local-first, serverless, tool-calling AI running entirely in your browser via WebAssembly.**

![Demo](https://img.shields.io/badge/Demo-Live-brightgreen?style=for-the-badge&logo=githubpages)
![Model](https://img.shields.io/badge/Model-Gorilla_3B-orange?style=for-the-badge&logo=huggingface)
![License](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)

---

## What is Bob?

Bob is a personal AI assistant that runs **100% locally in your browser**. No servers, no cloud, no tracking, no API keys required after initial model download (~600MB). Built with [Transformers.js](https://github.com/xenova/transformers.js) and [Gorilla OpenFunctions](https://huggingface.co/gorilla-llm/gorilla-openfunctions-v2).

### Key Features

- 🔒 **Zero Server** — Runs entirely client-side via WebAssembly
- 🛠 **Tool Calling** — Native function calling: `get_crypto_price`, `multiply_numbers`
- 🌐 **Offline-Capable** — Works after first load (model cached in IndexedDB)
- ⚡ **Instant Deploy** — Static files on GitHub Pages
- 🎨 **Stark UI** — Pure black/white high-contrast interface

---

## Live Demo

**https://yummyfiles.github.io/Project-Bob/**

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      BROWSER (Client)                        │
├─────────────────────────────────────────────────────────────┤
│  index.html  →  app.js  →  @xenova/transformers (WASM)      │
│                              ↓                               │
│                    ┌──────────────────┐                      │
│                    │  Gorilla-3B-4bit │  ← Cached in         │
│                    │  (ONNX quantized)│  ← IndexedDB         │
│                    └────────┬─────────┘                      │
│                             │                                │
│                    <call_tool> detection                     │
│                             ↓                                │
│              ┌──────────────┴──────────────┐                 │
│              ▼                             ▼                 │
│      get_crypto_price()            multiply_numbers()       │
│      (CoinGecko API)               (local JS math)          │
└─────────────────────────────────────────────────────────────┘
```

---

## Quick Start

### Use Online (No Setup)
Visit **https://yummyfiles.github.io/Project-Bob/** — loads model on first visit.

### Run Locally
```bash
git clone https://github.com/yummyfiles/Project-Bob
cd Project-Bob
npx serve  # or python -m http.server 8000
# Open http://localhost:3000
```

---

## Model

| Component | Details |
|-----------|---------|
| **Base** | `gorilla-llm/gorilla-openfunctions-v2` (3B params) |
| **Format** | ONNX INT4 quantized via Optimum |
| **Runtime** | Transformers.js (ONNX Runtime Web + WebAssembly) |
| **Size** | ~600MB download, cached after first load |
| **Capabilities** | Function calling, chat, reasoning |

### Why Gorilla?
- Trained specifically for **function calling** (API interaction)
- Open-source, Apache 2.0 license
- Works well quantized to 4-bit
- Small enough for browser inference

---

## Tool System

Bob detects `<call_tool>` tags in model output and executes matching JavaScript functions.

### Built-in Tools

| Tool | Description | Example |
|------|-------------|---------|
| `get_crypto_price(symbol)` | Fetches live crypto price from CoinGecko | `"BTC"` → `"$67,420"` |
| `multiply_numbers(a, b)` | Multiplies two numbers locally | `144, 37` → `5328` |

### Adding Tools

```javascript
// In app.js, extend customTools object:
const customTools = {
  get_crypto_price: async (symbol) => { ... },
  multiply_numbers: (a, b) => a * b,
  // Add yours here:
  my_custom_tool: async (arg1, arg2) => { ... }
};
```

Model prompt includes tool schemas — it learns to call them automatically.

---

## Project Structure

```
Project-Bob/
├── index.html          # Stark black/white UI
├── app.js              # Transformers.js runtime + tool engine
├── dataset.jsonl       # Fine-tuning examples (QLoRA format)
├── colab_training_notebook.py  # Google Colab training script
├── push_assets.py      # Deploy to GitHub Pages + HF Hub
└── README.md           # This file
```

---

## Fine-Tuning Your Own Bob

Train a specialized version on your data:

1. **Open Colab**: Upload `colab_training_notebook.ipynb`
2. **GPU Runtime**: Runtime → Change runtime type → T4 GPU
3. **Secrets**: Add `HF_TOKEN` (write access)
4. **Run All**: ~15 minutes on T4
5. **Result**: Trained LoRA + ONNX 4-bit pushed to `yummyfiles/Bob`

### Dataset Format (dataset.jsonl)

```jsonl
{"text": "<|begin_of_text|><|start_header_id|>user<|end_header_id|>What is the current price of Bitcoin?<|eot_id|><|start_header_id|>assistant<|end_header_id|><call_tool>get_crypto_price({\"symbol\": \"BTC\"})</call_tool><|eot_id|>"}
{"text": "<|begin_of_text|><|start_header_id|>user<|end_header_id|>Multiply 42 by 58 for me.<|eot_id|><|start_header_id|>assistant<|end_header_id|><call_tool>multiply_numbers({\"a\": 42, \"b\": 58})</call_tool><|eot_id|>"}
```

---

## Deployment

### GitHub Pages (Frontend)
```bash
python push_assets.py
# Pushes index.html, app.js → yummyfiles/Project-Bob (main branch)
# Enable Pages in repo settings: Source = main branch
```

### Hugging Face Hub (Model)
```bash
python push_assets.py
# Uploads model artifacts → yummyfiles/Bob
```

---

## Tech Stack

| Layer | Technology |
|-------|------------|
| **ML Runtime** | Transformers.js 2.17+ (ONNX Runtime Web + WASM) |
| **Model** | Gorilla OpenFunctions v2 (3B, INT4) |
| **Tools** | Native JS async functions |
| **Frontend** | Vanilla HTML/CSS/JS (ES Modules) |
| **Hosting** | GitHub Pages (static) |
| **Model Hub** | Hugging Face Hub |

---

## Browser Support

| Browser | Support |
|---------|---------|
| Chrome 94+ | ✅ Full |
| Firefox 93+ | ✅ Full |
| Safari 15.4+ | ✅ Full |
| Edge 94+ | ✅ Full |

Requires: `SharedArrayBuffer`, `WebAssembly`, `WebGL`/`WebGPU`

---

## Privacy

- **No telemetry**
- **No external requests** except:
  - Model download (once, from HF CDN)
  - `get_crypto_price` → CoinGecko public API
- **All inference local** — your prompts never leave your device

---

## License

MIT — Free for any use.

---

## Credits

- [Transformers.js](https://github.com/xenova/transformers.js) by Xenova
- [Gorilla OpenFunctions](https://huggingface.co/gorilla-llm/gorilla-openfunctions-v2) by Gorilla LLM team
- [Optimum](https://github.com/huggingface/optimum) for ONNX export
- [CoinGecko](https://www.coingecko.com/api) for crypto prices

---

**Built for local-first AI. No cloud required.**