Trifecta

# 🎓 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 [](https://youtu.be/YrWtIcUnS5M) ## 🏗️ 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 ```bash 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: ```bash # 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: ```bash copy .env.example .env ``` Open `.env` and configure your API key and port preferences: ```env 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)**: ```bash # 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)**: ```bash # Launches Uvicorn API server & glassmorphic SPA at http://127.0.0.1:8080 make dashboard ``` * **Student UI (Vite + React)**: ```bash # 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: ```bash # 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: ```bash # 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](LICENSE) file or visit [http://www.apache.org/licenses/LICENSE-2.0](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. ```