Skip to main content
The conv.utils property provides helper methods for extracting and validating information from the most recent user input during a conversation. These helpers are LLM-powered and return typed objects you can store in conv.state or use in your logic.
These utilities are opt-in and may not be enabled in your workspace. Contact your admin to request access.

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

​
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 populated; other fields may be None.
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. 
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-mini", "gpt-4.1-nano" – GPT-4.1 series
    • "claude-sonnet-4" – Claude Sonnet 4
    • "claude-3.5-haiku" – Claude 3.5 Haiku (fast)
Returns:
  • str or dict: The LLM response, parsed as JSON if return_json=True.
Raises:
  • NotImplementedError if the feature is not enabled for your account.
  • ChatCompletionError if the request fails.

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

​
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.
This feature requires legal approval and is currently restricted to specific projects.

​
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.
This feature requires legal approval and is currently restricted to specific projects.

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