Skip to content

feat: add AI Hints for exercises and hands-on practicals - #14

Merged
jiaxinnns merged 8 commits into
mainfrom
feat/llm-integration
Sep 26, 2026
Merged

jiaxinnns merged 8 commits into
mainfrom
feat/llm-integration

Conversation

@jiaxinnns

@jiaxinnns jiaxinnns commented Aug 29, 2026 •

Copy link
Copy Markdown
Contributor

Overview

Students who get stuck can ask an AI tutor that sees the exercise instructions and their repo state, and gives hints without handing out answers.

Solution

  • An AI Hints button on every exercise and hands-on. It is only enabled once the exercise is downloaded and AI is set up, and main re-checks both on click.
  • A chat pane stacked above the terminal, with a draggable split. Chat history lives in memory, and Clear history resets both history and context.
  • Each message carries fresh context: the instructions, a names-only file tree and read-only git state. No file contents or terminal output are sent, git reads are checked to stay inside the exercise folder, and paths are relative so the username never leaves the machine.
  • The system prompt nudges one step at a time on graded exercises, can guide more directly on hands-on practicals, turns down off-topic questions, and tells the model it has no tools.
  • Provider registry: OpenRouter is the default, and OpenAI, Anthropic, Google or any OpenAI-compatible URL can be chosen instead. Keys are encrypted and checked on save. Each provider uses a fixed model; only Custom asks for one.
  • OpenRouter tries three named free models in order, then openrouter/free only as a last resort. On its own, the router can land on tiny or classifier models that reply with raw tool-call tokens or "User Safety: safe". The tradeoffs are recorded in the docs.
  • Design decisions are recorded in docs/architecture/ai-hints.md.

Test cases

  • Settings → AI hints: an invalid key is rejected, and a valid OpenRouter key saves. No Model field appears unless the provider is Custom.
  • AI Hints is disabled before Start Exercise, with a tooltip explaining why, and enabled after Start.
  • Opening hints stacks the pane above the terminal, the divider resizes both, and closing then reopening keeps the chat.
  • In under-control, the "AI can see" list reports that no repository exists yet.
  • Asking for the full solution to an exercise gets a hint, not the commands. Replies are plain prose, with no tool-call tokens.
  • An off-topic question is politely declined.
  • Clear history empties the chat. Switching exercises starts a fresh chat for the new exercise.

@jiaxinnns jiaxinnns changed the title docs: add llm integration options feat: add AI Hints for exercises and hands-on practicals Sep 26, 2026
jiaxin.loh and others added 3 commits September 26, 2026 15:03
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
@jiaxinnns
jiaxinnns merged commit 5818d8b into main Sep 26, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant