@ebowwa/ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ebowwa Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @ebowwa/ai
+
+AI/LLM client utilities and GLM API integration with OpenAI-compatible protocol support.
+
+## Features
+
+- **OpenAI-Compatible Protocol**: Full support for OpenAI-compatible APIs
+- **GLM-4.7 Integration**: Optimized for Z.AI GLM models (GLM-4.7, GLM-4.6, GLM-4.5, GLM-4.5-air)
+- **Streaming Support**: Server-Sent Events (SSE) streaming for real-time responses
+- **Type-Safe**: Built with TypeScript and Zod for runtime validation
+- **Retry Logic**: Exponential backoff with configurable retries
+- **Timeout Handling**: Configurable timeouts with AbortController
+- **Error Handling**: Specific error types (Timeout, Auth, RateLimit, Network)
+- **Prompt Architecture**: Composable prompt building utilities
+
+## Installation
+
+```bash
+npm install @ebowwa/ai
+```
+
+## Usage
+
+### Basic Chat Completion
+
+```typescript
+import { GLMClient } from '@ebowwa/ai/client';
+
+const client = new GLMClient('your-api-key');
+
+const response = await client.chatCompletion([
+  { role: 'user', content: 'Hello, how are you?' }
+]);
+
+console.log(response.choices[0].message.content);
+```
+
+### Streaming
+
+```typescript
+import { GLMClient } from '@ebowwa/ai/client';
+
+const client = new GLMClient('your-api-key');
+
+for await (const chunk of client.streamGenerate('Tell me a story')) {
+  if (chunk.type === 'text') {
+    process.stdout.write(chunk.content);
+  }
+}
+```
+
+### Prompt Building
+
+```typescript
+import { PromptBuilder } from '@ebowwa/ai/prompts';
+
+const prompt = new PromptBuilder()
+  .system('helpful assistant', ['Be concise', 'Use examples'])
+  .context({ topic: 'programming' })
+  .task('Explain async/await in JavaScript')
+  .build();
+
+const response = await client.generate(prompt);
+```
+
+## API Reference
+
+### GLMClient
+
+Main client for AI chat completions.
+
+- `chatCompletion(messages, options)` - Non-streaming chat completion
+- `generate(prompt, options)` - Simple prompt generation
+- `generateWithSystem(systemPrompt, userPrompt, options)` - Generate with system prompt
+- `streamChatCompletion(messages, options)` - Streaming chat completion
+- `streamGenerate(prompt, options)` - Streaming simple prompt
+- `streamGenerateWithSystem(systemPrompt, userPrompt, options)` - Streaming with system prompt
+
+### PromptBuilder
+
+Composable prompt architecture for scalable AI interactions.
+
+- `system(role, guidelines)` - Set AI role and behavior
+- `context(data)` - Add context data
+- `examples(examples)` - Add few-shot examples
+- `output(type, schema)` - Specify output format
+- `constraints(...rules)` - Add constraints/rules
+- `task(instruction)` - Add main task/instruction
+- `build()` - Build final prompt string
+- `buildChat()` - Build for chat completion (returns messages array)
+
+## Environment Variables
+
+Set your API key via environment variables:
+
+- `Z_AI_API_KEY` - Primary API key
+- `ZAI_API_KEY` - Alternative API key
+- `GLM_API_KEY` - GLM-specific API key
+
+## License
+
+MIT
+
+## Author
+
+Ebowwa Labs <labs@ebowwa.com>

package/dist/client.d.ts

@@ -0,0 +1,179 @@
+/**
+ * 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)
+ */
+declare const fetch: typeof globalThis.fetch;
+import { type ChatCompletionOptions, type ChatMessage, type ChatCompletionResponse, type StreamChunk } from "./schemas/ai.js";
+/**
+ * Custom error types for better error handling
+ */
+export declare class GLMTimeoutError extends Error {
+    constructor(message: string);
+}
+export declare class GLMAuthError extends Error {
+    constructor(message: string);
+}
+export declare class GLMRateLimitError extends Error {
+    constructor(message: string);
+}
+export declare class GLMNetworkError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * GLM-4.7 Client for OpenAI-compatible API
+ * Includes timeout handling, retry logic, and detailed error reporting
+ */
+export declare class GLMClient {
+    private apiKey;
+    private baseURL;
+    private fetchImpl;
+    constructor(apiKey?: string, baseURL?: string, fetchImpl?: typeof fetch);
+    /**
+     * Make a request to the GLM API with timeout and retry logic (for non-streaming)
+     */
+    private requestWithRetry;
+    /**
+     * Make a streaming request to the GLM API with timeout and retry logic
+     * Returns the raw Response object for SSE parsing
+     */
+    private requestStream;
+    /**
+     * Public request method (backward compatibility)
+     */
+    request<T>(endpoint: string, options?: RequestInit): Promise<{
+        data: T;
+        latencyMs: number;
+    }>;
+    /**
+     * Validate and parse chat messages using Zod schema
+     */
+    private validateMessages;
+    /**
+     * Validate and parse chat completion options using Zod schema
+     */
+    private parseOptions;
+    /**
+     * Convert raw API response to internal format with Zod validation
+     */
+    private convertResponse;
+    /**
+     * Create a chat completion (non-streaming)
+     * Maps API response (snake_case) to internal types (camelCase)
+     * Includes latency tracking and configurable timeout
+     */
+    chatCompletion(messages: ChatMessage[], options?: Partial<ChatCompletionOptions>): Promise<ChatCompletionResponse>;
+    /**
+     * Simple generate method for quick prompts (non-streaming)
+     */
+    generate(prompt: string, options?: Partial<Omit<ChatCompletionOptions, "stream">>): Promise<string>;
+    /**
+     * Generate with system prompt (non-streaming)
+     */
+    generateWithSystem(systemPrompt: string, userPrompt: string, options?: Partial<Omit<ChatCompletionOptions, "stream">>): Promise<string>;
+    /**
+     * 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!');
+     *   }
+     * }
+     * ```
+     */
+    streamChatCompletion(messages: ChatMessage[], options?: Partial<ChatCompletionOptions>): AsyncGenerator<StreamChunk, void, unknown>;
+    /**
+     * 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);
+     *   }
+     * }
+     * ```
+     */
+    streamGenerate(prompt: string, options?: Partial<ChatCompletionOptions>): AsyncGenerator<StreamChunk, void, unknown>;
+    /**
+     * 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);
+     *   }
+     * }
+     * ```
+     */
+    streamGenerateWithSystem(systemPrompt: string, userPrompt: string, options?: Partial<ChatCompletionOptions>): AsyncGenerator<StreamChunk, void, unknown>;
+}
+export declare function getGLMClient(): GLMClient | null;
+export type * from "./schemas/ai.js";