🧠 Smart Hackathon Mentor Agent

An AI-powered mentor that guides hackathon teams from idea to demo using real-time reasoning, RAG, and agent orchestration.

📌 Project Overview

• Refine ideas and reduce scope
• Plan implementation effectively
• Design demo-ready architecture
• Prepare winning pitches

All in real time, adapting to team skills and constraints.

🎯 Problem Statement

Hackathon teams often struggle with:

• Overly ambitious or poorly scoped ideas
• Missing critical architecture components
• Limited mentor availability
• Poor planning, leading to incomplete demos

Currently, no system exists that can:

• Think and guide like a mentor
• Understand time, team size, and skill constraints
• Provide step-by-step actionable advice

💡 Solution

Our agent solves these problems by:

• Understanding team ideas and constraints
• Detecting risks in scope and feasibility
• Suggesting realistic MVPs and features
• Recommending simple, demo-focused architectures
• Creating step-by-step build plans and timelines
• Generating pitch and demo scripts

🚀 Key Features

• Idea Understanding & Context Analysis – Captures goals, users, tech stack, and constraints
• Interactive Question Loop – Asks clarifying questions until the idea is clear
• Scope & Feasibility Analysis – Evaluates ideas against time, team size, and complexity
• Automatic MVP Generation – Converts big ideas into achievable MVPs
• Skill-Aware Planning – Adapts advice based on team experience
• RAG-Based Guidance – Recommends strategies using real hackathon patterns
• Architecture Recommendation – Outputs clear, demo-ready designs
• Step-by-Step Build Plan – Time-boxed development roadmap
• Real-Time Mentorship Streaming – Shows agent reasoning live
• Failure Prediction – Warns about unrealistic goals or missing demos
• Pitch & Demo Scripts – Ready-to-use judge-friendly scripts
• Agent Reasoning Visualization – Visualizes decisions and reasoning paths

🧠 Technical Architecture

Frontend (React)
│
│ Server-Sent Events (Real-Time Updates)
▼
Backend (FastAPI)
│
├── Mentor Agent
│   ├── Idea Analyzer
│   ├── Clarification Node
│   ├── Feasibility Checker
│   ├── MVP Generator
│   ├── RAG Retriever
│   ├── Planner
│   └── Pitch & Demo Generator
│
└── Vector Database + LLM

📁 Folder Structure

SmartHackathonMentor/
├── frontend/      # React UI
├── backend/       # FastAPI & Agent Logic
├── .gitignore
└── README.md

⚡ Getting Started

Prerequisites

• Node.js (v18+) & npm
• Python 3.11+
• Vector Database or MongoDB

Installation

git clone <repo-url>
cd SmartHackathonMentor

Install frontend:

cd frontend
npm install

Install backend:

cd backend
pip install -r requirements.txt

Set environment variables:

cp .env.example .env
# Fill in the required values

Running

Frontend:

cd frontend
npm run dev

Backend:

cd backend
uvicorn main:app --reload

🎬 Demo & How It Works

1️⃣ Idea Intake

• Teams submit their hackathon idea
• The agent extracts goals, users, tech stack, and constraints
• Example visual: form or chat interface showing idea input

2️⃣ Clarification & Analysis

• The agent asks clarifying questions
• Feasibility and scope risks are analyzed instantly
• Example visual: question prompts appearing in the UI

3️⃣ MVP & Architecture Generation

• Large or complex ideas are converted into achievable MVPs
• The agent recommends a demo-focused architecture
• Example visual: diagram of simplified system architecture

4️⃣ Planning & Timelines

• Step-by-step build plans created based on team skills
• Time-boxed tasks ensure demo completion
• Example visual: timeline or Kanban board of tasks

5️⃣ Pitch & Demo Support

• Generates ready-to-use pitch and demo scripts
• Helps teams rehearse for judges
• Example visual: sample pitch screen or generated script

📝 Contributing

We follow Git Flow:

• main – production-ready
• develop – integration branch
• feature/* – new features
• bugfix/* – fixes
• hotfix/* – urgent fixes

Workflow:

1. Create a feature branch from develop
2. Implement changes & commit
3. Push branch and create PR to develop
4. Code review & merge
5. Release from develop → main

Commit Types: feat, fix, docs, refactor, test, chore