Grounded Developer Assistant

Python 3.10+ Streamlit Gemini MCP

A premium, interactive Streamlit chat interface designed to act as a Google Developer Assistant. By leveraging the Model Context Protocol (MCP) and Google's Developer Knowledge API, the assistant provides real-time technical answers grounded strictly in official documentation for Google Cloud, Firebase, Android, and Google Maps.

---

📖 Table of Contents

1. Key Features
2. Architecture Overview
3. Grounding Modes
4. Prerequisites
5. Installation
6. Configuration & Usage
7. Testing and Helper Scripts
8. Project Tags & Metadata

---

✨ Key Features

• ⚡ Premium User Experience: Built with custom styled components, a vibrant header banner utilizing HSL/linear-gradients, custom interactive source cards, and dynamic element rendering.
• 📚 Fully Grounded AI Responses: Answers are strictly backed by Google's official documentation datasets, significantly reducing hallucinations.
• 🛠️ Flexible Grounding Engines: Supports both custom standard Retrieval-Augmented Generation (RAG) and Google's Managed Answer API.
• 🔐 Seamless Authentication: Features automatic OAuth2 access token detection using the local Google Cloud SDK (gcloud CLI) as well as manual credential entry.
• 💬 Streaming Conversations: Interactive chatbot with persistent session memory and real-time word-by-word streaming generation.
• 🌐 Clickable Sources & References: Shows expandable grounded sources containing text snippets and direct web links to official documentation.

---

🖥️ Architecture Overview

graph TD
    User([User Prompt]) --> Streamlit[Streamlit UI app.py]
    Streamlit --> Auth{OAuth2 Token & API Key}
    Auth -->|Valid| ModeSelect{Grounding Mode?}
    
    ModeSelect -->|Standard RAG| Search[MCP search_documents]
    Search -->|Retrieved Docs| Context[Construct Context]
    Context --> Gemini[Gemini Client / API]
    Gemini -->|Streamed Response| Output[UI Chat Window]
    
    ModeSelect -->|Managed Answer| AnswerAPI[MCP answer_query]
    AnswerAPI -->|JSON Response| Parser[Parse Answer & Refs]
    Parser -->|Format output| Output

---

🔍 Grounding Modes

The application supports two distinct grounding workflows configured in the sidebar settings:

1. Standard RAG (Search + Gemini)

1. Retrieve: Queries the Developer Knowledge MCP Server (search_documents tool) with the user prompt.
2. Ground: Formulates a strict system prompt containing the search results/snippets.
3. Synthesize: Calls Gemini API (using the new google-genai SDK) to draft a response based only on the retrieved context.

2. Managed Answer API (answer_query)

1. Direct Execution: Directly calls the Google Developer Knowledge MCP answer_query tool.
2. Parse & Render: The backend returns pre-compiled answers along with corresponding official document references, which are structured and styled as rich interactive cards.

---

📋 Prerequisites

Before running the application, make sure you have:

1. Python 3.10+ installed.
2. Google Cloud SDK (gcloud CLI) installed and authenticated:

   gcloud auth login
   gcloud auth application-default login
   

   Note: The app will run gcloud auth print-access-token in the background to automatically retrieve your OAuth2 credentials.
3. An active Google Cloud project with the Developer Knowledge API enabled.
4. A Gemini API Key from Google AI Studio.

---

🚀 Installation

1. Clone or copy this repository to your local workspace.
2. Install the required Python dependencies:

   pip install streamlit google-genai requests
   

---

⚙️ Configuration & Usage

1. Start the Streamlit application:

   streamlit run app.py
   

2. Open the browser window at http://localhost:8501.
3. In the sidebar settings:
   • Gemini API Key: Input your API key (defaults to your environment's GEMINI_API_KEY).
   • GCP Project ID: Input your target Google Cloud Project ID (e.g., geogreenai).
   • OAuth2 Token: Automatically detected if your gcloud CLI is logged in. Otherwise, paste a manual token.
   • Model Settings: Choose from gemini-2.5-flash, gemini-1.5-flash, or gemini-1.5-pro and adjust the creativity Temperature.
   • Grounding Mode: Choose between Standard RAG and Managed Answer API.
4. Start chatting with the grounded developer assistant!

---

🧪 Testing and Helper Scripts

The codebase comes equipped with several lightweight test scripts to verify API connections and test components in isolation:

• test_gemini.py: Verifies the google-genai SDK connectivity and simple text generation.
• test_mcp.py: Tests the connection to the Developer Knowledge MCP Endpoint and lists available tools.
• test_mcp_oauth.py: Tests searching documents via OAuth2 authorization.
• test_mcp_search.py: Verifies document searching functionality using raw API keys.
• test_mcp_answer.py: Verifies target answer generation using the managed answer_query tool.
• test_parser.py: A local unit test for regex/parsing rules on the raw protocol response blocks.

---

🏷️ Project Tags & Metadata

• Category: AI Assistant / RAG / Developer Tools
• Frameworks: Streamlit, Google GenAI SDK, Model Context Protocol (MCP)
• Target Audiences: Cloud Engineers, Firebase Developers, Android Engineers, Google Maps Developers
• Languages: Python
• Design Keywords: HSL Gradients, Dark Theme, Responsive UI, Streamlit custom CSS