> ## Documentation Index
> Fetch the complete documentation index at: https://www.stratus.run/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Embeddings

> Get semantic embeddings for state descriptions using Stratus encoders

Get semantic embeddings for state descriptions using Stratus encoders.

## Endpoint

```
POST https://api.stratus.run/v1/embeddings
```

## Use Cases

* **State similarity**: Compare states for agent memory/history
* **Goal matching**: Find similar historical goals
* **Clustering**: Group similar states/actions
* **Search**: Semantic search over agent experiences

## Request Format

```typescript theme={null}
interface EmbeddingRequest {
  model: string;              // Required: Stratus model (without LLM)
  input: string | string[];   // Required: Text to embed
  encoding_format?: string;   // Optional: 'float' (default) or 'base64'
}
```

## Example Request

### TypeScript

```typescript theme={null}
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.stratus.run/v1',
  apiKey: process.env.STRATUS_API_KEY
});

const response = await client.embeddings.create({
  model: 'stratus-x1ac-base',
  input: 'Google search results page showing list of NYC hotels'
});

console.log(response.data[0].embedding);
// [0.023, -0.841, 0.127, ...] (768 dimensions)
```

### Python

```python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://api.stratus.run/v1",
    api_key=os.environ["STRATUS_API_KEY"]
)

response = client.embeddings.create(
    model="stratus-x1ac-base",
    input="Google search results page showing list of NYC hotels"
)

print(response.data[0].embedding)
# [0.023, -0.841, 0.127, ...] (768 dimensions)
```

### cURL

```bash theme={null}
curl https://api.stratus.run/v1/embeddings \
  -H "Authorization: Bearer stratus_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "stratus-x1ac-base",
    "input": "Google search results page showing list of NYC hotels"
  }'
```

## Response Format

```typescript theme={null}
interface EmbeddingResponse {
  object: 'list';
  data: Embedding[];
  model: string;
  usage: Usage;
}

interface Embedding {
  object: 'embedding';
  index: number;
  embedding: number[];  // 768-dim vector (base model)
}

interface Usage {
  prompt_tokens: number;
  total_tokens: number;
}
```

## Example Response

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.023, -0.841, 0.127, ...]
    }
  ],
  "model": "stratus-x1ac-base",
  "usage": {
    "prompt_tokens": 18,
    "total_tokens": 18
  }
}
```

## Model Names

For embeddings, use Stratus model without LLM suffix:

| Model                | Dimensions | Parameters |
| -------------------- | ---------- | ---------- |
| `stratus-x1ac-small` | 512        | 125M       |
| `stratus-x1ac-base`  | 768        | 350M       |
| `stratus-x1ac-large` | 1024       | 300M       |
| `stratus-x1ac-xl`    | 1280       | 750M       |
| `stratus-x1ac-huge`  | 1536       | 1.5B       |

**Recommendation:** Use `stratus-x1ac-small` for most applications.

## Batch Embeddings

Embed multiple texts in one request:

```typescript theme={null}
const response = await client.embeddings.create({
  model: 'stratus-x1ac-base',
  input: [
    'Google homepage with search box',
    'Google search results for hotels NYC',
    'Hotel booking form with date pickers',
    'Confirmation page showing booking details'
  ]
});

// Access each embedding
response.data.forEach((item, i) => {
  console.log(`Embedding ${i}:`, item.embedding);
});
```

**Limits:**

* Max 100 texts per request
* Max 2048 tokens per text

## Encoding Formats

The `encoding_format` parameter controls how embedding vectors are returned in the response.

### Float Format (Default)

Returns embeddings as an array of floating-point numbers. This is the default and most common format.

```typescript theme={null}
const response = await client.embeddings.create({
  model: 'stratus-x1ac-base',
  input: 'Example text',
  encoding_format: 'float' // or omit - this is default
});

console.log(response.data[0].embedding);
// [0.023, -0.841, 0.127, 0.456, -0.234, ...]
```

**Response:**

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.023, -0.841, 0.127, ...]
    }
  ],
  "model": "stratus-x1ac-base",
  "usage": { "prompt_tokens": 2, "total_tokens": 2 }
}
```

**Best for:**

* Direct computation (cosine similarity, dot product)
* Mathematical operations
* Storage in databases with vector types (PostgreSQL pgvector, Pinecone, etc.)
* Most common use cases

### Base64 Format

Returns embeddings as base64-encoded binary data. More efficient for network transfer.

