@talex-touch/utils 1.0.40 → 1.0.44

package/types/intelligence.ts

@@ -1,4 +1,9 @@
-export enum AiProviderType {
+import { NEXUS_BASE_URL } from '../env'
+
+/**
+ * Supported intelligence provider types.
+ */
+export enum IntelligenceProviderType {
   OPENAI = 'openai',
   ANTHROPIC = 'anthropic',
   DEEPSEEK = 'deepseek',
@@ -7,295 +12,1672 @@ export enum AiProviderType {
   CUSTOM = 'custom',
 }
 
-export enum AiCapabilityType {
+/**
+ * Intelligence capability types for various AI operations.
+ */
+export enum IntelligenceCapabilityType {
+  // Text capabilities
   CHAT = 'chat',
   COMPLETION = 'completion',
   EMBEDDING = 'embedding',
   SUMMARIZE = 'summarize',
   TRANSLATE = 'translate',
+  REWRITE = 'rewrite',
+  GRAMMAR_CHECK = 'grammar-check',
+  // Code capabilities
+  CODE_GENERATE = 'code-generate',
+  CODE_EXPLAIN = 'code-explain',
+  CODE_REVIEW = 'code-review',
+  CODE_REFACTOR = 'code-refactor',
+  CODE_DEBUG = 'code-debug',
+  // Analysis capabilities
+  INTENT_DETECT = 'intent-detect',
+  SENTIMENT_ANALYZE = 'sentiment-analyze',
+  CONTENT_EXTRACT = 'content-extract',
+  KEYWORDS_EXTRACT = 'keywords-extract',
+  CLASSIFICATION = 'classification',
+  // Audio capabilities
   TTS = 'tts',
   STT = 'stt',
+  AUDIO_TRANSCRIBE = 'audio-transcribe',
+  // Vision capabilities
   VISION = 'vision',
+  VISION_OCR = 'vision-ocr',
+  IMAGE_CAPTION = 'image-caption',
+  IMAGE_ANALYZE = 'image-analyze',
+  IMAGE_GENERATE = 'image-generate',
+  IMAGE_EDIT = 'image-edit',
+  // RAG & Search capabilities
+  RAG_QUERY = 'rag-query',
+  SEMANTIC_SEARCH = 'semantic-search',
+  RERANK = 'rerank',
+  // Workflow capabilities
+  WORKFLOW = 'workflow',
+  AGENT = 'agent',
 }
 
-export interface AiProviderRateLimit {
+/**
+ * Rate limit configuration for an intelligence provider.
+ */
+export interface IntelligenceProviderRateLimit {
+  /** Maximum requests allowed per minute. */
   requestsPerMinute?: number
+  /** Maximum requests allowed per day. */
   requestsPerDay?: number
+  /** Maximum tokens allowed per minute. */
   tokensPerMinute?: number
+  /** Maximum tokens allowed per day. */
   tokensPerDay?: number
 }
 
-export interface AiVisionImageSource {
+/**
+ * Image source configuration for vision capabilities.
+ */
+export interface IntelligenceVisionImageSource {
+  /** Source type: data URL, file path, or base64 encoded. */
   type: 'data-url' | 'file' | 'base64'
+  /** Data URL of the image. */
   dataUrl?: string
+  /** File path to the image. */
   filePath?: string
+  /** Base64 encoded image data. */
   base64?: string
 }
 
-export interface AiVisionOcrBlock {
+/**
+ * OCR text block detected in an image.
+ */
+export interface IntelligenceVisionOcrBlock {
+  /** Unique identifier for the block. */
   id?: string
+  /** Detected text content. */
   text: string
+  /** Detected language of the text. */
   language?: string
+  /** Confidence score (0-1). */
   confidence?: number
+  /** Bounding box coordinates [x, y, width, height]. */
   boundingBox?: [number, number, number, number]
+  /** Polygon points for non-rectangular regions. */
   polygon?: Array<[number, number]>
+  /** Block type classification. */
   type?: 'word' | 'line' | 'paragraph' | 'region'
-  children?: AiVisionOcrBlock[]
+  /** Nested child blocks. */
+  children?: IntelligenceVisionOcrBlock[]
 }
 
-export interface AiVisionOcrResult {
+/**
+ * Result from OCR vision capability.
+ */
+export interface IntelligenceVisionOcrResult {
+  /** Full extracted text. */
   text: string
+  /** Overall confidence score. */
   confidence?: number
+  /** Detected primary language. */
   language?: string
+  /** Extracted keywords for search. */
   keywords?: string[]
+  /** Suggested search terms. */
   suggestions?: string[]
-  blocks?: AiVisionOcrBlock[]
+  /** Structured text blocks. */
+  blocks?: IntelligenceVisionOcrBlock[]
+  /** OCR engine identifier. */
+  engine?: 'apple-vision' | 'windows-ocr' | 'cloud'
+  /** OCR execution latency in milliseconds. */
+  durationMs?: number
+  /** Raw provider response. */
   raw?: any
 }
 
-export interface AiVisionOcrPayload {
-  source: AiVisionImageSource
+/**
+ * Payload for OCR vision capability.
+ */
+export interface IntelligenceVisionOcrPayload {
+  /** Image source configuration. */
+  source: IntelligenceVisionImageSource
+  /** Expected language hint. */
   language?: string
+  /** Custom prompt for OCR. */
   prompt?: string
+  /** Additional metadata. */
   metadata?: Record<string, any>
+  /** Include layout information. */
   includeLayout?: boolean
+  /** Extract keywords from text. */
   includeKeywords?: boolean
 }
 
-export interface AiProviderConfig {
+/**
+ * Configuration for an intelligence provider.
+ */
+export interface IntelligenceProviderConfig {
+  /** Unique provider identifier. */
   id: string
-  type: AiProviderType
+  /** Provider type. */
+  type: IntelligenceProviderType
+  /** Display name. */
   name: string
+  /** Whether the provider is enabled. */
   enabled: boolean
+  /** API key for authentication. */
   apiKey?: string
+  /** Base URL for API requests. */
   baseUrl?: string
-  rateLimit?: AiProviderRateLimit
+  /** Rate limit configuration. */
+  rateLimit?: IntelligenceProviderRateLimit
+  /** Available models. */
   models?: string[]
+  /** Default model to use. */
   defaultModel?: string
+  /** System instructions. */
   instructions?: string
+  /** Request timeout in milliseconds. */
   timeout?: number
+  /** Provider priority for selection. */
   priority?: number
+  /** Supported capability IDs. */
   capabilities?: string[]
+  /** Additional metadata. */
   metadata?: Record<string, any>
 }
 
-export interface AiMessage {
+/**
+ * Chat message structure.
+ */
+export interface IntelligenceMessage {
+  /** Message role. */
   role: 'system' | 'user' | 'assistant'
+  /** Message content. */
   content: string
+  /** Optional sender name. */
   name?: string
 }
 
-export interface AiInvokeOptions {
+/**
+ * Options for invoking an intelligence capability.
+ */
+export interface IntelligenceInvokeOptions {
+  /** Strategy ID for provider selection. */
   strategy?: string
+  /** Preferred models in order. */
   modelPreference?: string[]
+  /** Maximum cost ceiling. */
   costCeiling?: number
+  /** Target latency in milliseconds. */
   latencyTarget?: number
+  /** Request timeout in milliseconds. */
   timeout?: number
+  /** Enable streaming response. */
   stream?: boolean
+  /** Preferred provider ID. */
   preferredProviderId?: string
+  /** Allowed provider IDs. */
   allowedProviderIds?: string[]
+  /** Additional metadata. */
   metadata?: Record<string, any>
+  /** Mark as test run. */
   testRun?: boolean
 }
 
-export interface AiInvokeContext {
+/**
+ * Context information for an invocation.
+ */
+export interface IntelligenceInvokeContext {
+  /** Request source identifier. */
   source?: string
+  /** User locale. */
   locale?: string
+  /** User identifier. */
   userId?: string
+  /** Session identifier. */
   sessionId?: string
 }
 
-export interface AiUsageInfo {
+/**
+ * Token usage information.
+ */
+export interface IntelligenceUsageInfo {
+  /** Tokens used in prompt. */
   promptTokens: number
+  /** Tokens used in completion. */
   completionTokens: number
+  /** Total tokens used. */
   totalTokens: number
+  /** Estimated cost. */
   cost?: number
 }
 
-export interface AiInvokeResult<T = any> {
+/**
+ * Result from an intelligence invocation.
+ * @template T - Result data type.
+ */
+export interface IntelligenceInvokeResult<T = any> {
+  /** The result data. */
   result: T
-  usage: AiUsageInfo
+  /** Token usage information. */
+  usage: IntelligenceUsageInfo
+  /** Model used for the request. */
   model: string
+  /** Request latency in milliseconds. */
   latency: number
+  /** Unique trace identifier. */
   traceId: string
+  /** Provider that handled the request. */
   provider: string
 }
 
-export interface AiStreamChunk {
+/**
+ * Streaming response chunk.
+ */
+export interface IntelligenceStreamChunk {
+  /** Content delta. */
   delta: string
+  /** Whether streaming is complete. */
   done: boolean
-  usage?: AiUsageInfo
+  /** Final usage info (when done). */
+  usage?: IntelligenceUsageInfo
 }
 
-export interface AiCapabilityDescriptor {
+/**
+ * Descriptor for a registered capability.
+ */
+export interface IntelligenceCapabilityDescriptor {
+  /** Unique capability identifier. */
   id: string
-  type: AiCapabilityType
+  /** Capability type. */
+  type: IntelligenceCapabilityType
+  /** Display name. */
   name: string
+  /** Description of the capability. */
   description: string
+  /** JSON schema for input validation. */
   inputSchema?: any
+  /** JSON schema for output validation. */
   outputSchema?: any
+  /** Default strategy for provider selection. */
   defaultStrategy?: string
-  supportedProviders: AiProviderType[]
+  /** Providers that support this capability. */
+  supportedProviders: IntelligenceProviderType[]
+  /** Additional metadata. */
   metadata?: Record<string, any>
 }
 
-export interface AiChatPayload {
-  messages: AiMessage[]
-  context?: AiInvokeContext
+/**
+ * Payload for chat capability.
+ */
+export interface IntelligenceChatPayload {
+  /** Conversation messages. */
+  messages: IntelligenceMessage[]
+  /** Invocation context. */
+  context?: IntelligenceInvokeContext
+  /** Sampling temperature (0-2). */
   temperature?: number
+  /** Maximum tokens to generate. */
   maxTokens?: number
+  /** Top-p sampling parameter. */
   topP?: number
+  /** Frequency penalty (-2 to 2). */
   frequencyPenalty?: number
+  /** Presence penalty (-2 to 2). */
   presencePenalty?: number
+  /** Stop sequences. */
   stop?: string[]
 }
 
-export interface AiEmbeddingPayload {
+/**
+ * Payload for embedding generation.
+ */
+export interface IntelligenceEmbeddingPayload {
+  /** Text to embed (single or batch). */
   text: string | string[]
+  /** Specific model to use. */
   model?: string
 }
 
-export interface AiTranslatePayload {
+/**
+ * Payload for translation capability.
+ */
+export interface IntelligenceTranslatePayload {
+  /** Text to translate. */
   text: string
+  /** Source language (auto-detect if omitted). */
   sourceLang?: string
+  /** Target language. */
   targetLang: string
 }
 
-export interface AiSummarizePayload {
+/**
+ * Payload for summarization capability.
+ */
+export interface IntelligenceSummarizePayload {
+  /** Text to summarize. */
   text: string
+  /** Maximum summary length. */
   maxLength?: number
+  /** Summary style. */
   style?: 'concise' | 'detailed' | 'bullet-points'
 }
 
-export interface AiSDKConfig {
-  providers: AiProviderConfig[]
+// ============================================================================
+// Extended Payload Types
+// ============================================================================
+
+/**
+ * Payload for text rewriting capability.
+ */
+export interface IntelligenceRewritePayload {
+  /** Text to rewrite. */
+  text: string
+  /** Writing style. */
+  style?: 'formal' | 'casual' | 'professional' | 'creative' | 'simplified'
+  /** Tone of voice. */
+  tone?: 'neutral' | 'friendly' | 'authoritative' | 'humorous'
+  /** Target audience description. */
+  targetAudience?: string
+  /** Keywords to preserve. */
+  preserveKeywords?: string[]
+}
+
+/**
+ * Payload for grammar checking capability.
+ */
+export interface IntelligenceGrammarCheckPayload {
+  /** Text to check. */
+  text: string
+  /** Language of the text. */
+  language?: string
+  /** Types of issues to check. */
+  checkTypes?: ('spelling' | 'grammar' | 'punctuation' | 'style')[]
+  /** Strictness level. */
+  strictness?: 'lenient' | 'standard' | 'strict'
+}
+
+/**
+ * Result from grammar checking capability.
+ */
+export interface IntelligenceGrammarCheckResult {
+  /** Corrected text. */
+  correctedText: string
+  /** List of issues found. */
+  issues: Array<{
+    type: 'spelling' | 'grammar' | 'punctuation' | 'style'
+    original: string
+    suggestion: string
+    position: { start: number, end: number }
+    explanation?: string
+  }>
+  /** Overall score (0-100). */
+  score: number
+}
+
+/**
+ * Payload for code generation capability.
+ */
+export interface IntelligenceCodeGeneratePayload {
+  /** Description of code to generate. */
+  description: string
+  /** Target programming language. */
+  language: string
+  /** Framework to use. */
+  framework?: string
+  /** Additional context. */
+  context?: string
+  /** Include unit tests. */
+  includeTests?: boolean
+  /** Include code comments. */
+  includeComments?: boolean
+  /** Code style preference. */
+  style?: 'minimal' | 'verbose' | 'production'
+}
+
+/**
+ * Result from code generation capability.
+ */
+export interface IntelligenceCodeGenerateResult {
+  /** Generated code. */
+  code: string
+  /** Programming language. */
+  language: string
+  /** Explanation of the code. */
+  explanation?: string
+  /** Required dependencies. */
+  dependencies?: string[]
+  /** Generated tests. */
+  tests?: string
+}
+
+/**
+ * Payload for code explanation capability.
+ */
+export interface IntelligenceCodeExplainPayload {
+  /** Code to explain. */
+  code: string
+  /** Programming language. */
+  language?: string
+  /** Explanation depth. */
+  depth?: 'brief' | 'detailed' | 'comprehensive'
+  /** Target audience level. */
+  targetAudience?: 'beginner' | 'intermediate' | 'expert'
+}
+
+/**
+ * Result from code explanation capability.
+ */
+export interface IntelligenceCodeExplainResult {
+  /** Detailed explanation. */
+  explanation: string
+  /** Brief summary. */
+  summary: string
+  /** Key points. */
+  keyPoints: string[]
+  /** Complexity assessment. */
+  complexity?: 'simple' | 'moderate' | 'complex'
+  /** Programming concepts used. */
+  concepts?: string[]
+}
+
+/**
+ * Payload for code review capability.
+ */
+export interface IntelligenceCodeReviewPayload {
+  /** Code to review. */
+  code: string
+  /** Programming language. */
+  language?: string
+  /** Additional context. */
+  context?: string
+  /** Areas to focus on. */
+  focusAreas?: ('security' | 'performance' | 'style' | 'bugs' | 'best-practices')[]
+}
+
+/**
+ * Result from code review capability.
+ */
+export interface IntelligenceCodeReviewResult {
+  /** Review summary. */
+  summary: string
+  /** Overall score (0-100). */
+  score: number
+  /** Issues found. */
+  issues: Array<{
+    severity: 'critical' | 'warning' | 'info' | 'suggestion'
+    type: string
+    line?: number
+    message: string
+    suggestion?: string
+  }>
+  /** Suggested improvements. */
+  improvements: string[]
+}
+
+/**
+ * Payload for code refactoring capability.
+ */
+export interface IntelligenceCodeRefactorPayload {
+  /** Code to refactor. */
+  code: string
+  /** Programming language. */
+  language?: string
+  /** Refactoring goals. */
+  goals?: ('readability' | 'performance' | 'maintainability' | 'modularity')[]
+  /** Preserve public interface. */
+  preserveInterface?: boolean
+}
+
+/**
+ * Result from code refactoring capability.
+ */
+export interface IntelligenceCodeRefactorResult {
+  /** Refactored code. */
+  refactoredCode: string
+  /** List of changes made. */
+  changes: Array<{
+    type: string
+    description: string
+    before?: string
+    after?: string
+  }>
+  /** Explanation of changes. */
+  explanation: string
+}
+
+/**
+ * Payload for code debugging capability.
+ */
+export interface IntelligenceCodeDebugPayload {
+  /** Code with bug. */
+  code: string
+  /** Error message. */
+  error?: string
+  /** Programming language. */
+  language?: string
+  /** Additional context. */
+  context?: string
+  /** Stack trace. */
+  stackTrace?: string
+}
+
+/**
+ * Result from code debugging capability.
+ */
+export interface IntelligenceCodeDebugResult {
+  /** Bug diagnosis. */
+  diagnosis: string
+  /** Root cause analysis. */
+  rootCause: string
+  /** Fixed code. */
+  fixedCode: string
+  /** Explanation of the fix. */
+  explanation: string
+  /** Tips to prevent similar bugs. */
+  preventionTips?: string[]
+}
+
+/**
+ * Payload for intent detection capability.
+ */
+export interface IntelligenceIntentDetectPayload {
+  /** Text to analyze. */
+  text: string
+  /** Additional context. */
+  context?: string
+  /** Possible intents to consider. */
+  possibleIntents?: string[]
+  /** Language of the text. */
+  language?: string
+}
+
+/**
+ * Result from intent detection capability.
+ */
+export interface IntelligenceIntentDetectResult {
+  /** Detected intent. */
+  intent: string
+  /** Confidence score (0-1). */
+  confidence: number
+  /** Extracted entities. */
+  entities: Array<{
+    type: string
+    value: string
+    position?: { start: number, end: number }
+  }>
+  /** Secondary intents. */
+  subIntents?: Array<{ intent: string, confidence: number }>
+}
+
+/**
+ * Payload for sentiment analysis capability.
+ */
+export interface IntelligenceSentimentAnalyzePayload {
+  /** Text to analyze. */
+  text: string
+  /** Language of the text. */
+  language?: string
+  /** Analysis granularity. */
+  granularity?: 'document' | 'sentence' | 'aspect'
+  /** Aspects to analyze. */
+  aspects?: string[]
+}
+
+/**
+ * Result from sentiment analysis capability.
+ */
+export interface IntelligenceSentimentAnalyzeResult {
+  /** Overall sentiment. */
+  sentiment: 'positive' | 'negative' | 'neutral' | 'mixed'
+  /** Sentiment score (-1 to 1). */
+  score: number
+  /** Confidence score (0-1). */
+  confidence: number
+  /** Detected emotions. */
+  emotions?: Array<{ emotion: string, score: number }>
+  /** Aspect-based sentiments. */
+  aspects?: Array<{ aspect: string, sentiment: string, score: number }>
+  /** Sentiment keywords. */
+  keywords?: string[]
+}
+
+/**
+ * Payload for content extraction capability.
+ */
+export interface IntelligenceContentExtractPayload {
+  /** Text to extract from. */
+  text: string
+  /** Types of entities to extract. */
+  extractTypes?: ('dates' | 'people' | 'locations' | 'organizations' | 'events' | 'products' | 'urls' | 'emails' | 'phones')[]
+  /** Language of the text. */
+  language?: string
+  /** Include surrounding context. */
+  includeContext?: boolean
+}
+
+/**
+ * Result from content extraction capability.
+ */
+export interface IntelligenceContentExtractResult {
+  /** Extracted entities by type. */
+  entities: Record<string, Array<{
+    value: string
+    confidence: number
+    context?: string
+    position?: { start: number, end: number }
+  }>>
+  /** Content summary. */
+  summary?: string
+}
+
+/**
+ * Payload for keyword extraction capability.
+ */
+export interface IntelligenceKeywordsExtractPayload {
+  /** Text to extract keywords from. */
+  text: string
+  /** Maximum keywords to return. */
+  maxKeywords?: number
+  /** Language of the text. */
+  language?: string
+  /** Include relevance scores. */
+  includeScores?: boolean
+  /** Types of keywords to extract. */
+  keywordTypes?: ('noun' | 'verb' | 'phrase' | 'entity')[]
+}
+
+/**
+ * Result from keyword extraction capability.
+ */
+export interface IntelligenceKeywordsExtractResult {
+  /** Extracted keywords. */
+  keywords: Array<{
+    term: string
+    relevance: number
+    frequency?: number
+    type?: string
+  }>
+}
+
+/**
+ * Payload for text classification capability.
+ */
+export interface IntelligenceClassificationPayload {
+  /** Text to classify. */
+  text: string
+  /** Available categories. */
+  categories: string[]
+  /** Allow multiple labels. */
+  multiLabel?: boolean
+  /** Confidence threshold. */
+  threshold?: number
+}
+
+/**
+ * Result from text classification capability.
+ */
+export interface IntelligenceClassificationResult {
+  /** Classification predictions. */
+  predictions: Array<{
+    category: string
+    confidence: number
+  }>
+  /** Classification explanation. */
+  explanation?: string
+}
+
+// ============================================================================
+// Audio Payload Types
+// ============================================================================
+
+/**
+ * Payload for text-to-speech capability.
+ */
+export interface IntelligenceTTSPayload {
+  /** Text to convert to speech. */
+  text: string
+  /** Voice identifier. */
+  voice?: string
+  /** Language code. */
+  language?: string
+  /** Speech speed multiplier. */
+  speed?: number
+  /** Voice pitch adjustment. */
+  pitch?: number
+  /** Output audio format. */
+  format?: 'mp3' | 'wav' | 'ogg' | 'flac'
+  /** Audio quality. */
+  quality?: 'standard' | 'hd'
+}
+
+/**
+ * Result from text-to-speech capability.
+ */
+export interface IntelligenceTTSResult {
+  /** Audio data. */
+  audio: ArrayBuffer | string
+  /** Audio format. */
+  format: string
+  /** Duration in seconds. */
+  duration?: number
+  /** Sample rate in Hz. */
+  sampleRate?: number
+}
+
+/**
+ * Payload for speech-to-text capability.
+ */
+export interface IntelligenceSTTPayload {
+  /** Audio data. */
+  audio: ArrayBuffer | string
+  /** Expected language. */
+  language?: string
+  /** Audio format. */
+  format?: string
+  /** Include word timestamps. */
+  enableTimestamps?: boolean
+  /** Enable speaker diarization. */
+  enableSpeakerDiarization?: boolean
+}
+
+/**
+ * Result from speech-to-text capability.
+ */
+export interface IntelligenceSTTResult {
+  /** Transcribed text. */
+  text: string
+  /** Confidence score (0-1). */
+  confidence: number
+  /** Detected language. */
+  language?: string
+  /** Transcription segments. */
+  segments?: Array<{
+    text: string
+    start: number
+    end: number
+    speaker?: string
+    confidence?: number
+  }>
+}
+
+/**
+ * Payload for audio transcription capability.
+ */
+export interface IntelligenceAudioTranscribePayload {
+  /** Audio data. */
+  audio: ArrayBuffer | string
+  /** Expected language. */
+  language?: string
+  /** Audio format. */
+  format?: string
+  /** Task type. */
+  task?: 'transcribe' | 'translate'
+  /** Include timestamps. */
+  enableTimestamps?: boolean
+  /** Context prompt. */
+  prompt?: string
+}
+
+/**
+ * Result from audio transcription capability.
+ */
+export interface IntelligenceAudioTranscribeResult {
+  /** Transcribed text. */
+  text: string
+  /** Detected language. */
+  language: string
+  /** Audio duration in seconds. */
+  duration: number
+  /** Transcription segments. */
+  segments?: Array<{
+    id: number
+    text: string
+    start: number
+    end: number
+    confidence?: number
+  }>
+}
+
+// ============================================================================
+// Vision Extended Payload Types
+// ============================================================================
+
+/**
+ * Payload for image captioning capability.
+ */
+export interface IntelligenceImageCaptionPayload {
+  /** Image source. */
+  source: IntelligenceVisionImageSource
+  /** Caption style. */
+  style?: 'brief' | 'detailed' | 'creative'
+  /** Output language. */
+  language?: string
+  /** Maximum caption length. */
+  maxLength?: number
+}
+
+/**
+ * Result from image captioning capability.
+ */
+export interface IntelligenceImageCaptionResult {
+  /** Generated caption. */
+  caption: string
+  /** Alternative captions. */
+  alternativeCaptions?: string[]
+  /** Image tags. */
+  tags?: string[]
+  /** Confidence score (0-1). */
+  confidence?: number
+}
+
+/**
+ * Payload for image analysis capability.
+ */
+export interface IntelligenceImageAnalyzePayload {
+  /** Image source. */
+  source: IntelligenceVisionImageSource
+  /** Types of analysis to perform. */
+  analysisTypes?: ('objects' | 'faces' | 'text' | 'colors' | 'composition' | 'scene' | 'emotions')[]
+  /** Output language. */
+  language?: string
+  /** Include detailed analysis. */
+  detailed?: boolean
+}
+
+/**
+ * Result from image analysis capability.
+ */
+export interface IntelligenceImageAnalyzeResult {
+  /** Overall description. */
+  description: string
+  /** Detected objects. */
+  objects?: Array<{
+    name: string
+    confidence: number
+    boundingBox?: [number, number, number, number]
+  }>
+  /** Detected faces. */
+  faces?: Array<{
+    age?: number
+    gender?: string
+    emotion?: string
+    boundingBox?: [number, number, number, number]
+  }>
+  /** Dominant colors. */
+  colors?: Array<{
+    color: string
+    percentage: number
+    hex?: string
+  }>
+  /** Scene classification. */
+  scene?: {
+    type: string
+    confidence: number
+    attributes?: Record<string, any>
+  }
+  /** Detected text. */
+  text?: string[]
+  /** Image tags. */
+  tags?: string[]
+}
+
+/**
+ * Payload for image generation capability.
+ */
+export interface IntelligenceImageGeneratePayload {
+  /** Generation prompt. */
+  prompt: string
+  /** Negative prompt. */
+  negativePrompt?: string
+  /** Image width in pixels. */
+  width?: number
+  /** Image height in pixels. */
+  height?: number
+  /** Style preset. */
+  style?: string
+  /** Image quality. */
+  quality?: 'standard' | 'hd'
+  /** Number of images to generate. */
+  count?: number
+  /** Random seed for reproducibility. */
+  seed?: number
+}
+
+/**
+ * Result from image generation capability.
+ */
+export interface IntelligenceImageGenerateResult {
+  /** Generated images. */
+  images: Array<{
+    url?: string
+    base64?: string
+    revisedPrompt?: string
+  }>
+  /** Seed used for generation. */
+  seed?: number
+}
+
+/**
+ * Payload for image editing capability.
+ */
+export interface IntelligenceImageEditPayload {
+  /** Source image. */
+  source: IntelligenceVisionImageSource
+  /** Mask for inpainting. */
+  mask?: IntelligenceVisionImageSource
+  /** Edit prompt. */
+  prompt: string
+  /** Type of edit. */
+  editType?: 'inpaint' | 'outpaint' | 'variation' | 'upscale'
+}
+
+/**
+ * Result from image editing capability.
+ */
+export interface IntelligenceImageEditResult {
+  /** Edited image. */
+  image: {
+    url?: string
+    base64?: string
+  }
+  /** Revised prompt. */
+  revisedPrompt?: string
+}
+
+// ============================================================================
+// RAG & Search Payload Types
+// ============================================================================
+
+/**
+ * Payload for RAG query capability.
+ */
+export interface IntelligenceRAGQueryPayload {
+  /** Query text. */
+  query: string
+  /** Documents to search. */
+  documents?: Array<{
+    id: string
+    content: string
+    metadata?: Record<string, any>
+  }>
+  /** Number of top results. */
+  topK?: number
+  /** Relevance threshold. */
+  threshold?: number
+  /** Enable reranking. */
+  rerank?: boolean
+  /** Include context in response. */
+  includeContext?: boolean
+}
+
+/**
+ * Result from RAG query capability.
+ */
+export interface IntelligenceRAGQueryResult {
+  /** Generated answer. */
+  answer: string
+  /** Source documents. */
+  sources: Array<{
+    id: string
+    content: string
+    relevance: number
+    metadata?: Record<string, any>
+  }>
+  /** Confidence score (0-1). */
+  confidence: number
+}
+
+/**
+ * Payload for semantic search capability.
+ */
+export interface IntelligenceSemanticSearchPayload {
+  /** Search query. */
+  query: string
+  /** Documents to search. */
+  documents: Array<{
+    id: string
+    content: string
+    embedding?: number[]
+    metadata?: Record<string, any>
+  }>
+  /** Number of top results. */
+  topK?: number
+  /** Similarity threshold. */
+  threshold?: number
+}
+
+/**
+ * Result from semantic search capability.
+ */
+export interface IntelligenceSemanticSearchResult {
+  /** Search results. */
+  results: Array<{
+    id: string
+    content: string
+    score: number
+    metadata?: Record<string, any>
+  }>
+}
+
+/**
+ * Payload for document reranking capability.
+ */
+export interface IntelligenceRerankPayload {
+  /** Query for relevance scoring. */
+  query: string
+  /** Documents to rerank. */
+  documents: Array<{
+    id: string
+    content: string
+    metadata?: Record<string, any>
+  }>
+  /** Number of top results. */
+  topK?: number
+}
+
+/**
+ * Result from document reranking capability.
+ */
+export interface IntelligenceRerankResult {
+  /** Reranked results. */
+  results: Array<{
+    id: string
+    content: string
+    score: number
+    originalRank: number
+    metadata?: Record<string, any>
+  }>
+}
+
+// ============================================================================
+// Prompt Workflow System
+// ============================================================================
+
+export type PromptVariableType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'file' | 'image'
+
+export interface PromptVariable {
+  name: string
+  type: PromptVariableType
+  description?: string
+  required?: boolean
+  default?: any
+  validation?: {
+    minLength?: number
+    maxLength?: number
+    pattern?: string
+    enum?: any[]
+    min?: number
+    max?: number
+  }
+}
+
+export interface PromptTemplate {
+  id: string
+  name: string
+  description?: string
+  template: string
+  variables: PromptVariable[]
+  category?: string
+  tags?: string[]
+  version?: string
+  author?: string
+  createdAt?: number
+  updatedAt?: number
+}
+
+export interface PromptStep {
+  id: string
+  name: string
+  type: 'prompt' | 'condition' | 'loop' | 'parallel' | 'transform' | 'api-call'
+  config: PromptStepConfig
+  next?: string | PromptStepCondition[]
+  onError?: 'fail' | 'skip' | 'retry' | string
+  retryConfig?: {
+    maxRetries: number
+    delay: number
+    backoff?: 'linear' | 'exponential'
+  }
+}
+
+export interface PromptStepConfig {
+  // For prompt type
+  templateId?: string
+  template?: string
+  variables?: Record<string, any>
+  capabilityId?: string
+  modelPreference?: string[]
+  // For condition type
+  condition?: string
+  // For loop type
+  items?: string
+  maxIterations?: number
+  // For parallel type
+  branches?: string[]
+  // For transform type
+  transform?: string
+  // For api-call type
+  url?: string
+  method?: string
+  headers?: Record<string, string>
+  body?: any
+}
+
+export interface PromptStepCondition {
+  condition: string
+  next: string
+}
+
+export interface PromptWorkflow {
+  id: string
+  name: string
+  description?: string
+  version?: string
+  steps: PromptStep[]
+  entryPoint: string
+  variables: PromptVariable[]
+  outputs?: string[]
+  metadata?: Record<string, any>
+  createdAt?: number
+  updatedAt?: number
+}
+
+export interface PromptWorkflowExecution {
+  id: string
+  workflowId: string
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+  startedAt: number
+  completedAt?: number
+  inputs: Record<string, any>
+  outputs?: Record<string, any>
+  steps: Array<{
+    stepId: string
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped'
+    startedAt?: number
+    completedAt?: number
+    input?: any
+    output?: any
+    error?: string
+  }>
+  error?: string
+}
+
+export interface PromptWorkflowContext {
+  execution: PromptWorkflowExecution
+  variables: Record<string, any>
+  stepResults: Record<string, any>
+  currentStep?: string
+}
+
+// ============================================================================
+// TuffIntelligence Orchestration
+// ============================================================================
+
+export type TuffIntelligenceSessionStatus
+  = | 'idle'
+    | 'planning'
+    | 'planned'
+    | 'executing'
+    | 'reflecting'
+    | 'waiting_approval'
+    | 'paused_disconnect'
+    | 'resuming'
+    | 'completed'
+    | 'failed'
+    | 'cancelled'
+
+export type TuffIntelligenceActionStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+
+export interface TuffIntelligenceActionNode {
+  id: string
+  type: 'intent' | 'plan' | 'tool' | 'agent' | 'capability' | 'reflect' | 'result'
+  title: string
+  status: TuffIntelligenceActionStatus
+  capabilityId?: string
+  toolId?: string
+  input?: unknown
+  output?: unknown
+  error?: string
+  parentId?: string
+  metadata?: Record<string, any>
+  createdAt: number
+  updatedAt?: number
+}
+
+export interface TuffIntelligenceActionGraph {
+  sessionId: string
+  nodes: TuffIntelligenceActionNode[]
+  edges: Array<{ from: string, to: string, kind?: 'sequence' | 'dependency' | 'reflection' }>
+  version: number
+  updatedAt: number
+}
+
+export interface TuffIntelligenceTurn {
+  id: string
+  sessionId: string
+  status: TuffIntelligenceSessionStatus
+  objective?: string
+  userInput?: string
+  plannerModel?: string
+  executionModel?: string
+  actionIds: string[]
+  reflection?: string
+  error?: string
+  metadata?: Record<string, any>
+  startedAt: number
+  completedAt?: number
+}
+
+export interface TuffIntelligenceSession {
+  id: string
+  status: TuffIntelligenceSessionStatus
+  pauseReason?: 'client_disconnect' | 'heartbeat_timeout' | 'manual_pause' | 'system_preempted'
+  lastEventSeq?: number
+  lastCheckpointAt?: number
+  resumeHint?: string
+  objective?: string
+  context?: Record<string, any>
+  metadata?: Record<string, any>
+  currentTurnId?: string
+  createdAt: number
+  updatedAt: number
+}
+
+export interface TuffIntelligenceTraceEvent {
+  id: string
+  sessionId: string
+  turnId?: string
+  type:
+    | 'session.started'
+    | 'session.resumed'
+    | 'session.paused'
+    | 'session.cancelled'
+    | 'plan.created'
+    | 'plan.updated'
+    | 'execution.started'
+    | 'execution.completed'
+    | 'execution.failed'
+    | 'tool.called'
+    | 'tool.completed'
+    | 'tool.approval_required'
+    | 'tool.approved'
+    | 'tool.rejected'
+    | 'reflection.completed'
+    | 'state.snapshot'
+  level: 'debug' | 'info' | 'warn' | 'error'
+  message: string
+  payload?: Record<string, any>
+  timestamp: number
+}
+
+export interface TuffIntelligenceApprovalTicket {
+  id: string
+  sessionId: string
+  turnId?: string
+  actionId?: string
+  toolId: string
+  riskLevel: 'low' | 'medium' | 'high' | 'critical'
+  reason: string
+  status: 'pending' | 'approved' | 'rejected'
+  requestedAt: number
+  resolvedAt?: number
+  resolvedBy?: string
+  metadata?: Record<string, any>
+}
+
+export interface TuffIntelligenceStateSnapshot {
+  sessionId: string
+  status: TuffIntelligenceSessionStatus
+  currentTurn?: TuffIntelligenceTurn
+  actionGraph: TuffIntelligenceActionGraph
+  pendingApprovals: TuffIntelligenceApprovalTicket[]
+  lastTraceEvent?: TuffIntelligenceTraceEvent
+  updatedAt: number
+}
+
+// ============================================================================
+// Agent System
+// ============================================================================
+
+/**
+ * Tool definition for an AI agent.
+ */
+export interface IntelligenceAgentTool {
+  /** Tool name. */
+  name: string
+  /** Tool description. */
+  description: string
+  /** Parameter schema. */
+  parameters: {
+    type: 'object'
+    properties: Record<string, {
+      type: string
+      description?: string
+      enum?: any[]
+      required?: boolean
+    }>
+    required?: string[]
+  }
+  /** Handler function name. */
+  handler?: string
+}
+
+/**
+ * Payload for agent capability.
+ */
+export interface IntelligenceAgentPayload {
+  /** Task description. */
+  task: string
+  /** Available tools. */
+  tools?: IntelligenceAgentTool[]
+  /** Additional context. */
+  context?: string
+  /** Maximum iterations. */
+  maxIterations?: number
+  /** Conversation memory. */
+  memory?: Array<{ role: string, content: string }>
+  /** Constraints for the agent. */
+  constraints?: string[]
+}
+
+/**
+ * Result from agent capability.
+ */
+export interface IntelligenceAgentResult {
+  /** Final result. */
+  result: string
+  /** Reasoning steps. */
+  steps: Array<{
+    thought: string
+    action?: string
+    actionInput?: any
+    observation?: string
+  }>
+  /** Tool call history. */
+  toolCalls: Array<{
+    tool: string
+    input: any
+    output: any
+  }>
+  /** Number of iterations. */
+  iterations: number
+}
+
+/**
+ * SDK configuration.
+ */
+export interface IntelligenceSDKConfig {
+  /** Provider configurations. */
+  providers: IntelligenceProviderConfig[]
+  /** Default strategy ID. */
   defaultStrategy: string
+  /** Enable audit logging. */
   enableAudit: boolean
+  /** Enable result caching. */
   enableCache: boolean
+  /** Enable quota management. */
+  enableQuota?: boolean
+  /** Cache expiration in seconds. */
   cacheExpiration?: number
-  capabilities?: Record<string, AiCapabilityRoutingConfig>
+  /** Capability routing configurations. */
+  capabilities?: Record<string, IntelligenceCapabilityRoutingConfig>
 }
 
-export interface AiStrategyConfig {
+/**
+ * Strategy configuration.
+ */
+export interface IntelligenceStrategyConfig {
+  /** Strategy ID. */
   id: string
+  /** Strategy name. */
   name: string
+  /** Strategy type. */
   type: 'rule-based' | 'adaptive' | 'custom'
+  /** Strategy rules. */
   rules?: any
+  /** Strategy priority. */
   priority?: number
 }
 
-export interface AiAuditLog {
+/**
+ * Audit log entry.
+ */
+export interface IntelligenceAuditLog {
+  /** Trace ID. */
   traceId: string
+  /** Timestamp. */
   timestamp: number
+  /** Capability ID. */
   capabilityId: string
+  /** Provider ID. */
   provider: string
+  /** Model used. */
   model: string
+  /** Prompt hash. */
   promptHash?: string
+  /** Caller identifier. */
   caller?: string
-  usage: AiUsageInfo
+  /** Usage information. */
+  usage: IntelligenceUsageInfo
+  /** Latency in milliseconds. */
   latency: number
+  /** Success status. */
   success: boolean
+  /** Error message. */
   error?: string
 }
 
-export interface AiCapabilityProviderBinding {
+/**
+ * Provider binding for a capability.
+ */
+export interface IntelligenceCapabilityProviderBinding {
+  /** Provider ID. */
   providerId: string
+  /** Specific models to use. */
   models?: string[]
+  /** Priority for selection. */
   priority?: number
+  /** Whether binding is enabled. */
   enabled?: boolean
+  /** Additional metadata. */
   metadata?: Record<string, any>
 }
 
-export interface AiCapabilityRoutingConfig {
+/**
+ * Routing configuration for a capability.
+ */
+export interface IntelligenceCapabilityRoutingConfig {
+  /** Display label. */
   label?: string
+  /** Description. */
   description?: string
-  providers: AiCapabilityProviderBinding[]
+  /** Provider bindings. */
+  providers: IntelligenceCapabilityProviderBinding[]
+  /** Prompt template. */
   promptTemplate?: string
+  /** Test resource directory. */
   testResourceDir?: string
+  /** Additional metadata. */
   metadata?: Record<string, any>
 }
 
-export interface AiSDKPersistedConfig {
-  providers: AiProviderConfig[]
+/**
+ * Persisted SDK configuration.
+ */
+export interface IntelligenceSDKPersistedConfig {
+  /** Provider configurations. */
+  providers: IntelligenceProviderConfig[]
+  /** Global configuration. */
   globalConfig: {
     defaultStrategy: string
     enableAudit: boolean
     enableCache: boolean
     cacheExpiration?: number
   }
-  capabilities?: Record<string, AiCapabilityRoutingConfig>
+  /** Capability configurations. */
+  capabilities?: Record<string, IntelligenceCapabilityRoutingConfig>
+  /** Configuration version. */
   version: number
 }
 
-export interface AiProviderAdapter {
-  readonly type: AiProviderType
-  getConfig: () => AiProviderConfig
-  updateConfig: (config: Partial<AiProviderConfig>) => void
+/**
+ * Provider adapter interface.
+ */
+export interface IntelligenceProviderAdapter {
+  /** Provider type. */
+  readonly type: IntelligenceProviderType
+  /** Get provider configuration. */
+  getConfig: () => IntelligenceProviderConfig
+  /** Update provider configuration. */
+  updateConfig: (config: Partial<IntelligenceProviderConfig>) => void
+  /** Check if provider is enabled. */
   isEnabled: () => boolean
-  chat: (payload: AiChatPayload, options: AiInvokeOptions) => Promise<AiInvokeResult<string>>
-  chatStream: (
-    payload: AiChatPayload,
-    options: AiInvokeOptions,
-  ) => AsyncGenerator<AiStreamChunk>
-  embedding: (payload: AiEmbeddingPayload, options: AiInvokeOptions) => Promise<AiInvokeResult<number[]>>
-  translate: (payload: AiTranslatePayload, options: AiInvokeOptions) => Promise<AiInvokeResult<string>>
-  visionOcr: (
-    payload: AiVisionOcrPayload,
-    options: AiInvokeOptions,
-  ) => Promise<AiInvokeResult<AiVisionOcrResult>>
-}
-
-export interface ProviderManagerAdapter {
+
+  // Core text capabilities
+  chat: (payload: IntelligenceChatPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<string>>
+  chatStream: (payload: IntelligenceChatPayload, options: IntelligenceInvokeOptions) => AsyncGenerator<IntelligenceStreamChunk>
+  embedding: (payload: IntelligenceEmbeddingPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<number[]>>
+  translate: (payload: IntelligenceTranslatePayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<string>>
+  summarize?: (payload: IntelligenceSummarizePayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<string>>
+  rewrite?: (payload: IntelligenceRewritePayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<string>>
+  grammarCheck?: (payload: IntelligenceGrammarCheckPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceGrammarCheckResult>>
+
+  // Code capabilities
+  codeGenerate?: (payload: IntelligenceCodeGeneratePayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceCodeGenerateResult>>
+  codeExplain?: (payload: IntelligenceCodeExplainPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceCodeExplainResult>>
+  codeReview?: (payload: IntelligenceCodeReviewPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceCodeReviewResult>>
+  codeRefactor?: (payload: IntelligenceCodeRefactorPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceCodeRefactorResult>>
+  codeDebug?: (payload: IntelligenceCodeDebugPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceCodeDebugResult>>
+
+  // Analysis capabilities
+  intentDetect?: (payload: IntelligenceIntentDetectPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceIntentDetectResult>>
+  sentimentAnalyze?: (payload: IntelligenceSentimentAnalyzePayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceSentimentAnalyzeResult>>
+  contentExtract?: (payload: IntelligenceContentExtractPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceContentExtractResult>>
+  keywordsExtract?: (payload: IntelligenceKeywordsExtractPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceKeywordsExtractResult>>
+  classification?: (payload: IntelligenceClassificationPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceClassificationResult>>
+
+  // Vision capabilities
+  visionOcr: (payload: IntelligenceVisionOcrPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceVisionOcrResult>>
+  imageCaption?: (payload: IntelligenceImageCaptionPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceImageCaptionResult>>
+  imageAnalyze?: (payload: IntelligenceImageAnalyzePayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceImageAnalyzeResult>>
+  imageGenerate?: (payload: IntelligenceImageGeneratePayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceImageGenerateResult>>
+  imageEdit?: (payload: IntelligenceImageEditPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceImageEditResult>>
+
+  // Audio capabilities
+  tts?: (payload: IntelligenceTTSPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceTTSResult>>
+  stt?: (payload: IntelligenceSTTPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceSTTResult>>
+  audioTranscribe?: (payload: IntelligenceAudioTranscribePayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceAudioTranscribeResult>>
+
+  // RAG & Search capabilities
+  ragQuery?: (payload: IntelligenceRAGQueryPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceRAGQueryResult>>
+  semanticSearch?: (payload: IntelligenceSemanticSearchPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceSemanticSearchResult>>
+  rerank?: (payload: IntelligenceRerankPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceRerankResult>>
+
+  // Agent capabilities
+  agent?: (payload: IntelligenceAgentPayload, options: IntelligenceInvokeOptions) => Promise<IntelligenceInvokeResult<IntelligenceAgentResult>>
+}
+
+/**
+ * Provider manager adapter interface.
+ */
+export interface IntelligenceProviderManagerAdapter {
+  /** Clear all providers. */
   clear: () => void
-  registerFromConfig: (config: AiProviderConfig) => AiProviderAdapter
-  getEnabled: () => AiProviderAdapter[]
-  get: (providerId: string) => AiProviderAdapter | undefined
-  createProviderInstance: (config: AiProviderConfig) => AiProviderAdapter
+  /** Register provider from configuration. */
+  registerFromConfig: (config: IntelligenceProviderConfig) => IntelligenceProviderAdapter
+  /** Get all enabled providers. */
+  getEnabled: () => IntelligenceProviderAdapter[]
+  /** Get provider by ID. */
+  get: (providerId: string) => IntelligenceProviderAdapter | undefined
+  /** Create provider instance. */
+  createProviderInstance: (config: IntelligenceProviderConfig) => IntelligenceProviderAdapter
 }
 
-export interface AISDKGlobalConfig {
+export type ProviderManagerAdapter = IntelligenceProviderManagerAdapter
+
+/**
+ * Global SDK configuration.
+ */
+export interface IntelligenceGlobalConfig {
+  /** Default strategy ID. */
   defaultStrategy: string
+  /** Enable audit logging. */
   enableAudit: boolean
+  /** Enable result caching. */
   enableCache: boolean
+  /** Cache expiration in seconds. */
   cacheExpiration?: number
+  /** Maximum retry attempts. */
   maxRetries?: number
+  /** Default timeout in milliseconds. */
   defaultTimeout?: number
+  /** Enable logging. */
   enableLogging?: boolean
+  /** Log level. */
   logLevel?: 'debug' | 'info' | 'warn' | 'error'
+  /** Enable caching. */
   enableCaching?: boolean
+  /** Cache size limit. */
   cacheSize?: number
+  /** Fallback strategy. */
   fallbackStrategy?: 'next-available' | 'fail-fast' | 'round-robin'
+  /** Allow parallel requests. */
   parallelRequests?: boolean
 }
 
-export interface TestResult {
+/**
+ * Test result structure.
+ */
+export interface IntelligenceTestResult {
+  /** Whether test succeeded. */
   success: boolean
+  /** Result message. */
   message?: string
+  /** Latency in milliseconds. */
   latency?: number
+  /** Test timestamp. */
   timestamp: number
 }
 
-export interface AISDKCapabilityConfig {
+export type TestResult = IntelligenceTestResult
+
+/**
+ * Capability configuration for SDK.
+ */
+export interface IntelligenceCapabilityConfig {
+  /** Capability ID. */
   id: string
+  /** Display label. */
   label: string
+  /** Description. */
   description?: string
-  providers: AiCapabilityProviderBinding[]
+  /** Provider bindings. */
+  providers: IntelligenceCapabilityProviderBinding[]
+  /** Prompt template. */
   promptTemplate?: string
+  /** Test resource directory. */
   testResourceDir?: string
+  /** Additional metadata. */
   metadata?: Record<string, any>
 }
 
-export interface AISDKStorageData {
-  providers: AiProviderConfig[]
-  globalConfig: AISDKGlobalConfig
-  capabilities: Record<string, AISDKCapabilityConfig>
+/**
+ * Storage data structure for SDK.
+ */
+export interface IntelligenceStorageData {
+  /** Provider configurations. */
+  providers: IntelligenceProviderConfig[]
+  /** Global configuration. */
+  globalConfig: IntelligenceGlobalConfig
+  /** Capability configurations. */
+  capabilities: Record<string, IntelligenceCapabilityConfig>
+  /** Data version. */
   version: number
 }
 
-export const DEFAULT_PROVIDERS: AiProviderConfig[] = [
+/**
+ * Default provider configurations.
+ */
+export const DEFAULT_PROVIDERS: IntelligenceProviderConfig[] = [
   {
     id: 'openai-default',
-    type: AiProviderType.OPENAI,
+    type: IntelligenceProviderType.OPENAI,
     name: 'OpenAI',
     enabled: false,
     priority: 1,
@@ -306,7 +1688,7 @@ export const DEFAULT_PROVIDERS: AiProviderConfig[] = [
   },
   {
     id: 'anthropic-default',
-    type: AiProviderType.ANTHROPIC,
+    type: IntelligenceProviderType.ANTHROPIC,
     name: 'Anthropic',
     enabled: false,
     priority: 2,
@@ -317,7 +1699,7 @@ export const DEFAULT_PROVIDERS: AiProviderConfig[] = [
   },
   {
     id: 'deepseek-default',
-    type: AiProviderType.DEEPSEEK,
+    type: IntelligenceProviderType.DEEPSEEK,
     name: 'DeepSeek',
     enabled: false,
     priority: 2,
@@ -328,7 +1710,7 @@ export const DEFAULT_PROVIDERS: AiProviderConfig[] = [
   },
   {
     id: 'siliconflow-default',
-    type: AiProviderType.SILICONFLOW,
+    type: IntelligenceProviderType.SILICONFLOW,
     name: 'SiliconFlow',
     enabled: false,
     priority: 2,
@@ -348,9 +1730,24 @@ export const DEFAULT_PROVIDERS: AiProviderConfig[] = [
     timeout: 30000,
     rateLimit: {},
   },
+  {
+    id: 'tuff-nexus-default',
+    type: IntelligenceProviderType.CUSTOM,
+    name: 'Tuff Nexus',
+    enabled: false,
+    priority: 1,
+    baseUrl: `${NEXUS_BASE_URL}/v1`,
+    models: ['gpt-4o', 'gpt-4o-mini'],
+    defaultModel: 'gpt-4o-mini',
+    timeout: 30000,
+    rateLimit: {},
+    metadata: {
+      origin: 'tuff-nexus',
+    },
+  },
   {
     id: 'local-default',
-    type: AiProviderType.LOCAL,
+    type: IntelligenceProviderType.LOCAL,
     name: 'Local Model',
     enabled: false,
     priority: 3,
@@ -361,18 +1758,18 @@ export const DEFAULT_PROVIDERS: AiProviderConfig[] = [
   },
 ]
 
-export const DEFAULT_GLOBAL_CONFIG: AISDKGlobalConfig = {
+export const DEFAULT_GLOBAL_CONFIG: IntelligenceGlobalConfig = {
   defaultStrategy: 'adaptive-default',
   enableAudit: false,
   enableCache: true,
   cacheExpiration: 3600,
 }
 
-export const DEFAULT_CAPABILITIES: Record<string, AISDKCapabilityConfig> = {
+export const DEFAULT_CAPABILITIES: Record<string, IntelligenceCapabilityConfig> = {
   'text.chat': {
     id: 'text.chat',
     label: '对话 / Chat',
-    description: '默认用于系统对话、翻译、总结等文本任务的模型集合',
+    description: '通用对话、问答、助理类能力',
     providers: [
       { providerId: 'openai-default', priority: 1, enabled: true },
       { providerId: 'anthropic-default', priority: 2, enabled: true },
@@ -605,3 +2002,17 @@ export const DEFAULT_CAPABILITIES: Record<string, AISDKCapabilityConfig> = {
     ],
   },
 }
+
+export interface CapabilityTestResult {
+  success: boolean
+  message?: string
+  latency?: number
+  provider?: string
+  model?: string
+  textPreview?: string
+  timestamp: number
+}
+
+export interface CapabilityBinding extends IntelligenceCapabilityProviderBinding {
+  provider?: IntelligenceProviderConfig
+}