diff --git a/README.md b/README.md index 41254b3..774a4fb 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,272 @@ -# StudyOS +
-Plataforma de estudio personal con IA. Chat con streaming, seguimiento de progreso, procesamiento de PDFs, y micro-chats temáticos (fork/merge). +![StudyOS](https://img.shields.io/badge/StudyOS-7C3AED?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9IiNmZmYiIHN0cm9rZS13aWR0aD0iMiI+PGNpcmNsZSBjeD0iMTIiIGN5PSIxMiIgcj0iMTAiLz48cGF0aCBkPSJNMTIgNmgtLjVhMy41IDMuNSAwIDEgMCAwIDdoMWMzLjE0IDAgMy41IDMgMS41IDUiLz48L3N2Zz4=) +![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white) +![React](https://img.shields.io/badge/React-18-087ea4?logo=react) +![SQLite](https://img.shields.io/badge/SQLite-WASM-003b57?logo=sqlite&logoColor=white) +![License](https://img.shields.io/badge/license-MIT-blue) -## Stack -- **Backend**: Node.js + Express + SQLite (sql.js, WASM — sin compilación nativa) -- **Frontend**: React 18 + Vite -- **Streaming**: Server-Sent Events (SSE) +**AI-powered study platform. Chat with your notes, fork topics, track progress — all local, all yours.** -## Requisitos -- Node.js 18+ +
-## Instalación +--- + +## What StudyOS Does + +Upload your PDFs, talk to an LLM that reads them, split conversations into topic-focused forks, do exercises, track your progress, review with flashcards, generate exams — all in one polished dark-UI interface. No cloud accounts, no data leaving your machine. + +``` + ┌─────────────┐ ┌──────────────┐ ┌────────────────┐ + │ React 18 │────▶│ Express API │────▶│ SQLite (WASM) │ + │ + Vite │◀────│ :3001 │ │ sql.js │ + └─────────────┘ SSE └──────┬───────┘ └────────────────┘ + │ + ┌─────────┼─────────┐ + ▼ ▼ ▼ + ┌────────┐ ┌──────┐ ┌──────────────┐ + │ glm │ │ VLM │ │ Transformers │ + │ 4.5-air│ │glm4.6v│ │ .js (local) │ + └────────┘ └──────┘ └──────────────┘ +``` + +## Features + +### Chat & AI +- **Streaming chat** (SSE) — tokens appear in real time, dual adapter (Anthropic + OpenAI-compatible) +- **Multi-model** — configure any OpenAI-compatible endpoint, switch on the fly +- **Syntax highlighting** — `prismjs` with auto-language detection from code fences +- **LaTeX rendering** — `KaTeX` for all inline and block math +- **Graph rendering** — inline SVG coordinate planes via ` ```graph ` blocks +- **Voice input** — Web Speech API microphone to text +- **LaTeX editor** — real-time preview while typing + +### PDF Processing +- **Upload & extract** — VLM extraction first (`glm-4.6v`), `pdfjs-dist` fallback +- **RAG search** — local embeddings via `@xenova/transformers` (ONNX Runtime + DirectML GPU), cosine similarity retrieval over chunks +- **Multi-PDF compare** — side-by-side view of two PDFs +- **Sidebar search** — FTS5 full-text search across all PDFs and messages, with LIKE fallback + +### Study System +- **Conversations** — organized chat threads with file attachments +- **Forks** — branch any topic into a focused sub-chat, merge back when done +- **Auto-fork suggestion** — model detects when you're struggling and suggests a practice fork +- **Exercises** — model generates exercises, auto-detects correctness, logs to progress +- **Progress tracking** — per-topic stats (exercises done, correct, accuracy, difficulty) +- **Difficulty auto-adjust** — lowers difficulty after consecutive failures +- **Calendar heatmap** — GitHub-style study activity visualization +- **Pomodoro timer** — 25/5 minute cycles with browser notifications + +### Exams & Flashcards +- **Exam generator** — AI generates exams from your progress data +- **Timed exams** — countdown timer, auto-submit on expiry, instant grading +- **Exam PDF export** — download any exam as printable PDF via `pdfkit` +- **Flashcard generator** — LLM creates Q&A cards from your PDFs and exercises +- **SM-2 spaced repetition** — science-backed review scheduling with ease factor +- **Review queue** — sidebar badge shows due cards + +### Collaboration +- **Study buddy mode** — share a conversation via token, two users chat with AI referee +- **WebSocket real-time** — progress and buddy message push across tabs + +### UI & UX +- **Dark/light theme** — toggle with CSS variables, persisted to localStorage, zero flash +- **Glassmorphism** — indigo/purple gradients, backdrop blur, micro-interactions +- **Sidebar** — collapsible sections, PDF reorder via drag-and-drop, search bar +- **Fork panel** — resizeable right panel, own chat context +- **Toasts** — context-based notification system for success/error feedback +- **Skeleton loading** — animated placeholders while data loads +- **Scroll-to-bottom FAB** — appears when scrolled up in chat +- **Keyboard shortcuts** — `Ctrl+N` new chat, `Ctrl+K` search, `Escape` close panels, `Ctrl+Enter` send +- **PWA** — install as native app via `vite-plugin-pwa` +- **Responsive** — sidebar auto-collapses on mobile with hamburger overlay +- **Message copy** — hover to reveal copy button on any message + +### Infrastructure +- **Zero native deps** — `sql.js` WASM for SQLite, `@xenova/transformers` WASM for embeddings +- **Tests** — `vitest` (jsdom) on client, `node:test` on server +- **DB backup/restore** — download/upload SQLite file from Settings +- **Rate limiting** — client-side guard blocks concurrent sends + +--- + +## Quick Start ```bash +# 1. Install cd studyos/server && npm install cd studyos/client && npm install + +# 2. Run backend (terminal 1) +cd studyos/server && node index.js + +# 3. Run frontend (terminal 2) +cd studyos/client && npm run dev + +# 4. Open http://localhost:5173 ``` -## Desarrollo +First launch: the embeddings model (~118 MB) downloads automatically to `server/node_modules/.cache/transformers/`. Chat works immediately — embeddings are ready after the warmup completes (check server logs). -```bash -# Terminal 1 — Backend -cd studyos/server -node index.js - -# Terminal 2 — Frontend -cd studyos/client -npm run dev -``` - -Abrí http://localhost:5173 en el navegador. - -## Producción +## Production ```bash cd studyos/client && npm run build cd studyos/server && node index.js +# Everything served from http://localhost:3001 ``` -Todo se sirve desde http://localhost:3001. +## Configuration -## Estructura +Everything lives in the Settings page. No `.env` file needed. + +| Setting | Default | Purpose | +|---------|---------|---------| +| Main model | None | LLM for chat (OpenAI-compatible endpoint) | +| Fork model | None | LLM used inside forks (falls back to main) | +| VLM endpoint | None | Vision model for PDF extraction | +| VLM API key | None | Key for the vision endpoint | +| Admin key | None | Required for DB backup/restore | + +### Recommended: Z.ai + +| Role | Model | Endpoint | +|------|-------|----------| +| Chat | `glm-4.5-air` | `https://api.z.ai/api/coding/paas/v4` | +| Vision | `glm-4.6v` | `https://api.z.ai/api/coding/paas/v4` | + +StudyOS is provider-agnostic — any OpenAI-compatible endpoint works. + +--- + +## Architecture + +### Backend (`server/`) ``` -studyos/ -├── server/ # Backend Express -│ ├── index.js # Servidor principal + init async -│ ├── db.js # Schema SQLite vía sql.js (WASM) + seed -│ ├── lib/llm.js # Adaptador SSE (Anthropic + OpenAI) -│ ├── routes/ # Endpoints REST -│ └── systemPromptBuilder.js -├── client/ # Frontend React + Vite -│ └── src/ -│ ├── components/ # Sidebar, MainChat, ForkPanel, etc. -│ ├── hooks/ # useChat, usePdfs, useProgress -│ ├── pages/ # Settings -│ └── lib/ # API client -└── data/ # SQLite database (auto-creado) +server/ +├── index.js # Express + WebSocket server, async DB init +├── db.js # sql.js schema, migrations, seed +├── systemPromptBuilder.js # Context-aware prompt: PDFs, progress, RAG, difficulty +├── lib/ +│ ├── llm.js # Dual SSE adapter (Anthropic SDK + OpenAI SDK) +│ ├── embeddings.js # @xenova/transformers pipeline (webgpu → wasm) +│ ├── rag.js # chunkText, cosineSimilarity, searchRelevant +│ ├── broadcast.js # WebSocket broadcast with buddy support +│ └── sm2.js # SM-2 spaced repetition algorithm +└── routes/ + ├── chat.js # SSE streaming, RAG pipeline, auto-fork, difficulty + ├── conversations.js # CRUD, fork, merge, study buddy share/join + ├── pdfs.js # Upload, VLM extraction, embedding generation + ├── progress.js # Topic stats, study sessions, heatmap, exam PDF + ├── exams.js # Generate, start, submit timed exams + ├── flashcards.js # SSE generation, SM-2 reviews, due queue + ├── search.js # FTS5 full-text search with LIKE fallback + ├── models.js # LLM model CRUD, default exclusivity + ├── config.js # Key-value config, VLM test, DB backup/restore + └── notes.js # Simple notes CRUD ``` -## Configuración Inicial +### Frontend (`client/`) -1. La base de datos se crea automáticamente en `data/studyos.db` -2. El modelo por defecto es `claude-sonnet-4` (Anthropic) -3. Configurá tus API keys en Settings → Modelos -4. El endpoint VLM por defecto es `http://localhost:8080/vlm` +``` +client/src/ +├── components/ +│ ├── Sidebar.jsx # Conv list, PDFs, search, theme toggle, nav +│ ├── MainChat.jsx # Chat area, graph panel, rename, scroll FAB +│ ├── MessageBubble.jsx # Markdown, KaTeX, Prism, reactions, copy +│ ├── ForkPanel.jsx # Resizeable fork chat panel +│ ├── ChatInput.jsx # Text area, voice input, LaTeX toggle, send +│ ├── SearchBar.jsx # FTS5 modal overlay with results +│ ├── ThemeToggle.jsx # Dark/light switch +│ ├── [17 more components] # All features listed above +├── hooks/ +│ ├── useChat.js # SSE stream, send, fork/difficulty events +│ ├── useExam.js # Timer, auto-submit, navigation +│ ├── useFlashcards.js # Queue, review, due count +│ ├── usePdfs.js # Upload, reorder, delete, refresh +│ ├── useProgress.js # Stats, WebSocket subscription +│ ├── useSearch.js # Debounced FTS5 queries +│ ├── useStudyBuddy.js # Token join, WebSocket sync +│ └── [6 more hooks] +├── lib/ +│ ├── api.js # All endpoint functions +│ └── sm2.js # Client-side SM-2 mirror +├── context/ +│ └── ReactionsContext.jsx # 👍/👎 session-local state +├── pages/ +│ └── Settings.jsx # Models, VLM, backup/restore, exam export, theme +└── data/ + └── roadmap.json # Topic relationship graph +``` -## Features +### Database -- 💬 Chat con streaming SSE (Anthropic + OpenAI-compatible) -- 📄 Subida y procesamiento de PDFs -- 📊 Seguimiento de progreso por tema -- 🔀 Micro-chats temáticos (fork/merge) -- 🎨 Tema oscuro con diseño pulido -- ⚙️ Configuración de modelos y VLM +SQLite via `sql.js` (WASM). Tables include `conversations`, `messages`, `pdfs`, `models`, `progress`, `exams`, `flashcards`, `flashcard_reviews`, `study_sessions`, `embeddings`, `shared_conversations`, `conversation_participants`, `topic_relationships`, plus FTS5 virtual tables for full-text search. + +--- + +## API Overview + +| Method | Path | Purpose | +|--------|------|---------| +| `POST` | `/api/chat/:id/stream` | SSE chat streaming | +| `GET/POST` | `/api/conversations` | List / create conversations | +| `POST` | `/api/conversations/:id/fork` | Create topic fork | +| `POST` | `/api/conversations/:id/merge` | Merge fork back | +| `POST` | `/api/conversations/:id/share` | Generate buddy token | +| `POST` | `/api/conversations/join` | Join buddy conversation | +| `POST` | `/api/pdfs/upload` | Upload PDF + extract + embed | +| `GET` | `/api/progress?main_id=:id` | Topic-level progress | +| `GET` | `/api/progress/heatmap?days=365` | Study activity data | +| `GET` | `/api/progress/exam/pdf` | Download exam as PDF | +| `POST` | `/api/exams/generate` | AI-generated exam | +| `POST` | `/api/exams/:id/submit` | Submit exam answers | +| `POST` | `/api/flashcards/generate` | SSE flashcard generation | +| `PUT` | `/api/flashcards/:id/review` | SM-2 review (quality 0-5) | +| `GET` | `/api/flashcards/reviews/due` | Due review queue | +| `GET` | `/api/search?q=term` | FTS5 search messages + PDFs | +| `GET` | `/api/config/backup` | Download DB (auth required) | +| `POST` | `/api/config/restore` | Upload DB (auth required) | +| `GET` | `/api/models` | Available chat models | +| `WS` | `ws://localhost:3001` | Progress push, buddy messages | + +--- + +## Testing + +```bash +# Client (vitest + jsdom) +cd studyos/client && npm test + +# Server (node:test) +cd studyos/server && npm test +``` + +--- + +## Tech Stack + +| Layer | Technology | +|-------|-----------| +| Runtime | Node.js 18+ | +| Backend | Express 4, `ws` | +| Database | SQLite via `sql.js` (WASM — zero native) | +| Frontend | React 18, Vite 5 | +| Routing | react-router-dom v6 | +| Markdown | react-markdown v9 | +| Math | KaTeX 0.17 | +| Syntax | Prism.js 1.30 | +| Charts | Recharts | +| Drag & drop | @dnd-kit | +| Icons | Lucide React | +| PWA | vite-plugin-pwa | +| Tests | Vitest + @testing-library/react (client), node:test (server) | +| LLM client | Anthropic SDK + OpenAI SDK | +| Embeddings | @xenova/transformers (local, WASM + DirectML) | +| PDF export | pdfkit | +| PDF extraction | pdfjs-dist | + +## License + +MIT