> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.poly.ai/feedback

```json
{
  "path": "/tools/classes/conv-utils",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Conversation utilities

> Access secrets and helper methods for extracting addresses and other structured data from conv.utils.

The `conv.utils` property provides helper methods for accessing secrets, extracting and validating information from user input, and making standalone LLM calls.

## `get_secret`

Retrieve a stored [secret](/secrets/introduction) by name. Returns the secret value as a string or dictionary (for key/value pair secrets).

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
api_key = conv.utils.get_secret("stripe_api_key")
response = requests.get(url, headers={"Authorization": f"Bearer {api_key}"})
```

Parameters:

* `secret_name` (str): The name of the secret as configured in the [Secrets Vault](/secrets/how-to-setup).

Returns:

* `str` or `dict`: The secret value.

Raises:

* `SecretNotFound` if the secret does not exist.
* `MissingAccess` if the current agent does not have [access](/secrets/how-to-access-control) to this secret.

<Warning>Never hardcode credentials in function code. Always use `conv.utils.get_secret()` for API keys, tokens, and passwords.</Warning>

## `extract_address`

Extract a structured postal address from the latest user turn. Optionally validate against a list of known addresses.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
address = conv.utils.extract_address(country="US")
conv.state.user_address = address
```

Parameters:

* `addresses`: Optional list of `Address` objects to match against. Street name must be specified for each address.
* `country`: Optional country code to filter on (default `"US"`).

Returns:

* An `Address` instance with available fields populated. Some fields may be `None` if not provided.

Raises:

* `ExtractionError` if parsing fails.

Providing an `addresses` list improves extraction accuracy. Without it, street numbers or names may be missed or incorrect — always confirm extracted addresses with the caller before taking action.

## `extract_city`

Extract a valid city name (and optionally state/country) from the latest user turn.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
city_data = conv.utils.extract_city(states=["CA"], country="US")
conv.state.city = city_data.city
```

Parameters:

* `city_spellings`: Optional list of spelled-out city names to match.
* `states`: Optional list of states to filter on.
* `country`: Optional country code to filter on (default `"US"`).

Returns:

* An `Address` instance where the `city` field is guaranteed to be populated on a successful extraction; other fields may be `None`. If extraction fails, an `ExtractionError` is raised instead.

Raises:

* `ExtractionError` if parsing fails.

### `Address` type

Both utilities return the same `Address` type:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
@dataclass
class Address:
    street_number: Optional[str]
    street_name: Optional[str]
    city: Optional[str]
    state: Optional[str]
    postcode: Optional[str]
    country: Optional[str]
```

## `prompt_llm`

Perform a standalone LLM request with a given prompt. Useful for summarizing conversations or extracting specific information.

<Note>This method requires activation for your account. If you receive a `NotImplementedError`, contact your PolyAI representative to enable it.</Note>

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
summary = conv.utils.prompt_llm(
  "Summarize the key points from this conversation",
  show_history=True,
  return_json=False,
  model="gpt-4o"
)
```

Parameters:

* `prompt` (str): The system-level prompt containing instructions for the model.
* `show_history` (bool, optional): Whether to include conversation history in the request. Default `False`.
* `return_json` (bool, optional): Whether to return the response as a parsed JSON dict. Default `False`.
* `model` (str, optional): The LLM to use. Default `"gpt-4o"`. Available options:
  * `"gpt-4o"` – GPT-4o (default, balanced performance)
  * `"gpt-4o-mini"` – GPT-4o Mini (faster, lower cost)
  * `"gpt-4.1"` – GPT-4.1
  * `"gpt-4.1-mini"` – GPT-4.1 Mini
  * `"gpt-4.1-nano"` – GPT-4.1 Nano (fast, low cost)
  * `"gpt-5"` – GPT-5 (full reasoning model, highest capability)
  * `"gpt-5-mini"` – GPT-5 Mini (balanced speed and capability)
  * `"gpt-5-nano"` – GPT-5 Nano (fastest, lowest latency)
  * `"gpt-5-chat"` – GPT-5 Chat (optimised for conversation)
  * `"claude-3.5-haiku"` – Claude 3.5 Haiku (fast)
  * `"claude-sonnet-4"` – Claude Sonnet 4

Returns:

* `str` or `dict`: The LLM response, parsed as JSON if `return_json=True`.

Raises:

* `ChatCompletionError` if the request fails.

<Warning>`prompt_llm` makes a synchronous LLM call during the conversation turn. This adds latency — choose a smaller model (e.g. `"gpt-5-nano"` or `"gpt-4.1-nano"`) when speed matters, and avoid calling it multiple times in a single turn.</Warning>

## `validate_entity`

Validate an entity value against a configuration schema.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
result = conv.utils.validate_entity(
  value="john@example.com",
  entity_config=conv.utils.EmailConfig()
)
if result.valid:
  conv.state.email = result.value
```

Parameters:

* `value` (str): The value to validate.
* `entity_config` (EntityConfig): Configuration for the entity type. Available configs:
  * `conv.utils.EmailConfig()`
  * `conv.utils.PhoneNumberConfig()`
  * `conv.utils.DateConfig()`
  * `conv.utils.TimeConfig()`
  * `conv.utils.NumericConfig()`
  * `conv.utils.QuantityConfig()`
  * `conv.utils.CurrencyConfig()`
  * `conv.utils.NameConfig()`
  * `conv.utils.AlphanumericConfig()`
  * `conv.utils.EnumConfig()`
  * `conv.utils.FreeTextConfig()`

Returns:

* `EntityValidationResponse` with `valid`, `value`, and validation details. Some config types expose additional fields – for example, `PhoneNumberConfig` results include `country_code` and `number`. Available fields vary by config type.

<Warning>Entity values are always returned as strings, even for numeric entity types. Cast with `int()` or `float()` before numeric comparisons.</Warning>

## Notes

* **Latency**: Each method may take a few seconds to complete due to LLM processing.
* **Validation**: Providing allowed values (addresses, city spellings, or states) can improve accuracy.
* **Scope**: Operates on the most recent user input, including alternate transcript hypotheses.

## See also

* [`conv` object](./conv-object) – full list of conversation methods and attributes.