studyproof

# StudyProof **Bring your sources to an AI study session. Check the quotes that come back.** [](https://github.com/Lapmlnex/studyproof/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) StudyProof is a local evidence workbench for researchers and students. Add PDFs, lecture notes, or readings. Search for relevant passages, export a compact context pack for your AI assistant, and check whether quotations in its answer actually appear in that pack. No account. No API key. No embedding model or GPU. Your source library stays on your computer until you choose to share passages with an AI client. ## Try it in one command With [uv](https://docs.astral.sh/uv/getting-started/installation/) installed: ```sh uvx --from git+https://github.com/Lapmlnex/studyproof studyproof demo --web ``` Open the local address printed in the terminal. The demo includes original teaching notes about retrieval, study practice, and interpreting evidence. Search **retrieval evidence**, build a pack, then try the quotation checker. No external documents or model credentials are needed. ## The workflow | Step | What you get | | --- | --- | | **Add** a PDF, Markdown file, or text note | A searchable local library with source hashes and page/line locations | | **Search** a topic | Relevant excerpts ranked with SQLite's BM25 keyword search | | **Pack** your evidence | Markdown context for an AI assistant plus a JSON audit file | | **Check** an answer | Matching quotations, missing references, unknown IDs, and changed wording | A pack assigns citation IDs such as `[S1]` to the excerpts it contains. Ask your assistant to quote evidence using this format: ```markdown > Exact wording from the evidence pack. [S1] Explain what this passage means, and identify what it does not establish. ``` StudyProof checks the quotation against `[S1]`. A real citation ID alone is not proof that an answer is supported. **The audit checks quoted wording and citation IDs; it does not verify scientific truth, paraphrases, or the reasoning around a quote.** An answer without checkable quotations is reported as unverified. ## Use your own sources Install once with Python 3.10 or newer: ```sh python -m pip install git+https://github.com/Lapmlnex/studyproof studyproof serve ``` Open the printed localhost address and select **Add sources**. Supported formats: text-layer PDF, `.md`, and `.txt`. The browser accepts files up to 10 MiB each. Uploaded files and the index remain in your local StudyProof workspace. Or use the terminal: ```sh studyproof add paper.pdf studyproof add lecture-notes.md studyproof search "retrieval evidence" studyproof pack "retrieval evidence" --output context.md studyproof audit answer.md --pack context.json ``` Keep `context.json` with the answer you want to check. Audit against the same pack you gave your assistant. Packs include excerpt text and source hashes so they can be inspected separately from your current library. For a separate course or project, put `--db` before the command: ```sh studyproof --db ./course/library.db add reading.pdf studyproof --db ./course/library.db serve ``` Run `studyproof --help` and `studyproof <command> --help` for available options. ## Connect an AI assistant with MCP The optional adapter exposes read-only source listing, search, and context-pack creation through the official Model Context Protocol Python SDK. ```sh python -m pip install 'studyproof[mcp] @ git+https://github.com/Lapmlnex/studyproof' studyproof --db /absolute/path/to/library.db mcp ``` For an MCP client that accepts JSON server configuration: ```json { "mcpServers": { "studyproof": { "command": "studyproof", "args": ["--db", "/absolute/path/to/library.db", "mcp"] } } } ``` Replace the database path with your library's path; use an absolute executable path if your client cannot find `studyproof`. Restart the client after adding its configuration. The adapter uses stdio and does not start a public HTTP endpoint. Your AI client may send retrieved passages to its model provider. Its privacy settings apply. Source text is untrusted content; it is never an instruction to execute a command or disclose other files. ## What this version does well - A small, inspectable retrieval core, without a vector database service. - Source locations and fingerprints attached to the retrieved text. - A context-size budget measured in characters, including the pack wrapper. - A useful browser interface, CLI, and optional MCP adapter over the same core. - Explicit failures and uncertainty instead of a green badge for any cited answer. ## Limits to know - Search matches words, not meaning. Try a specific term that occurs in your readings. It does not expand synonyms or translate queries. - PDF extraction requires a text layer. Scanned PDFs need OCR beforehand. Multi-column text, tables and mathematical notation may extract imperfectly. - Matching a quote does not establish the source's quality, relevance or truth. - Source hashes identify an imported file snapshot. They are not a publisher signature or proof that an exported pack has not been deliberately altered. - The workbench is for your own computer. It binds to `127.0.0.1` and is not a multiuser hosted service. See [SECURITY.md](SECURITY.md). ## Development ```sh git clone https://github.com/Lapmlnex/studyproof cd studyproof python -m pip install -e '.[dev,mcp]' python -m pytest ``` See [CONTRIBUTING.md](CONTRIBUTING.md) for small, useful ways to help and [docs/SOURCE_USE.md](docs/SOURCE_USE.md) for the implementation's source references. If StudyProof helps with a reading group, a course, or a research project, share the repository with someone who has the same problem. Reproducible bug reports and small example files are especially useful. ## License [MIT](LICENSE). Created by [Lapmlnex](https://github.com/Lapmlnex).