papers-app 0.2.0__tar.gz

papers_app-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+data/
+.env
+dist/
+build/
+.ruff_cache/
+*.egg-info/

papers_app-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# Contributing to Papers
+
+Thanks for helping. Papers is a small app on purpose: a Python server (FastAPI) and a web page made of plain
+JavaScript modules, with no build step. If you can read Python and JavaScript, you can change any part of it.
+
+## Set up
+
+```bash
+git clone https://github.com/hBouanane/papers && cd papers
+python -m venv .venv
+.venv/Scripts/pip install -e ".[dev]"            # macOS/Linux: .venv/bin/pip
+.venv/Scripts/uvicorn papers.main:app --reload    # http://localhost:8000; restarts when Python changes
+```
+
+The web files are served as they are: edit them and reload the page. To try things without touching your own
+library, point the app at another folder: `PAPERS_DATA=./scratch` (or `papers --data ./scratch`).
+
+Before sending a pull request:
+
+```bash
+.venv/Scripts/ruff check papers tests    # style and common mistakes (`--fix` repairs most)
+.venv/Scripts/pytest -q                  # all AI and network calls are faked; no keys needed
+```
+
+CI runs both on Python 3.11 to 3.13 and checks that the Docker image starts.
+
+## How the code is laid out
+
+```
+papers/
+  cli.py            the `papers` command: options, then starts the server and opens the browser
+  config.py         where data lives and every environment variable
+  main.py           builds the app: the routers below, error handling, the web files, the Inbox watcher
+
+  routes/           the HTTP API, one file per part of the app
+    papers.py         add (search result, link, PDF), list, edit, delete, the PDF file, prepare
+    goals.py          goals (stored as "topics"), finding papers for them, BibTeX export
+    reading.py        progress, finishing, figures and tables, references, the chain a paper is in
+    learning.py       key points, vocabulary, explain/translate/ask (streamed), quiz and spaced review
+    notes.py          notes and highlights
+    recall.py         full-text search and "which paper had this idea?"
+    settings.py       name, language, AI provider, library folder and the folder picker
+
+  store.py          reading and writing papers; every change also updates the search index and the folder
+  ingest.py         turning a PDF into a paper, the Inbox, and preparing papers ahead of time with the AI
+  llm.py            every prompt: one function per task (skim, explain, glossary, quiz, grade, recall, ...), and the
+                    tutor's rules for conversations (TUTOR, TASKS: how Explain, Simplify, Translate and questions answer)
+  ai/               getting a prompt to the chosen model and its answer back; streaming.py: thinking vs answer, Stop,
+                    and giving up on a silent model
+  chat/             conversations: store.py (conversations and messages), answer.py (streams an answer and saves it)
+  agent/            Deep mode: tools.py (what the AI can look up and do), loop.py (the tool loop for each provider),
+                    mcp_server.py (the same tools for Claude Code)
+    providers.py      the provider list and which one is chosen, with its key, model and address
+    anthropic_api.py  claude_code.py  codex.py  openai_compat.py   one file per way of reaching a model
+
+  db.py             SQLite schema, migrations and settings     index.py   full-text search (SQLite FTS5)
+  pdf.py            text, titles and abstracts out of PDFs     figures.py figures and tables cut out of PDFs
+  scholar.py        Semantic Scholar and arXiv                 library.py the library folder (PDFs + Markdown notes)
+  notes.py          notes and highlights storage               folders.py the folder picker
+  bibtex.py         BibTeX entries
+
+  static/           the web app (no build step; ES modules loaded by the browser)
+    index.html        the page shell; links the stylesheets below in order
+    css/              styles by area, each file building on the ones before it:
+                        tokens (colours, shadows, fonts for light, dim and dark), base (type, page, top bar,
+                        theme switch, toast), components (buttons, cards, menus, covers, notes, vocabulary,
+                        combobox, folder picker), then one per screen: library, goals, recall, map, paper
+                        (overview, figures, review), reader, settings
+    js/main.js        routes each #/address to a page; paste and drop anywhere to add papers
+    js/core.js        shared helpers: api(), toast(), paper rows, markdown, the top bar
+    js/pages/         one file per screen: library, goals, recall, map, settings (+ shared.js)
+    js/paper/         a paper's screens: overview, reader, review, figures (+ shared.js)
+    js/paper/reader/  the reader's parts, wired together by readerPage() in reader.js; they share one
+                      state object (state.js: the paper, the page's elements, the open view):
+                        layout (markup), bar (one-row bar and its ⋯ menu), route (the pill at the bottom),
+                        views (PDF or Text, Go to…, back to where you stopped), progress (what you've read,
+                        skimming), selection (the bar on selected text), highlighter, panel (Ask, Words,
+                        Notes; streamed answers), finish, zoom, keys (shortcuts), terms + vocab (the Words switch:
+                        hard words marked in the page, with a card for each)
+    js/components/    reusable widgets: combobox (searchable dropdown), folderpicker
+    js/chat/          the conversation panel: conversation.js (History, composer, Quick/Deep), answer.js (an answer
+                      being written), stream.js, render.js (Markdown, math, citations, visuals), widgets.js,
+                      canvas.js (a visual opened large)
+    js/*.js           shared by the paper screens: pdfview (PDF.js), textview, highlights, notes, tracker,
+                      speech, readprefs (font, size, page tone), covers (first-page thumbnails), theme
+
+tests/              one file per feature, using FastAPI's test client against a temporary database
+```
+
+Two rules keep it easy to follow:
+
+- **Routes stay thin.** A route checks its input (the pydantic `...In` classes), calls `store`, `ingest` or
+  `llm`, and returns JSON. Logic that isn't about HTTP goes in a module next to them.
+- **The AI is only reached through `llm.py`.** Pages and routes never build prompts; tests replace the `llm`
+  functions with fakes (see `tests/conftest.py`, which also blocks any real AI call).
+
+## Common changes
+
+| You want to | Look at |
+| --- | --- |
+| Change what the AI writes (key points, quiz, ...) | the prompt in `papers/llm.py` |
+| Change how Explain or Simplify answer | `TASKS` in `papers/llm.py` (the rules all answers follow are `TUTOR`) |
+| Give the AI a new tool in Deep mode | a function and an entry in `TOOLS`, `papers/agent/tools.py` (`"act": True` if it changes the library, with `data` for Undo) |
+| Add a kind of visual | a fenced block in `papers/static/js/chat/render.js` (or a widget in `widgets.js`), and a line in `TUTOR` |
+| Add a provider that speaks the OpenAI chat API | one line in `PROVIDERS`, `papers/ai/providers.py` |
+| Add a provider with its own API | a module in `papers/ai/` with `parse()` and `stream()`, and a branch in `ai/__init__.py` |
+| Add an API endpoint | the matching file in `papers/routes/` (a new area gets a new file, added to `routes/__init__.py`) |
+| Add a column or table | `SCHEMA` and the migrations in `papers/db.py` |
+| Add a screen | a file in `static/js/pages/` and a line in the `routes` list of `static/js/main.js` |
+| Change colours or spacing | `static/css/tokens.css` (see [DESIGN.md](DESIGN.md)) |
+| Change how a screen looks | its file in `static/css/`; shared pieces are in `components.css` |
+| Change something in the reader | its part in `static/js/paper/reader/` (each file says what it does at the top) |
+
+## Style
+
+- Python: `ruff` settings in `pyproject.toml` (120 columns). Type hints on public functions; a docstring when
+  the name doesn't say it all.
+- JavaScript: ES modules, no framework, no build. Keep markup in template strings next to the code that
+  wires it up, and escape anything from the server or the user with `esc()`.
+- Text the user reads: short, plain sentences; say what to do, not what went wrong inside.
+- Light, dim and dark themes all need to look right, and motion respects `prefers-reduced-motion`.
+
+## Releasing
+
+Bump `__version__` in `papers/__init__.py` and push a tag like `v0.2.0`. The release workflow publishes to PyPI
+and pushes the Docker image to `ghcr.io`.

