@ebowwa/codespaces-types 1.1.0 → 1.2.0

package/runtime/ai.ts

@@ -0,0 +1,501 @@
+/**
+ * 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 AIChatModuleRequestSchema = 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",
+]);
+
+// ============================================================================
+// TYPE INFERENCE
+// ============================================================================
+
+export type ChatMessageRole = z.infer<typeof ChatMessageRoleSchema>;
+export type ChatMessage = z.infer<typeof ChatMessageSchema>;
+export type TokenUsage = z.infer<typeof TokenUsageSchema>;
+export type BaseAIRequestOptions = z.infer<typeof BaseAIRequestOptionsSchema>;
+export type ChatCompletionOptions = z.infer<typeof ChatCompletionOptionsSchema>;
+export type AIRequest = z.infer<typeof AIRequestSchema>;
+export type AIChatModuleRequest = z.infer<typeof AIChatModuleRequestSchema>;
+export type LatencyInfo = z.infer<typeof LatencyInfoSchema>;
+export type RawChatCompletionResponse = z.infer<
+  typeof RawChatCompletionResponseSchema
+>;
+export type ChatCompletionResponse = z.infer<
+  typeof ChatCompletionResponseSchema
+>;
+export type AIResponse = z.infer<typeof AIResponseSchema>;
+export type AIChatResponse = z.infer<typeof AIChatResponseSchema>;
+export type APIErrorResponse = z.infer<typeof APIErrorResponseSchema>;
+export type ErrorType = z.infer<typeof ErrorTypeSchema>;
+export type StreamDelta = z.infer<typeof StreamDeltaSchema>;
+export type StreamChunkType = z.infer<typeof StreamChunkTypeSchema>;
+export type RawStreamChunk = z.infer<typeof RawStreamChunkSchema>;
+export type StreamChunk = z.infer<typeof StreamChunkSchema>;
+
+// ============================================================================
+// VALIDATION HELPERS
+// ============================================================================
+
+/**
+ * Validate chat message
+ */
+export function validateChatMessage(data: unknown) {
+  return ChatMessageSchema.safeParse(data);
+}
+
+/**
+ * Validate chat messages array
+ */
+export function validateChatMessages(data: unknown) {
+  return z.array(ChatMessageSchema).min(1).safeParse(data);
+}
+
+/**
+ * Validate chat completion options
+ */
+export function validateChatCompletionOptions(data: unknown) {
+  return ChatCompletionOptionsSchema.safeParse(data);
+}
+
+/**
+ * Validate raw API response
+ */
+export function validateRawResponse(data: unknown) {
+  return RawChatCompletionResponseSchema.safeParse(data);
+}
+
+/**
+ * Validate and convert raw usage to internal format
+ */
+export function convertUsage(raw: unknown): TokenUsage | null {
+  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: unknown): ErrorType {
+  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: string): string | null {
+  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: Response,
+): AsyncGenerator<StreamChunk, void, unknown> {
+  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: TokenUsage | undefined = 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,
+  AIChatModuleRequestSchema,
+
+  // Responses
+  LatencyInfoSchema,
+  RawChatCompletionResponseSchema,
+  ChatCompletionResponseSchema,
+  AIResponseSchema,
+  AIChatResponseSchema,
+
+  // Streaming
+  StreamDeltaSchema,
+  StreamChunkTypeSchema,
+  RawStreamChunkSchema,
+  StreamChunkSchema,
+
+  // Errors
+  APIErrorResponseSchema,
+  ErrorTypeSchema,
+
+  // Helpers
+  validateChatMessage,
+  validateChatMessages,
+  validateChatCompletionOptions,
+  validateRawResponse,
+  convertUsage,
+  categorizeError,
+  parseSSERow,
+  parseSSEStream,
+};