Metadata-Version: 2.4
Name: gemini-ai-terminal
Version: 1.0.0
Summary: A lightweight terminal AI chatbot connected to Gemini via Vercel serverless backend.
Author: Coding Council JMI
License-Expression: MIT
Keywords: gemini,ai,chatbot,terminal,cli,fastapi,vercel
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: python-dotenv>=1.0.0

# Gemini AI Chatbot Wrapper

A lightweight, secure, and production-ready AI chatbot system featuring a FastAPI backend deployable as a serverless function on [Vercel](https://vercel.com/) and an interactive Python terminal client.

```text
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

```text
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](https://aistudio.google.com/).
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:**
   ```bash
   cd gemini-chat-wrapper
   ```

2. **Create and activate a virtual environment (optional but recommended):**
   ```bash
   # 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:**
   ```bash
   pip install -r requirements.txt
   ```

4. **Create your `.env` file:**
   ```bash
   cp .env.example .env
   ```
   Edit `.env` to include your Gemini API key:
   ```env
   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:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   npm i -g vercel
   ```

2. **Deploy the project:**
   ```bash
   vercel
   ```
   Follow the interactive prompts (select default settings).

3. **Add your Environment Variables on Vercel:**
   ```bash
   vercel env add GEMINI_API_KEY
   ```
   * Enter your Gemini API key when prompted.
   * Select `Production`, `Preview`, and `Development`.

   *(Optional)* Configure the model name:
   ```bash
   vercel env add GEMINI_MODEL
   ```
   * Set value to `gemini-2.5-flash`.

4. **Deploy to Production:**
   ```bash
   vercel --prod
   ```

---

### Option B: Deploy via Vercel Dashboard (GitHub)

1. Push this repository to GitHub.
2. Go to [Vercel Dashboard](https://vercel.com/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:**
     ```env
     BACKEND_URL=https://your-project.vercel.app
     ```
   * **Or directly in your shell:**
     ```bash
     # 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:**
   ```bash
   python client/main.py
   ```

---

## 💬 Terminal Client Interface Example

```text
╔════════════════════════════╗
║      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
```json
{
  "message": "What is artificial intelligence?"
}
```

#### Success Response (`200 OK`)
```json
{
  "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`)
```json
{
  "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.
