1# Study Pal
 2
 3Study Pal 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 OpenAI's Responses API.
 6
 7## Features
 8
 9- Branching conversation tree with clickable question nodes
10- Root-to-current-branch conversation view
11- Ask about selected answer text with suggested or custom follow-ups
12- Streaming responses
13- Markdown, fenced code blocks, and LaTeX rendering through KaTeX
14- Persistent sessions and API settings in `localStorage`
15- Lightweight vanilla HTML, CSS, and JavaScript
16- Responsive concept map for desktop and small screens
17- Persistent light/dark theme with system-theme detection
18- Large-answer optimizations: throttled stream painting and `content-visibility`
19
20## Run locally
21
22You need a modern browser, an internet connection, and an OpenAI API key. A ChatGPT subscription/password is not an API key; create a project key in the [OpenAI dashboard](https://platform.openai.com/api-keys).
23
24From this directory, start any static file server. Python is commonly preinstalled:
25
26```bash
27python3 -m http.server 8080
28```
29
30Then open <http://localhost:8080>.
31
32Alternatively, with Node.js:
33
34```bash
35npx --yes serve .
36```
37
38Open the local URL printed by `serve`.
39
401. Choose **Settings**.
412. Paste an OpenAI API key.
423. Keep `gpt-5-mini`, or enter another model available to your API project.
434. Save and ask a question.
44
45The endpoint is configurable under **Advanced**, which is useful for an OpenAI-compatible Responses API. Compatibility depends on whether that provider implements the Responses API and browser CORS.
46
47## How branching works
48
49Each 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.
50
51The 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.
52
53## Storage and security
54
55The browser stores two local keys:
56
57- `study-pal:v1` — conversation nodes
58- `study-pal:settings:v1` — API key, model, endpoint, and system instructions
59
60This 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:
61
62- Run the app only from files you trust.
63- Do not publish or host this version as a public multi-user site.
64- Prefer a restricted OpenAI project key with appropriate spend limits.
65- Use **Settings → Forget key** before sharing the browser profile or local origin.
66- Using a different port creates a different browser origin and therefore a separate session.
67
68For a public deployment, put API calls behind an authenticated backend and keep the key in a server environment variable.
69
70## Performance notes
71
72Only 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. Off-screen messages use CSS `content-visibility`, and the concept map is built with a single document-fragment update.
73
74Very 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.
75
76## Browser support
77
78Use 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.
79
80## API reference
81
82The app uses `POST /v1/responses` with `stream: true` and reads Server-Sent Events. See the official [OpenAI streaming Responses documentation](https://developers.openai.com/api/docs/guides/streaming-responses).