skrypt-ai 0.1.0

package/dist/llm/anthropic-client.js

@@ -0,0 +1,92 @@
+import Anthropic from '@anthropic-ai/sdk';
+/**
+ * Anthropic Claude client
+ */
+export class AnthropicClient {
+    provider = 'anthropic';
+    client;
+    model;
+    maxRetries;
+    constructor(config) {
+        this.model = config.model;
+        this.maxRetries = config.maxRetries ?? 3;
+        this.client = new Anthropic({
+            apiKey: config.apiKey,
+            timeout: config.timeout ?? 60000,
+            maxRetries: this.maxRetries
+        });
+    }
+    isConfigured() {
+        return true; // Anthropic SDK handles validation
+    }
+    async complete(request) {
+        const model = request.model || this.model;
+        // Separate system message from conversation
+        const systemMessage = request.messages.find(m => m.role === 'system');
+        const conversationMessages = request.messages.filter(m => m.role !== 'system');
+        try {
+            const response = await this.client.messages.create({
+                model,
+                max_tokens: request.maxTokens ?? 4096,
+                system: systemMessage?.content,
+                messages: conversationMessages.map(m => ({
+                    role: m.role,
+                    content: m.content
+                })),
+                temperature: request.temperature ?? 0
+            });
+            // Extract text content from response
+            const content = response.content
+                .filter(block => block.type === 'text')
+                .map(block => block.text)
+                .join('');
+            return {
+                content,
+                model: response.model,
+                usage: {
+                    inputTokens: response.usage.input_tokens,
+                    outputTokens: response.usage.output_tokens,
+                    totalTokens: response.usage.input_tokens + response.usage.output_tokens
+                },
+                finishReason: this.mapStopReason(response.stop_reason)
+            };
+        }
+        catch (error) {
+            throw this.handleError(error);
+        }
+    }
+    mapStopReason(reason) {
+        switch (reason) {
+            case 'end_turn':
+            case 'stop_sequence':
+                return 'stop';
+            case 'max_tokens':
+                return 'length';
+            default:
+                return 'error';
+        }
+    }
+    handleError(error) {
+        if (error instanceof Anthropic.APIError) {
+            const status = error.status;
+            const message = error.message;
+            if (status === 401) {
+                return new Error('Authentication failed for Anthropic: Invalid API key');
+            }
+            if (status === 429) {
+                return new Error(`Rate limited by Anthropic: ${message}`);
+            }
+            if (status === 500 || status === 502 || status === 503) {
+                return new Error(`Anthropic service error: ${message}`);
+            }
+            if (status === 400 && message.includes('credit')) {
+                return new Error('Anthropic API: Insufficient credits');
+            }
+            return new Error(`Anthropic API error (${status}): ${message}`);
+        }
+        if (error instanceof Error) {
+            return error;
+        }
+        return new Error(`Unknown error from Anthropic: ${String(error)}`);
+    }
+}

package/dist/llm/index.d.ts

@@ -0,0 +1,53 @@
+import { LLMProvider } from '../config/types.js';
+import { LLMClient } from './types.js';
+export * from './types.js';
+export type { LLMClient };
+/**
+ * Create an LLM client for the specified provider
+ */
+export declare function createLLMClient(config: {
+    provider: LLMProvider;
+    model: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+}): LLMClient;
+/**
+ * Extended element info for better doc generation
+ */
+export interface ElementContext {
+    kind: string;
+    name: string;
+    signature: string;
+    parameters: Array<{
+        name: string;
+        type?: string;
+        default?: string;
+    }>;
+    returnType?: string;
+    docstring?: string;
+    parentClass?: string;
+    imports?: string[];
+    packageName?: string;
+    sourceContext?: string;
+    filePath?: string;
+}
+/**
+ * Generated documentation result
+ */
+export interface GeneratedDocResult {
+    markdown: string;
+    codeExample: string;
+    pythonExample?: string;
+    typescriptExample?: string;
+}
+/**
+ * Helper to generate documentation for a code element
+ */
+export declare function generateDocumentation(client: LLMClient, element: ElementContext, options?: {
+    multiLanguage?: boolean;
+}): Promise<GeneratedDocResult>;
+/**
+ * Helper to fix a broken code sample with smart strategies
+ */
+export declare function fixCodeSample(client: LLMClient, code: string, error: string, context: string, iteration?: number): Promise<string>;

