README.md

---
title: OpenAI to Gemini Adapter
emoji: 🔄☁️
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---

# OpenAI to Gemini Adapter

This service provides an OpenAI-compatible API that translates requests to Google's Vertex AI Gemini models, allowing you to use Gemini models with tools expecting an OpenAI interface.

## Features

-   OpenAI-compatible API endpoints (`/v1/chat/completions`, `/v1/models`).
-   Supports Google Cloud credentials via `GOOGLE_CREDENTIALS_JSON` secret (recommended for Spaces) or local file methods.
-   Supports credential rotation when using local files.
-   Handles streaming and non-streaming responses.
-   Configured for easy deployment on Hugging Face Spaces using Docker (port 7860) or locally via Docker Compose (port 8050).

## Hugging Face Spaces Deployment (Recommended)

This application is ready for deployment on Hugging Face Spaces using Docker.

1.  **Create a new Space:** Go to Hugging Face Spaces and create a new Space, choosing "Docker" as the Space SDK.
2.  **Upload Files:** Upload the `app/` directory, `Dockerfile`, and `app/requirements.txt` to your Space repository. You can do this via the web interface or using Git.
3.  **Configure Secrets:** In your Space settings, navigate to the **Secrets** section and add the following secrets:
    *   `API_KEY`: Your desired API key for authenticating requests to this adapter service. If not set, it defaults to `123456`.
    *   `GOOGLE_CREDENTIALS_JSON`: The **entire content** of your Google Cloud service account JSON key file. Copy and paste the JSON content directly into the secret value field. **This is the required method for providing credentials on Hugging Face.**
4.  **Deployment:** Hugging Face will automatically build and deploy the Docker container. The application will run on port 7860 as defined in the `Dockerfile` and this README's metadata.

Your adapter service will be available at the URL provided by your Hugging Face Space (e.g., `https://your-user-name-your-space-name.hf.space`).

## Local Docker Setup (for Development/Testing)

### Prerequisites

-   Docker and Docker Compose
-   Google Cloud service account credentials with Vertex AI access

### Credential Setup (Local Docker)

1.  Create a `credentials` directory in the project root:
    ```bash
    mkdir -p credentials
    ```
2.  Add your service account JSON files to the `credentials` directory:
    ```bash
    # Example with multiple credential files
    cp /path/to/your/service-account1.json credentials/service-account1.json
    cp /path/to/your/service-account2.json credentials/service-account2.json
    ```
    The service will automatically detect and rotate through all `.json` files in this directory if the `GOOGLE_CREDENTIALS_JSON` environment variable is *not* set.
3.  Alternatively, set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable *in your local environment or `docker-compose.yml`* to the *path* of a single credential file (used as a fallback if the other methods fail).

### Running Locally

Start the service using Docker Compose:

```bash
docker-compose up -d
```

The service will be available at `http://localhost:8050` (as defined in `docker-compose.yml`).

## API Usage

The service implements OpenAI-compatible endpoints:

-   `GET /v1/models` - List available models
-   `POST /v1/chat/completions` - Create a chat completion
-   `GET /health` - Health check endpoint (includes credential status)

All endpoints require authentication using an API key in the Authorization header.

### Authentication

The service requires an API key for authentication.

To authenticate, include the API key in the `Authorization` header using the `Bearer` token format:

```
Authorization: Bearer YOUR_API_KEY
```

Replace `YOUR_API_KEY` with the key you configured (either via the `API_KEY` secret/environment variable or the default `123456`).

### Example Requests

*(Replace `YOUR_ADAPTER_URL` with your Hugging Face Space URL or `http://localhost:8050` if running locally)*

#### Basic Request

```bash
curl -X POST YOUR_ADAPTER_URL/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gemini-1.5-pro",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello, how are you?"}
    ],
    "temperature": 0.7
  }'
```

#### Grounded Search Request

```bash
curl -X POST YOUR_ADAPTER_URL/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gemini-2.5-pro-exp-03-25-search",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant with access to the latest information."},
      {"role": "user", "content": "What are the latest developments in quantum computing?"}
    ],
    "temperature": 0.2
  }'
```

### Supported Models

The API supports the following Vertex AI Gemini models:

| Model ID                       | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| `gemini-2.5-pro-exp-03-25`     | Gemini 2.5 Pro Experimental (March 25)         |
| `gemini-2.5-pro-exp-03-25-search` | Gemini 2.5 Pro with Google Search grounding |
| `gemini-2.0-flash`             | Gemini 2.0 Flash                             |
| `gemini-2.0-flash-search`      | Gemini 2.0 Flash with Google Search grounding |
| `gemini-2.0-flash-lite`        | Gemini 2.0 Flash Lite                          |
| `gemini-2.0-flash-lite-search` | Gemini 2.0 Flash Lite with Google Search grounding |
| `gemini-2.0-pro-exp-02-05`     | Gemini 2.0 Pro Experimental (February 5)      |
| `gemini-1.5-flash`             | Gemini 1.5 Flash                             |
| `gemini-1.5-flash-8b`          | Gemini 1.5 Flash 8B                          |
| `gemini-1.5-pro`             | Gemini 1.5 Pro                               |
| `gemini-1.0-pro-002`           | Gemini 1.0 Pro                               |
| `gemini-1.0-pro-vision-001`    | Gemini 1.0 Pro Vision                        |
| `gemini-embedding-exp`         | Gemini Embedding Experimental                |

Models with the `-search` suffix enable grounding with Google Search using dynamic retrieval.

### Supported Parameters

The API supports common OpenAI-compatible parameters, mapping them to Vertex AI where possible:

| OpenAI Parameter    | Vertex AI Parameter | Description                                       |
| ------------------- | --------------------- | ------------------------------------------------- |
| `temperature`       | `temperature`         | Controls randomness (0.0 to 1.0)                  |
| `max_tokens`        | `max_output_tokens`   | Maximum number of tokens to generate              |
| `top_p`             | `top_p`               | Nucleus sampling parameter (0.0 to 1.0)           |
| `top_k`             | `top_k`               | Top-k sampling parameter                          |
| `stop`              | `stop_sequences`      | List of strings that stop generation when encountered |
| `presence_penalty`  | `presence_penalty`    | Penalizes repeated tokens                         |
| `frequency_penalty` | `frequency_penalty`   | Penalizes frequent tokens                         |
| `seed`              | `seed`                | Random seed for deterministic generation          |
| `logprobs`          | `logprobs`            | Number of log probabilities to return           |
| `n`                 | `candidate_count`     | Number of completions to generate               |

## Credential Handling Priority

The application loads Google Cloud credentials in the following order:

1.  **`GOOGLE_CREDENTIALS_JSON` Environment Variable / Secret:** Checks for the JSON *content* directly in this variable (Required for Hugging Face).
2.  **`credentials/` Directory (Local Only):** Looks for `.json` files in the directory specified by `CREDENTIALS_DIR` (Default: `/app/credentials` inside the container). Rotates through found files. Used if `GOOGLE_CREDENTIALS_JSON` is not set.
3.  **`GOOGLE_APPLICATION_CREDENTIALS` Environment Variable (Local Only):** Checks for a *file path* specified by this variable. Used as a fallback if the above methods fail.

## Environment Variables / Secrets

-   `API_KEY`: API key for authentication (Default: `123456`). **Required as Secret on Hugging Face.**
-   `GOOGLE_CREDENTIALS_JSON`: **(Required Secret on Hugging Face)** The full JSON content of your service account key. Takes priority over other methods.
-   `CREDENTIALS_DIR` (Local Only): Directory containing credential files (Default: `/app/credentials` in the container). Used if `GOOGLE_CREDENTIALS_JSON` is not set.
-   `GOOGLE_APPLICATION_CREDENTIALS` (Local Only): Path to a *specific* credential file. Used as a fallback if the above methods fail.
-   `PORT`: Not needed for `CMD` config (uses 7860). Hugging Face provides this automatically, `docker-compose.yml` maps 8050 locally.

## Health Check

You can check the status of the service using the health endpoint:

```bash
curl YOUR_ADAPTER_URL/health -H "Authorization: Bearer YOUR_API_KEY"
```

This returns information about the credential status:

```json
{
  "status": "ok",
  "credentials": {
    "available": 1, // Example: 1 if loaded via JSON secret, or count if loaded from files
    "files": [], // Lists files only if using CREDENTIALS_DIR method
    "current_index": 0
  }
}
```

## License

This project is licensed under the MIT License.