papers_app-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hBouanane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

papers_app-0.2.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: papers-app
+Version: 0.2.0
+Summary: An AI reading companion for research papers: skim, read, ask, recall. Runs on your computer.
+Project-URL: Homepage, https://github.com/hBouanane/papers
+Project-URL: Issues, https://github.com/hBouanane/papers/issues
+Author: hBouanane
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,llm,papers,pdf,reading,research
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: keyring>=24
+Requires-Dist: pdfplumber>=0.11
+Requires-Dist: pypdf>=5
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Papers
+
+An AI reading companion for research papers. Define what you are working on, get relevant
+papers, skim them Andrew Ng–style, read with an explainer that knows the whole paper, track
+where you stopped, quiz yourself when you finish, ask "where did I read this idea?", and follow
+reference chains. It runs on your computer; your papers and notes stay there.
+See [SPEC.md](SPEC.md) for the design.
+
+## Install
+
+With Python 3.11 or newer, one command (like `npx` for Node):
+
+```bash
+uvx papers-app
+```
+
+or install it to keep it around, then start it with `papers`:
+
+```bash
+pipx install papers-app
+```
+
+`papers` opens http://localhost:8000 in your browser. Options: `--port 9000`, `--data D:\Papers` (where the
+database and PDFs live), `--no-browser`, `--host 0.0.0.0` (reach it from other devices on your network; there
+is no login, so only on networks you trust).
+
+### With Docker
+
+```bash
+docker compose up -d
+```
+
+Then open http://localhost:8000. Your library is kept in the `papers-data` volume. See
+[docker-compose.yml](docker-compose.yml) to use a folder on your computer for the library folder, or a model
+running on your computer (Ollama, LM Studio). Subscriptions (Claude, ChatGPT) need their app on the same
+computer, so in Docker use an API key or a local model.
+
+### From the source
+
+```bash
+git clone https://github.com/hBouanane/papers && cd papers
+python -m venv .venv
+.venv/Scripts/pip install -e ".[dev]"     # macOS/Linux: .venv/bin/pip
+.venv/Scripts/papers
+```
+
+## Choosing an AI model
+
+Settings > AI model has one list of providers; each is set up the same way (key if it needs one, then
+**List models** and pick one). Each provider keeps its own key and model, so you can switch freely.
+
+- **Use your subscription**: Claude (Pro, Max) through [Claude Code](https://claude.com/claude-code), or
+  ChatGPT (Plus, Pro) through OpenAI's [Codex CLI](https://developers.openai.com/codex/cli/reference)
+  (`npm install -g @openai/codex`, then `codex login`). Both run on your computer with your own account,
+  for your own use: don't host the app for others on your subscription.
+- **Pay per use with an API key**: Anthropic, OpenAI, Google Gemini (has a free tier), Mistral, Groq, or
+  OpenRouter (hundreds of models).
+- **On this computer**: [Ollama](https://ollama.com) or [LM Studio](https://lmstudio.ai). Free, and nothing
+  leaves your machine.
+- **Other**: any OpenAI-compatible server (vLLM, llama.cpp, a company gateway), by its address.
+
+Small local models can't read a whole paper; *More options* can send just its beginning.
+Keys are kept in your system's keychain (Windows Credential Manager, macOS Keychain, or the Secret Service on Linux),
+so you paste each one once; Settings shows which provider has a key saved (its last four characters) and can forget
+it. Where there's no keychain (Docker, servers) they stay in the app's database. Keys are never sent back to the page.
+
+With a subscription the app runs the official CLI on your computer (`claude -p` or `codex exec`, with no
+tools), which signs in with your own account; usage counts toward your plan. The app never reads or stores
+those credentials. `PAPERS_CLAUDE_BIN` and `PAPERS_CODEX_BIN` point at a specific binary if needed.
+
+## Asking the AI
+
+Select text in a paper and press **Explain** (a short lesson: the problem, the idea, the formula read slowly, a worked
+example, why it works, where it connects in the paper), **Simplify** (the same passage in plain English) or
+**Translate**. Each starts a conversation you can keep going; **History** keeps them per paper, and **Add to chat**
+attaches more passages.
+
+Answers can contain formulas, clickable citations ([§3.4], [Fig. 1]), charts, diagrams, the paper's own figures with
+"look here" boxes, and interactive widgets. Switch the chat to **Deep** and the AI first reads the sections, looks at
+the figures and checks your notes and library before it answers; ask it to and it saves notes, words and
+highlights, or adds a paper from the references (each with Undo). Deep mode works with Claude (subscription or API
+key) and with models that support tool calling; in **More options**, tick *This model can see images* if yours does,
+and *Interactive pages* to let the AI write small demos that run in a sealed frame.
+
+## Library folder
+
+In Settings, choose a folder (**Choose…** opens a folder browser with your usual folders and drives) and the app keeps a copy of your
+library there: one folder per goal (`Unsorted` for the rest), each paper as `Author et al. Year - Title.pdf`
+with a `.md` notes file next to it (key points, explanations, quiz, `[[links]]` to related papers, so
+Obsidian shows them as a graph). PDFs dropped into its `Inbox` folder are imported within about 10 seconds.
+
+## Settings from the environment
+
+| Variable | What it does |
+| --- | --- |
+| `PAPERS_DATA` | Folder for the database, PDFs and figures (same as `--data`). Default: `%APPDATA%\Papers`, `~/Library/Application Support/Papers` or `~/.local/share/papers` |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | API keys, if you'd rather not type them in Settings |
+| `S2_API_KEY` | A Semantic Scholar key; without one, search often falls back to arXiv because of rate limits |
+| `PAPERS_MODEL` | The Claude model used by default (`claude-opus-5-5`) |
+| `PAPERS_INBOX_POLL` | Seconds between Inbox checks (`0` turns it off) |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md): how the code is laid out, how to run it and the tests, and where to
+start for common changes.
+
+## License
+
+[MIT](LICENSE)

papers_app-0.2.0/README.md

@@ -0,0 +1,109 @@
+# Papers
+
+An AI reading companion for research papers. Define what you are working on, get relevant
+papers, skim them Andrew Ng–style, read with an explainer that knows the whole paper, track
+where you stopped, quiz yourself when you finish, ask "where did I read this idea?", and follow
+reference chains. It runs on your computer; your papers and notes stay there.
+See [SPEC.md](SPEC.md) for the design.
+
+## Install
+
+With Python 3.11 or newer, one command (like `npx` for Node):
+
+```bash
+uvx papers-app
+```
+
+or install it to keep it around, then start it with `papers`:
+
+```bash
+pipx install papers-app
+```
+
+`papers` opens http://localhost:8000 in your browser. Options: `--port 9000`, `--data D:\Papers` (where the
+database and PDFs live), `--no-browser`, `--host 0.0.0.0` (reach it from other devices on your network; there
+is no login, so only on networks you trust).
+
+### With Docker
+
+```bash
+docker compose up -d
+```
+
+Then open http://localhost:8000. Your library is kept in the `papers-data` volume. See
+[docker-compose.yml](docker-compose.yml) to use a folder on your computer for the library folder, or a model
+running on your computer (Ollama, LM Studio). Subscriptions (Claude, ChatGPT) need their app on the same
+computer, so in Docker use an API key or a local model.
+
+### From the source
+
+```bash
+git clone https://github.com/hBouanane/papers && cd papers
+python -m venv .venv
+.venv/Scripts/pip install -e ".[dev]"     # macOS/Linux: .venv/bin/pip
+.venv/Scripts/papers
+```
+
+## Choosing an AI model
+
+Settings > AI model has one list of providers; each is set up the same way (key if it needs one, then
+**List models** and pick one). Each provider keeps its own key and model, so you can switch freely.
+
+- **Use your subscription**: Claude (Pro, Max) through [Claude Code](https://claude.com/claude-code), or
+  ChatGPT (Plus, Pro) through OpenAI's [Codex CLI](https://developers.openai.com/codex/cli/reference)
+  (`npm install -g @openai/codex`, then `codex login`). Both run on your computer with your own account,
+  for your own use: don't host the app for others on your subscription.
+- **Pay per use with an API key**: Anthropic, OpenAI, Google Gemini (has a free tier), Mistral, Groq, or
+  OpenRouter (hundreds of models).
+- **On this computer**: [Ollama](https://ollama.com) or [LM Studio](https://lmstudio.ai). Free, and nothing
+  leaves your machine.
+- **Other**: any OpenAI-compatible server (vLLM, llama.cpp, a company gateway), by its address.
+
+Small local models can't read a whole paper; *More options* can send just its beginning.
+Keys are kept in your system's keychain (Windows Credential Manager, macOS Keychain, or the Secret Service on Linux),
+so you paste each one once; Settings shows which provider has a key saved (its last four characters) and can forget
+it. Where there's no keychain (Docker, servers) they stay in the app's database. Keys are never sent back to the page.
+
+With a subscription the app runs the official CLI on your computer (`claude -p` or `codex exec`, with no
+tools), which signs in with your own account; usage counts toward your plan. The app never reads or stores
+those credentials. `PAPERS_CLAUDE_BIN` and `PAPERS_CODEX_BIN` point at a specific binary if needed.
+
+## Asking the AI
+
+Select text in a paper and press **Explain** (a short lesson: the problem, the idea, the formula read slowly, a worked
+example, why it works, where it connects in the paper), **Simplify** (the same passage in plain English) or
+**Translate**. Each starts a conversation you can keep going; **History** keeps them per paper, and **Add to chat**
+attaches more passages.
+
+Answers can contain formulas, clickable citations ([§3.4], [Fig. 1]), charts, diagrams, the paper's own figures with
+"look here" boxes, and interactive widgets. Switch the chat to **Deep** and the AI first reads the sections, looks at
+the figures and checks your notes and library before it answers; ask it to and it saves notes, words and
+highlights, or adds a paper from the references (each with Undo). Deep mode works with Claude (subscription or API
+key) and with models that support tool calling; in **More options**, tick *This model can see images* if yours does,
+and *Interactive pages* to let the AI write small demos that run in a sealed frame.
+
+## Library folder
+
+In Settings, choose a folder (**Choose…** opens a folder browser with your usual folders and drives) and the app keeps a copy of your
+library there: one folder per goal (`Unsorted` for the rest), each paper as `Author et al. Year - Title.pdf`
+with a `.md` notes file next to it (key points, explanations, quiz, `[[links]]` to related papers, so
+Obsidian shows them as a graph). PDFs dropped into its `Inbox` folder are imported within about 10 seconds.
+
+## Settings from the environment
+
+| Variable | What it does |
+| --- | --- |
+| `PAPERS_DATA` | Folder for the database, PDFs and figures (same as `--data`). Default: `%APPDATA%\Papers`, `~/Library/Application Support/Papers` or `~/.local/share/papers` |
+| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` | API keys, if you'd rather not type them in Settings |
+| `S2_API_KEY` | A Semantic Scholar key; without one, search often falls back to arXiv because of rate limits |
+| `PAPERS_MODEL` | The Claude model used by default (`claude-opus-5-5`) |
+| `PAPERS_INBOX_POLL` | Seconds between Inbox checks (`0` turns it off) |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md): how the code is laid out, how to run it and the tests, and where to
+start for common changes.
+
+## License
+
+[MIT](LICENSE)

papers_app-0.2.0/papers/__init__.py

@@ -0,0 +1,2 @@
+"""Papers: an AI reading companion for research papers."""
+__version__ = "0.2.0"

papers_app-0.2.0/papers/__main__.py

@@ -0,0 +1,3 @@
+from papers.cli import main
+
+main()

papers_app-0.2.0/papers/agent/__init__.py

@@ -0,0 +1,2 @@
+"""Deep mode: the AI uses tools (tools.py) in a loop (loop.py) while it answers; mcp_server.py gives the same tools
+to Claude Code."""