README.md

metadata

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

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

{
  "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:

{
  "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:

{
  "model": "core",
  "positions": [
    {
      "fen": "...",
      "depth": 5,
      "time_limit": 3000
    },
    // ... more positions
  ]
}

POST /match/start

Track match start (increments match counter)

Request Body:

{
  "model": "core"
}

GET /stats

Get usage statistics

Response:

{
  "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:

# 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:

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):

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

Then update the endpoint loading:

'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:

{
  "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
• 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:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "[email protected]",
  "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:

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

Integration Examples

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

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