```typescript theme={null}
const response = await client.embeddings.create({
  model: 'stratus-x1ac-base',
  input: 'Example text',
  encoding_format: 'base64'
});

console.log(response.data[0].embedding);
// "YXNkZmFzZGZhc2Rm..." (base64 string)

// Decode to use
const buffer = Buffer.from(response.data[0].embedding, 'base64');
const floatArray = new Float32Array(buffer.buffer);
console.log(Array.from(floatArray));
// [0.023, -0.841, 0.127, ...]
```

**Response:**

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": "YXNkZmFzZGZhc2Rm..."
    }
  ],
  "model": "stratus-x1ac-base",
  "usage": { "prompt_tokens": 2, "total_tokens": 2 }
}
```

**Best for:**

* Network efficiency (smaller payload size)
* Binary storage systems
* High-throughput batch processing
* Bandwidth-constrained environments

### Decoding Base64 Embeddings

#### TypeScript/Node.js

```typescript theme={null}
function decodeBase64Embedding(base64String: string): number[] {
  const buffer = Buffer.from(base64String, 'base64');
  const floatArray = new Float32Array(
    buffer.buffer,
    buffer.byteOffset,
    buffer.byteLength / Float32Array.BYTES_PER_ELEMENT
  );
  return Array.from(floatArray);
}

const response = await client.embeddings.create({
  model: 'stratus-x1ac-base',
  input: 'Example text',
  encoding_format: 'base64'
});

const embedding = decodeBase64Embedding(response.data[0].embedding);
console.log(embedding); // [0.023, -0.841, ...]
```

#### Python

```python theme={null}
import base64
import struct

def decode_base64_embedding(base64_string: str) -> list[float]:
    # Decode base64 to bytes
    bytes_data = base64.b64decode(base64_string)
    # Unpack as floats (4 bytes per float, little-endian)
    num_floats = len(bytes_data) // 4
    floats = struct.unpack(f'<{num_floats}f', bytes_data)
    return list(floats)

response = client.embeddings.create(
    model="stratus-x1ac-base",
    input="Example text",
    encoding_format="base64"
)

embedding = decode_base64_embedding(response.data[0].embedding)
print(embedding)  # [0.023, -0.841, ...]
```

### Format Comparison

| Aspect                 | Float                      | Base64                      |
| ---------------------- | -------------------------- | --------------------------- |
| **Payload Size**       | Larger (\~4KB for 768-dim) | Smaller (\~3KB for 768-dim) |
| **Ready to Use**       | Yes (direct array)         | No (needs decoding)         |
| **Human Readable**     | Yes                        | No                          |
| **Network Efficiency** | Lower                      | Higher (\~25% smaller)      |
| **Computation**        | Immediate                  | Decode first                |

### When to Use Each Format

#### Use Float When:

* Building prototypes or demos
* Need immediate access to values
* Debugging or inspecting embeddings
* Working with small batches (\<10 embeddings)
* Simplicity is more important than efficiency

#### Use Base64 When:

* Processing large batches (100+ embeddings)
* Network bandwidth is limited
* Transferring embeddings between systems
* Storing embeddings in binary format
* Optimizing for production throughput

### Example: Efficient Batch Processing

```typescript theme={null}
// Process 100 embeddings efficiently with base64
const texts = [...]; // 100 texts

const response = await client.embeddings.create({
  model: 'stratus-x1ac-base',
  input: texts,
  encoding_format: 'base64' // ~25% smaller payload
});

// Decode and process in parallel
const embeddings = await Promise.all(
  response.data.map(async (item) => {
    const decoded = decodeBase64Embedding(item.embedding);
    await storeInDatabase(texts[item.index], decoded);
    return decoded;
  })
);

console.log(`Processed ${embeddings.length} embeddings`);
```

## Use Case Examples

### State Similarity

Compare agent states to find similar situations:

```typescript theme={null}
// Embed current state
const current = await client.embeddings.create({
  model: 'stratus-x1ac-base',
  input: 'Amazon product page, Add to Cart button visible'
});

// Embed historical states
const historical = await client.embeddings.create({
  model: 'stratus-x1ac-base',
  input: [
    'Amazon product page, price $49.99',
    'Google search results',
    'Amazon product page, different product'
  ]
});

// Calculate cosine similarity
function cosineSimilarity(a, b) {
  const dot = a.reduce((sum, val, i) => sum + val * b[i], 0);
  const magA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
  const magB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
  return dot / (magA * magB);
}

