<?php

namespace XZD\AI\V5\AI;

/**
 * AI 厂商统一接口
 *
 * 所有厂商 Provider 必须实现此接口。
 * 支持三种 API 格式: OpenAI 兼容 / Anthropic / Google Gemini
 */
interface ProviderInterface
{
    /**
     * 非流式对话
     *
     * @param array  $messages [['role'=>'user','content'=>'...'], ...]
     * @param array  $options  ['temperature','max_tokens','tools',...]
     * @return array ['content'=>'...','tool_calls'=>[...],'input_tokens'=>N,'output_tokens'=>N]
     */
    public function chat(array $messages, array $options = []): array;

    /**
     * 流式对话 (Generator)
     *
     * @param ?callable $onChunk 可选即时回调，每个chunk到达时立即调用（不等curl结束），用于真流式SSE
     * @return \Generator 每次 yield ['delta'=>'...','type'=>'text'|'tool_call','tool_call'=>[...]|null,'done'=>bool]
     */
    public function chatStream(array $messages, array $options = [], ?callable $onChunk = null): \Generator;

    /**
     * 测试连接
     */
    public function testConnection(): array;

    /**
     * 获取可用模型列表
     *
     * @return array ['models'=>['id'=>'model-id','name'=>'display name',...], 'success'=>bool]
     */
    public function getModels(): array;

    /**
     * 厂商标识
     */
    public function getProviderKey(): string;

    /**
     * 获取配置信息
     */
    public function getConfig(): array;
}
