feat(docs): add structured output example and details

src/types/index.ts

@@ -36,10 +36,24 @@ export interface AIMessage {
   metadata?: Record<string, any>;
 }
 
+/**
+ * Response type definition for structured AI outputs
+ */
+export interface ResponseType<T = any> {
+  /** The TypeScript type definition as a string */
+  typeDefinition: string;
+  /** Human-readable description of the expected response format */
+  description: string;
+  /** Example of the expected response structure */
+  example?: T;
+  /** Whether to enforce strict JSON formatting */
+  strictJson?: boolean;
+}
+
 /**
  * Parameters for AI completion requests
  */
-export interface CompletionParams {
+export interface CompletionParams<T = any> {
   /** Array of messages forming the conversation */
   messages: AIMessage[];
   /** Model to use for completion */
@@ -54,6 +68,8 @@ export interface CompletionParams {
   stopSequences?: string[];
   /** Whether to stream the response */
   stream?: boolean;
+  /** Expected response type for structured outputs */
+  responseType?: ResponseType<T>;
   /** Additional provider-specific parameters */
   [key: string]: any;
 }
@@ -144,4 +160,115 @@ export interface ProviderInfo {
   supportsStreaming: boolean;
   /** Additional capabilities */
   capabilities?: Record<string, any>;
+}
+
+// ============================================================================
+// RESPONSE TYPE UTILITIES
+// ============================================================================
+
+/**
+ * Creates a response type definition for structured AI outputs
+ * 
+ * @param typeDefinition - TypeScript type definition as a string
+ * @param description - Human-readable description of the expected format
+ * @param example - Optional example of the expected response structure
+ * @param strictJson - Whether to enforce strict JSON formatting (default: true)
+ * @returns ResponseType object for use in completion requests
+ * 
+ * @example
+ * ```typescript
+ * const userType = createResponseType(
+ *   `{
+ *     name: string;
+ *     age: number;
+ *     email: string;
+ *     preferences: {
+ *       theme: 'light' | 'dark';
+ *       notifications: boolean;
+ *     };
+ *   }`,
+ *   'A user profile with personal information and preferences',
+ *   {
+ *     name: 'John Doe',
+ *     age: 30,
+ *     email: 'john@example.com',
+ *     preferences: { theme: 'dark', notifications: true }
+ *   }
+ * );
+ * ```
+ */
+export function createResponseType<T = any>(
+  typeDefinition: string,
+  description: string,
+  example?: T,
+  strictJson: boolean = true
+): ResponseType<T> {
+  return {
+    typeDefinition: typeDefinition.trim(),
+    description,
+    example,
+    strictJson
+  };
+}
+
+/**
+ * Generates a system prompt instruction for structured output based on response type
+ * 
+ * @param responseType - The response type definition
+ * @returns Formatted system prompt instruction
+ */
+export function generateResponseTypePrompt(responseType: ResponseType): string {
+  const { typeDefinition, description, example, strictJson } = responseType;
+  
+  let prompt = `You must respond with a JSON object that matches the following TypeScript type definition:\n\n`;
+  prompt += `Type Definition:\n\`\`\`typescript\n${typeDefinition}\n\`\`\`\n\n`;
+  prompt += `Description: ${description}\n\n`;
+  
+  if (example) {
+    prompt += `Example:\n\`\`\`json\n${JSON.stringify(example, null, 2)}\n\`\`\`\n\n`;
+  }
+  
+  if (strictJson) {
+    prompt += `IMPORTANT: Your response must be valid JSON only. Do not include any text before or after the JSON object. Do not use markdown formatting.`;
+  } else {
+    prompt += `Your response should follow the structure defined above.`;
+  }
+  
+  return prompt;
+}
+
+/**
+ * Validates that a response matches the expected type structure
+ * 
+ * @param response - The response content to validate
+ * @param responseType - The expected response type
+ * @returns Object with validation result and parsed data
+ */
+export function validateResponseType<T = any>(
+  response: string,
+  responseType: ResponseType<T>
+): { isValid: boolean; data?: T; error?: string } {
+  try {
+    // Parse JSON response
+    const parsed = JSON.parse(response);
+    
+    // Basic validation - in a real implementation, you might want to use
+    // a schema validation library like zod or ajv for more thorough validation
+    if (typeof parsed !== 'object' || parsed === null) {
+      return {
+        isValid: false,
+        error: 'Response must be a JSON object'
+      };
+    }
+    
+    return {
+      isValid: true,
+      data: parsed as T
+    };
+  } catch (error) {
+    return {
+      isValid: false,
+      error: `Invalid JSON: ${(error as Error).message}`
+    };
+  }
 }