learning-os

Planning package for the MVP of a course-aware learning OS.

The MVP goal is intentionally narrow:

Ingest course files, build source-grounded course graphs, capture notes, mature notes into grounded claims, quiz the learner, track mastery gaps, and choose the next useful study action.

The project should not start as an automatic contemporary science updater. The architecture keeps an evidence layer so that capability can be added later without mixing course content, learner beliefs, and current evidence into one untraceable index.

Documentation Map

• Project Brief
• Requirements
• Architecture And Mermaid Diagrams
• Kanban Board Static Snapshot
• Roadmap And Milestones Static Snapshot
• Decision Log
• Architecture Decision Records
• Risk Register
• Engineering Standards
• GitHub Bootstrap
• Lightweight Requirements Discovery
• Thesis Workspace
• GitHub Workflow
• Agent GitHub Operating Guide

Operational planning now lives in GitHub Project 5: https://github.com/users/kmosoti/projects/5

MVP Demo Target

Upload EMT pre-course materials, process them into source spans and graph nodes, help the learner answer assignment questions, ground class notes, generate retrieval-practice quizzes, update learner mastery, and recommend one next study action.

Tooling Baseline

• Python: 3.14.5
• Project manager: uv
• Lockfile: uv.lock
• Formatter/linter: Ruff
• Type checker: ty
• Backend: FastAPI
• Persistence: SQLite, SQLAlchemy 2.x, Alembic, FTS5
• Graph: NetworkX for MVP traversal
• UI: HTMX server-rendered frontend unless a later decision explicitly changes it

Verified on 2026-06-04:

• Python.org lists Python 3.14.5 as the latest Python 3 release on the source downloads page.
• uv supports Python version management and universal lockfiles.
• Ruff supports py314 as a target version.
• ty is Astral's Python type checker and language server.

Local Setup

uv python install 3.14.5
uv sync

If uv reports that no managed 3.14.5 download is available for your platform, update uv or install Python 3.14.5 separately, then rerun uv sync. Do not silently fall back to an earlier 3.14 patch version.

Quality Checks

uv run ruff check .
uv run ruff format --check .
uv run ty check
uv run pytest

Run The App

uv run uvicorn app.main:app --reload

For local-network testing:

uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

Each request includes an X-Request-ID response header and emits a structured request log.

First Implementation Slice

Build a local app that can:

1. Start with uv run.
2. Create one course.
3. Upload one PDF or text source.
4. Parse source spans.
5. Persist those spans.
6. Show the source and span count in a plain UI.

That creates the first observable thread through the architecture before adding LLM extraction or quiz behavior.