Tag v0.0.5

Add a model field to the gemini request mapping and implement a new
root endpoint that returns a plain text status message.

.dockerignore

@@ -0,0 +1,31 @@
+# Dependencies
+node_modules/
+npm-debug.log
+yarn-debug.log*
+yarn-error.log*
+
+# Environment variables
+.env
+.env.example
+
+# Build output
+dist/
+build/
+coverage/
+
+# Development
+profile/
+*.test.ts
+*.spec.ts
+
+# Version control
+.git/
+.gitignore
+
+# IDE
+.vscode/
+.idea/
+
+# Docker
+Dockerfile
+docker-compose.yml

.env.example

@@ -1 +1,10 @@
 PORT=11434
+VERBOSE=false
+API_KEY=MY0P3NA1K3Y
+ACCESS_TOKEN=MYACC3SS_T0K3N
+REFRESH_TOKEN=MYR3FR3SH_T0K3N
+EXPIRY_DATE=1234567890
+# Docker
+DOCKER_REGISTRY=
+DOCKER_REGISTRY_USER=
+DOCKER_HUB_USER=

.gitignore

@@ -22,3 +22,6 @@ dist/
 
 # Environment variables
 .env
+
+# Roo Modes
+.roomodes

.prettierignore

@@ -0,0 +1 @@
+*.*

.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": [
+      "source.fixAll.eslint"
+    ],
+    "eslint.validate": ["javascript", "typescript"],
+    "prettier.singleQuote": true,
+    "cSpell.ignorePaths" : [
+        "src"
+    ]
+}

Dockerfile

@@ -0,0 +1,26 @@
+# Use an official Node.js runtime as a parent image
+FROM node:22.15-slim
+
+# Set the working directory in the container
+WORKDIR /usr/src/app
+
+# Create directory for oauth credentials
+RUN mkdir -p /root/.gemini
+
+# Copy package.json and package-lock.json to the working directory
+COPY package*.json ./
+
+# Install any needed packages specified in package.json
+RUN npm install
+
+# Bundle app source
+COPY . .
+
+# Build the typescript code
+RUN npm run build
+
+# Make port 4343 available to the world outside this container
+EXPOSE 4343
+
+# Define the command to run the app
+CMD [ "npm", "start" ]

README.md

@@ -1,76 +1,163 @@
-# Gemini ↔︎ OpenAI Proxy
+# Gemini CLI OpenAI API Proxy
 
-Serve **Google Gemini 2.5 Pro** (or Flash) through an **OpenAI-compatible API**.  
+This project provides a lightweight proxy server that translates OpenAI API requests to the Google Gemini API, utilizing the `@google/gemini-cli` for authentication and request handling.
-Plug-and-play with clients that already speak OpenAI—SillyTavern, llama.cpp, LangChain, the VS Code *Cline* extension, etc.
 
----
+## Features
 
-## ✨ Features
+* **OpenAI API Compatibility:**  Acts as a drop-in replacement for services that use the OpenAI API format.
+* **Google Gemini Integration:** Leverages the power of Google's Gemini models.
+* **Authentication:** Uses `gemini-cli` for secure OAuth2 authentication with Google.
+* **Docker Support:** Includes `Dockerfile` and `docker-compose.yml` for easy containerized deployment.
+* **Hugging Face Spaces Ready:** Can be easily deployed as a Hugging Face Space.
 
-| ✔ | Feature | Notes |
+## Support the Project
-|---|---------|-------|
-| `/v1/chat/completions` | Non-stream & stream (SSE) | Works with curl, ST, LangChain… |
-| Vision support | `image_url` → Gemini `inlineData` | |
-| Function / Tool calling | OpenAI “functions” → Gemini Tool Registry | |
-| Reasoning / chain-of-thought | Sends `enable_thoughts:true`, streams `<think>` chunks | ST shows grey bubbles |
-| 1 M-token context | Proxy auto-lifts Gemini CLI’s default 200 k cap | |
-| CORS | Enabled (`*`) by default | Ready for browser apps |
-| Zero external deps | Node 22 + TypeScript only | No Express |
 
----
+If you find this project useful, consider supporting its development:
 
