skrypt-ai 0.3.3 → 0.4.0

package/dist/template/src/app/docs/llm/index.md

@@ -0,0 +1,471 @@
+# Index.ts
+
+## Functions
+
+### `createLLMClient`
+
+```typescript
+function createLLMClient(config: {
+  provider: LLMProvider
+  model: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+}): LLMClient
+```
+
+Use this to initialize a typed LLM client for a specific AI provider (OpenAI, Anthropic, etc.) with retry and timeout handling built in.
+
+This is your entry point for all LLM interactions — call it once at startup and reuse the returned `LLMClient` throughout your application.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `config.provider` | `LLMProvider` | ✅ Yes | The AI provider to use. Accepted values: `"openai"`, `"anthropic"`, `"azure"` |
+| `config.model` | `string` | ✅ Yes | The model identifier to use (e.g. `"gpt-4o"`, `"claude-3-5-sonnet-20241022"`) |
+| `config.baseUrl` | `string` | No | Override the default API endpoint. Useful for proxies or self-hosted models |
+| `config.timeout` | `number` | No | Request timeout in milliseconds. Defaults to `30000` (30s) |
+| `config.maxRetries` | `number` | No | Number of times to retry on transient failures. Defaults to `3` |
+
+## Returns
+
+Returns an `LLMClient` instance with methods to send completions and chat messages to the configured provider. The client is pre-configured with your chosen model, timeout, and retry policy.
+
+| Scenario | Result |
+|----------|--------|
+| Valid config | Returns a ready-to-use `LLMClient` |
+| Unknown provider | Throws an error at construction time |
+| Network failure (within retries) | Automatically retried up to `maxRetries` times |
+| Timeout exceeded | Throws a timeout error after `timeout` ms |
+
+**Example:**
+
+```typescript example.ts
+// --- Inline types (do not import from autodocs) ---
+type LLMProvider = "openai" | "anthropic" | "azure"
+
+interface LLMClientConfig {
+  provider: LLMProvider
+  model: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+}
+
+interface ChatMessage {
+  role: "user" | "assistant" | "system"
+  content: string
+}
+
+interface LLMClient {
+  chat: (messages: ChatMessage[]) => Promise<{ content: string; model: string; usage: { promptTokens: number; completionTokens: number } }>
+  provider: LLMProvider
+  model: string
+}
+
+// --- Simulated createLLMClient (mirrors real behavior) ---
+function createLLMClient(config: LLMClientConfig): LLMClient {
+  const SUPPORTED_PROVIDERS: LLMProvider[] = ["openai", "anthropic", "azure"]
+
+  if (!SUPPORTED_PROVIDERS.includes(config.provider)) {
+    throw new Error(`Unsupported provider: "${config.provider}". Must be one of: ${SUPPORTED_PROVIDERS.join(", ")}`)
+  }
+
+  const timeout = config.timeout ?? 30_000
+  const maxRetries = config.maxRetries ?? 3
+  const baseUrl = config.baseUrl ?? `https://api.${config.provider}.com/v1`
+
+  console.log(`[LLMClient] Initialized — provider: ${config.provider}, model: ${config.model}`)
+  console.log(`[LLMClient] baseUrl: ${baseUrl}, timeout: ${timeout}ms, maxRetries: ${maxRetries}`)
+
+  return {
+    provider: config.provider,
+    model: config.model,
+    chat: async (messages: ChatMessage[]) => {
+      // Simulated API response
+      return {
+        content: `Hello! You asked: "${messages.at(-1)?.content}"`,
+        model: config.model,
+        usage: { promptTokens: 24, completionTokens: 18 },
+      }
+    },
+  }
+}
+
+// --- Usage ---
+async function main() {
+  try {
+    // Basic setup — reads API key from environment
+    const apiKey = process.env.OPENAI_API_KEY || "sk-your-api-key-here"
+    console.log(`Using API key: ${apiKey.slice(0, 6)}...`)
+
+    const client = createLLMClient({
+      provider: "openai",
+      model: "gpt-4o",
+      timeout: 15_000,   // 15 second timeout
+      maxRetries: 2,     // retry twice on failure
+    })
+
+    const response = await client.chat([
+      { role: "system",  content: "You are a helpful assistant." },
+      { role: "user",    content: "What is the capital of France?" },
+    ])
+
+    console.log("\n--- Response ---")
+    console.log("Content:  ", response.content)
+    console.log("Model:    ", response.model)
+    console.log("Usage:    ", response.usage)
+    // Output:
+    // Content:   Hello! You asked: "What is the capital of France?"
+    // Model:     gpt-4o
+    // Usage:     { promptTokens: 24, completionTokens: 18 }
+
+    // Example: custom baseUrl for a proxy or Azure endpoint
+    const azureClient = createLLMClient({
+      provider: "azure",
+      model: "gpt-4o",
+      baseUrl: process.env.AZURE_OPENAI_ENDPOINT || "https://my-org.openai.azure.com/v1",
+      timeout: 20_000,
+      maxRetries: 3,
+    })
+
+    console.log(`\nAzure client ready — provider: ${azureClient.provider}, model: ${azureClient.model}`)
+    // Output: Azure client ready — provider: azure, model: gpt-4o
+
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error("Failed to create LLM client:", error.message)
+    }
+  }
+}
+
+main()
+```
+
+### `generateDocumentation`
+
+```typescript
+async function generateDocumentation(client: LLMClient, element: ElementContext, options?: { multiLanguage?: boolean }): Promise<GeneratedDocResult>
+```
+
+Use this to automatically generate documentation for a code element (function, class, method, etc.) using an LLM client, with optional multi-language support.
+
+Takes a configured LLM client and a code element's context, then returns structured documentation output — useful for automating doc generation pipelines or IDE tooling.
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `client` | `LLMClient` | ✅ Yes | A configured LLM client instance (e.g. OpenAI-compatible or Anthropic) used to generate the documentation |
+| `element` | `ElementContext` | ✅ Yes | Context object describing the code element — includes its name, signature, source code, and metadata |
+| `options` | `{ multiLanguage?: boolean }` | ❌ No | Optional config. Set `multiLanguage: false` to generate docs in English only; defaults to `true` |
+
+### Returns
+
+Returns a `Promise<GeneratedDocResult>` that resolves to a structured documentation result. Typically includes:
+
+| Field | Description |
+|-------|-------------|
+| `summary` | A concise description of what the element does |
+| `params` | Documentation for each parameter |
+| `returns` | Description of the return value |
+| `examples` | Generated usage examples (may include multiple languages if `multiLanguage` is enabled) |
+
+Rejects with an error if the LLM client fails to respond or the element context is malformed.
+
+**Example:**
+
+```typescript example.ts
+// ── Inline type definitions (no external imports needed) ──────────────────────
+
+type ElementKind = 'function' | 'class' | 'method' | 'interface'
+
+interface ElementContext {
+  name: string
+  kind: ElementKind
+  signature: string
+  sourceCode: string
+  filePath: string
+  language: string
+}
+
+interface GeneratedDocResult {
+  summary: string
+  params: Array<{ name: string; description: string }>
+  returns: string
+  examples: Array<{ language: string; code: string }>
+  rawOutput: string
+}
+
+interface LLMClient {
+  complete: (prompt: string) => Promise<string>
+}
+
+// ── Simulated generateDocumentation implementation ────────────────────────────
+
+async function generateDocumentation(
+  client: LLMClient,
+  element: ElementContext,
+  options?: { multiLanguage?: boolean }
+): Promise<GeneratedDocResult> {
+  const useMultiLang = options?.multiLanguage ?? true
+
+  const prompt = `
+Generate documentation for the following ${element.kind}:
+
+Name: ${element.name}
+Signature: ${element.signature}
+Language: ${element.language}
+Source:
+${element.sourceCode}
+
+Provide: summary, parameter descriptions, return value, and usage examples.
+${useMultiLang ? 'Include examples in TypeScript and Python.' : 'Include examples in TypeScript only.'}
+  `.trim()
+
+  const rawOutput = await client.complete(prompt)
+
+  // Parse the LLM response into structured output
+  return {
+    summary: `Calculates the total price of items in a cart after applying a discount.`,
+    params: [
+      { name: 'items',    description: 'Array of cart items with price and quantity' },
+      { name: 'discount', description: 'Fractional discount to apply, e.g. 0.1 for 10% off' },
+    ],
+    returns: 'The final total as a number, rounded to 2 decimal places.',
+    examples: [
+      {
+        language: 'typescript',
+        code: `const total = calculateTotal([{ price: 9.99, qty: 2 }], 0.1)\nconsole.log(total) // 17.98`,
+      },
+      ...(useMultiLang
+        ? [{
+            language: 'python',
+            code: `total = calculate_total([{"price": 9.99, "qty": 2}], 0.1)\nprint(total)  # 17.98`,
+          }]
+        : []),
+    ],
+    rawOutput,
+  }
+}
+
+// ── Mock LLM client (replace with a real client in production) ────────────────
+
+function createMockLLMClient(apiKey: string): LLMClient {
+  return {
+    complete: async (prompt: string): Promise<string> => {
+      // In production this would call OpenAI / Anthropic / etc.
+      console.log(`[LLMClient] Sending prompt (${prompt.length} chars) to API...`)
+      return `Generated documentation response from LLM using key: ${apiKey.slice(0, 8)}...`
+    },
+  }
+}
+
+// ── Main usage example ────────────────────────────────────────────────────────
+
+async function main() {
+  const client = createMockLLMClient(
+    process.env.OPENAI_API_KEY || 'sk-proj-abc123xyz'
+  )
+
+  const element: ElementContext = {
+    name: 'calculateTotal',
+    kind: 'function',
+    signature: 'function calculateTotal(items: CartItem[], discount: number): number',
+    language: 'typescript',
+    filePath: 'src/cart/pricing.ts',
+    sourceCode: `
+function calculateTotal(items: CartItem[], discount: number): number {
+  const subtotal = items.reduce((sum, item) => sum + item.price * item.qty, 0)
+  return Math.round(subtotal * (1 - discount) * 100) / 100
+}
+    `.trim(),
+  }
+
+  try {
+    // Generate docs with multi-language examples (default)
+    const result = await generateDocumentation(client, element, {
+      multiLanguage: true,
+    })
+
+    console.log('✅ Documentation generated:\n')
+    console.log('Summary:  ', result.summary)
+    console.log('Returns:  ', result.returns)
+    console.log('Params:')
+    result.params.forEach(p => console.log(`  - ${p.name}: ${p.description}`))
+    console.log('Examples:')
+    result.examples.forEach(ex => {
+      console.log(`\n  [${ex.language}]\n  ${ex.code}`)
+    })
+
+    // Expected output:
+    // ✅ Documentation generated:
+    // Summary:   Calculates the total price of items in a cart after applying a discount.
+    // Returns:   The final total as a number, rounded to 2 decimal places.
+    // Params:
+    //   - items: Array of cart items with price and quantity
+    //   - discount: Fractional discount to apply, e.g. 0.1 for 10% off
+    // Examples:
+    //   [typescript]  const total = calculateTotal(...)
+    //   [python]      total = calculate_total(...)
+
+  } catch (error) {
+    console.error('❌ Documentation generation failed:', error)
+    process.exit(1)
+  }
+}
+
+main()
+```
+
+### `fixCodeSample`
+
+```typescript
+async function fixCodeSample(client: LLMClient, code: string, error: string, context: string, iteration: number = 1): Promise<string>
+```
+
+Use this to automatically repair broken code samples by sending them to an LLM with the error context and receiving a corrected version. Ideal for iterative code generation pipelines where generated code fails validation or execution.
+
+## Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `client` | `LLMClient` | Yes | An initialized LLM client instance used to send the fix request |
+| `code` | `string` | Yes | The broken code sample that needs to be fixed |
+| `error` | `string` | Yes | The error message or stack trace produced by the broken code |
+| `context` | `string` | Yes | Additional context about what the code is supposed to do (e.g., function docs, expected behavior) |
+| `iteration` | `number` | No | Which fix attempt this is (default: `1`). Used to apply progressively smarter fix strategies on repeated failures |
+
+## Returns
+
+Returns a `Promise<string>` containing the corrected code sample. The returned string is the LLM's best attempt at fixing the code given the error and context provided.
+
+## Notes
+
+- The `iteration` parameter enables **progressive fix strategies** — later iterations may prompt the LLM differently (e.g., more conservative rewrites, stripping problematic patterns) to break out of repeated failure loops.
+- Pass the output back into your validation/execution step and call `fixCodeSample` again with `iteration + 1` if it still fails.
+- Keep `context` focused and concise — include the function signature, purpose, and any constraints the code must satisfy.
+
+**Example:**
+
+```typescript example.ts
+// --- Inline types (do not import from autodocs) ---
+interface LLMMessage {
+  role: 'system' | 'user' | 'assistant'
+  content: string
+}
+
+interface LLMClient {
+  complete(messages: LLMMessage[]): Promise<string>
+}
+
+// --- Inline implementation of fixCodeSample ---
+async function fixCodeSample(
+  client: LLMClient,
+  code: string,
+  error: string,
+  context: string,
+  iteration: number = 1
+): Promise<string> {
+  const strategy =
+    iteration === 1
+      ? 'Fix the specific error while keeping the structure intact.'
+      : iteration === 2
+      ? 'Consider a more significant rewrite to avoid the root cause of the error.'
+      : 'Simplify the code as much as possible and avoid any patterns that could cause the error.'
+
+  const messages: LLMMessage[] = [
+    {
+      role: 'system',
+      content:
+        'You are an expert code repair assistant. Return ONLY the corrected code with no explanation or markdown fences.',
+    },
+    {
+      role: 'user',
+      content: `The following code sample has an error. Fix it.
+
+## Context
+${context}
+
+## Broken Code
+\`\`\`typescript
+${code}
+\`\`\`
+
+## Error
+${error}
+
+## Fix Strategy (attempt ${iteration})
+${strategy}
+
+Return only the corrected code.`,
+    },
+  ]
+
+  const fixed = await client.complete(messages)
+  return fixed.trim()
+}
+
+// --- Mock LLM client (simulates an OpenAI-compatible response) ---
+function createMockLLMClient(apiKey: string): LLMClient {
+  return {
+    async complete(messages: LLMMessage[]): Promise<string> {
+      // In production this would call OpenAI/Anthropic/etc.
+      console.log(`[LLMClient] Sending ${messages.length} messages to API...`)
+      console.log(`[LLMClient] Using API key: ${apiKey.slice(0, 8)}...`)
+
+      // Simulate a fixed version of the broken code
+      return `
+async function fetchUserData(userId: string): Promise<{ id: string; name: string }> {
+  const response = await fetch(\`https://api.example.com/users/\${userId}\`)
+  if (!response.ok) {
+    throw new Error(\`HTTP error: \${response.status}\`)
+  }
+  return response.json()
+}`.trim()
+    },
+  }
+}
+
+// --- Example usage ---
+async function main() {
+  const client = createMockLLMClient(
+    process.env.OPENAI_API_KEY || 'sk-your-api-key-here'
+  )
+
+  const brokenCode = `
+async function fetchUserData(userId: string) {
+  const response = await fetch('https://api.example.com/users/' + userId)
+  return response.json() // Missing error handling
+  const data = response.text() // Unreachable code
+}`.trim()
+
+  const error = `
+TypeError: Cannot read properties of undefined (reading 'json')
+  at fetchUserData (example.ts:3:20)`.trim()
+
+  const context = `
+Function: fetchUserData
+Purpose: Fetches a user object by ID from the REST API.
+Returns: Promise<{ id: string; name: string }>
+Must throw a descriptive error if the HTTP response is not OK.`.trim()
+
+  try {
+    console.log('=== Attempt 1: Targeted fix ===')
+    const fixedCode = await fixCodeSample(client, brokenCode, error, context, 1)
+    console.log('Fixed code:\n', fixedCode)
+    // Output: corrected fetchUserData with proper error handling
+
+    console.log('\n=== Attempt 2: Broader rewrite strategy ===')
+    const fixedCodeV2 = await fixCodeSample(client, brokenCode, error, context, 2)
+    console.log('Fixed code (v2):\n', fixedCodeV2)
+    // Output: same fix, but LLM prompted to consider deeper rewrites
+  } catch (err) {
+    console.error('Failed to fix code sample:', err)
+  }
+}
+
+main()
+```
+