Socratic Hints & Tutoring
Relevant source files
The following files were used as context for generating this wiki page:
Socratic Hints & Tutoring is the core pedagogical engine of Nudge, designed to assist students in their learning process without providing direct answers. The system functions as a warm, patient live tutor that observes a student's screen in real-time, identifies moments of struggle, and intervenes with well-timed, minimal prompts.
The philosophy behind this feature is "restraint": the assistant acknowledges struggle, responds with precision, and ensures the student maintains ownership of the work. By utilizing Socratic questions and small hints, Nudge helps students move past bottlenecks while preserving their confidence and flow.
Sources: website/src/renderer.js:15-18, services/agent/src/prompt.ts:5-13
Core Tutoring Philosophy
The tutoring system operates under specific persona rules to ensure a supportive rather than corrective experience. Key principles include:
- Socratic Interventions: Preferring questions and short hints over dumping full solutions.
- Ownership Preservation: Never spoiling the complete answer unless explicitly requested or after significant struggle.
- Context Awareness: Adapting to exactly what is on the student's screen, such as worksheets, notes, or code.
- Spoken Conciseness: Keeping turns short (one or two sentences) to avoid overwhelming the learner during high-friction moments.
Sources: services/agent/src/prompt.ts:5-15, website/src/renderer.js:52-60
Architecture and Data Flow
The tutoring logic is split between a vision layer ("Eyes") that identifies struggle and a talk layer ("Talk") that generates the spoken intervention.
The diagram shows how screen data and user speech are processed by the Agent service to decide whether to intervene or remain silent.
Sources: services/agent/src/live/turn-runner.ts:161-200, apps/web/src/lib/live/useLiveSession.ts:133-150
Observe Loop and Intervention Logic
The system maintains a proactive "Observe Loop" that periodically captures screen frames to evaluate student progress. It identifies productive struggle versus dead-end confusion.
| Component | Description | Logic / Threshold |
|---|---|---|
| Signal Layer | Detects friction points | Pauses, repeated errors, or drop in momentum. |
| Policy Layer | Chooses intervention type | Based on interruptLevel (Quiet, Balanced, Active). |
| Interrupt: QUIET | Rare intervention | Default to SILENCE unless seriously stuck. |
| Interrupt: ACTIVE | Frequent check-ins | Hints or questions when progress stalls. |
Sources: website/src/renderer.js:98-112, services/agent/src/prompt.ts:47-55, apps/web/src/lib/live/useLiveSession.ts:133-150
Implementation Details
The Tutoring Prompt
The tutoring behavior is governed by the STUDY_TUTOR_PERSONA and STUDY_TUTOR_RULES. These system prompts define how the model should interpret screen "ground truth" and when it is appropriate to speak.
// services/agent/src/prompt.ts:5-13
export const STUDY_TUTOR_PERSONA = `You are Nudge — a warm, patient live tutor watching the student work on their screen. Your job is to help them learn, not to finish their homework for them.
HOW YOU TEACH
- Prefer Socratic questions and short hints over dumping full answers.
- Never spoil the complete solution unless they explicitly ask for the answer...
- Celebrate progress briefly; correct misconceptions gently and specifically.`;
Sources: services/agent/src/prompt.ts:5-13
Handling Proactive Observe Turns
In proactive observe turns, the tutor peeks at the screen without the student speaking. The system follows a strict decision tree:
- SILENCE: If the student is reading, writing, or making steady progress.
- Soft Nudge: A single short sentence if the student is idle too long or repeating a clear mistake.
- Socratic Question: Preferred over explanations to unlock insights.
Sources: services/agent/src/prompt.ts:31-43
Technical Data Structures
The ObserveVisionResult structure is used to parse the output of the vision model to determine the next action.
| Field | Type | Description |
|---|---|---|
summary | string | A dense factual line describing problem type and key on-screen text. |
speak | string | The hint or question to be spoken to the student. |
silent | boolean | If true, no audio intervention is generated. |
Sources: services/agent/src/live/turn-runner.ts:121-137, services/agent/src/live/turn-runner.ts:153-157
Interaction Layer
Interactions are designed to feel like a "calm guide sitting beside the student." The UI/UX provides tools for students to manage their study session.
- Study Goal: Students can set a specific goal (e.g., "AP Chem chapter 4") which is injected into the tutor's context.
- Floating Sphere: The interface collapses into a ~64px orb to stay out of the way during active study.
- Focus Check-In: A dwell clock triggers a proactive "Focus Prompt" if the student remains idle for a duration defined by the
interruptLevel.
Sources: apps/web/src/components/live/LiveStage.tsx:88-95, apps/web/src/lib/live/useLiveSession.ts:80-97, website/src/renderer.js:41-50
Summary
Socratic Hints & Tutoring transforms the AI from a simple answer-engine into a pedagogical assistant. By combining real-time computer vision (Eyes) with a restrained conversational model (Talk), the system provides well-timed guidance that encourages student independence and maintains the flow of learning.
Sources: website/src/renderer.js:190-195, services/agent/src/prompt.ts:5-15