-## 🚀 Quick start (local)
+[![Donate using Liberapay][liberapay-logo]][liberapay-link]
+
+[liberapay-logo]: https://liberapay.com/assets/widgets/donate.svg "Liberapay Logo"
+[liberapay-link]: https://liberapay.com/sfiorini/donate
+
+## Prerequisites
+
+Before you begin, ensure you have the following installed:
+
+* [Node.js](https://nodejs.org/) (v18 or higher)
+* [npm](https://www.npmjs.com/)
+* [Docker](https://www.docker.com/) (for containerized deployment)
+* [Git](https://git-scm.com/)
+
+## Local Installation and Setup
+
+1. **Clone the repository:**
+
+    ```bash
+    git clone https://github.com/your-username/gemini-cli-openai-api.git
+    cd gemini-cli-openai-api
+    ```
+
+2. **Install project dependencies:**
+
+    ```bash
+    npm install
+    ```
+
+3. **Install the Gemini CLI and Authenticate:**
+
+    This is a crucial step to authenticate with your Google account and generate the necessary credentials.
+
+    ```bash
+    npm install -g @google/gemini-cli
+    gemini auth login
+    ```
+
+    Follow the on-screen instructions to log in with your Google account. This will create a file at `~/.gemini/oauth_creds.json` containing your authentication tokens.
+
+4. **Configure Environment Variables:**
+
+    Create a `.env` file by copying the example file:
+
+    ```bash
+    cp .env.example .env
+    ```
+
+    Open the `.env` file and set the following variables:
+
+    * `PORT`: The port the server will run on (default: `11434`).
+    * `API_KEY`: A secret key to protect your API endpoint. You can generate a strong random string for this.
+
+## Running the Project
+
+### Development Mode
+
+To run the server in development mode with hot-reloading:
 
 ```bash
-git clone https://huggingface.co/engineofperplexity/gemini-openai-proxy
+npm run dev
-cd gemini-openai-proxy
+```
-npm ci                        # install deps & ts-node
 
-# launch on port 11434
+The server will be accessible at `http://localhost:11434` (or the port you specified).
-npx ts-node src/server.ts
-Optional env vars
-PORT=3000 change listen port
-GEMINI_API_KEY=<key> use your own key
 
-Minimal curl test
+### Production Mode
-bash
-Copy
-Edit
-curl -X POST http://localhost:11434/v1/chat/completions \
-     -H "Content-Type: application/json" \
-     -d '{
-       "model": "gemini-2.5-pro-latest",
-       "messages":[{"role":"user","content":"Hello Gemini!"}]
-     }'
-SillyTavern settings
-Field	Value
-API Base URL	http://127.0.0.1:11434/v1
-Model	gemini-2.5-pro-latest
-Streaming	On
-Reasoning	On → grey <think> lines appear
 
-🐳 Docker
+To build and run the server in production mode:
-bash
-Copy
-Edit
-# build once
-docker build -t gemini-openai-proxy .
 
-# run
+```bash
-docker run -p 11434:11434 \
+npm run build
-           -e GEMINI_API_KEY=$GEMINI_API_KEY \
+npm start
-           gemini-openai-proxy
+```
-🗂 Project layout
+
-pgsql
+## Docker Deployment
-Copy
+
-Edit
+### Using Docker Compose
-src/
+
-  server.ts        – minimalist HTTP server
+The easiest way to deploy the project with Docker is by using the provided `docker-compose.yml` file.
-  mapper.ts        – OpenAI ⇄ Gemini transforms
+
-  chatwrapper.ts   – thin wrapper around @google/genai
+1. **Authentication:**
-  remoteimage.ts   – fetch + base64 for vision
+
-package.json       – deps & scripts
+    The Docker container needs access to your OAuth credentials. You have two options:
-Dockerfile
+
-README.md
+    * **Option A (Recommended): Mount the credentials file.**
-📜 License
+        Uncomment the `volumes` section in `docker-compose.yml` to mount your local `oauth_creds.json` file into the container.
-MIT – free for personal & commercial use.
+
+        ```yaml
+        volumes:
+          - ~/.gemini/oauth_creds.json:/root/.gemini/oauth_creds.json
+        ```
+
+    * **Option B: Use environment variables.**
+        If you cannot mount the file, you can set the `ACCESS_TOKEN`, `REFRESH_TOKEN`, and `EXPIRY_DATE` environment variables in the `docker-compose.yml` file. You can get these values from your `~/.gemini/oauth_creds.json` file.
+
+2. **Configure `docker-compose.yml`:**
+
+    Open `docker-compose.yml` and set the `API_KEY` and other environment variables as needed.
+
+3. **Start the container:**
+
+    ```bash
+    docker-compose up -d
+    ```
+
+    The server will be running on the port specified in the `ports` section of the `docker-compose.yml` file (e.g., `4343`).
+
+### Building the Docker Image Manually
+
+If you need to build the Docker image yourself:
+
+```bash
+docker build -t gemini-cli-openai-api .
+```
+
+Then you can run the container with the appropriate environment variables and volume mounts.
+
+## Hugging Face Spaces Deployment
+
+You can deploy this project as a Docker Space on Hugging Face.
+
+1. **Create a new Space:**
+    * Go to [huggingface.co/new-space](https://huggingface.co/new-space).
+    * Choose a name for your space.
+    * Select "Docker" as the Space SDK.
+    * Choose "From scratch".
+    * Create the space.
+
+2. **Upload the project files:**
+    * Upload all the project files (including the `Dockerfile`) to your new Hugging Face Space repository. You can do this via the web interface or by cloning the space's repository and pushing the files.
+
+3. **Configure Secrets:**
+    * In your Space's settings, go to the "Secrets" section.
+    * Add the following secrets. You can get the values for the first three from your `~/.gemini/oauth_creds.json` file.
+        * `ACCESS_TOKEN`: Your Google OAuth access token.
+        * `REFRESH_TOKEN`: Your Google OAuth refresh token.
+        * `EXPIRY_DATE`: The expiry date of your access token.
+        * `API_KEY`: The secret API key you want to use to protect your endpoint.
+        * `PORT`: The port the application should run on inside the container (e.g., `7860`, which is a common default for Hugging Face Spaces).
+
+4. **Update Dockerfile (if necessary):**
+    * The provided `Dockerfile` exposes port `4343`. If Hugging Face requires a different port (like `7860`), you may need to update the `EXPOSE` instruction in the `Dockerfile`.
+
+5. **Deploy:**
+    * Hugging Face Spaces will automatically build and deploy your Docker container when you push changes to the repository. Check the "Logs" to monitor the build and deployment process.
+
+Your Gemini-powered OpenAI proxy will now be running on your Hugging Face Space!

docker-compose.yml

@@ -0,0 +1,20 @@
+version: '3.8'
+services:
+  gemini-cli-openai-api:
+    container_name: gemini-cli-openai-api  
+    image: sfiorini/gemini-cli-openai-api:latest
+    ports:
+      - "4343:4343"
+    # Enable sharing a pre existing OAuth credentials file
+    # to avoid the need to set environment variables.
+    # volumes:
+    #   - ~/.gemini/oauth_creds.json:/root/.gemini/oauth_creds.json
+    environment:
+      - TZ=America/Chicago
+      - PORT=4343
+      - VERBOSE=false
+      - API_KEY=MY0P3NA1K3Y
+      - ACCESS_TOKEN=MYACC3SS_T0K3N
+      - REFRESH_TOKEN=MYR3FR3SH_T0K3N
+      - EXPIRY_DATE=1234567890
+    restart: unless-stopped

eslint.config.ts

@@ -9,7 +9,7 @@ export default tseslint.config(
   ...tseslint.configs.strictTypeChecked,
   ...tseslint.configs.stylisticTypeChecked,
   {
-    ignores: ['**/node_modules/*', '**/*.mjs', '**/*.js', 'src/mapper.ts'],
+    ignores: ['**/node_modules/*', '**/*.mjs', '**/*.js'],
   },
   {
     languageOptions: {

package-lock.json

@@ -1,15 +1,16 @@
 {
   "name": "gemini-cli-openai-api",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "gemini-cli-openai-api",
-      "version": "0.0.2",
+      "version": "0.0.5",
       "license": "MIT",
       "dependencies": {
         "@google/gemini-cli-core": "^0.1.7",
+        "consola": "^3.4.2",
         "dotenv": "^17.0.0",
         "zod": "^3.25.67"
       },
@@ -18,6 +19,7 @@
         "@stylistic/eslint-plugin": "^5.0.0",
         "@types/node": "^24.0.6",
         "bumpp": "^10.2.0",
+        "dotenv-cli": "^8.0.0",
         "eslint": "^9.30.0",
         "eslint-plugin-n": "^17.20.0",
         "jiti": "^2.4.2",
@@ -2941,7 +2943,6 @@
       "version": "3.4.2",
       "resolved": "https://registry.npmjs.org/consola/-/consola-3.4.2.tgz",
       "integrity": "sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": "^14.18.0 || >=16.10.0"
@@ -3185,6 +3186,45 @@
         "url": "https://dotenvx.com"
       }
     },
+    "node_modules/dotenv-cli": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/dotenv-cli/-/dotenv-cli-8.0.0.tgz",
+      "integrity": "sha512-aLqYbK7xKOiTMIRf1lDPbI+Y+Ip/wo5k3eyp6ePysVaSqbyxjyK3dK35BTxG+rmd7djf5q2UPs4noPNH+cj0Qw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cross-spawn": "^7.0.6",
+        "dotenv": "^16.3.0",
+        "dotenv-expand": "^10.0.0",
+        "minimist": "^1.2.6"
+      },
+      "bin": {
+        "dotenv": "cli.js"
+      }
+    },
+    "node_modules/dotenv-cli/node_modules/dotenv": {
+      "version": "16.6.1",
+      "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.6.1.tgz",
+      "integrity": "sha512-uBq4egWHTcTt33a72vpSG0z3HnPuIl6NqYcTrKEg2azoEyl2hpW0zqlxysq2pK9HlDIHyHyakeYaYnSAwd8bow==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://dotenvx.com"
+      }
+    },
+    "node_modules/dotenv-expand": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/dotenv-expand/-/dotenv-expand-10.0.0.tgz",
+      "integrity": "sha512-GopVGCpVS1UKH75VKHGuQFqS1Gusej0z4FyQkPdwjil2gNIv+LNsqBlboOzpJFZKVT95GkCyWJbBSdFEFUWI2A==",
+      "dev": true,
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=12"
+      }
+    },
     "node_modules/dts-resolver": {
       "version": "2.1.1",
       "resolved": "https://registry.npmjs.org/dts-resolver/-/dts-resolver-2.1.1.tgz",

package.json

@@ -1,11 +1,22 @@
 {
   "name": "gemini-cli-openai-api",
-  "version": "0.0.2",
+  "version": "0.0.5",
   "main": "server.ts",
   "scripts": {
     "build": "tsdown",
     "bump-release": "bumpp",
     "dev": "tsx watch ./src/server.ts",
+    "docker": "npm run docker:build && npm run docker:push",
+    "docker:build": "npm run docker:build:version && npm run docker:tag:latest && npm run docker:build:du:version && npm run docker:tag:du:latest",
+    "docker:build:version": "dotenv -- bash -c 'docker build -t $DOCKER_REGISTRY/$DOCKER_REGISTRY_USER/$npm_package_name:v$npm_package_version .'",
+    "docker:build:du:version": "dotenv -- bash -c 'docker build -t $DOCKER_HUB_USER/$npm_package_name:v$npm_package_version .'",
+    "docker:push": "npm run docker:push:version && npm run docker:push:latest && npm run docker:push:du:version && npm run docker:push:du:latest",
+    "docker:push:latest": "dotenv -- bash -c 'docker push $DOCKER_REGISTRY/$DOCKER_REGISTRY_USER/$npm_package_name:latest'",
+    "docker:push:du:latest": "dotenv -- bash -c 'docker push $DOCKER_HUB_USER/$npm_package_name:latest'",
+    "docker:push:version": "dotenv -- bash -c 'docker push $DOCKER_REGISTRY/$DOCKER_REGISTRY_USER/$npm_package_name:v$npm_package_version'",
+    "docker:push:du:version": "dotenv -- bash -c 'docker push $DOCKER_HUB_USER/$npm_package_name:v$npm_package_version'",
+    "docker:tag:latest": "dotenv -- bash -c 'docker tag $DOCKER_REGISTRY/$DOCKER_REGISTRY_USER/$npm_package_name:v$npm_package_version $DOCKER_REGISTRY/$DOCKER_REGISTRY_USER/$npm_package_name:latest'",
+    "docker:tag:du:latest": "dotenv -- bash -c 'docker tag $DOCKER_HUB_USER/$npm_package_name:v$npm_package_version $DOCKER_HUB_USER/$npm_package_name:latest'",
     "start": "node ./dist/server.js",
     "knip": "knip",
     "lint": "eslint --fix ."
@@ -16,6 +27,7 @@
   "description": "",
   "dependencies": {
     "@google/gemini-cli-core": "^0.1.7",
+    "consola": "^3.4.2",
     "dotenv": "^17.0.0",
     "zod": "^3.25.67"
   },
@@ -24,6 +36,7 @@
     "@stylistic/eslint-plugin": "^5.0.0",
     "@types/node": "^24.0.6",
     "bumpp": "^10.2.0",
+    "dotenv-cli": "^8.0.0",
     "eslint": "^9.30.0",
     "eslint-plugin-n": "^17.20.0",
     "jiti": "^2.4.2",

src/auth.ts

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview This file contains the authentication logic for the server.
+ */
+import http from 'http';
+import { config } from './config';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import consola from 'consola';
+
+/**
+ * Ensures that the OAuth credentials file exists if the required environment
+ * variables are present.
+ */
+export async function ensureOAuthCredentials(): Promise<void> {
+  const geminiDir = path.join(os.homedir(), '.gemini');
+  const credsPath = path.join(geminiDir, 'oauth_creds.json');
+
+  try {
+    await fs.access(credsPath);
+    consola.info(`OAuth credentials file already exists at ${credsPath}`);
+  } catch {
+    consola.info(`OAuth credentials file not found at ${credsPath}.`);
+    if (config.ACCESS_TOKEN && config.REFRESH_TOKEN && config.EXPIRY_DATE) {
+      consola.info('Creating OAuth credentials file' +
+        ' from environment variables.');
+      await fs.mkdir(geminiDir, { recursive: true });
+      const creds = {
+        access_token: config.ACCESS_TOKEN,
+        refresh_token: config.REFRESH_TOKEN,
+        token_type: 'Bearer',
+        expiry_date: config.EXPIRY_DATE,
+      };
+      await fs.writeFile(credsPath, JSON.stringify(creds, null, 2));
+      consola.info(`Successfully created ${credsPath}`);
+    } else {
+      consola.error(
+        'OAuth credentials file is missing and one or more required ' +
+          'environment variables: ACCESS_TOKEN, REFRESH_TOKEN, EXPIRY_DATE.',
+      );
+      throw new Error('Missing OAuth credentials or environment variables.');
+    }
+  }
+}
+
+/**
+ * Checks for API key authentication.
+ * @param req - The HTTP incoming message object.
+ * @param res - The HTTP server response object.
+ * @returns True if the request is authorized, false otherwise.
+ */
+export function isAuthorized(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+): boolean {
+  if (!config.API_KEY) {
+    return true; // No key configured, public access.
+  }
+
+  const authHeader = req.headers.authorization;
+  if (!authHeader) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(
+      JSON.stringify({ error: { message: 'Missing Authorization header' } }),
+    );
+    return false;
+  }
+
+  const token = authHeader.split(' ')[1];
+  if (token !== config.API_KEY) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: { message: 'Invalid API key' } }));
+    return false;
+  }
+
+  return true;
+}

