/**
 * Generic LLM Types
 * Universal interfaces for LLM interaction across all resource types
 */

// ============================================================================
// Message Format (OpenAI-compatible)
// ============================================================================

/**
 * Standard chat message format
 * Compatible with OpenAI, Anthropic, and other providers
 */
export interface LLMMessage {
  role: 'system' | 'user' | 'assistant'
  content: string
}

// ============================================================================
// Generic Request/Response
// ============================================================================

/**
 * Generic LLM generation request
 * Usable by agents, workflows, tools, etc.
 */
export interface LLMGenerateRequest {
  // Prompt (required)
  messages: LLMMessage[]

  // Output structure (required)
  responseSchema: unknown // JSON Schema for structured output

  // Constraints (optional)
  /** Maximum output tokens per LLM call. NOT the model's context window — see ModelInfo.maxTokens for that. */
  maxOutputTokens?: number
  temperature?: number
  topP?: number

  // Cancellation (optional)
  signal?: AbortSignal // Execution-level abort signal, composed with per-call timeout in base adapters
}

/**
 * Generic LLM generation response
 * Usage field is internal-only (stripped by UniversalLLMAdapter wrapper)
 */
export interface LLMGenerateResponse<T = unknown> {
  output: T // Parsed structured output (validated against responseSchema)

  // Internal use only (for observability tracking)
  // Not exposed in public interface - wrapper extracts this
  usage?: {
    inputTokens: number
    outputTokens: number
    totalTokens: number
  }

  // Actual cost from provider in USD (when available)
  // Currently only OpenRouter provides this via usage accounting
  cost?: number
}

// ============================================================================
// LLM Adapter Interface
// ============================================================================

/**
 * LLM Adapter interface
 * Generic primitive for all resource types (agents, workflows, tools)
 *
 * Design principles:
 * - Single method: generate() - the core LLM primitive
 * - Generic return type for type safety
 * - Universal format (not agent-specific)
 * - Standard message-based input (OpenAI-compatible)
 */
export interface LLMAdapter {
  /**
   * Generate structured output from prompt using LLM
   *
   * @param request - Generation request with messages and response schema
   * @returns Generated output (typed) with optional usage metadata
   */
  generate<T = unknown>(request: LLMGenerateRequest): Promise<LLMGenerateResponse<T>>
}
