🎓 Trifecta Agent

The Trifecta is an advanced educational AI assistant built using the Google Agents SDK. It designs personalized, multi-turn study pathways tailored to individual student needs by dynamically diagnosing knowledge gaps, checking inputs for security violations, retrieving reference material via an MCP retrieval-augmented generation (RAG) vector store, and yielding structured 7-day study plans. Incorporating two distinct Human-in-the-Loop (HITL) checkpoints—one for security moderation and another for parent/teacher study plan approval—the system ensures that educational material is safe, relevant, and fully aligned with pedagogical requirements.

🎥 Video Demonstration

🏗️ Architecture and Agent Hierarchy

The agent workflow is structured as a directed graph of nodes orchestrating different sub-agents and validation rules. Below is the ASCII architecture diagram showing the execution path:

               +----------------------------------------+
               |              Student Input             |
               +----------------------------------------+
                                    |
                                    v
                       +-------------------------+
                       |       parse_input       |
                       +-------------------------+
                                    |
                                    v
                       +-------------------------+
                       |   security_checkpoint   | <--- Presidio PII scrubbing
                       +-------------------------+
                         /                     \
                   [safe]                       [escalate]
                   /                               \
                  v                                 v
        +------------------+             +-----------------------+
        |    quiz_agent    | <---------> |  security_moderation  | (HITL Checkpoint 1)
        +------------------+   [safe]    +-----------------------+
                 |
                 v (grades quiz / subtopics)
        +------------------+
        | weakness_tracker |
        +------------------+
                 |
                 v (finds subtopic weaknesses)
        +----------------------+
        | study_plan_generator | <--- Grounded using indexed documents via FastMCP
        +----------------------+
                 |
                 v
        +-----------------------+
        |  study_plan_approval  | (HITL Checkpoint 2: Parent/Teacher review)
        +-----------------------+
          /         |         \
    [approved]   [revise]    [rejected]
       /            |            \
      v             |             v
+------------+      |      +------------+
|  deliver   |      |      |  rejected  |
+------------+      |      +------------+
                    v
          (with revision note)
                    |
                    +-----> loop back to study_plan_generator

---

📋 Prerequisites

Before setting up the project, ensure you have the following installed:

• Python 3.13+: The core execution runtime.
• Node.js 18+: Required to run the frontend SPA student interface.
• uv: Modern, high-performance Python package manager (highly recommended).
• Google Cloud SDK (gcloud): Required for Cloud services (if deploying to GCP).
• Groq API Key: A valid API Key from Groq Console.

---

🚀 Quick-Start

Follow these steps to clone, configure, and boot up the local playground and teacher dashboard:

1. Clone the Repository

git clone <repository_url> capstone-study-coach
cd capstone-study-coach/trifecta-agent

2. Install Dependencies

Set up the virtual environment and install both Python back-end packages and Node.js front-end packages:

# Install Python packages and CLI utilities
pip install -e ".[dev]"

# Download required fonts for PDF export generation
python scripts/download_fonts.py

# Install frontend UI dependencies
cd frontend && npm install
cd ..

3. Configure the Environment

Create a .env file in the trifecta-agent root folder based on the example:

copy .env.example .env

Open .env and configure your API key and port preferences:

GROQ_API_KEY=gsk_YourActualAPIKeyHere
ADK_BASE_URL=http://127.0.0.1:8001
ALLOW_ORIGINS=*

4. Launch the System

Run the predefined commands in separate terminals (or use the provided start.ps1 script on Windows):

• Backend Agent Server (ADK):

  # Launches the integrated ADK server & MCP endpoints at http://127.0.0.1:8001
  uvicorn trifecta_agent.fast_api_app:app --port 8001

• Teacher/Moderator Dashboard (FastAPI):

  # Launches Uvicorn API server & glassmorphic SPA at http://127.0.0.1:8080
  make dashboard

• Student UI (Vite + React):

  # Launches Vite development server at http://localhost:7860
  make student-ui

---

🤖 Sub-Agents & HITL Flows

The Personal Trifecta employs modular sub-agents to divide responsibilities, combined with interactive checkpoints for safety and quality control:

Sub-Agents

1. Security Checkpoint (PII Redaction & Injection Defense): Uses Microsoft Presidio Analyzer and Anonymizer engines to scrub names, phone numbers, SSNs, email addresses, and student IDs. It also inspects inputs for prompt injection attack patterns.
2. Interactive Quiz Agent: Triggers a turn-by-turn multiple-choice testing flow. It queries the document index via FastMCP to ground the generated questions and requests Groq (Llama 3) to construct exactly 5 questions based on the student's selected difficulty.
3. Weakness Tracker Agent: A deterministic, rule-based Python analyzer. It aggregates historical quiz responses, groups them by subtopic, flags any subtopic scoring below WEAKNESS_THRESHOLD (default: 60%), and assigns priority categories (high, medium, low).
4. Study Plan Generator Agent: Prompts the Groq (Llama 3) model to synthesize a structured 7-day schedule utilizing structured JSON formatting. It prioritizes identified high-priority weakness topics, integrates FastMCP study resources, and narrates a motivational introduction.

Human-in-the-Loop (HITL) Checkpoints