src/chatwrapper.ts

@@ -1,69 +1,208 @@
-// src/chatwrapper.ts
+/**
+ * @fileoverview This file provides a wrapper around the Gemini API, handling
+ * content generation, model management, and retry logic.
+ */
 import {
   AuthType,
   createContentGeneratorConfig,
   createContentGenerator,
+  ContentGenerator,
 } from '@google/gemini-cli-core/dist/src/core/contentGenerator.js';
 
-/* ------------------------------------------------------------------ */
+import {
-/* 1.  Build the ContentGenerator exactly like the CLI does           */
+  DEFAULT_GEMINI_MODEL,
-/* ------------------------------------------------------------------ */
+  DEFAULT_GEMINI_FLASH_MODEL,
-let modelName: string;                      // we'll fill this once
+} from '@google/gemini-cli-core/dist/src/config/models.js';
-const generatorPromise = (async () => {
-  // Pass undefined for model so the helper falls back to DEFAULT_GEMINI_MODEL
-  const cfg = await createContentGeneratorConfig(
-    undefined, // let helper pick default (Gemini-2.5-Pro)
-    AuthType.LOGIN_WITH_GOOGLE_PERSONAL, // same mode the CLI defaults to
-  );
-  modelName = cfg.model;           // remember the actual model string
-  return await createContentGenerator(cfg);
-})();
 
