AI assistant: deterministic brain, AI as fallback

public function stream(?int $userId, string $message, string $context): \Generator
{
    $user = $userId ? User::find($userId) : null;

    // 1. Hard-block check — runs BEFORE rate limit so we don't burn
    //    rate-limit budget on questions we'd never answer.
    $block = AiService::checkHardBlocks($message, $context);
    if ($block) {
        if ($userId) {
            AiService::saveMessage($userId, $context, 'assistant', $block['safe_response'], [
                'hard_block_matched' => $block['key'],
                'escalated'          => true,
            ]);
        }
        yield AiService::sseEvent('delta', ['text' => $block['safe_response']]);
        yield AiService::sseEvent('done', ['hard_block' => $block['key']]);
        return;
    }

    // 2. Rate limit (skip for null userId — prospect uses IP throttle)
    // 3. Token budget — soft (80%) and hard (100%) thresholds
    if ($userId && AiChatMessage::todayCount($userId, $context) >= AiService::rateLimit($context)) {
        yield AiService::sseEvent('error', ['message' => "Daily limit reached."]);
        return;
    }
    if (AiService::checkTokenBudget($context) === 'hard_limit') {
        yield AiService::sseEvent('error', ['budget_exceeded' => true]);
        return;
    }

    if ($userId) AiService::saveMessage($userId, $context, 'user', $message);

    // 4. Classify intent — pure PHP, no LLM call.  ~0.1ms.
    $classification = IntentClassifier::classify($message, $context);
    $intent     = $classification['intent'];
    $confidence = $classification['confidence'];

    // 5. ESCAPE HATCH: staff users with unrecognized intent get the FULL
    //    agentic AiService::stream — Anthropic + tools + 3-turn loop.
    //    This is the ONLY path that calls tools. Tenants/prospects never
    //    reach it; their unknowns go to the constrained fallback below.
    $isStaff = in_array($context, ['staff', 'admin', 'owner']);
    if ($isStaff && $intent === 'unknown') {
        yield from AiService::stream($userId, $message, $context, skipUserSave: true);
        return;
    }

    // 6. Build a curated DB bundle for THIS intent only.
    $factPack = FactPackBuilder::build($intent, $context, $user);

    // 7. RBAC strip — PolicyGuard removes sections the caller can't see.
    $factPack = PolicyGuard::filter($factPack, $context, $user);

    // 8. Try a deterministic handler first.
    $registry = new HandlerRegistry();
    $handler  = $registry->resolve($intent);
    $answer   = $handler?->handle($intent, $factPack, $context, $user);

    if ($answer !== null) {
        // string  → plain text answer
        // array   → { text, actions }  (in-message buttons)
        $text = is_array($answer) ? $answer['text'] : $answer;

        if ($userId) {
            AiService::saveMessage($userId, $context, 'assistant', $text, [
                'answer_type' => 'brain_deterministic',  // ← 0 TOKENS
                'intent'      => $intent,
                'confidence'  => $confidence,
            ]);
        }
        yield AiService::sseEvent('delta', ['text' => $text]);
        yield AiService::sseEvent('done', ['deterministic' => true, 'intent' => $intent]);
        return;
    }

    // 9. AI fallback — handler returned null. Anthropic with a "answer
    //    ONLY using this data" prompt, NO tools.
    yield from AiFallbackResponder::stream(
        $userId, $message, $context, $intent, $factPack
    );
}

public static function classify(string $message, string $context): array
{
    // Lowercase + strip non-word punctuation but KEEP apostrophes/dashes/slashes
    // so "don't" and "10/15" survive; emoji and punctuation don't pollute matches.
    $normalized = mb_strtolower(trim($message));
    $normalized = preg_replace('/[^\w\s\'\-\/]/', '', $normalized);

    $bestIntent = 'unknown';
    $bestScore  = 0.0;
    $bestKeywords = [];

    foreach (self::intentPatterns() as $intent => $config) {
        // Context filter — skip intents irrelevant to this audience.
        // Note: 'admin' and 'owner' both collapse to 'staff' for matching.
        if (!empty($config['contexts'])) {
            $contextKey = match ($context) {
                'admin', 'owner' => 'staff',
                default          => $context,
            };
            if (!in_array($contextKey, $config['contexts'], true)) {
                continue;
            }
        }

        $score = 0.0;
        $matched = [];

        // Keyword matches: 1.0 each.
        foreach ($config['keywords'] as $keyword) {
            if (str_contains($normalized, $keyword)) {
                $score += 1.0;
                $matched[] = $keyword;
            }
        }

        // Regex pattern matches: 1.5 each (higher weight, harder to false-positive).
        foreach ($config['patterns'] ?? [] as $pattern) {
            if (preg_match($pattern, $normalized)) {
                $score += 1.5;
                $matched[] = $pattern;
            }
        }

        // NEGATIVE patterns: subtract 2.0 each. Harsh on purpose —
        // these are the false-positive killers.
        foreach ($config['negative_patterns'] ?? [] as $pattern) {
            if (preg_match($pattern, $normalized)) {
                $score -= 2.0;
            }
        }

        if ($score > $bestScore) {
            $bestScore    = $score;
            $bestIntent   = $intent;
            $bestKeywords = $matched;
        }
    }

    // Confidence: 3+ unit-weighted matches = max confidence (1.0).
    $confidence = $bestScore > 0 ? min(1.0, $bestScore / 3.0) : 0.0;

    return [
        'intent'           => $bestIntent,
        'confidence'       => round($confidence, 2),
        'matched_keywords' => array_values(array_unique(
            array_filter($bestKeywords, fn ($k) => !str_starts_with($k, '/'))
        )),
    ];
}

