DerridAI is a local-first Docker application for building, auditing, and querying scholarly corpora of philosophical texts. It turns source PDFs into structured JSONL records, reviews and enriches those records with local or OpenAI-compatible LLMs, manages persistent ChromaDB vector collections, and runs an evidence-grounded retrieval-augmented generation (RAG) pipeline over the result.
Current version: 0.62.8 — Spacious Stork (release notes).
- Corpus Builder — a sequenced Source → Document structure → LLM & enrichment → Record construction → Build workflow that extracts, segments, and enriches records from PDFs, with reviewer-owned document structure and auditable field provenance.
- Record review — JSONL workspaces with full audit history, bulk and work-level metadata editing, red/green diffs, source-PDF linking, and human/LLM field ownership (high-confidence LLM proposals populate fields; lower-confidence ones stay as suggestions).
- LLM review and tools — foreground, background, and background Auto-improve runs against named Ollama or OpenAI-compatible provider profiles, each with its own concurrency limit and warmup state.
- Vector stores — persistent ChromaDB collections on the local filesystem or a running Chroma server, with English/French language mirrors, background upserts, and JSONL round-tripping.
- RAG Research — hybrid retrieval, cross-encoder reranking, language routing, streamed and cancellable generation, a cached Response Library, and LLM grading of answers.
- Roles — Admin and Researcher accounts; researchers see summarized evidence text and cannot mutate corpora.
- Backup & restore — one ZIP holding workspaces, audit history, provider profiles, PDFs, and every Chroma collection with its embeddings.
- Bilingual and accessible — English and French are first-class locales with enforced key parity. Keyboard access, visible focus, and WCAG 2.0 AA are release requirements.
See the User Guide for a full feature reference.
| Service | Stack | Notes |
|---|---|---|
web |
Vue 3, TypeScript, Pinia, Vue Router, Vite, PDF.js, served by nginx | Proxies /api/ to the API; Storybook is available as an opt-in dev service |
api |
Python 3.12, FastAPI, ChromaDB, PyMuPDF, sentence-transformers | Persistent state lives under ./data (Chroma, SQLite auth/system stores, model cache) |
| LLM backend | Ollama (default) or any OpenAI-compatible endpoint | Runs on the host or elsewhere; not part of the compose stack |
Prerequisites: Docker with Compose, and an Ollama server (or an OpenAI-compatible endpoint) with the default models pulled.
cp .env.example .env
docker compose up -d --buildThen open http://localhost:8181. On first launch DerridAI asks you to create the initial administrator account; no default credentials are shipped. Interactive API documentation is at http://localhost:8000/docs.
To rebuild after an upgrade:
docker compose down
docker compose up -d --buildCopy .env.example to .env and edit as needed. Key settings:
OLLAMA_BASE_URL=http://host.docker.internal:11434
OLLAMA_MODEL=gemma4:e2b
OLLAMA_EMBED_MODEL=bge-m3:latest
EMBEDDING_PROVIDER=ollamaSet SESSION_COOKIE_SECURE=true only when the browser reaches DerridAI through an HTTPS reverse proxy (it defaults to false for local HTTP). Repeated failed logins lock the username for AUTH_LOGIN_LOCKOUT_SECONDS (default 300) after AUTH_LOGIN_MAX_FAILURES (default 5).
On Docker Desktop with WSL, set HOST_UID and HOST_GID to id -u / id -g so Chroma files are not created root-owned. Additional LLM providers are configured in the app under LLM Providers.
./scripts/diagnose.sh # PowerShell: .\scripts\diagnose.ps1
./scripts/fix-data-permissions.sh # if older releases left root-owned data# Backend and release regression tests
pip install -r api/requirements.txt pytest
pytest -q
# Frontend
cd web
npm install
npm run typecheck && npm run test:unit && npm run build
npm run storybook # or: docker compose --profile dev up storybook
npm run test:e2e # Playwright + axe-coreCI (.github/workflows/frontend.yml) runs Ruff, mypy, ESLint, the backend tests, and the full frontend gate. See CONTRIBUTING.md for every gate and AGENTS.md for conventions.
- User Guide — feature reference, operations, backup, and limitations
- Changelog — release history; full notes live in
docs/notes/ - Architecture overview and Contributing
- Design notes: Storage, Shareable state and data model, Search workspace, Packet reduction, fr-CA localization
No license file is currently included. Source files carry Copyright 2026 Aaron John Schlosser, PhD. The sign-in screen, account menu, and Settings → About DerridAI show © 2026 The New England Transcendental Club of California.