-/* ------------------------------------------------------------------ */
+import { Content, GeminiResponse, Model } from './types.js';
-/* 2.  Helpers consumed by server.ts                                   */
+import consola from 'consola';
-/* ------------------------------------------------------------------ */
+
+// ==================================================================
+// 1. ContentGenerator Management
+// ==================================================================
+
+/**
+ * A cache for ContentGenerator instances to avoid re-creating them.
+ * The key is the model name, or 'default' for the default model.
+ */
+const generatorCache = new Map<
+  string,
+  Promise<{
+    generator: ContentGenerator,
+    model: string,
+  }>
+>();
+
+/**
+ * Retrieves a ContentGenerator, creating and caching it if necessary.
+ * If an unsupported model is requested, it falls back to the default model.
+ *
+ * @param model - The name of the model to use.
+ * @returns A promise that resolves to an object containing
+ * the generator and the effective model name.
+ */
+function getGenerator(
+  model?: string,
+): Promise<{
+  generator: ContentGenerator,
+  model: string,
+}> {
+  // Fallback to default if the specified model is not supported.
+  const modelToUse =
+    model === DEFAULT_GEMINI_MODEL || model === DEFAULT_GEMINI_FLASH_MODEL
+      ? model
+      : undefined;
+
+  // Use the effective model name for the cache key.
+  const key = modelToUse ?? 'default';
+
+  if (generatorCache.has(key)) {
+    return generatorCache.get(key)!;
+  }
+
+  // Create and cache a new generator.
+  const generatorPromise = (async () => {
+    const cfg = await createContentGeneratorConfig(
+      modelToUse,
+      AuthType.LOGIN_WITH_GOOGLE_PERSONAL,
+    );
+    const generator = await createContentGenerator(cfg);
+    return { generator, model: cfg.model };
+  })();
+
+  generatorCache.set(key, generatorPromise);
+  return generatorPromise;
+}
+
+// ==================================================================
+// 2. API Helpers
+// ==================================================================
 type GenConfig = Record<string, unknown>;
 
+const MAX_RETRIES = 3;
+const INITIAL_RETRY_DELAY = 1000; // 1 second
+
+/**
+ * A higher-order function that adds retry logic with exponential backoff
+ * to an operation that may fail due to rate limiting.
+ *
+ * @param operation - The async operation to perform.
+ * @returns The result of the operation.
+ * @throws Throws an error if the operation fails after all retries.
+ */
+async function withRetry<T>(operation: () => Promise<T>): Promise<T> {
+  let retries = 0;
+  while (true) {
+    try {
+      return await operation();
+    } catch (error) {
+      // Only retry on 'RESOURCE_EXHAUSTED' errors.
+      if (!(error instanceof Error) ||
+          !error.message.includes('RESOURCE_EXHAUSTED') ||
+          retries >= MAX_RETRIES) {
+        throw error;
+      }
+      retries++;
+      const delay = INITIAL_RETRY_DELAY * Math.pow(2, retries - 1);
+       
+      consola.error(
+        `Rate limit hit, retrying in ${delay}ms ` +
+        `(attempt ${retries}/${MAX_RETRIES})`,
+      );
+      await new Promise(resolve => setTimeout(resolve, delay));
+    }
+  }
+}
+
+/**
+ * Sends a chat request to the Gemini API.
+ *
+ * @param params - The request parameters.
+ * @param params.model - The model to use.
+ * @param params.contents - The chat history.
+ * @param params.generationConfig - Configuration for the generation.
+ * @returns The Gemini API response.
+ */
 export async function sendChat({
+  model,
   contents,
   generationConfig = {},
 }: {
-  contents: any[],
+  model?: string,
+  contents: Content[],
   generationConfig?: GenConfig,
   tools?: unknown, // accepted but ignored for now
-}) {
+}): Promise<GeminiResponse> {
-  const generator: any = await generatorPromise;
+  const { generator, model: modelName } = await getGenerator(model);
-  return await generator.generateContent({
+  const gResp = await withRetry(() => generator.generateContent({
     model: modelName,
     contents,
     config: generationConfig,
-  });
+  }));
+  return {
+    text: gResp.text ?? '',
+    usageMetadata: {
+      promptTokens: gResp.usageMetadata?.promptTokenCount ?? 0,
+      candidatesTokens: gResp.usageMetadata?.candidatesTokenCount ?? 0,
+      totalTokens: gResp.usageMetadata?.totalTokenCount ?? 0,
+    },
+  };
 }
 
