@od-oneapp/ai-platform 0.1.0

package/src/catalog.ts

@@ -0,0 +1,921 @@
+/**
+ * @fileoverview Pattern catalog for the ai-platform package.
+ *
+ * Machine-readable registry of every public module, pattern, and capability
+ * exposed by this package. Designed for both human developers and AI agents
+ * to discover what's available and when to use each piece.
+ *
+ * Import the catalog and search/filter programmatically:
+ * ```ts
+ * import { PATTERN_CATALOG } from '@od-oneapp/ai-platform/catalog';
+ *
+ * // Find all RAG-related patterns
+ * const ragPatterns = PATTERN_CATALOG.filter(p => p.tags.includes('rag'));
+ *
+ * // Find patterns for a use case
+ * const streaming = PATTERN_CATALOG.filter(p => p.domain === 'streaming');
+ * ```
+ *
+ * @module @od-oneapp/ai-platform/catalog
+ */
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+/** A single entry in the pattern catalog. */
+export interface CatalogEntry {
+  /** Unique kebab-case identifier. */
+  id: string;
+  /** Human-readable name. */
+  name: string;
+  /** Package subpath export (e.g. `'./agents/triage'`). */
+  module: string;
+  /** Top-level domain grouping. */
+  domain:
+    | 'agents'
+    | 'models'
+    | 'streaming'
+    | 'grounding'
+    | 'tools'
+    | 'sdk'
+    | 'security'
+    | 'governance'
+    | 'observability'
+    | 'hitl'
+    | 'output'
+    | 'prompts'
+    | 'pipelines'
+    | 'caching'
+    | 'shared'
+    | 'integrations'
+    | 'generative-ui';
+  /** One-sentence description of what this module provides. */
+  description: string;
+  /** Searchable tags for filtering. */
+  tags: readonly string[];
+  /** When you should reach for this pattern. */
+  useCase: string;
+}
+
+// ---------------------------------------------------------------------------
+// Catalog
+// ---------------------------------------------------------------------------
+
+/**
+ * Complete catalog of public patterns and modules in `@od-oneapp/ai-platform`.
+ *
+ * Every entry maps to a `package.json` subpath export.
+ * Use `domain` or `tags` to filter programmatically.
+ */
+export const PATTERN_CATALOG: readonly CatalogEntry[] = [
+  // ===========================================================================
+  // MODELS
+  // ===========================================================================
+  {
+    id: 'models',
+    name: 'Model Registry',
+    module: './models',
+    domain: 'models',
+    description:
+      'LLM provider integration with model registry, metadata, tier routing, and cost estimation.',
+    tags: ['model', 'registry', 'routing', 'cost'],
+    useCase: 'When you need to select, configure, or route between LLM providers.',
+  },
+
+  // ===========================================================================
+  // AGENTS
+  // ===========================================================================
+  {
+    id: 'agents',
+    name: 'Agent Framework',
+    module: './agents',
+    domain: 'agents',
+    description:
+      'Multi-faceted AI agent framework with core types, routing, coordination, patterns, and workflows.',
+    tags: ['agent', 'orchestration', 'framework'],
+    useCase: 'Top-level import when you need any agent capability.',
+  },
+  {
+    id: 'agents-base',
+    name: 'Agent Base',
+    module: './agents/base',
+    domain: 'agents',
+    description: 'Base agent types, schemas, and default agent implementation.',
+    tags: ['agent', 'base', 'types', 'schemas'],
+    useCase: 'When building a custom agent from scratch or extending base types.',
+  },
+  {
+    id: 'agents-coordinator',
+    name: 'Coordinator Agent',
+    module: './agents/coordinator',
+    domain: 'agents',
+    description:
+      'Multi-agent orchestration with task planning, delegation, and result aggregation.',
+    tags: ['agent', 'coordinator', 'orchestration', 'planning'],
+    useCase: 'When you need a lead agent that plans and delegates work to sub-agents.',
+  },
+  {
+    id: 'agents-swarm',
+    name: 'Swarm Agent',
+    module: './agents/multi/swarm',
+    domain: 'agents',
+    description: 'Agent swarm coordination with parallel task execution and result aggregation.',
+    tags: ['agent', 'swarm', 'parallel', 'multi-agent'],
+    useCase: 'When you need many agents working in parallel on independent tasks.',
+  },
+  {
+    id: 'agents-multi',
+    name: 'Multi-Agent System',
+    module: './agents/multi',
+    domain: 'agents',
+    description: 'Multi-agent coordination, supervision, and state management.',
+    tags: ['agent', 'multi-agent', 'coordination', 'supervision'],
+    useCase: 'When you need agents that communicate, delegate, and share state.',
+  },
+  {
+    id: 'agents-persistence',
+    name: 'Agent Persistence',
+    module: './agents/persistence',
+    domain: 'agents',
+    description:
+      'Durable state management with checkpoint/restore for crash recovery and resumable workflows.',
+    tags: ['agent', 'persistence', 'checkpoint', 'recovery'],
+    useCase: 'When agent state must survive restarts or be resumed later.',
+  },
+  {
+    id: 'agents-control-flow',
+    name: 'Agent Control Flow',
+    module: './agents/control-flow',
+    domain: 'agents',
+    description:
+      'Control patterns for agent execution: abort signals, stops, timeouts, and manual intervention.',
+    tags: ['agent', 'control-flow', 'abort', 'timeout'],
+    useCase: 'When you need to cancel, timeout, or manually intervene in agent execution.',
+  },
+  {
+    id: 'agents-fallback',
+    name: 'Agent Fallback',
+    module: './agents/fallback',
+    domain: 'agents',
+    description: 'Model fallback strategies, circuit breakers, and resilience patterns.',
+    tags: ['agent', 'fallback', 'resilience', 'circuit-breaker'],
+    useCase: 'When you need automatic model failover or rate-limit recovery.',
+  },
+  {
+    id: 'agents-patterns',
+    name: 'Agent Patterns',
+    module: './agents/patterns',
+    domain: 'agents',
+    description: 'Reusable agent architectures like evaluator-optimizer feedback loops.',
+    tags: ['agent', 'patterns', 'evaluator-optimizer', 'feedback'],
+    useCase: 'When you need a documented, reusable agent architecture pattern.',
+  },
+  {
+    id: 'agents-experimental',
+    name: 'Experimental Agents',
+    module: './agents/experimental',
+    domain: 'agents',
+    description: 'AI SDK v6 agent patterns with prepareStep hook and phased tools (unstable).',
+    tags: ['agent', 'experimental', 'prepareStep'],
+    useCase: 'When you want to test new agent capabilities before they stabilize.',
+  },
+  {
+    id: 'agents-observability',
+    name: 'Agent Observability',
+    module: './agents/observability',
+    domain: 'agents',
+    description:
+      'Step-by-step execution tracing and debugging for agents with decision logs and metrics.',
+    tags: ['agent', 'observability', 'tracing', 'debugging'],
+    useCase: 'When you need detailed visibility into agent decision-making.',
+  },
+  {
+    id: 'agents-workflows',
+    name: 'Agent Workflows',
+    module: './agents/workflows',
+    domain: 'agents',
+    description:
+      'Workflow definition and execution interfaces for Vercel Workflows (WDK) integration.',
+    tags: ['agent', 'workflow', 'wdk'],
+    useCase: 'When agents need to execute as durable Vercel Workflows.',
+  },
+
+  // ===========================================================================
+  // STREAMING
+  // ===========================================================================
+  {
+    id: 'streaming',
+    name: 'Streaming',
+    module: './streaming',
+    domain: 'streaming',
+    description:
+      'Unified streaming utilities for AI responses with transforms and control patterns.',
+    tags: ['streaming', 'response', 'transform'],
+    useCase: 'Top-level import when you need any streaming capability.',
+  },
+  {
+    id: 'streaming-core',
+    name: 'Streaming Core',
+    module: './streaming/core',
+    domain: 'streaming',
+    description: 'Core artifact and data streaming with writer utilities for streaming protocols.',
+    tags: ['streaming', 'core', 'artifact', 'writer'],
+    useCase: 'When building custom stream writers or artifact streams.',
+  },
+  {
+    id: 'streaming-control',
+    name: 'Streaming Control',
+    module: './streaming/control',
+    domain: 'streaming',
+    description: 'Composable streaming patterns: budget guards, step limits, stream smoothing.',
+    tags: ['streaming', 'control', 'budget', 'throttle'],
+    useCase: 'When you need to limit, smooth, or guard streaming output.',
+  },
+  {
+    id: 'streaming-infra',
+    name: 'Streaming Infrastructure',
+    module: './streaming/infra',
+    domain: 'streaming',
+    description: 'Infrastructure: transforms, metrics, backpressure, multiplexing.',
+    tags: ['streaming', 'infra', 'transform', 'metrics'],
+    useCase: 'When you need low-level stream processing or metrics collection.',
+  },
+  {
+    id: 'streaming-resilience',
+    name: 'Streaming Resilience',
+    module: './streaming/infra/resilience',
+    domain: 'streaming',
+    description:
+      'Stream recovery and resumption from Redis checkpoints for fault-tolerant operations.',
+    tags: ['streaming', 'resilience', 'checkpoint', 'recovery'],
+    useCase: 'When long-running streams must survive disconnections.',
+  },
+  {
+    id: 'streaming-transport',
+    name: 'Streaming Transport',
+    module: './streaming/infra/transport',
+    domain: 'streaming',
+    description: 'Transport adapters for SSE, WebSocket, and HTTP streaming protocols.',
+    tags: ['streaming', 'transport', 'sse', 'websocket'],
+    useCase: 'When you need to expose streams over different transport protocols.',
+  },
+
+  // ===========================================================================
+  // TOOLS
+  // ===========================================================================
+  {
+    id: 'tools',
+    name: 'Tool System',
+    module: './tools',
+    domain: 'tools',
+    description:
+      'Tool execution patterns including core definitions, computer use, MCP, and specialized capabilities.',
+    tags: ['tool', 'execution', 'framework'],
+    useCase: 'Top-level import when you need any tool capability.',
+  },
+  {
+    id: 'tools-core',
+    name: 'Tool Core',
+    module: './tools/core',
+    domain: 'tools',
+    description:
+      'Core tool utilities: factory methods, abort signal handling, validation wrappers.',
+    tags: ['tool', 'core', 'factory', 'validation'],
+    useCase: 'When building or wrapping custom tools.',
+  },
+  {
+    id: 'tools-computer',
+    name: 'Computer Use',
+    module: './tools/computer',
+    domain: 'tools',
+    description: 'Browser automation and computer use for agent interaction with web interfaces.',
+    tags: ['tool', 'computer-use', 'browser', 'automation'],
+    useCase: 'When agents need to interact with web UIs or take screenshots.',
+  },
+  {
+    id: 'tools-mcp',
+    name: 'MCP Integration',
+    module: './tools/mcp',
+    domain: 'tools',
+    description:
+      'Model Context Protocol integration with client, connection management, and tool caching.',
+    tags: ['tool', 'mcp', 'protocol', 'external'],
+    useCase: 'When integrating external tool servers via MCP protocol.',
+  },
+  {
+    id: 'tools-superpowers',
+    name: 'Superpowers Tools',
+    module: './tools/superpowers',
+    domain: 'tools',
+    description:
+      '20 engineering-focused tools that enforce planning, testing, and validation patterns.',
+    tags: ['tool', 'superpowers', 'engineering', 'planning'],
+    useCase: 'When agents need structured engineering workflows (plan → implement → test).',
+  },
+  {
+    id: 'tools-approval',
+    name: 'Tool Approval',
+    module: './tools/approval',
+    domain: 'tools',
+    description: 'HITL approval system: tool wrappers, middleware chain, pluggable queue backends.',
+    tags: ['tool', 'approval', 'hitl', 'middleware'],
+    useCase: 'When tool execution needs human approval before proceeding.',
+  },
+  {
+    id: 'tools-compliance',
+    name: 'Tool Compliance',
+    module: './tools/compliance',
+    domain: 'tools',
+    description:
+      'Tool compliance wrappers for ABAC, approval workflows, timeouts, and retry patterns.',
+    tags: ['tool', 'compliance', 'abac', 'wrapper'],
+    useCase: 'When tools must enforce access control or compliance policies.',
+  },
+
+  // ===========================================================================
+  // GROUNDING
+  // ===========================================================================
+  {
+    id: 'grounding',
+    name: 'Grounding',
+    module: './grounding',
+    domain: 'grounding',
+    description:
+      'RAG, embeddings, and response verification: citation, hallucination detection, source attribution.',
+    tags: ['grounding', 'rag', 'citation', 'verification'],
+    useCase: 'Top-level import when you need any grounding capability.',
+  },
+  {
+    id: 'grounding-rag',
+    name: 'Research Pipeline',
+    module: './grounding/rag',
+    domain: 'grounding',
+    description:
+      'Three-stage research pipeline (context expansion → reasoning → verification) with configurable models.',
+    tags: ['grounding', 'rag', 'research', 'pipeline', 'multi-model'],
+    useCase: 'When you need citation-backed, verified research answers.',
+  },
+  {
+    id: 'grounding-embed',
+    name: 'Embeddings',
+    module: './grounding/embed',
+    domain: 'grounding',
+    description: 'Text chunking, embedding generation, similarity search, and reranking.',
+    tags: ['grounding', 'embedding', 'search', 'reranking'],
+    useCase: 'When you need vector-based retrieval for RAG.',
+  },
+  {
+    id: 'grounding-citation',
+    name: 'Citations',
+    module: './grounding/citation',
+    domain: 'grounding',
+    description: 'Citation generation from retrieved sources with verification and formatting.',
+    tags: ['grounding', 'citation', 'source'],
+    useCase: 'When AI responses need inline citations referencing source material.',
+  },
+  {
+    id: 'grounding-hallucination',
+    name: 'Hallucination Detection',
+    module: './grounding/hallucination',
+    domain: 'grounding',
+    description: 'Identifies claims in AI output that are unsupported by source documents.',
+    tags: ['grounding', 'hallucination', 'detection', 'verification'],
+    useCase: 'When you need post-generation truthfulness checking.',
+  },
+  {
+    id: 'grounding-attribution',
+    name: 'Source Attribution',
+    module: './grounding/attribution',
+    domain: 'grounding',
+    description: 'Tracks which sources contributed to AI-generated content for transparency.',
+    tags: ['grounding', 'attribution', 'transparency', 'audit'],
+    useCase: 'When you need an audit trail of which sources informed each claim.',
+  },
+  {
+    id: 'grounding-verification',
+    name: 'Fact Verification',
+    module: './grounding/verification',
+    domain: 'grounding',
+    description: 'Fact verification against knowledge sources with confidence scoring.',
+    tags: ['grounding', 'verification', 'fact-check', 'confidence'],
+    useCase: 'When individual claims must be verified against authoritative sources.',
+  },
+  {
+    id: 'grounding-context',
+    name: 'Request Context',
+    module: './grounding/context',
+    domain: 'grounding',
+    description: 'Identity and request context management with permission checking.',
+    tags: ['grounding', 'context', 'identity', 'permissions'],
+    useCase: 'When you need request-scoped context propagation through the pipeline.',
+  },
+  {
+    id: 'grounding-proof-map',
+    name: 'Proof Maps',
+    module: './grounding/proof-map',
+    domain: 'grounding',
+    description:
+      'Multi-model proof loops and patch application for structured verification of AI outputs.',
+    tags: ['grounding', 'proof', 'verification', 'patch'],
+    useCase: 'When you need structured, multi-step verification of complex AI outputs.',
+  },
+
+  // ===========================================================================
+  // SDK
+  // ===========================================================================
+  {
+    id: 'sdk',
+    name: 'SDK Extensions',
+    module: './sdk',
+    domain: 'sdk',
+    description:
+      'Vercel AI SDK v6 extensions: error hierarchy, stop conditions, and middleware patterns.',
+    tags: ['sdk', 'extension', 'middleware'],
+    useCase: 'Top-level import when you need any SDK extension.',
+  },
+  {
+    id: 'sdk-errors',
+    name: 'Error Hierarchy',
+    module: './sdk/errors',
+    domain: 'sdk',
+    description: 'Unified error hierarchy with error codes, retry info, and structured metadata.',
+    tags: ['sdk', 'errors', 'retry', 'hierarchy'],
+    useCase: 'When you need typed, classifiable errors with retry semantics.',
+  },
+  {
+    id: 'sdk-stop-conditions',
+    name: 'Stop Conditions',
+    module: './sdk/stop-conditions',
+    domain: 'sdk',
+    description: 'Utilities for controlling agentic loop termination with condition evaluation.',
+    tags: ['sdk', 'stop', 'termination', 'control'],
+    useCase: 'When you need custom logic for when an agent should stop iterating.',
+  },
+  {
+    id: 'sdk-experimental',
+    name: 'SDK Experimental',
+    module: './sdk/experimental',
+    domain: 'sdk',
+    description: 'Experimental SDK v6 features using experimental_ prefix (unstable).',
+    tags: ['sdk', 'experimental'],
+    useCase: 'When you want to test new SDK capabilities before they stabilize.',
+  },
+
+  // ===========================================================================
+  // SECURITY
+  // ===========================================================================
+  {
+    id: 'security',
+    name: 'Security',
+    module: './security',
+    domain: 'security',
+    description: 'Guardrails, injection detection, and PII filtering for secure AI applications.',
+    tags: ['security', 'guardrails', 'pii', 'injection'],
+    useCase: 'Top-level import when you need any security capability.',
+  },
+  {
+    id: 'security-guardrails',
+    name: 'Guardrails',
+    module: './security/guardrails',
+    domain: 'security',
+    description: 'PII filtering and content filtering middleware for response security.',
+    tags: ['security', 'guardrails', 'pii', 'filter'],
+    useCase: 'When AI responses must be scrubbed of PII or harmful content.',
+  },
+  {
+    id: 'security-injection',
+    name: 'Injection Defense',
+    module: './security/injection',
+    domain: 'security',
+    description: 'Prompt injection detection and defense mechanisms.',
+    tags: ['security', 'injection', 'defense', 'detection'],
+    useCase: 'When user input must be screened for prompt injection attacks.',
+  },
+
+  // ===========================================================================
+  // GOVERNANCE
+  // ===========================================================================
+  {
+    id: 'governance',
+    name: 'Governance',
+    module: './governance',
+    domain: 'governance',
+    description:
+      'Enterprise compliance, audit, policy, and multi-tenant management for AI systems.',
+    tags: ['governance', 'compliance', 'audit', 'policy'],
+    useCase: 'Top-level import when you need any governance capability.',
+  },
+  {
+    id: 'governance-compliance',
+    name: 'Compliance',
+    module: './governance/compliance',
+    domain: 'governance',
+    description: 'ABAC policy engine, PHI detection, redaction, and approval workflows.',
+    tags: ['governance', 'compliance', 'abac', 'phi', 'redaction'],
+    useCase: 'When you need access control policies or PHI handling.',
+  },
+  {
+    id: 'governance-audit',
+    name: 'Audit',
+    module: './governance/audit',
+    domain: 'governance',
+    description: 'Audit logging and schema for tracking AI system operations.',
+    tags: ['governance', 'audit', 'logging', 'tracking'],
+    useCase: 'When you need a tamper-evident audit trail of AI operations.',
+  },
+  {
+    id: 'governance-policies',
+    name: 'Policies',
+    module: './governance/policies',
+    domain: 'governance',
+    description:
+      'Policy definitions for guardrails, loop controls, and telemetry governing agent behavior.',
+    tags: ['governance', 'policy', 'guardrails', 'rules'],
+    useCase: 'When you need to define declarative rules that constrain agents.',
+  },
+  {
+    id: 'governance-tenancy',
+    name: 'Multi-Tenancy',
+    module: './governance/tenancy',
+    domain: 'governance',
+    description: 'Tenant isolation, quota management, and per-tenant configuration.',
+    tags: ['governance', 'tenancy', 'isolation', 'quota'],
+    useCase: 'When you need to isolate AI resources across tenants with quotas.',
+  },
+
+  // ===========================================================================
+  // OBSERVABILITY
+  // ===========================================================================
+  {
+    id: 'observability',
+    name: 'Observability',
+    module: './observability',
+    domain: 'observability',
+    description:
+      'Monitoring, tracing, and cost management with telemetry, analytics, and budget tracking.',
+    tags: ['observability', 'monitoring', 'tracing', 'cost'],
+    useCase: 'Top-level import when you need any observability capability.',
+  },
+  {
+    id: 'observability-telemetry',
+    name: 'Telemetry',
+    module: './observability/telemetry',
+    domain: 'observability',
+    description:
+      'AI SDK v6 telemetry: span tracing, token usage, cost estimation, and latency metrics.',
+    tags: ['observability', 'telemetry', 'spans', 'tokens'],
+    useCase: 'When you need fine-grained span-level metrics for AI calls.',
+  },
+  {
+    id: 'observability-tracing',
+    name: 'Distributed Tracing',
+    module: './observability/tracing',
+    domain: 'observability',
+    description:
+      'OpenTelemetry-compatible instrumentation with multiple exporters (Langfuse, Axiom, Datadog).',
+    tags: ['observability', 'tracing', 'otel', 'langfuse', 'axiom'],
+    useCase: 'When you need distributed tracing exported to external APM tools.',
+  },
+  {
+    id: 'observability-analytics',
+    name: 'Analytics',
+    module: './observability/analytics',
+    domain: 'observability',
+    description:
+      'AI usage analytics with token tracking, cost estimation, and performance metrics.',
+    tags: ['observability', 'analytics', 'usage', 'performance'],
+    useCase: 'When you need aggregate analytics over AI usage patterns.',
+  },
+  {
+    id: 'observability-cost',
+    name: 'Cost Tracking',
+    module: './observability/cost',
+    domain: 'observability',
+    description:
+      'Cost tracking middleware for enforcing budgets and attributing costs to users/teams/features.',
+    tags: ['observability', 'cost', 'budget', 'attribution'],
+    useCase: 'When you need to enforce spend limits or attribute AI costs.',
+  },
+
+  // ===========================================================================
+  // HITL
+  // ===========================================================================
+  {
+    id: 'hitl',
+    name: 'Human-in-the-Loop',
+    module: './hitl',
+    domain: 'hitl',
+    description:
+      'Human-in-the-loop integration: approval queues, review triggers, and escalation handling.',
+    tags: ['hitl', 'human', 'review', 'approval'],
+    useCase: 'Top-level import when you need any HITL capability.',
+  },
+  {
+    id: 'hitl-feedback',
+    name: 'Feedback Collection',
+    module: './hitl/feedback',
+    domain: 'hitl',
+    description:
+      'User feedback collection and aggregation for quality monitoring and model improvement.',
+    tags: ['hitl', 'feedback', 'quality', 'rating'],
+    useCase: 'When you need thumbs-up/down or free-text feedback on AI responses.',
+  },
+  {
+    id: 'hitl-annotation',
+    name: 'Annotation',
+    module: './hitl/annotation',
+    domain: 'hitl',
+    description: 'Human annotation tools for labeling and correcting AI outputs as training data.',
+    tags: ['hitl', 'annotation', 'labeling', 'training'],
+    useCase: 'When humans need to label AI outputs for fine-tuning or evaluation.',
+  },
+  {
+    id: 'hitl-active-learning',
+    name: 'Active Learning',
+    module: './hitl/active-learning',
+    domain: 'hitl',
+    description: 'Intelligent sample selection for human annotation to maximize model improvement.',
+    tags: ['hitl', 'active-learning', 'sampling', 'optimization'],
+    useCase: 'When you want to pick the most informative samples for human review.',
+  },
+  {
+    id: 'hitl-approval',
+    name: 'HITL Approval',
+    module: './hitl/approval',
+    domain: 'hitl',
+    description: 'Approval queue for human review gates on sensitive AI outputs.',
+    tags: ['hitl', 'approval', 'queue', 'gate'],
+    useCase: 'When AI outputs must be approved by a human before being used.',
+  },
+  {
+    id: 'hitl-review',
+    name: 'Review Triggers',
+    module: './hitl/review',
+    domain: 'hitl',
+    description: 'Human review workflow triggers based on confidence, risk, and content analysis.',
+    tags: ['hitl', 'review', 'trigger', 'confidence'],
+    useCase: 'When you need automatic escalation to humans based on risk signals.',
+  },
+
+  // ===========================================================================
+  // OUTPUT
+  // ===========================================================================
+  {
+    id: 'output',
+    name: 'Output',
+    module: './output',
+    domain: 'output',
+    description:
+      'Output API factories for structured generation: objects, arrays, choices, and streaming.',
+    tags: ['output', 'structured', 'generation', 'factory'],
+    useCase: 'When you need typed, validated structured output from models.',
+  },
+  {
+    id: 'output-multimodal',
+    name: 'Multimodal Output',
+    module: './output/multimodal',
+    domain: 'output',
+    description: 'Image generation, audio, and speech/transcription for multimodal AI output.',
+    tags: ['output', 'multimodal', 'image', 'audio'],
+    useCase: 'When agents need to produce images, audio, or other non-text output.',
+  },
+
+  // ===========================================================================
+  // PROMPTS
+  // ===========================================================================
+  {
+    id: 'prompts',
+    name: 'Prompt Management',
+    module: './prompts',
+    domain: 'prompts',
+    description:
+      'Centralized system prompt management with model-specific composition and variants.',
+    tags: ['prompt', 'template', 'composition', 'model-specific'],
+    useCase: 'When you need reusable, model-optimized prompt templates.',
+  },
+
+  // ===========================================================================
+  // PIPELINES
+  // ===========================================================================
+  {
+    id: 'pipelines',
+    name: 'Pipelines',
+    module: './pipelines',
+    domain: 'pipelines',
+    description: 'Multi-step pipeline execution with resumption, compliance checking, and tracing.',
+    tags: ['pipeline', 'multi-step', 'orchestration', 'resumption'],
+    useCase: 'When you need a sequence of AI steps with built-in compliance and tracing.',
+  },
+
+  // ===========================================================================
+  // CACHING
+  // ===========================================================================
+  {
+    id: 'caching',
+    name: 'Caching',
+    module: './caching',
+    domain: 'caching',
+    description:
+      'Response caching middleware with multiple storage backends and eviction strategies.',
+    tags: ['caching', 'middleware', 'storage'],
+    useCase: 'Top-level import when you need any caching capability.',
+  },
+  {
+    id: 'caching-adapters',
+    name: 'Cache Adapters',
+    module: './caching/adapters',
+    domain: 'caching',
+    description: 'Cache adapter implementations for memory and Redis storage backends.',
+    tags: ['caching', 'adapter', 'memory', 'redis'],
+    useCase: 'When you need to plug in a specific cache storage backend.',
+  },
+  {
+    id: 'caching-strategies',
+    name: 'Cache Strategies',
+    module: './caching/strategies',
+    domain: 'caching',
+    description: 'Pluggable eviction strategies: LRU, LFU, TTL, FIFO, Adaptive.',
+    tags: ['caching', 'strategy', 'lru', 'lfu', 'ttl', 'eviction'],
+    useCase: 'When you need a specific eviction policy for your cache.',
+  },
+
+  // ===========================================================================
+  // SHARED
+  // ===========================================================================
+  {
+    id: 'shared',
+    name: 'Shared SDK Layer',
+    module: './shared',
+    domain: 'shared',
+    description:
+      'Centralized SDK types and runtime exports — canonical import path for all AI SDK usage.',
+    tags: ['shared', 'sdk', 'types', 'runtime'],
+    useCase: 'When importing AI SDK types or runtime functions (instead of directly from "ai").',
+  },
+
+  // ===========================================================================
+  // INTEGRATIONS
+  // ===========================================================================
+  {
+    id: 'integrations',
+    name: 'Integrations',
+    module: './integrations',
+    domain: 'integrations',
+    description:
+      'Third-party runtime adapter interfaces: Redis, Blob Storage, Rate Limit, Stream, Notifications.',
+    tags: ['integrations', 'adapter', 'third-party'],
+    useCase: 'Top-level import when you need any integration adapter.',
+  },
+  {
+    id: 'integrations-redis',
+    name: 'Redis Integration',
+    module: './integrations/redis',
+    domain: 'integrations',
+    description: 'RedisClient/RedisClientExtended interfaces with Upstash adapter implementation.',
+    tags: ['integrations', 'redis', 'upstash', 'cache'],
+    useCase: 'When you need Redis KV or extended commands (lists, hashes, sorted sets).',
+  },
+  {
+    id: 'integrations-blob-storage',
+    name: 'Blob Storage Integration',
+    module: './integrations/blob-storage',
+    domain: 'integrations',
+    description: 'BlobStorageClient interface with Vercel Blob adapter implementation.',
+    tags: ['integrations', 'blob', 'storage', 'vercel'],
+    useCase: 'When you need to store/retrieve files or large objects.',
+  },
+  {
+    id: 'integrations-rate-limit',
+    name: 'Rate Limit Integration',
+    module: './integrations/rate-limit',
+    domain: 'integrations',
+    description: 'RateLimiter interface with Upstash rate-limit adapter.',
+    tags: ['integrations', 'rate-limit', 'upstash', 'throttle'],
+    useCase: 'When you need distributed rate limiting for API calls.',
+  },
+  {
+    id: 'integrations-stream',
+    name: 'Stream Integration',
+    module: './integrations/stream',
+    domain: 'integrations',
+    description: 'ResumableStreamContext interface with resumable stream adapter.',
+    tags: ['integrations', 'stream', 'resumable'],
+    useCase: 'When you need streams that survive disconnections and resume.',
+  },
+  {
+    id: 'integrations-notifications',
+    name: 'Notifications Integration',
+    module: './integrations/notifications',
+    domain: 'integrations',
+    description:
+      'Notifier interface with log adapter (replaces sonner for server-side notifications).',
+    tags: ['integrations', 'notifications', 'toast', 'log'],
+    useCase: 'When you need to emit notifications from AI pipeline events.',
+  },
+
+  // ===========================================================================
+  // GENERATIVE UI
+  // ===========================================================================
+  {
+    id: 'generative-ui',
+    name: 'Generative UI',
+    module: './generative-ui',
+    domain: 'generative-ui',
+    description:
+      'AI-driven dynamic interface generation with enterprise catalog, streaming, and governance.',
+    tags: ['generative-ui', 'dynamic', 'catalog', 'streaming', 'json-render'],
+    useCase: 'Top-level import when you need AI to generate dynamic user interfaces.',
+  },
+  {
+    id: 'generative-ui-catalog',
+    name: 'UI Catalog',
+    module: './generative-ui/catalog',
+    domain: 'generative-ui',
+    description:
+      'Enterprise component catalog with entitlement-based filtering and prompt generation.',
+    tags: ['generative-ui', 'catalog', 'entitlements', 'prompt'],
+    useCase: 'When defining which UI components AI can use, filtered by user tier.',
+  },
+  {
+    id: 'generative-ui-registry',
+    name: 'UI Registry',
+    module: './generative-ui/registry',
+    domain: 'generative-ui',
+    description: 'Zod schema registry for runtime validation of AI-generated component props.',
+    tags: ['generative-ui', 'registry', 'validation', 'zod', 'schema'],
+    useCase: 'When you need to validate AI-generated UI trees before rendering.',
+  },
+  {
+    id: 'generative-ui-stream',
+    name: 'UI Stream',
+    module: './generative-ui/stream',
+    domain: 'generative-ui',
+    description:
+      'Streaming configuration for generative UI with budget guards, audit logging, and validation.',
+    tags: ['generative-ui', 'stream', 'budget', 'audit', 'streaming'],
+    useCase: 'When streaming AI-generated UI trees with cost control and audit.',
+  },
+] as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** All unique domain names in the catalog. */
+export const CATALOG_DOMAINS = [...new Set(PATTERN_CATALOG.map(e => e.domain))] as const;
+
+/** All unique tags used in the catalog. */
+export const CATALOG_TAGS = [
+  ...new Set(PATTERN_CATALOG.flatMap(e => e.tags)),
+].sort() as readonly string[];
+
+/**
+ * Find catalog entries matching a query.
+ *
+ * Searches id, name, description, tags, and useCase fields (case-insensitive).
+ *
+ * @param query - Search string.
+ * @returns Matching catalog entries.
+ * @example
+ * ```ts
+ * import { searchCatalog } from '@od-oneapp/ai-platform/catalog';
+ *
+ * searchCatalog('approval');
+ * // → [tools-approval, hitl-approval, governance-compliance, ...]
+ *
+ * searchCatalog('circuit breaker');
+ * // → [agents-fallback, grounding-rag]
+ * ```
+ */
+export function searchCatalog(query: string): readonly CatalogEntry[] {
+  const q = query.toLowerCase();
+  return PATTERN_CATALOG.filter(
+    e =>
+      e.id.includes(q) ||
+      e.name.toLowerCase().includes(q) ||
+      e.description.toLowerCase().includes(q) ||
+      e.tags.some(t => t.includes(q)) ||
+      e.useCase.toLowerCase().includes(q),
+  );
+}
+
+/**
+ * Get all catalog entries for a given domain.
+ *
+ * @param domain - Domain to filter by.
+ * @returns Catalog entries in that domain.
+ */
+export function getCatalogByDomain(domain: CatalogEntry['domain']): readonly CatalogEntry[] {
+  return PATTERN_CATALOG.filter(e => e.domain === domain);
+}
+
+/**
+ * Get all catalog entries that include a specific tag.
+ *
+ * @param tag - Tag to filter by.
+ * @returns Catalog entries with that tag.
+ */
+export function getCatalogByTag(tag: string): readonly CatalogEntry[] {
+  return PATTERN_CATALOG.filter(e => e.tags.includes(tag));
+}