skrypt-ai 0.7.0 → 0.8.0

package/dist/template/src/app/docs/llm/anthropic-client.md

@@ -1,549 +0,0 @@
-# Anthropic-client.ts
-
-## Classes
-
-### `AnthropicClient`
-
-```typescript
-class AnthropicClient implements LLMClient
-```
-
-Use this to send completion requests to Anthropic's Claude models with automatic retry logic and a standardized LLM interface.
-
-`AnthropicClient` wraps the Anthropic SDK and implements the `LLMClient` interface, giving you a consistent way to interact with Claude models alongside other LLM providers in your application.
-
-## Constructor Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `config.model` | `string` | Yes | The Claude model to use (e.g. `"claude-3-5-sonnet-20241022"`) |
-| `config.maxRetries` | `number` | No | Number of times to retry failed requests. Defaults to `3` |
-| `config.apiKey` | `string` | No | Anthropic API key. Falls back to `ANTHROPIC_API_KEY` environment variable |
-
-## Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `provider` | `'anthropic'` | Always `'anthropic'` — use this to identify the active LLM provider at runtime |
-
-## Returns
-
-- **`complete(request)`** — Returns a `Promise<CompletionResponse>` containing the model's reply, token usage, and finish reason
-- **`provider`** — Static string `'anthropic'` identifying this client's backend
-
-## When to Use
-
-- You need Claude-specific capabilities (long context, vision, tool use) behind a shared `LLMClient` interface
-- You want automatic retries without writing retry logic yourself
-- You're building a multi-provider system and need to swap LLM backends without changing call sites
-
-**Example:**
-
-```typescript example.ts
-// ─── Inline types (no imports from autodocs) ───────────────────────────────
-
-type LLMProvider = 'anthropic' | 'openai' | 'gemini'
-
-interface LLMClientConfig {
-  model: string
-  maxRetries?: number
-  apiKey?: string
-}
-
-interface CompletionRequest {
-  messages: Array<{ role: 'user' | 'assistant'; content: string }>
-  systemPrompt?: string
-  maxTokens?: number
-  temperature?: number
-}
-
-interface CompletionResponse {
-  content: string
-  usage: { inputTokens: number; outputTokens: number }
-  finishReason: 'stop' | 'max_tokens' | 'error'
-}
-
-interface LLMClient {
-  provider: LLMProvider
-  complete(request: CompletionRequest): Promise<CompletionResponse>
-}
-
-// ─── Simulated AnthropicClient (mirrors real implementation behavior) ────────
-
-class AnthropicClient implements LLMClient {
-  provider: LLMProvider = 'anthropic'
-  private model: string
-  private maxRetries: number
-  private apiKey: string
-
-  constructor(config: LLMClientConfig) {
-    this.model = config.model
-    this.maxRetries = config.maxRetries ?? 3
-    this.apiKey = config.apiKey || process.env.ANTHROPIC_API_KEY || 'your-anthropic-api-key'
-
-    if (!this.apiKey) {
-      throw new Error('Anthropic API key is required. Set ANTHROPIC_API_KEY or pass config.apiKey.')
-    }
-  }
-
-  async complete(request: CompletionRequest): Promise<CompletionResponse> {
-    // In production this calls the Anthropic SDK with retry logic.
-    // Here we simulate a successful response for demonstration.
-    console.log(`[AnthropicClient] Model: ${this.model}`)
-    console.log(`[AnthropicClient] Max retries: ${this.maxRetries}`)
-    console.log(`[AnthropicClient] Sending ${request.messages.length} message(s)...`)
-
-    if (request.systemPrompt) {
-      console.log(`[AnthropicClient] System prompt: "${request.systemPrompt}"`)
-    }
-
-    // Simulated response — real client returns Claude's actual reply
-    return {
-      content: 'TypeScript is a statically typed superset of JavaScript that compiles to plain JS.',
-      usage: { inputTokens: 24, outputTokens: 18 },
-      finishReason: 'stop',
-    }
-  }
-}
-
-// ─── Usage ───────────────────────────────────────────────────────────────────
-
-async function main() {
-  try {
-    const client = new AnthropicClient({
-      model: 'claude-3-5-sonnet-20241022',
-      maxRetries: 3,
-      apiKey: process.env.ANTHROPIC_API_KEY || 'sk-ant-your-key-here',
-    })
-
-    console.log('Provider:', client.provider) // Output: Provider: anthropic
-
-    const response = await client.complete({
-      systemPrompt: 'You are a concise technical assistant.',
-      messages: [
-        { role: 'user', content: 'What is TypeScript in one sentence?' },
-      ],
-      maxTokens: 256,
-      temperature: 0.3,
-    })
-
-    console.log('\n── Response ──────────────────────────────')
-    console.log('Content:      ', response.content)
-    console.log('Finish reason:', response.finishReason)
-    console.log('Tokens used:  ', response.usage)
-    // Output:
-    // Provider: anthropic
-    // [AnthropicClient] Model: claude-3-5-sonnet-20241022
-    // [AnthropicClient] Max retries: 3
-    // [AnthropicClient] Sending 1 message(s)...
-    // [AnthropicClient] System prompt: "You are a concise technical assistant."
-    // ── Response ──────────────────────────────
-    // Content:       TypeScript is a statically typed superset of JavaScript...
-    // Finish reason: stop
-    // Tokens used:   { inputTokens: 24, outputTokens: 18 }
-
-  } catch (error) {
-    if (error instanceof Error) {
-      console.error('LLM request failed:', error.message)
-    }
-  }
-}
-
-main()
-```
-
-### Methods
-
-#### `constructor`
-
-```typescript
-constructor(config: LLMClientConfig)
-```
-
-Use this to create an Anthropic-backed LLM client for sending completion requests, with built-in retry logic and model configuration.
-
-The `AnthropicClient` constructor initializes a client that wraps the Anthropic SDK, binding it to a specific model and API key. It defaults to 3 retries on failure unless overridden.
-
-### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `config` | `LLMClientConfig` | ✅ | Configuration object for the client |
-| `config.apiKey` | `string` | ✅ | Your Anthropic API key |
-| `config.model` | `string` | ✅ | The Anthropic model to use (e.g. `"claude-3-5-sonnet-20241022"`) |
-| `config.maxRetries` | `number` | ❌ | Number of retry attempts on failure. Defaults to `3` |
-
-### Returns
-
-An `AnthropicClient` instance with:
-- `provider` set to `"anthropic"`
-- An initialized Anthropic SDK client ready to send requests
-- Retry logic applied to all completion calls
-
-**Example:**
-
-```typescript example.ts
-// Inline types — no library imports needed
-type LLMProvider = 'anthropic' | 'openai'
-
-interface LLMClientConfig {
-  apiKey: string
-  model: string
-  maxRetries?: number
-}
-
-interface CompletionRequest {
-  prompt: string
-  maxTokens?: number
-}
-
-interface CompletionResponse {
-  text: string
-  model: 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) {
-    this.model = config.model
-    this.maxRetries = config.maxRetries ?? 3
-    this.apiKey = config.apiKey
-
-    console.log(`AnthropicClient initialized`)
-    console.log(`  Model:       ${this.model}`)
-    console.log(`  Max Retries: ${this.maxRetries}`)
-    console.log(`  Provider:    ${this.provider}`)
-  }
-
-  async complete(request: CompletionRequest): Promise<CompletionResponse> {
-    // Simulated response — real client calls Anthropic SDK here
-    return {
-      text: `Response to: "${request.prompt}"`,
-      model: this.model,
-      usage: { inputTokens: 12, outputTokens: 34 },
-    }
-  }
-}
-
-// --- Usage ---
-
-async function main() {
-  try {
-    // Basic setup with defaults (maxRetries defaults to 3)
-    const client = new AnthropicClient({
-      apiKey: process.env.ANTHROPIC_API_KEY || 'sk-ant-your-api-key-here',
-      model: 'claude-3-5-sonnet-20241022',
-    })
-
-    const response = await client.complete({
-      prompt: 'Summarize the benefits of TypeScript in one sentence.',
-      maxTokens: 100,
-    })
-
-    console.log('\nCompletion response:')
-    console.log('  Text:   ', response.text)
-    console.log('  Model:  ', response.model)
-    console.log('  Usage:  ', response.usage)
-    // Output:
-    // AnthropicClient initialized
-    //   Model:       claude-3-5-sonnet-20241022
-    //   Max Retries: 3
-    //   Provider:    anthropic
-    //
-    // Completion response:
-    //   Text:    Response to: "Summarize the benefits of TypeScript..."
-    //   Model:   claude-3-5-sonnet-20241022
-    //   Usage:   { inputTokens: 12, outputTokens: 34 }
-
-    // With custom retry count
-    const reliableClient = new AnthropicClient({
-      apiKey: process.env.ANTHROPIC_API_KEY || 'sk-ant-your-api-key-here',
-      model: 'claude-3-haiku-20240307',
-      maxRetries: 5,
-    })
-
-    console.log('\nReliable client provider:', reliableClient.provider)
-    // Output: anthropic
-  } catch (error) {
-    console.error('Failed to initialize AnthropicClient:', error)
-  }
-}
-
-main()
-```
-
-#### `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 submitting requests in workflows where client configuration may be conditional or deferred.
-
-**Returns**
-
-| Value | Condition |
-|-------|-----------|
-| `true` | Always — the client is initialized and the Anthropic SDK handles API key validation internally |
-
-> **Note:** A return value of `true` does not guarantee the API key is valid or that requests will succeed. It confirms the client object is configured and ready to attempt calls. Authentication errors will surface when `complete()` is called.
-
-**Parameters**
-
-None.
-
-**Example:**
-
-```typescript example.ts
-// Inline types to simulate AnthropicClient behavior
-interface LLMClientConfig {
-  apiKey: string
-  model?: string
-  timeout?: number
-  maxRetries?: number
-}
-
-// Simulated AnthropicClient class
-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
-  }
-
-  // Anthropic SDK handles credential validation internally —
-  // this method simply confirms the client is initialized.
-  isConfigured(): boolean {
-    return true
-  }
-
-  async complete(prompt: string): Promise<string> {
-    if (!this.isConfigured()) {
-      throw new Error('Client is not configured. Cannot send requests.')
-    }
-    // Real implementation would call Anthropic SDK here
-    return `Response from ${this.model}: (simulated)`
-  }
-}
-
-// --- Usage ---
-
-async function runWithGuard(client: AnthropicClient, prompt: string) {
-  try {
-    // Guard: check configuration before making expensive API calls
-    if (!client.isConfigured()) {
-      console.warn('Client not ready — skipping request.')
-      return null
-    }
-
-    console.log('Client is configured:', client.isConfigured())
-    // Output: Client is configured: true
-
-    const response = await client.complete(prompt)
-    console.log('Response:', response)
-    // Output: Response: Response from claude-3-5-sonnet-20241022: (simulated)
-
-    return response
-  } catch (error) {
-    console.error('Request failed:', error instanceof Error ? error.message : error)
-    return null
-  }
-}
-
-const client = new AnthropicClient({
-  apiKey: process.env.ANTHROPIC_API_KEY || 'sk-ant-your-api-key-here',
-  model: 'claude-3-5-sonnet-20241022',
-  timeout: 30000,
-  maxRetries: 3,
-})
-
-runWithGuard(client, 'Explain recursion in one sentence.')
-```
-
-#### `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 message history automatically.
-
-This method separates system messages from conversation messages internally, so you can pass a unified message array without pre-processing. It falls back to the client's default model if none is specified in the request.
-
-## Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `request` | `CompletionRequest` | Yes | The completion request object containing messages, optional model override, and generation settings |
-| `request.messages` | `Message[]` | Yes | Array of messages with `role` (`"system"`, `"user"`, `"assistant"`) and `content` string fields |
-| `request.model` | `string` | No | Model identifier (e.g. `"claude-3-5-sonnet-20241022"`). Falls back to the client's configured default model |
-| `request.maxTokens` | `number` | No | Maximum number of tokens to generate in the response |
-| `request.temperature` | `number` | No | Sampling temperature between 0 and 1. Lower = more deterministic |
-
-## 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 used to generate the response |
-| `usage` | `object` | Token usage stats with `inputTokens` and `outputTokens` |
-| `finishReason` | `string` | Why generation stopped (e.g. `"end_turn"`, `"max_tokens"`) |
-
-Throws an error if the Anthropic API request fails or returns a non-successful status.
-
-**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
-}
-
-interface CompletionResponse {
-  content: string
-  model: string
-  usage: {
-    inputTokens: number
-    outputTokens: number
-  }
-  finishReason: string
-}
-
-// ── Simulated AnthropicClient (mirrors real implementation behavior) ────────
-
-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,
-      })),
-    }
-
-    const response = await fetch('https://api.anthropic.com/v1/messages', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'x-api-key': this.apiKey,
-        'anthropic-version': '2023-06-01',
-      },
-      body: JSON.stringify(payload),
-    })
-
-    if (!response.ok) {
-      const error = await response.text()
-      throw new Error(`Anthropic API error ${response.status}: ${error}`)
-    }
-
-    const data = await response.json() as {
-      content: Array<{ type: string; text: string }>
-      model: string
-      usage: { input_tokens: number; output_tokens: number }
-      stop_reason: string
-    }
-
-    return {
-      content: data.content.find(b => b.type === 'text')?.text ?? '',
-      model: data.model,
-      usage: {
-        inputTokens: data.usage.input_tokens,
-        outputTokens: data.usage.output_tokens,
-      },
-      finishReason: 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 used:  ', response.model)
-    console.log('Tokens used: ', response.usage)
-    console.log('Finish reason:', response.finishReason)
-
-    // Expected output:
-    // Reply:        The capital of Japan is Tokyo.
-    // Model used:   claude-3-5-sonnet-20241022
-    // Tokens used:  { inputTokens: 32, outputTokens: 10 }
-    // Finish reason: end_turn
-  } catch (error) {
-    console.error('Completion failed:', error)
-    process.exit(1)
-  }
-}
-
-main()
-```
-