Personalized Learning Assistant

A local-first personalized learning assistant built around a 1:1 correction chat box.

The project is a small Python web app that stores learning plans, corrections, local memory, tasks, review items, and curated training examples on disk. It can run fully offline with deterministic fallback replies, or call an OpenAI-compatible endpoint from the server side when an API key is provided.

Why It Exists

Most personal assistant prototypes start as dashboards. This one starts from the interaction that produces the highest-quality personalization signal: the user correcting the assistant in a focused learning conversation.

The assistant treats those corrections as durable local evidence. Later replies can use local memory retrieval, tool receipts, task creation, end-of-day review, and ChatML export to support long-running tracks such as PTE Core preparation, PhD planning, career applications, and project work.

Core Features

• 1:1 correction chat interface for learning and planning.
• Local JSON state for conversations, captures, tasks, agenda items, imports, and review queue.
• Server-side optional OpenAI-compatible chat completions; keys never enter frontend code.
• Deterministic offline fallback when no key is configured.
• Tool receipt model for local actions such as memory search, capture write, task creation, and schedule intent.
• In-process BM25-style memory retrieval with IDF, document-length normalization, Chinese bigrams, tags, signals, and recency weighting.
• Historical chat import pipeline for Codex, Claude, and Cursor exports.
• Training sample scoring, persona distillation, and curated ChatML JSONL export.
• Product documentation with requirements IDs, priorities, acceptance criteria, and privacy constraints.

Repository Boundary

This public repository intentionally excludes all private runtime data:

• data/
• exports/
• .workbuddy/
• Python caches
• environment files and API keys

The excluded local data may contain private conversations, training samples, imported chats, and credentials accidentally present in historical messages. Only source code and sanitized documentation are published here.

Run Locally

Requirements:

• Python 3.10 or newer
• No external Python package is required for the core app

python3 server.py

Open:

http://127.0.0.1:8765

Use another port:

PORT=8877 python3 server.py

Optional AI Runtime

Without a key, the app still records local data, searches memory, creates tasks, and replies with deterministic fallback logic.

With a server-side key:

GOGOSLING_KEY=your_server_side_key python3 server.py

Optional:

AI_BASE=https://ai.gogosling.ca/v1
AI_MODEL=auto
MAX_AGENT_STEPS=6

The selected memory context may be sent to AI_BASE only when an online AI runtime is enabled. Keep real keys in local environment variables, never in committed files.

Validation

python3 -m py_compile server.py scripts/*.py
python3 scripts/validate_prompt_behavior.py

The validation script uses temporary state and checks that local tool behavior, memory retrieval, and learning-correction positioning still work without polluting real user data.

Key Files

server.py                         Local HTTP server, API routes, state, tool loop, fallback replies
index.html                        Single-page web UI
docs/product-requirements.md       Product requirements and acceptance criteria
docs/prompt_validation.md          Prompt and local-tool validation notes
docs/i18n-glossary.md              Chinese terminology consistency
scripts/import_chat_samples.py     Local Codex/Claude/Cursor import pipeline
scripts/score_training_samples.py  Training sample scoring
scripts/distill_persona.py         Persona profile distillation
scripts/validate_prompt_behavior.py Regression validation

Status

Portfolio/public showcase snapshot. The local private version continues to store personal state and training data outside this repository.