import { CodeTabs } from '../views/docs/CodeTabs';
import { Callout, NextLink } from '../views/docs/prose';
import {
  INTENT_RECOGNIZER_SIG_PY, INTENT_RECOGNIZER_SIG_TS,
  INTENT_RECOGNIZER_EX_PY, INTENT_RECOGNIZER_EX_TS,
  INTENT_CLARIFIER_SIG_PY, INTENT_CLARIFIER_SIG_TS,
  INTENT_CLARIFIER_EX_PY, INTENT_CLARIFIER_EX_TS,
} from './helpers-constants';

## Intent Helpers

Guava provides two intent classification helpers for routing caller requests: `IntentRecognizer` for single-best-match classification, and `IntentClarifier` for surfacing multiple plausible matches when the caller's intent is ambiguous.

Both classes are imported from `guava.helpers.openai`.

### IntentRecognizer

`IntentRecognizer` classifies a free-text caller utterance into one of your predefined intent labels. Use it inside `on_action_request()` to map vague caller language to clean routing decisions.

<CodeTabs
  python={{ code: INTENT_RECOGNIZER_SIG_PY, filename: "signature" }}
  typescript={{ code: INTENT_RECOGNIZER_SIG_TS, filename: "signature" }}
/>

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `intent_choices` | `list[str] \| dict[str, str]` | Yes | The set of intents to classify into. Pass a list of choice strings, or a dict mapping choice strings to plain-English descriptions (descriptions improve accuracy on similar-sounding choices). |
| `client` | `openai.OpenAI` | No | An OpenAI client to use. If omitted, a client is created automatically. |

**`classify(intent: str) -> str | None`** — Returns the single choice string from `intent_choices` that best matches `intent`, or `None` if the model cannot match any choice. When `intent_choices` is a `dict`, the keys are the valid return values; values are used only as descriptions to guide the model.

<CodeTabs
  python={{ code: INTENT_RECOGNIZER_EX_PY, filename: "support_agent.py" }}
  typescript={{ code: INTENT_RECOGNIZER_EX_TS, filename: "support_agent.ts" }}
/>

### IntentClarifier

`IntentClarifier` analyzes a caller's intent and returns the subset of choices that could plausibly match, ordered by likelihood. Use this when an intent may be ambiguous and you need to surface options for the caller to confirm.

<CodeTabs
  python={{ code: INTENT_CLARIFIER_SIG_PY, filename: "signature" }}
  typescript={{ code: INTENT_CLARIFIER_SIG_TS, filename: "signature" }}
/>

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `intent_choices` | `list[str] \| dict[str, str]` | Yes | The set of intents to match against. Same format as `IntentRecognizer`. |
| `client` | `openai.OpenAI` | No | An OpenAI client to use. If omitted, a client is created automatically. |

**`propose_choices(intent: str) -> list[str]`** — Returns a list of choices that could match `intent`, ordered by likelihood:
- One element if the intent clearly maps to a single choice.
- Multiple elements if the intent is ambiguous.
- Empty list if the intent matches none of the provided choices.

An empty list means the caller's intent is out-of-scope — not that an error occurred. When `intent_choices` is a `dict`, only the keys appear in the returned list.

<CodeTabs
  python={{ code: INTENT_CLARIFIER_EX_PY, filename: "scheduler_agent.py" }}
  typescript={{ code: INTENT_CLARIFIER_EX_TS, filename: "scheduler_agent.ts" }}
/>

<Callout>
  <span className="text-primary font-semibold">Model details:</span> Both `IntentRecognizer` and `IntentClarifier` use `gpt-5-mini` with a hardcoded `reasoning.effort` of `"low"`. These settings are not configurable.
</Callout>

<NextLink section="document-qa" label="DocumentQA" />