skrypt-ai 0.7.0 → 0.8.0

package/dist/template/src/app/docs/llm/page.mdx

@@ -1,428 +0,0 @@
-## Classes
-
-### `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` |
-
-## Methods
-
-### `complete(request: CompletionRequest): Promise<CompletionResponse>`
-
-Sends a completion request to the configured provider.
-
-| 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 |
-| `request.stream` | `boolean` | ❌ | Enable streaming responses |
-
-#### Returns
-
-A `CompletionResponse` object:
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `content` | `string` | The generated text response |
-| `usage.promptTokens` | `number` | Tokens consumed by the input |
-| `usage.completionTokens` | `number` | Tokens consumed by the output |
-| `usage.totalTokens` | `number` | Total tokens used |
-
-## Provider Quick Reference
-
-| 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 |
-
-### Methods
-
-#### `constructor`
-
-```typescript
-constructor(config: LLMClientConfig)
-```
-
-Use this to create a unified LLM client that connects to any OpenAI-compatible API provider (OpenAI, Anthropic, Mistral, local models, etc.) with automatic retry logic and provider-specific configuration.
-
-#### Parameters
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `config` | `LLMClientConfig` | Yes | Configuration object for the LLM client |
-| `config.provider` | `LLMProvider` | Yes | The LLM provider identifier (e.g., `'openai'`, `'mistral'`, `'anthropic'`) |
-| `config.model` | `string` | Yes | The model name to use for completions (e.g., `'gpt-4o'`, `'mistral-large'`) |
-| `config.baseUrl` | `string` | No | Override the default base URL for the provider's API endpoint |
-| `config.maxRetries` | `number` | No | Number of retry attempts on failure. Defaults to `3` |
-| `config.apiKey` | `string` | Yes | API key for authenticating with the provider |
-
-#### Returns
-
-An `OpenAICompatibleClient` instance with:
-- `provider` — the configured provider identifier (publicly accessible)
-- Access to completion methods using the specified model and retry settings
-
-## Notes
-
-- If `config.baseUrl` is omitted, the client automatically resolves the correct endpoint from a built-in provider URL map
-- If `config.maxRetries` is omitted, it defaults to `3`
-- The underlying HTTP client is an `OpenAI` SDK instance, making this compatible with any provider that follows the OpenAI API spec
-
-**Example:**
-
-```typescript example.ts
-// ── Inline types (no external imports needed) ──────────────────────────────
-
-type LLMProvider = 'openai' | 'mistral' | 'anthropic' | 'local'
-
-interface LLMClientConfig {
-  provider: LLMProvider
-  model: string
-  apiKey: string
-  baseUrl?: string
-  maxRetries?: number
-}
-
-const PROVIDER_BASE_URLS: Record<LLMProvider, string> = {
-  openai: 'https://api.openai.com/v1',
-  mistral: 'https://api.mistral.ai/v1',
-  anthropic: 'https://api.anthropic.com/v1',
-  local: 'http://localhost:11434/v1',
-}
-
-// ── Simulated OpenAICompatibleClient class ─────────────────────────────────
-
-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.baseUrl = config.baseUrl || PROVIDER_BASE_URLS[config.provider]
-    this.apiKey = config.apiKey
-
-    console.log(`[OpenAICompatibleClient] Initialized`)
-    console.log(`  Provider  : ${this.provider}`)
-    console.log(`  Model     : ${this.model}`)
-    console.log(`  Base URL  : ${this.baseUrl}`)
-    console.log(`  MaxRetries: ${this.maxRetries}`)
-  }
-
-  async complete(prompt: string): Promise<{ text: string; model: string }> {
-    console.log(`\n[OpenAICompatibleClient] Sending prompt to ${this.provider}...`)
-    // Simulated response — replace with real HTTP call in production
-    return {
-      text: `Echo from ${this.model}: "${prompt}"`,
-      model: this.model,
-    }
-  }
-}
-
-// ── Usage examples ─────────────────────────────────────────────────────────
-
-async function main() {
-  try {
-    // Example 1: Connect to OpenAI with default settings
-    const openaiClient = new OpenAICompatibleClient({
-      provider: 'openai',
-      model: 'gpt-4o',
-      apiKey: process.env.OPENAI_API_KEY || 'sk-your-openai-key-here',
-    })
-
-    const openaiResult = await openaiClient.complete('Summarize the water cycle.')
-    console.log('\nOpenAI result:', openaiResult)
-    // Output: { text: 'Echo from gpt-4o: "Summarize the water cycle."', model: 'gpt-4o' }
-
-    // Example 2: Connect to a local Ollama instance with custom base URL
-    const localClient = new OpenAICompatibleClient({
-      provider: 'local',
-      model: 'llama3',
-      apiKey: 'not-required-for-local',
-      baseUrl: 'http://localhost:11434/v1', // override default
-      maxRetries: 1, // fewer retries for local dev
-    })
-
-    const localResult = await localClient.complete('What is 2 + 2?')
-    console.log('\nLocal model result:', localResult)
-    // Output: { text: 'Echo from llama3: "What is 2 + 2?"', model: 'llama3' }
-
-    // Example 3: Connect to Mistral with default retry count (3)
-    const mistralClient = new OpenAICompatibleClient({
-      provider: 'mistral',
-      model: 'mistral-large-latest',
-      apiKey: process.env.MISTRAL_API_KEY || 'your-mistral-key-here',
-    })
-
-    console.log(`\nMistral provider: ${mistralClient.provider}`)
-    // Output: Mistral provider: mistral
-
-  } catch (error) {
-    console.error('Failed to initialize or call LLM client:', error)
-  }
-}
-
-main()
-```
-
-#### `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 follow a consistent "is configured?" pattern across multiple LLM client types.
-
-#### Returns
-
-| Condition | Value |
-|-----------|-------|
-| Always | `true` — configuration validation is delegated to the OpenAI SDK |
-
-> **Note:** A `true` return does **not** guarantee the API key is valid or that the endpoint is reachable. It only confirms the client object was constructed. Actual credential errors surface when calling `complete()`.
-
-**Example:**
-
-```typescript example.ts
-// Inline types to simulate the OpenAICompatibleClient behavior
-type LLMProvider = 'openai' | 'azure' | 'groq' | 'custom'
-
-interface LLMClientConfig {
-  apiKey: string
-  provider: LLMProvider
-  model?: string
-  baseURL?: string
-}
-
-// Simulated OpenAICompatibleClient
-class OpenAICompatibleClient {
-  private apiKey: string
-  private provider: LLMProvider
-  private model: string
-
-  constructor(config: LLMClientConfig) {
-    this.apiKey = config.apiKey
-    this.provider = config.provider
-    this.model = config.model || 'gpt-4o'
-  }
-
-  // OpenAI SDK handles validation — always returns true
-  isConfigured(): boolean {
-    return true
-  }
-}
-
-// --- Usage Example ---
-
-const client = new OpenAICompatibleClient({
-  apiKey: process.env.OPENAI_API_KEY || 'sk-proj-abc123xyz',
-  provider: 'openai',
-  model: 'gpt-4o',
-})
-
-// Guard clause pattern: check before proceeding
-function runCompletion(client: OpenAICompatibleClient, prompt: string) {
-  if (!client.isConfigured()) {
-    console.error('Client is not configured. Aborting.')
-    return
-  }
-
-  console.log(`Client is configured: ${client.isConfigured()}`)
-  // Output: Client is configured: true
-
-  console.log(`Proceeding with prompt: "${prompt}"`)
-  // In real usage, you would call: await client.complete({ prompt })
-}
-
-runCompletion(client, 'Summarize the latest AI research trends.')
-
-// Multi-client health check pattern
-const clients = [
-  new OpenAICompatibleClient({ apiKey: 'sk-groq-key-001', provider: 'groq', model: 'llama3-8b-8192' }),
-  new OpenAICompatibleClient({ apiKey: 'sk-azure-key-002', provider: 'azure', model: 'gpt-4' }),
-]
-
-const allReady = clients.every(c => c.isConfigured())
-console.log(`All clients ready: ${allReady}`)
-// Output: All clients ready: true
-```
-
-#### `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 to:
-
-| 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
-// ── Inline types (no external imports needed) ──────────────────────────────
-
-type Message = { role: 'system' | 'user' | 'assistant'; content: string }
-
-type CompletionRequest = {
-  messages: Message[]
-  model?: string
-  temperature?: number
-  maxTokens?: number
-  systemPrompt?: string
-}
-
-type CompletionResponse = {
-  content: string
-  model: string
-  usage: {
-    promptTokens: number
-    completionTokens: number
-    totalTokens: number
-  }
-}
-
-// ── Minimal OpenAI-compatible client (self-contained simulation) ───────────
-
-class OpenAICompatibleClient {
-  private apiKey: string
-  private baseURL: string
-  private model: string
-
-  constructor(config: { apiKey: string; baseURL?: string; model?: string }) {
-    this.apiKey = config.apiKey
-    this.baseURL = config.baseURL || 'https://api.openai.com/v1'
-    this.model = config.model || 'gpt-4o'
-  }
-
-  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 body = {
-      model,
-      messages,
-      ...(request.temperature !== undefined && { temperature: request.temperature }),
-      ...(request.maxTokens !== undefined && { max_tokens: request.maxTokens }),
-    }
-
-    const response = await fetch(`${this.baseURL}/chat/completions`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this.apiKey}`,
-      },
-      body: JSON.stringify(body),
-    })
-
-    if (!response.ok) {
-      const error = await response.text()
-      throw new Error(`API request failed (${response.status}): ${error}`)
-    }
-
-    const data = await response.json()
-    const choice = data.choices[0]
-
-    return {
-      content: choice.message.content ?? '',
-      model: data.model,
-      usage: {
-        promptTokens: data.usage.prompt_tokens,
-        completionTokens: data.usage.completion_tokens,
-        totalTokens: data.usage.total_tokens,
-      },
-    }
-  }
-}
-
-// ── Usage example ──────────────────────────────────────────────────────────
-
-const client = new OpenAICompatibleClient({
-  apiKey: process.env.OPENAI_API_KEY || 'sk-your-api-key-here',
-  baseURL: 'https://api.openai.com/v1',
-  model: 'gpt-4o-mini',
-})
-
-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)
-    }
-  }
-}
-
-main()
-```
-