@ebowwa/ai 0.1.0

package/dist/schemas/ai.js

@@ -0,0 +1,416 @@
+/**
+ * Zod schemas for AI module runtime validation
+ *
+ * Provides:
+ * - Runtime type validation for all AI operations
+ * - Type inference for TypeScript types
+ * - Safe parsing with error handling
+ * - Streaming support for Server-Sent Events
+ * - Reusable schemas across multiple AI providers
+ */
+import { z } from "zod";
+// ============================================================================
+// BASE SCHEMAS
+// ============================================================================
+/**
+ * Chat message role (OpenAI-compatible)
+ */
+export const ChatMessageRoleSchema = z.enum(["system", "user", "assistant"]);
+/**
+ * Base chat message (OpenAI-compatible)
+ */
+export const ChatMessageSchema = z.object({
+    role: ChatMessageRoleSchema,
+    content: z.string(),
+});
+/**
+ * Token usage information (camelCase)
+ */
+export const TokenUsageSchema = z.object({
+    promptTokens: z.number().int().nonnegative(),
+    completionTokens: z.number().int().nonnegative(),
+    totalTokens: z.number().int().nonnegative(),
+});
+/**
+ * Raw API usage (snake_case from most APIs)
+ */
+export const RawUsageSchema = z.object({
+    prompt_tokens: z.number().int().nonnegative(),
+    completion_tokens: z.number().int().nonnegative(),
+    total_tokens: z.number().int().nonnegative(),
+});
+// ============================================================================
+// REQUEST SCHEMAS
+// ============================================================================
+/**
+ * Base AI request options shared across all AI requests
+ */
+export const BaseAIRequestOptionsSchema = z.object({
+    model: z.string().optional(),
+    temperature: z.number().min(0).max(2).optional(),
+    maxTokens: z.number().int().positive().optional(),
+});
+/**
+ * Chat completion options (extends base with stream/timeout/retry)
+ */
+export const ChatCompletionOptionsSchema = BaseAIRequestOptionsSchema.extend({
+    stream: z.boolean().optional().default(false),
+    timeout: z.number().int().positive().optional().default(30000),
+    maxRetries: z.number().int().nonnegative().optional().default(3),
+});
+/**
+ * Simple prompt-based AI request
+ */
+export const AIRequestSchema = BaseAIRequestOptionsSchema.extend({
+    prompt: z.string(),
+    systemPrompt: z.string().optional(),
+});
+/**
+ * Multi-turn chat request
+ */
+export const AIChatRequestSchema = BaseAIRequestOptionsSchema.extend({
+    messages: z.array(ChatMessageSchema).min(1),
+});
+// ============================================================================
+// RESPONSE SCHEMAS
+// ============================================================================
+/**
+ * Latency information
+ */
+export const LatencyInfoSchema = z.object({
+    totalMs: z.number().nonnegative(),
+    formatted: z.string(),
+});
+/**
+ * Raw API response choice (snake_case from API)
+ */
+export const RawChoiceSchema = z.object({
+    index: z.number().int().nonnegative(),
+    message: z.object({
+        role: z.string(),
+        content: z.string(),
+    }),
+    finish_reason: z.string(),
+});
+/**
+ * Raw chat completion response from API (snake_case)
+ */
+export const RawChatCompletionResponseSchema = z.object({
+    id: z.string(),
+    object: z.string(),
+    created: z.number().int().nonnegative(),
+    model: z.string(),
+    choices: z.array(RawChoiceSchema).min(1),
+    usage: RawUsageSchema.optional(),
+});
+/**
+ * Chat completion response (internal camelCase)
+ */
+export const ChatCompletionResponseSchema = z.object({
+    id: z.string(),
+    object: z.string(),
+    created: z.number().int().nonnegative(),
+    model: z.string(),
+    choices: z
+        .array(z.object({
+        index: z.number().int().nonnegative(),
+        message: z.object({
+            role: z.string(),
+            content: z.string(),
+        }),
+        finish_reason: z.string(),
+    }))
+        .min(1),
+    usage: TokenUsageSchema.optional(),
+    latency: LatencyInfoSchema.optional(),
+});
+/**
+ * Simple AI response
+ */
+export const AIResponseSchema = z.object({
+    success: z.boolean(),
+    content: z.string().optional(),
+    error: z.string().optional(),
+    usage: TokenUsageSchema.optional(),
+});
+/**
+ * Chat response
+ */
+export const AIChatResponseSchema = z.object({
+    success: z.boolean(),
+    message: z.string().optional(),
+    usage: TokenUsageSchema.optional(),
+    error: z.string().optional(),
+});
+// ============================================================================
+// STREAMING SCHEMAS
+// ============================================================================
+/**
+ * Stream delta content (incremental content from streaming responses)
+ */
+export const StreamDeltaSchema = z.object({
+    role: z.string().optional(),
+    content: z.string().optional(),
+});
+/**
+ * Stream chunk type
+ */
+export const StreamChunkTypeSchema = z.enum(["text", "done", "error"]);
+/**
+ * Raw stream chunk from API (snake_case)
+ */
+export const RawStreamChunkSchema = z.object({
+    id: z.string(),
+    object: z.string(),
+    created: z.number().int().nonnegative(),
+    model: z.string(),
+    choices: z
+        .array(z.object({
+        index: z.number().int().nonnegative(),
+        delta: StreamDeltaSchema,
+        finish_reason: z.string().nullable().optional(),
+    }))
+        .min(1),
+    usage: RawUsageSchema.optional(),
+});
+/**
+ * Processed stream chunk (internal camelCase)
+ */
+export const StreamChunkSchema = z.object({
+    type: StreamChunkTypeSchema,
+    id: z.string().optional(),
+    content: z.string().optional(),
+    finishReason: z.string().optional(),
+    usage: TokenUsageSchema.optional(),
+    error: z.string().optional(),
+});
+// ============================================================================
+// ERROR SCHEMAS
+// ============================================================================
+/**
+ * Generic API error response (most providers use this format)
+ */
+export const APIErrorResponseSchema = z.object({
+    error: z
+        .object({
+        message: z.string(),
+        type: z.string().optional(),
+        code: z.string().optional(),
+    })
+        .optional(),
+});
+/**
+ * Error types categorization
+ */
+export const ErrorTypeSchema = z.enum([
+    "timeout",
+    "auth",
+    "rate_limit",
+    "network",
+    "validation",
+    "unknown",
+]);
+// ============================================================================
+// VALIDATION HELPERS
+// ============================================================================
+/**
+ * Validate chat message
+ */
+export function validateChatMessage(data) {
+    return ChatMessageSchema.safeParse(data);
+}
+/**
+ * Validate chat messages array
+ */
+export function validateChatMessages(data) {
+    return z.array(ChatMessageSchema).min(1).safeParse(data);
+}
+/**
+ * Validate chat completion options
+ */
+export function validateChatCompletionOptions(data) {
+    return ChatCompletionOptionsSchema.safeParse(data);
+}
+/**
+ * Validate raw API response
+ */
+export function validateRawResponse(data) {
+    return RawChatCompletionResponseSchema.safeParse(data);
+}
+/**
+ * Validate and convert raw usage to internal format
+ */
+export function convertUsage(raw) {
+    const result = RawUsageSchema.safeParse(raw);
+    if (!result.success)
+        return null;
+    return {
+        promptTokens: result.data.prompt_tokens,
+        completionTokens: result.data.completion_tokens,
+        totalTokens: result.data.total_tokens,
+    };
+}
+/**
+ * Categorize error from unknown data
+ * Generic error categorization that works across providers
+ */
+export function categorizeError(data) {
+    if (data instanceof Error) {
+        if (data.message.includes("timeout")) {
+            return "timeout";
+        }
+        if (data.message.includes("unauthorized") || data.message.includes("401")) {
+            return "auth";
+        }
+        if (data.message.includes("rate limit") || data.message.includes("429")) {
+            return "rate_limit";
+        }
+        if (data instanceof TypeError || data.message.includes("fetch")) {
+            return "network";
+        }
+    }
+    const errorResult = APIErrorResponseSchema.safeParse(data);
+    if (errorResult.success && errorResult.data.error) {
+        const errorMsg = errorResult.data.error.message.toLowerCase();
+        if (errorMsg.includes("timeout"))
+            return "timeout";
+        if (errorMsg.includes("unauthorized") ||
+            errorMsg.includes("invalid api key") ||
+            errorMsg.includes("401"))
+            return "auth";
+        if (errorMsg.includes("rate limit") || errorMsg.includes("429"))
+            return "rate_limit";
+    }
+    return "unknown";
+}
+// ============================================================================
+// STREAMING HELPERS
+// ============================================================================
+/**
+ * Parse a single SSE line
+ * Returns null if line is empty or just whitespace
+ */
+export function parseSSERow(line) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed === "")
+        return null;
+    if (!trimmed.startsWith("data: "))
+        return null;
+    const data = trimmed.slice(6);
+    if (data === "[DONE]")
+        return data;
+    return data;
+}
+/**
+ * Parse SSE response body and yield stream chunks
+ * Converts raw SSE lines to processed StreamChunk objects
+ */
+export async function* parseSSEStream(response) {
+    if (!response.body) {
+        yield {
+            type: "error",
+            error: "Response body is null",
+        };
+        return;
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop() || ""; // Keep the last incomplete line in buffer
+            for (const line of lines) {
+                const data = parseSSERow(line);
+                if (!data)
+                    continue;
+                if (data === "[DONE]") {
+                    yield {
+                        type: "done",
+                    };
+                    return;
+                }
+                try {
+                    const raw = JSON.parse(data);
+                    const rawChunkResult = RawStreamChunkSchema.safeParse(raw);
+                    if (!rawChunkResult.success) {
+                        yield {
+                            type: "error",
+                            error: `Invalid stream chunk: ${rawChunkResult.error.message}`,
+                        };
+                        continue;
+                    }
+                    const rawChunk = rawChunkResult.data;
+                    const delta = rawChunk.choices[0].delta;
+                    // Convert usage if present (usually only in final chunk)
+                    const usage = rawChunk.usage
+                        ? {
+                            promptTokens: rawChunk.usage.prompt_tokens,
+                            completionTokens: rawChunk.usage.completion_tokens,
+                            totalTokens: rawChunk.usage.total_tokens,
+                        }
+                        : undefined;
+                    yield {
+                        type: "text",
+                        id: rawChunk.id,
+                        content: delta.content || "",
+                        finishReason: rawChunk.choices[0].finish_reason || undefined,
+                        usage,
+                    };
+                }
+                catch (error) {
+                    yield {
+                        type: "error",
+                        error: `Failed to parse stream chunk: ${error instanceof Error ? error.message : String(error)}`,
+                    };
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+// ============================================================================
+// EXPORTS
+// ============================================================================
+export default {
+    // Messages
+    ChatMessageSchema,
+    ChatMessageRoleSchema,
+    // Usage
+    TokenUsageSchema,
+    RawUsageSchema,
+    // Requests
+    BaseAIRequestOptionsSchema,
+    ChatCompletionOptionsSchema,
+    AIRequestSchema,
+    AIChatRequestSchema,
+    // Responses
+    LatencyInfoSchema,
+    RawChatCompletionResponseSchema,
+    ChatCompletionResponseSchema,
+    AIResponseSchema,
+    AIChatResponseSchema,
+    // Streaming
+    StreamDeltaSchema,
+    StreamChunkTypeSchema,
+    RawStreamChunkSchema,
+    StreamChunkSchema,
+    // Errors
+    APIErrorResponseSchema,
+    ErrorTypeSchema,
+    // Helpers
+    validateChatMessage,
+    validateChatMessages,
+    validateChatCompletionOptions,
+    validateRawResponse,
+    convertUsage,
+    categorizeError,
+    parseSSERow,
+    parseSSEStream,
+};

package/dist/schemas/glm.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Zod schemas for Z.AI GLM API
+ *
+ * Provider-specific schemas for Z.AI (GLM) models.
+ * Generic AI schemas (chat messages, streaming, etc.) are in ./ai.ts
+ */
+import { z } from "zod";
+/**
+ * Available GLM models from Z.AI API
+ */
+export declare const GLMModelSchema: z.ZodEnum<["GLM-4.7", "GLM-4.6", "GLM-4.5", "GLM-4.5-air"]>;
+export type GLMModel = z.infer<typeof GLMModelSchema>;
+declare const _default: {
+    GLMModelSchema: z.ZodEnum<["GLM-4.7", "GLM-4.6", "GLM-4.5", "GLM-4.5-air"]>;
+};
+export default _default;

package/dist/schemas/glm.js

@@ -0,0 +1,25 @@
+/**
+ * Zod schemas for Z.AI GLM API
+ *
+ * Provider-specific schemas for Z.AI (GLM) models.
+ * Generic AI schemas (chat messages, streaming, etc.) are in ./ai.ts
+ */
+import { z } from "zod";
+// ============================================================================
+// Z.AI GLM MODELS
+// ============================================================================
+/**
+ * Available GLM models from Z.AI API
+ */
+export const GLMModelSchema = z.enum([
+    "GLM-4.7",
+    "GLM-4.6",
+    "GLM-4.5",
+    "GLM-4.5-air",
+]);
+// ============================================================================
+// EXPORTS
+// ============================================================================
+export default {
+    GLMModelSchema,
+};

package/dist/schemas/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Schemas module exports
+ */
+export * from './ai.js';
+export * from './glm.js';

package/dist/schemas/index.js

@@ -0,0 +1,5 @@
+/**
+ * Schemas module exports
+ */
+export * from './ai.js';
+export * from './glm.js';

package/dist/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OpenAI protocol related types for the application
+ *
+ * This file now re-exports types from schema.ts for backward compatibility.
+ * New code should import directly from schema.ts.
+ *
+ * Schema provides:
+ * - Runtime validation with Zod
+ * - Type inference for TypeScript
+ * - Helper functions for validation
+ */
+export type * from "./schemas/ai.js";
+export { validateChatMessage, validateChatMessages, validateChatCompletionOptions, validateRawResponse, convertUsage, categorizeError, } from "./schemas/ai.js";

package/dist/types.js

@@ -0,0 +1,13 @@
+/**
+ * OpenAI protocol related types for the application
+ *
+ * This file now re-exports types from schema.ts for backward compatibility.
+ * New code should import directly from schema.ts.
+ *
+ * Schema provides:
+ * - Runtime validation with Zod
+ * - Type inference for TypeScript
+ * - Helper functions for validation
+ */
+// Re-export validation helpers for convenience
+export { validateChatMessage, validateChatMessages, validateChatCompletionOptions, validateRawResponse, convertUsage, categorizeError, } from "./schemas/ai.js";

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@ebowwa/ai",
+  "version": "0.1.0",
+  "description": "AI/LLM client utilities and GLM API integration",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./prompts": {
+      "types": "./dist/prompts.d.ts",
+      "import": "./dist/prompts.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js"
+    },
+    "./schemas/ai": {
+      "types": "./dist/schemas/ai.d.ts",
+      "import": "./dist/schemas/ai.js"
+    },
+    "./schemas/glm": {
+      "types": "./dist/schemas/glm.d.ts",
+      "import": "./dist/schemas/glm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "glm",
+    "openai",
+    "chat",
+    "streaming",
+    "zod",
+    "typescript"
+  ],
+  "author": "Ebowwa Labs <labs@ebowwa.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/ebowwa/ai#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ebowwa/ai.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ebowwa/ai/issues"
+  },
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}