paperless-brain CLAUDE.md

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

# Deploy: tag a release, CI publishes the image, the server pulls it
git tag vX.Y.Z && git push origin main --tags   # .github/workflows/release.yml
ssh <server> "cd /root/paperlessbrain && docker compose pull && docker compose up -d"

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.
• 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) with its own backend (anthropic / openai_compatible), base URL, key and model id — which is what makes AI gateways (OpenRouter, Requesty, LiteLLM, Portkey …) work with no code.
• SEARXNG_HOST — self-hosted SearXNG instance
• STORAGE_SECRET — NiceGUI session secret