@ebowwa/codespaces-types 1.1.0 → 1.2.0

package/runtime/ai.js

@@ -0,0 +1,505 @@
+"use strict";
+/**
+ * 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
+ */
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorTypeSchema = exports.APIErrorResponseSchema = exports.StreamChunkSchema = exports.RawStreamChunkSchema = exports.StreamChunkTypeSchema = exports.StreamDeltaSchema = exports.AIChatResponseSchema = exports.AIResponseSchema = exports.ChatCompletionResponseSchema = exports.RawChatCompletionResponseSchema = exports.RawChoiceSchema = exports.LatencyInfoSchema = exports.AIChatModuleRequestSchema = exports.AIRequestSchema = exports.ChatCompletionOptionsSchema = exports.BaseAIRequestOptionsSchema = exports.RawUsageSchema = exports.TokenUsageSchema = exports.ChatMessageSchema = exports.ChatMessageRoleSchema = void 0;
+exports.validateChatMessage = validateChatMessage;
+exports.validateChatMessages = validateChatMessages;
+exports.validateChatCompletionOptions = validateChatCompletionOptions;
+exports.validateRawResponse = validateRawResponse;
+exports.convertUsage = convertUsage;
+exports.categorizeError = categorizeError;
+exports.parseSSERow = parseSSERow;
+exports.parseSSEStream = parseSSEStream;
+var zod_1 = require("zod");
+// ============================================================================
+// BASE SCHEMAS
+// ============================================================================
+/**
+ * Chat message role (OpenAI-compatible)
+ */
+exports.ChatMessageRoleSchema = zod_1.z.enum(["system", "user", "assistant"]);
+/**
+ * Base chat message (OpenAI-compatible)
+ */
+exports.ChatMessageSchema = zod_1.z.object({
+    role: exports.ChatMessageRoleSchema,
+    content: zod_1.z.string(),
+});
+/**
+ * Token usage information (camelCase)
+ */
+exports.TokenUsageSchema = zod_1.z.object({
+    promptTokens: zod_1.z.number().int().nonnegative(),
+    completionTokens: zod_1.z.number().int().nonnegative(),
+    totalTokens: zod_1.z.number().int().nonnegative(),
+});
+/**
+ * Raw API usage (snake_case from most APIs)
+ */
+exports.RawUsageSchema = zod_1.z.object({
+    prompt_tokens: zod_1.z.number().int().nonnegative(),
+    completion_tokens: zod_1.z.number().int().nonnegative(),
+    total_tokens: zod_1.z.number().int().nonnegative(),
+});
+// ============================================================================
+// REQUEST SCHEMAS
+// ============================================================================
+/**
+ * Base AI request options shared across all AI requests
+ */
+exports.BaseAIRequestOptionsSchema = zod_1.z.object({
+    model: zod_1.z.string().optional(),
+    temperature: zod_1.z.number().min(0).max(2).optional(),
+    maxTokens: zod_1.z.number().int().positive().optional(),
+});
+/**
+ * Chat completion options (extends base with stream/timeout/retry)
+ */
+exports.ChatCompletionOptionsSchema = exports.BaseAIRequestOptionsSchema.extend({
+    stream: zod_1.z.boolean().optional().default(false),
+    timeout: zod_1.z.number().int().positive().optional().default(30000),
+    maxRetries: zod_1.z.number().int().nonnegative().optional().default(3),
+});
+/**
+ * Simple prompt-based AI request
+ */
+exports.AIRequestSchema = exports.BaseAIRequestOptionsSchema.extend({
+    prompt: zod_1.z.string(),
+    systemPrompt: zod_1.z.string().optional(),
+});
+/**
+ * Multi-turn chat request
+ */
+exports.AIChatModuleRequestSchema = exports.BaseAIRequestOptionsSchema.extend({
+    messages: zod_1.z.array(exports.ChatMessageSchema).min(1),
+});
+// ============================================================================
+// RESPONSE SCHEMAS
+// ============================================================================
+/**
+ * Latency information
+ */
+exports.LatencyInfoSchema = zod_1.z.object({
+    totalMs: zod_1.z.number().nonnegative(),
+    formatted: zod_1.z.string(),
+});
+/**
+ * Raw API response choice (snake_case from API)
+ */
+exports.RawChoiceSchema = zod_1.z.object({
+    index: zod_1.z.number().int().nonnegative(),
+    message: zod_1.z.object({
+        role: zod_1.z.string(),
+        content: zod_1.z.string(),
+    }),
+    finish_reason: zod_1.z.string(),
+});
+/**
+ * Raw chat completion response from API (snake_case)
+ */
+exports.RawChatCompletionResponseSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    object: zod_1.z.string(),
+    created: zod_1.z.number().int().nonnegative(),
+    model: zod_1.z.string(),
+    choices: zod_1.z.array(exports.RawChoiceSchema).min(1),
+    usage: exports.RawUsageSchema.optional(),
+});
+/**
+ * Chat completion response (internal camelCase)
+ */
+exports.ChatCompletionResponseSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    object: zod_1.z.string(),
+    created: zod_1.z.number().int().nonnegative(),
+    model: zod_1.z.string(),
+    choices: zod_1.z
+        .array(zod_1.z.object({
+        index: zod_1.z.number().int().nonnegative(),
+        message: zod_1.z.object({
+            role: zod_1.z.string(),
+            content: zod_1.z.string(),
+        }),
+        finish_reason: zod_1.z.string(),
+    }))
+        .min(1),
+    usage: exports.TokenUsageSchema.optional(),
+    latency: exports.LatencyInfoSchema.optional(),
+});
+/**
+ * Simple AI response
+ */
+exports.AIResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    content: zod_1.z.string().optional(),
+    error: zod_1.z.string().optional(),
+    usage: exports.TokenUsageSchema.optional(),
+});
+/**
+ * Chat response
+ */
+exports.AIChatResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    message: zod_1.z.string().optional(),
+    usage: exports.TokenUsageSchema.optional(),
+    error: zod_1.z.string().optional(),
+});
+// ============================================================================
+// STREAMING SCHEMAS
+// ============================================================================
+/**
+ * Stream delta content (incremental content from streaming responses)
+ */
+exports.StreamDeltaSchema = zod_1.z.object({
+    role: zod_1.z.string().optional(),
+    content: zod_1.z.string().optional(),
+});
+/**
+ * Stream chunk type
+ */
+exports.StreamChunkTypeSchema = zod_1.z.enum(["text", "done", "error"]);
+/**
+ * Raw stream chunk from API (snake_case)
+ */
+exports.RawStreamChunkSchema = zod_1.z.object({
+    id: zod_1.z.string(),
+    object: zod_1.z.string(),
+    created: zod_1.z.number().int().nonnegative(),
+    model: zod_1.z.string(),
+    choices: zod_1.z
+        .array(zod_1.z.object({
+        index: zod_1.z.number().int().nonnegative(),
+        delta: exports.StreamDeltaSchema,
+        finish_reason: zod_1.z.string().nullable().optional(),
+    }))
+        .min(1),
+    usage: exports.RawUsageSchema.optional(),
+});
+/**
+ * Processed stream chunk (internal camelCase)
+ */
+exports.StreamChunkSchema = zod_1.z.object({
+    type: exports.StreamChunkTypeSchema,
+    id: zod_1.z.string().optional(),
+    content: zod_1.z.string().optional(),
+    finishReason: zod_1.z.string().optional(),
+    usage: exports.TokenUsageSchema.optional(),
+    error: zod_1.z.string().optional(),
+});
+// ============================================================================
+// ERROR SCHEMAS
+// ============================================================================
+/**
+ * Generic API error response (most providers use this format)
+ */
+exports.APIErrorResponseSchema = zod_1.z.object({
+    error: zod_1.z
+        .object({
+        message: zod_1.z.string(),
+        type: zod_1.z.string().optional(),
+        code: zod_1.z.string().optional(),
+    })
+        .optional(),
+});
+/**
+ * Error types categorization
+ */
+exports.ErrorTypeSchema = zod_1.z.enum([
+    "timeout",
+    "auth",
+    "rate_limit",
+    "network",
+    "validation",
+    "unknown",
+]);
+// ============================================================================
+// VALIDATION HELPERS
+// ============================================================================
+/**
+ * Validate chat message
+ */
+function validateChatMessage(data) {
+    return exports.ChatMessageSchema.safeParse(data);
+}
+/**
+ * Validate chat messages array
+ */
+function validateChatMessages(data) {
+    return zod_1.z.array(exports.ChatMessageSchema).min(1).safeParse(data);
+}
+/**
+ * Validate chat completion options
+ */
+function validateChatCompletionOptions(data) {
+    return exports.ChatCompletionOptionsSchema.safeParse(data);
+}
+/**
+ * Validate raw API response
+ */
+function validateRawResponse(data) {
+    return exports.RawChatCompletionResponseSchema.safeParse(data);
+}
+/**
+ * Validate and convert raw usage to internal format
+ */
+function convertUsage(raw) {
+    var result = exports.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
+ */
+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";
+        }
+    }
+    var errorResult = exports.APIErrorResponseSchema.safeParse(data);
+    if (errorResult.success && errorResult.data.error) {
+        var 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
+ */
+function parseSSERow(line) {
+    var trimmed = line.trim();
+    if (!trimmed || trimmed === "")
+        return null;
+    if (!trimmed.startsWith("data: "))
+        return null;
+    var 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
+ */
+function parseSSEStream(response) {
+    return __asyncGenerator(this, arguments, function parseSSEStream_1() {
+        var reader, decoder, buffer, _a, done, value, lines, _i, lines_1, line, data, raw, rawChunkResult, rawChunk, delta, usage, error_1;
+        return __generator(this, function (_b) {
+            switch (_b.label) {
+                case 0:
+                    if (!!response.body) return [3 /*break*/, 4];
+                    return [4 /*yield*/, __await({
+                            type: "error",
+                            error: "Response body is null",
+                        })];
+                case 1: return [4 /*yield*/, _b.sent()];
+                case 2:
+                    _b.sent();
+                    return [4 /*yield*/, __await(void 0)];
+                case 3: return [2 /*return*/, _b.sent()];
+                case 4:
+                    reader = response.body.getReader();
+                    decoder = new TextDecoder();
+                    buffer = "";
+                    _b.label = 5;
+                case 5:
+                    _b.trys.push([5, , 24, 25]);
+                    _b.label = 6;
+                case 6:
+                    if (!true) return [3 /*break*/, 23];
+                    return [4 /*yield*/, __await(reader.read())];
+                case 7:
+                    _a = _b.sent(), done = _a.done, value = _a.value;
+                    if (done)
+                        return [3 /*break*/, 23];
+                    buffer += decoder.decode(value, { stream: true });
+                    lines = buffer.split("\n");
+                    buffer = lines.pop() || ""; // Keep the last incomplete line in buffer
+                    _i = 0, lines_1 = lines;
+                    _b.label = 8;
+                case 8:
+                    if (!(_i < lines_1.length)) return [3 /*break*/, 22];
+                    line = lines_1[_i];
+                    data = parseSSERow(line);
+                    if (!data)
+                        return [3 /*break*/, 21];
+                    if (!(data === "[DONE]")) return [3 /*break*/, 12];
+                    return [4 /*yield*/, __await({
+                            type: "done",
+                        })];
+                case 9: return [4 /*yield*/, _b.sent()];
+                case 10:
+                    _b.sent();
+                    return [4 /*yield*/, __await(void 0)];
+                case 11: return [2 /*return*/, _b.sent()];
+                case 12:
+                    _b.trys.push([12, 18, , 21]);
+                    raw = JSON.parse(data);
+                    rawChunkResult = exports.RawStreamChunkSchema.safeParse(raw);
+                    if (!!rawChunkResult.success) return [3 /*break*/, 15];
+                    return [4 /*yield*/, __await({
+                            type: "error",
+                            error: "Invalid stream chunk: ".concat(rawChunkResult.error.message),
+                        })];
+                case 13: return [4 /*yield*/, _b.sent()];
+                case 14:
+                    _b.sent();
+                    return [3 /*break*/, 21];
+                case 15:
+                    rawChunk = rawChunkResult.data;
+                    delta = rawChunk.choices[0].delta;
+                    usage = rawChunk.usage
+                        ? {
+                            promptTokens: rawChunk.usage.prompt_tokens,
+                            completionTokens: rawChunk.usage.completion_tokens,
+                            totalTokens: rawChunk.usage.total_tokens,
+                        }
+                        : undefined;
+                    return [4 /*yield*/, __await({
+                            type: "text",
+                            id: rawChunk.id,
+                            content: delta.content || "",
+                            finishReason: rawChunk.choices[0].finish_reason || undefined,
+                            usage: usage,
+                        })];
+                case 16: return [4 /*yield*/, _b.sent()];
+                case 17:
+                    _b.sent();
+                    return [3 /*break*/, 21];
+                case 18:
+                    error_1 = _b.sent();
+                    return [4 /*yield*/, __await({
+                            type: "error",
+                            error: "Failed to parse stream chunk: ".concat(error_1 instanceof Error ? error_1.message : String(error_1)),
+                        })];
+                case 19: return [4 /*yield*/, _b.sent()];
+                case 20:
+                    _b.sent();
+                    return [3 /*break*/, 21];
+                case 21:
+                    _i++;
+                    return [3 /*break*/, 8];
+                case 22: return [3 /*break*/, 6];
+                case 23: return [3 /*break*/, 25];
+                case 24:
+                    reader.releaseLock();
+                    return [7 /*endfinally*/];
+                case 25: return [2 /*return*/];
+            }
+        });
+    });
+}
+// ============================================================================
+// EXPORTS
+// ============================================================================
+exports.default = {
+    // Messages
+    ChatMessageSchema: exports.ChatMessageSchema,
+    ChatMessageRoleSchema: exports.ChatMessageRoleSchema,
+    // Usage
+    TokenUsageSchema: exports.TokenUsageSchema,
+    RawUsageSchema: exports.RawUsageSchema,
+    // Requests
+    BaseAIRequestOptionsSchema: exports.BaseAIRequestOptionsSchema,
+    ChatCompletionOptionsSchema: exports.ChatCompletionOptionsSchema,
+    AIRequestSchema: exports.AIRequestSchema,
+    AIChatModuleRequestSchema: exports.AIChatModuleRequestSchema,
+    // Responses
+    LatencyInfoSchema: exports.LatencyInfoSchema,
+    RawChatCompletionResponseSchema: exports.RawChatCompletionResponseSchema,
+    ChatCompletionResponseSchema: exports.ChatCompletionResponseSchema,
+    AIResponseSchema: exports.AIResponseSchema,
+    AIChatResponseSchema: exports.AIChatResponseSchema,
+    // Streaming
+    StreamDeltaSchema: exports.StreamDeltaSchema,
+    StreamChunkTypeSchema: exports.StreamChunkTypeSchema,
+    RawStreamChunkSchema: exports.RawStreamChunkSchema,
+    StreamChunkSchema: exports.StreamChunkSchema,
+    // Errors
+    APIErrorResponseSchema: exports.APIErrorResponseSchema,
+    ErrorTypeSchema: exports.ErrorTypeSchema,
+    // Helpers
+    validateChatMessage: validateChatMessage,
+    validateChatMessages: validateChatMessages,
+    validateChatCompletionOptions: validateChatCompletionOptions,
+    validateRawResponse: validateRawResponse,
+    convertUsage: convertUsage,
+    categorizeError: categorizeError,
+    parseSSERow: parseSSERow,
+    parseSSEStream: parseSSEStream,
+};