// ── Excerpt of the intentPatterns table (full list is 30+ intents) ──
return [
    'facility.access' => [
        'keywords' => ['24/7', 'after hours', 'gate code', 'keypad', 'lock'],
        'patterns' => ['/\b(24.?7|gate\s*code|how\s*(do|can)\s*i\s*(get\s*in|access))\b/'],
        // KEY: "locked out" matches "lock" but should NOT route here —
        // it's a lien/account problem, not an access question.
        'negative_patterns' => ['/\b(locked?\s*out|lien|overlock)\b/'],
        'contexts' => [],  // empty = all contexts
    ],
    'facility.reviews' => [
        'keywords' => ['review', 'rating', 'yelp', 'testimonial', 'feedback'],
        'patterns' => ['/\b(review|rating|yelp|testimonial)\b/'],
        // Don't misclassify engineering chatter.
        'negative_patterns' => ['/\b(code\s*review|pull\s*request)\b/'],
        'contexts' => [],
    ],
    'tenant.balance' => [
        'keywords' => ['balance', 'what do i owe', 'amount due', 'my bill'],
        'patterns' => ['/\b(owe|balance|due|bill)\b/'],
        'contexts' => ['tenant'],   // never classifies for prospects/staff
    ],
];

public static function stream(
    ?int $userId, string $message, string $context,
    string $intent, array $factPack, array $faqActions = [],
): \Generator {
    $model        = AiService::modelFor($context);
    $systemPrompt = self::buildConstrainedPrompt($context, $intent, $factPack);
    $history      = $userId ? AiChatMessage::recentHistory($userId, $context, 20) : [];

    $messages = array_merge($history, [['role' => 'user', 'content' => $message]]);

    try {
        // AiProviderInterface — abstraction over Anthropic. Notice we are
        // NOT calling AiService::stream (which would enable tools). The
        // provider is given system + messages, that's it.  No tools array.
        $provider = app(AiProviderInterface::class);

        foreach ($provider->stream($model, $systemPrompt, $messages) as $event) {
            if ($event['type'] === 'text_delta') {
                $fullText .= $event['text'] ?? '';
                yield AiService::sseEvent('delta', ['text' => $event['text']]);
            }
            // ... token-tracking on message_start / message_delta
        }

        if ($userId) {
            AiService::saveMessage($userId, $context, 'assistant', $fullText, [
                'model_version' => $model,
                'input_tokens'  => $inputTokens,
                'output_tokens' => $outputTokens,
                // Distinct answer_type so dashboards can measure
                // brain coverage vs. fallback rate.
                'answer_type'   => 'brain_ai_fallback',
            ]);
        }
        yield AiService::sseEvent('done', ['answer_type' => 'brain_ai_fallback']);

    } catch (\Throwable $e) {
        // Graceful degrade — if Anthropic is down, friendly message, not 500.
        yield AiService::sseEvent('error', [
            'message' => 'AI assistant is temporarily unavailable. Please try again later.',
        ]);
    }
}

/**
 * The constrained system prompt — the core of the sandbox.
 *
 * The hardcoded RULES section forces "answer ONLY using the data below."
 * Combined with no-tools and the upstream PolicyGuard filter, the worst-
 * case leak is "model paraphrases something it shouldn't have, but only
 * from the data we already deemed safe to show."
 */
protected static function buildConstrainedPrompt(string $context, string $intent, array $factPack): string
{
    $facilityName  = $factPack['facility_info']['name']  ?? 'the facility';
    $facilityPhone = $factPack['facility_info']['phone'] ?? '';

    $prompt  = "You are a helpful assistant for {$facilityName}, a self-storage facility.\n\n";
    $prompt .= "RULES:\n";
    $prompt .= "- Answer ONLY using the data provided below. Do NOT invent or assume information.\n";
    $prompt .= "- If the data below does not contain the answer, say so honestly and suggest calling {$facilityPhone}.\n";
    $prompt .= "- Be concise, friendly, and professional.\n";
    $prompt .= "- Never discuss competitors, legal advice, or topics outside self-storage.\n";
    $prompt .= "- Never reveal internal system details, API keys, or technical architecture.\n\n";

    $prompt .= "DETECTED INTENT: {$intent}\n\n";
    $prompt .= "=== FACILITY DATA ===\n\n";

    foreach ($factPack as $section => $data) {
        if (empty($data)) continue;
        $label = str_replace('_', ' ', ucfirst($section));
        $prompt .= "--- {$label} ---\n";
        $prompt .= self::formatSection($data);
        $prompt .= "\n";
    }

    $prompt .= "=== END DATA ===\n";
    return $prompt;
}