Documentation

README.md

@@ -31,22 +31,34 @@ pinned: false
 | **Article / transcript**  | Paste any text directly                                                       |
 | **File upload**           | Drag-and-drop `.txt` files                                                    |
 | **Streaming**             | Summaries stream token-by-token from Ollama via NDJSON                        |
-| **Model switching**       | Choose between available Ollama models from the UI                            |
+| **Model switching**       | Choose between available Ollama models from the UI with live VRAM warmup      |
+
+### Keyboard Shortcuts
+
+| Shortcut | Action | Behavior |
+|---|---|---|
+| <kbd>Ctrl</kbd> + <kbd>Enter</kbd> | **Generate** | Triggers summarization on the active tab |
+| <kbd>Ctrl</kbd> + <kbd>C</kbd> | **Cancel** | Stops active generation; preserves streamed tokens as a `· partial` summary |
+| <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>C</kbd> | **Copy Link** | Copies current YouTube URL to clipboard |
 
 ---
 
 ## API Endpoints
 
-| Method  |       Path              |     Description       |
-|---------|-------------------------|-----------------------|
-| `GET`   | `/health`               | Health check          |
-| `GET`   | `/status`               | Ollama statuses, etc. |
-| `GET`   | `/models`               | List available models |
-| `POST`  | `/summarize/transcript` | Raw text summary      |
-| `POST`  | `/summarize/youtube`    | YouTube video by URL  |
-| `POST`  | `/summarize/file`       | `.txt` file summary   |
-
-All `/summarize/*` endpoints accept an optional `model` field to override the default and require `X-API-Key` header (`PRECIS_API_KEY`).
+| Method  | Path                     | Auth Required | Description |
+|---------|--------------------------|:-------------:|-------------|
+| `GET`   | `/health`                | No            | Service liveness check |
+| `GET`   | `/status`                | No            | Ollama reachability, model configuration, version info |
+| `GET`   | `/models`                | No            | Lists installed models, currently running VRAM models, and default |
+| `POST`  | `/warmup`                | No            | Pre-loads model into Ollama VRAM (`?model=<name>`) |
+| `GET`   | `/warmup/status`         | No            | Checks if model is currently loaded in memory (`?model=<name>`) |
+| `POST`  | `/unload`                | No            | Evicts a specific model or all models from VRAM |
+| `GET`   | `/api`                   | No            | API root metadata and documentation links |
+| `POST`  | `/summarize/transcript`  | `X-API-Key`   | Plain-text summarization (JSON body) |
+| `POST`  | `/summarize/youtube`     | `X-API-Key`   | YouTube video transcript fetch + summary (JSON body) |
+| `POST`  | `/summarize/file`        | `X-API-Key`   | Plain `.txt` file upload (`multipart/form-data`, optional `?model=`) |
+
+All `/summarize/*` endpoints stream responses via NDJSON (`application/x-ndjson`) and require the `X-API-Key` header matching `PRECIS_API_KEY`. Model reasoning and `<think>` blocks are isolated server-side and streamed as formatted markdown blockquotes.
 
 ---
 
