Study/README.md
Elijah f0aabe4d5d
All checks were successful
Verify and publish V2 container / build-and-push (push) Successful in 1m2s
First revision: DeepSeek, numeric questions, background assistant, UI fixes
Providers and pricing
- Add a DeepSeek provider: thinking mode with low/high/max effort, reasoning_content
  replayed between tool steps, cache-hit usage, /models discovery and catalog prices.
- Fix "does not support tool calling": a rejected forced tool_choice (DeepSeek thinking
  mode) now asks for the call in the prompt; only a genuine no-tools 400 is "unsupported".
- Seven reasoning-effort levels (Off to Max) mapped per adapter.
- Cached-input price per model, cache-write and DeepSeek off-peak aware cost estimates.
- Built-in bge-small embedding model (transformers.js) as the semantic search default.

Quizzes
- Numeric (type-the-answer) questions: units ignored, optional ± tolerance; editor,
  runner, importer, templates and generation prompts.
- Quiz start screen instead of showing answers; navigator ring no longer clipped and
  key legend removed; clock only for timed exams; 7-point letter grades.

Assistant and generation
- Assistant turns run on the server independently of the browser, with re-attach and
  an explicit stop; drafts tray shows generations in progress.
- Per-chat model switcher, @-tagging of class materials, full-width assistant page and
  a smaller assistant button.
- Editable generation instructions and built-in presets, separate from the chatbot
  import instructions.

Other
- Dialog footer padding, keyboard hints removed, copy buttons work over plain HTTP,
  class and folder shares include documents.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 12:48:17 -07:00

88 lines
4.3 KiB
Markdown

# Study Desk V2
A personal study platform for nursing school: classes and folders, quizzes, FSRS flashcards,
notes, private documents, and AI-assisted content creation. One administrator; friends study
through revocable public links without accounts.
## Run locally
Requires Node.js 24 or newer and npm. The development VM currently uses Node 26.
```powershell
npm.cmd ci
npm.cmd run dev
```
Open the Vite address printed in the terminal (normally http://localhost:5173).
The API listens on port 3726. For the production build locally:
```powershell
npm.cmd run build
npm.cmd start
```
Open http://localhost:3726. On a fresh install, enter the setup code from the server log or
`data/setup-code.txt`, then choose your administrator password. Alternatively set
`ADMIN_PASSWORD` for first startup. An optional `.env` file is loaded by the server; see
[.env.example](.env.example). Existing environment variables take precedence.
**This checkout already has an ignored `.env` pointing at `.data/` from development.**
Do not delete it or run reset/seed commands against content you want to keep. The demo seeder
is an opt-in development tool, never part of startup.
## What is implemented
- Classes, folders, search, edit/duplicate/move/delete actions; Markdown and embedded images.
- Multiple-choice, select-all and numeric (type-the-answer calculation) questions; a start
screen that hides answers, practice feedback, optional exam time limits, shuffle, partial
credit, saved sessions, missed-question review, 7-point letter grades and history.
- Flashcard editing, browse/self-assessment sessions, FSRS scheduling, persistent reviews,
undo, keyboard shortcuts and streak effects.
- Public quiz/deck/class/folder/note/document links. Collection (class and folder) shares
include current and future quizzes, decks, notes and processed documents.
- JSON import previews, validation, templates, content exports and a V1 SQLite import path.
- PDF/DOCX/PPTX/TXT/Markdown/image uploads; text extraction, OCR via a configured vision model,
chunking and SQLite FTS retrieval with source references.
- OpenAI, Anthropic, Gemini, DeepSeek, OpenAI-compatible and Ollama provider connections,
manual/discovered models, task routing with reasoning effort from Off to Max, encrypted keys
and usage estimates that price cached input separately.
- Semantic search with cloud embeddings or a built-in model that runs on the server.
- AI generation with editable drafts and editable instructions/presets; generation and
assistant answers keep running on the server when you leave the page. The assistant
searches materials, reads notes, creates drafts, finds weak topics, proposes confirmed
content changes, accepts @-tagged materials and can switch models per chat.
- Responsive light/dark interface and an installable app shell. Offline studying is limited:
private data is not cached; most operations need a server connection.
## Deploy, back up, migrate
See [deployment and restore](docs/DEPLOYMENT.md), [V1 migration](docs/MIGRATION.md), and
[AI providers and account integration](docs/AI.md).
The image runs a single Node process with SQLite and local file storage. No database or queue
container is required. The container runs as UID/GID 1000 and persists everything under `/data`.
```sh
docker compose up -d --build
```
Default V2 host port: **3727**, deliberately separate from the old application. Use a separate
data folder. Docker Desktop image build and disposable-container runtime checks now pass;
Unraid-specific permissions and reverse-proxy checks remain. No production deployment has
been performed.
## Verification and resuming work
```powershell
npm.cmd run check
```
Tests create isolated temporary databases. AI integration tests use a local mock server and
need loopback networking. They do not spend provider credits. Real provider credentials,
account-specific model access, Linux container behavior and Unraid proxy configuration must
be checked in their target environments.
[PROGRESS.md](PROGRESS.md) records completed work, remaining verification, decisions and the
resume procedure. V1 remains on `main` and in Git history; V2 work is on the `v2` branch.
Pushing `v2` to Forgejo runs CI and publishes the `study:v2` image (never `:latest`); see
[deployment](docs/DEPLOYMENT.md). Nothing deploys automatically.