Agents-architecture

The marathon agents form the core intelligence layer of LearnPanta, designed as a real-time, non-intrusive monitoring and analysis engine for high-stakes exam simulations.

Current Debrief UI: The Review/Explore tabs use the TLDraw scaffold agent on the frontend. The backend “Unified Reviewer” pipeline remains available but is not the default UI path.

Core Design Principles

• Silent Background Mode: Continuous 2–6+ hour operation without user interruption
• Passive Collection: Real-time tracking of answer timing, hesitations, changes, and optional biometrics
• Incremental Analysis: Background processing culminating in immediate feedback
• Long-Running Durability: State persisting across server restarts via Temporal workflows

1. Agent Components

MarathonSessionWorkflow (Orchestrator)

Role: The "conductor". Initializes exam session, persists state, coordinates agents.

Technology: Temporal.io workflow with durable state

State Management:

• Stores all telemetry metrics in workflow state
• Handles signals for real-time metric ingestion
• Coordinates agent activities on exam completion

File: backend/app/agent/workflows.py

@workflow.defn
class MarathonSessionWorkflow:
    def __init__(self):
        self._state = {
            "metrics": [],
            "answer_changes": [],
            "question_times": {},
            "tab_blur_count": 0,
            # ... comprehensive behavioral state
        }

Agent Activities

A. Telemetry Ingestion (WebSocket)

Role: Receives real-time metrics from browser

Input: WebSocket connection from frontend (native WebSocket, not Socket.io)

Tracks:

• Time per question
• Answer selection and changes
• Tab focus/blur events
• Tool usage (calculator, notepad, scanner)
• Flag usage
• Optional: Face detection and gaze metrics (MediaPipe)

File: backend/app/agent/ingestion.py

B. Telemetry Analyzer

Role: Processes collected metrics into actionable insights

Model: Gemini Flash (fast pattern detection)

Output: Focus score, fatigue indicators, anomalies

File: backend/app/services/llm.py → analyze_telemetry()

C. Holistic Feedback Provider

Role: Synthesizes all data into comprehensive feedback

Model: Gemini Pro (deep reasoning)

Input:

• Exam score and per-question results
• Behavioral metrics summary
• Scratchpad images (if captured)
• Answer change history

Output: Structured feedback with strengths, improvement areas, and study priorities

File: backend/app/agent/activities.py → feedback_synthesis_agent()

D. Debrief Orchestrator

Role: Generates guided review scripts (beat-synced)

Model: Gemini Flash

Output: Structured JSON with beats for speech, cursor actions, and optional canvas instructions

File: backend/app/routers/debrief.py

E. Interviewer Agent

Role: Conducts voice-based oral debrief

Model: Gemini Pro (conversational)

Input: Exam context + user's spoken responses (transcribed)

Output: Probing questions and feedback via TTS

File: backend/app/services/llm.py → conduct_interview_turn()

Content Curator

Role: Generates exam questions from official syllabi

Model: Gemini Pro with Google Search grounding

Process:

1. Search for official exam syllabus
2. Extract topics and weightings
3. Generate balanced MCQs per topic

File: backend/app/agent/curator.py

2. Data Flow

3. Technology Stack

4. Metrics Collected

Tier 1: Behavioral (Always On)

Tier 2: Biometric (Optional Camera)

5. Roadmap & Status

Current: TimescaleDB for Historical Metrics

Metrics are persisted to TimescaleDB for analytics, while Temporal workflow state still holds per-session telemetry.

Current (Optional): Pinecone for Semantic Search

Semantic search is available when Pinecone is configured (PINECONE_API_KEY).

Next Steps

• Agents - Agent handbook
• Architecture - System overview
• Deployment - Deploy to GCP