intent helpers.md

Intent Helpers

Guava provides an intent classification helper for routing caller requests. IntentRecognizer classifies caller utterances into your predefined intents and returns matching actions for the dialog engine to handle.

IntentRecognizer

IntentRecognizer classifies a free-text caller utterance against your predefined intent labels and returns all plausible matches as SuggestedAction objects. Use it inside on_action_request() to map caller language to routing decisions — return the full list and let the dialog engine handle disambiguation automatically.

Import: from guava.helpers.llm import IntentRecognizer

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 to help IntentRecognizer disambiguate meaning. When a dict is passed, descriptions are also attached to the returned `SuggestedAction` objects so the dialog engine can use them when disambiguating multiple matches with the caller.

classify(intent: str) -> list[SuggestedAction] \| None — Returns all choices from intent_choices that plausibly match intent, ordered by likelihood. Returns None if no choice matches. It is recommended to return the full list from on_action_request to let the dialog engine handle disambiguation automatically.

IntentRecognizer (openai — deprecated)

Deprecated: IntentRecognizer from guava.helpers.openai is deprecated. Use the new IntentRecognizer from guava.helpers.llm above instead.

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.

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.

IntentClarifier (deprecated)

Deprecated: IntentClarifier from guava.helpers.openai is deprecated. Use the new IntentRecognizer from guava.helpers.llm above instead — it returns all plausible matches by default, replacing the need for a separate clarifier.

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.

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.