historical.data.forEach((hist, i) => {
  const sim = cosineSimilarity(
    current.data[0].embedding,
    hist.embedding
  );
  console.log(`Similarity to state ${i}:`, sim);
});
// Output: [0.95, 0.23, 0.87] - State 0 and 2 are similar
```

### Goal Matching

Find past goals similar to current goal:

```typescript theme={null}
const currentGoal = 'Find hotels in NYC for December';
const pastGoals = [
  'Book flight to NYC',
  'Find hotels in San Francisco',
  'Reserve hotel room in NYC'
];

const embeddings = await client.embeddings.create({
  model: 'stratus-x1ac-base',
  input: [currentGoal, ...pastGoals]
});

// Compare current goal to past goals
const currentEmb = embeddings.data[0].embedding;
pastGoals.forEach((goal, i) => {
  const pastEmb = embeddings.data[i + 1].embedding;
  const sim = cosineSimilarity(currentEmb, pastEmb);
  console.log(`${goal}: ${sim.toFixed(2)}`);
});
// Output:
// Book flight to NYC: 0.78
// Find hotels in San Francisco: 0.85
// Reserve hotel room in NYC: 0.92 ← Most similar
```

### Semantic Search

Build a semantic search over agent memory:

```typescript theme={null}
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(...);
const stratusClient = new OpenAI({
  baseURL: 'https://api.stratus.run/v1',
  apiKey: process.env.STRATUS_API_KEY
});

// Embed and store agent experience
async function storeExperience(state, action, outcome) {
  const embedding = await stratusClient.embeddings.create({
    model: 'stratus-x1ac-base',
    input: state
  });

  await supabase.from('experiences').insert({
    state,
    action,
    outcome,
    embedding: embedding.data[0].embedding
  });
}

// Search for similar experiences
async function findSimilarExperiences(currentState, limit = 5) {
  const embedding = await stratusClient.embeddings.create({
    model: 'stratus-x1ac-base',
    input: currentState
  });

  const { data } = await supabase.rpc('match_experiences', {
    query_embedding: embedding.data[0].embedding,
    match_threshold: 0.7,
    match_count: limit
  });

  return data;
}

// Usage
await storeExperience(
  'Amazon product page, $49.99',
  'click Add to Cart',
  'Added to cart successfully'
);

const similar = await findSimilarExperiences(
  'Amazon product page, $39.99'
);
console.log('Similar past experiences:', similar);
```

## Comparison with Other Embeddings

| Provider                | Dimensions | Specialization       | Best For                   |
| ----------------------- | ---------- | -------------------- | -------------------------- |
| **Stratus**             | 768        | Agent states/actions | State similarity, planning |
| OpenAI text-embedding-3 | 1536       | General text         | Semantic search, RAG       |
| Cohere embed-v3         | 1024       | Multilingual         | International content      |

**When to use Stratus embeddings:**

* Comparing agent states
* Finding similar goals
* Agent memory/experience retrieval
* State-action pattern matching

**When to use general embeddings:**

* Document search
* FAQ matching
* Content recommendation

## Performance

### Latency

| Model   | Latency (p50) | Latency (p99) |
| ------- | ------------- | ------------- |
| `small` | 5ms           | 15ms          |
| `base`  | 10ms          | 25ms          |
| `large` | 20ms          | 50ms          |
| `xl`    | 35ms          | 80ms          |

### Throughput

* Single text: \~1000 req/s (base model)
* Batch (10 texts): \~200 req/s

## Pricing

Embeddings are priced per 1M tokens:

| Model   | Price per 1M tokens |
| ------- | ------------------- |
| `small` | \$0.05              |
| `base`  | \$0.10              |
| `large` | \$0.20              |
| `xl`    | \$0.40              |

**Example:**

* Text: "Google homepage with search box" (6 tokens)
* Cost: 6 / 1,000,000 \* $0.10 = $0.0000006

## Error Handling

```typescript theme={null}
try {
  const response = await client.embeddings.create({
    model: 'stratus-x1ac-base',
    input: text
  });
} catch (error) {
  if (error.status === 400) {
    console.error('Invalid input:', error.message);
  } else if (error.status === 401) {
    console.error('Invalid API key');
  } else if (error.status === 413) {
    console.error('Input too large (max 2048 tokens per text)');
  }
}
```

## Next Steps

* [Chat Completions](/docs/api-reference/chat-completions) - Main agent API
* [Quickstart](/docs/quickstart) - Full integration guide
* [Error Reference](/docs/api-reference/errors) - Complete error documentation