---
title: Marginalia Web
emoji: 📱
colorFrom: green
colorTo: indigo
sdk: docker
pinned: false
short_description: Marginalia literary companion — web & iPhone, no robot
tags:
  - literary
  - ai-assistant
  - reading
---

# Marginalia Web

The same **Marginalia** experience as [Marginalia for Reachy Mini](https://huggingface.co/spaces/SantiPa/marginalia), but as a **web app** you can open on iPhone, iPad, or any browser and share with a link.

- Wikipedia-backed sources with thumbnails  
- Streaming answers from a Hugging Face hosted LLM (same defaults as the robot app)  
- **Read aloud** defaults to **server-side Edge neural TTS** (same family as Reachy Marginalia); set **`MARGINALIA_TTS=browser`** to use only the Web Speech API (device voices).  
- **No Reachy Mini**, no robot SDK

## Create your own Space (clone)

1. On Hugging Face: **New Space** → name it e.g. `marginalia-web` → **Docker** SDK.  
2. Push this repository folder to that Space (e.g. `git clone` the Space, copy these files, commit, push). After changing `static/` assets, bump the `?v=` query on `style.css` / `main.js` in `index.html` if browsers cache old files.  
3. Add a **repository secret** named **`HF_TOKEN`** (see below). Docker Spaces do **not** auto-inject a Hub token; without it, inference fails with an *api_key* error from the Inference client.

## Run locally

```bash
cd marginalia-web
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
hf auth login
uvicorn marginalia_web.app:app --reload --host 0.0.0.0 --port 7860
```

Open `http://localhost:7860`.

## Configuration

Same environment variables as the robot app for the LLM, e.g. `MARGINALIA_LLM_MODEL`, `MARGINALIA_LLM_MAX_TOKENS`, `MARGINALIA_LLM_TEMPERATURE`.

Optional: `MARGINALIA_INFERENCE_PROVIDER` — defaults to `auto` (server-side router; needs `HF_TOKEN` for gated / routed models). Use `hf-inference` only if your `MARGINALIA_LLM_MODEL` is supported on that provider.

### Text-to-speech (`MARGINALIA_TTS`)

| Value | Behaviour |
|-------|-----------|
| `edge` (default) | **Microsoft Edge neural TTS** via [`edge-tts`](https://github.com/rany2/edge-tts) on the Space (outbound HTTPS). Same voice IDs as the robot app (`en-GB-SoniaNeural`, …). Uses `/api/tts/split` + `/api/tts`. |
| `browser` | **Web Speech API** only — no audio synthesis on the server. |

Optional tuning (robot parity): `MARGINALIA_VOICE`, `MARGINALIA_EDGE_RATE`, `MARGINALIA_EDGE_PITCH`, `MARGINALIA_EDGE_TIMEOUT`, `MARGINALIA_TTS_MAX_INPUT_CHARS`, `MARGINALIA_TTS_MAX_CHUNK_CHARS`.

The Edge TTS path relies on Microsoft’s public speech endpoints; availability may change. For production you may prefer **Azure Speech** or another vendor.

### Inference API token (Docker Spaces)

The app normalizes **`HF_TOKEN`**, **`HUGGING_FACE_HUB_TOKEN`**, **`HUGGINGFACEHUB_API_TOKEN`**, and optional **`/run/secrets/HF_TOKEN`**, so `InferenceClient` and `get_token()` agree. If you see *"You must provide an api_key"*:

1. Open the Space → **Settings** → **Repository secrets**.
2. Add **`HF_TOKEN`** with a [user access token](https://huggingface.co/settings/tokens) that can call Inference (fine-grained: inference / read as appropriate for your model).
3. Factory-rebuild or push a new commit so the container restarts.

Local runs: use `hf auth login`, or export `HF_TOKEN` for a non-interactive shell.

## Privacy

Questions are sent to this Space’s backend, then to the Hugging Face Inference API and Wikipedia. **Read aloud** in `edge` mode sends chunked text to **Microsoft’s Edge TTS service** for audio generation. Do not submit secrets or private health/legal data.