package/dist/llm/index.js

@@ -0,0 +1,400 @@
+import { PROVIDER_ENV_KEYS } from '../config/types.js';
+import { OpenAICompatibleClient } from './openai-client.js';
+import { AnthropicClient } from './anthropic-client.js';
+export * from './types.js';
+/**
+ * Create an LLM client for the specified provider
+ */
+export function createLLMClient(config) {
+    // Get API key from environment
+    const envKey = PROVIDER_ENV_KEYS[config.provider];
+    const apiKey = envKey ? process.env[envKey] || '' : '';
+    const clientConfig = {
+        provider: config.provider,
+        model: config.model,
+        apiKey,
+        baseUrl: config.baseUrl,
+        timeout: config.timeout,
+        maxRetries: config.maxRetries
+    };
+    // Use Anthropic client for Anthropic, OpenAI-compatible for everything else
+    if (config.provider === 'anthropic') {
+        return new AnthropicClient(clientConfig);
+    }
+    return new OpenAICompatibleClient(clientConfig);
+}
+/**
+ * Helper to generate documentation for a code element
+ */
+export async function generateDocumentation(client, element, options) {
+    const useMultiLang = options?.multiLanguage ?? true;
+    const prompt = buildDocPrompt(element, useMultiLang);
+    const response = await client.complete({
+        messages: [
+            {
+                role: 'system',
+                content: useMultiLang ? SYSTEM_PROMPT_MULTI_LANG : SYSTEM_PROMPT
+            },
+            {
+                role: 'user',
+                content: prompt
+            }
+        ],
+        temperature: 0,
+        maxTokens: useMultiLang ? 4096 : 2048
+    });
+    return useMultiLang
+        ? parseMultiLangResponse(response.content)
+        : parseDocResponse(response.content);
+}
+// Phase 2: Multi-language system prompt
+const SYSTEM_PROMPT_MULTI_LANG = `You are an expert technical writer creating OUTCOMES-FOCUSED documentation with DUAL-LANGUAGE examples.
+
+Your goal: Help developers achieve their task FAST. Lead with "Use this to..." not "This function...".
+
+## Documentation Rules
+1. Do NOT include a heading with the function/class name - start directly with the use case
+2. Start with the PRIMARY USE CASE - what problem does this solve?
+3. Use a markdown table for parameters (Name | Type | Required | Description)
+4. Clearly document what is returned and when
+
+## Code Example Rules (CRITICAL)
+Generate TWO self-contained examples: TypeScript AND Python.
+
+Both examples MUST be:
+1. COMPLETELY SELF-CONTAINED - no external imports from the library
+2. EXECUTABLE standalone - inline all types and mock all functions
+3. Using realistic data (API keys, user IDs, etc.)
+4. Wrapped in try/except (Python) or try/catch (TypeScript)
+5. Showing environment variable usage
+6. Ending with print/console.log showing expected output
+
+## TypeScript Example Pattern
+\`\`\`typescript
+// Inline types
+type Config = { apiKey: string }
+
+// Mock implementation
+function createTool(config: Config) {
+  return { execute: async (q: string) => ({ results: [q] }) }
+}
+
+// Usage
+const tool = createTool({ apiKey: process.env.API_KEY || 'your-key' })
+
+async function main() {
+  try {
+    const result = await tool.execute('query')
+    console.log('Result:', result)
+    // Output: { results: ['query'] }
+  } catch (error) {
+    console.error('Failed:', error)
+  }
+}
+main()
+\`\`\`
+
+## Python Example Pattern
+\`\`\`python
+import os
+from dataclasses import dataclass
+from typing import Optional, List, Dict, Any
+
+# Inline types
+@dataclass
+class Config:
+    api_key: str
+    timeout: int = 30
+
+# Mock implementation
+class Tool:
+    def __init__(self, config: Config):
+        self.config = config
+
+    async def execute(self, query: str) -> Dict[str, Any]:
+        return {"results": [query]}
+
+# Usage
+import asyncio
+
+async def main():
+    try:
+        tool = Tool(Config(api_key=os.getenv("API_KEY", "your-key")))
+        result = await tool.execute("query")
+        print(f"Result: {result}")
+        # Output: {'results': ['query']}
+    except Exception as e:
+        print(f"Failed: {e}")
+
+asyncio.run(main())
+\`\`\`
+
+## Output Format
+---MARKDOWN---
+[Your markdown documentation with parameter table]
+---TYPESCRIPT---
+[Self-contained TypeScript example]
+---PYTHON---
+[Self-contained Python example]
+---END---`;
+const SYSTEM_PROMPT = `You are an expert technical writer creating OUTCOMES-FOCUSED documentation.
+
+Your goal: Help developers achieve their task FAST. Lead with "Use this to..." not "This function...".
+
+## Documentation Rules
+1. Do NOT include a heading with the function/class name - start directly with the use case
+2. Start with the PRIMARY USE CASE - what problem does this solve?
+3. Use a markdown table for parameters (Name | Type | Required | Description)
+4. Clearly document what is returned and when
+
+## Code Example Rules (CRITICAL)
+Your code examples MUST be COMPLETELY SELF-CONTAINED and EXECUTABLE:
+
+1. NEVER import from the library being documented (e.g., "@supermemory/tools")
+2. Instead, INLINE any types or simple implementations needed
+3. Use realistic but simple data (real-looking API keys, user IDs, etc.)
+4. ALWAYS wrap async code in try/catch with meaningful error handling
+5. ALWAYS show environment variable usage: process.env.API_KEY || 'your-api-key'
+6. End with a console.log showing expected output
+7. Include a brief comment showing what output to expect
+
+## Self-Contained Example Pattern
+BAD (imports from library - will fail):
+\`\`\`typescript
+import { createTool } from '@mylib/tools'
+const tool = createTool('key')
+\`\`\`
+
+GOOD (self-contained - will run):
+\`\`\`typescript
+// Define the types inline
+type ToolConfig = { apiKey: string; timeout?: number }
+
+// Simulate the function behavior
+function createTool(config: ToolConfig) {
+  return {
+    execute: async (query: string) => {
+      console.log(\`Searching for: \${query}\`)
+      return { results: ['result1', 'result2'] }
+    }
+  }
+}
+
+// Usage example
+const tool = createTool({
+  apiKey: process.env.MY_API_KEY || 'your-api-key-here'
+})
+
+async function main() {
+  try {
+    const result = await tool.execute('my query')
+    console.log('Results:', result)
+    // Output: { results: ['result1', 'result2'] }
+  } catch (error) {
+    console.error('Failed:', error)
+  }
+}
+
+main()
+\`\`\`
+
+Output format:
+---MARKDOWN---
+[Your markdown documentation with parameter table]
+---CODE---
+[Your SELF-CONTAINED, EXECUTABLE code example]
+---END---`;
+function buildDocPrompt(element, multiLanguage = false) {
+    let prompt = `Generate documentation for this ${element.kind}:\n\n`;
+    prompt += `**Name:** ${element.name}\n`;
+    prompt += `**Signature:** ${element.signature}\n`;
+    if (element.parentClass) {
+        prompt += `**Class:** ${element.parentClass}\n`;
+    }
+    if (element.packageName && element.packageName !== 'unknown') {
+        prompt += `**Package:** ${element.packageName} (DO NOT import from this - make example self-contained)\n`;
+    }
+    if (element.parameters.length > 0) {
+        prompt += `\n**Parameters:**\n`;
+        for (const param of element.parameters) {
+            prompt += `- ${param.name}`;
+            if (param.type)
+                prompt += `: ${param.type}`;
+            if (param.default)
+                prompt += ` = ${param.default}`;
+            prompt += '\n';
+        }
+    }
+    if (element.returnType) {
+        prompt += `\n**Returns:** ${element.returnType}\n`;
+    }
+    if (element.docstring) {
+        prompt += `\n**Existing docstring:**\n${element.docstring}\n`;
+    }
+    if (element.sourceContext) {
+        prompt += `\n**Source context (for understanding, not for importing):**\n\`\`\`\n${element.sourceContext}\n\`\`\`\n`;
+    }
+    if (element.imports && element.imports.length > 0) {
+        prompt += `\n**File imports (shows dependencies - your example should NOT use these):**\n`;
+        prompt += element.imports.slice(0, 5).join('\n') + '\n';
+    }
+    if (multiLanguage) {
+        prompt += `\n**IMPORTANT:** Generate BOTH TypeScript AND Python self-contained examples.`;
+    }
+    else {
+        prompt += `\n**IMPORTANT:** Generate a SELF-CONTAINED example that runs without any external imports.`;
+    }
+    return prompt;
+}
+function parseDocResponse(content) {
+    // Extract markdown section
+    const markdownMatch = content.match(/---MARKDOWN---\s*([\s\S]*?)\s*---CODE---/);
+    const markdown = markdownMatch?.[1]?.trim() || content;
+    // Extract code section
+    const codeMatch = content.match(/---CODE---\s*([\s\S]*?)\s*---END---/);
+    let codeExample = codeMatch?.[1]?.trim() || '';
+    // Clean up code fences if present
+    codeExample = codeExample.replace(/^```\w*\n?/, '').replace(/\n?```$/, '');
+    return { markdown, codeExample, typescriptExample: codeExample };
+}
+function parseMultiLangResponse(content) {
+    // Extract markdown section
+    const markdownMatch = content.match(/---MARKDOWN---\s*([\s\S]*?)\s*---TYPESCRIPT---/);
+    const markdown = markdownMatch?.[1]?.trim() || '';
+    // Extract TypeScript section
+    const tsMatch = content.match(/---TYPESCRIPT---\s*([\s\S]*?)\s*---PYTHON---/);
+    let typescriptExample = tsMatch?.[1]?.trim() || '';
+    typescriptExample = typescriptExample.replace(/^```\w*\n?/, '').replace(/\n?```$/, '');
+    // Extract Python section
+    const pyMatch = content.match(/---PYTHON---\s*([\s\S]*?)\s*---END---/);
+    let pythonExample = pyMatch?.[1]?.trim() || '';
+    pythonExample = pythonExample.replace(/^```\w*\n?/, '').replace(/\n?```$/, '');
+    // Primary code example is TypeScript (for backwards compat)
+    return {
+        markdown,
+        codeExample: typescriptExample,
+        typescriptExample,
+        pythonExample
+    };
+}
+/**
+ * Helper to fix a broken code sample with smart strategies
+ */
+export async function fixCodeSample(client, code, error, context, iteration = 1) {
+    // Analyze error type to provide better fix guidance
+    const fixStrategy = analyzeErrorAndGetStrategy(error, code);
+    const response = await client.complete({
+        messages: [
+            {
+                role: 'system',
+                content: FIX_SYSTEM_PROMPT
+            },
+            {
+                role: 'user',
+                content: `Fix this code example. It must be COMPLETELY SELF-CONTAINED and runnable.
+
+**Current code:**
+\`\`\`
+${code}
+\`\`\`
+
+**Error:**
+${error}
+
+**Fix strategy:** ${fixStrategy}
+
+**Context:**
+${context}
+
+**Iteration ${iteration}:** ${iteration > 2 ? 'SIMPLIFY the example drastically - focus on demonstrating the concept, not real functionality.' : 'Make it self-contained.'}
+
+Return ONLY the fixed code, no explanations or markdown fences.`
+            }
+        ],
+        temperature: iteration > 3 ? 0.3 : 0, // Add creativity on later iterations
+        maxTokens: 1024
+    });
+    // Clean up any markdown fences
+    return response.content
+        .replace(/^```\w*\n?/, '')
+        .replace(/\n?```$/, '')
+        .trim();
+}
+const FIX_SYSTEM_PROMPT = `You are fixing a documentation code example to make it SELF-CONTAINED and RUNNABLE.
+
+## Fix Strategies by Error Type
+
+**Import/Module errors ("Cannot find module", "is not defined"):**
+- DO NOT try to fix the import
+- INLINE the type definitions
+- MOCK the function behavior with a simple implementation
+- Show what the function WOULD do conceptually
+
+**Type errors ("Type X is not assignable"):**
+- Define the type inline with \`type X = {...}\`
+- Use simpler types if complex ones cause issues
+
+**Runtime errors ("undefined is not a function", "Cannot read property"):**
+- Initialize all variables
+- Add null checks
+- Use optional chaining (?.)
+
+**Async errors ("await is only valid in async"):**
+- Wrap in async function
+- Add proper try/catch
+- Call the async function at the end
+
+## Example Fix Pattern
+If the error is "Cannot find module '@mylib/tools'":
+
+WRONG (trying to fix import):
+\`\`\`
+import { tool } from '@mylib/tools-v2' // Still fails
+\`\`\`
+
+RIGHT (inline everything):
+\`\`\`
+// Define types inline
+type ToolResult = { data: string[] }
+
+// Mock the tool behavior
+const tool = {
+  search: async (query: string): Promise<ToolResult> => {
+    // Simulated behavior
+    return { data: ['result1', 'result2'] }
+  }
+}
+
+// Usage
+async function main() {
+  const result = await tool.search('test')
+  console.log(result) // { data: ['result1', 'result2'] }
+}
+main()
+\`\`\`
+
+Return ONLY the fixed code.`;
+function analyzeErrorAndGetStrategy(error, _code) {
+    const errorLower = error.toLowerCase();
+    if (errorLower.includes('cannot find module') || errorLower.includes('module not found')) {
+        const importMatch = error.match(/['"]([^'"]+)['"]/)?.[1] || 'the library';
+        return `IMPORT ERROR: Cannot import from "${importMatch}". Remove ALL imports and inline types/mock functions instead.`;
+    }
+    if (errorLower.includes('is not defined') || errorLower.includes('is not a function')) {
+        const undefinedMatch = error.match(/(\w+) is not (defined|a function)/)?.[1];
+        return `UNDEFINED: "${undefinedMatch}" is not available. Define it inline or mock it.`;
+    }
+    if (errorLower.includes('type') && (errorLower.includes('assignable') || errorLower.includes('missing'))) {
+        return `TYPE ERROR: Type mismatch. Simplify types or define them inline with correct structure.`;
+    }
+    if (errorLower.includes('await') && errorLower.includes('async')) {
+        return `ASYNC ERROR: Wrap code in async function and call it: async function main() {...} main()`;
+    }
+    if (errorLower.includes('timeout') || errorLower.includes('timed out')) {
+        return `TIMEOUT: Code took too long. Remove any actual API calls or network requests. Use mock data.`;
+    }
+    if (errorLower.includes('syntaxerror') || errorLower.includes('unexpected token')) {
+        return `SYNTAX ERROR: Fix syntax issues. Check for missing brackets, quotes, or semicolons.`;
+    }
+    return `GENERAL: Make the code self-contained. Define all types inline, mock all external calls, use try/catch.`;
+}

