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 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 (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.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.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.

​
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 geocoded coordinates populated where available.
Raises:
  • ExtractionError if geocoding fails or the address cannot be resolved.
This feature is available on select plans. Contact your PolyAI representative 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 24, 2026