| # StudyAgent — FOR_SMLFLG |
| |
| ## Was ist das? |
| ADHS-freundlicher Study Buddy: Hilft Studenten mit ADHS durch ihr Semester. |
| Keine starren Plaene — Micro-Steps, Buddy-Ton, Dopamin beim Start statt beim Abschluss. |
| |
| ## Warum |
| Samuel IS die Zielgruppe. 569 ChatGPT + 232 Claude Sessions dokumentieren das Problem. |
| Kern-Insight: Dopamin kommt beim Task-BEGINN, nicht beim Complete. Jeder Step = frischer Start. |
| |
| ## Pain Points die das System loest |
| 1. Lernplaene die nie halten — elastischer Plan, kein Guilt |
| 2. WIP explodiert — max 2 Faecher gleichzeitig (hard enforcement in API) |
| 3. Zeitdruck als Feature — Panik-Modus bei <48h |
| 4. Routinedokumentation unmoeglich — Micro-Steps (je 5 Min) |
| 5. Session-Memory — nie wieder bei Null anfangen |
| |
| ## Architektur & Tech-Stack |
| |
| ``` |
| StudyAgent/ |
| ├── main.py # FastAPI app, alle Routes, htmx-Partials (~516 LOC) |
| ├── agent.py # MiniMax M2.5 API-Call, Fallback-Steps ohne Key |
| ├── models.py # SQLAlchemy Models (Subject, Deadline, MicroStep, StudySession) |
| ├── database.py # SQLite Setup, Session-Maker |
| ├── requirements.txt |
| ├── static/style.css # Warm palette, ADHS-friendly Design |
| ├── templates/ |
| │ ├── base.html |
| │ ├── index.html |
| │ └── partials/ # subject_card, deadline_item, micro_step_card, |
| │ # elastic_plan, progress_journey, session_banner |
| └── study_agent.db # auto-created |
| ``` |
| |
| **Tech:** Python + FastAPI (async, lifespan) + SQLAlchemy + SQLite + htmx + Jinja2 + MiniMax M2.5 API |
| |
| ## Starten / Nutzen |
| |
| ```bash |
| cd ~/Projekte/StudyAgent |
| |
| # Erste Einrichtung |
| pip install -r requirements.txt |
| export MINIMAX_API_KEY=your-key-here # optional — ohne Key laufen Fallback-Steps |
| |
| # Starten |
| .venv/bin/uvicorn main:app --reload # oder: uvicorn main:app --reload |
| # open http://localhost:8000 |
| ``` |
| |
| ## Was funktioniert (implementiert) |
| |
| - **Dashboard** (`GET /`) — aktive Faecher, naechste Deadlines, naechster Step, Session-Banner, Panik-Indikatoren |
| - **Faecher CRUD** (`POST/DELETE /subjects`) — WIP-Limit 2 wird server-seitig enforced |
| - **Deadlines anlegen** (`POST /deadlines`) — auto-generiert sofort Micro-Steps via MiniMax M2.5 |
| - **Steps abschliessen/ueberspringen** (`POST /steps/{id}/complete|skip`) — naechster Step wird inline geladen |
| - **Elastischer Plan** (`GET /deadlines/{id}/plan`) — auto-komprimiert wenn Steps die verbleibende Zeit uebersteigen |
| - **Replan** (`POST /deadlines/{id}/replan`) — loescht pending+skipped, generiert neu |
| - **Session-Tracking** — Sessions werden auto-gestartet, after 30 Min Inaktivitaet auto-geschlossen |
| - **Panik-Modus** (`is_panic_mode()`) — greift bei <48h, reduziert auf 3-4 wesentliche Steps |
| - **AI-Fallback** — ohne `MINIMAX_API_KEY` kommen sinnvolle Dummy-Steps (kein Absturz) |
| |
| ## Was fehlt / bekannte Issues |
| |
| - `.env` vorhanden (`MINIMAX_API_KEY`), in `.gitignore` geschuetzt. `.env.example` als Vorlage vorhanden. |
| - Browser-Test-Flow (Subject anlegen → Dashboard → Steps) noch nicht durchgespielt |
| - `fi_date`-aehnlicher Edge-Case: wenn `due_date` bereits vergangen ist, liefert `is_panic_mode()` `False` statt sinnvollen Zustand |
| - Kein Deployment-Setup (Fly.io geplant) |
| - Kein Auth (MVP-bewusste Entscheidung) |
| |
| ## Entscheidungen & Lessons Learned |
| |
| - **htmx statt React** — kein Build-Step, Partials direkt vom Server, funktioniert ohne JS-Framework |
| - **Buddy-Ton in Code** — "Kein Stress, machen wir anders." direkt in Responses, kein separates i18n |
| - **Dummy-Steps als Fallback** — API-Fehler oder fehlender Key darf nie das Feature brechen |
| - **WIP-Limit server-seitig** — nicht nur UI-Warnung, sondern echter `HTTPException`-Block im `POST /subjects` |
| - **Auto-compress elastisch** — 20% Buffer-Formel: wenn `pending * 5min > hours_left * 0.8 * 60` → Replan |
|
|
| ## Next Steps (priorisiert) |
|
|
| 1. `MINIMAX_API_KEY` in `.env`-File konfigurieren und testen |
| 2. Browser-End-to-End-Test: Subject → Deadline → Steps → Complete/Skip |
| 3. Edge-Case fixen: vergangene Deadlines richtig behandeln |
| 4. Sprint 3: Panik-Modus visuell sichtbar machen (Banner, roten Rahmen) |
| 5. Fly.io Deployment vorbereiten |
|
|
