<?php
namespace boru\ai\Provider;

use boru\ai\Schema\Request;
use boru\ai\Schema\Response;
use boru\ai\Schema\ToolResult;

interface ProviderInterface
{
    /**
     * Stable provider name, e.g. openai, gemini.
     *
     * @return string
     */
    public function name();

    /**
     * Provider capability descriptor.
     *
     * @return Capabilities
     */
    public function capabilities();

    /**
     * Whether this provider can likely handle the given model.
     *
     * @param string $model
     * @return bool
     */
    public function supportsModel($model);

    /**
     * Execute a normalized request.
     *
     * Implementations may optionally invoke $eventCallback with
     * boru\ai\Stream\StreamEvent objects during execution.
     *
     * @param Request $request
     * @param callable|null $eventCallback
     * @return Response
     */
    public function execute(Request $request, $eventCallback = null);

    /**
     * Continue generation after the runtime has resolved tool calls.
     *
     * Providers should use the original request, the previous response,
     * and the normalized tool results to resume provider execution.
     *
     * @param Request $request
     * @param Response $previousResponse
     * @param ToolResult[] $toolResults
     * @param callable|null $eventCallback
     * @return Response
     */
    public function continueResponse(Request $request, Response $previousResponse, array $toolResults, $eventCallback = null);
}