+/**
+ * Sends a streaming chat request to the Gemini API.
+ *
+ * @param params - The request parameters.
+ * @param params.model - The model to use.
+ * @param params.contents - The chat history.
+ * @param params.generationConfig - Configuration for the generation.
+ * @yields Chunks of the Gemini API response.
+ */
 export async function* sendChatStream({
+  model,
   contents,
   generationConfig = {},
 }: {
-  contents: any[],
+  model?: string,
+  contents: Content[],
   generationConfig?: GenConfig,
   tools?: unknown,
 }) {
-  const generator: any = await generatorPromise;
+  const { generator, model: modelName } = await getGenerator(model);
-  const stream = await generator.generateContentStream({
+  const stream = await withRetry(() => generator.generateContentStream({
     model: modelName,
     contents,
     config: generationConfig,
-  });
+  }));
   for await (const chunk of stream) yield chunk;
 }
 
-/* ------------------------------------------------------------------ */
+/**
-/* 3.  Additional stubs to implement later                            */
+ * Lists the available models.
-/* ------------------------------------------------------------------ */
+ *
-// export function listModels() {
+ * @returns An array of available models.
-//   return [{ id: modelName }];
+ */
-// }
+export function listModels(): Model[] {
+  return  [
+    {
+      id: DEFAULT_GEMINI_MODEL,
+      object: 'model',
+      owned_by: 'google',
+    },
+    {
+      id: DEFAULT_GEMINI_FLASH_MODEL,
+      object: 'model',
+      owned_by: 'google',
+    },
+  ];
+}
 
+// ==================================================================
+// 3. Future Implementations
+// ==================================================================
+
+// The embeddings endpoint is not yet implemented.
 // export async function embed(_input: unknown) {
 //   throw new Error('Embeddings endpoint not implemented yet.');
 // }
+

src/config.ts

@@ -1,8 +1,49 @@
+/**
+ * @fileoverview This file manages the application's configuration,
+ * loading environment variables and providing them in a structured object.
+ */
+/* eslint-disable n/no-process-env */
 import dotenv from 'dotenv';
 
 dotenv.config();
 
+/**
+ * Application configuration object.
+ */
 export const config = {
-  // eslint-disable-next-line n/no-process-env
+  /**
+   * The port number for the server to listen on.
+   * Defaults to 11434 if not specified in the environment.
+   * @type {number}
+   */
   PORT: Number(process.env.PORT ?? 11434),
+  /**
+   * A flag to enable or disable verbose logging.
+   * Defaults to true if not specified in the environment.
+   * @type {boolean}
+   */
+  VERBOSE: Boolean(process.env.VERBOSE ?? true),
+  /**
+   * The API key for securing the server.
+   * If not set, the server will be public.
+   * @type {string | undefined}
+   */
+  API_KEY: process.env.API_KEY,
+  /**
+   * The access token for OAuth.
+   * @type {string | undefined}
+   */
+  ACCESS_TOKEN: process.env.ACCESS_TOKEN,
+  /**
+   * The refresh token for OAuth.
+   * @type {string | undefined}
+   */
+  REFRESH_TOKEN: process.env.REFRESH_TOKEN,
+  /**
+   * The expiry date for the access token.
+   * @type {number | undefined}
+   */
+  EXPIRY_DATE: process.env.EXPIRY_DATE
+    ? Number(process.env.EXPIRY_DATE)
+    : undefined,
 };

src/mapper.ts

@@ -1,95 +1,153 @@
-/* ------------------------------------------------------------------ */
+/**
-/*  mapper.ts – OpenAI ⇆ Gemini (with reasoning/1 M context)           */
+ * @fileoverview This file contains the logic for mapping requests and
-/* ------------------------------------------------------------------ */
+ * responses between the OpenAI and Gemini API formats. It handles message
+ * conversion, vision support, and tool mapping.
+ */
 import { fetchAndEncode } from './remoteimage';
-import { z } from 'zod';
+import { z, ZodRawShape } from 'zod';
-import { ToolRegistry } from '@google/gemini-cli-core/dist/src/tools/tool-registry.js';
+import { ToolRegistry }
+  from '@google/gemini-cli-core/dist/src/tools/tool-registry.js';
+import { Config } from '@google/gemini-cli-core/dist/src/config/config.js';
+import { Tool } from '@google/gemini-cli-core/dist/src/tools/tools.js';
+import {
+  Part,
+  RequestBody,
+  GeminiResponse,
+  GeminiStreamChunk,
+  GeminiRequestBody,
+  Content,
+} from './types';
 
