@od-oneapp/ai-platform 0.1.0

package/src/hitl/types.ts

@@ -0,0 +1,126 @@
+/**
+ * Human-in-the-Loop (HITL) types
+ */
+
+/**
+ * Approval status for human review
+ */
+export type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'modified';
+
+/**
+ * Approval request for human review
+ */
+export interface ApprovalRequest<T = unknown> {
+  /** Unique request ID */
+  id: string;
+  /** Request type */
+  type: 'action' | 'content' | 'decision';
+  /** Content requiring approval */
+  content: T;
+  /** Context for the reviewer */
+  context?: string;
+  /** Urgency level */
+  priority?: 'low' | 'medium' | 'high' | 'critical';
+  /** Deadline for response */
+  deadline?: Date;
+  /** Requester information */
+  requester?: string;
+  /** Created timestamp */
+  createdAt: Date;
+}
+
+/**
+ * Approval response from human reviewer
+ */
+export interface ApprovalResponse<T = unknown> {
+  /** Request ID being responded to */
+  requestId: string;
+  /** Approval status */
+  status: ApprovalStatus;
+  /** Modified content (if status is "modified") */
+  modifiedContent?: T;
+  /** Reviewer feedback */
+  feedback?: string;
+  /** Reviewer identifier */
+  reviewer: string;
+  /** Response timestamp */
+  respondedAt: Date;
+}
+
+/**
+ * Escalation configuration
+ */
+export interface EscalationConfig {
+  /** Time to wait before escalating (ms) */
+  timeoutMs: number;
+  /** Escalation targets in order */
+  escalationChain: string[];
+  /** Action on timeout with no response */
+  defaultAction: 'approve' | 'reject' | 'escalate';
+}
+
+/**
+ * HITL workflow configuration
+ */
+export interface HITLConfig {
+  /** Enable HITL review */
+  enabled: boolean;
+  /** Conditions that trigger review */
+  triggerConditions?: ReviewCondition[];
+  /** Escalation configuration */
+  escalation?: EscalationConfig;
+  /** Notification callback */
+  notify?: (request: ApprovalRequest) => Promise<void>;
+}
+
+/**
+ * Condition that triggers human review
+ */
+export interface ReviewCondition {
+  /** Condition type */
+  type: 'confidence' | 'content' | 'action' | 'custom';
+  /** Threshold for confidence-based triggers */
+  threshold?: number;
+  /** Pattern for content-based triggers */
+  pattern?: RegExp;
+  /** Action types requiring review */
+  actions?: string[];
+  /** Custom evaluation function */
+  evaluate?: (context: unknown) => boolean;
+}
+
+/**
+ * Approval queue interface
+ */
+export interface ApprovalQueue {
+  /** Submit a request for approval */
+  submit<T>(request: ApprovalRequest<T>): Promise<string>;
+  /** Get a pending request */
+  get(requestId: string): Promise<ApprovalRequest | null>;
+  /** List pending requests */
+  listPending(options?: { limit?: number; priority?: string }): Promise<ApprovalRequest[]>;
+  /** Submit a response to a request */
+  respond<T>(response: ApprovalResponse<T>): Promise<void>;
+  /** Wait for approval with timeout */
+  waitForApproval<T>(requestId: string, timeoutMs?: number): Promise<ApprovalResponse<T>>;
+}
+
+/**
+ * Review session for interactive feedback
+ */
+export interface ReviewSession {
+  /** Session ID */
+  id: string;
+  /** Current content being reviewed */
+  content: unknown;
+  /** Reviewer feedback history */
+  feedbackHistory: Array<{
+    feedback: string;
+    timestamp: Date;
+    revision: number;
+  }>;
+  /** Number of revisions */
+  revisionCount: number;
+  /** Session status */
+  status: 'active' | 'completed' | 'abandoned';
+}

package/src/index.ts

