paperless-brain: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

PaperlessBrain — AI-powered frontend for Paperless-ngx. Built with NiceGUI + FastAPI. Lets users chat with their document archive (invoices, contracts, letters) via Claude or Ollama LLMs, with full tool-call agentic loop.

Running

# Local dev
python main.py
# App runs at http://0.0.0.0:8080

# Release: tag it; CI publishes latest / lean / the version
git tag vX.Y.Z && git push origin main --tags   # .github/workflows/release.yml

The dev server deploys itself: every merge to main, and every manual "Run workflow" on any branch, publishes :dev (never :latest), and a systemd timer on the server (paperlessbrain-autodeploy, every 2 min) pulls it, restarts both containers and prunes old images. It waits up to 3 h for a running Werkbank run, which a restart would stop. Watchtower is gone: it recreated containers past Compose and raced manual deploys.

Dependencies

Single source of truth: pyproject.toml (direct deps only, range pins; name paperless-brain, version from config/version.py via hatchling). The old requirements*.txt files are gone.

# GPU machine (dev)
pip install -e ".[crawl,i18n]"

# CPU-only (LXC/Docker) — +cpu torch wheel outranks the CUDA build on PyPI
pip install --extra-index-url https://download.pytorch.org/whl/cpu -e ".[crawl,i18n]"
playwright install chromium   # only needed with the [crawl] extra

# Docker
docker build -t paperless-brain .                    # full
docker build --build-arg LEAN=1 -t paperless-brain . # no crawl4ai/chromium
docker compose up -d

Extras: [crawl] = crawl4ai + headless Chromium (JS-heavy page fetching — app degrades to trafilatura-only without it); [i18n] = pybabel workflow.

Configuration

All settings via .env file (loaded by config/settings.py via pydantic-settings). Required keys:

• APP_PATH — absolute path to repo root (with trailing slash)
• PAPERLESS_URL, PAPERLESS_SUPERUSER_TOKEN — Paperless-ngx API
• IGNORE_INBOX_TAG_AT_SYNC — tag name to skip during sync
• EMBEDDING_MODEL, CHROMA_PATH, CHROMA_COLLECTION, EXTRACTION_SIDECAR_PATH, THUMB_PATH
• OLLAMA_SERVER, OLLAMA_INGEST_MODEL — optional, vision LLM for ingestion (both also settable in Settings > Processing, which wins). Chat and Werkbank never read them — those use per-user models with their own base_url. OLLAMA_SERVER additionally names the host the WoL/shutdown buttons control; without it that is inferred from the first local-lane model in the registry.
• Every Anthropic SDK client comes from services/anthropic_client.async_client. SDK 2.x sends the key as Authorization: Bearer; for a custom base URL the factory moves it back to X-Api-Key (gateways read that). Sampling parameters are never sent on the Anthropic path (2026-10-21 rejects them with a 400).
• No provider API key belongs in .env. Every chat/research/vision model is managed per user in the UI (Settings > AI Models, services/model_registry.py): one entry per service (backend anthropic / openai_compatible, base URL, key, lane) with any number of models below it — which is what makes AI gateways (OpenRouter, Requesty, LiteLLM, Portkey …) work with no code.
  • get_models() stays the flat view (one dict per model, service fields merged in). Everything that runs a model reads that; only the settings editor sees the tree.
  • A model is referenced by its display name, everywhere (chat choice, ingest model, memo/dream model, Werkbank). The ingest model is a global setting resolved in whichever user's registry triggers the sync, so a per-user id would not do. Hence display names are unique across all services (enforced on save), and a rename re-points the stored choices.
  • Every model dropdown goes through app_ui/model_picker.model_select, which groups by service. Never a raw ui.select over model names.
  • The flat list of older versions (llm_models) is migrated on first read and left in place as a fallback copy. A base URL is normalized on save — a pasted /chat/completions or /v1/messages doubled the path and produced a bare 404.
• SEARXNG_HOST — self-hosted SearXNG instance
• STORAGE_SECRET — NiceGUI session secret