SDK Reference

Why Use the SDK

Since the SIMOSphere AI API is fully OpenAI-compatible, you can use the official OpenAI SDKs by simply changing the base URL. The dedicated @simosphere/sdk adds value on top:

• Preconfigured base URL — no manual URL overrides; the SDK always points to the correct SIMOSphere AI gateway.
• Exponential backoff — automatic retries with jitter for transient errors (429, 500, 502, 503).
• Usage tracking — per-request token counters available as typed response fields.
• Streaming helpers — async iterators for TypeScript and generators for Python that handle SSE parsing.
• Type safety — full TypeScript definitions and Python dataclass models for all request/response shapes.

TypeScript SDK

Installation

npm install @simosphere/sdk
# or
pnpm add @simosphere/sdk
# or
yarn add @simosphere/sdk

Basic Usage

import { SIMOSphere } from "@simosphere/sdk";

const client = new SIMOSphere({
  apiKey: process.env.SIMOSPHERE_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "mistral-small-latest",
  messages: [
    { role: "system", content: "You are a GDPR compliance advisor." },
    { role: "user", content: "Summarize Article 17 (Right to Erasure)." },
  ],
  temperature: 0.3,
  max_tokens: 1024,
});

console.log(completion.choices[0].message.content);
console.log("Tokens used:", completion.usage.total_tokens);

Streaming

The SDK provides an async iterable for streaming responses. Each chunk is typed and includes delta content as well as optional finish reasons:

const stream = await client.chat.completions.create({
  model: "mistral-small-latest",
  messages: [{ role: "user", content: "Write a haiku about sovereignty." }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0]?.delta?.content;
  if (delta) process.stdout.write(delta);
}
console.log(); // newline after streaming completes

Error Handling

The SDK throws typed errors that you can catch and inspect. All errors include the HTTP status code, a machine-readable error type, and a human-readable message:

import { SIMOSphere, APIError, RateLimitError } from "@simosphere/sdk";

try {
  const result = await client.chat.completions.create({ ... });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log("Rate limited. Retry after:", error.retryAfter);
  } else if (error instanceof APIError) {
    console.log("API error:", error.status, error.message);
  }
}

Python SDK

Installation

pip install simosphere
# or with uv
uv add simosphere

Synchronous Client

from simosphere import SIMOSphere

client = SIMOSphere(api_key="sk_live_YOUR_API_KEY")

response = client.chat.completions.create(
    model="mistral-small-latest",
    messages=[
        {"role": "system", "content": "You are a data privacy expert."},
        {"role": "user", "content": "What is a DPIA?"},
    ],
    temperature=0.5,
    max_tokens=512,
)

print(response.choices[0].message.content)
print(f"Total tokens: {response.usage.total_tokens}")

Async Client

For asyncio-based applications, the SDK provides an async client with the same interface. All methods return awaitables:

import asyncio
from simosphere import AsyncSIMOSphere

async def main():
    client = AsyncSIMOSphere(api_key="sk_live_YOUR_API_KEY")

    response = await client.chat.completions.create(
        model="mistral-small-latest",
        messages=[{"role": "user", "content": "Explain EU AI Act."}],
    )
    print(response.choices[0].message.content)

asyncio.run(main())

Streaming (Python)

stream = client.chat.completions.create(
    model="mistral-small-latest",
    messages=[{"role": "user", "content": "List 5 benefits of data sovereignty."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)
print()  # newline after streaming completes

Configuration Reference

Both SDKs accept the following configuration options at initialization. All options except the API key have sensible defaults and can be omitted for standard usage:

Using the OpenAI SDK

If you prefer to use the official OpenAI SDK directly, you only need to change two configuration values. The SIMOSphere AI API is fully compatible with the OpenAI request and response format, so all features including streaming, function calling, and tool use work without modification:

// TypeScript — using the official OpenAI SDK
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.SIMOSPHERE_API_KEY,  // your SIMOSphere key
  baseURL: "https://api.simosphereai.com/v1",  // point to SIMOSphere
});

// Everything else works exactly the same
const result = await client.chat.completions.create({
  model: "mistral-small-latest",
  messages: [{ role: "user", content: "Hello from the OpenAI SDK!" }],
});

# Python — using the official OpenAI SDK
from openai import OpenAI

client = OpenAI(
    api_key="sk_live_YOUR_API_KEY",
    base_url="https://api.simosphereai.com/v1",
)

response = client.chat.completions.create(
    model="mistral-small-latest",
    messages=[{"role": "user", "content": "Hello from the OpenAI SDK!"}],
)
print(response.choices[0].message.content)