@od-oneapp/ai-platform 0.1.0

package/src/pipelines/validation.ts

@@ -0,0 +1,323 @@
+/**
+ * @fileoverview Pipeline Validation Utilities
+ * Pipeline Validation Utilities
+ * Validate pipeline configurations before execution
+ */
+
+import { logWarn } from '@repo/shared/logs';
+
+import { isModelRef } from '../shared';
+
+import type { PipelineConfig, PipelineStep } from './types';
+
+export interface PipelineValidationIssue {
+  field: string;
+  message: string;
+  severity: 'error' | 'warning';
+}
+
+/**
+ * @deprecated Use PipelineValidationIssue instead
+ */
+export type ValidationError = PipelineValidationIssue;
+
+export interface PipelineValidationResult {
+  valid: boolean;
+  errors: PipelineValidationIssue[];
+  warnings: PipelineValidationIssue[];
+}
+
+/**
+ * @deprecated Use PipelineValidationResult instead
+ */
+export type ValidationResult = PipelineValidationResult;
+
+/**
+ * Validate pipeline configuration
+ */
+export function validatePipelineConfig(config: PipelineConfig): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationError[] = [];
+
+  // Required fields
+  if (!config.id || config.id.trim() === '') {
+    errors.push({
+      field: 'id',
+      message: 'Pipeline ID is required',
+      severity: 'error',
+    });
+  }
+
+  if (!config.name || config.name.trim() === '') {
+    errors.push({
+      field: 'name',
+      message: 'Pipeline name is required',
+      severity: 'error',
+    });
+  }
+
+  if (!config.actorId || config.actorId.trim() === '') {
+    errors.push({
+      field: 'actorId',
+      message: 'Actor ID is required for audit compliance',
+      severity: 'error',
+    });
+  }
+
+  if (!config.storage) {
+    errors.push({
+      field: 'storage',
+      message: 'Storage type is required',
+      severity: 'error',
+    });
+  }
+
+  // Steps validation
+  if (!config.steps || config.steps.length === 0) {
+    errors.push({
+      field: 'steps',
+      message: 'Pipeline must have at least one step',
+      severity: 'error',
+    });
+  } else {
+    // Validate each step
+    config.steps.forEach((step, index) => {
+      const stepErrors = validatePipelineStep(step, index);
+      errors.push(...stepErrors.filter(e => e.severity === 'error'));
+      warnings.push(...stepErrors.filter(e => e.severity === 'warning'));
+    });
+
+    // Check for duplicate step IDs
+    const stepIds = config.steps.map(s => s.id);
+    const duplicates = stepIds.filter((id, index) => stepIds.indexOf(id) !== index);
+    if (duplicates.length > 0) {
+      errors.push({
+        field: 'steps',
+        message: `Duplicate step IDs found: ${duplicates.join(', ')}`,
+        severity: 'error',
+      });
+    }
+  }
+
+  // Compliance validation
+  if (!config.compliance) {
+    warnings.push({
+      field: 'compliance',
+      message: 'No compliance configuration provided',
+      severity: 'warning',
+    });
+  }
+
+  // Initial messages
+  if (!config.initialMessages || config.initialMessages.length === 0) {
+    warnings.push({
+      field: 'initialMessages',
+      message: 'No initial messages provided',
+      severity: 'warning',
+    });
+  }
+
+  // Resumption validation
+  if (config.enableResumption && !config.resumeFromRunId) {
+    // This is fine - resumption is enabled for new runs
+  }
+
+  if (config.resumeFromRunId && !config.enableResumption) {
+    warnings.push({
+      field: 'resumeFromRunId',
+      message: 'resumeFromRunId provided but enableResumption is false',
+      severity: 'warning',
+    });
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Validate individual pipeline step
+ */
+export function validatePipelineStep(step: PipelineStep, index: number): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  const field = `steps[${index}]`;
+
+  // Required fields
+  if (!step.id || step.id.trim() === '') {
+    errors.push({
+      field: `${field}.id`,
+      message: `Step ${index}: ID is required`,
+      severity: 'error',
+    });
+  }
+
+  if (!step.name || step.name.trim() === '') {
+    errors.push({
+      field: `${field}.name`,
+      message: `Step ${index}: Name is required`,
+      severity: 'error',
+    });
+  }
+
+  if (!step.model) {
+    errors.push({
+      field: `${field}.model`,
+      message: `Step ${index}: Model is required`,
+      severity: 'error',
+    });
+  } else if (!isModelRef(step.model)) {
+    errors.push({
+      field: `${field}.model`,
+      message: `Step ${index}: Model must be a string or a language model instance`,
+      severity: 'error',
+    });
+  }
+
+  // Temperature validation
+  if (step.temperature !== undefined && (step.temperature < 0 || step.temperature > 2)) {
+    errors.push({
+      field: `${field}.temperature`,
+      message: `Step ${index}: Temperature must be between 0 and 2`,
+      severity: 'error',
+    });
+  }
+
+  // Max tokens validation
+  if (step.maxTokens !== undefined) {
+    if (step.maxTokens < 1) {
+      errors.push({
+        field: `${field}.maxTokens`,
+        message: `Step ${index}: maxTokens must be positive`,
+        severity: 'error',
+      });
+    }
+    if (step.maxTokens > 100000) {
+      errors.push({
+        field: `${field}.maxTokens`,
+        message: `Step ${index}: maxTokens seems unusually high (${step.maxTokens})`,
+        severity: 'warning',
+      });
+    }
+  }
+
+  // Timeout validation
+  if (step.timeoutMs !== undefined) {
+    if (step.timeoutMs < 1000) {
+      errors.push({
+        field: `${field}.timeoutMs`,
+        message: `Step ${index}: Timeout too short (minimum 1000ms recommended)`,
+        severity: 'warning',
+      });
+    }
+    if (step.timeoutMs > 600000) {
+      errors.push({
+        field: `${field}.timeoutMs`,
+        message: `Step ${index}: Timeout very long (${step.timeoutMs}ms = ${step.timeoutMs / 60000} minutes)`,
+        severity: 'warning',
+      });
+    }
+  }
+
+  // Retry validation
+  if (step.retry) {
+    if (step.retry.maxAttempts < 1) {
+      errors.push({
+        field: `${field}.retry.maxAttempts`,
+        message: `Step ${index}: maxAttempts must be at least 1`,
+        severity: 'error',
+      });
+    }
+    if (step.retry.maxAttempts > 10) {
+      errors.push({
+        field: `${field}.retry.maxAttempts`,
+        message: `Step ${index}: maxAttempts very high (${step.retry.maxAttempts})`,
+        severity: 'warning',
+      });
+    }
+    if (step.retry.delayMs < 0) {
+      errors.push({
+        field: `${field}.retry.delayMs`,
+        message: `Step ${index}: Retry delay must be non-negative`,
+        severity: 'error',
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Assert pipeline config is valid (throws on error)
+ */
+export function assertValidPipelineConfig(config: PipelineConfig): void {
+  const result = validatePipelineConfig(config);
+
+  if (!result.valid) {
+    const errorMessages = result.errors.map(e => `  - ${e.field}: ${e.message}`);
+    throw new Error(`Invalid pipeline configuration:\n${errorMessages.join('\n')}`);
+  }
+
+  // Log warnings if any
+  if (result.warnings.length > 0) {
+    logWarn('Pipeline configuration warnings', { warnings: result.warnings });
+    result.warnings.forEach(w => {
+      logWarn(`  - ${w.field}: ${w.message}`, { field: w.field, message: w.message });
+    });
+  }
+}
+
+/**
+ * Validate storage configuration
+ */
+export function validateStorageConfig(config: {
+  type: 'blob' | 'postgres';
+  blob?: { token: string };
+  redis?: { url: string; token: string };
+  postgres?: { connectionString: string };
+}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationError[] = [];
+
+  if (config.type === 'blob') {
+    if (!config.blob?.token) {
+      errors.push({
+        field: 'blob.token',
+        message: 'Blob token is required for blob storage',
+        severity: 'error',
+      });
+    }
+    if (!config.redis?.url || !config.redis?.token) {
+      errors.push({
+        field: 'redis',
+        message: 'Redis configuration is required for blob storage',
+        severity: 'error',
+      });
+    }
+  }
+
+  if (config.type === 'postgres') {
+    if (!config.postgres?.connectionString) {
+      errors.push({
+        field: 'postgres.connectionString',
+        message: 'Connection string is required for postgres storage',
+        severity: 'error',
+      });
+    }
+    if (!config.blob?.token) {
+      errors.push({
+        field: 'blob.token',
+        message: 'Blob token is required for postgres storage (artifacts)',
+        severity: 'error',
+      });
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}

package/src/prompts/index.ts

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview Centralized system prompt management with model-specific composition and variants.
+ * @module @od-oneapp/ai-platform/prompts
+ */
+
+import { formatPromptForClaude, formatPromptForGemini, formatPromptForGPT } from './model-variants';
+
+// System prompts for different assistant personas
+export const SYSTEM_PROMPTS = {
+  default: `You are a helpful, harmless, and honest AI assistant.
+You provide accurate, thoughtful responses while maintaining clarity and concision.
+Always prioritize user safety and accuracy in your responses.`,
+
+  assistant: `You are a professional AI assistant designed to help users with a wide variety of tasks.
+You are knowledgeable, helpful, and respectful. You provide detailed, accurate information.
+You ask clarifying questions when needed and adapt your communication style to the user's needs.`,
+
+  coder: `You are an expert software engineer and code reviewer.
+You write clean, maintainable, and well-documented code following best practices.
+You provide comprehensive explanations of technical concepts and help debug complex issues.
+You recommend performance optimizations and security improvements.`,
+
+  analyst: `You are a data analyst and business intelligence expert.
+You interpret data accurately, identify trends, and provide actionable insights.
+You communicate complex analytical findings in clear, understandable terms.
+You consider context and limitations when making recommendations based on data.`,
+
+  researcher: `You are a thorough research expert with strong analytical capabilities.
+You synthesize information from multiple sources and identify patterns and connections.
+You distinguish between facts, evidence, and speculation clearly.
+You acknowledge gaps in knowledge and suggest further research directions.`,
+
+  writer: `You are a skilled professional writer and editor.
+You create compelling, well-structured content tailored to your audience.
+You maintain consistency in tone, style, and messaging.
+You provide constructive feedback and help refine written work.`,
+};
+
+// Prompt fragments for composition and reuse
+export const PROMPT_FRAGMENTS = {
+  safety: `Always prioritize safety and accuracy. Never provide harmful information.
+Be transparent about limitations and uncertainties in your knowledge.
+If you're unsure, say so and suggest reliable ways to find accurate information.`,
+
+  formatting: `Structure your response clearly with appropriate formatting:
+- Use bullet points for lists
+- Use code blocks for code examples with language specification
+- Use tables for comparative information
+- Use headers to organize long responses
+- Use emphasis (bold/italic) for important points`,
+
+  codeStyle: `When writing code:
+- Follow the language's standard conventions and best practices
+- Include meaningful variable and function names
+- Add comments for complex logic
+- Provide error handling where appropriate
+- Consider edge cases and potential issues`,
+
+  reasoning: `Show your reasoning and thought process:
+- Explain the why behind recommendations
+- Break down complex problems step by step
+- Consider multiple perspectives and approaches
+- Acknowledge trade-offs and limitations`,
+
+  citations: `When referencing information:
+- Cite sources when using specific facts or data
+- Distinguish between widely-known information and specialized knowledge
+- Indicate the recency and reliability of sources when relevant
+- Acknowledge when information might be outdated`,
+};
+
+/**
+ * Options for composing system prompts
+ */
+export interface ComposeOptions {
+  basePrompt: string;
+  fragments?: string[];
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  style?: 'concise' | 'detailed' | 'balanced';
+  customInstructions?: string;
+}
+
+/**
+ * Compose a system prompt from base prompt and fragments
+ * @param options Configuration for prompt composition
+ * @returns Composed system prompt string
+ */
+export function composeSystemPrompt(options: ComposeOptions): string {
+  const { basePrompt, fragments = [], customInstructions, style = 'balanced' } = options;
+
+  let composed = basePrompt;
+
+  // Add fragments if specified
+  if (fragments.length > 0) {
+    composed += '\n\n';
+    composed += fragments.join('\n\n');
+  }
+
+  // Add style-specific guidance
+  if (style === 'concise') {
+    composed += '\n\n';
+    composed += 'Keep responses concise and to the point. Avoid unnecessary elaboration.';
+  } else if (style === 'detailed') {
+    composed += '\n\n';
+    composed += 'Provide comprehensive, detailed responses with thorough explanations.';
+  }
+
+  // Add custom instructions if provided
+  if (customInstructions) {
+    composed += '\n\n';
+    composed += `Additional instructions: ${customInstructions}`;
+  }
+
+  return composed;
+}
+
+/**
+ * Formats a base prompt with model-specific conventions based on the model identifier.
+ *
+ * Detects the model family from the ID prefix (e.g., `claude-*`, `gpt-*`, `gemini-*`)
+ * and applies the corresponding formatting variant. Returns the prompt unchanged
+ * if the model family is not recognized.
+ *
+ * @param basePrompt - The base system prompt to format
+ * @param model - Model identifier (e.g., `'claude-opus'`, `'gpt-4'`, `'gemini-pro'`)
+ * @returns The prompt formatted for the target model's conventions
+ *
+ * @example
+ * ```ts
+ * const prompt = formatPromptForModel('You are a helpful assistant.', 'claude-opus');
+ * // Returns: '<system>\nYou are a helpful assistant.\n</system>'
+ * ```
+ */
+const MODEL_VARIANTS: Record<string, (prompt: string) => string> = {
+  claude: formatPromptForClaude,
+  gemini: formatPromptForGemini,
+  gpt: formatPromptForGPT,
+};
+
+export function formatPromptForModel(basePrompt: string, model: string): string {
+  const [modelPrefixRaw] = model.split('-');
+  const modelPrefix = modelPrefixRaw?.toLowerCase();
+
+  if (!modelPrefix) {
+    return basePrompt;
+  }
+
+  const variantFn = MODEL_VARIANTS[modelPrefix];
+
+  if (!variantFn) {
+    return basePrompt;
+  }
+
+  return variantFn(basePrompt);
+}
+
+/**
+ * Template variables for prompt interpolation
+ */
+export interface TemplateVariables {
+  [key: string]: string | number | boolean;
+}
+
+/**
+ * Prompt template interface
+ */
+export interface PromptTemplate {
+  template: string;
+  variables: Set<string>;
+}
+
+/**
+ * Validate that all template variables are provided
+ * @param template The prompt template
+ * @param variables Provided variable values
+ * @returns Object indicating validation result and missing variables
+ */
+export function validatePromptVariables(
+  template: PromptTemplate,
+  variables: TemplateVariables,
+): { valid: boolean; missing: string[] } {
+  const missing = Array.from(template.variables).filter(v => !(v in variables));
+  return {
+    valid: missing.length === 0,
+    missing,
+  };
+}
+
+/**
+ * Merge multiple prompt fragments into a cohesive prompt
+ * @param fragments Array of prompt fragments to merge
+ * @param separator String to join fragments with (default: double newline)
+ * @returns Merged prompt string
+ */
+export function mergePromptFragments(fragments: string[], separator: string = '\n\n'): string {
+  return fragments.filter(f => f.trim().length > 0).join(separator);
+}
+
+/**
+ * Export template utilities
+ */
+export * from './templates';
+
+/**
+ * Export model variants
+ */
+export * from './model-variants';
+
+// ---------------------------------------------------------------------------
+// Configuration constants & fragments (migrated from @repo/ai)
+// ---------------------------------------------------------------------------
+
+/**
+ * Common temperature presets used across providers.
+ * Single source of truth for temperature values.
+ */
+export const TEMPS = {
+  PRECISE: 0, // Deterministic, no randomness
+  VERY_LOW: 0.1, // Near-deterministic, minimal variation
+  FACTUAL: 0.2, // Low creativity, high accuracy
+  LOW_CREATIVE: 0.3, // Slightly creative, mostly factual
+  MODERATE: 0.5, // Moderate balance
+  BALANCED: 0.7, // Default for most use cases
+  HIGH_CREATIVE: 0.8, // Higher creativity
+  CREATIVE: 0.9, // High creativity, more variety
+} as const;
+
+/**
+ * Common token limit presets.
+ * Standardized across providers where applicable.
+ */
+export const TOKENS = {
+  TINY: 256, // Very short responses
+  SHORT: 1024, // Quick responses
+  MEDIUM: 2048, // Standard responses
+  LONG: 4096, // Detailed responses
+  EXTENDED: 8192, // Extended context
+  MAX: 16384, // Maximum for most models
+} as const;
+
+/**
+ * Chat configuration fragments - frequently reused patterns only.
+ *
+ * @example
+ * ```typescript
+ * const { basicChat } = chatFragments;
+ * const config = { ...basicChat, system: 'You are a helpful assistant.' };
+ * ```
+ */
+export const chatFragments = {
+  /** Basic chat configuration - used 6+ times across generation functions */
+  basicChat: {
+    temperature: TEMPS.BALANCED,
+    maxOutputTokens: TOKENS.MEDIUM,
+  },
+
+  /** Structured data chat - used 6+ times in object generation */
+  structured: {
+    temperature: TEMPS.VERY_LOW,
+    maxOutputTokens: TOKENS.LONG,
+  },
+
+  /** Tool-enabled chat - used 3+ times */
+  withTools: {
+    temperature: TEMPS.BALANCED,
+    maxOutputTokens: TOKENS.MEDIUM,
+    toolChoice: 'auto' as const,
+  },
+} as const;