# Garage-on-the-Go AI Agent 🛠️

**Kaggle AI Agents Capstone Project: Intensive Vibe Coding**

---

## Project Scope

Garage-on-the-Go AI Agent is a Kaggle capstone prototype designed to demonstrate multi-agent vehicle diagnostics, service estimation, and mobile mechanic matching.

- **Capstone Prototype**: Built for Kaggle AI Agents Capstone evaluation and portfolio demonstration.
- **Simulated Operations**: Uses mock service catalog data and simulated mechanic profiles for Guwahati-style areas.
- **No Real Dispatching**: The generated booking receipt is a demo output and does not trigger real mechanic assignment, payment, or physical dispatch.

---

## 📌 Problem Statement
Stranded motorists facing sudden vehicle failures lack an immediate, reliable way to:
1. Safely diagnose whether their vehicle is safe to drive or requires immediate towing.
2. Estimate realistic, local maintenance costs without visiting physical workshops.
3. Quickly find and book available mock mechanics operating in their specific neighborhood.

## 💡 Solution
A localized, secure mobile mechanic coordinator driven by an ADK-inspired multi-agent orchestration sequential pipeline:
- **Triage Agent**: Conducts safety and urgency classification.
- **Estimate Agent**: Matches the query to a structured catalog, determining base service details and pricing ranges.
- **Booking Agent**: Assigns mock mechanic specialists located in Guwahati areas and compiles a finalized booking summary.

---

## 🛠️ Architecture & Multi-Agent Flow
The workflow is coordinated sequentially by a **Root Agent** orchestrator:

```
[User Input] 
    │
    ▼
[Security Shield] ──► 1. Input Guard (Rejects injections / size limits)
    │                 2. PII Redactor (Filters email/phone for privacy)
    ▼
[Root Agent (Orchestrator)]
    │
    ├─► [Triage Agent] ──► Diagnoses causes, Urgency levels, Safety directions
    │
    ├─► [Estimate Agent] ──► Queries Service Catalog Tool, determines Cost range
    │
    └─► [Booking Agent] ──► Invokes Mechanic Match Tool, compiles Receipt
        │
        ▼
   [Final Output] ──► Booking Confirmation Receipt JSON & Dashboard Cards
```

---

## 🎓 Kaggle Course Concepts Demonstrated

*   **Multi-agent orchestration**: Uses a sequential coordination pipeline (Triage -> Estimate -> Booking) directed by a central Root Orchestrator.
*   **Gemini API via google-genai with fallback mode**: Migrated to the modern `google-genai` SDK targeting the `gemini-2.5-flash` model. Includes a full deterministic rule-based fallback if the API key is not present or calls fail.
*   **Real ADK integration layer under adk_agent/**: Exposes the vehicle diagnostics agent tools using the official Google Agent Development Kit framework configuration.
*   **Real MCP server under mcp_server/real_mcp_server.py**: Exposes tools (`search_services`, `find_mechanic`, and `generate_booking`) to external clients using the official `FastMCP` framework on standard stdio transport.
*   **Security guardrails**: Includes prompt injection protection, input length restrictions, and regex-based redaction of phone/email PII before processing.
*   **Streamlit deployability**: Provides an interactive browser-based web demo interface ready for cloud environment testing. Features visual status chips, summary cards, confidence meters, and a structured Agent Execution Trace / Reasoning Flow panel.

---

## 🚀 Setup & Execution

### Prerequisites
- Python 3.8+ installed on your system.

### Installation
1. Clone or navigate to the project directory:
   ```bash
   cd garage-on-the-go-agent
   ```
2. Create and activate a virtual environment:
   ```bash
   python -m venv venv
   # On Windows (PowerShell):
   .\venv\Scripts\Activate.ps1
   # On macOS/Linux:
   source venv/bin/activate
   ```
3. Install the dependencies:
   ```bash
   pip install -r requirements.txt
   ```

### Configuration
1. (Optional) Create a `.env` file in the root directory and add your Google Gemini API key:
   ```env
   GEMINI_API_KEY=your_actual_api_key_here
   ```
   *Note: If no API key is specified, the application automatically runs in rule-based offline fallback mode using the Maruti/Pulsar heuristics.*
   
   ⚠️ **WARNING**: Never commit your `.env` file or expose raw API keys to GitHub.

---

## 🕹️ How to Run

### 1. Run the Streamlit Interface
To view the Streamlit web demo:
```bash
streamlit run app.py
```

#### Streamlit App Pages
The Streamlit dashboard has been upgraded with a sidebar navigation menu to showcase a complete portfolio-ready workflow. The app includes the following pages:
- **Dashboard**: Displays project overview, system statuses (Gemini API or fallback state), mock database summary counts, and system architecture.
- **Diagnose**: Runs the main diagnostic workflow with safety/PII pre-validation, triage diagnostics, catalog matching, dispatcher tool assignment, booking receipt compilation, and the visual step-by-step Agent reasoning trace.
- **Mechanics**: Displays simulated mock mechanic profiles (names, specialties, ratings, and operating neighborhoods) from local JSON data.
- **Bookings**: Shows the latest booking receipt compiled in the current Streamlit session (requires performing a diagnostic first).
- **History**: Shows diagnostic history compiled during the current active session only (uses temporary `st.session_state` with no persistent database storage).
- **Settings**: Summarizes project configuration status, local env setups, mock parameters, and safety shields.

### 2. Run the CLI Terminal Demo
To run the interactive command-line utility:
```bash
python main.py
```

### 3. Run Automated Self-Tests
To run the programmatic validation suite verifying security guardrails, PII filters, and pipeline routing:
```bash
python main.py --test
```

### 4. Run the Google ADK Wrapper
To verify tool registration and inspect the Google Agent Development Kit setup:
```bash
python adk_agent/agent.py
```

### 5. Run the Real MCP Server
To execute the tool server via standard stdio transport:
```bash
python mcp_server/real_mcp_server.py
```
Or run the server in development mode using the FastMCP command-line tool:
```bash
mcp dev mcp_server/real_mcp_server.py
```

---

## 🧪 Demo Scenario
Try entering the following description in the CLI or Streamlit text input:
> *"My car's engine is making a loud knocking sound, and the dashboard temperature gauge is in the red. I see some coolant leaking onto the driveway. Call me at 98765-43210 or email user@test.com to confirm."*

**Expected Results:**
- **Security Guard**: Redacts `98765-43210` to `[PHONE REDACTED]` and `user@test.com` to `[EMAIL REDACTED]`.
- **Triage**: Diagnoses a cooling system/radiator issue, marks urgency as **Critical**, and issues a safety recommendation to stop driving immediately.
- **Estimate**: Selects **Coolant Flush & Top Up** or **Engine Diagnostics** from the catalog, calculating a total pricing breakdown.
- **Booking**: Matches an available mechanic in your location area (e.g. *Rajen Kalita* for Beltola) and prints a receipt with booking ID.

---

## ⚠️ Limitations & Future Scope
- **Current Limitations**: This is a prototype system that operates entirely on mock data, with no real GPS positioning, no payment gateway integration, and no real-world mechanic booking or dispatching.
- **Future Scope**: Integration with real mechanic dashboards via Websockets, mapping visual routing APIs, and deploying native MCP server adapters to bind directly into developer IDE hosts.