@od-oneapp/ai-platform 0.1.0

package/src/hitl/approval/approval-queue.ts

@@ -0,0 +1,132 @@
+/**
+ * In-memory approval queue for HITL workflows
+ */
+
+import type { ApprovalQueue, ApprovalRequest, ApprovalResponse } from '../types';
+
+/**
+ * In-memory approval queue implementation
+ *
+ * @example
+ * ```ts
+ * const queue = new InMemoryApprovalQueue();
+ *
+ * // Submit for approval
+ * const requestId = await queue.submit({
+ *   id: "req-1",
+ *   type: "action",
+ *   content: { action: "delete_user", userId: "123" },
+ *   context: "User requested account deletion",
+ *   priority: "high",
+ *   createdAt: new Date(),
+ * });
+ *
+ * // Wait for approval
+ * const response = await queue.waitForApproval(requestId, 30000);
+ * if (response.status === "approved") {
+ *   // Proceed with action
+ * }
+ * ```
+ */
+export class InMemoryApprovalQueue implements ApprovalQueue {
+  private requests = new Map<string, ApprovalRequest>();
+  private responses = new Map<string, ApprovalResponse>();
+  private waiters = new Map<
+    string,
+    Array<{
+      resolve: (response: ApprovalResponse) => void;
+      reject: (error: Error) => void;
+    }>
+  >();
+
+  async submit<T>(request: ApprovalRequest<T>): Promise<string> {
+    this.requests.set(request.id, request as ApprovalRequest);
+    return request.id;
+  }
+
+  async get(requestId: string): Promise<ApprovalRequest | null> {
+    return this.requests.get(requestId) || null;
+  }
+
+  async listPending(
+    options: { limit?: number; priority?: string } = {},
+  ): Promise<ApprovalRequest[]> {
+    const { limit = 100, priority } = options;
+
+    let pending = Array.from(this.requests.values()).filter(req => !this.responses.has(req.id));
+
+    if (priority) {
+      pending = pending.filter(req => req.priority === priority);
+    }
+
+    // Sort by priority and creation time
+    const priorityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    pending.sort((a, b) => {
+      const priorityDiff =
+        (priorityOrder[a.priority || 'medium'] || 2) - (priorityOrder[b.priority || 'medium'] || 2);
+      if (priorityDiff !== 0) return priorityDiff;
+      return a.createdAt.getTime() - b.createdAt.getTime();
+    });
+
+    return pending.slice(0, limit);
+  }
+
+  async respond<T>(response: ApprovalResponse<T>): Promise<void> {
+    this.responses.set(response.requestId, response as ApprovalResponse);
+
+    // Notify waiters
+    const waiters = this.waiters.get(response.requestId) || [];
+    for (const waiter of waiters) {
+      waiter.resolve(response as ApprovalResponse);
+    }
+    this.waiters.delete(response.requestId);
+  }
+
+  async waitForApproval<T>(requestId: string, timeoutMs = 30000): Promise<ApprovalResponse<T>> {
+    // Check if already responded
+    const existing = this.responses.get(requestId);
+    if (existing) {
+      return existing as ApprovalResponse<T>;
+    }
+
+    return new Promise((resolve, reject) => {
+      const waiters = this.waiters.get(requestId) || [];
+
+      const timer = setTimeout(() => {
+        const idx = waiters.indexOf(waiter);
+        if (idx >= 0) waiters.splice(idx, 1);
+        reject(new Error(`Approval timeout: ${requestId}`));
+      }, timeoutMs);
+
+      const wrappedResolve = (response: ApprovalResponse) => {
+        clearTimeout(timer);
+        resolve(response as ApprovalResponse<T>);
+      };
+
+      const wrappedReject = (error: Error) => {
+        clearTimeout(timer);
+        reject(error);
+      };
+
+      const waiter = { resolve: wrappedResolve, reject: wrappedReject };
+      waiters.push(waiter);
+      this.waiters.set(requestId, waiters);
+    });
+  }
+
+  /**
+   * Get response for a request
+   */
+  getResponse(requestId: string): ApprovalResponse | undefined {
+    return this.responses.get(requestId);
+  }
+
+  /**
+   * Clear all requests and responses
+   */
+  clear(): void {
+    this.requests.clear();
+    this.responses.clear();
+    this.waiters.clear();
+  }
+}