-/* ------------------------------------------------------------------ */
+/**
-interface Part { text?: string; inlineData?: { mimeType: string, data: string } }
+ * A placeholder for a local function call.
-
+ *
-/* ------------------------------------------------------------------ */
+ * @returns A promise that resolves to a successful execution result.
-function callLocalFunction(_name: string, _args: unknown) {
+ */
-  return { ok: true };
+async function callLocalFunction(/*_name: string, _args: unknown*/) {
+  return Promise.resolve({
+    ok: true,
+    llmContent: [],
+    returnDisplay: 'Function executed successfully',
+  });
 }
 
-/* ================================================================== */
+// ==================================================================
-/* Request mapper: OpenAI ➞ Gemini                                     */
+// Request Mapper: OpenAI -> Gemini
-/* ================================================================== */
+// ==================================================================
-export async function mapRequest(body: any) {
+/**
-  const parts: Part[] = [];
+ * Maps an OpenAI-compatible request body to a Gemini-compatible format.
+ *
+ * @param body - The incoming OpenAI request body.
+ * @returns An object containing the mapped Gemini request and tools.
+ */
+export async function mapRequest(body: RequestBody) {
+  const contents: Content[] = [];
+  const systemParts: Part[] = [];
 
-  /* ---- convert messages & vision --------------------------------- */
+  // Convert messages and handle vision content.
   for (const m of body.messages) {
+    const parts: Part[] = [];
     if (Array.isArray(m.content)) {
       for (const item of m.content) {
-        if (item.type === 'image_url') {
+        if (item.type === 'image_url' && item.image_url) {
           parts.push({ inlineData: await fetchAndEncode(item.image_url.url) });
         } else if (item.type === 'text') {
           parts.push({ text: item.text });
         }
       }
-    } else {
+    } else if (m.content) {
       parts.push({ text: m.content });
     }
+
+    if (m.role === 'system') {
+      systemParts.push(...parts);
+      continue;
+    }
+
+    if (m.role === 'user') {
+      contents.push({ role: 'user', parts: [...systemParts, ...parts] });
+      systemParts.length = 0;
+    } else if (m.role === 'assistant') {
+      contents.push({ role: 'model', parts });
+    }
   }
 
-  /* ---- base generationConfig ------------------------------------- */
+  // Map generation configuration parameters.
   const generationConfig: Record<string, unknown> = {
     temperature: body.temperature,
     maxOutputTokens: body.max_tokens,
     topP: body.top_p,
-    ...(body.generationConfig ?? {}), // copy anything ST already merged
+    ...(body.generationConfig ?? {}), // Preserve existing ST-merged config.
   };
   if (body.include_reasoning === true) {
-    generationConfig.enable_thoughts = true;        // ← current flag
+    // The current flag for enabling thoughts.
-    generationConfig.thinking_budget ??= 2048;      // optional limit
+    generationConfig.enable_thoughts = true;
+    // Optional limit for thinking budget.
+    generationConfig.thinking_budget ??= 2048;
   }
 
-  /* ---- auto-enable reasoning & 1 M context ----------------------- */
+  // Auto-enable reasoning and a 1 million token context window.
   if (body.include_reasoning === true && generationConfig.thinking !== true) {
     generationConfig.thinking = true;
     generationConfig.thinking_budget ??= 2048;
   }
-  generationConfig.maxInputTokens ??= 1_000_000; // lift context cap
+  generationConfig.maxInputTokens ??= 1_000_000; // Increase the context cap.
 
-  const geminiReq = {
+  // Map tools and functions.
-    contents: [{ role: 'user', parts }],
+  // Note: ToolRegistry expects a complex Config object that is not available
-    generationConfig,
+  // here. Casting to `Config` is a necessary workaround.
-    stream: body.stream,
+  const tools = new ToolRegistry({} as Config);
-  };
-
-  /* ---- Tool / function mapping ----------------------------------- */
-  const tools = new ToolRegistry({} as any);
 
   if (body.functions?.length) {
-    const reg = tools as any;
+    for (const fn of body.functions) {
-    body.functions.forEach((fn: any) =>
+      tools.registerTool({
-      reg.registerTool(
+        name: fn.name,
-        fn.name,
+        displayName: fn.name,
-        {
-          title: fn.name,
         description: fn.description ?? '',
-          inputSchema: z.object(fn.parameters?.properties ?? {}),
+        schema: z.object((fn.parameters?.properties as ZodRawShape) ?? {}),
-        },
+        isOutputMarkdown: false,
-        (args: unknown) => callLocalFunction(fn.name, args),
+        canUpdateOutput: false,
-      ),
+        validateToolParams: () => null,
-    );
+        getDescription: (params: unknown) =>
+          `Executing ${fn.name} with parameters: ` + JSON.stringify(params),
+        shouldConfirmExecute: () => Promise.resolve(false),
+        execute: () => callLocalFunction(),
+      } as Tool);
+    }
   }
 
-  return { geminiReq, tools };
+  return {
+    geminiReq: {
+      model: body.model,
+      contents,
+      generationConfig,
+      stream: body.stream,
+    } as GeminiRequestBody,
+    tools,
+  };
 }
 
-/* ================================================================== */
+// ==================================================================
-/* Non-stream response: Gemini ➞ OpenAI                                */
+// Response Mapper: Gemini -> OpenAI (Non-Streaming)
-/* ================================================================== */
+// ==================================================================
-export function mapResponse(gResp: any) {
+/**
-  const usage = gResp.usageMetadata ?? {};
+ * Maps a Gemini API response to the OpenAI format for non-streaming responses.
+ *
+ * @param gResp - The response from the Gemini API.
+ * @param body - The original OpenAI request body.
+ * @returns An OpenAI-compatible chat completion object.
+ */
+export function mapResponse(gResp: GeminiResponse, body: RequestBody) {
+  const usage = gResp.usageMetadata ?? {
+    promptTokens: 0,
+    candidatesTokens: 0,
+    totalTokens: 0,
+  };
   return {
     id: `chatcmpl-${Date.now()}`,
     object: 'chat.completion',
     created: Math.floor(Date.now() / 1000),
-    model: 'gemini-2.5-pro-latest',
+    model: body.model,
     choices: [
       {
         index: 0,
@@ -98,27 +156,32 @@ export function mapResponse(gResp: any) {
       },
     ],
     usage: {
-      prompt_tokens: usage.promptTokens ?? 0,
+      prompt_tokens: usage.promptTokens,
-      completion_tokens: usage.candidatesTokens ?? 0,
+      completion_tokens: usage.candidatesTokens,
-      total_tokens: usage.totalTokens ?? 0,
+      total_tokens: usage.totalTokens,
     },
   };
 }
 
-/* ================================================================== */
+// ==================================================================
-/* Stream chunk mapper: Gemini ➞ OpenAI                                */
+// Stream Chunk Mapper: Gemini -> OpenAI
-/* ================================================================== */
+// ==================================================================
 
-export function mapStreamChunk(chunk: any) {
+/**
+ * Maps a Gemini stream chunk to the OpenAI format.
+ *
+ * @param chunk - A chunk from the Gemini API stream.
+ * @returns An OpenAI-compatible stream chunk.
+ */
+export function mapStreamChunk(chunk: GeminiStreamChunk) {
   const part = chunk?.candidates?.[0]?.content?.parts?.[0] ?? {};
-  const delta: any = { role: 'assistant' };
+  const delta: { role: 'assistant', content?: string } = { role: 'assistant' };
 
   if (part.thought === true) {
-    delta.content = `<think>${part.text ?? ''}`;  // ST renders grey bubble
+    // Wrap thought content in <think> tags for rendering.
+    delta.content = `<think>${part.text ?? ''}`;
   } else if (typeof part.text === 'string') {
     delta.content = part.text;
   }
-  return { choices: [ { delta, index: 0 } ] };
+  return { choices: [{ delta, index: 0 }] };
 }
-
-

src/remoteimage.ts

@@ -1,3 +1,17 @@
+/**
+ * @fileoverview This file provides a utility function for fetching a remote
+ * image and encoding it in base64.
+ */
+
+/**
+ * Fetches an image from a URL and returns
+ * its MIME type and base64-encoded data.
+ *
+ * @param url - The URL of the image to fetch.
+ * @returns A promise that resolves to an object containing the MIME type and
+ *   base64-encoded image data.
+ * @throws Throws an error if the image fetch fails.
+ */
 export async function fetchAndEncode(url: string) {
   const res = await fetch(url);
   if (!res.ok) throw new Error(`Failed to fetch image: ${url}`);

src/server.ts

@@ -1,23 +1,56 @@
+/**
+ * @fileoverview This file sets up and runs the HTTP server that acts as a
+ * proxy between an OpenAI-compatible client and the Gemini API.
+ */
+import consola from 'consola';
 import http from 'http';
-import { sendChat, sendChatStream } from './chatwrapper';
+import { listModels, sendChat, sendChatStream } from './chatwrapper';
-import { mapRequest, mapResponse, mapStreamChunk } from './mapper';
+import { mapRequest, mapResponse, mapStreamChunk } from './mapper.js';
+import { RequestBody, GeminiResponse, GeminiStreamChunk, Part } from './types';
 import { config } from './config';
+import { isAuthorized, ensureOAuthCredentials } from './auth';
 
-/* ── basic config ─────────────────────────────────────────────────── */
+// ==================================================================
+// Server Configuration
+// ==================================================================
 const PORT = config.PORT;
+const VERBOSE = config.VERBOSE;
 
-/* ── CORS helper ──────────────────────────────────────────────────── */
+// ==================================================================
+// Logger Setup
+// ==================================================================
+if (VERBOSE) {
+  consola.level = 5;
+  consola.info('Verbose logging enabled');
+}
+
+consola.info('Google CLI OpenAI API');
+
+// ==================================================================
+// HTTP Server Helpers
+// ==================================================================
+
+/**
+ * Sets CORS headers to allow cross-origin requests.
+ * @param res - The HTTP server response object.
+ */
 function allowCors(res: http.ServerResponse) {
   res.setHeader('Access-Control-Allow-Origin', '*');
   res.setHeader('Access-Control-Allow-Headers', '*');
   res.setHeader('Access-Control-Allow-Methods', 'GET,POST,OPTIONS');
 }
 
-/* ── JSON body helper ─────────────────────────────────────────────── */
+/**
+ * Reads and parses a JSON request body.
+ * @param req - The HTTP incoming message object.
+ * @param res - The HTTP server response object.
+ * @returns A promise that resolves to the parsed request body
+ * or null if invalid.
+ */
 function readJSON(
   req: http.IncomingMessage,
   res: http.ServerResponse,
-): Promise<any | null> {
+): Promise<RequestBody | null> {
   return new Promise((resolve) => {
     let data = '';
     req.on('data', (c) => (data += c));
@@ -30,55 +63,70 @@ function readJSON(
               error: { message: 'Request body is missing for POST request' },
             }),
           );
+          resolve(null);
+          return;
         }
-        return resolve(null);
+        resolve(null);
+        return;
       }
       try {
-        resolve(JSON.parse(data));
+        resolve(JSON.parse(data) as RequestBody);
       } catch {
-        res.writeHead(400, { 'Content-Type': 'application/json' }); // malformed JSON
+        // Handle malformed JSON.
+        res.writeHead(400, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: { message: 'Malformed JSON' } }));
         resolve(null);
+        return;
       }
     });
   });
 }
 