@@ -0,0 +1,125 @@
+/**
+ * @od-oneapp/ai-platform
+ *
+ * Enterprise patterns library for Vercel AI SDK v6.
+ * Provides standardized agent orchestration, compliance policies,
+ * and tooling for monorepo environments.
+ *
+ * @module @od-oneapp/ai-platform
+ *
+ * This package exports the complete public surface for AI SDK v6 patterns.
+ */
+
+export const VERSION = '0.1.0';
+
+// =============================================================================
+// Pattern catalog (machine-readable registry of all public modules)
+// =============================================================================
+
+/** Searchable registry of all patterns and modules in this package. */
+export {
+  PATTERN_CATALOG,
+  CATALOG_DOMAINS,
+  CATALOG_TAGS,
+  searchCatalog,
+  getCatalogByDomain,
+  getCatalogByTag,
+  type CatalogEntry,
+} from './catalog';
+
+// =============================================================================
+// Convenience exports (most commonly used APIs)
+// =============================================================================
+
+/** Agent orchestration patterns */
+export {
+  createTriageAgent,
+  createKeywordTriage,
+  type TriageAgentConfig,
+  type TriageResult,
+  createCoordinatorAgent,
+  type CoordinatorConfig,
+  type ExecutionPlan,
+  type Task,
+  type TaskResult,
+} from "./agents";
+
+/** Streaming utilities and infrastructure */
+export { createResumableStream } from "./streaming";
+
+/** Output patterns and structured generation */
+export { createObjectOutput } from "./output";
+
+/** Prompt management */
+export { composeSystemPrompt, formatPromptForModel } from "./prompts";
+
+/** Pipeline orchestration */
+export { quickPipeline } from "./pipelines";
+
+/** Caching with multi-tier adapters */
+export { createCachingMiddleware } from "./caching";
+
+/** Security guardrails and injection defense */
+export { createGuardrailMiddleware } from "./security";
+
+/** Compliance, audit, policies, tenancy */
+export { createEntitlementChecker } from "./governance";
+
+/** Human-in-the-loop patterns */
+export { createFeedbackCollector } from "./hitl";
+
+/** RAG, embeddings, hallucination detection, citations */
+export { generateCitations } from "./grounding";
+
+/** Generative UI: enterprise catalog and stream factory */
+export { createEnterpriseCatalog, BASE_CATALOG_COMPONENTS } from "./generative-ui";
+export { createGenerativeUIStreamConfig } from "./generative-ui";
+
+// =============================================================================
+// Namespaced exports (complete module surfaces without name collisions)
+// =============================================================================
+
+/** Model registry with semantic names and gateway routing */
+export * as models from "./models";
+
+/** Agent orchestration patterns */
+export * as agents from "./agents";
+
+/** Streaming utilities and infrastructure */
+export * as streaming from "./streaming";
+
+/** Output patterns and structured generation */
+export * as output from "./output";
+
+/** Prompt management */
+export * as prompts from "./prompts";
+
+/** Pipeline orchestration */
+export * as pipelines from "./pipelines";
+
+/** SDK extensions and middleware */
+export * as sdk from "./sdk";
+
+/** RAG, embeddings, hallucination detection, citations */
+export * as grounding from "./grounding";
+
+/** Caching with multi-tier adapters */
+export * as caching from "./caching";
+
+/** Security guardrails and injection defense */
+export * as security from "./security";
+
+/** Compliance, audit, policies, tenancy */
+export * as governance from "./governance";
+
+/** Telemetry, tracing, analytics, cost tracking */
+export * as observability from "./observability";
+
+/** Human-in-the-loop patterns */
+export * as hitl from "./hitl";
+
+/** Tool execution patterns */
+export * as tools from "./tools";
+
+/** Generative UI: AI-driven dynamic interface generation */
+export * as generativeUI from "./generative-ui";

package/src/integrations/blob-storage/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Blob storage integration — types + Vercel Blob adapter.
+ * @module @od-oneapp/ai-platform/integrations/blob-storage
+ */
+
+export * from './types';
+export * from './vercel-blob-adapter';