@@ -78,17 +90,26 @@ cp .env.example .env
 # VITE_API_KEY must match PRECIS_API_KEY so the baked frontend can auth
 ```
 
-> **`.env.example` defaults for Docker (host Ollama):**
-> ```ini
-> OLLAMA_BASE_URL=http://127.0.0.1:11434        # for local `uvicorn` without Docker; Docker compose hard-codes http://host.docker.internal:11434 (host GPU)
-> DEFAULT_MODEL=phi4-mini:latest
-> AVAILABLE_MODELS=phi4-mini:latest,qwen3:4b
-> PRECIS_API_KEY=replace-with-a-long-random-secret
-> VITE_API_KEY=replace-with-a-long-random-secret
-> PRECIS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:8000
-> VITE_API_BASE_URL=                            # empty = same origin (correct for Docker)
-> # NOTE: OLLAMA_HOST_DIR removed — no Docker Ollama container, no bind mount. Host Ollama uses its native store.
-> ```
+> **Configuration & Environment Variables:**
+>
+> | Variable | Default | Purpose |
+> |---|---|---|
+> | `OLLAMA_BASE_URL` | `http://127.0.0.1:11434` | Host Ollama URL (Docker Compose sets `http://host.docker.internal:11434`) |
+> | `DEFAULT_MODEL` | `phi4-mini:latest` | Default model tag when none specified in request |
+> | `AVAILABLE_MODELS` | `phi4-mini:latest` | Comma-separated allowlist of models |
+> | `PRECIS_API_KEY` | *(required)* | Secret token checked against `X-API-Key` on `/summarize/*` |
+> | `VITE_API_KEY` | *(required)* | Inlined into frontend bundle at build time to authenticate with API |
+> | `VITE_API_BASE_URL` | `""` | Base API URL; empty string uses same origin (or Vite proxy in dev) |
+> | `VITE_PROXY_TARGET` | `http://api:8000` | Target backend host used by Docker frontend container |
+> | `PORT` | `8000` | Service listening port (defaults to `8000`, Hugging Face Spaces sets `7860`) |
+> | `PRECIS_ALLOWED_ORIGINS` | `http://localhost:5173,http://localhost:8000` | CORS allowed origins |
+> | `OLLAMA_KEEP_ALIVE` | `30m` | Duration Ollama retains loaded model in VRAM |
+> | `MAX_SUMMARY_TOKENS` | `120` | Max tokens generated per summary |
+> | `TEMPERATURE` | `0.2` | Generation sampling temperature |
+> | `PRECIS_MAX_UPLOAD_BYTES` | `10485760` | Max upload size for `/summarize/file` (10 MB) |
+> | `PRECIS_MAX_TRANSCRIPT_CHARS` | `250000` | Max characters allowed for text summarization |
+> | `CHOKIDAR_USEPOLLING` | `1` | Enables filesystem polling for Vite HMR across Docker on Windows |
+> | `CHOKIDAR_INTERVAL` | `1000` | Polling interval in milliseconds to prevent CPU thrashing |
 
 ### 3. Run
 
@@ -116,7 +137,7 @@ The API will 503 until a model is installed. On **host**:
 ```bash
 ollama pull phi4-mini:latest
 # optional extras:
-ollama pull qwen3:4b
+ollama pull qwen2.5:3b
 ollama list
 ```
 
@@ -125,15 +146,15 @@ Then refresh http://localhost:5173 — the model selector populates automaticall
 #### Useful commands
 
 ```bash
-docker compose up --watch -d   # detached with watch
-docker compose logs -f api     # tail API logs (no ollama container anymore)
+docker compose up --watch -d   # detached with watch (api + frontend containers)
+docker compose logs -f api     # tail API logs
 docker compose logs -f frontend
 docker compose down            # stop api+frontend
 docker compose ps
 curl http://localhost:8000/health
 curl http://localhost:8000/status
 curl http://host.docker.internal:11434/api/tags # verify host Ollama reachable from Docker
-# prod without watch/HMR (static frontend at 8000):
+# prod without watch/HMR (static frontend baked into api image at 8000):
 docker compose -f docker-compose.yml up --build -d
 ```
 
@@ -142,7 +163,9 @@ docker compose -f docker-compose.yml up --build -d
 If you just want the API image and already run Ollama natively (`ollama serve` on host):
 
 ```bash
-docker build -t precis .
+docker build -t precis \
+  --build-arg PRECIS_API_KEY=your-secret-key \
+  --build-arg VITE_API_KEY=your-secret-key .
 docker run --rm -p 8000:8000 --env-file .env \
   -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
   --add-host=host.docker.internal:host-gateway \

frontend/README.md

@@ -2,11 +2,53 @@
 
 React 19 + Vite frontend for Précis. See the [root README](../README.md) for full setup instructions.
 
-Navigate to the `frontend/` folder, then run:
+## Development
+
+### 1. With Docker (Recommended)
+From the repository root, run:
+
+```bash
+docker compose up --watch -d
+```
+
+The frontend container starts the Vite dev server at `http://localhost:5173` with HMR enabled, proxying API requests to the backend container at `http://api:8000`.
+
+### 2. Manual (Without Docker)
+From the `frontend/` directory:
 
 ```bash
 npm install
 npm run dev
 ```
 