-/* ── server ───────────────────────────────────────────────────────── */
+// ==================================================================
-http
+// Main Server Logic
+// ==================================================================
+
+ensureOAuthCredentials()
+  .then(() => {
+    http
       .createServer(async (req, res) => {
         allowCors(res);
         const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
         const pathname = url.pathname.replace(/\/$/, '') || '/';
-    console.log(`[proxy] ${req.method} ${url.pathname}`);
+        consola.info(`${req.method} ${url.pathname}`);
 
-    /* -------- pre-flight ---------- */
+        // Handle pre-flight CORS requests.
         if (req.method === 'OPTIONS') {
           res.writeHead(204).end();
           return;
         }
 
-    /* -------- /v1/models ---------- */
+        if (pathname === '/') {
+          res.writeHead(200, { 'Content-Type': 'text/plain' });
+          res.end('Google CLI OpenAI API server is running......');
+          return;
+        }
+
+        if (!isAuthorized(req, res)) {
+          return;
+        }
+
+        // Route for listing available models.
         if (pathname === '/v1/models' || pathname === '/models') {
           res.writeHead(200, { 'Content-Type': 'application/json' });
           res.end(
             JSON.stringify({
-          data: [
+              data: listModels(),
-            {
-              id: 'gemini-2.5-pro',
-              object: 'model',
-              owned_by: 'google',
-            },
-          ],
             }),
           );
           return;
         }
 
-    /* ---- /v1/chat/completions ---- */
+        // Route for chat completions.
         if (
           (pathname === '/chat/completions' ||
-      (pathname === '/v1/chat/completions' ) && req.method === 'POST')
+        pathname === '/v1/chat/completions') &&
+      req.method === 'POST'
         ) {
           const body = await readJSON(req, res);
           if (!body) return;
@@ -93,24 +141,79 @@ http
                 Connection: 'keep-alive',
               });
 
-          for await (const chunk of sendChatStream({ ...geminiReq, tools })) {
+              for await (
-            res.write(`data: ${JSON.stringify(mapStreamChunk(chunk))}\n\n`);
+                const chunk of sendChatStream({ ...geminiReq, tools })) {
+                // Transform the chunk to match the expected stream format.
+                const transformedParts =
+              chunk.candidates?.[0]?.content?.parts?.map((part) => {
+                const transformedPart: Part = {
+                  text: part.text,
+                  thought: part.text?.startsWith?.('<think>') ?? false,
+                };
+
+                if (part.inlineData?.data) {
+                  transformedPart.inlineData = {
+                    mimeType: part.inlineData.mimeType ?? 'text/plain',
+                    data: part.inlineData.data,
+                  };
+                }
+
+                return transformedPart;
+              }) ?? [];
+
+                const streamChunk: GeminiStreamChunk = {
+                  candidates: [
+                    {
+                      content: {
+                        parts: transformedParts,
+                      },
+                    },
+                  ],
+                };
+
+                res.write(
+                  `data: ${JSON.stringify(mapStreamChunk(streamChunk))}\n\n`,
+                );
               }
               res.end('data: [DONE]\n\n');
             } else {
-          const gResp = await sendChat({ ...geminiReq, tools });
+              const gResp: GeminiResponse =
+              await sendChat({ ...geminiReq, tools });
               res.writeHead(200, { 'Content-Type': 'application/json' });
-          res.end(JSON.stringify(mapResponse(gResp)));
+              res.end(JSON.stringify(mapResponse(gResp, body)));
-        }
-      } catch (err: any) {
-        console.error('Proxy error ➜', err);
-        res.writeHead(500, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ error: { message: err.message } }));
-      }
-      return;
             }
