api-docs

export interface DocEntry {
  id: string;
  title: string;
  category: string;
  provider: string;
  content: string;
  keywords: string[];
}

export const openAIDocs: DocEntry[] = [
  {
    id: "openai-chat-completions",
    title: "Chat Completions API",
    category: "chat",
    provider: "openai",
    keywords: ["chat", "completions", "messages", "gpt", "conversation", "chatgpt"],
    content: `# OpenAI Chat Completions API

## Endpoint
POST https://api.openai.com/v1/chat/completions

## Request Headers
- Authorization: Bearer YOUR_API_KEY
- Content-Type: application/json

## Request Body
\`\`\`json
{
  "model": "gpt-4o" | "gpt-4o-mini" | "o1" | "o1-mini" | "o3" | "o3-mini",
  "messages": [
    {
      "role": "system" | "user" | "assistant" | "tool" | "developer",
      "content": "string" | [{"type": "text", "text": "string"} | {"type": "image_url", "image_url": {"url": "string", "detail": "auto"|"low"|"high"}}],
      "name": "string (optional)"
    }
  ],
  "max_tokens": number,
  "temperature": number (0-2, default 1),
  "top_p": number (0-1, default 1),
  "n": number (1-128, default 1),
  "stream": boolean (default false),
  "stop": string | string[],
  "presence_penalty": number (-2 to 2),
  "frequency_penalty": number (-2 to 2),
  "logit_bias": {token_id: number},
  "user": "string (end-user identifier)",
  "response_format": {"type": "text" | "json_object" | "json_schema"},
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "string",
        "description": "string",
        "parameters": {JSON Schema object}
      }
    }
  ],
  "tool_choice": "none" | "auto" | "required" | {"type": "function", "function": {"name": "string"}},
  "parallel_tool_calls": boolean (default true),
  "seed": number (for deterministic output)
}
\`\`\`

## Response
\`\`\`json
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-4o-2024-05-13",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "string",
        "tool_calls": [
          {
            "id": "call_xxx",
            "type": "function",
            "function": {"name": "string", "arguments": "JSON string"}
          }
        ],
        "refusal": "string"
      },
      "finish_reason": "stop" | "length" | "tool_calls" | "content_filter"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 0}
  }
}
\`\`\`

## Streaming Response
When stream: true, Server-Sent Events (SSE) are returned:
\`\`\`
data: {"id":"...","choices":[{"delta":{"role":"assistant"},"index":0}]}
data: {"id":"...","choices":[{"delta":{"content":"Hello"},"index":0}]}
data: [DONE]
\`\`\`

## Role Details
- "system": Sets behavior/instructions (o1 models: use "developer" instead)
- "user": User messages
- "assistant": Model responses
- "tool": Tool call results (requires tool_call_id)
- "developer": Alternative to "system" for o1 models

## Tool Usage
When model calls a tool:
1. Model returns message with tool_calls array
2. You execute the tool
3. Send back message with role "tool", tool_call_id, and content (result)

## Common Models
- gpt-4o: Latest flagship, multimodal
- gpt-4o-mini: Faster, cheaper variant
- o1: Reasoning model (chain of thought)
- o1-mini: Smaller reasoning model
- o3: Advanced reasoning
- o3-mini: Smaller reasoning variant

## Python SDK Example
\`\`\`python
from openai import OpenAI

client = OpenAI(api_key="sk-...")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are helpful"},
        {"role": "user", "content": "Hello!"}
    ],
    temperature=0.7,
    max_tokens=1000
)

print(response.choices[0].message.content)
\`\`\`

## Node.js SDK Example
\`\`\`javascript
import OpenAI from "openai";

const client = new OpenAI({ apiKey: "sk-..." });

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are helpful" },
    { role: "user", content: "Hello!" }
  ],
  temperature: 0.7,
  max_tokens: 1000
});

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

## cURL Example
\`\`\`bash
curl https://api.openai.com/v1/chat/completions \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "temperature": 0.7
  }'
\`\`\``
  },
  {
    id: "openai-embeddings",
    title: "Embeddings API",
    category: "embeddings",
    provider: "openai",
    keywords: ["embeddings", "vector", "similarity", "semantic"],
    content: `# OpenAI Embeddings API

## Endpoint
POST https://api.openai.com/v1/embeddings

## Request
\`\`\`json
{
  "model": "text-embedding-3-small" | "text-embedding-3-large" | "text-embedding-ada-002",
  "input": "string" | ["string1", "string2"],
  "encoding_format": "float" | "base64",
  "dimensions": number (optional, for text-embedding-3 models),
  "user": "string"
}
\`\`\`

## Response
\`\`\`json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023064255, -0.009327292, ...]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {"prompt_tokens": 8, "total_tokens": 8}
}
\`\`\`

## Model Dimensions
- text-embedding-3-small: 1536 dimensions (default), can reduce
- text-embedding-3-large: 3072 dimensions (default), can reduce
- text-embedding-ada-002: 1536 dimensions (fixed)

## Python Example
\`\`\`python
from openai import OpenAI

client = OpenAI()

response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Your text here",
    dimensions=512  # optional dimensionality reduction
)

embedding = response.data[0].embedding
\`\`\`

## Use Cases
- Semantic search
- RAG (Retrieval Augmented Generation)
- Clustering
- Anomaly detection`
  },
  {
    id: "openai-functions",
    title: "Function Calling (Tools)",
    category: "tools",
    provider: "openai",
    keywords: ["function", "tools", "tool calling", "function calling"],
    content: `# OpenAI Function Calling

## Tool Definition Format
\`\`\`json
{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City name, e.g. San Francisco"
        },
        "unit": {
          "type": "string",
          "enum": ["celsius", "fahrenheit"],
          "default": "celsius"
        }
      },
      "required": ["location"]
    }
  }
}
\`\`\`

## Tool Choice Options
- "auto": Model decides whether to call tools
- "required": Model MUST call a tool
- "none": Model cannot call tools
- {"type": "function", "function": {"name": "specific_tool"}}: Force specific tool

## Handling Tool Calls
\`\`\`python
response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

# Check if model wants to call tools
if response.choices[0].message.tool_calls:
    for tool_call in response.choices[0].message.tool_calls:
        function_name = tool_call.function.name
        arguments = json.loads(tool_call.function.arguments)
        result = execute_function(function_name, arguments)
        
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": str(result)
        })
    
    # Get final response
    final = client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
        tools=tools
    )
\`\`\`

## Parallel Tool Calls
- Enabled by default (parallel_tool_calls: true)
- Model can call multiple tools in one response
- Set parallel_tool_calls: false to force sequential calls`
  },
  {
    id: "openai-structured-output",
    title: "Structured Output (JSON Mode)",
    category: "output",
    provider: "openai",
    keywords: ["json", "structured", "schema", "format"],
    content: `# OpenAI Structured Output

## JSON Mode (Basic)
\`\`\`json
{
  "response_format": {"type": "json_object"}
}
\`\`\`
- Must include "json" in system prompt
- Returns valid JSON but no schema enforcement

## JSON Schema Mode (Strict)
\`\`\`json
{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "math_response",
      "schema": {
        "type": "object",
        "properties": {
          "result": {"type": "number"}
        },
        "required": ["result"]
      },
      "strict": true
    }
  }
}
\`\`\`

## Python SDK with Pydantic
\`\`\`python
from pydantic import BaseModel
from openai import OpenAI

class Step(BaseModel):
    explanation: str
    output: str

class MathResponse(BaseModel):
    steps: list[Step]
    final_answer: str

client = OpenAI()
response = client.beta.chat.completions.parse(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Solve 2+2"}],
    response_format=MathResponse
)
parsed = response.choices[0].message.parsed
print(parsed.final_answer)
\`\`\``
  },
  {
    id: "openai-vision",
    title: "Vision / Image Input",
    category: "multimodal",
    provider: "openai",
    keywords: ["vision", "image", "picture", "photo", "multimodal"],
    content: `# OpenAI Vision (Image Input)

## Supported Models
- gpt-4o
- gpt-4o-mini
- gpt-4-turbo

## Image Input Format
\`\`\`json
{
  "role": "user",
  "content": [
    {"type": "text", "text": "What is in this image?"},
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.jpg",
        "detail": "auto" | "low" | "high"
      }
    }
  ]
}
\`\`\`

## Base64 Image
\`\`\`json
{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}
\`\`\`

## Detail Levels
- "auto": Model chooses (default)
- "low": 512x512, uses 85 tokens
- "high": Full resolution, more tokens

## Python Example
\`\`\`python
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Describe this image"},
                {
                    "type": "image_url",
                    "image_url": {"url": "https://example.com/image.jpg"}
                }
            ]
        }
    ]
)
\`\`\``
  },
  {
    id: "openai-rate-limits",
    title: "Rate Limits & Pricing",
    category: "limits",
    provider: "openai",
    keywords: ["rate limit", "pricing", "cost", "tokens", "limits"],
    content: `# OpenAI Rate Limits & Pricing

## Rate Limits
Measured in RPM (requests per minute) and TPM (tokens per minute).

### Tier 1 (Free)
- gpt-4o: 200 RPM, 40,000 TPM
- gpt-4o-mini: 200 RPM, 200,000 TPM
- text-embedding-3-small: 300 RPM, 1,000,000 TPM

### Higher Tiers
Increase with usage and billing history.

## Pricing (per 1M tokens)
- gpt-4o: Input $2.50, Output $10.00
- gpt-4o-mini: Input $0.15, Output $0.60
- o1: Input $15.00, Output $60.00
- o3-mini: Input $1.10, Output $4.40
- text-embedding-3-small: $0.02
- text-embedding-3-large: $0.13

## Error Codes
- 400: Bad Request (invalid params)
- 401: Unauthorized (bad API key)
- 429: Rate limit exceeded
- 500: Server error

## Handling 429 Errors
\`\`\`python
import time
from openai import OpenAI, RateLimitError

client = OpenAI()

for attempt in range(3):
    try:
        response = client.chat.completions.create(...)
        break
    except RateLimitError:
        time.sleep(2 ** attempt)  # Exponential backoff
\`\`\``
  }
];