<?php
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

interface Arcai_Provider {

	/**
	 * Embed an array of texts.
	 *
	 * @param string[] $texts
	 * @return array|WP_Error { embeddings: float[][], tokens: int, cost: float }
	 */
	public function embed( array $texts );

	/**
	 * Run a chat completion.
	 *
	 * @param array $messages Array of [ 'role' => ..., 'content' => ... ].
	 * @param array $opts     Supports 'json' => true for JSON-mode output, 'max_tokens'.
	 * @return array|WP_Error { content: string, tokens_in: int, tokens_out: int, cost: float }
	 */
	public function chat( array $messages, array $opts = array() );

	/**
	 * Run a streamed chat completion, invoking $on_delta with each text
	 * fragment as it arrives. Implementations without streaming support may
	 * fall back to a single $on_delta call with the full content.
	 *
	 * @param array    $messages
	 * @param array    $opts
	 * @param callable $on_delta function ( string $text_fragment ): void
	 * @return array|WP_Error Same shape as chat().
	 */
	public function chat_stream( array $messages, array $opts, callable $on_delta );

	/**
	 * Estimated embedding cost in USD for a given token count (no API call).
	 *
	 * @param int $tokens
	 * @return float
	 */
	public function estimate_embedding_cost( $tokens );
}
