AI Top-K

# Brok UI: AI Top-K (`ai-top-k`)

A next-token probability debugger listing candidate tokens with proportional bars and percentages.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add ai-top-k
```

## Usage

```blade
<x-ui.ai.top-k class="mx-auto w-full max-w-sm" />
```

## Props

- `tokens` (array, default `[]`)

## Use when

- Use to expose AI-specific prompts, states, or reasoning metadata when those details help users supervise or understand an AI workflow.
- Inspecting the candidate next tokens a model considered, with their probabilities.
- Building a playground or eval tool where sampling has to be explained.

## Avoid when

- Do not surface internal AI mechanics when they add confusion or implementation detail without user value.
- Charting general data; chart and partition-bar are the data-viz primitives.
- Showing a single probability, where a progress bar reads more simply.

## Anti-patterns

- Decorative AI chrome
- Exposing internal mechanics without user value

## Rules

- Use the `<brok:ai-top-k>` tag (or `<x-ui.ai-top-k>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/ai-top-k
- Registry JSON (files, props, contract): https://brokui.dev/r/open/ai-top-k.json

@props([
    'tokens' => [],
])

@php
    $tokens = is_array($tokens) && count($tokens)
        ? $tokens
        : [
            ['token' => ' the', 'prob' => 0.42],
            ['token' => ' a', 'prob' => 0.21],
            ['token' => ' an', 'prob' => 0.12],
            ['token' => ' this', 'prob' => 0.08],
            ['token' => ' that', 'prob' => 0.05],
        ];

    // Highest probability for subtle emphasis of the front-runner.
    $maxProb = 0.0;
    foreach ($tokens as $t) {
        $maxProb = max($maxProb, (float) ($t['prob'] ?? 0));
    }
@endphp

{{--
    AI top-k — a next-token probability debugger. Each candidate token renders as
    a labelled row: the raw token in a monospace chip (literal spaces shown as ␣
    so leading whitespace is visible), a proportional bar fed by the inline --prob
    CSS var (width = calc(--prob * 100%)), and the percentage in tabular figures.
    Modelled as a description list (dt = token, dd = probability) for a11y.
--}}
<div
    data-slot="ai-top-k"
    role="group"
    aria-label="{{ __('Next token probabilities') }}"
    {{ $attributes->merge(['class' => 'rounded-md border border-border bg-card p-3 text-foreground']) }}
>
    <div data-slot="ai-top-k-title" class="mb-2 text-sm font-medium">{{ __('Next token') }}</div>

    <dl class="space-y-2">
        @foreach ($tokens as $t)
            @php
                $raw = (string) ($t['token'] ?? '');
                $prob = max(0.0, min(1.0, (float) ($t['prob'] ?? 0)));
                $pct = round($prob * 100, 1);
                $display = str_replace(' ', '␣', $raw);
                $isTop = $prob >= $maxProb && $maxProb > 0;
            @endphp
            <div class="flex items-center gap-2">
                <dt class="w-20 shrink-0">
                    <code class="inline-block max-w-full truncate rounded bg-muted px-2 text-xs font-mono {{ $isTop ? 'text-foreground' : 'text-muted-foreground' }}">{{ $display }}</code>
                </dt>
                <dd class="flex flex-1 items-center gap-2">
                    <div class="h-2 flex-1 overflow-hidden rounded-full bg-muted" aria-hidden="true">
                        <div
                            @class([
                                'h-full rounded-full bg-primary transition-[width] duration-500 motion-reduce:transition-none',
                                'opacity-100' => $isTop,
                                'opacity-70' => ! $isTop,
                            ])
                            style="--prob:{{ round($prob, 4) }};width:calc(var(--prob) * 100%)"
                        ></div>
                    </div>
                    <span class="w-12 shrink-0 text-end text-xs tabular-nums {{ $isTop ? 'font-medium text-foreground' : 'text-muted-foreground' }}">{{ $pct }}%</span>
                </dd>
            </div>
        @endforeach
    </dl>
</div>