<?php

namespace Modules\AiCore\Entities\Verticals;

/**
 * Immutable description of ONE business type ("vertical").
 *
 * A vertical bundles the domain knowledge AiCore uses to get better results
 * out of any LLM for that kind of business, without the consumer having to
 * hand-write a prompt:
 *
 *   - persona     : who the assistant is + how it should sound (system prompt seed)
 *   - tone        : a short style directive layered on top of the persona
 *   - grounding   : bullet hints telling the model which facts it may rely on and
 *                   what it must hand off / never invent for this domain
 *   - actions     : tool names this vertical typically offers (advisory; the
 *                   consumer still gates + whitelists the real AiTool instances)
 *   - emoji/label : presentation only
 *
 * Profiles are pure data — see {@see VerticalCatalog} for the catalog and
 * {@see \Modules\AiCore\Entities\Services\PromptBuilder} for how they are
 * assembled into a final system prompt.
 */
class VerticalProfile
{
    public function __construct(
        public readonly string $key,
        public readonly string $label,
        public readonly string $emoji,
        public readonly string $persona,
        public readonly string $tone,
        /** @var string[] */
        public readonly array $grounding = [],
        /** @var string[] suggested tool names for this vertical */
        public readonly array $actions = [],
        public readonly float $temperature = 0.4,
        // ── Documentation framing — drives the business-type-aware dictation
        //    cleanup + scribe/assistant task prompts. Sensible generic defaults
        //    so any vertical works without filling these in. ──
        public readonly string $subject = 'customer',     // pet / patient / vehicle / customer
        public readonly string $scribeRole = 'documentation scribe editor',
        public readonly string $assistant = 'knowledgeable expert assistant',
        /** @var string[] substantive content to keep when cleaning a dictation */
        public readonly array $keep = [],
    ) {
    }

    /** What to keep when cleaning a dictation, with a generic fallback. */
    public function keepList(): array
    {
        return !empty($this->keep) ? $this->keep : [
            'The substantive details, facts, decisions and instructions discussed',
            'Names, quantities, measurements, dates and figures stated',
            'Actions taken or to be taken, and any follow-up',
        ];
    }

    /** "🐾 Veterinary Clinic" */
    public function displayLabel(): string
    {
        return trim($this->emoji . ' ' . $this->label);
    }

    /** Grounding hints rendered as a prompt block, or '' when none. */
    public function groundingBlock(): string
    {
        if (empty($this->grounding)) {
            return '';
        }
        return "DOMAIN GUIDANCE:\n- " . implode("\n- ", $this->grounding);
    }
}