package/src/integrations/blob-storage/types.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Blob storage interface for dependency injection.
+ *
+ * Compatible with Vercel Blob, Cloudflare R2, S3, or any blob-like store.
+ *
+ * @module @od-oneapp/ai-platform/integrations/blob-storage
+ */
+
+/** Result of a blob put operation. */
+export interface BlobPutResult {
+  url: string;
+}
+
+/** Options for uploading a blob. */
+export interface BlobPutOptions {
+  access: 'public' | 'private';
+  contentType?: string;
+  token?: string;
+}
+
+/** Minimal blob storage client. */
+export interface BlobStorageClient {
+  put(
+    pathname: string,
+    body: Buffer | string | ReadableStream,
+    options: BlobPutOptions,
+  ): Promise<BlobPutResult>;
+}

package/src/integrations/blob-storage/vercel-blob-adapter.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Vercel Blob adapter — the only file that imports @vercel/blob.
+ * @module @od-oneapp/ai-platform/integrations/blob-storage
+ */
+
+import { put } from '@integrations/vercel/blob-client';
+
+import type { BlobPutOptions, BlobPutResult, BlobStorageClient } from './types';
+
+/** Vercel Blob storage client. */
+export class VercelBlobClient implements BlobStorageClient {
+  async put(
+    pathname: string,
+    body: Buffer | string | ReadableStream,
+    options: BlobPutOptions,
+  ): Promise<BlobPutResult> {
+    const blob = await put(pathname, body, {
+      access: options.access as 'public',
+      contentType: options.contentType,
+      token: options.token,
+    });
+    return { url: blob.url };
+  }
+}
+
+/** Options for creating a Vercel Blob client (reserved for future use). */
+export interface VercelBlobClientOptions {
+  token?: string;
+  baseUrl?: string;
+}
+
+/** Create a Vercel Blob storage client. */
+export function createVercelBlobClient(_options?: VercelBlobClientOptions): BlobStorageClient {
+  return new VercelBlobClient();
+}

package/src/integrations/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Integration layer — all 3rd-party runtime adapters.
+ *
+ * Consumer code programs against the interfaces exported here.
+ * Concrete adapters (upstash, vercel-blob, resumable-stream, etc.)
+ * are co-located but only imported at composition roots.
+ *
+ * @module @od-oneapp/ai-platform/integrations
+ */
+
+export * from './redis';
+export * from './blob-storage';
+export * from './rate-limit';
+export * from './stream';
+export * from './notifications';

package/src/integrations/notifications/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Notifications integration — types + log adapter.
+ * @module @od-oneapp/ai-platform/integrations/notifications
+ */
+
+export * from './types';
+export * from './log-adapter';

package/src/integrations/notifications/log-adapter.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Log-based notifier — uses @repo/shared/logs as the backend.
+ * @module @od-oneapp/ai-platform/integrations/notifications
+ */
+
+import { logError, logInfo, logWarn } from '@repo/shared/logs';
+
+import type { Notification, Notifier } from './types';
+
+/** Create a Notifier that writes to the structured logger. */
+export function createLogNotifier(): Notifier {
+  return {
+    notify(notification: Notification): void {
+      const ctx = notification.id ? { id: notification.id } : undefined;
+
+      switch (notification.level) {
+        case 'error':
+          logError(new Error(notification.message), ctx);
+          break;
+        case 'warn':
+          logWarn(notification.message, ctx);
+          break;
+        case 'info':
+        default:
+          logInfo(notification.message, ctx);
+          break;
+      }
+    },
+  };
+}

package/src/integrations/notifications/types.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Notification interface for dependency injection.
+ *
+ * Abstracts user-facing notifications so the package can swap between
+ * logging, toast libraries, push services, etc.
+ *
+ * @module @od-oneapp/ai-platform/integrations/notifications
+ */
+
+/** Severity levels for notifications. */
+export type NotificationLevel = 'info' | 'warn' | 'error';
+
+/** A single notification dispatched by the system. */
+export interface Notification {
+  /** Severity / level. */
+  level: NotificationLevel;
+  /** Human-readable message. */
+  message: string;
+  /** Optional stable ID for deduplication. */
+  id?: string;
+}
+
+/** Notifier contract — implementations choose the delivery mechanism. */
+export interface Notifier {
+  /** Dispatch a notification to the user / operator. */
+  notify(notification: Notification): void;
+}

