README.md

---
title: API Bridge
emoji: 😻
colorFrom: red
colorTo: purple
sdk: docker
pinned: false
license: gpl-3.0
short_description: The Bridge of The API's
---

# GambitFlow Bridge API

Unified API gateway for all GambitFlow chess engines with Firebase analytics and caching.

## Features

- **Unified Endpoint**: Single API for all models (Nano, Core, Base)
- **Firebase Analytics**: Real-time tracking of moves and matches
- **Intelligent Caching**: 5-minute cache for repeated positions
- **Batch Predictions**: Process multiple positions in one request
- **Model Health Checks**: Monitor all engine statuses
- **No Rate Limiting**: Unrestricted access for all users

## Quick Start

### Basic Request

```bash
curl -X POST https://YOUR-SPACE.hf.space/predict \
  -H "Content-Type: application/json" \
  -d '{
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
    "model": "core",
    "depth": 5,
    "time_limit": 3000
  }'
```

### Response

```json
{
  "best_move": "e2e4",
  "evaluation": 0.25,
  "depth_searched": 5,
  "nodes_evaluated": 125000,
  "time_taken": 1500,
  "pv": ["e2e4", "e7e5", "Ng1f3"],
  "from_cache": false,
  "model": "core"
}
```

## Endpoints

### POST /predict
Get best move for a position

**Request Body:**
```json
{
  "fen": "string",        // Required: FEN notation
  "model": "core",        // Optional: nano|core|base (default: core)
  "depth": 5,             // Optional: 1-10 (default: 5)
  "time_limit": 3000,     // Optional: ms (default: 3000)
  "track_stats": true     // Optional: track in analytics (default: true)
}
```

### POST /batch
Batch predictions (max 10 positions)

**Request Body:**
```json
{
  "model": "core",
  "positions": [
    {
      "fen": "...",
      "depth": 5,
      "time_limit": 3000
    },
    // ... more positions
  ]
}
```

### POST /match/start
Track match start (increments match counter)

**Request Body:**
```json
{
  "model": "core"
}
```

### GET /stats
Get usage statistics

**Response:**
```json
{
  "total": {
    "moves": 15420,
    "matches": 532
  },
  "models": {
    "nano": {"moves": 4200, "matches": 150},
    "core": {"moves": 8500, "matches": 280},
    "base": {"moves": 2720, "matches": 102}
  },
  "last_updated": 1704724800
}
```

### GET /models
List all available models

### GET /health
Health check

## Configuration

### Environment Variables

Set these in your HuggingFace Space settings:

```bash
# Model Endpoints
NANO_ENDPOINT=https://gambitflow-nexus-nano-inference-api.hf.space
CORE_ENDPOINT=https://gambitflow-nexus-core-inference-api.hf.space
BASE_ENDPOINT=https://gambitflow-synapse-base-inference-api.hf.space

```

### Adding New Models

To add a new model:

1. **Deploy the model inference API** to HuggingFace Spaces

2. **Update `app.py`** - Add model configuration:

```python
MODELS = {
    'nano': {...},
    'core': {...},
    'base': {...},
    'new_model': {  # Add here
        'name': 'New-Model',
        'endpoint': 'https://your-new-model-api.hf.space',
        'timeout': 40
    }
}
```

3. **Set environment variable** (optional, if URL is dynamic):

```bash
NEW_MODEL_ENDPOINT=https://your-new-model-api.hf.space
```

Then update the endpoint loading:
```python
'new_model': {
    'name': 'New-Model',
    'endpoint': os.getenv('NEW_MODEL_ENDPOINT', 'https://fallback-url.hf.space'),
    'timeout': 40
}
```

4. **Update Firebase structure** - Initialize stats for new model in Firebase:

```json
{
  "stats": {
    "models": {
      "new_model": {
        "moves": 0,
        "matches": 0
      }
    }
  }
}
```

5. **Restart the Space** - Changes will take effect immediately

## Firebase Setup

### 1. Create Firebase Project
- Go to [Firebase Console](https://console.firebase.google.com/)
- Create new project
- Enable Realtime Database

### 2. Get Service Account
- Go to Project Settings → Service Accounts
- Generate new private key
- Copy JSON content

### 3. Configure Space
Add to HuggingFace Space secrets:

**FIREBASE_DATABASE_URL:**
```
https://YOUR-PROJECT.firebaseio.com
```

**FIREBASE_CREDENTIALS:**
```json
{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "firebase-adminsdk-xxxxx@your-project.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}
```

### 4. Database Rules
Set Realtime Database rules:

```json
{
  "rules": {
    "stats": {
      ".read": true,
      ".write": false
    }
  }
}
```

## Integration Examples

### Python

```python
import requests

API_URL = "https://YOUR-SPACE.hf.space"

# Single prediction
response = requests.post(f"{API_URL}/predict", json={
    "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
    "model": "core",
    "depth": 5
})
result = response.json()
print(f"Best move: {result['best_move']}")

# Get statistics
stats = requests.get(f"{API_URL}/stats").json()
print(f"Total moves: {stats['total']['moves']}")
```

### JavaScript

```javascript
const API_URL = "https://YOUR-SPACE.hf.space";

async function getBestMove(fen, model = 'core') {
  const response = await fetch(`${API_URL}/predict`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      fen: fen,
      model: model,
      depth: 5
    })
  });
  return await response.json();
}

// Usage
const result = await getBestMove('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1');
console.log(`Best move: ${result.best_move}`);
```

---

**GambitFlow Bridge API** - Unified gateway for chess AI engines