# AI Project Feasibility & Solution Planner Agent

An MCP-based AI agent that evaluates an AI project idea using structured reasoning stages. The project focuses on reasoning quality, prompt engineering, structured outputs, and clean logs using the Gemini API (optimized for Free Tier).

## Screenshots

<!-- ![Terminal Output Screenshot](./assets/screenshot.png) -->
<img width="1258" height="798" alt="Screenshot 2026-08-05 002416" src="https://github.com/user-attachments/assets/a573e385-1c26-4af5-91b2-78c9df3aaa07" />
<img width="1267" height="911" alt="Screenshot 2026-08-05 002450" src="https://github.com/user-attachments/assets/13acb98a-5a74-4bf1-ba1d-3018f6dafcde" />
<img width="1247" height="906" alt="Screenshot 2026-08-05 002519" src="https://github.com/user-attachments/assets/eb70042b-abff-4e83-ac0d-07b3396a38c2" />
<img width="1253" height="900" alt="Screenshot 2026-08-05 002542" src="https://github.com/user-attachments/assets/97728874-2d10-4252-a6ac-90b4f30bf68a" />
<img width="1247" height="880" alt="Screenshot 2026-08-05 002607" src="https://github.com/user-attachments/assets/13ecc81b-9dc1-4aaf-80ef-befb8b253fea" />



## Architecture

The project consists of a FastMCP server and a client interacting with the Gemini 2.5 Flash model.
- **Client (`client.py`)**: Prompts the user for a project idea, communicates with the Gemini model, routes tool calls to the MCP server, and formats the output cleanly using the `Rich` library.
- **Server (`server.py`)**: A FastMCP server exposing a `research_topic` tool that uses DuckDuckGo Search to fetch up-to-date web information.
- **Models (`models/reasoning_models.py`)**: Pydantic models ensuring structured JSON outputs for all 7 reasoning stages.
- **Reasoning**: Evaluates the idea through 7 structured stages:
  1. Problem Understanding
  2. Requirement Analysis
  3. Complexity & Constraint Analysis
  4. Research Decision (Calls MCP tool only if needed)
  5. Technology Recommendation
  6. Risk & Roadmap
  7. Final Report

## Folder Structure

```text
s5 - AI Project Planner Agent/
│
├── server.py               # FastMCP server exposing the research_topic tool
├── client.py               # Main client application handling Gemini interactions
├── prompts/
│   └── system_prompt.md    # System prompt guiding the reasoning stages
├── tools/
│   └── research_tool.py    # Implementation of web search logic
├── models/
│   └── reasoning_models.py # Pydantic models for structured outputs
├── README.md               # Project documentation
└── pyproject.toml          # uv configuration
```

## Installation

This project uses `uv` for lightning-fast dependency management.

```bash
# Sync dependencies
uv sync
```

*(If initializing from scratch)*:
```bash
uv init
uv add google-genai mcp fastmcp pydantic rich duckduckgo-search python-dotenv
```

**Environment Variables**:
Create a `.env` file in the root directory and add your Gemini API key (ensure `.env` is listed in your `.gitignore`!):
```env
GEMINI_API_KEY="your_api_key_here"
```

## Usage

You do not need to run the server separately. The client automatically spawns the MCP server over `stdio` using `uv`.

### Running the Client

```bash
uv run client.py
```

### Example User Prompts

```text
I want to build an AI-powered crop disease detection system.
```
```text
I want to build an AI-powered exam proctoring system.
```

### Prompt Evaluation Workflow

The system prompt is isolated in `prompts/system_prompt.md`. You can freely evaluate and refine the instructions in this file without modifying any application logic. Ensure that changes in the prompt still instruct the model to produce the 7 required reasoning stages matching the Pydantic models. This project is verified against `prompt_checker.md` for explicit reasoning instructions, internal self-checks, and fallback plans.

## Example Logs

```text
Welcome to the AI Project Planner Agent
Enter your project idea: I want to build an AI-powered exam proctoring system.

Connecting to MCP Server...
Reasoning about your project...

Agent decided to research: research_topic(...)

==================================================

Stage – Problem Understanding

Goal
Understand the user's project

Analysis
AI-powered exam monitoring.

Reasoning Summary
Computer vision + authentication.

Reasoning Type
analytical

Self Check
Did I assume the user has access to a webcam? Yes, need to clarify.

Status
Completed

==================================================

... (Repeat for all 7 stages) ...

==================================================

MISSION COMPLETE
```