few large files". * * @package AIPT\Api\ContentStructure\Engine\Generators\Formula * @since 2.8.0 */ namespace AIPT\Api\ContentStructure\Engine\Generators\Formula; use AIPT\Api\ContentStructure\Engine\StructuredCallerInterface; defined( 'ABSPATH' ) || exit; /** * Shared call/usage/budget helper for formula generators. */ final class FormulaCallRunner { /** * No targeted retry may start with less than this many seconds left * before the execution deadline (mirrors GenerationRoundRunner's own * rule). */ const MIN_RETRY_SECONDS = 15.0; /** * Run one StructuredCallerInterface::call(), filling in the * provider/model from runOptions when not explicitly overridden (a * targeted retry reuses the first call's resolved provider/model so a * mid-generation provider failover never happens between rounds). * * @param StructuredCallerInterface $caller Structured AI caller. * @param array $ctx Execution context (see GeneratorInterface). * @param array $compiled array{system:string,user:string,schema:array,schemaName:string,validate?:callable,image?:array}. * @param int $max_calls Provider-call budget for this call() (1 or 2). * @param float $deadline Unix deadline. * @param string $provider Provider override. * @param string $model Model override. * @return array StructuredCallerInterface::call()'s result. */ public function call( StructuredCallerInterface $caller, array $ctx, array $compiled, int $max_calls, float $deadline, string $provider = '', string $model = '' ): array { $request = array( 'provider' => '' !== $provider ? $provider : (string) ( $ctx['runOptions']['provider'] ?? '' ), 'model' => '' !== $model ? $model : (string) ( $ctx['runOptions']['model'] ?? '' ), 'system' => (string) ( $compiled['system'] ?? '' ), 'user' => (string) ( $compiled['user'] ?? '' ), 'schema' => isset( $compiled['schema'] ) && is_array( $compiled['schema'] ) ? $compiled['schema'] : array(), 'schemaName' => (string) ( $compiled['schemaName'] ?? 'aipt_blueprint_formula' ), 'maxCalls' => $max_calls, 'deadline' => $deadline, ); if ( isset( $compiled['validate'] ) && is_callable( $compiled['validate'] ) ) { $request['validate'] = $compiled['validate']; } if ( isset( $compiled['image'] ) && is_array( $compiled['image'] ) ) { $request['image'] = $compiled['image']; } return $caller->call( $request ); } /** * @return array{aiCalls:int,nativeStructuredOutput:bool,provider:string,model:string,durationMs:int} */ public function emptyUsage(): array { return array( 'aiCalls' => 0, 'nativeStructuredOutput' => false, 'provider' => '', 'model' => '', 'durationMs' => 0, ); } /** * @param array &$usage Accumulator, updated in place. * @param array $call_result StructuredCallerInterface::call()'s result. * @return void */ public function mergeUsage( array &$usage, array $call_result ): void { $usage['aiCalls'] += (int) ( $call_result['calls'] ?? 0 ); $usage['nativeStructuredOutput'] = $usage['nativeStructuredOutput'] || ! empty( $call_result['native'] ); $usage['provider'] = (string) ( $call_result['provider'] ?? $usage['provider'] ); $usage['model'] = (string) ( $call_result['model'] ?? $usage['model'] ); $usage['durationMs'] += (int) ( $call_result['durationMs'] ?? 0 ); } /** * Whether one more provider call may start: budget remains AND at least * MIN_RETRY_SECONDS remain before the deadline. * * @param int $budget Total provider-call budget for this generation. * @param int $calls_used Calls already made. * @param float $deadline Unix deadline. * @return bool */ public function canRetry( int $budget, int $calls_used, float $deadline ): bool { return ( $budget - $calls_used ) >= 1 && ( $deadline - microtime( true ) ) >= self::MIN_RETRY_SECONDS; } }