package/dist/llm/llm.manual-test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/llm/llm.manual-test.js

@@ -0,0 +1,112 @@
+import { createLLMClient, generateDocumentation, fixCodeSample } from './index.js';
+import { PROVIDER_ENV_KEYS } from '../config/types.js';
+async function runTests() {
+    console.log('=== LLM Client Tests ===\n');
+    // Find an available provider
+    const providers = ['deepseek', 'openai', 'anthropic', 'google', 'openrouter', 'ollama'];
+    let availableProvider = null;
+    let availableModel = null;
+    for (const provider of providers) {
+        const envKey = PROVIDER_ENV_KEYS[provider];
+        if (!envKey || process.env[envKey]) {
+            availableProvider = provider;
+            availableModel = getTestModel(provider);
+            break;
+        }
+    }
+    if (!availableProvider) {
+        console.log('No LLM provider available. Set one of these env vars:');
+        console.log('  DEEPSEEK_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY,');
+        console.log('  GOOGLE_API_KEY, OPENROUTER_API_KEY, or run Ollama locally');
+        process.exit(0);
+    }
+    console.log(`Using provider: ${availableProvider} (${availableModel})`);
+    console.log('');
+    // Test 1: Create client
+    console.log('Test 1: Create LLM client');
+    const client = createLLMClient({
+        provider: availableProvider,
+        model: availableModel
+    });
+    console.log(`  provider: ${client.provider}`);
+    console.log('  ✓ client created\n');
+    // Test 2: Simple completion
+    console.log('Test 2: Simple completion');
+    try {
+        const response = await client.complete({
+            messages: [
+                { role: 'user', content: 'Say "hello" and nothing else.' }
+            ],
+            maxTokens: 10
+        });
+        console.log(`  response: "${response.content.trim()}"`);
+        console.log(`  model: ${response.model}`);
+        console.log(`  tokens: ${response.usage.totalTokens}`);
+        console.log('  ✓ completion works\n');
+    }
+    catch (err) {
+        console.log(`  ✗ completion failed: ${err}`);
+        process.exit(1);
+    }
+    // Test 3: Generate documentation
+    console.log('Test 3: Generate documentation');
+    try {
+        const result = await generateDocumentation(client, {
+            kind: 'function',
+            name: 'add',
+            signature: 'def add(a: int, b: int) -> int',
+            parameters: [
+                { name: 'a', type: 'int' },
+                { name: 'b', type: 'int' }
+            ],
+            returnType: 'int',
+            docstring: 'Add two numbers together.'
+        });
+        console.log(`  markdown length: ${result.markdown.length} chars`);
+        console.log(`  code example length: ${result.codeExample.length} chars`);
+        if (result.codeExample.includes('add(')) {
+            console.log('  ✓ code example calls the function\n');
+        }
+        else {
+            console.log(`  code example:\n${result.codeExample}`);
+            console.log('  ⚠ code example might not call the function\n');
+        }
+    }
+    catch (err) {
+        console.log(`  ✗ doc generation failed: ${err}`);
+        process.exit(1);
+    }
+    // Test 4: Fix broken code
+    console.log('Test 4: Fix broken code');
+    try {
+        const fixed = await fixCodeSample(client, 'print(add(1, 2)', // Missing closing paren
+        'SyntaxError: unexpected EOF while parsing', 'This is a code example for the add function');
+        console.log(`  fixed code: ${fixed}`);
+        if (fixed.includes(')')) {
+            console.log('  ✓ code was fixed\n');
+        }
+        else {
+            console.log('  ⚠ fix might be incomplete\n');
+        }
+    }
+    catch (err) {
+        console.log(`  ✗ code fix failed: ${err}`);
+        process.exit(1);
+    }
+    console.log('✓ All LLM client tests passed');
+}
+function getTestModel(provider) {
+    switch (provider) {
+        case 'deepseek': return 'deepseek-chat';
+        case 'openai': return 'gpt-4o-mini';
+        case 'anthropic': return 'claude-sonnet-4-5-20241022';
+        case 'google': return 'gemini-2.0-flash';
+        case 'ollama': return 'llama3.2:1b'; // Small model for testing
+        case 'openrouter': return 'openai/gpt-4o-mini';
+        default: return 'gpt-4o-mini';
+    }
+}
+runTests().catch(err => {
+    console.error('Test failed:', err);
+    process.exit(1);
+});

package/dist/llm/llm.mock-test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Mock tests for LLM client - tests structure without API calls
+ */
+export {};