<?php

namespace GriffinForms\Includes\Ai;

class ClassificationResult
{
    /** @var string 'advice'|'suggestion'|'scope_mismatch'|'generation'|'single'|'batch'|'potential_paths' */
    public string $type;

    /** Resolved handler key (empty for advice/scope_mismatch/potential_paths) */
    public string $handler_key;

    /** Selected item type (for single/scope_mismatch) */
    public string $item_type;

    /** Selected item ID (for single/scope_mismatch) */
    public int $item_id;

    /** [['type'=>string,'id'=>int,'handler_key'=>string], ...] for batch */
    public array $batch_items;

    /** Passed through for handler config assembly */
    public array $suggestion_context;

    /** User-facing message when type=scope_mismatch */
    public string $scope_mismatch_message;

    /**
     * [ ['token'=>string,'user_label'=>string], ... ] max 3
     * Tokens are generated server-side and stored in transients.
     * Defined in 3.1.8.0 (reserved); populated by runModelLayer() in 3.1.9.0.
     */
    public array $potential_paths;

    private function __construct()
    {
        $this->type                  = '';
        $this->handler_key           = '';
        $this->item_type             = '';
        $this->item_id               = 0;
        $this->batch_items           = [];
        $this->suggestion_context    = [];
        $this->scope_mismatch_message = '';
        $this->potential_paths       = [];
    }

    public static function advice(): self
    {
        $r = new self();
        $r->type        = 'advice';
        $r->handler_key = 'advisory_response';
        return $r;
    }

    public static function suggestionShortCircuit(string $suggestion_id, string $handler_key, array $suggestion_context = []): self
    {
        $r = new self();
        $r->type               = 'suggestion';
        $r->handler_key        = $handler_key;
        $r->suggestion_context = $suggestion_context;
        return $r;
    }

    public static function scopeMismatch(array $selected_context, string $message = ''): self
    {
        $r = new self();
        $r->type                  = 'scope_mismatch';
        $r->item_type             = sanitize_key((string) ($selected_context['item_type'] ?? ''));
        $r->item_id               = absint($selected_context['item_id'] ?? 0);
        $r->scope_mismatch_message = $message !== '' ? $message : __("Your prompt doesn't seem to match the selected element. Please reselect an element or clarify your intent.", 'griffinforms-form-builder');
        return $r;
    }

    public static function single(string $handler_key, string $item_type = '', int $item_id = 0): self
    {
        $r = new self();
        $r->type        = 'single';
        $r->handler_key = $handler_key;
        $r->item_type   = $item_type;
        $r->item_id     = $item_id;
        return $r;
    }

    public static function generation(string $handler_key): self
    {
        $r = new self();
        $r->type        = 'generation';
        $r->handler_key = $handler_key;
        return $r;
    }

    public static function batch(array $items): self
    {
        $r = new self();
        $r->type        = 'batch';
        $r->batch_items = $items;
        return $r;
    }

    /**
     * Reserved in 3.1.8.0 — called by runModelLayer() in 3.1.9.0 when all matches are low confidence.
     *
     * @param array $paths [ ['token'=>string, 'user_label'=>string], ... ] max 3 entries
     */
    public static function potentialPaths(array $paths): self
    {
        $r = new self();
        $r->type            = 'potential_paths';
        $r->potential_paths = array_slice($paths, 0, 3);
        return $r;
    }
}
