1# Study Lab
  2
  3Study Lab is a local-first, branching AI chat for exploring technical concepts. Every question becomes a node in a concept map. Select any earlier node to continue from that point, or select text inside an answer and ask a focused follow-up.
  4
  5The app is intentionally frontend-only: there is no build step, package manager, backend, or database. Conversations and settings persist in the browser's `localStorage`, while responses stream directly from either OpenAI or OpenRouter's Responses API.
  6
  7## Features
  8
  9- can branch off any previous answer
 10- select a chunk of text from an answer and ask about it
 11- vim-like shortcuts
 12- plain js + html + css
 13- provider API keys and history stay local in your browser; questions go directly to the selected provider
 14- the composer shows the active model and provider at a glance
 15- each generated answer records and displays the model and provider that produced it
 16- you see token usage and cost estimations
 17
 18other:
 19- branching conversation tree with clickable question nodes
 20- root-to-current-branch conversation view
 21- ask about selected answer text with suggested or custom follow-ups
 22- streaming responses
 23- markdown, fenced code blocks, and LaTeX rendering through KaTeX
 24- persistent sessions and API settings in `localStorage`
 25- lightweight vanilla HTML, CSS, and JavaScript
 26- responsive concept map for desktop and small screens
 27- persistent light/dark theme with system-theme detection
 28- monthly token tracking with per-model details and a local billing estimate
 29- independent chat-history clearing and per-conversation deletion
 30- multiple persistent maps with a browsable conversation sidebar
 31- per-map PDF context for books and papers, uploaded once through the Files API
 32- debounced search across map titles, questions, answers, and PDF names
 33- collapsible, zoomable concept trees with active-path highlighting
 34- vim-style keyboard navigation for nodes, maps, search, and the composer
 35- large-answer optimizations through throttled stream painting
 36
 37![Study Lab main view showing a branching conversation](screenshots/main%20view.png)
 38
 39## Run locally
 40
 41You need a modern browser, an internet connection, and either an [OpenAI API key](https://platform.openai.com/api-keys) or an [OpenRouter API key](https://openrouter.ai/settings/keys). A ChatGPT subscription/password is not an OpenAI API key.
 42
 43From this directory, start any static file server. Python is commonly preinstalled:
 44
 45```bash
 46python3 -m http.server 8080
 47```
 48
 49Then open <http://localhost:8080>.
 50
 51Alternatively, with Node.js:
 52
 53```bash
 54npx --yes serve .
 55```
 56
 57Open the local URL printed by `serve`.
 58
 591. Choose **Settings**.
 602. Select **OpenAI** or **OpenRouter**.
 613. Paste that provider's API key.
 624. Choose a suggested model or enter any model ID available to your account. OpenRouter model IDs use the `provider/model` form, such as `openai/gpt-5-mini`.
 635. Save and ask a question.
 64
 65Settings places the active-provider dropdown at the top and shows separate OpenAI and OpenRouter configuration cards at the same time. Each card stores its own API key, model, and endpoint, so switching providers does not require re-entering its configuration.
 66
 67To ask about a book or paper, choose **+ PDF** beside the composer and select one or more PDFs. The files are attached to the current map and included with questions sent through the same provider, including questions asked from older branches. Each file must be under 50 MB, and files attached through one provider in a map must total under 50 MB.
 68
 69The endpoint for each provider is configurable under **Advanced**. OpenAI defaults to `https://api.openai.com/v1/responses`; OpenRouter defaults to `https://openrouter.ai/api/v1/responses`.
 70
 71## How branching works
 72
 73Each node stores its parent ID. Clicking a node makes it the active context and displays only the path from the root to that node. The next question becomes its child. Selecting text within an answer and choosing **Ask** creates a child of the answer's node, even if another branch was active.
 74
 75The complete parent-path conversation is sent with each request. This makes every branch self-contained and avoids coupling local history to provider-side response IDs.
 76
 77![Using Go deeper to ask a focused follow-up about selected text](screenshots/go%20deeper.png)
 78
 79## Multiple maps
 80
 81Choose **New map** in the header or conversation sidebar to open a blank map. The current map is retained automatically. Use the left **Conversations** sidebar to switch between saved maps; each entry shows its title, node count, and last activity date. Use ✎ to rename a map or × to delete its entire conversation. A custom title remains unchanged as new questions are added; submitting a blank title restores automatic naming. Existing sessions from the original single-map storage format are migrated automatically.
 82
 83**Settings → Clear chat history** is the explicit destructive action that removes all saved maps. It does not remove the API key, other settings, or the separate API-usage ledger.
 84
 85## Search and navigation
 86
 87Use the search field in the conversation sidebar—or press `/` outside an input—to search all saved map titles, questions, answers, and PDF names. Results link directly to the matching map or question node. Search is debounced and capped at 60 displayed results to keep large workspaces responsive.
 88
 89The concept-map toolbar can expand or collapse all branches and zoom the tree from 80% to 140%. Individual branches have disclosure arrows, and their collapsed state persists with the map. The current root-to-node path remains highlighted.
 90
 91![Study Lab tree and conversation navigation](screenshots/tree%20navbar.png)
 92
 93Vim-style shortcuts work whenever a text field or dialog control is not focused:
 94
 95- `j` / `k` — next / previous visible concept node
 96- `h` / `l` — parent / first child; `l` expands a collapsed active node first
 97- `gg` / `G` — first / last visible node
 98- `J` / `K` — next / previous conversation
 99- `Space` — collapse or expand the active node
100- `/` — focus cross-conversation search
101- `i` — focus the question composer
102- `Esc` — leave input or search mode
103- `?` — open the in-app shortcut reference
104
105![In-app reference for Vim-style keyboard shortcuts](screenshots/vim%20shortcuts.png)
106
107## PDF context
108
109PDFs are uploaded directly from the browser to the selected provider's Files endpoint, derived from its configured Responses API URL. Only their file IDs, provider, names, and sizes are stored in `localStorage`; the PDF bytes are not copied into browser storage. Page images use low visual detail to reduce token use, while extracted PDF text remains available to the model. Use a model that supports PDF inputs.
110
111File IDs belong to the provider that received the upload. If you switch providers, PDFs uploaded to the other provider remain visible but are dimmed and are not sent. Upload the PDF again while the new provider is selected to use it there.
112
113PDF parsing adds extracted text and page images to the prompt, so large books can consume substantial input tokens on every question. The header usage tracker includes tokens reported for these requests. For very large collections or frequent querying, OpenAI recommends retrieval with File Search; this lightweight local app intentionally uses direct PDF input and does not create vector stores.
114
115Removing a PDF chip or clearing local chat history detaches the file locally but does **not** delete the uploaded copy from OpenAI. Delete retained files separately through your OpenAI account if needed. Custom API providers must expose a compatible `/files` endpoint next to their configured `/responses` endpoint.
116
117## Storage and security
118
119The browser stores these local keys:
120
121- `study-lab:v1` — multi-map conversation workspace, PDF file references, collapsed branches, and active-map selection
122- `study-lab:settings:v1` — selected provider, per-provider API keys/models/endpoints, and system instructions
123- `study-lab:usage:v1` — token usage and estimated request costs recorded by this browser
124- `study-lab:openrouter-prices:v1` — a bounded cache of recently used OpenRouter model rates
125- `study-lab:theme` — light/dark theme preference
126- `study-lab:tree-zoom` — concept-map zoom preference
127
128Data saved by releases before the rename is copied into the new storage namespace automatically on first load.
129
130The usage button in the header counts tokens reported by completed Responses API requests made from this browser. OpenAI requests use a local pricing table. For OpenRouter requests, Study Lab looks up the model returned by the response through OpenRouter's single-model API and caches its prompt, completion, cache-read, and request rates for 24 hours. Each usage record retains the exact rate snapshot used for its USD estimate.
131
132These values are estimates, not invoices. OpenRouter's model endpoint reports its current model price structure, which can differ from the final routed-provider charge or charges for non-token features. The tracker also cannot see other browsers or applications, older untracked requests, credits, taxes, or special pricing. Use the linked dashboard for the selected provider as the source of truth for billing.
133
134![API usage details with token and cost estimates](screenshots/api%20usage.png)
135
136This design is convenient for a private tool on your own laptop, but browser storage is not a secure secret vault. Any JavaScript executing on the same origin can read it. Therefore:
137
138- Run the app only from files you trust.
139- Do not publish or host this version as a public multi-user site.
140- Prefer restricted provider keys with appropriate spend limits.
141- Use **Settings → Forget key** before sharing the browser profile or local origin.
142- Using a different port creates a different browser origin and therefore a separate session.
143
144For a public deployment, put API calls behind an authenticated backend and keep the key in a server environment variable.
145
146## Performance notes
147
148Only the active branch is added to the main document; sibling branches remain compact data in `localStorage`. Streaming UI updates are batched roughly every 70 ms instead of rerendering for every token, and the concept map is built with a single document-fragment update.
149
150Very large sessions are ultimately limited by the browser's `localStorage` quota (usually a few megabytes). Start a new map when the saved tree becomes unusually large.
151
152## Browser support
153
154Use a current version of Chrome, Edge, Firefox, or Safari. LaTeX loads from the jsDelivr CDN; if it cannot load, equations remain visible as plain source text. The OpenAI API must allow requests from your local browser origin. If a corporate browser policy or custom endpoint blocks CORS, a small local proxy backend would be required.
155
156## API reference
157
158The app uses the selected provider's Responses endpoint with `stream: true` and reads Server-Sent Events. See the official [OpenAI streaming Responses documentation](https://developers.openai.com/api/docs/guides/streaming-responses) and [OpenRouter Responses documentation](https://openrouter.ai/docs/api_reference/responses/overview).