@ebowwa/ai 0.1.0

package/dist/client.js

@@ -0,0 +1,492 @@
+/**
+ * GLM-4.7 AI Client using Z.AI OpenAI-compatible endpoint
+ *
+ * Based on documentation from: https://api.z.ai/api/coding/paas/v4
+ *
+ * Usage with any OpenAI-compatible client library:
+ * - Base URL: https://api.z.ai/api/coding/paas/v4
+ * - Models: GLM-4.7, GLM-4.6, GLM-4.5, GLM-4.5-air
+ *
+ * === LAYER 1: OpenAI Protocol Implementation ===
+ *
+ * This client implements the OpenAI-compatible protocol with:
+ * - 30s default timeout (configurable)
+ * - 3 retries with exponential backoff (1s → 2s → 4s, max 10s)
+ * - Specific error types: GLMTimeoutError, GLMAuthError, GLMRateLimitError, GLMNetworkError
+ * - AbortController for cancellation
+ * - Runtime validation with Zod schemas
+ * - SSE streaming support (NOW IMPLEMENTED)
+ *
+ * LAYER 2 (CLI Wrapper) concerns:
+ * - MCP plugin system → See docs/CLI-ARCHITECTURE.md
+ * - Session persistence → See docs/CLI-ARCHITECTURE.md
+ * - TUI/Ink rendering → See docs/CLI-ARCHITECTURE.md
+ *
+ * === STREAMING (Layer 1 - OpenAI Protocol) ===
+ *
+ * Streaming is now fully implemented with SSE (Server-Sent Events) parsing:
+ * - streamChatCompletion() - full chat streaming with StreamChunk objects
+ * - streamGenerate() - simple prompt streaming
+ * - streamGenerateWithSystem() - streaming with system prompt
+ *
+ * Each method returns an AsyncGenerator that yields StreamChunk objects:
+ * - type: "text" - contains incremental content in `content` field
+ * - type: "done" - stream complete
+ * - type: "error" - error occurred (check `error` field)
+ *
+ * Final chunk includes usage information (prompt_tokens, completion_tokens, total_tokens)
+ */
+import { z } from "zod";
+import { ChatCompletionOptionsSchema, ChatMessageSchema, TokenUsageSchema, LatencyInfoSchema, ChatCompletionResponseSchema, RawChatCompletionResponseSchema, } from "./schemas/ai.js";
+import { parseSSEStream } from "./schemas/ai.js";
+const GLM_API_BASE = "https://api.z.ai/api/coding/paas/v4";
+const DEFAULT_TIMEOUT = 30000; // 30 seconds
+const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Custom error types for better error handling
+ */
+export class GLMTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GLMTimeoutError";
+    }
+}
+export class GLMAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GLMAuthError";
+    }
+}
+export class GLMRateLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GLMRateLimitError";
+    }
+}
+export class GLMNetworkError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "GLMNetworkError";
+    }
+}
+/**
+ * Resolve GLM API key from environment or explicit parameter
+ */
+function resolveApiKey(apiKey) {
+    if (apiKey)
+        return apiKey;
+    if (process.env.Z_AI_API_KEY)
+        return process.env.Z_AI_API_KEY;
+    if (process.env.ZAI_API_KEY)
+        return process.env.ZAI_API_KEY;
+    if (process.env.GLM_API_KEY)
+        return process.env.GLM_API_KEY;
+    throw new Error("GLM API key not found. Set Z_AI_API_KEY, ZAI_API_KEY, or GLM_API_KEY environment variable.");
+}
+/**
+ * Format milliseconds to human-readable string
+ */
+function formatLatency(ms) {
+    if (ms < 1000)
+        return `${ms.toFixed(0)}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(2)}s`;
+    return `${(ms / 60000).toFixed(2)}m`;
+}
+/**
+ * Sleep for a specified duration (for retry backoff)
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Calculate exponential backoff delay
+ */
+function calculateBackoff(retryCount, baseDelay = 1000) {
+    return Math.min(baseDelay * Math.pow(2, retryCount), 10000); // Max 10 seconds
+}
+/**
+ * Create a timeout promise that rejects after specified duration
+ */
+function createTimeoutPromise(ms) {
+    return new Promise((_, reject) => {
+        setTimeout(() => reject(new GLMTimeoutError(`Request timeout after ${ms}ms`)), ms);
+    });
+}
+/**
+ * GLM-4.7 Client for OpenAI-compatible API
+ * Includes timeout handling, retry logic, and detailed error reporting
+ */
+export class GLMClient {
+    apiKey;
+    baseURL;
+    fetchImpl;
+    constructor(apiKey, baseURL, fetchImpl) {
+        this.apiKey = resolveApiKey(apiKey);
+        this.baseURL = baseURL || GLM_API_BASE;
+        // Use injected fetch for testing, otherwise use imported fetch
+        this.fetchImpl = fetchImpl || fetch;
+    }
+    /**
+     * Make a request to the GLM API with timeout and retry logic (for non-streaming)
+     */
+    async requestWithRetry(endpoint, options = {}, timeout = DEFAULT_TIMEOUT, maxRetries = DEFAULT_MAX_RETRIES, retryCount = 0) {
+        const startTime = performance.now();
+        try {
+            // Create abort controller for timeout
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            // Race between fetch and timeout
+            const response = (await Promise.race([
+                this.fetchImpl(`${this.baseURL}${endpoint}`, {
+                    ...options,
+                    signal: controller.signal,
+                    headers: {
+                        Authorization: `Bearer ${this.apiKey}`,
+                        "Content-Type": "application/json",
+                        ...options.headers,
+                    },
+                }),
+                createTimeoutPromise(timeout),
+            ]));
+            clearTimeout(timeoutId);
+            // Handle specific HTTP status codes
+            if (response.status === 401) {
+                throw new GLMAuthError("Invalid API key or unauthorized access");
+            }
+            if (response.status === 429) {
+                throw new GLMRateLimitError("Rate limit exceeded, please retry later");
+            }
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`GLM API error: ${response.status} ${response.statusText} - ${errorText}`);
+            }
+            const data = await response.json();
+            const latencyMs = performance.now() - startTime;
+            return { data, latencyMs };
+        }
+        catch (error) {
+            const latencyMs = performance.now() - startTime;
+            // Don't retry on auth errors or if we've exhausted retries
+            if (error instanceof GLMAuthError || retryCount >= maxRetries) {
+                throw error;
+            }
+            // Retry on timeout, network errors, or rate limit (with backoff)
+            if (error instanceof GLMTimeoutError ||
+                error instanceof GLMRateLimitError ||
+                (error instanceof TypeError && error.message.includes("fetch"))) {
+                const backoffDelay = calculateBackoff(retryCount);
+                console.warn(`GLM API request failed (attempt ${retryCount + 1}/${maxRetries + 1}), ` +
+                    `retrying in ${backoffDelay}ms...`);
+                await sleep(backoffDelay);
+                return this.requestWithRetry(endpoint, options, timeout, maxRetries, retryCount + 1);
+            }
+            // Wrap other errors in GLMNetworkError
+            throw new GLMNetworkError(`Network error: ${error.message}`, error);
+        }
+    }
+    /**
+     * Make a streaming request to the GLM API with timeout and retry logic
+     * Returns the raw Response object for SSE parsing
+     */
+    async requestStream(endpoint, options = {}, timeout = DEFAULT_TIMEOUT, maxRetries = DEFAULT_MAX_RETRIES, retryCount = 0) {
+        try {
+            // Create abort controller for timeout
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeout);
+            // Race between fetch and timeout
+            const response = (await Promise.race([
+                this.fetchImpl(`${this.baseURL}${endpoint}`, {
+                    ...options,
+                    signal: controller.signal,
+                    headers: {
+                        Authorization: `Bearer ${this.apiKey}`,
+                        "Content-Type": "application/json",
+                        ...options.headers,
+                    },
+                }),
+                createTimeoutPromise(timeout),
+            ]));
+            clearTimeout(timeoutId);
+            // Handle specific HTTP status codes
+            if (response.status === 401) {
+                throw new GLMAuthError("Invalid API key or unauthorized access");
+            }
+            if (response.status === 429) {
+                throw new GLMRateLimitError("Rate limit exceeded, please retry later");
+            }
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`GLM API error: ${response.status} ${response.statusText} - ${errorText}`);
+            }
+            return response;
+        }
+        catch (error) {
+            // Don't retry on auth errors or if we've exhausted retries
+            if (error instanceof GLMAuthError || retryCount >= maxRetries) {
+                throw error;
+            }
+            // Retry on timeout, network errors, or rate limit (with backoff)
+            if (error instanceof GLMTimeoutError ||
+                error instanceof GLMRateLimitError ||
+                (error instanceof TypeError && error.message.includes("fetch"))) {
+                const backoffDelay = calculateBackoff(retryCount);
+                console.warn(`GLM API streaming request failed (attempt ${retryCount + 1}/${maxRetries + 1}), ` +
+                    `retrying in ${backoffDelay}ms...`);
+                await sleep(backoffDelay);
+                return this.requestStream(endpoint, options, timeout, maxRetries, retryCount + 1);
+            }
+            // Wrap other errors in GLMNetworkError
+            throw new GLMNetworkError(`Network error: ${error.message}`, error);
+        }
+    }
+    /**
+     * Public request method (backward compatibility)
+     */
+    async request(endpoint, options = {}) {
+        return this.requestWithRetry(endpoint, options, DEFAULT_TIMEOUT);
+    }
+    /**
+     * Validate and parse chat messages using Zod schema
+     */
+    validateMessages(messages) {
+        const result = z.array(ChatMessageSchema).min(1).safeParse(messages);
+        if (!result.success) {
+            throw new Error(`Invalid chat messages: ${result.error.message}`);
+        }
+        return result.data;
+    }
+    /**
+     * Validate and parse chat completion options using Zod schema
+     */
+    parseOptions(options) {
+        const result = ChatCompletionOptionsSchema.safeParse(options);
+        if (!result.success) {
+            throw new Error(`Invalid chat completion options: ${result.error.message}`);
+        }
+        return result.data;
+    }
+    /**
+     * Convert raw API response to internal format with Zod validation
+     */
+    convertResponse(raw, latencyMs) {
+        // Validate raw API response
+        const rawResult = RawChatCompletionResponseSchema.safeParse(raw);
+        if (!rawResult.success) {
+            throw new Error(`Invalid API response: ${rawResult.error.message}`);
+        }
+        const rawResponse = rawResult.data;
+        // Convert snake_case usage to camelCase
+        const usage = rawResponse.usage
+            ? {
+                promptTokens: rawResponse.usage.prompt_tokens,
+                completionTokens: rawResponse.usage.completion_tokens,
+                totalTokens: rawResponse.usage.total_tokens,
+            }
+            : undefined;
+        // Validate usage if present
+        if (usage) {
+            const usageResult = TokenUsageSchema.safeParse(usage);
+            if (!usageResult.success) {
+                throw new Error(`Invalid token usage: ${usageResult.error.message}`);
+            }
+        }
+        // Create latency info
+        const latency = {
+            totalMs: latencyMs,
+            formatted: formatLatency(latencyMs),
+        };
+        const latencyResult = LatencyInfoSchema.safeParse(latency);
+        if (!latencyResult.success) {
+            throw new Error(`Invalid latency info: ${latencyResult.error.message}`);
+        }
+        // Build final response
+        const response = {
+            id: rawResponse.id,
+            object: rawResponse.object,
+            created: rawResponse.created,
+            model: rawResponse.model,
+            choices: rawResponse.choices,
+            usage,
+            latency: latencyResult.data,
+        };
+        // Validate final response
+        const finalResult = ChatCompletionResponseSchema.safeParse(response);
+        if (!finalResult.success) {
+            throw new Error(`Invalid response format: ${finalResult.error.message}`);
+        }
+        return finalResult.data;
+    }
+    /**
+     * Create a chat completion (non-streaming)
+     * Maps API response (snake_case) to internal types (camelCase)
+     * Includes latency tracking and configurable timeout
+     */
+    async chatCompletion(messages, options = {}) {
+        // Validate inputs using Zod schemas
+        const validatedMessages = this.validateMessages(messages);
+        const validatedOptions = this.parseOptions(options);
+        const { model = "GLM-4.7", temperature = 0.7, maxTokens, stream = false, timeout = DEFAULT_TIMEOUT, maxRetries = DEFAULT_MAX_RETRIES, } = validatedOptions;
+        const body = {
+            model,
+            messages: validatedMessages,
+            temperature,
+        };
+        if (maxTokens !== undefined) {
+            body.max_tokens = maxTokens;
+        }
+        if (stream) {
+            body.stream = true;
+        }
+        // Raw API response has snake_case usage fields
+        const { data: raw, latencyMs } = await this.requestWithRetry("/chat/completions", {
+            method: "POST",
+            body: JSON.stringify(body),
+        }, timeout, maxRetries);
+        // Convert and validate response using Zod
+        return this.convertResponse(raw, latencyMs);
+    }
+    /**
+     * Simple generate method for quick prompts (non-streaming)
+     */
+    async generate(prompt, options = {}) {
+        const response = await this.chatCompletion([{ role: "user", content: prompt }], options);
+        return response.choices[0]?.message?.content || "";
+    }
+    /**
+     * Generate with system prompt (non-streaming)
+     */
+    async generateWithSystem(systemPrompt, userPrompt, options = {}) {
+        const response = await this.chatCompletion([
+            { role: "system", content: systemPrompt },
+            { role: "user", content: userPrompt },
+        ], options);
+        return response.choices[0]?.message?.content || "";
+    }
+    /**
+     * Stream a chat completion
+     *
+     * Returns an async generator that yields StreamChunk objects as they arrive.
+     * Each chunk contains incremental text content, and the final chunk includes
+     * usage information.
+     *
+     * @param messages - The chat messages to send
+     * @param options - Chat completion options (timeout, maxRetries, etc.)
+     * @returns Async generator of StreamChunk objects
+     *
+     * @example
+     * ```ts
+     * const chunks = [];
+     * for await (const chunk of client.streamChatCompletion(messages)) {
+     *   if (chunk.type === 'text') {
+     *     chunks.push(chunk.content);
+     *     process.stdout.write(chunk.content);
+     *   } else if (chunk.type === 'done') {
+     *     console.log('\nStream complete!');
+     *   }
+     * }
+     * ```
+     */
+    async *streamChatCompletion(messages, options = {}) {
+        // Validate inputs using Zod schemas
+        const validatedMessages = this.validateMessages(messages);
+        const validatedOptions = this.parseOptions(options);
+        const { model = "GLM-4.7", temperature = 0.7, maxTokens, timeout = DEFAULT_TIMEOUT, maxRetries = DEFAULT_MAX_RETRIES, } = validatedOptions;
+        const body = {
+            model,
+            messages: validatedMessages,
+            temperature,
+            stream: true, // Enable streaming
+        };
+        if (maxTokens !== undefined) {
+            body.max_tokens = maxTokens;
+        }
+        try {
+            // Make the streaming request
+            const response = await this.requestStream("/chat/completions", {
+                method: "POST",
+                body: JSON.stringify(body),
+            }, timeout, maxRetries);
+            // Parse the SSE stream and yield chunks
+            for await (const chunk of parseSSEStream(response)) {
+                yield chunk;
+            }
+        }
+        catch (error) {
+            yield {
+                type: "error",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Stream a simple prompt
+     *
+     * Returns an async generator that yields chunks of text as they arrive.
+     * Simplified interface for single-prompt streaming.
+     *
+     * @param prompt - The prompt to send
+     * @param options - Chat completion options (timeout, maxRetries, etc.)
+     * @returns Async generator of StreamChunk objects
+     *
+     * @example
+     * ```ts
+     * for await (const chunk of client.streamGenerate("Tell me a story")) {
+     *   if (chunk.type === 'text') {
+     *     process.stdout.write(chunk.content);
+     *   }
+     * }
+     * ```
+     */
+    async *streamGenerate(prompt, options = {}) {
+        yield* this.streamChatCompletion([{ role: "user", content: prompt }], options);
+    }
+    /**
+     * Stream with system prompt
+     *
+     * Returns an async generator that yields chunks of text as they arrive.
+     * Includes both system and user prompts.
+     *
+     * @param systemPrompt - The system prompt
+     * @param userPrompt - The user prompt
+     * @param options - Chat completion options (timeout, maxRetries, etc.)
+     * @returns Async generator of StreamChunk objects
+     *
+     * @example
+     * ```ts
+     * for await (const chunk of client.streamGenerateWithSystem(
+     *   "You are a helpful assistant",
+     *   "Explain quantum computing"
+     * )) {
+     *   if (chunk.type === 'text') {
+     *     process.stdout.write(chunk.content);
+     *   }
+     * }
+     * ```
+     */
+    async *streamGenerateWithSystem(systemPrompt, userPrompt, options = {}) {
+        yield* this.streamChatCompletion([
+            { role: "system", content: systemPrompt },
+            { role: "user", content: userPrompt },
+        ], options);
+    }
+}
+/**
+ * Create a singleton instance for use in the app
+ */
+let glmClient = null;
+export function getGLMClient() {
+    if (glmClient)
+        return glmClient;
+    try {
+        glmClient = new GLMClient();
+        console.log("✓ GLM-4.7 API client initialized");
+        return glmClient;
+    }
+    catch (error) {
+        console.warn("GLM API key not configured - AI features unavailable");
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AI module exports
+ *
+ * Exports:
+ * - client: GLMClient class and related error types
+ * - types: Type definitions (now re-exported from schema)
+ * - prompts: Prompt building utilities
+ * - schema: Zod schemas and validation helpers
+ *
+ * Streaming support:
+ * - streamChatCompletion: Stream chat completions with SSE
+ * - streamGenerate: Stream simple prompts
+ * - streamGenerateWithSystem: Stream with system prompt
+ * - StreamChunk: Type for stream chunks
+ */
+export * from "./client.js";
+export * from "./types.js";
+export * from "./prompts.js";
+export type * from "./schemas/ai.js";
+export type { StreamChunk, StreamChunkType, StreamDelta, RawStreamChunk, } from "./schemas/ai.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * AI module exports
+ *
+ * Exports:
+ * - client: GLMClient class and related error types
+ * - types: Type definitions (now re-exported from schema)
+ * - prompts: Prompt building utilities
+ * - schema: Zod schemas and validation helpers
+ *
+ * Streaming support:
+ * - streamChatCompletion: Stream chat completions with SSE
+ * - streamGenerate: Stream simple prompts
+ * - streamGenerateWithSystem: Stream with system prompt
+ * - StreamChunk: Type for stream chunks
+ */
+export * from "./client.js";
+export * from "./types.js";
+export * from "./prompts.js";