+          } catch (err) {
+            const error = err as Error;
+            consola.error('Proxy error ➜', error);
         
-    /* ---- anything else ---------- */
+            // Handle errors, sending them in the appropriate
-    res.writeHead(404).end();
+            // format for streaming or non-streaming responses.
+            if (body.stream && res.headersSent) {
+              res.write(
+                `data: ${JSON.stringify({
+                  error: {
+                    message: error.message,
+                    type: 'error',
+                  },
+                })}\n\n`,
+              );
+              res.end('data: [DONE]\n\n');
+              return;
+            } else {
+              res.writeHead(500, { 'Content-Type': 'application/json' });
+              res.end(JSON.stringify({ error: { message: error.message } }));
+            }
+          }
+        }
       })
-  .listen(PORT, () => console.log(`OpenAI proxy on :${PORT}`));
+      .listen(PORT, () => {
+        consola.info(`Listening on port :${PORT}`);
+      });
+  })
+  .catch((err: unknown) => {
+    if (err instanceof Error) {
+      consola.error(err.message);
+    } else {
+      consola.error('An unknown error occurred during startup.');
+    }
+  });

src/types.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview This file contains type definitions for the data structures
+ * used throughout the application, including request and response bodies for
+ * both the OpenAI and Gemini APIs.
+ */
+/**
+ * Represents a model available in the API.
+ */
+export interface Model {
+  /** The unique identifier for the model. */
+  id: string;
+  /** The type of object, always 'model'. */
+  object: 'model';
+  /** The owner of the model, always 'google'. */
+  owned_by: 'google';
+}
+
+/**
+ * Represents inline data, such as an image.
+ */
+interface InlineData {
+  /** The MIME type of the data (e.g., 'image/png'). */
+  mimeType: string;
+  /** The base64-encoded data. */
+  data: string;
+}
+
+/**
+ * Represents a part of a multi-part message.
+ */
+export interface Part {
+  /** The text content of the part. */
+  text?: string;
+  /** The inline data content of the part. */
+  inlineData?: InlineData;
+  /** A flag indicating if this part represents a thought process. */
+  thought?: boolean;
+}
+
+/**
+ * Represents a piece of content in a conversation.
+ */
+export interface Content {
+  /**
+   * The producer of the content. Must be either 'user' or 'model'.
+   *
+   * Useful to set for multi-turn conversations, otherwise can be empty.
+   * If role is not specified, SDK will determine the role.
+   */
+  role?: 'user' | 'model';
+  /** An array of parts that make up the content. */
+  parts: Part[];
+}
+
+/**
+ * Represents a function definition for tool use.
+ */
+interface FunctionDef {
+  /** The name of the function. */
+  name: string;
+  /** A description of the function. */
+  description?: string;
+  /** The parameters of the function, described as a JSON schema. */
+  parameters?: {
+    properties?: Record<string, unknown>,
+  };
+}
+
+/**
+ * Represents the body of an incoming OpenAI-compatible request.
+ */
+export interface RequestBody {
+  /** The model to use for the request. */
+  model: string;
+  /** A list of messages in the conversation history. */
+  messages: {
+    role: string,
+    content:
+      | string
+      | { type: string, image_url?: { url: string }, text?: string }[],
+  }[];
+  /** The sampling temperature. */
+  temperature?: number;
+  /** The maximum number of tokens to generate. */
+  max_tokens?: number;
+  /** The nucleus sampling probability. */
+  top_p?: number;
+  /** Additional generation configuration for the Gemini API. */
+  generationConfig?: Record<string, unknown>;
+  /** A flag to include reasoning/thoughts in the response. */
+  include_reasoning?: boolean;
+  /** A flag to indicate if the response should be streamed. */
+  stream?: boolean;
+  /** A list of functions the model can call. */
+  functions?: FunctionDef[];
+}
+
+/**
+ * Represents the request body for the Gemini API.
+ */
+export interface GeminiRequestBody {
+  /** The model to use. */
+  model?: string;
+  /** The content of the conversation. */
+  contents: Content[];
+  /** Configuration for the generation process. */
+  generationConfig: Record<string, unknown>;
+  /** Whether to stream the response. */
+  stream?: boolean;
+}
+
+
+/**
+ * Represents a non-streaming response from the Gemini API.
+ */
+export interface GeminiResponse {
+  /** The generated text content. */
+  text: string;
+  /** Metadata about token usage. */
+  usageMetadata?: {
+    /** The number of tokens in the prompt. */
+    promptTokens: number,
+    /** The number of tokens in the generated candidates. */
+    candidatesTokens: number,
+    /** The total number of tokens used. */
+    totalTokens: number,
+  };
+}
+
+/**
+ * Represents a chunk of a streaming response from the Gemini API.
+ */
+export interface GeminiStreamChunk {
+  /** A list of candidate responses. */
+  candidates?: {
+    content?: {
+      parts?: Part[],
+    },
+  }[];
+}