# Student Coding Assistant — README ## Project overview / Problem statement Students learning to code often run into errors and conceptual gaps (loops, conditions, control flow). They want: * **Very simple, bite-sized explanations** of programming concepts (e.g., “What is a loop?”). * **Clear diagnostics and step-by-step fixes** for code errors. * A **chat interface** that preserves conversation context so follow-up questions are natural and the assistant is context-aware. * The ability to **save / bookmark useful replies** with **predefined tags** (e.g., `Loops`, `Debugging`, `Python`) and search/filter them later. * Teachers want a chat-like dashboard to **review, reuse, and share** curated answers. This project builds a web app (Flask backend + JS frontend) integrating **LangChain** for LLM orchestration and **LangGraph** for structured conversation/workflow management. It supports two-tier memory: * **Short-term memory**: session-level context used for immediate conversation (e.g., last N messages, variables). * **Long-term memory**: persistent vector-store of embeddings for retrieval across sessions (saved answers, bookmarks, teacher notes). ## Goals & key features * Chat UI optimized for novices (simple language, examples, analogies). * Error-explanation pipeline that: 1. Accepts code snippet and environment/context, 2. Detects error, maps to root cause, 3. Returns minimal fix + explanation + example. * Bookmarking & tagging of assistant replies (predefined tags, tag editing). * Teacher dashboard for browsing/bookmark collections, tag-based search, and reusing replies. * Context-aware assistance using both short-term session context and long-term retrieval. * Pluggable LLM backend (OpenAI, Anthropic, local LLM) via LangChain adapters. * Orchestrated tools/workflows in LangGraph for tasks like: * `explain_error` * `explain_concept` * `generate_example` * `save_bookmark` --- ## High-level architecture (text diagram) ``` [Frontend Chat UI] <----HTTP / WebSocket----> [Flask Backend / API] | | | | +---- Websocket for live chat / streaming ----> + | [LangChain Agent + Tools] <-> [LangGraph Workflows] | +----------------------------+-----------------------+ | | [Short-term Memory: Redis / In-memory] [Long-term Memory: Vector DB (Milvus/Weaviate/PGVector)] | | Session state, last N messages Stored bookmarks, embeddings, teacher library ``` --- ## Tech stack (suggested) * Backend: **Flask** (API + WebSocket via Flask-SocketIO) * LLM Orchestration: **LangChain** * Workflow orchestration / agent graph: **LangGraph** * Short-term memory: **Redis** (or in-memory cache for small deployments) * Long-term memory / vector DB: **Postgres + pgvector** or **Weaviate** / **Milvus** * Embeddings: LangChain-compatible provider (OpenAI embeddings, or local model) * Frontend: React (recommended) or simple JS + HTML; chat UI component with message streaming * Database for metadata (bookmarks, users, tags): **Postgres** * Auth: JWT (Flask-JWT-Extended) or session cookies * Optional: Celery for background tasks (embedding generation, archiving) --- ## Data models (simplified) **User** * id (uuid), name, email, role (`student` | `teacher`), hashed_password, created_at **Message** * id, user_id, role (`student` | `assistant`), content, timestamp, session_id **Session** * id, user_id, started_at, last_active_at, metadata (language, course) **Bookmark** * id, user_id, message_id, title, note, created_at **Tag** * id, name (predefined list), description **BookmarkTag** (many-to-many) * bookmark_id, tag_id **LongTermEntry** (the vector DB metadata entry) * id, bookmark_id (nullable), content, embedding_id, created_at --- ## API endpoints (example) > Base: `POST /api/v1` 1. `POST /chat/start` Request: `{ "user_id": "...", "session_meta": {...} }` Response: `{ "session_id": "..." }` 2. `POST /chat/message` Request: `{ "session_id":"...", "user_id":"...", "message":"How do I fix IndexError?", "language":"python" }` Response: streaming assistant text (or `{ "assistant": "..." }`) 3. `GET /chat/session/{session_id}` Get messages or last N messages. 4. `POST /bookmark` Request: `{ "user_id":"...", "message_id":"...", "title":"Fix IndexError", "tags":["Errors","Python"] }` Response: bookmark metadata 5. `GET /bookmarks?user_id=&tag=Loops&query=` Searching & filtering bookmarks 6. `POST /embed` (internal) Request: `{ "content":"...", "source":"bookmark", ... }` Response: embedding id 7. `POST /teacher/library/share` For teachers to share replies + tags to a shared library 8. `POST /agent/explain_error` (LangGraph trigger) Request: `{ "code":"...", "error_output":"Traceback...", "language":"python", "session_id":"..." }` Response: structured result: ``` { "summary": "...", "root_cause": "...", "fix": "...", "example_patch": "...", "confidence": 0.87 } ``` --- ## How the LLM pipeline works (suggested flow) 1. **Preprocessing**: * Normalize code (strip long outputs), detect language (if not provided). * Extract last stack trace lines, relevant code region (use heuristics or tools). 2. **Short-term memory injection**: * Retrieve last N messages from session to maintain conversational context. * Provide these as `chat_history` to the agent. 3. **Long-term retrieval**: * Use a semantic retrieval (vector DB) to fetch up to K relevant bookmarks / teacher notes. * Append top retrieved items as `context` for the agent (if they match). 4. **LangGraph execution**: * Trigger `explain_error` workflow which: * Calls a classifier to categorize the error (SyntaxError, IndexError, TypeError, Logical). * If syntax or runtime error, create targeted prompt templates for LangChain to return short explanation + fix steps. * Optionally run a sandboxed static analyzer or linter to provide suggestions (e.g., flake8, pylint). 5. **Response generation**: * LangChain returns assistant message with sections: * One-line summary (simple language). * Root cause (one-sentence). * Minimal fix (code diff or patch). * Example explanation (analogy if helpful). * Suggested exercises (small practice). * If the user asks to save, persist the assistant message to bookmarks + create embedding. --- ## Prompting & templates (guidelines) * Always ask the LLM to **use simple language**, short sentences, and examples. * Template example for concept explanation: ``` You are an assistant for beginner programmers. Reply in simple English, using short sentences and an analogy. Task: Explain the programming concept: {concept} Provide: 1) A one-line plain-language definition. 2) A short example in {language}. 3) A one-sentence analogy. 4) One quick exercise for the student to try. ``` * Template example for error explanation: ``` You are a debugging assistant. Given the code and error trace below: - Provide a one-sentence summary of the problem. - Identify the root cause in one sentence. - Show the minimal code patch to fix the bug (3-10 lines max). - Explain why the patch works in 2-3 sentences with a simple example. - If uncertain, indicate other things to check (env, versions). ``` --- ## Memory strategy: short-term vs long-term **Short-term (session)**: * Store last N messages (e.g., N=8-10) in Redis or session cache. * Purpose: maintain conversational state, follow-ups, variable names, incremental debugging steps. **Long-term (persistent)**: * Vector store of: * Saved bookmarks (assistant reply content). * Teacher-curated notes. * Frequently asked Q&A. * Use pgvector / Weaviate / Milvus for semantic search. * On message arrival: compute embedding (async or sync) and use retrieval for context augmentation. **Retention & privacy**: * Let users opt-in to long-term memory for their chat (default: on for study). * Provide a UI to view and delete stored memories. * Teachers can access shared library only by permission. --- ## Bookmarking & tagging UX * Predefined tags (configurable): `Basics`, `Loops`, `Conditions`, `Debugging`, `APIs`, `Python`, `JavaScript`, `Advanced` * When assistant produces an answer, show: * `Save` (bookmark) button * Tag selection UI (multi-select from predefined list + teacher-only custom tags) * Optional short note title & explanation * Saved bookmarks are added to: * User personal library * Optionally the shared teacher library (requires teacher approval) * Provide fast search: tag filter + free-text query + semantic similarity (vector search) across bookmark contents. --- ## Teacher features * Dashboard to view shared bookmarks with filters: tag, subject, difficulty. * Create/edit curated Q&A and push to student groups. * Export a set of bookmarks as a lesson pack (JSON / CSV). * Review anonymized student conversations for improvements / interventions. --- ## Example minimal Flask app structure ``` /app /api chat.py # chat endpoints bookmarks.py # bookmark endpoints teacher.py # teacher endpoints /agents langchain_agent.py langgraph_workflows.py /memory short_term.py # Redis session memory long_term.py # wrapper for vector DB /models user.py bookmark.py /utils embeddings.py prompts.py /static /templates app.py requirements.txt README.md ``` --- ## Minimal run / dev steps 1. Create virtual env and install dependencies: ```bash python -m venv venv source venv/bin/activate pip install -r requirements.txt ``` `requirements.txt` should include: `flask`, `flask-socketio`, `langchain`, `langgraph`, `psycopg2-binary`, `pgvector` (adapter), `redis`, `weaviate-client` (or chosen vector db client), `python-dotenv`, `requests`. 2. Setup environment (example `.env`): ``` FLASK_APP=app.py FLASK_ENV=development DATABASE_URL=postgresql://user:pass@localhost:5432/assistantdb VECTOR_DB=pgvector REDIS_URL=redis://localhost:6379/0 OPENAI_API_KEY=sk-... ``` 3. Run DB migrations (Alembic or simple SQL scripts) to create tables. 4. Start backend: ```bash flask run # or for socket support gunicorn -k geventwebsocket.gunicorn.workers.GeventWebSocketWorker app:app ``` 5. Start frontend (if React): ```bash cd frontend npm install npm run dev ``` --- ## Example: explain_error workflow (LangGraph sketch) * Nodes: * `receive_input` → accepts code, error. * `detect_lang` → autodetect language. * `classify_error` → classify error type. * `fetch_context` → short-term + long-term retrieval. * `call_llm_explain` → LangChain LLM call with appropriate prompt template. * `format_output` → produce structured JSON. * `optionally_save` → if user requests, persist to bookmarks + embed. * Each node should be small, testable, and idempotent. --- ## Security & privacy considerations * Sanitize code before any execution — never run untrusted code in production. * Never include secrets or personal data in LLM prompts. * Provide data deletion endpoints (GDPR-style rights). * Rate limit user requests and LLM calls to control costs. * Ensure vector DB access is authenticated and network-restricted. --- ## Testing & evaluation * Unit tests for: * Prompt templates (deterministic outputs for sample inputs). * Bookmark CRUD operations. * Embedding generation & retrieval. * Integration tests: * Simulated user session: chat → explain_error → save bookmark → retrieve bookmark * UAT with students: measure comprehension via quick quizzes after explanation (A/B test simple vs. advanced explanations). --- ## Deployment considerations * Use managed vector DB if possible for reliability (Weaviate cloud, Milvus cloud, or Postgres + pgvector). * Use a managed Redis instance. * Containerize with Docker; use Kubernetes or a simple Docker Compose setup for small deployments. * Monitor LLM usage and costs; consider caching assistant replies for identical queries. --- ## Roadmap / enhancements * Add code-execution sandbox for runnable examples (strict sandboxing). * Support multi-language explanations (toggle English/simple English). * Add offline/local LLM support for on-prem use. * Add teacher analytics (common student errors, trending tags). * Gamify: badges for students who save & revisit bookmarks. --- ## Appendix: sample prompt examples **Concept: Loop** ``` SYSTEM: You are an assistant for beginner programmers. Use simple language (max 3 sentences per point). Provide a small code example. USER: Explain "loop" with a short example in python. ASSISTANT: ... ``` **Error: IndexError** ``` SYSTEM: You are a debugging assistant. Provide: (1) one-line summary, (2) root cause, (3) minimal fix, (4) why it fixes, (5) one follow-up check. USER: Code: ... Traceback: IndexError: list index out of range ``` --- ## Final notes * Prioritize **clarity** and **brevity** in assistant replies for learners. * Keep the **memory and bookmark UX** simple: easy save, obvious tags, quick retrieval. * Start small: implement a robust `explain_error` + bookmarking pipeline first; expand with LangGraph workflows and teacher tooling iteratively. --- If you'd like, I can: * Generate a **starter Flask repo skeleton** (files + minimal implementations). * Draft the **LangGraph workflow YAML / JSON** for `explain_error`. * Provide **sample prompt templates** and unit tests. Which of those should I produce next?