Skip to main content
This page requires Python familiarity. It covers helper methods available inside Python functions.
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 PolyAI support 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 (fastest, lowest cost)
    • "gpt-5.2-chat" – GPT-5.2 Chat (latest)
    • "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) 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.is_valid:
  conv.state.email = result.normalized_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.CurrencyConfig()
    • conv.utils.NameConfig()
    • conv.utils.AlphanumericConfig()
    • conv.utils.EnumConfig()
    • conv.utils.FreeTextConfig()
Returns:
  • EntityValidationResponse with is_valid, normalized_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.

​
geocode_address

Geocode a full address string using configured mapping services. 
address = conv.utils.geocode_address(
  full_address="123 Main St, New York, NY 10001",
  provider="google_maps"
)
Parameters:
  • full_address (str): The complete address string to geocode.
  • provider (str, optional): Geocoding provider ("google_maps" or "mapbox"). Default "google_maps".
Returns:
  • An Address instance with coordinates in other_fields if available.
Raises:
  • ExtractionError if geocoding fails or the address cannot be resolved.
This feature is available on select plans. Contact PolyAI support to check availability for your project.

​
extract_and_geocode_address

Extract a full address from the latest user input and geocode it in a single operation. 
address = conv.utils.extract_and_geocode_address(
  country="US",
  postcodes=["10001", "10002"],
  biases=["123 Main St, New York"],
  provider="google_maps"
)
Parameters:
  • country (str, optional): Country code to bias extraction/geocoding. Default "US".
  • postcodes (list[str], optional): Candidate postcodes to bias extraction.
  • biases (list[str], optional): Nearby or full addresses to bias extraction.
  • provider (str, optional): Geocoding provider. Default "google_maps".
Returns:
  • A fully geocoded Address with coordinates in other_fields if provided.
Raises:
  • ExtractionError if address extraction or geocoding fails.
This feature is available on select plans. Contact PolyAI support to check availability for your project.

​
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 March 22, 2026