/**
 * Metona IR — Provider Adapter 接口定义
 *
 * 所有 LLM Provider 适配器必须实现此接口。
 *
 * @see docs/MetonaAI-Desktop 内部API请求与响应标准.html
 */

import type { MetonaRequest, MetonaResponse, MetonaStreamEvent } from './index';

/**
 * Provider 适配器配置
 */
export interface AdapterConfig {
  /** Provider 标识（如 'deepseek'、'agnes'、'ollama'） */
  provider: string;
  /** API 基础 URL */
  baseURL: string;
  /** API 密钥（Ollama 等本地 Provider 可为空） */
  apiKey?: string;
  /** 默认模型名 */
  defaultModel: string;
  /** 请求超时（ms） */
  timeoutMs?: number;
  /** 自定义请求头 */
  headers?: Record<string, string>;
}

/**
 * Provider 适配器统一接口
 *
 * 职责：
 * 1. 将 MetonaRequest 转换为目标 Provider 原生请求格式
 * 2. 调用外部 API
 * 3. 将原生响应转换为 MetonaResponse / MetonaStreamEvent
 *
 * 铁律：外部 API 原始类型不得穿透到此接口之外
 */
export interface IMetonaProviderAdapter {
  /** Provider 标识 */
  readonly provider: string;

  /** 支持的模型列表 */
  readonly supportedModels: string[];

  /** 是否支持 Tool Calling */
  readonly supportsToolCalling: boolean;

  /** 是否支持 Thinking / Reasoning 模式 */
  readonly supportsThinking: boolean;

  /**
   * 发送非流式请求
   */
  chat(request: MetonaRequest): Promise<MetonaResponse>;

  /**
   * 发送流式请求
   * @returns AsyncIterable 逐事件推送 MetonaStreamEvent
   */
  chatStream(request: MetonaRequest): AsyncIterable<MetonaStreamEvent>;

  /**
   * 检查 Provider 可用性
   */
  healthCheck(): Promise<boolean>;

  /**
   * 列出可用模型（可选）
   */
  listModels?(): Promise<string[]>;
}