package/src/hitl/approval/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Human Approval Gates
+ * @module hitl/approval
+ */
+export * from './approval-queue';

package/src/hitl/feedback/index.ts

@@ -0,0 +1,284 @@
+/**
+ * User Feedback Collection
+ *
+ * Collects and aggregates user feedback on AI responses
+ * for quality monitoring and model improvement.
+ *
+ * @module @od-oneapp/ai-platform/hitl/feedback
+ *
+ * @example
+ * ```typescript
+ * import { createFeedbackCollector } from '@od-oneapp/ai-platform/hitl/feedback';
+ *
+ * const collector = createFeedbackCollector();
+ *
+ * // Collect feedback
+ * await collector.collect({
+ *   responseId: 'resp-123',
+ *   rating: 5,
+ *   comment: 'Very helpful response!'
+ * });
+ *
+ * // Get aggregated stats
+ * const stats = await collector.aggregate();
+ * console.log(`Average rating: ${stats.avgRating}`);
+ * ```
+ */
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+/** User feedback on an AI response */
+export interface Feedback {
+  readonly id: string;
+  readonly responseId: string;
+  readonly userId?: string;
+  readonly rating: number; // 1-5
+  readonly comment?: string;
+  readonly tags?: string[];
+  readonly metadata?: Record<string, unknown>;
+  readonly timestamp: Date;
+}
+
+/** Feedback input without auto-generated fields */
+export type FeedbackInput = Omit<Feedback, 'id' | 'timestamp'>;
+
+/** Aggregated feedback statistics */
+export interface FeedbackStats {
+  readonly avgRating: number;
+  readonly count: number;
+  readonly distribution: Record<number, number>;
+  readonly recentTrend: 'improving' | 'declining' | 'stable';
+}
+
+/** Feedback query options */
+export interface FeedbackQuery {
+  readonly responseId?: string;
+  readonly userId?: string;
+  readonly minRating?: number;
+  readonly maxRating?: number;
+  readonly startDate?: Date;
+  readonly endDate?: Date;
+  readonly tags?: string[];
+  readonly limit?: number;
+  readonly offset?: number;
+}
+
+/** Feedback storage interface */
+export interface FeedbackStore {
+  save(feedback: Feedback): Promise<void>;
+  get(id: string): Promise<Feedback | null>;
+  query(query: FeedbackQuery): Promise<Feedback[]>;
+  delete(id: string): Promise<void>;
+}
+
+/** Feedback collector interface */
+export interface FeedbackCollector {
+  collect(input: FeedbackInput): Promise<Feedback>;
+  getByResponse(responseId: string): Promise<Feedback[]>;
+  getByUser(userId: string): Promise<Feedback[]>;
+  query(query: FeedbackQuery): Promise<Feedback[]>;
+  aggregate(query?: FeedbackQuery): Promise<FeedbackStats>;
+}
+
+// -----------------------------------------------------------------------------
+// In-Memory Store
+// -----------------------------------------------------------------------------
+
+/**
+ * Simple in-memory feedback store for development/testing.
+ */
+export class InMemoryFeedbackStore implements FeedbackStore {
+  private readonly feedbacks = new Map<string, Feedback>();
+
+  async save(feedback: Feedback): Promise<void> {
+    this.feedbacks.set(feedback.id, feedback);
+  }
+
+  async get(id: string): Promise<Feedback | null> {
+    return this.feedbacks.get(id) ?? null;
+  }
+
+  async query(query: FeedbackQuery): Promise<Feedback[]> {
+    let results = Array.from(this.feedbacks.values());
+    const { minRating, maxRating, startDate, endDate, tags } = query;
+
+    if (query.responseId) {
+      results = results.filter(f => f.responseId === query.responseId);
+    }
+    if (query.userId) {
+      results = results.filter(f => f.userId === query.userId);
+    }
+    if (minRating !== undefined) {
+      results = results.filter(f => f.rating >= minRating);
+    }
+    if (maxRating !== undefined) {
+      results = results.filter(f => f.rating <= maxRating);
+    }
+    if (startDate) {
+      results = results.filter(f => f.timestamp >= startDate);
+    }
+    if (endDate) {
+      results = results.filter(f => f.timestamp <= endDate);
+    }
+    if (tags?.length) {
+      results = results.filter(f => tags.some(tag => f.tags?.includes(tag)));
+    }
+
+    // Sort by timestamp descending
+    results.sort((a, b) => b.timestamp.getTime() - a.timestamp.getTime());
+
+    // Apply pagination
+    const offset = query.offset ?? 0;
+    const limit = query.limit ?? 100;
+    return results.slice(offset, offset + limit);
+  }
+
+  async delete(id: string): Promise<void> {
+    this.feedbacks.delete(id);
+  }
+
+  /** Clear all feedback (for testing) */
+  clear(): void {
+    this.feedbacks.clear();
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Feedback Collector Implementation
+// -----------------------------------------------------------------------------
+
+/** Configuration for feedback collector */
+export interface FeedbackCollectorConfig {
+  readonly store?: FeedbackStore;
+  readonly validateRating?: (rating: number) => boolean;
+  readonly onFeedback?: (feedback: Feedback) => void;
+}
+
+/**
+ * Creates a feedback collector for gathering user feedback on AI responses.
+ *
+ * @example
+ * ```typescript
+ * const collector = createFeedbackCollector({
+ *   onFeedback: (feedback) => {
+ *     console.log(`New feedback: ${feedback.rating}/5`);
+ *   }
+ * });
+ *
+ * await collector.collect({
+ *   responseId: 'resp-123',
+ *   rating: 4,
+ *   comment: 'Good but could be more concise'
+ * });
+ * ```
+ */
+export function createFeedbackCollector(config: FeedbackCollectorConfig = {}): FeedbackCollector {
+  const {
+    store = new InMemoryFeedbackStore(),
+    validateRating = r => r >= 1 && r <= 5,
+    onFeedback,
+  } = config;
+
+  async function collect(input: FeedbackInput): Promise<Feedback> {
+    // Validate rating
+    if (!validateRating(input.rating)) {
+      throw new Error(`Invalid rating: ${input.rating}. Must be between 1 and 5.`);
+    }
+
+    const feedback: Feedback = {
+      ...input,
+      id: generateId(),
+      timestamp: new Date(),
+    };
+
+    await store.save(feedback);
+    onFeedback?.(feedback);
+
+    return feedback;
+  }
+
+  async function getByResponse(responseId: string): Promise<Feedback[]> {
+    return store.query({ responseId });
+  }
+
+  async function getByUser(userId: string): Promise<Feedback[]> {
+    return store.query({ userId });
+  }
+
+  async function query(q: FeedbackQuery): Promise<Feedback[]> {
+    return store.query(q);
+  }
+
+  async function aggregate(q?: FeedbackQuery): Promise<FeedbackStats> {
+    const feedbacks = await store.query(q ?? {});
+
+    if (feedbacks.length === 0) {
+      return {
+        avgRating: 0,
+        count: 0,
+        distribution: { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 },
+        recentTrend: 'stable',
+      };
+    }
+
+    // Calculate distribution
+    const distribution: Record<number, number> = { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 };
+    let sum = 0;
+
+    for (const f of feedbacks) {
+      sum += f.rating;
+      distribution[f.rating] = (distribution[f.rating] ?? 0) + 1;
+    }
+
+    const avgRating = sum / feedbacks.length;
+
+    // Calculate trend from recent vs older feedback
+    const trend = calculateTrend(feedbacks);
+
+    return {
+      avgRating: Math.round(avgRating * 100) / 100,
+      count: feedbacks.length,
+      distribution,
+      recentTrend: trend,
+    };
+  }
+
+  return {
+    collect,
+    getByResponse,
+    getByUser,
+    query,
+    aggregate,
+  };
+}
+
+// -----------------------------------------------------------------------------
+// Utilities
+// -----------------------------------------------------------------------------
+
+function generateId(): string {
+  return `fb-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function calculateTrend(feedbacks: Feedback[]): 'improving' | 'declining' | 'stable' {
+  if (feedbacks.length < 10) return 'stable';
+
+  // Sort by timestamp
+  const sorted = [...feedbacks].sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+
+  // Compare first half avg vs second half avg
+  const mid = Math.floor(sorted.length / 2);
+  const firstHalf = sorted.slice(0, mid);
+  const secondHalf = sorted.slice(mid);
+
+  const firstAvg = firstHalf.reduce((s, f) => s + f.rating, 0) / firstHalf.length;
+  const secondAvg = secondHalf.reduce((s, f) => s + f.rating, 0) / secondHalf.length;
+
+  const diff = secondAvg - firstAvg;
+
+  if (diff > 0.3) return 'improving';
+  if (diff < -0.3) return 'declining';
+  return 'stable';
+}

package/src/hitl/index.ts

@@ -0,0 +1,69 @@
+/**
+ * Human-in-the-Loop (HITL) module
+ *
+ * Provides patterns for integrating human review and approval
+ * into AI workflows, including approval queues, review triggers,
+ * and escalation handling.
+ *
+ * @module @od-oneapp/ai-platform/hitl
+ */
+
+// Types
+export type {
+  ApprovalStatus,
+  ApprovalRequest,
+  ApprovalResponse,
+  EscalationConfig,
+  HITLConfig,
+  ReviewCondition,
+  ApprovalQueue,
+  ReviewSession,
+} from './types';
+
+// Approval
+export { InMemoryApprovalQueue } from './approval/approval-queue';
+
+// Review
+export {
+  evaluateReviewTriggers,
+  ReviewConditions,
+  type ReviewContext,
+} from './review/review-trigger';
+
+// Feedback collection
+export {
+  createFeedbackCollector,
+  type Feedback,
+  type FeedbackInput,
+  type FeedbackQuery,
+  type FeedbackStats,
+  type FeedbackStore,
+  type FeedbackCollector,
+  type FeedbackCollectorConfig,
+} from "./feedback";
+
+// Annotation management
+export {
+  createAnnotationStore,
+  type TaskType,
+  type TaskStatus,
+  type AnnotationTask,
+  type Annotation,
+  type AnnotationInput,
+  type TaskQuery,
+  type AnnotationStats,
+  type AnnotatorStats,
+  type AnnotationStore,
+} from "./annotation";
+
+// Active learning
+export {
+  createActiveLearner,
+  createSample,
+  createSamples,
+  type SelectionStrategy,
+  type Sample,
+  type SelectionResult,
+  type ActiveLearner,
+  type ActiveLearnerConfig,
+} from "./active-learning";

package/src/hitl/review/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Human review workflows
+ * @module @od-oneapp/ai-platform/hitl/review
+ */
+
+export { evaluateReviewTriggers, ReviewConditions, type ReviewContext } from './review-trigger';

package/src/hitl/review/review-trigger.ts

@@ -0,0 +1,162 @@
+/**
+ * Review trigger evaluation
+ */
+
+import type { ReviewCondition } from '../types';
+
+/**
+ * Context for evaluating review triggers
+ */
+export interface ReviewContext {
+  /** Confidence score (0-1) */
+  confidence?: number;
+  /** Content being generated */
+  content?: string;
+  /** Action being taken */
+  action?: string;
+  /** Additional context */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Evaluate if human review is required
+ *
+ * @example
+ * ```ts
+ * const conditions: ReviewCondition[] = [
+ *   { type: "confidence", threshold: 0.8 },
+ *   { type: "action", actions: ["delete", "publish"] },
+ *   { type: "content", pattern: /sensitive|confidential/i },
+ * ];
+ *
+ * const context = {
+ *   confidence: 0.7,
+ *   action: "update",
+ *   content: "This contains sensitive information",
+ * };
+ *
+ * const result = evaluateReviewTriggers(conditions, context);
+ * // result.requiresReview = true
+ * // result.triggeredConditions = ["confidence", "content"]
+ * ```
+ */
+export function evaluateReviewTriggers(
+  conditions: ReviewCondition[],
+  context: ReviewContext,
+): { requiresReview: boolean; triggeredConditions: string[] } {
+  const triggeredConditions: string[] = [];
+
+  for (const condition of conditions) {
+    if (evaluateCondition(condition, context)) {
+      triggeredConditions.push(condition.type);
+    }
+  }
+
+  return {
+    requiresReview: triggeredConditions.length > 0,
+    triggeredConditions,
+  };
+}
+
+/**
+ * Evaluate a single review condition
+ */
+function evaluateCondition(condition: ReviewCondition, context: ReviewContext): boolean {
+  switch (condition.type) {
+    case 'confidence':
+      return evaluateConfidenceCondition(condition, context);
+
+    case 'content':
+      return evaluateContentCondition(condition, context);
+
+    case 'action':
+      return evaluateActionCondition(condition, context);
+
+    case 'custom':
+      return condition.evaluate?.(context) ?? false;
+
+    default:
+      return false;
+  }
+}
+
+function evaluateConfidenceCondition(condition: ReviewCondition, context: ReviewContext): boolean {
+  if (context.confidence === undefined || condition.threshold === undefined) {
+    return false;
+  }
+  // Trigger review if confidence is BELOW threshold
+  return context.confidence < condition.threshold;
+}
+
+function evaluateContentCondition(condition: ReviewCondition, context: ReviewContext): boolean {
+  if (!context.content || !condition.pattern) {
+    return false;
+  }
+  return condition.pattern.test(context.content);
+}
+
+function evaluateActionCondition(condition: ReviewCondition, context: ReviewContext): boolean {
+  if (!context.action || !condition.actions) {
+    return false;
+  }
+  return condition.actions.includes(context.action);
+}
+
+/**
+ * Create common review conditions
+ */
+export const ReviewConditions = {
+  /**
+   * Require review when confidence is below threshold
+   */
+  lowConfidence(threshold: number): ReviewCondition {
+    return { type: 'confidence', threshold };
+  },
+
+  /**
+   * Require review for destructive actions
+   */
+  destructiveActions(): ReviewCondition {
+    return {
+      type: 'action',
+      actions: ['delete', 'remove', 'destroy', 'drop', 'truncate'],
+    };
+  },
+
+  /**
+   * Require review for publishing actions
+   */
+  publishingActions(): ReviewCondition {
+    return {
+      type: 'action',
+      actions: ['publish', 'post', 'send', 'broadcast', 'announce'],
+    };
+  },
+
+  /**
+   * Require review for sensitive content patterns
+   */
+  sensitiveContent(): ReviewCondition {
+    return {
+      type: 'content',
+      pattern: /\b(confidential|secret|private|sensitive|ssn|password|api[_-]?key)\b/i,
+    };
+  },
+
+  /**
+   * Require review for PII patterns
+   */
+  piiContent(): ReviewCondition {
+    return {
+      type: 'content',
+      pattern: /\b(\d{3}-\d{2}-\d{4}|\d{16}|\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4})\b/,
+    };
+  },
+
+  /**
+   * Custom condition
+   */
+  custom(evaluate: (context: unknown) => boolean): ReviewCondition {
+    return { type: 'custom', evaluate };
+  },
+};