skrypt-ai 0.5.0 → 0.6.0

package/dist/template/content/docs/integrations.md

@@ -0,0 +1,1158 @@
+---
+title: "Integrations"
+description: "Third-party integrations"
+---
+
+<CardGroup cols={2}>
+  <Card title="AnthropicClient" icon="cube" href="#anthropicclient">
+    Claude LLM client with retries
+  </Card>
+  <Card title="OpenAICompatibleClient" icon="cube" href="#openaicompatibleclient">
+    Universal OpenAI-compatible client
+  </Card>
+  <Card title="AnthropicClient.complete" icon="code" href="#anthropicclientcomplete">
+    Sends prompts to Claude models
+  </Card>
+  <Card title="OpenAICompatibleClient.complete" icon="code" href="#openaicompatibleclientcomplete">
+    Sends OpenAI chat completions
+  </Card>
+  <Card title="AnthropicClient.constructor" icon="code" href="#anthropicclientconstructor">
+    Creates Anthropic LLM client
+  </Card>
+  <Card title="OpenAICompatibleClient.constructor" icon="code" href="#openaicompatibleclientconstructor">
+    Creates OpenAI-compatible client
+  </Card>
+  <Card title="AnthropicClient.isConfigured" icon="code" href="#anthropicclientisconfigured">
+    Checks Anthropic client readiness
+  </Card>
+  <Card title="OpenAICompatibleClient.isConfigured" icon="code" href="#openaicompatibleclientisconfigured">
+    Checks OpenAI client readiness
+  </Card>
+</CardGroup>
+
+
+## `AnthropicClient`
+
+```typescript
+class AnthropicClient implements LLMClient
+```
+
+Use this to send prompts to Anthropic's Claude models and receive structured completions — with automatic retries built in.
+
+`AnthropicClient` wraps the Anthropic SDK and implements a common `LLMClient` interface, making it easy to swap between LLM providers without changing your application logic.
+
+## Constructor Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config.model` | `string` | Yes | The Claude model to use (e.g. `"claude-3-5-sonnet-20241022"`) |
+| `config.apiKey` | `string` | Yes | Your Anthropic API key |
+| `config.maxRetries` | `number` | No | Number of retry attempts on failure. Defaults to `3` |
+
+## Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `provider` | `'anthropic'` | Always `'anthropic'` — useful for provider-switching logic |
+
+## Methods
+
+### `complete(request: CompletionRequest): Promise<CompletionResponse>`
+
+Sends a completion request to Claude and returns the model's response.
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `request.messages` | `Array<{ role: 'user' \| 'assistant', content: string }>` | Yes | Conversation history to send |
+| `request.systemPrompt` | `string` | No | System-level instruction prepended to the conversation |
+| `request.maxTokens` | `number` | No | Maximum tokens in the response |
+
+**Returns:** A `CompletionResponse` containing:
+- `content` — the model's reply text
+- `usage` — token counts (`inputTokens`, `outputTokens`)
+- `model` — the model that generated the response
+
+### Example
+
+```typescript example.ts
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type LLMProvider = 'anthropic' | 'openai'
+
+type LLMClientConfig = {
+  model: string
+  apiKey: string
+  maxRetries?: number
+}
+
+type CompletionRequest = {
+  messages: Array<{ role: 'user' | 'assistant'; content: string }>
+  systemPrompt?: string
+  maxTokens?: number
+}
+
+type CompletionResponse = {
+  content: string
+  model: string
+  usage: { inputTokens: number; outputTokens: number }
+}
+
+// ── Simulated AnthropicClient (mirrors real implementation) ────────────────
+
+class AnthropicClient {
+  provider: LLMProvider = 'anthropic'
+  private model: string
+  private apiKey: string
+  private maxRetries: number
+
+  constructor(config: LLMClientConfig) {
+    this.model = config.model
+    this.apiKey = config.apiKey
+    this.maxRetries = config.maxRetries ?? 3
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const body = {
+      model: this.model,
+      max_tokens: request.maxTokens ?? 1024,
+      system: request.systemPrompt,
+      messages: request.messages,
+    }
+
+    let lastError: Error | undefined
+
+    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+      try {
+        const response = await fetch('https://api.anthropic.com/v1/messages', {
+          method: 'POST',
+          headers: {
+            'x-api-key': this.apiKey,
+            'anthropic-version': '2023-06-01',
+            'content-type': 'application/json',
+          },
+          body: JSON.stringify(body),
+        })
+
+        if (!response.ok) {
+          throw new Error(`Anthropic API error: ${response.status} ${response.statusText}`)
+        }
+
+        const data = await response.json() as {
+          content: Array<{ text: string }>
+          model: string
+          usage: { input_tokens: number; output_tokens: number }
+        }
+
+        return {
+          content: data.content[0].text,
+          model: data.model,
+          usage: {
+            inputTokens: data.usage.input_tokens,
+            outputTokens: data.usage.output_tokens,
+          },
+        }
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error))
+        if (attempt < this.maxRetries) {
+          console.warn(`Attempt ${attempt} failed, retrying...`)
+          await new Promise(resolve => setTimeout(resolve, 500 * attempt))
+        }
+      }
+    }
+
+    throw lastError
+  }
+}
+
+// ── Usage example ──────────────────────────────────────────────────────────
+
+const client = new AnthropicClient({
+  apiKey: process.env.ANTHROPIC_API_KEY || 'your-anthropic-api-key',
+  model: 'claude-3-5-sonnet-20241022',
+  maxRetries: 3,
+})
+
+async function main() {
+  try {
+    const response = await client.complete({
+      systemPrompt: 'You are a concise assistant. Reply in one sentence.',
+      messages: [
+        { role: 'user', content: 'What is the capital of Japan?' },
+      ],
+      maxTokens: 100,
+    })
+
+    console.log('Provider: ', client.provider)
+    console.log('Model:    ', response.model)
+    console.log('Reply:    ', response.content)
+    console.log('Tokens:   ', response.usage)
+    // Expected output:
+    // Provider:  anthropic
+    // Model:     claude-3-5-sonnet-20241022
+    // Reply:     The capital of Japan is Tokyo.
+    // Tokens:    { inputTokens: 28, outputTokens: 10 }
+  } catch (error) {
+    console.error('Completion failed after all retries:', error)
+  }
+}
+
+main()
+```
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="AnthropicClient.constructor" icon="link" href="#anthropicclientconstructor">
+    Uses
+  </Card>
+</CardGroup>
+
+---
+
+
+## `OpenAICompatibleClient`
+
+```typescript
+class OpenAICompatibleClient implements LLMClient
+```
+
+Use this to connect to any OpenAI-compatible LLM provider — including OpenAI, DeepSeek, Ollama, OpenRouter, and Google Gemini — through a single unified client interface.
+
+`OpenAICompatibleClient` normalizes provider differences (base URLs, auth headers, retry logic) so you can swap providers without changing your application code.
+
+## Constructor Config
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `provider` | `LLMProvider` | ✅ | Provider identifier (e.g. `'openai'`, `'deepseek'`, `'ollama'`, `'openrouter'`, `'gemini'`) |
+| `model` | `string` | ✅ | Model name to use (e.g. `'gpt-4o'`, `'deepseek-chat'`, `'llama3'`) |
+| `apiKey` | `string` | ✅ | API key for the provider (use `'ollama'` or any placeholder for local providers) |
+| `maxRetries` | `number` | ❌ | Number of retry attempts on failure. Defaults to `3` |
+
+## Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| `provider` | `LLMProvider` | The configured provider for this client instance |
+
+## Methods
+
+### `complete(request: CompletionRequest): Promise<CompletionResponse>`
+
+Sends a completion request to the configured provider and returns the model's response.
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `request.messages` | `Message[]` | ✅ | Array of `{ role: 'system' \| 'user' \| 'assistant', content: string }` |
+| `request.temperature` | `number` | ❌ | Sampling temperature (0–2). Lower = more deterministic |
+| `request.maxTokens` | `number` | ❌ | Maximum tokens in the response |
+
+**Returns:** `Promise<CompletionResponse>` — resolves with `{ content: string, usage?: { promptTokens, completionTokens, totalTokens } }`
+
+## Supported Providers
+
+| Provider | `provider` value | Notes |
+|----------|-----------------|-------|
+| OpenAI | `'openai'` | Requires OpenAI API key |
+| DeepSeek | `'deepseek'` | Requires DeepSeek API key |
+| Ollama | `'ollama'` | Local — no API key needed |
+| OpenRouter | `'openrouter'` | Routes to many models |
+| Google Gemini | `'gemini'` | Requires Google API key |
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="OpenAICompatibleClient.constructor" icon="link" href="#openaicompatibleclientconstructor">
+    Uses
+  </Card>
+</CardGroup>
+
+---
+
+
+## `AnthropicClient.complete`
+
+```typescript
+async complete(request: CompletionRequest): Promise<CompletionResponse>
+```
+
+Use this to send a conversation to Anthropic's Claude models and receive a completion response, handling system prompts and multi-turn conversations automatically.
+
+This method separates system messages from conversation messages internally, so you can pass a unified message array without pre-processing. It wraps Anthropic's SDK and returns a normalized `CompletionResponse` regardless of which Claude model you target.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `request` | `CompletionRequest` | Yes | The completion request object containing messages, model, and generation settings |
+| `request.messages` | `Message[]` | Yes | Array of messages with `role` (`"system"`, `"user"`, `"assistant"`) and `content` string |
+| `request.model` | `string` | No | Claude model ID (e.g. `"claude-3-5-sonnet-20241022"`). Falls back to the client's default model if omitted |
+| `request.maxTokens` | `number` | No | Maximum tokens to generate in the response |
+| `request.temperature` | `number` | No | Sampling temperature between `0` and `1`. Lower = more deterministic |
+| `request.stopSequences` | `string[]` | No | Sequences that will halt generation when encountered |
+
+## Returns
+
+Returns a `Promise<CompletionResponse>` that resolves with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `content` | `string` | The generated text from Claude |
+| `model` | `string` | The model ID that produced the response |
+| `usage.inputTokens` | `number` | Number of tokens in the prompt |
+| `usage.outputTokens` | `number` | Number of tokens in the completion |
+| `stopReason` | `string` | Why generation stopped (e.g. `"end_turn"`, `"max_tokens"`) |
+
+Rejects with an error if the API key is invalid, the model ID is unrecognized, or the request exceeds context limits.
+
+### Example
+
+```typescript example.ts
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type MessageRole = 'system' | 'user' | 'assistant'
+
+interface Message {
+  role: MessageRole
+  content: string
+}
+
+interface CompletionRequest {
+  messages: Message[]
+  model?: string
+  maxTokens?: number
+  temperature?: number
+  stopSequences?: string[]
+}
+
+interface CompletionResponse {
+  content: string
+  model: string
+  usage: {
+    inputTokens: number
+    outputTokens: number
+  }
+  stopReason: string
+}
+
+// ── Simulated AnthropicClient.complete implementation ──────────────────────
+
+class AnthropicClient {
+  private model: string
+  private apiKey: string
+
+  constructor(config: { apiKey: string; model?: string }) {
+    this.apiKey = config.apiKey
+    this.model = config.model || 'claude-3-5-sonnet-20241022'
+  }
+
+  isConfigured(): boolean {
+    return true
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const model = request.model || this.model
+
+    // Separate system message from conversation (mirrors real implementation)
+    const systemMessage = request.messages.find(m => m.role === 'system')
+    const conversationMessages = request.messages.filter(m => m.role !== 'system')
+
+    // Build the Anthropic API payload
+    const payload = {
+      model,
+      max_tokens: request.maxTokens ?? 1024,
+      temperature: request.temperature ?? 0.7,
+      ...(systemMessage && { system: systemMessage.content }),
+      messages: conversationMessages.map(m => ({
+        role: m.role,
+        content: m.content,
+      })),
+      ...(request.stopSequences && { stop_sequences: request.stopSequences }),
+    }
+
+    const response = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'x-api-key': this.apiKey,
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(payload),
+    })
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}))
+      throw new Error(
+        `Anthropic API error ${response.status}: ${(error as any).error?.message ?? response.statusText}`
+      )
+    }
+
+    const data = await response.json() as any
+
+    return {
+      content: data.content[0]?.text ?? '',
+      model: data.model,
+      usage: {
+        inputTokens: data.usage.input_tokens,
+        outputTokens: data.usage.output_tokens,
+      },
+      stopReason: data.stop_reason,
+    }
+  }
+}
+
+// ── Usage example ──────────────────────────────────────────────────────────
+
+const client = new AnthropicClient({
+  apiKey: process.env.ANTHROPIC_API_KEY || 'your-anthropic-api-key',
+  model: 'claude-3-5-sonnet-20241022',
+})
+
+async function main() {
+  try {
+    const response = await client.complete({
+      messages: [
+        {
+          role: 'system',
+          content: 'You are a concise assistant. Reply in one sentence.',
+        },
+        {
+          role: 'user',
+          content: 'What is the capital of Japan?',
+        },
+      ],
+      maxTokens: 256,
+      temperature: 0.3,
+    })
+
+    console.log('Reply:      ', response.content)
+    console.log('Model:      ', response.model)
+    console.log('Stop reason:', response.stopReason)
+    console.log('Tokens used:', response.usage)
+
+    // Expected output:
+    // Reply:       The capital of Japan is Tokyo.
+    // Model:       claude-3-5-sonnet-20241022
+    // Stop reason: end_turn
+    // Tokens used: { inputTokens: 32, outputTokens: 9 }
+  } catch (error) {
+    console.error('Completion failed:', error instanceof Error ? error.message : error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="AnthropicClient.isConfigured" icon="link" href="#anthropicclientisconfigured">
+    Uses
+  </Card>
+  <Card title="OpenAICompatibleClient.isConfigured" icon="link" href="#openaicompatibleclientisconfigured">
+    Uses
+  </Card>
+  <Card title="AnthropicClient.isConfigured" icon="link" href="#anthropicclientisconfigured">
+    Used by
+  </Card>
+  <Card title="OpenAICompatibleClient.isConfigured" icon="link" href="#openaicompatibleclientisconfigured">
+    Used by
+  </Card>
+  <Card title="AnthropicClient" icon="link" href="#anthropicclient">
+    Related
+  </Card>
+  <Card title="OpenAICompatibleClient" icon="link" href="#openaicompatibleclient">
+    Related
+  </Card>
+</CardGroup>
+
+---
+
+
+## `OpenAICompatibleClient.complete`
+
+```typescript
+async complete(request: CompletionRequest): Promise<CompletionResponse>
+```
+
+Use this to send a chat completion request to any OpenAI-compatible API endpoint (OpenAI, Azure, Groq, Together AI, etc.) and receive a structured response with the generated text and token usage.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `request` | `CompletionRequest` | Yes | The completion request object containing messages, model, and generation settings |
+| `request.messages` | `Array<{role: string, content: string}>` | Yes | Conversation history as an array of role/content message objects |
+| `request.model` | `string` | No | Model identifier to use (e.g. `"gpt-4o"`, `"llama-3-8b"`). Falls back to the client's default model if omitted |
+| `request.temperature` | `number` | No | Sampling temperature between 0–2. Lower = more deterministic, higher = more creative |
+| `request.maxTokens` | `number` | No | Maximum number of tokens to generate in the response |
+| `request.systemPrompt` | `string` | No | System-level instruction prepended to the conversation |
+
+## Returns
+
+Returns a `Promise<CompletionResponse>` that resolves with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `content` | `string` | The generated text from the model |
+| `model` | `string` | The model that was actually used to generate the response |
+| `usage.promptTokens` | `number` | Number of tokens consumed by the input messages |
+| `usage.completionTokens` | `number` | Number of tokens in the generated response |
+| `usage.totalTokens` | `number` | Total tokens used (prompt + completion) |
+
+Throws an error if the API request fails, the model is unavailable, or the API key is invalid.
+
+### Example
+
+```typescript example.ts
+import OpenAI from 'openai'
+
+// --- Inline types (do not import from library) ---
+interface Message {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+interface CompletionRequest {
+  messages: Message[]
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  systemPrompt?: string
+}
+
+interface CompletionResponse {
+  content: string
+  model: string
+  usage: {
+    promptTokens: number
+    completionTokens: number
+    totalTokens: number
+  }
+}
+
+// --- Inline OpenAI-compatible client implementation ---
+class OpenAICompatibleClient {
+  private client: OpenAI
+  private model: string
+
+  constructor(config: { apiKey: string; baseURL?: string; defaultModel?: string }) {
+    this.client = new OpenAI({
+      apiKey: config.apiKey,
+      baseURL: config.baseURL,
+    })
+    this.model = config.defaultModel || 'gpt-4o-mini'
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    const model = request.model || this.model
+
+    const messages: Message[] = []
+
+    if (request.systemPrompt) {
+      messages.push({ role: 'system', content: request.systemPrompt })
+    }
+
+    messages.push(...request.messages)
+
+    const response = await this.client.chat.completions.create({
+      model,
+      messages,
+      temperature: request.temperature ?? 0.7,
+      max_tokens: request.maxTokens,
+    })
+
+    const choice = response.choices[0]
+
+    return {
+      content: choice.message.content ?? '',
+      model: response.model,
+      usage: {
+        promptTokens: response.usage?.prompt_tokens ?? 0,
+        completionTokens: response.usage?.completion_tokens ?? 0,
+        totalTokens: response.usage?.total_tokens ?? 0,
+      },
+    }
+  }
+}
+
+// --- Usage example ---
+const client = new OpenAICompatibleClient({
+  apiKey: process.env.OPENAI_API_KEY || 'sk-your-api-key-here',
+  defaultModel: 'gpt-4o-mini',
+  // Swap baseURL to use Groq, Together AI, etc.:
+  // baseURL: 'https://api.groq.com/openai/v1'
+})
+
+async function main() {
+  try {
+    const response = await client.complete({
+      systemPrompt: 'You are a concise assistant. Reply in one sentence.',
+      messages: [
+        { role: 'user', content: 'What is the capital of Japan?' },
+      ],
+      temperature: 0.3,
+      maxTokens: 60,
+    })
+
+    console.log('Generated text:', response.content)
+    // Output: "The capital of Japan is Tokyo."
+
+    console.log('Model used:', response.model)
+    // Output: "gpt-4o-mini"
+
+    console.log('Token usage:', response.usage)
+    // Output: { promptTokens: 28, completionTokens: 10, totalTokens: 38 }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('Completion failed:', error.message)
+      // Common causes: invalid API key, unknown model name, rate limit exceeded
+    }
+  }
+}
+
+main()
+```
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="AnthropicClient.isConfigured" icon="link" href="#anthropicclientisconfigured">
+    Uses
+  </Card>
+  <Card title="OpenAICompatibleClient.isConfigured" icon="link" href="#openaicompatibleclientisconfigured">
+    Uses
+  </Card>
+  <Card title="AnthropicClient.isConfigured" icon="link" href="#anthropicclientisconfigured">
+    Used by
+  </Card>
+  <Card title="OpenAICompatibleClient.isConfigured" icon="link" href="#openaicompatibleclientisconfigured">
+    Used by
+  </Card>
+  <Card title="AnthropicClient" icon="link" href="#anthropicclient">
+    Related
+  </Card>
+  <Card title="OpenAICompatibleClient" icon="link" href="#openaicompatibleclient">
+    Related
+  </Card>
+</CardGroup>
+
+---
+
+
+## `AnthropicClient.constructor`
+
+```typescript
+constructor(config: LLMClientConfig)
+```
+
+Use this to create an Anthropic-backed LLM client that handles retries and model configuration for sending completion requests.
+
+The `AnthropicClient` constructor initializes a client instance configured with your Anthropic API key, target model, and retry behavior. It wraps the Anthropic SDK to provide a consistent interface for making LLM calls.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config.apiKey` | `string` | Yes | Your Anthropic API key used to authenticate requests |
+| `config.model` | `string` | Yes | The Anthropic model to use (e.g., `claude-3-5-sonnet-20241022`) |
+| `config.maxRetries` | `number` | No | Number of times to retry failed requests. Defaults to `3` |
+
+### Returns
+
+Returns an `AnthropicClient` instance with:
+- `provider` — always `'anthropic'`
+- Access to completion methods for sending prompts to the configured model
+
+### When to use
+
+- You need a reusable client scoped to a specific Anthropic model
+- You want automatic retry logic on transient API failures
+- You are building a multi-provider LLM system and need an Anthropic-compatible implementation
+
+### Example
+
+```typescript example.ts
+// Inline type definitions (do not import from autodocs)
+type LLMProvider = 'anthropic' | 'openai'
+
+interface LLMClientConfig {
+  apiKey: string
+  model: string
+  maxRetries?: number
+}
+
+interface CompletionRequest {
+  prompt: string
+  maxTokens?: number
+}
+
+interface CompletionResponse {
+  text: string
+  usage?: { inputTokens: number; outputTokens: number }
+}
+
+// Simulated AnthropicClient (mirrors the real implementation)
+class AnthropicClient {
+  provider: LLMProvider = 'anthropic'
+  private model: string
+  private maxRetries: number
+  private apiKey: string
+
+  constructor(config: LLMClientConfig) {
+    if (!config.apiKey) throw new Error('apiKey is required')
+    if (!config.model) throw new Error('model is required')
+
+    this.apiKey = config.apiKey
+    this.model = config.model
+    this.maxRetries = config.maxRetries ?? 3
+  }
+
+  // Simulated completion method
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    console.log(`[${this.provider}] Sending request to model: ${this.model}`)
+    console.log(`[${this.provider}] Max retries configured: ${this.maxRetries}`)
+    console.log(`[${this.provider}] Prompt: "${request.prompt}"`)
+
+    // Simulated response (real client would call Anthropic API here)
+    return {
+      text: `Simulated response from ${this.model}`,
+      usage: { inputTokens: 12, outputTokens: 8 },
+    }
+  }
+}
+
+// --- Usage Example ---
+
+async function main() {
+  try {
+    // Initialize the client with your Anthropic credentials
+    const client = new AnthropicClient({
+      apiKey: process.env.ANTHROPIC_API_KEY || 'sk-ant-your-api-key-here',
+      model: 'claude-3-5-sonnet-20241022',
+      maxRetries: 5, // optional, defaults to 3
+    })
+
+    console.log('Provider:', client.provider)
+    // Output: Provider: anthropic
+
+    const response = await client.complete({
+      prompt: 'Explain recursion in one sentence.',
+      maxTokens: 100,
+    })
+
+    console.log('Response:', response.text)
+    // Output: Response: Simulated response from claude-3-5-sonnet-20241022
+
+    console.log('Token usage:', response.usage)
+    // Output: Token usage: { inputTokens: 12, outputTokens: 8 }
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('Failed to initialize AnthropicClient:', error.message)
+    }
+  }
+}
+
+main()
+```
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="PluginManager" icon="link" href="/docs/core#pluginmanager">
+    Uses
+  </Card>
+  <Card title="AnthropicClient" icon="link" href="#anthropicclient">
+    Used by
+  </Card>
+  <Card title="OpenAICompatibleClient" icon="link" href="#openaicompatibleclient">
+    Used by
+  </Card>
+  <Card title="PluginManager" icon="link" href="/docs/core#pluginmanager">
+    Used by
+  </Card>
+  <Card title="AnthropicClient" icon="link" href="#anthropicclient">
+    Related
+  </Card>
+  <Card title="OpenAICompatibleClient" icon="link" href="#openaicompatibleclient">
+    Related
+  </Card>
+</CardGroup>
+
+---
+
+
+## `OpenAICompatibleClient.constructor`
+
+```typescript
+constructor(config: LLMClientConfig)
+```
+
+Use this to create an LLM client that connects to any OpenAI-compatible API provider (OpenAI, Azure, Anthropic, local models, etc.) with automatic retry logic and provider-specific configuration.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `LLMClientConfig` | ✅ | Configuration object for the LLM client |
+| `config.provider` | `LLMProvider` | ✅ | The LLM provider identifier (e.g., `'openai'`, `'anthropic'`, `'azure'`) |
+| `config.model` | `string` | ✅ | The model name to use for completions (e.g., `'gpt-4o'`, `'claude-3-5-sonnet'`) |
+| `config.apiKey` | `string` | ✅ | API key for authenticating with the provider |
+| `config.baseUrl` | `string` | ❌ | Override the default base URL for the provider. Useful for local models or custom endpoints |
+| `config.maxRetries` | `number` | ❌ | Number of times to retry failed requests. Defaults to `3` |
+
+## Returns
+
+An `OpenAICompatibleClient` instance with:
+- `provider` — the resolved provider set on the instance
+- `complete()` — method to send completion requests
+- Automatic retry handling on transient failures
+
+## Notes
+
+- If `baseUrl` is omitted, the client falls back to a built-in map of known provider URLs (`PROVIDER_BASE_URLS`)
+- `maxRetries` defaults to `3` if not specified
+- The underlying HTTP client is an `OpenAI` SDK instance, making this compatible with any API that follows the OpenAI REST spec
+
+### Example
+
+```typescript example.ts
+// ── Inline types (no external imports needed) ──────────────────────────────
+
+type LLMProvider = 'openai' | 'anthropic' | 'azure' | 'ollama' | string
+
+interface LLMClientConfig {
+  provider: LLMProvider
+  model: string
+  apiKey: string
+  baseUrl?: string
+  maxRetries?: number
+}
+
+interface CompletionRequest {
+  messages: { role: 'system' | 'user' | 'assistant'; content: string }[]
+  temperature?: number
+  maxTokens?: number
+}
+
+interface CompletionResponse {
+  content: string
+  usage?: { promptTokens: number; completionTokens: number }
+}
+
+// ── Provider default URLs (mirrors PROVIDER_BASE_URLS) ─────────────────────
+
+const PROVIDER_BASE_URLS: Record<string, string> = {
+  openai: 'https://api.openai.com/v1',
+  anthropic: 'https://api.anthropic.com/v1',
+  ollama: 'http://localhost:11434/v1',
+}
+
+// ── Simulated OpenAICompatibleClient ──────────────────────────────────────
+
+class OpenAICompatibleClient {
+  provider: LLMProvider
+  private model: string
+  private maxRetries: number
+  private baseUrl: string
+  private apiKey: string
+
+  constructor(config: LLMClientConfig) {
+    this.provider = config.provider
+    this.model = config.model
+    this.maxRetries = config.maxRetries ?? 3
+    this.apiKey = config.apiKey
+    this.baseUrl = config.baseUrl || PROVIDER_BASE_URLS[config.provider] || ''
+
+    console.log(`[OpenAICompatibleClient] Initialized`)
+    console.log(`  Provider : ${this.provider}`)
+    console.log(`  Model    : ${this.model}`)
+    console.log(`  Base URL : ${this.baseUrl}`)
+    console.log(`  Retries  : ${this.maxRetries}`)
+  }
+
+  async complete(request: CompletionRequest): Promise<CompletionResponse> {
+    // Simulated response — replace with real OpenAI SDK call in production
+    const lastMessage = request.messages.at(-1)?.content ?? ''
+    return {
+      content: `[Simulated response to: "${lastMessage}"]`,
+      usage: { promptTokens: 12, completionTokens: 20 },
+    }
+  }
+}
+
+// ── Example 1: Standard OpenAI setup ──────────────────────────────────────
+
+async function main() {
+  try {
+    const client = new OpenAICompatibleClient({
+      provider: 'openai',
+      model: 'gpt-4o',
+      apiKey: process.env.OPENAI_API_KEY || 'sk-your-api-key-here',
+      maxRetries: 3,
+    })
+
+    const response = await client.complete({
+      messages: [
+        { role: 'system', content: 'You are a helpful assistant.' },
+        { role: 'user', content: 'What is the capital of France?' },
+      ],
+      temperature: 0.7,
+    })
+
+    console.log('\n[Response]', response.content)
+    console.log('[Usage]', response.usage)
+    // Output: [Response] [Simulated response to: "What is the capital of France?"]
+    // Output: [Usage]    { promptTokens: 12, completionTokens: 20 }
+
+    // ── Example 2: Local Ollama model with custom base URL ─────────────────
+
+    const localClient = new OpenAICompatibleClient({
+      provider: 'ollama',
+      model: 'llama3.2',
+      apiKey: 'ollama', // Ollama doesn't require a real key
+      baseUrl: 'http://localhost:11434/v1', // explicit override
+      maxRetries: 1,
+    })
+
+    console.log('\n[Local provider]', localClient.provider)
+    // Output: [Local provider] ollama
+
+  } catch (error) {
+    console.error('Failed to initialize or call client:', error)
+  }
+}
+
+main()
+```
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="PluginManager" icon="link" href="/docs/core#pluginmanager">
+    Uses
+  </Card>
+  <Card title="AnthropicClient" icon="link" href="#anthropicclient">
+    Used by
+  </Card>
+  <Card title="OpenAICompatibleClient" icon="link" href="#openaicompatibleclient">
+    Used by
+  </Card>
+  <Card title="PluginManager" icon="link" href="/docs/core#pluginmanager">
+    Used by
+  </Card>
+  <Card title="AnthropicClient" icon="link" href="#anthropicclient">
+    Related
+  </Card>
+  <Card title="OpenAICompatibleClient" icon="link" href="#openaicompatibleclient">
+    Related
+  </Card>
+</CardGroup>
+
+---
+
+
+## `AnthropicClient.isConfigured`
+
+```typescript
+isConfigured(): boolean
+```
+
+Use this to verify that an `AnthropicClient` instance is ready to make API calls before attempting completions.
+
+This method acts as a readiness check — it confirms the client has been initialized and the underlying Anthropic SDK has taken responsibility for credential validation. Call it as a guard before executing requests in conditional flows or health checks.
+
+**Returns**
+
+| Value | Condition |
+|-------|-----------|
+| `true` | Always — the client is initialized and the Anthropic SDK handles API key validation internally |
+
+> **Note:** A `true` return does **not** guarantee the API key is valid or that the network is reachable. It confirms the client object is properly constructed. Actual credential errors surface when calling `complete()`.
+
+### Example
+
+```typescript example.ts
+// Inline types to simulate AnthropicClient behavior
+interface LLMClientConfig {
+  apiKey: string
+  model?: string
+  timeout?: number
+  maxRetries?: number
+}
+
+// Simulated AnthropicClient class (self-contained, no external imports)
+class AnthropicClient {
+  private apiKey: string
+  private model: string
+  private timeout: number
+  private maxRetries: number
+
+  constructor(config: LLMClientConfig) {
+    this.apiKey = config.apiKey
+    this.model = config.model ?? 'claude-3-5-sonnet-20241022'
+    this.timeout = config.timeout ?? 60000
+    this.maxRetries = config.maxRetries ?? 2
+  }
+
+  isConfigured(): boolean {
+    return true // Anthropic SDK handles validation
+  }
+}
+
+// --- Usage Example ---
+
+const client = new AnthropicClient({
+  apiKey: process.env.ANTHROPIC_API_KEY || 'sk-ant-your-api-key-here',
+  model: 'claude-3-5-sonnet-20241022',
+  timeout: 30000,
+})
+
+async function runCompletion() {
+  try {
+    // Guard against unconfigured clients before making requests
+    if (!client.isConfigured()) {
+      throw new Error('AnthropicClient is not configured. Check your API key and settings.')
+    }
+
+    console.log('Client configured:', client.isConfigured())
+    // Output: Client configured: true
+
+    console.log('Proceeding with API request...')
+    // In real usage, you would call client.complete({ prompt: '...' }) here
+
+  } catch (error) {
+    console.error('Client setup error:', error instanceof Error ? error.message : error)
+  }
+}
+
+runCompletion()
+```
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="AnthropicClient.complete" icon="link" href="#anthropicclientcomplete">
+    Uses
+  </Card>
+  <Card title="OpenAICompatibleClient.complete" icon="link" href="#openaicompatibleclientcomplete">
+    Uses
+  </Card>
+  <Card title="AnthropicClient.complete" icon="link" href="#anthropicclientcomplete">
+    Used by
+  </Card>
+  <Card title="OpenAICompatibleClient.complete" icon="link" href="#openaicompatibleclientcomplete">
+    Used by
+  </Card>
+  <Card title="AnthropicClient" icon="link" href="#anthropicclient">
+    Related
+  </Card>
+  <Card title="OpenAICompatibleClient" icon="link" href="#openaicompatibleclient">
+    Related
+  </Card>
+</CardGroup>
+
+---
+
+
+## `OpenAICompatibleClient.isConfigured`
+
+```typescript
+isConfigured(): boolean
+```
+
+Use this to verify that an `OpenAICompatibleClient` instance is ready to make API calls before attempting completions.
+
+This method acts as a readiness check — it always returns `true` because the underlying OpenAI SDK handles API key validation and configuration errors at request time rather than at initialization. Use it in guard clauses or health checks to conform to a standard client interface without worrying about pre-flight validation logic.
+
+### Returns
+
+| Condition | Value |
+|-----------|-------|
+| Always | `true` — the OpenAI SDK manages its own configuration validation |
+
+### Parameters
+
+None.
+
+### Example
+
+```typescript example.ts
+// Inline the minimal interface and class needed to demonstrate isConfigured()
+interface LLMClientConfig {
+  apiKey: string
+  model?: string
+  baseURL?: string
+  maxRetries?: number
+}
+
+// Simulated OpenAICompatibleClient with isConfigured behavior
+class OpenAICompatibleClient {
+  private apiKey: string
+  private model: string
+  private baseURL?: string
+  private maxRetries: number
+
+  constructor(config: LLMClientConfig) {
+    this.apiKey = config.apiKey
+    this.model = config.model || 'gpt-4o'
+    this.baseURL = config.baseURL
+    this.maxRetries = config.maxRetries ?? 3
+  }
+
+  // Always returns true — OpenAI SDK handles validation internally
+  isConfigured(): boolean {
+    return true
+  }
+}
+
+// --- Usage Example ---
+
+const client = new OpenAICompatibleClient({
+  apiKey: process.env.OPENAI_API_KEY || 'sk-your-api-key-here',
+  model: 'gpt-4o',
+  maxRetries: 2
+})
+
+try {
+  // Guard clause: check before attempting any completions
+  if (!client.isConfigured()) {
+    throw new Error('LLM client is not configured — cannot proceed.')
+  }
+
+  console.log('Client configured:', client.isConfigured())
+  // Output: Client configured: true
+
+  console.log('Proceeding to make completion requests...')
+  // Output: Proceeding to make completion requests...
+} catch (error) {
+  console.error('Configuration check failed:', error)
+}
+```
+
+### Related
+
+<CardGroup cols={3}>
+  <Card title="AnthropicClient.complete" icon="link" href="#anthropicclientcomplete">
+    Uses
+  </Card>
+  <Card title="OpenAICompatibleClient.complete" icon="link" href="#openaicompatibleclientcomplete">
+    Uses
+  </Card>
+  <Card title="AnthropicClient.complete" icon="link" href="#anthropicclientcomplete">
+    Used by
+  </Card>
+  <Card title="OpenAICompatibleClient.complete" icon="link" href="#openaicompatibleclientcomplete">
+    Used by
+  </Card>
+  <Card title="AnthropicClient" icon="link" href="#anthropicclient">
+    Related
+  </Card>
+  <Card title="OpenAICompatibleClient" icon="link" href="#openaicompatibleclient">
+    Related
+  </Card>
+</CardGroup>
+
+---
+