Gemini AI Chatbot Wrapper

A lightweight, secure, and production-ready AI chatbot system featuring a FastAPI backend deployable as a serverless function on Vercel and an interactive Python terminal client.

Terminal Client
      ↓ HTTPS
Vercel Backend API (FastAPI)
      ↓
Gemini API (Google AI)
      ↓
Vercel Backend API
      ↓
Terminal Client

---

🌟 Key Features

• Secure Backend Architecture: The Gemini API key remains safely stored in the backend environment variables and is never exposed to the client.
• Vercel Serverless Ready: Pre-configured with vercel.json for one-command deployment to Vercel.
• FastAPI Backend: Fast, robust, asynchronous request handling with strict Pydantic validation.
• Interactive Terminal Client: Clean CLI interface with session banners, continuous input, network error handling, and graceful exit (exit / quit).
• Free-Tier Compatible: Defaults to Google Gemini free-tier friendly models (e.g., gemini-2.5-flash or gemini-1.5-flash).

---

📁 Project Structure

gemini-chat-wrapper/
│
├── api/
│   └── chat.py          # FastAPI serverless backend endpoint
│
├── client/
│   └── main.py          # Interactive Python terminal client
│
├── requirements.txt     # Python package dependencies
├── vercel.json          # Vercel serverless deployment configuration
├── .env.example         # Example environment variables template
├── .gitignore           # Git ignore file (secures .env and artifacts)
└── README.md            # Complete documentation and setup guide

---

🚀 Quick Start Guide

Step 1: Get a Gemini API Key

1. Visit Google AI Studio.
2. Sign in with your Google account.
3. Click Get API Key and then Create API Key.
4. Copy the generated API key.

---

Step 2: Local Installation & Setup

1. Clone or navigate to the project directory:

   cd gemini-chat-wrapper
   

2. Create and activate a virtual environment (optional but recommended):

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

3. Install dependencies:

   pip install -r requirements.txt
   

4. Create your .env file:

   cp .env.example .env
   

   Edit .env to include your Gemini API key:

   GEMINI_API_KEY=your_actual_gemini_api_key_here
   GEMINI_MODEL=gemini-2.5-flash
   BACKEND_URL=http://127.0.0.1:8000
   

---

Step 3: Run and Test Locally

1. Start the local FastAPI backend server:

   uvicorn api.chat:app --reload --port 8000
   

   • The API health check will be live at: http://127.0.0.1:8000/api/chat
   • Interactive OpenAPI Docs at: http://127.0.0.1:8000/docs

2. In a new terminal window, start the terminal client:

   python client/main.py
   

---

☁️ Deploying to Vercel

You can deploy the backend to Vercel in two ways: via the Vercel CLI or through the Vercel Web Dashboard (GitHub).

Option A: Deploy via Vercel CLI (Fastest)

1. Install Vercel CLI:

   npm i -g vercel
   

2. Deploy the project:

   vercel
   

   Follow the interactive prompts (select default settings).

3. Add your Environment Variables on Vercel:

   vercel env add GEMINI_API_KEY
   

   • Enter your Gemini API key when prompted.
   • Select Production, Preview, and Development.

   (Optional) Configure the model name:

   vercel env add GEMINI_MODEL
   

   • Set value to gemini-2.5-flash.

4. Deploy to Production:

   vercel --prod
   

---

Option B: Deploy via Vercel Dashboard (GitHub)

1. Push this repository to GitHub.
2. Go to Vercel Dashboard and click Add New Project.
3. Import your GitHub repository.
4. Under Environment Variables, add:
   • GEMINI_API_KEY: Your Gemini API Key from Google AI Studio.
   • GEMINI_MODEL (Optional): gemini-2.5-flash (or gemini-1.5-flash).
5. Click Deploy.

---

🔗 Connecting the Terminal Client to Vercel

1. Copy your deployed Vercel URL: Once deployment completes, Vercel gives you a URL such as: https://your-project.vercel.app

2. Configure your Terminal Client: Set the BACKEND_URL environment variable:

   • Via .env file:

     BACKEND_URL=https://your-project.vercel.app
     

   • Or directly in your shell:

     # Linux / macOS
     export BACKEND_URL="https://your-project.vercel.app"
     
     # Windows (PowerShell)
     $env:BACKEND_URL="https://your-project.vercel.app"
     
     # Windows (CMD)
     set BACKEND_URL=https://your-project.vercel.app
     

3. Launch the interactive terminal client:

   python client/main.py
   

---

💬 Terminal Client Interface Example

╔════════════════════════════╗
║      GEMINI AI CLIENT      ║
╚════════════════════════════╝

Connected to AI Server: https://your-project.vercel.app
Type 'exit' or 'quit' to leave the chat.

You > Hello

AI > Hello! How can I help you today?

You > Explain recursion in simple terms.

AI > Recursion is a programming technique where a function solves a problem by calling a smaller instance of itself until it reaches a base condition.

You > exit

Goodbye!

---

📡 API Specification

POST /api/chat

Request Body

{
  "message": "What is artificial intelligence?"
}

Success Response (200 OK)

{
  "response": "Artificial intelligence (AI) refers to computer systems capable of performing tasks that typically require human intelligence..."
}

Error Response (400 Bad Request / 500 Internal Server Error / 502 Bad Gateway)

{
  "error": "Message cannot be empty."
}

---

🛡️ Security Best Practices

• Zero Client Secrets: The terminal client never touches or stores the Gemini API key.
• Environment Protection: Secrets are kept in .env locally (ignored in Git) and configured in Vercel's encrypted environment variable store.
• Error Sanitization: Backend error handlers redact sensitive API tokens from error outputs.

---

📄 License

MIT License. Open source and free to use.