Skip to main content
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 by name. Returns the secret value as a string or dictionary (for key/value pair secrets). 
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.
Returns:
  • str or dict: The secret value.
Raises:
  • SecretNotFound if the secret does not exist.
  • MissingAccess if the current agent does not have access to this secret.
Never hardcode credentials in function code. Always use conv.utils.get_secret() for API keys, tokens, and passwords.

​
extract_address

Extract a structured postal address from the latest user turn. Optionally validate against a list of known addresses. 
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. 
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: 
@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.
This method requires activation for your account. If you receive a NotImplementedError, contact your PolyAI representative to enable it.
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.
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.

​
validate_entity

Validate an entity value against a configuration schema. 
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.
Entity values are always returned as strings, even for numeric entity types. Cast with int() or float() before numeric comparisons.

​
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 – full list of conversation methods and attributes.
Last modified on April 21, 2026