package/src/integrations/rate-limit/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Rate-limit integration — types + Upstash adapter.
+ * @module @od-oneapp/ai-platform/integrations/rate-limit
+ */
+
+export * from './types';
+export * from './upstash-adapter';

package/src/integrations/rate-limit/types.ts

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Rate limiter interface for dependency injection.
+ *
+ * Compatible with @upstash/ratelimit or any rate-limiting backend.
+ *
+ * @module @od-oneapp/ai-platform/integrations/rate-limit
+ */
+
+/** Result of a rate limit check. */
+export interface RateLimitResult {
+  /** Whether the request is allowed. */
+  success: boolean;
+  /** Maximum requests allowed in the window. */
+  limit: number;
+  /** Remaining requests in the current window. */
+  remaining: number;
+  /** Timestamp (ms) when the limit resets. */
+  reset: number;
+  /** Pending analytics promise (fire-and-forget). */
+  pending: Promise<unknown>;
+}
+
+/** Rate limiter that checks identifiers against a quota. */
+export interface RateLimiter {
+  limit(identifier: string): Promise<RateLimitResult>;
+}

package/src/integrations/rate-limit/upstash-adapter.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Upstash rate-limit adapter — the only file that imports @upstash/ratelimit.
+ * @module @od-oneapp/ai-platform/integrations/rate-limit
+ */
+
+import { Ratelimit } from '@integrations/upstash/redis-client';
+
+import type { RateLimiter } from './types';
+import type { RedisClientExtended } from '../redis/types';
+
+/** Options for creating an Upstash rate limiter. */
+export interface UpstashRateLimitOptions {
+  redis: RedisClientExtended;
+  /** Max requests per window. */
+  maxRequests: number;
+  /** Window duration (e.g., '1d', '1h', '10m'). */
+  window: Parameters<typeof Ratelimit.slidingWindow>[1];
+  /** Enable analytics. */
+  analytics?: boolean;
+  /** Key prefix. */
+  prefix?: string;
+}
+
+/** Create a rate limiter backed by Upstash. */
+export function createUpstashRateLimiter(options: UpstashRateLimitOptions): RateLimiter {
+  const limiter = new Ratelimit({
+    redis: options.redis as unknown as ConstructorParameters<typeof Ratelimit>[0]['redis'],
+    limiter: Ratelimit.slidingWindow(options.maxRequests, options.window),
+    analytics: options.analytics ?? true,
+    prefix: options.prefix ?? '@upstash/ratelimit',
+  });
+
+  return {
+    limit: async (identifier: string) => {
+      const result = await limiter.limit(identifier);
+      return {
+        success: result.success,
+        limit: result.limit,
+        remaining: result.remaining,
+        reset: result.reset,
+        pending: result.pending,
+      };
+    },
+  };
+}

package/src/integrations/redis/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Redis integration — types + Upstash adapter.
+ * @module @od-oneapp/ai-platform/integrations/redis
+ */
+
+export * from './types';
+export * from './upstash-adapter';

