HackCrib-AI

<div align="center"> <h1>🏆 HackCrib AI</h1> <p><strong>An AI-powered multi-agent hackathon mentor built with Google Agent Development Kit (ADK)</strong></p> <p><em>From a blank idea to a complete, approved project plan — in under 2 minutes of conversation.</em></p> <br/> [](https://www.python.org/) [](https://adk.dev/) [](https://aistudio.google.com/) [](https://fastapi.tiangolo.com/) [](https://modelcontextprotocol.io/) [](https://a2a-protocol.org/) [](LICENSE) <br/> <p align="center"> <img src="https://github.com/user-attachments/assets/590e0b1b-6549-490a-bb5a-cd8d0035cc3e" alt="HackCrib AI Banner" width="100%"> </p> </div> --- ## 📖 Table of Contents - [Overview](#-overview) - [Features](#-features) - [Tech Stack](#-tech-stack) - [Architecture](#-architecture) - [Multi-Agent Workflow](#-multi-agent-workflow) - [Human Approval Flow](#-human-approval-flow) - [Quick Start](#-quick-start) - [Usage](#-usage) - [Project Structure](#-project-structure) - [API Reference](#-api-reference) - [Deployment](#-deployment) - [ADK Features Used](#-adk-features-used) - [Future Improvements](#-future-improvements) - [Hackathon](#-hackathon) - [Contributors](#-contributors) - [License](#-license) --- ## 🎯 Overview **HackCrib AI** is an intelligent hackathon planning system that acts as a personal AI mentor for students. Through a natural conversation, students describe their hackathon — the problem statement, team composition, time constraints, and technology preferences. A pipeline of six specialized AI agents then collaborates to produce a structured, actionable project plan. Before the plan is locked in, a **Human-in-the-Loop (HITL) approval step** gives the student full control: review the AI-generated draft, request targeted refinements, or approve it to generate the final deliverable. > **Built entirely on [Google Agent Development Kit (ADK) 2.x](https://adk.dev/)** — demonstrating 10 ADK primitives in a single production-grade application. --- ## ✨ Features | Feature | Description | |:---|:---| | 🤖 **6 Specialized AI Agents** | Hackathon intelligence, tech stack advisor, sprint planner, documentation generator, orchestrator, and student mentor | | 👤 **Human-in-the-Loop (HITL)** | Review and approve (or request refinements on) the draft plan before it is finalized | | 🔄 **Unlimited Refinement Loops** | Describe changes in plain English — the orchestrator re-plans until you are satisfied | | 🛡️ **Security by Default** | PII scrubbing (email, credentials) and prompt injection detection on every single input | | 🔧 **MCP Tool Integration** | Tech documentation search, API discovery, and dependency validation via a local MCP server | | 📊 **Structured Output** | Plans are validated against a `ProjectPlanOutput` Pydantic schema — no hallucinated fields | | 🔌 **A2A Protocol Support** | Full [Agent-to-Agent protocol](https://a2a-protocol.org/) for interoperability with other ADK agents | | ⚡ **Rate-Limiter Built-in** | Free-tier Gemini API safe by design — monkey-patched global rate limiter at 12s minimum interval | | 🐳 **Cloud-Ready** | Docker + Google Cloud Run + Agent Runtime deployment out of the box | | 💬 **Persistent Student Profile** | Learns and retains student skills, experience level, and preferences across conversation turns | --- ## 🛠️ Tech Stack | Layer | Technology | |:---|:---| | **AI Framework** | [Google Agent Development Kit (ADK) 2.x](https://adk.dev/) | | **LLM** | [Gemini 2.5 Flash / Flash Lite](https://aistudio.google.com/) via Google AI Studio | | **Web Server** | [FastAPI](https://fastapi.tiangolo.com/) + [Uvicorn](https://www.uvicorn.org/) | | **Agent Protocol** | [A2A Protocol](https://a2a-protocol.org/) (`a2a-sdk`) | | **Tool Protocol** | [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) (`mcp`) | | **Data Validation** | [Pydantic v2](https://docs.pydantic.dev/) | | **Package Manager** | [uv](https://docs.astral.sh/uv/) | | **Container** | [Docker](https://www.docker.com/) | | **Deployment** | [Google Cloud Run](https://cloud.google.com/run) / [Agent Runtime](https://cloud.google.com/agent-runtime) | | **Observability** | [OpenTelemetry](https://opentelemetry.io/) + [Google Cloud Logging](https://cloud.google.com/logging) | --- ## 🏗️ Architecture HackCrib AI is structured as a **two-layer system**: a conversational root agent that collects context, and a multi-agent workflow that executes the planning pipeline. <p align="center"> <img src="https://github.com/user-attachments/assets/d0d0d693-bec9-48b5-bac6-3811a54998e6" alt="HackCrib AI Architecture" width="95%"> </p> ``` ┌─────────────────────────────────────────────────────────────────────┐ │ User (ADK Playground / A2A Client / REST API) │ └──────────────────────────┬──────────────────────────────────────────┘ │ SSE / HTTP ┌──────────────────────────▼──────────────────────────────────────────┐ │ FastAPI Server (fast_api_app.py) │ │ ├── ADK web routes (/run_sse, /run, /apps/...) │ │ ├── A2A routes (/a2a/app/...) │ │ └── /feedback │ └──────────────────────────┬──────────────────────────────────────────┘ │ ┌──────────────────────────▼──────────────────────────────────────────┐ │ student_mentor_agent (LlmAgent, mode=chat) │ │ ├── before_model_callback → security_checkpoint (PII + injection) │ │ ├── after_model_callback → lightweight logging │ │ ├── state_schema: HackCribState │ │ └── tool: start_project_planning() │ └──────────────────────────┬──────────────────────────────────────────┘ │ ctx.run_node(hackcrib_workflow) ┌──────────────────────────▼──────────────────────────────────────────┐ │ hackcrib_workflow (ADK Workflow) │ │ ├── security_checkpoint ──unsafe──▶ security_error_node │ │ │ │ safe │ │ ├── orchestrator_agent (output_schema=ProjectPlanOutput) │ │ │ ├── hackathon_intelligence_agent (AgentTool) │ │ │ ├── tech_stack_advisor_agent (AgentTool + MCP) │ │ │ │ └── MCP: search_tech_docs, discover_apis │ │ │ ├── project_planning_agent (AgentTool + MCP) │ │ │ │ └── MCP: validate_dependencies │ │ │ └── documentation_agent (AgentTool) │ │ ├── human_approval_node (RequestInput → HITL pause) │ │ │ ├── "approve" ──▶ final_output │ │ │ └── <refinement> ──▶ orchestrator_agent │ │ └── final_output (yields rich Markdown Event) │ └─────────────────────────────────────────────────────────────────────┘ ``` 📐 Full architecture details: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) --- ## 🔀 Multi-Agent Workflow <p align="center"> <img src="https://github.com/user-attachments/assets/b3a1d416-0ca9-44d7-9271-96fe9131ba39" alt="HackCrib AI Workflow" width="95%"> </p> ```mermaid flowchart TD A([User Message]) --> B[student_mentor_agent\nLlmAgent · mode=chat] B -->|"Enough context collected"| C[start_project_planning\ntool call] C --> D[security_checkpoint\nPII scrub · injection detect] D -->|unsafe| E[security_error_node\nTerminate with alert] D -->|safe| F[orchestrator_agent\nProjectPlanOutput schema] F --> G[hackathon_intelligence_agent\nAnalyze criteria & scoring] F --> H[tech_stack_advisor_agent\nMCP: search_tech_docs\nMCP: discover_apis] F --> I[project_planning_agent\nMCP: validate_dependencies] F --> J[documentation_agent\nREADME outline · checklist] G & H & I & J --> K[human_approval_node\nRequestInput · HITL pause] K -->|"approve"| L[final_output\nFormatted Markdown plan] K -->|refinement text| F L --> M([✅ Approved Plan Delivered]) style A fill:#1a1a2e,color:#fff,stroke:#4285F4 style B fill:#4285F4,color:#fff,stroke:#4285F4 style C fill:#2d5a27,color:#fff,stroke:#34A853 style D fill:#7b2d00,color:#fff,stroke:#EA4335 style E fill:#3d0000,color:#ff6b6b,stroke:#EA4335 style F fill:#1a3a6b,color:#fff,stroke:#4285F4 style G fill:#0d3349,color:#fff,stroke:#00BCD4 style H fill:#0d3349,color:#fff,stroke:#00BCD4 style I fill:#0d3349,color:#fff,stroke:#00BCD4 style J fill:#0d3349,color:#fff,stroke:#00BCD4 style K fill:#4a2060,color:#fff,stroke:#9C27B0 style L fill:#1b4332,color:#fff,stroke:#34A853 style M fill:#34A853,color:#fff,stroke:#34A853 ``` --- ## ✅ Human Approval Flow ```mermaid sequenceDiagram actor Student participant Mentor as student_mentor_agent participant Workflow as hackcrib_workflow participant Approval as human_approval_node participant Final as final_output Student->>Mentor: Describe hackathon + team Mentor->>Mentor: Collect context (multi-turn) Mentor->>Workflow: start_project_planning() Workflow->>Workflow: security_checkpoint → orchestrator → 4 agents Workflow->>Approval: Draft ProjectPlanOutput ready Approval-->>Student: 📋 Draft plan + "approve or refine?" alt Student approves Student->>Approval: "approve" Approval->>Final: route = "approve" Final-->>Student: 🎉 Final Markdown Plan else Student requests refinement Student->>Approval: "Change the database to PostgreSQL" Approval->>Workflow: route = "refine" + feedback in state Workflow->>Workflow: orchestrator re-plans with feedback Workflow->>Approval: Revised draft Approval-->>Student: 📋 Updated plan + "approve or refine?" end ``` --- ## 🚀 Quick Start ### Prerequisites | Requirement | Version | Install | |:---|:---|:---| | Python | ≥ 3.11 | [python.org](https://www.python.org/downloads/) | | uv | Latest | `pip install uv` | | Google AI Studio API Key | Free | [aistudio.google.com/apikey](https://aistudio.google.com/apikey) | ### Installation ```bash # 1. Clone the repository git clone https://github.com/SeshankTangudu/HackCrib-AI cd HackCrib-AI # 2. Copy and configure environment cp .env.example .env # Open .env and set your GOOGLE_API_KEY # 3. Install all dependencies uv sync # 4. Launch the ADK Playground make playground ``` Open **[http://localhost:18081](http://localhost:18081)** → select the **`app`** agent → start chatting. > 💡 **Free-tier tip**: Use `GEMINI_MODEL=gemini-2.5-flash-lite` in your `.env` for higher free-tier rate limits. One full workflow run uses ~8–12 API calls. --- ## 💬 Usage ### Step 1 — Describe your hackathon ``` I want to participate in a 36-hour hackathon called "EduTech Innovation Challenge". The problem is: remote student teams struggle to collaborate on group projects. My team has 1 FastAPI developer and 2 React developers. We prefer WebSockets. ``` ### Step 2 — Trigger planning ``` Yes, everything is ready. Please generate a complete project plan now. ``` The system runs 6 agents in sequence (~60–90 seconds on free tier). You will see each agent's contribution stream into the Playground in real time. ### Step 3 — Review and approve The draft plan appears with project name, top ideas, selected architecture, tech stack, and sprint milestones. ``` approve ``` Or request a refinement: ``` Please replace Vue with React and add a WebRTC milestone in the final 6 hours. ``` ### Step 4 — Receive final plan ``` 🎉 Hackathon Project Plan Approved! 💡 Evaluated Ideas ⚙️ Selected Implementation Details 🛠️ Recommended Technology Stack 📅 Development Roadmap 🏆 Sprint Checkpoints 👥 Team Task Allocation ``` --- ## 📁 Project Structure ``` HackCrib-AI/ ├── app/ │ ├── agent.py # All agents, workflow, nodes, tools, callbacks, rate limiter │ ├── config.py # Model and environment configuration │ ├── mcp_server.py # Local MCP server (search_tech_docs, discover_apis, validate_dependencies) │ ├── fast_api_app.py # FastAPI server — ADK web routes + A2A protocol routes │ ├── __init__.py │ └── app_utils/ │ ├── a2a.py # A2A protocol adapter │ ├── services.py # Session and runner services │ ├── telemetry.py # OpenTelemetry integration │ ├── typing.py # Shared type definitions │ └── reasoning_engine_adapter.py ├── tests/ │ ├── unit/ │ │ └── test_dummy.py # Unit test placeholder │ ├── integration/ │ │ ├── test_agent.py │ │ ├── test_server_e2e.py │ │ └── test_e2e_workflow.py # Full end-to-end workflow test │ └── eval/ │ ├── eval_config.yaml │ └── datasets/ │ └── basic-dataset.json ├── docs/ │ ├── ARCHITECTURE.md # System design, component diagram, data flow │ ├── DEPLOYMENT.md # Local, Docker, Cloud Run, Agent Runtime │ ├── API.md # REST endpoints, SSE schema, A2A protocol │ ├── DEMO.md # Step-by-step demo script for judges │ ├── PRESENTATION.md # Pitch slide talking points │ └── SUBMISSION.md # Hackathon submission checklist ├── assets/ │ ├── thumbnail.md # Thumbnail image generation specification │ ├── architecture_flow.md # Architecture Mermaid source │ └── workflow_flow.md # Workflow Mermaid source ├── deployment/ │ └── terraform/ # Infrastructure-as-code (single-project) ├── .env.example # Environment variable template (copy → .env) ├── .gitignore # Excludes .env, .venv, logs, __pycache__ ├── Dockerfile # Container build for Cloud Run ├── Makefile # Developer convenience commands ├── pyproject.toml # Project metadata and dependencies ├── agents-cli-manifest.yaml # agents-cli deployment configuration └── GEMINI.md # AI coding agent guidance for this project ``` --- ## 📡 API Reference | Endpoint | Method | Description | |:---|:---:|:---| | `/run_sse` | POST | Run agent and stream events (Server-Sent Events) | | `/run` | POST | Run agent, return all events as JSON array | | `/apps/{app}/users/{uid}/sessions` | POST | Create a new session | | `/apps/{app}/users/{uid}/sessions` | GET | List sessions | | `/apps/{app}/users/{uid}/sessions/{sid}` | GET | Get session with full event history | | `/apps/{app}/users/{uid}/sessions/{sid}/feedback` | POST | Submit session feedback | | `/a2a/app/.well-known/agent-card.json` | GET | A2A agent card | | `/a2a/app` | POST | A2A task endpoint | Full API documentation with `curl` examples and SSE event schema: [`docs/API.md`](docs/API.md) --- ## 🚢 Deployment ### Local (development) ```bash make playground # ADK Playground on :18081 make run # Raw FastAPI server on :8000 ``` ### Docker ```bash docker build -t hackcrib-ai . docker run -p 8080:8080 \ -e GOOGLE_API_KEY=your-key \ -e GOOGLE_GENAI_USE_VERTEXAI=False \ -e GEMINI_MODEL=gemini-2.5-flash-lite \ hackcrib-ai ``` ### Google Cloud Run ```bash gcloud config set project YOUR_PROJECT_ID agents-cli deploy ``` Full deployment guide with Terraform, Cloud Run, and Agent Runtime instructions: [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) --- ## ⚙️ ADK Features Used This project exercises **10 Google ADK primitives** in a single application: | # | ADK Feature | Where Used | |:---:|:---|:---| | 1 | `LlmAgent` with `mode="chat"` | `student_mentor_agent` — multi-turn conversation | | 2 | `before_model_callback` | Security PII scrubbing + injection detection | | 3 | `after_model_callback` | Lightweight turn logging | | 4 | ADK `Workflow` with conditional routing | `hackcrib_workflow` — 4 workflow edges | | 5 | Custom sync/async workflow nodes | `security_checkpoint`, `human_approval_node`, `final_output` | | 6 | `RequestInput` — Human-in-the-Loop | `human_approval_node` — approve/refine pause | | 7 | `AgentTool` — agents calling agents | `orchestrator_agent` → 4 specialist agents | | 8 | `output_schema` — structured Pydantic output | `orchestrator_agent` → `ProjectPlanOutput` | | 9 | `McpToolset` — MCP tool integration | `tech_stack_advisor_agent`, `project_planning_agent` | | 10 | `ctx.run_node()` — nested workflow from tool | `start_project_planning()` invokes `hackcrib_workflow` | --- ## 🔮 Future Improvements - 🌐 **Multi-language support** — non-English hackathon descriptions and plans - 📊 **Historical analytics** — track patterns from past winning hackathon submissions - 🔗 **Direct integrations** — auto-create GitHub repo, Jira board, Figma template on approval - 🏫 **Mentor dashboard** — institution-level view for mentors to track multiple student teams - 🔊 **Voice input** — describe your hackathon via speech using the Gemini Live API - 🌍 **Remote MCP transport** — swap `StdioConnectionParams` for HTTP MCP for horizontal scaling - 💾 **Persistent sessions** — Cloud Firestore or Cloud SQL session service for stateful deployments - 📱 **Mobile companion** — lightweight app to access the mentor on the go during hackathon hours --- ## 🏆 Hackathon This project was built for the **Google ADK Hackathon 2026**. | Field | Details | |:---|:---| | **Hackathon** | Google Agent Development Kit (ADK) Hackathon 2026 | | **Category** | Developer Tools / Education / Multi-Agent AI | | **Framework** | Google Agent Development Kit (ADK) 2.x | | **Submission** | [`docs/SUBMISSION.md`](docs/SUBMISSION.md) | | **Demo Script** | [`docs/DEMO.md`](docs/DEMO.md) | | **Architecture** | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | | **Demo Video** | *(to be recorded and added before final submission)* | --- ## 👤 Contributors | Name | Role | |:---|:---| | **[Seshank Tangudu](https://github.com/SeshankTangudu)** | Project Lead · AI Workflow Design · Backend Development · Multi-Agent Architecture · Testing · Documentation · Deployment | --- ## 📄 License This project is licensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) file for details. ``` Copyright 2026 Seshank Tangudu Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. ``` --- <div align="center"> **Built with ❤️ using [Google ADK](https://adk.dev/) · [Gemini](https://aistudio.google.com/) · [FastAPI](https://fastapi.tiangolo.com/) · [MCP](https://modelcontextprotocol.io/)** ⭐ Star this repo if HackCrib AI helped your hackathon planning! [🐛 Report a Bug](https://github.com/SeshankTangudu/HackCrib-AI/issues) · [💡 Request a Feature](https://github.com/SeshankTangudu/HackCrib-AI/issues) · [📖 Read the Docs](docs/ARCHITECTURE.md) </div>