# Threshold Calibration Panel

Threshold Calibration Panel [#threshold-calibration-panel]

The **Threshold Calibration Panel** renders a similarity-threshold calibration result: the empirically **calibrated threshold** side-by-side with the model's **preset default** (or an explicit no-preset state), the calibration **metadata** (percentile, sample size, model ID, distance function), the pairwise similarity **distribution statistics** (mean / median / std-dev / min / max / pair count), and a **preset-thresholds reference** list with the active model highlighted. Loading and empty states carry optional calibrate / cancel affordances.

**When to use it:** surfacing the output of `useCalibrateThreshold` — tuning a semantic-search relevance threshold to your corpus, or comparing an empirical threshold against a model's known-good default.

**Relationship to [Evaluation Metrics Dashboard](/docs/results/evaluation-metrics-dashboard):** that composite ships an optional embedded calibration sub-view. This standalone panel is the full-fidelity calibration surface — it adds the preset comparison, the preset reference list, and the calibrate / cancel affordances. Use the dashboard for a combined metrics + matrix + calibration overview; use this panel when calibration is the focus.

Preview [#preview]

```tsx
'use client';

import {
  ThresholdCalibrationPanel,
  type CalibrationResult,
  type ThresholdPreset,
} from '@/components/threshold-calibration-panel';

/** A recorded BGE-small calibration result (fixture — no model runs here). */
const CALIBRATION: CalibrationResult = {
  threshold: 0.6234,
  percentile: 90,
  sampleSize: 20,
  modelId: 'Xenova/bge-small-en-v1.5',
  distanceFunction: 'cosine',
  distribution: {
    mean: 0.4187,
    median: 0.4021,
    stdDev: 0.1103,
    min: 0.1442,
    max: 0.7318,
    count: 190,
  },
};

/** Known-good preset thresholds (mirrors `MODEL_THRESHOLD_PRESETS`). */
const PRESETS: ThresholdPreset[] = [
  { modelId: 'Xenova/bge-small-en-v1.5', threshold: 0.5 },
  { modelId: 'Xenova/bge-base-en-v1.5', threshold: 0.5 },
  { modelId: 'Xenova/all-MiniLM-L6-v2', threshold: 0.68 },
  { modelId: 'nomic-ai/nomic-embed-text-v1.5', threshold: 0.55 },
  { modelId: 'Xenova/gte-small', threshold: 0.6 },
];

/**
 * Demo for ThresholdCalibrationPanel. Renders fixture calibration data only —
 * no model download, no network. Wire `calibration` to `useCalibrateThreshold`
 * and pair `presetThreshold` with `getDefaultThreshold(modelId)` in your app.
 */
export default function ThresholdCalibrationPanelDemo() {
  return (
    <div className="mx-auto w-full max-w-lg">
      <ThresholdCalibrationPanel
        calibration={CALIBRATION}
        presetThreshold={0.5}
        presets={PRESETS}
      />
    </div>
  );
}
```

Installation [#installation]

```bash
npx shadcn@latest add @localmode/ui/results/threshold-calibration-panel
```

Dependencies [#dependencies]

* **Data source:** renders the `calibration` object you pass — works with any backend. Recommended producer: `useCalibrateThreshold` from `@localmode/react` (optional). See [Bring your own data](/docs/bring-your-own-data#results--insights).

* `clsx` + `tailwind-merge` — via the shared `cn()` util

Files installed [#files-installed]

* `threshold-calibration-panel.tsx` — the component
* `lib/utils.ts` — the `cn()` helper (if not already present)

Props [#props]

**ThresholdCalibrationPanel**

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `calibration` | `object \| null` | — | **Required.** The calibration result to render, or `null` for the empty / pre-run state. Recommended producer: `useCalibrateThreshold` from `@localmode/react` — but any backend that returns this shape works. |
| `presetThreshold` | `number` | — | The selected model's preset threshold, rendered side-by-side with the calibrated value. Omit to show an explicit "no preset" state. |
| `presets` | `array` | — | A reference list of known-good preset thresholds. The entry whose `modelId` matches `calibration.modelId` is highlighted. |
| `isCalibrating` | `boolean` | — | Whether a calibration run is in progress (renders the busy state). |
| `onCalibrate` | `function` | — | Fired when the user requests a (re)calibration from the empty/idle state. |
| `onCancel` | `function` | — | Fired when the user cancels an in-flight calibration. |

Examples [#examples]

Wired to `useCalibrateThreshold` [#wired-to-usecalibratethreshold]

The panel is backend-agnostic — pass any producer of the `CalibrationResult` shape. The recommended LocalMode wiring pairs `presetThreshold` with `getDefaultThreshold(modelId)` and `presets` with `MODEL_THRESHOLD_PRESETS`:

```tsx
import { ThresholdCalibrationPanel } from '@/components/threshold-calibration-panel';
import { useCalibrateThreshold } from '@localmode/react';
import { getDefaultThreshold, MODEL_THRESHOLD_PRESETS } from '@localmode/core';

export function Example({ model, corpus }) {
  const { calibration, isCalibrating, calibrate, cancel } = useCalibrateThreshold({
    model,
    percentile: 90,
  });

  const presets = Object.entries(MODEL_THRESHOLD_PRESETS).map(([modelId, threshold]) => ({
    modelId,
    threshold,
  }));

  return (
    <ThresholdCalibrationPanel
      calibration={calibration}
      presetThreshold={getDefaultThreshold(model.modelId)}
      presets={presets}
      isCalibrating={isCalibrating}
      onCalibrate={() => calibrate(corpus)}
      onCancel={cancel}
    />
  );
}
```

Read-only result [#read-only-result]

Omit the callbacks to render the panel as a static result surface:

```tsx
<ThresholdCalibrationPanel calibration={calibration} presetThreshold={0.5} />
```

Model without a preset [#model-without-a-preset]

When `presetThreshold` is omitted, the panel shows an explicit "no preset for this model" state instead of a comparison value:

```tsx
<ThresholdCalibrationPanel calibration={calibration} />
```

Customization [#customization]

Sections render only when their data is present, so the panel adapts to read-only, busy, and empty states. The calibrated value uses `bg-primary/5` + `text-primary` to stand out from the preset; the delta caption tints amber when the calibrated threshold sits above the preset and sky when below. The preset reference highlights the entry matching `calibration.modelId` with `bg-primary/10`. All colors are shadcn/ui CSS-variable tokens, so the panel inherits the consumer's theme.