Perspicacité is a local-first RAG framework for searching, understanding, and organizing academic literature. It exposes a web UI, a REST API, a CLI, and an MCP server — all backed by the same retrieval and reasoning engine.
- New here? Read getting-started.md — install, configure, create your first KB, and ask your first question in under ten minutes.
- Want to understand the design? Read VISION.md — the problem this project addresses, the design philosophy, and the architecture overview.
- Looking for a specific feature? Browse the sections below.
Background reading for understanding how Perspicacité works internally.
| File | What it covers |
|---|---|
| concepts/knowledge-bases.md | What a KB is, how to create one, multi-KB routing |
| concepts/rag-modes.md | The six RAG modes and when to use each |
| concepts/capsules.md | Per-paper capsule structure: figures, references, code, SI |
| concepts/provenance.md | How the retrieval trace is built, where it lives, how to export it |
| concepts/citation-graph.md | Snowball walks, OpenAlex + Semantic Scholar fallback, arXiv handling |
Step-by-step walkthroughs for common tasks.
| File | What it covers |
|---|---|
| guides/ingest-bibtex.md | Import a .bib file into a knowledge base |
| guides/search-to-kb.md | The search → screen → ingest workflow |
| guides/expand-via-citations.md | Growing a KB by following citations |
| guides/zotero-integration.md | Pushing papers to Zotero, building KBs from collections |
| guides/obsidian-export.md | Exporting a KB as an Obsidian Markdown vault |
| guides/institutional-pdf-access.md | Browser cookie flow for paywalled PDFs |
Exact interface specifications: flags, endpoints, tool signatures, config keys.
| File | What it covers |
|---|---|
| reference/cli.md | All perspicacite <subcommand> calls and their flags |
| reference/rest-api.md | REST endpoints, request/response shapes |
| reference/mcp-tools.md | The 32 MCP tools |
| reference/config.md | config.yml schema with all fields and defaults |
| reference/paper-source-enum.md | All PaperSource values and when each is used |
For contributors and people extending the codebase.
| File | What it covers |
|---|---|
| development/contributing.md | Dev-loop setup, CLA workflow |
| development/architecture.md | Code tour of the layered source tree |
| development/testing.md | How to run pytest, unit vs integration, API-key gates |
| development/superpowers-workflow.md | How the brainstorm→spec→plan→subagent cycle works |
- README — project overview and quick start
- VISION.md — framework vision and design philosophy
- CONTRIBUTING.md — contributor agreement and CLA workflow
- MANUAL_QA.md — manual QA checklist for UI features
- ROADMAP.md — high-level roadmap