README.md

---
title: FFEmbeds
emoji: 😻
colorFrom: red
colorTo: blue
sdk: gradio
sdk_version: 5.49.1
license: apache-2.0
short_description: Qwen 4b Embeddings for Games
---
# 😻 FF Embeddings API

**Powered by Qwen3-Embedding-4B** - Advanced 4B-parameter multilingual embedding model with matryoshka truncation


## 🚀 Quick Start

### Python

```python
import requests
import numpy as np

url = "https://YOUR_USERNAME-fairfate-embeddings.hf.space/api/predict"

# Generate embeddings
texts = [
    "Storm King's Thunder - Epic D&D 5E giant-themed adventure",
    "Curse of Strahd - Gothic horror campaign in Ravenloft"
]

response = requests.post(
    url,
    json={
        "data": [texts, True, 1536],  # [texts, use_instruction, dimensions]
        "fn_index": 0
    }
)

result = response.json()
embeddings = np.array(result["data"][0])

# Calculate similarity
def cosine_similarity(a, b):
    return np.dot(a, b)  # Already normalized

similarity = cosine_similarity(embeddings[0], embeddings[1])
print(f"Similarity: {similarity:.3f}")  # ~0.65 (related but different)
```

### TypeScript/JavaScript

```typescript
interface EmbeddingResponse {
  data: number[][][];
}

async function getEmbeddings(
  texts: string[],
  useInstruction: boolean = true,
  dimensions: number = 1536
): Promise<number[][]> {
  const response = await fetch(
    'https://YOUR_USERNAME-fairfate-embeddings.hf.space/api/predict',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        data: [texts, useInstruction, dimensions],
        fn_index: 0
      })
    }
  );

  const result: EmbeddingResponse = await response.json();
  return result.data[0];
}

// Usage
const embeddings = await getEmbeddings([
  "Pathfinder 2E Core Rulebook",
  "D&D 5E Player's Handbook"
]);

// Calculate cosine similarity (already normalized)
function cosineSimilarity(a: number[], b: number[]): number {
  return a.reduce((sum, val, i) => sum + val * b[i], 0);
}

const similarity = cosineSimilarity(embeddings[0], embeddings[1]);
console.log(`Similarity: ${similarity.toFixed(3)}`); // ~0.78 (both RPG rulebooks)
```

### cURL

```bash
curl -X POST \
  https://YOUR_USERNAME-fairfate-embeddings.hf.space/api/predict \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      ["Cyberpunk detective noir campaign for Shadowrun"],
      true,
      1536
    ],
    "fn_index": 0
  }'
```

## 📖 API Reference

### Endpoint

```
POST /api/predict
```

### Request Format

```json
{
  "data": [
    ["text1", "text2", ...],  // Array of texts to embed
    true,                      // use_instruction (boolean)
    1536                       // output_dimensions (32-3584, production: 1536)
  ],
  "fn_index": 0
}
```

### Response Format

```json
{
  "data": [
    [
      [0.123, -0.456, 0.789, ...],  // First embedding (1536 dims)
      [-0.234, 0.567, -0.890, ...]  // Second embedding (1536 dims)
    ]
  ]
}
```

### Parameters

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| `texts` | string[] | required | - | Texts to embed |
| `use_instruction` | boolean | true | - | Add instruction prefix (recommended) |
| `output_dimensions` | number | 1536 | 32-2560 | Output embedding size (production: 1536) |