1. Security Escalation (Checkpoint 1): If security_checkpoint detects a potential prompt injection keyword, the workflow pauses, raising a security_escalation interrupt. A human moderator must audit the input on the Teacher Dashboard to mark it Safe (anonymizing and resuming the quiz) or Malicious (raising a value error and terminating the session).
2. Study Plan Approval (Checkpoint 2): Before a 7-day study plan is delivered to the student, the workflow pauses, creating a study_plan_approval interrupt. A teacher or parent reviews the plan on the dashboard and can choose to:
   • Approve: Delivers the study plan directly to the student UI.
   • Revise: Submits a revision note (e.g., "Add more algorithms practice") which routes execution back to the study_plan_generator to rebuild the plan.
   • Reject: Cancels the study plan and notifies the student.

---

📄 Ingesting Materials & Teacher Console Navigation

To ground the quiz questions and study plans, and manage the student experience, perform the following steps:

📊 Teacher Console Features

The Teacher Administration Console at http://127.0.0.1:8080 provides five major tabs:

1. Overview & Charts: Real-time KPI summaries (Active Sessions, Awaiting Reviews, Avg Accuracy, and Indexed Chunks) and Chart.js graphs mapping subtopic proficiency and timeline activity.
2. Student Sessions: Registry of active sessions. Teachers can click on any Session ID to inspect a deep-dive Student Profile, displaying PII audit logs, question-by-question quiz answers, and generated plan schedules.
3. Review Queue: Consolidated center to resolve HITL prompts, displaying a visual day-by-day preview grid for proposed study plans.
4. MCP Knowledge Base: Drag-and-drop document upload paired with an index browser to search and preview RAG chunks.
5. Agent Settings: Adjust thresholds (e.g. weakness threshold, quiz length, model) dynamically.

1. Ingest Study Materials

1. Open the Teacher Console at http://127.0.0.1:8080 and switch to the MCP Knowledge Base tab.
2. Drag & drop or browse to select a PDF, TXT, or Markdown document in the upload zone.
3. Click Upload to MCP Vector Store. The file is forwarded to the FastMCP server, split into overlapping chunks, and indexed into the local index.json vector file. You can search indexed chunks in the real-time inspector.

2. Play a Quiz Session

1. Open the Student UI at http://localhost:7860 (or run a CLI session in the playground).
2. Start a session by entering a topic and difficulty (e.g., "Python loops hard").
3. The quiz agent will search the MCP index for loops, build 5 questions, and present them one-by-one.
4. Answer each question. The agent provides immediate feedback.
5. After the final question, the Weakness Tracker prints a report, and the Study Plan Generator drafts a plan.
6. The UI will pause and display "Waiting for parent/teacher approval...".
7. Go to the dashboard, click Review, insert optional instructions, and click Approve Plan or Request Revision.
8. The student UI immediately updates with the approved plan.
9. Export: Students can click the Download PDF button to receive a beautifully branded, offline-ready ReportLab A4 PDF of their study schedule.

---

📊 Running Evaluations

The evaluation loop measures response quality and graph performance against custom datasets.

Configuration

Metrics are defined in tests/eval/eval_config.yaml. The suite utilizes a custom LLM-as-a-Judge metric (custom_response_quality) to score agent responses on a scale from 1 (poor) to 5 (excellent), along with a programmatic metric (agent_turn_count) to track conversation lengths.

Run Evaluations

Use the agents-cli executable to generate conversation traces and run evaluation metrics:

# Step 1: Synthesize testing datasets (optional)
agents-cli eval dataset synthesize --count 10

# Step 2: Generate traces using test inputs
agents-cli eval generate --dataset tests/eval/datasets/basic-dataset.json --output eval_traces/

# Step 3: Grade the traces using configured metrics
agents-cli eval grade --config tests/eval/eval_config.yaml --traces eval_traces/ --output grade_results.json

To run regression comparison or cluster failures:

# Compare candidate traces against baseline
agents-cli eval compare baseline_grades.json grade_results.json

# Cluster and analyze failure modes
agents-cli eval analyze grade_results.json

---

🏆 Kaggle Submission Notes: Agents for Good (Education Track)

When packaging this agent for submission to the Kaggle Agents for Good — Education Track, review the following structural configurations:

1. API Key Loading: The agent is designed to run self-contained. It reads GROQ_API_KEY from the environment. Ensure this key is injected during notebook execution or kaggle secret setup.
2. Offline Execution & Local Ingestion:
   • The MCP document vector store uses a lightweight, self-contained mathematical TF-IDF engine inside mcp_server/server.py.
   • It relies on a local JSON file (index.json) for persistence, eliminating external database dependencies.
   • If submitting to an offline environment, ensure index.json is packaged inside the zip bundle so pre-ingested syllabus materials are readable.
3. Container Constraints: The FastAPI server and MCP server run internally as stdio processes. For submission notebook execution:
   • Package the dependencies in a single requirements.txt or configure the notebook to run pip install -e . offline using wheelhouses.
   • Do not run uvicorn as a blocking process; execute the agent directly using the Runner script or the agents-cli harness.

---

📄 License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file or visit http://www.apache.org/licenses/LICENSE-2.0 for more details.

Copyright 2026 Google LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.