Garage On The Go Server

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:

   cd garage-on-the-go-agent
   

2. Create and activate a virtual environment:

   python -m venv venv
   # On Windows (PowerShell):
   .\venv\Scripts\Activate.ps1
   # On macOS/Linux:
   source venv/bin/activate
   

3. Install the dependencies:

   pip install -r requirements.txt
   

Configuration

1. (Optional) Create a .env file in the root directory and add your Google Gemini API key:

   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:

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:

python main.py

3. Run Automated Self-Tests

To run the programmatic validation suite verifying security guardrails, PII filters, and pipeline routing:

python main.py --test

4. Run the Google ADK Wrapper

To verify tool registration and inspect the Google Agent Development Kit setup:

python adk_agent/agent.py

5. Run the Real MCP Server

To execute the tool server via standard stdio transport:

python mcp_server/real_mcp_server.py

Or run the server in development mode using the FastMCP command-line tool:

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 [email protected] to confirm."

Expected Results:

• Security Guard: Redacts 98765-43210 to [PHONE REDACTED] and [email protected] 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.