skrypt-ai 0.3.4 → 0.4.1

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

@@ -0,0 +1,428 @@
+## 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()
+```
+

package/dist/template/src/app/docs/llms-full.md

@@ -0,0 +1,256 @@
+# Skrypt API
+
+> API documentation for Skrypt
+
+## getAuthConfig
+function getAuthConfig(): AuthConfig
+
+## saveAuthConfig
+function saveAuthConfig(config: AuthConfig): void
+
+## clearAuth
+function clearAuth(): void
+
+## checkPlan
+async function checkPlan(apiKey: string): Promise<PlanCheckResponse>
+
+## requirePro
+async function requirePro(commandName: string): Promise<boolean>
+
+## isProCommand
+function isProCommand(command: string): boolean
+
+## autoFixExample
+async function autoFixExample(example: CodeExample, client: LLMClient, options: AutoFixOptions = {}): Promise<FixResult>
+
+## autoFixBatch
+async function autoFixBatch(examples: CodeExample[], client: LLMClient, options: AutoFixOptions = {}): Promise<Map<number, FixResult>>
+
+## createTypeScriptValidator
+function createTypeScriptValidator(): (code: string) => Promise<ValidationResult>
+
+## createPythonValidator
+function createPythonValidator(): (code: string) => Promise<ValidationResult>
+
+## findConfigFile
+function findConfigFile(dir: string): string | null
+
+## loadConfig
+function loadConfig(configPath?: string): Config
+
+## validateConfig
+function validateConfig(config: Config): string[]
+
+## checkApiKey
+function checkApiKey(provider: LLMProvider): { ok: boolean; envKey: string | null }
+
+## generateForElement
+async function generateForElement(element: APIElement, client: LLMClient, options: GenerationOptions, onProgress?: (progress: GenerationProgress) => void): Promise<GeneratedDoc>
+
+## generateForElements
+async function generateForElements(elements: APIElement[], client: LLMClient, options: GenerationOptions): Promise<GeneratedDoc[]>
+
+## formatAsMarkdown
+function formatAsMarkdown(docs: GeneratedDoc[], title: string): string
+
+## organizeByTopic
+function organizeByTopic(docs: GeneratedDoc[], config: TopicConfig = DEFAULT_TOPIC_CONFIG): Topic[]
+
+## detectCrossReferences
+function detectCrossReferences(docs: GeneratedDoc[]): CrossReference[]
+
+## getCrossRefsForElement
+function getCrossRefsForElement(elementName: string, allRefs: CrossReference[]): CrossReference[]
+
+## buildNavigation
+function buildNavigation(topics: Topic[]): NavigationItem[]
+
+## generateSidebarConfig
+function generateSidebarConfig(topics: Topic[]): object
+
+## mergeTopicConfig
+function mergeTopicConfig(userConfig: Partial<TopicConfig>, defaults: TopicConfig = DEFAULT_TOPIC_CONFIG): TopicConfig
+
+## writeLlmsTxt
+async function writeLlmsTxt(docs: GeneratedDoc[], outputDir: string, options: { projectName?: string; description?: string } = {}): Promise<void>
+
+## writeDocsToDirectory
+async function writeDocsToDirectory(results: FileGenerationResult[], outputDir: string, sourceDir: string): Promise<{ filesWritten: number; totalDocs: number }>
+
+## groupDocsByFile
+function groupDocsByFile(docs: GeneratedDoc[]): FileGenerationResult[]
+
+## writeDocsByTopic
+async function writeDocsByTopic(docs: GeneratedDoc[], outputDir: string): Promise<{ filesWritten: number; totalDocs: number; topics: Topic[] }>
+
+## postPRComment
+async function postPRComment(config: PRCommentConfig, issues: DocumentationIssue[]): Promise<CommentResult>
+
+## postInlineComments
+async function postInlineComments(config: PRCommentConfig, issues: DocumentationIssue[]): Promise<CommentResult[]>
+
+## analyzePRForDocs
+async function analyzePRForDocs(config: PRCommentConfig, _options: { checkExamples?: boolean } = {}): Promise<DocumentationIssue[]>
+
+## AnthropicClient
+class AnthropicClient implements LLMClient
+
+## constructor
+constructor(config: LLMClientConfig)
+
+## isConfigured
+isConfigured(): boolean
+
+## complete
+async complete(request: CompletionRequest): Promise<CompletionResponse>
+
+## createLLMClient
+function createLLMClient(config: {
+  provider: LLMProvider
+  model: string
+  baseUrl?: string
+  timeout?: number
+  maxRetries?: number
+}): LLMClient
+
+## generateDocumentation
+async function generateDocumentation(client: LLMClient, element: ElementContext, options?: { multiLanguage?: boolean }): Promise<GeneratedDocResult>
+
+## fixCodeSample
+async function fixCodeSample(client: LLMClient, code: string, error: string, context: string, iteration: number = 1): Promise<string>
+
+## OpenAICompatibleClient
+class OpenAICompatibleClient implements LLMClient
+
+## constructor
+constructor(config: LLMClientConfig)
+
+## isConfigured
+isConfigured(): boolean
+
+## complete
+async complete(request: CompletionRequest): Promise<CompletionResponse>
+
+## PluginManager
+class PluginManager
+
+## constructor
+constructor(sourcePath: string, outputPath: string, config: Record<string, unknown> = {})
+
+## loadPlugins
+async loadPlugins(configPath?: string): Promise<void>
+
+## register
+register(plugin: SkryptPlugin): void
+
+## runHook
+async runHook<T>(hook: keyof SkryptPlugin, ...args: unknown[]): Promise<T | undefined>
+
+## onInit
+async onInit(): Promise<void>
+
+## onBeforeScan
+async onBeforeScan(): Promise<void>
+
+## onAfterScan
+async onAfterScan<T>(elements: T[]): Promise<T[]>
+
+## onBeforeGenerate
+async onBeforeGenerate<T>(elements: T[]): Promise<T[]>
+
+## onAfterGenerate
+async onAfterGenerate<T>(docs: T[]): Promise<T[]>
+
+## onBeforeWrite
+async onBeforeWrite<T>(docs: T[]): Promise<T[]>
+
+## onAfterWrite
+async onAfterWrite(): Promise<void>
+
+## transformContent
+async transformContent(content: string, filePath: string): Promise<string>
+
+## definePlugin
+function definePlugin(plugin: SkryptPlugin): SkryptPlugin
+
+## classifyElement
+function classifyElement(element: APIElement): ContentClassification
+
+## classifyElements
+function classifyElements(elements: APIElement[]): Map<ContentType, APIElement[]>
+
+## getRecommendedStructure
+function getRecommendedStructure(elements: APIElement[]): {
+  sections: { name: string; type: ContentType; elements: APIElement[] }[]
+  stats: { api: number; guide: number; tutorial: number; overview: number }
+}
+
+## getPromptForContentType
+function getPromptForContentType(type: ContentType): string
+
+## GoScanner
+class GoScanner implements Scanner
+
+## canHandle
+canHandle(filePath: string): boolean
+
+## scanFile
+async scanFile(filePath: string): Promise<ScanResult>
+
+## scanDirectory
+async function scanDirectory(dir: string, options: ScanOptions = {}): Promise<ScanAllResult>
+
+## scanFile
+async function scanFile(filePath: string): Promise<ScanResult>
+
+## PythonScanner
+class PythonScanner implements Scanner
+
+## canHandle
+canHandle(filePath: string): boolean
+
+## scanFile
+async scanFile(filePath: string): Promise<ScanResult>
+
+## get_docstring
+def get_docstring(node: ast.AST) -> str | None
+
+## get_type_annotation
+def get_type_annotation(annotation: ast.AST | None) -> str | None
+
+## get_default_value
+def get_default_value(default: ast.AST | None) -> str | None
+
+## extract_parameters
+def extract_parameters(args: ast.arguments) -> list[dict[str, Any]]
+
+## build_signature
+def build_signature(name: str, args: ast.arguments, returns: ast.AST | None, is_async: bool) -> str
+
+## extract_function
+def extract_function(node: ast.FunctionDef | ast.AsyncFunctionDef, file_path: str, parent_class: str | None) -> dict[str, Any]
+
+## extract_class
+def extract_class(node: ast.ClassDef, file_path: str) -> list[dict[str, Any]]
+
+## scan_file
+def scan_file(file_path: str) -> dict[str, Any]
+
+## RustScanner
+class RustScanner implements Scanner
+
+## canHandle
+canHandle(filePath: string): boolean
+
+## scanFile
+async scanFile(filePath: string): Promise<ScanResult>
+
+## TypeScriptScanner
+class TypeScriptScanner implements Scanner
+
+## canHandle
+canHandle(filePath: string): boolean
+
+## scanFile
+async scanFile(filePath: string): Promise<ScanResult>
+