-Requires the backend API running at `http://localhost:5173`.
+Served at `http://localhost:5173`. Requires the backend API running at `http://localhost:8000` (requests to `/health`, `/status`, `/models`, `/warmup`, `/unload`, and `/summarize` are proxied via `vite.config.js`).
+
+## Production Build
+
+```bash
+npm run build
+```
+
+Generates an optimized static bundle in `frontend/dist/`. In production or single-container Docker deployments, the FastAPI backend automatically detects `frontend/dist` and serves the single-page application directly from `/`.
+
+## Environment Variables
+
+Read at build/dev time from the repo root `.env` or injected by Docker Compose:
+
+| Variable | Description |
+|---|---|
+| `VITE_API_KEY` | API secret key inlined into the frontend bundle at build time; sent as `X-API-Key` to authorize with the backend. Must match `PRECIS_API_KEY`. |
+| `VITE_API_BASE_URL` | Base API URL. Leave empty (`""`) to use same-origin (production) or the Vite dev proxy. |
+| `VITE_PROXY_TARGET` | Proxy destination for Vite in dev mode (default: `http://localhost:8000`, set to `http://api:8000` inside Docker Compose). |
+
+## Architecture
+
+* **`src/App.jsx`**: Main application shell with tab controls (YouTube, Text, File) and model selector with active VRAM status indicators.
+* **`src/hooks/useStreaming.js`**: Custom hook for reading NDJSON streams (`ReadableStream` -> `TextDecoder`). Uses `requestAnimationFrame` frame-throttling (~60fps) to eliminate UI lag during rapid token delivery. Supports in-flight cancellation while preserving partial summaries.
+* **`src/components/InlineResult.jsx`**: Renders markdown output, streaming status indicators, and model reasoning tags.
+
+### Keyboard Shortcuts
+
+* <kbd>Ctrl</kbd> + <kbd>Enter</kbd>: Submit active form and generate summary.
+* <kbd>Ctrl</kbd> + <kbd>C</kbd>: Cancel active generation and keep streamed tokens as a `· partial` result.
+* <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>C</kbd>: Copy current YouTube URL to clipboard.

frontend/src/App.css

@@ -339,7 +339,6 @@
   color: var(--color-danger-fg);
 }
 
-.inline-result--loading,
 .inline-result--streaming {
   background-color: var(--color-canvas-inset);
   border-color: var(--color-border-muted);
@@ -521,7 +520,7 @@
     background-color: #24292f;
     color: #ffffff;
     font-size: 11px;
-    font-family: var(--font-family-sans);
+    font-family: var(--font-family);
     font-weight: 500;
     padding: 5px 8px;
     border-radius: 6px;

frontend/src/index.css

@@ -120,20 +120,6 @@ body {
   background-color: var(--color-btn-primary-hover-bg);
 }
 
-.btn-lg {
-  padding: 10px 24px;
-  font-size: 16px;
-  line-height: 24px;
-}
-
-/* Card styles */
-.card {
-  background-color: var(--color-canvas-subtle);
-  border: 1px solid var(--color-border-default);
-  border-radius: var(--radius-1);
-  padding: var(--spacing-4);
-}
-
 /* Input styles */
 .input {
   width: 100%;
@@ -207,17 +193,6 @@ body {
   color: var(--color-fg-muted);
 }
 
-.dropzone-text {
-  font-size: 16px;
-  color: var(--color-fg-muted);
-  text-align: center;
-}
-
-.dropzone-hint {
-  font-size: 12px;
-  color: var(--color-fg-subtle);
-}
-
 /* Animations */
 @keyframes fadeIn {
   from {
@@ -230,23 +205,10 @@ body {
   }
 }
 
-@keyframes pulse {
-  0%, 100% {
-    opacity: 1;
-  }
-  50% {
-    opacity: 0.5;
-  }
-}
-
 .fade-in {
   animation: fadeIn 0.3s ease-out forwards;
 }
 
-.pulse {
-  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
-}
-
 /* Scrollbar */
 ::-webkit-scrollbar {
   width: 8px;

frontend/src/main.jsx

@@ -6,6 +6,5 @@ import App from './App.jsx'
 // caused duplicate /models + /warmup calls on every reload → perceived lag
 // and "stops after script fetching" race. We run without it for stability.
 // Re-enable only if you need to audit effects.
-// import { StrictMode } from 'react'
 
 createRoot(document.getElementById('root')).render(<App />)

scripts/cleaners/clean_ds.py

@@ -22,7 +22,7 @@ def write_jsonl(rows, output_path):
     with open(output_path, 'w', encoding='utf-8') as f:
         for row in rows:
             new_data = {
-                "id": i,
+                "id": row["id"],
                 "original_source": "DialogSum",
                 "dialogue": row["dialogue"],
                 "summary": row["summary"],

scripts/cleaners/clean_ms.py

@@ -24,7 +24,7 @@ def write_jsonl(lines, output_path):
         for line in lines:
             data = json.loads(line)
             new_data = {
-                "id": i,
+                "id": data["id"],
                 "original_source": "MediaSum",
                 "url": data["url"],
                 "summary": data["summary"],