SunnyBoy-y/LearnGraph

LearnGraph – AI‑augmented, self‑hosted learning workspace

What it is

• A self‑hosted web + Android application that helps a user set a concrete learning goal, builds a knowledge graph for that goal, and lets an AI agent guide the user through study, practice, and assessment.
• The system continuously updates the graph and a memory of evidence (what the user read, answered, or coded) so the agent can recommend the next step.

Key capabilities

Feature	What you get
Growing knowledge graph	From a natural‑language goal the backend generates a versioned, editable graph of topics and prerequisite relationships. Users audit and revise it.
Agent‑native learning	An AI agent plans actions – fetches sources, explains concepts, creates exercises, runs code in a Docker sandbox, and records outcomes.
Full‑duplex voice tutor	Speech‑to‑text and text‑to‑speech (DashScope ASR + Volcano TTS) are integrated; you can speak and listen simultaneously, with live subtitles that highlight spoken sentences.
Docker‑isolated sandbox	Agent‑executed code runs in a Docker container that is offline by default; outbound network requires explicit approval, providing a strong security boundary.
Android client	Native Kotlin/Jetpack‑Compose app (GeckoView) mirrors the web UI and adds camera, file sharing, QR‑scan, biometric login, TTS, and push notifications.
Event‑sourced long‑term memory	Every interaction is stored as an immutable event. A projection layer builds searchable context on‑demand, enabling replay, audit, and protection against prompt injection.
Interactive learning pages	Each graph node can spawn a full learning page with material, interactive experiments, mini‑games, and graded quizzes. Progress is persisted and can be resumed.
“Magic Card” components	AI‑generated UI widgets (multiple‑choice, fill‑in‑the‑blank, charts, etc.) that carry state and can be reused across learning pages.
Multi‑model provider support	Plug‑in architecture for OpenAI, Anthropic, Qwen, DeepSeek, Ollama, Copilot and others, with unified credential handling.

Architecture at a glance

• Frontend: React 19 + TypeScript (Vite) for the web UI; Kotlin/Jetpack‑Compose for Android. Uses TanStack Query, React Flow, and a custom trusted‑renderer for safe HTML generated by the AI.
• Backend: FastAPI (Python 3.11+) exposing HTTP + SSE endpoints. Core services implement the G‑R‑E‑M‑A learning loop (Goal → Representation → Evidence → Mastery → Action).
• Memory: Event store in SQLite (WAL) with layered projections for hybrid vector + keyword retrieval.
• Sandbox: sandboxd daemon controls Docker containers that execute agent tools; an egress‑proxy enforces “offline‑by‑default, approve‑to‑go‑online” policy.
• Data persistence: All user data, graph versions, evidence, and encrypted provider secrets live in a Docker volume (or bind‑mounted directory) and survive container upgrades.

How to try it

1. Docker compose (recommended)

   git clone https://github.com/SunnyBoy-y/LearnGraph.git
   cd LearnGraph
   docker compose up -d --build   # builds web+API image and sandbox services
   

   • Open http://127.0.0.1:18000 in a browser.
   • Log in with the temporary admin password printed in the container logs, then change the password.
2. Development mode (if you want to contribute)

   npm run dev:install   # installs Node & Python deps, creates .env files
   npm run dev           # starts Vite frontend and FastAPI backend
   

   • Frontend: http://127.0.0.1:5173
   • API: http://127.0.0.1:8000
3. Android client
   • Build the Kotlin app in mobile/native or install a pre‑built APK.
   • Point it at the host address (e.g., http://192.168.1.5:18000).

Typical workflow

1. State a learning goal – “Learn basic Python for data analysis in 2 weeks.”
2. Review the generated graph – approve nodes like variables, pandas, visualisation.
3. Chat with the agent – ask for explanations, request code examples, or ask the agent to create a practice exercise.
4. Do the exercise – the UI presents an interactive page; results are stored as evidence.
5. Get the next recommendation – the system updates your mastery state and suggests the next highest‑impact node.

Who might use it

• Individual learners who want a structured, AI‑guided path into a new domain.
• Researchers experimenting with agent‑driven tutoring, memory‑audit, or sandboxed tool execution.
• Small teams building internal knowledge‑on‑boarding pipelines (self‑hosted keeps data private).

Current limitations

• Still early‑development; not recommended for production workloads.
• Voice capabilities rely on cloud providers (DashScope, Volcano); they send audio to those services.
• The sandbox only supports Docker; environments without Docker cannot run code‑execution features.
• Multi‑user collaboration is limited to basic RBAC; real‑time co‑learning is not yet implemented.

Where to learn more

• Developer guide & docs: https://sunnyboy-y.github.io/LearnGraph/
• Source code: https://github.com/SunnyBoy-y/LearnGraph
• License: MIT (feel free to fork and extend).

---

LearnGraph is a genuine open‑source AI‑agent learning platform that combines knowledge‑graph planning, an autonomous tutoring agent, voice interaction, and a Docker‑isolated execution sandbox.