<?php

namespace Modules\AiCore\Entities\Contracts;

/**
 * A whitelisted, validated AI action.
 *
 * SECURITY MODEL (carried forward from WhatsApp's AppointmentBookingTool):
 * the model NEVER runs SQL and NEVER receives the right to act directly. It can
 * only *request* a named tool with structured args; the tool then validates
 * every argument in PHP and performs ONE safe, parameterised operation.
 *
 * Implementations MUST:
 *   - resolve the actor/owner from TRUSTED context (the WhatsApp number, the
 *     logged-in user…), never from model-supplied IDs;
 *   - validate & type every arg (parse + bound dates, constrain references to
 *     the actor's OWN records);
 *   - prefer pending/draft writes a human confirms; never delete or mutate
 *     critical data unless explicitly designed and permission-gated;
 *   - be idempotent / dedupe repeated requests.
 *
 * Tools are matched by exact {@see name()}; unknown names are ignored.
 */
interface AiTool
{
    /** Unique, whitelisted key, e.g. 'book_appointment'. [a-z_]+ only. */
    public function name(): string;

    /** Short description for the system prompt (when to use this tool). */
    public function description(): string;

    /**
     * JSON-schema-ish arg description used both to instruct the model and as a
     * validation hint, e.g. ['date' => 'YYYY-MM-DD (required)', 'pet' => 'pet name'].
     *
     * @return array<string,string>
     */
    public function argsSchema(): array;

    /**
     * Validate args IN PHP and perform exactly one safe operation.
     *
     * @param int   $businessId tenant scope
     * @param array $args       model-supplied, UNTRUSTED
     * @param array $context    trusted caller context (e.g. ['wa_id'=>..., 'conversation'=>...])
     * @return array{ok:bool, reply:string, meta:array} user-facing result
     */
    public function handle(int $businessId, array $args, array $context = []): array;
}
