Update README.md

README.md

@@ -9,4 +9,325 @@ license: cc-by-nc-4.0
 short_description: The Bridge of The API's
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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}`);
+```
+
+### Lichess Bot Integration
+
+```python
+import berserk
+import requests
+
+API_URL = "https://YOUR-SPACE.hf.space"
+
+def get_engine_move(board_fen):
+    response = requests.post(f"{API_URL}/predict", json={
+        "fen": board_fen,
+        "model": "base",  # Use strongest model
+        "depth": 6,
+        "time_limit": 5000
+    })
+    return response.json()['best_move']
+
+# Use in Lichess bot
+client = berserk.Client(berserk.TokenSession(API_TOKEN))
+for event in client.bots.stream_incoming_events():
+    # ... handle game
+    move = get_engine_move(game.fen())
+    client.bots.make_move(game_id, move)
+```
+
+## Performance
+
+- **Cache Hit Rate**: ~40-50% for common positions
+- **Average Latency**: 2-5 seconds depending on model
+- **Throughput**: Unlimited (no rate limits)
+
+## Monitoring
+
+View real-time statistics:
+```bash
+curl https://YOUR-SPACE.hf.space/stats
+```
+
+## Support
+
+- **Space URL**: [Your HuggingFace Space](https://huggingface.co/spaces/GambitFlow/Bridge-API)
+- **Main Site**: [gambitflow.onrender.com](https://gambitflow.onrender.com)
+- **Issues**: GitHub Issues
+
+---
+
+**GambitFlow Bridge API** - Unified gateway for chess AI engines