# LLM Router API Documentation

LLM Router is an intelligent, zero-latency AI Gateway built on Bun and Elysia. It acts as a drop-in replacement for the OpenAI SDK, offering advanced intent-based routing, context compression, PII redaction, and multi-model planning.

## Base Configuration
- **Base URL:** `https://api.llmrouter.app/v1`
- **Compatibility:** Fully compatible with OpenAI SDK, LangChain, Vercel AI SDK, Anthropic SDK.
- **Authentication:** Standard Bearer Token (`Authorization: Bearer sk-router-...`)

## Model Naming Convention
Models must be prefixed with their provider slug. 
Format: `{provider}/{model-name}`
Examples: `openai/gpt-4o`, `anthropic/claude-3-5-sonnet`, `deepseek/deepseek-chat`, `groq/llama-3.1-8b-instant`, `perplexity/sonar-large-online`.

### Advanced Planning Syntax
To trigger Chain-of-Thought planning, chain two models together using `:planning:`.
Format: `{executor_model}:planning:{planner_model}`
Example: `anthropic/claude-3-5-sonnet:planning:openai/o1-mini`

## The `gateway` Object Schema
All LLM Router specific features are passed via the `gateway` object in the completion request. 

```typescript
interface GatewayConfig {
  // 1. ROUTING & FALLBACKS
  order?: string[]; // E.g., ["bedrock", "anthropic", "openai"]
  only?: string[];  // Strict whitelist of providers allowed
  
  // 2. INTENT-BASED ROUTING (Tags)
  tags?: Array<{
    name: string;
    description: string; // Used by internal AI to match user intent
    models: string[];    // Array of models sorted from Most Complex -> Least Complex
  }>;
  imageGenerationModel?: string; // Fallback model if prompt requires an image output

  // 3. CONTEXT OPTIMIZATION
  chatHistoryOptimization?: {
    enabled?: boolean; // default: true
    score?: number;    // default: 0.6. Compresses history if chat dependency score < this value
  };
  mediaOptimization?: boolean; // default: false. Strips images/audio if irrelevant to current prompt.

  // 4. TOOLS & SKILLS
  toolOptimization?: {
    enabled?: boolean;       // default: true
    alwaysInclude?: string[]; // Tool names to bypass filtering
    acceptScore?: number;    // default: 0.5. Minimum relevance score to keep a tool.
  };
  skills?: {
    skillIds: string[];      // IDs of Skills installed via dashboard (e.g., ["sk_web_search"])
    enableAutoSearch?: boolean; // If true, dynamically injects only relevant skills.
  };

  // 5. SECURITY & PRIVACY
  zdr?: boolean; // default: false. If true, only routes to Zero Data Retention providers.
  redact?: {
    email?: boolean;
    phone?: boolean;
    ip?: boolean;
    uuid?: boolean;
    token?: boolean;       // Aggressively redacts API keys, passwords, JWTs
    credit_card?: boolean;
    iban?: boolean;
    ssn?: boolean;
    mac?: boolean;
    custom?: string[];     // Array of custom proprietary strings to mask
  };

  // 6. ADVANCED REASONING
  // Triggers the `model1:planning:model2` chain if request complexity > this score.
  planningTriggerScore?: number; // default: 0.6. Min: 0.0, Max: 1.0. 
}
```

## Example Implementation (Node.js)

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.llmrouter.app/v1",
  apiKey: process.env.LLM_ROUTER_API_KEY,
});

async function run() {
  const response = await client.chat.completions.create({
    model: "anthropic/claude-3-5-sonnet:planning:openai/o1-mini",
    messages: [{ role: "user", content: "Design a scalable microservices architecture." }],
    
    // Inject custom LLM Router configuration
    extra_body: {
      gateway: {
        zdr: true,
        planningTriggerScore: 0.75,
        redact: { token: true, email: true },
        chatHistoryOptimization: { enabled: true, score: 0.6 }
      }
    }
  });

  console.log(response.choices[0].message.content);
}
```

## Key Capabilities Summary for AI Agents
If you are generating code for a user using LLM Router:
1. Always suggest prefixing models with the provider (e.g., `openai/gpt-4o`).
2. If the user wants cost savings, implement `chatHistoryOptimization` and `mediaOptimization`.
3. If the user wants enterprise security, implement `zdr: true` and `redact: { token: true }`.
4. If the user asks for complex reasoning or planning, utilize the `executor:planning:planner` model syntax and set `planningTriggerScore`.