Code Spotter

Code Spotter is an agent service that monitors student activities in coding environments (currently supporting Jupyter Notebooks), detects "stuck" states, and provides timely, non-intrusive interventions.

Architecture

The project uses Docker Compose for local development orchestration, consisting of the following components:

• Probe: Lightweight collector running alongside user tools (Jupyter), listening to kernel events and sending standardized events.
• Backend: Centralized service that consumes events, maintains user state machines, and triggers interventions.
• Event Bus: Redis (Pub/Sub) as a decoupling layer between Probe and Backend.

Quick Start

Prerequisites

• Docker & Docker Compose
• Recommended hardware: 2vCPU / 8GB RAM (Minimum: 4GB RAM on native Linux)

Starting the Services

1. Start the service stack:

   TEST_MODE=true docker compose up --build

   TEST_MODE=true shortens detection timeouts for quick demonstrations.

2. Access the services:

   Service	URL	Description
   Demo Dashboard	http://localhost:8080/demo	Real-time event stream + intervention visualization
   Jupyter Lab	http://localhost:8888	Coding environment
   Intervention Page	http://localhost:8080	Intervention messages only

3. Verify monitoring: Check the agent-backend service logs. When executing code in Jupyter, you should see real-time events.

Demo

The project provides two demonstration methods to showcase the complete flow of "stuck" detection and intervention generation.

Method 1: Demo Dashboard Trigger Buttons (Recommended)

The fastest way to demonstrate, no Jupyter interaction required:

1. Open Demo Dashboard: http://localhost:8080/demo
2. Click any trigger button:
   • Consecutive Errors (x3) - Simulates 3 consecutive identical errors
   • Repeat Execution (x3) - Simulates executing the same code repeatedly
   • Error + Idle - Simulates stopping after an error
3. Observe the Event Stream on the left and Interventions on the right

Method 2: Jupyter Notebook Real Experience

Experience the real coding monitoring flow:

1. Refresh the Jupyter page: http://localhost:8888
2. Open work/demo.ipynb
3. Run any cell to start the kernel
4. Open Demo Dashboard: http://localhost:8080/demo
5. Select "Jupyter (default-session)" in the top-left dropdown
6. Return to Jupyter, run the TRIGGER: CONSECUTIVE_ERRORS cell 3 times
7. Observe real-time events and intervention messages in the Demo Dashboard

Detection Rules

Stuck Type	Trigger Condition	Intervention Level
CONSECUTIVE_ERRORS	Same error appears ≥3 times within 2 minutes	warning
NO_PROGRESS_EXECUTION	Same code executed ≥3 times without modification	info
ERROR_THEN_IDLE	No activity ≥5 minutes after error (TEST_MODE: 10s)	alert

Project Structure

• docs/: Architecture decision records and RFC documents.
• shared/: Shared Python libraries (event protocol definitions).
• probe/: Jupyter Probe service (custom Jupyter Docker image).
• backend/: Agent Core service.
• web/: Web UI service (intervention display + Demo Dashboard).
• tests/: MVP acceptance tests.
• logs/: Runtime logs directory (auto-created, gitignored).
• notebooks/: Runtime notebooks directory (auto-created by Docker, gitignored).
• docker-compose.yml: Local development orchestration configuration.

Documentation

• RFC-001: Learning Event Protocol