<?php

namespace App\Service\common\ai;

/**
 * AI Agent 统一接口（OpenAI 兼容 chat completions）
 * 各供应商（讯飞 Spark / DeepSeek 等）实现本接口，业务层只依赖工厂
 */
interface AiAgentInterface
{
    /**
     * 发起对话补全
     *
     * @param array $messages OpenAI 格式 messages：[['role'=>'system|user|assistant','content'=>'...'], ...]
     * @param array $options 可选覆盖：model / temperature / max_tokens 等
     */
    public function chatCompletions(array $messages, array $options = []): AiChatResult;

    /**
     * 供应商标识（spark / deepseek）
     */
    public function provider(): string;
}