package/src/integrations/redis/types.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Redis client interface for dependency injection.
+ *
+ * Compatible with @upstash/redis, ioredis, Vercel KV, and any Redis-like client.
+ * Consumers program against this interface; concrete adapters live alongside.
+ *
+ * @module @od-oneapp/ai-platform/integrations/redis
+ */
+
+/** Minimal Redis client for key-value operations. */
+export interface RedisClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+  del(...keys: string[]): Promise<number>;
+  flushdb?(): Promise<unknown>;
+}
+
+/**
+ * Extended Redis client with the full set of operations used across
+ * the ai-platform package: sorted sets, lists, hashes, key scanning, etc.
+ *
+ * All @upstash/redis, ioredis, and Vercel KV clients satisfy this interface.
+ */
+export interface RedisClientExtended extends RedisClient {
+  // Connection
+  ping(): Promise<unknown>;
+
+  // Key operations
+  exists(key: string): Promise<number>;
+  expire(key: string, seconds: number): Promise<number>;
+  keys(pattern: string): Promise<string[]>;
+
+  // Numeric
+  incrby(key: string, increment: number): Promise<number>;
+
+  // Sorted sets
+  zadd(key: string, ...args: unknown[]): Promise<unknown>;
+  zrange<T = string[]>(
+    key: string,
+    start: number,
+    stop: number,
+    options?: Record<string, unknown>,
+  ): Promise<T>;
+  zrangebyscore(
+    key: string,
+    min: number | string,
+    max: number | string,
+    options?: { limit?: { offset: number; count: number } },
+  ): Promise<string[]>;
+  zrem(key: string, member: string): Promise<number>;
+
+  // Lists
+  lpush(key: string, ...values: string[]): Promise<number>;
+  rpush(key: string, ...values: string[]): Promise<number>;
+  lrange(key: string, start: number, stop: number): Promise<string[]>;
+  ltrim(key: string, start: number, stop: number): Promise<string>;
+
+  // Hashes
+  hget(key: string, field: string): Promise<string | null>;
+  hincrby(key: string, field: string, increment: number): Promise<number>;
+}
+
+/** Configuration for connecting to a Redis instance. */
+export interface RedisConfig {
+  url: string;
+  token: string;
+}

package/src/integrations/redis/upstash-adapter.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Upstash Redis adapter — the only file that imports @upstash/redis.
+ * @module @od-oneapp/ai-platform/integrations/redis
+ */
+
+import { Redis } from '@integrations/upstash/redis-client';
+
+import type { RedisClientExtended, RedisConfig } from './types';
+
+/** Create an Upstash Redis client from explicit config. */
+export function createUpstashRedis(config: RedisConfig): RedisClientExtended {
+  return new Redis({ url: config.url, token: config.token }) as unknown as RedisClientExtended;
+}
+
+/** Create an Upstash Redis client from environment variables. */
+export function createUpstashRedisFromEnv(): RedisClientExtended {
+  return Redis.fromEnv() as unknown as RedisClientExtended;
+}

package/src/integrations/stream/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Stream integration — types + resumable-stream adapter.
+ * @module @od-oneapp/ai-platform/integrations/stream
+ */
+
+export * from './types';
+export * from './resumable-adapter';

package/src/integrations/stream/resumable-adapter.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview resumable-stream adapter — the only file that imports resumable-stream.
+ * @module @od-oneapp/ai-platform/integrations/stream
+ */
+
+import { createResumableStreamContext as createContext } from 'resumable-stream';
+
+import type { ResumableStreamContext, ResumableStreamOptions } from './types';
+
+/** Create a resumable stream context backed by the `resumable-stream` package. */
+export function createResumableStream(options?: ResumableStreamOptions): ResumableStreamContext {
+  const ctx = createContext({ waitUntil: options?.waitUntil ?? null });
+  return {
+    resumeExistingStream: async (streamId: string) =>
+      (await ctx.resumeExistingStream(streamId)) ?? null,
+    createNewResumableStream: async (streamId: string, streamFactory: () => ReadableStream) => {
+      await ctx.createNewResumableStream(streamId, streamFactory);
+    },
+  };
+}

package/src/integrations/stream/types.ts

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Resumable stream interface for dependency injection.
+ *
+ * Abstracts stream resumption so the package can support multiple
+ * resumable-stream backends (or custom implementations) in the future.
+ *
+ * @module @od-oneapp/ai-platform/integrations/stream
+ */
+
+/** Context for managing resumable streams. */
+export interface ResumableStreamContext {
+  /** Resume an existing stream by ID. Returns null if not found / expired. */
+  resumeExistingStream(streamId: string): Promise<ReadableStream | null>;
+  /** Create a new resumable stream and register it by ID. */
+  createNewResumableStream(streamId: string, streamFactory: () => ReadableStream): Promise<void>;
+}
+
+/** Factory options for creating a resumable stream context. */
+export interface ResumableStreamOptions {
+  waitUntil?: (promise: Promise<unknown>) => void;
+}