nemo_voice_agent.evaluation.tools.tau2_telecom_params

View as Markdown

Pydantic parameter models for tau2_telecom DB shapes.

Used primarily by scripts/prepare_tau2_data/prepare_telecom.py to round-trip the upstream TOML files through Pydantic — this materializes default field values (e.g. UserSurroundings.signal_strength per-network defaults, MockPhoneAttributes field defaults) that aren’t present in the raw TOML. After round-trip the converted JSON is shape-complete and downstream predicate / init function code can read fields via dict access without defensive .get(..., default) everywhere.

Per-tool *Params argument-schema classes are added incrementally as each LLM-callable tool is ported (same pattern as tau2_airline_params.py / tau2_retail_params.py).

Module Contents

Classes

NameDescription
APNNames-
APNSettingsAccess Point Name configuration.
AccountStatus-
Address-
AppPermissionsPermissions relevant to an application.
AppStatusStatus of a specific application relevant to issues.
BaseModelNoExtraMirror of upstream tau2.utils.pydantic_utils.BaseModelNoExtra.
Bill-
BillStatus-
CanSendMmsParamsNo arguments.
CheckApnSettingsParamsNo arguments.
CheckAppPermissionsParamsGet the permissions granted to a specific app.
CheckAppStatusParamsGet detailed status of a specific installed app.
CheckDataRestrictionStatusParamsNo arguments.
CheckInstalledAppsParamsNo arguments.
CheckNetworkModePreferenceParamsNo arguments.
CheckNetworkStatusParamsNo arguments.
CheckPaymentRequestParamsNo arguments.
CheckSimStatusParamsNo arguments.
CheckStatusBarParamsNo arguments. Returns the formatted phone-status-bar string.
CheckVpnStatusParamsNo arguments.
CheckWifiCallingStatusParamsNo arguments.
CheckWifiStatusParamsNo arguments.
ConnectVpnParamsNo arguments.
Customer-
Device-
DeviceType-
DisableRoamingParamsDisable international data roaming on a line.
DisconnectVpnParamsNo arguments.
EnableRoamingParamsEnable international data roaming on a line.
GetBillsForCustomerParamsList a customer’s bills, most-recent-first, optionally limited.
GetCustomerByIdParamsRetrieve a customer record by their customer ID.
GetCustomerByNameParamsFind customer records by full name + date of birth (YYYY-MM-DD).
GetCustomerByPhoneParamsFind a customer record by their primary or line phone number.
GetDataUsageParamsGet current cycle data usage + plan limit + refueling amount for a line.
GetDetailsByIdParamsGet details for any object by its ID (Customer C, Line L,
GrantAppPermissionParamsGrant a specific permission to a specific app.
Line-
LineItem-
LineStatus-
MakePaymentParamsNo arguments. Pays the most recent pending payment request from the agent.
MockPhoneAttributesState attributes of the mock phone device on the user side.
NetworkModePreference-
NetworkStatus-
NetworkTechnology-
PaymentMethod-
PaymentMethodType-
PaymentRequestPayment request initiated by the agent that the user can pay.
PerformanceLevel-
Plan-
RebootDeviceParamsNo arguments.
RefuelDataParamsRefuel a line with additional data (positive GB amount). Adds a
ReseatSimCardParamsNo arguments.
ResetApnSettingsParamsNo arguments.
ResumeLineParamsResume a Suspended or Pending Activation line.
RunSpeedTestParamsNo arguments. Returns the simulated mobile-data download speed.
SendPaymentRequestParamsSend a payment request to the customer for a specific bill.
SetApnSettingsParamsSets the active APN settings to a new APNSettings dict.
SetNetworkModePreferenceParamsSets the preferred cellular network mode (5G, 4G, 3G, 2G).
SignalStrength-
SimStatus-
StatusBarInformation displayed in the phone’s status bar.
SuspendLineParamsSuspend an Active line; records suspension start date + reason.
TelecomDBDatabase interface for the telecom domain (agent-facing).
TelecomUserDBDatabase interface for the telecom domain (user-facing).
ToggleAirplaneModeParamsNo arguments. Toggles Airplane Mode on the device.
ToggleDataParamsNo arguments. Toggles the mobile-data master switch on the device.
ToggleDataSaverModeParamsNo arguments.
ToggleRoamingParamsNo arguments.
ToggleWifiCallingParamsNo arguments.
ToggleWifiParamsNo arguments.
TransferToHumanAgentsParamsTransfer the call to a human agent with a summary of the issue.
UserSurroundingsPhysical surroundings of the user (per-task; populated by init actions).
VpnDetailsDetails about the VPN connection if active.
_NoArgsParamsShared no-arguments schema used by every parameter-less telecom tool.

Functions

NameDescription
validation_error_responseMirror of the helper in tau2_retail_params.py — uniform shape for

Data

DEFAULT_START_DATE

__all__

API

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.APNNames

Bases: enum.Enum

BROKEN
= 'broken'
INTERNET
= 'internet'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.APNSettings()

Bases: BaseModelNoExtra

Access Point Name configuration.

apn_name
APNNames
mms_apn
Optional[str]
mms_port
Optional[int] = Field(None, description='MMS proxy server port')
mms_proxy
Optional[str]
mmsc_url
Optional[str]
reset_at_reboot
bool
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.AccountStatus

Bases: enum.Enum

ACTIVE
= 'Active'
CLOSED
= 'Closed'
PENDING_VERIFICATION
= 'Pending Verification'
SUSPENDED
= 'Suspended'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.Address()

Bases: BaseModelNoExtra

city
str = Field(description='City name')
state
str
street
str
zip_code
str = Field(description='Postal/ZIP code')
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.AppPermissions()

Bases: BaseModelNoExtra

Permissions relevant to an application.

network
bool
phone
bool
sms
bool
storage
bool
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.AppStatus()

Bases: BaseModelNoExtra

Status of a specific application relevant to issues.

app_name
str
permissions
AppPermissions
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.BaseModelNoExtra()

Bases: BaseModel

Mirror of upstream tau2.utils.pydantic_utils.BaseModelNoExtra.

Forbids extra fields on input — catches typos in upstream data and in init/predicate function arguments at validation time.

model_config
= ConfigDict(extra='forbid')
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.Bill()

Bases: BaseModelNoExtra

bill_id
str
customer_id
str
due_date
date
issue_date
date
line_items
List[LineItem]
period_end
date
period_start
date
status
BillStatus
total_due
float = Field(description='Total amount due in USD')
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.BillStatus

Bases: enum.Enum

AWAITING_PAYMENT
= 'Awaiting Payment'
DISPUTED
= 'Disputed'
DRAFT
= 'Draft'
ISSUED
= 'Issued'
OVERDUE
= 'Overdue'
PAID
= 'Paid'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CanSendMmsParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckApnSettingsParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckAppPermissionsParams()

Bases: BaseModelNoExtra

Get the permissions granted to a specific app.

app_name
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckAppStatusParams()

Bases: BaseModelNoExtra

Get detailed status of a specific installed app.

app_name
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckDataRestrictionStatusParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckInstalledAppsParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckNetworkModePreferenceParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckNetworkStatusParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckPaymentRequestParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckSimStatusParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckStatusBarParams()

Bases: _NoArgsParams

No arguments. Returns the formatted phone-status-bar string.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckVpnStatusParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckWifiCallingStatusParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.CheckWifiStatusParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.ConnectVpnParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.Customer()

Bases: BaseModelNoExtra

account_status
AccountStatus
address
Address = Field(description="Customer's billing address")
bill_ids
List[str]
created_at
datetime
customer_id
str
date_of_birth
str
email
str = Field(description="Customer's email address")
full_name
str = Field(description="Customer's full name")
goodwill_credit_used_this_year
float
last_extension_date
Optional[date]
line_ids
List[str]
payment_methods
List[PaymentMethod]
phone_number
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.Device()

Bases: BaseModelNoExtra

activated
bool
activation_date
Optional[datetime]
device_id
str
device_type
DeviceType = Field(description='Type/category of the device')
imei
Optional[str]
is_esim_capable
bool
last_esim_transfer_date
Optional[datetime]
model
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.DeviceType

Bases: enum.Enum

OTHER
= 'other'
PHONE
= 'phone'
ROUTER
= 'router'
TABLET
= 'tablet'
WATCH
= 'watch'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.DisableRoamingParams()

Bases: BaseModelNoExtra

Disable international data roaming on a line.

customer_id
str
line_id
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.DisconnectVpnParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.EnableRoamingParams()

Bases: BaseModelNoExtra

Enable international data roaming on a line.

customer_id
str
line_id
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.GetBillsForCustomerParams()

Bases: BaseModelNoExtra

List a customer’s bills, most-recent-first, optionally limited.

customer_id
str
limit
int = 12
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.GetCustomerByIdParams()

Bases: BaseModelNoExtra

Retrieve a customer record by their customer ID.

customer_id
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.GetCustomerByNameParams()

Bases: BaseModelNoExtra

Find customer records by full name + date of birth (YYYY-MM-DD).

dob is required for name-based lookup — disambiguates customers with the same name (upstream policy: name alone cannot identify; DOB confirms identity).

dob
str
full_name
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.GetCustomerByPhoneParams()

Bases: BaseModelNoExtra

Find a customer record by their primary or line phone number.

phone_number
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.GetDataUsageParams()

Bases: BaseModelNoExtra

Get current cycle data usage + plan limit + refueling amount for a line.

customer_id
str
line_id
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.GetDetailsByIdParams()

Bases: BaseModelNoExtra

Get details for any object by its ID (Customer C, Line L, Device D, Bill B, or Plan P).

id
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.GrantAppPermissionParams()

Bases: BaseModelNoExtra

Grant a specific permission to a specific app.

permission is one of the lowercase keys on AppPermissions (storage, camera, microphone, location, contacts, sms, phone). Unknown keys are rejected at execution time.

app_name
str
permission
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.Line()

Bases: BaseModelNoExtra

contract_end_date
Optional[date]
data_refueling_gb
float
data_used_gb
float
device_id
Optional[str]
last_plan_change_date
Optional[date]
last_sim_replacement_date
Optional[date]
line_id
str
phone_number
str
plan_id
str
roaming_enabled
bool
status
LineStatus
suspension_start_date
Optional[date]
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.LineItem()

Bases: BaseModelNoExtra

amount
float
date
date
description
str
item_type
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.LineStatus

Bases: enum.Enum

ACTIVE
= 'Active'
CLOSED
= 'Closed'
PENDING_ACTIVATION
= 'Pending Activation'
SUSPENDED
= 'Suspended'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.MakePaymentParams()

Bases: _NoArgsParams

No arguments. Pays the most recent pending payment request from the agent.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.MockPhoneAttributes()

Bases: BaseModelNoExtra

State attributes of the mock phone device on the user side.

active_apn_settings
APNSettings
airplane_mode
bool
app_statuses
Dict[str, AppStatus]
battery_level
int = Field(80, description='Battery level (0-100)')
data_enabled
bool
data_saver_mode
bool
network_connection_status
NetworkStatus
network_mode_preference
NetworkModePreference
network_signal_strength
SignalStrength
network_technology_connected
NetworkTechnology
roaming_enabled
bool
sim_card_missing
bool
sim_card_status
SimStatus
vpn_connected
bool
vpn_details
Optional[VpnDetails]
vpn_enabled_setting
bool
wifi_calling_enabled
bool
wifi_calling_mms_over_wifi
bool
wifi_connected
bool
wifi_enabled
bool
wifi_signal_strength
SignalStrength
wifi_ssid
Optional[str]
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.NetworkModePreference

Bases: enum.Enum

FOUR_G_5G_PREFERRED
= '4g_5g_preferred'
FOUR_G_ONLY
= '4g_only'
THREE_G_ONLY
= '3g_only'
TWO_G_ONLY
= '2g_only'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.NetworkStatus

Bases: enum.Enum

CONNECTED
= 'connected'
EMERGENCY_ONLY
= 'emergency_only'
NO_SERVICE
= 'no_service'
SEARCHING
= 'searching'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.NetworkTechnology

Bases: enum.Enum

FIVE_G
= '5G'
FOUR_G
= '4G'
NONE
= 'none'
THREE_G
= '3G'
TWO_G
= '2G'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.PaymentMethod()

Bases: BaseModelNoExtra

account_number_last_4
str
expiration_date
str
method_type
PaymentMethodType = Field(description='Type of payment method')
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.PaymentMethodType

Bases: enum.Enum

CREDIT_CARD
= 'Credit Card'
DEBIT_CARD
= 'Debit Card'
PAYPAL
= 'PayPal'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.PaymentRequest()

Bases: BaseModelNoExtra

Payment request initiated by the agent that the user can pay.

amount_due
float = Field(description='Amount of the payment in USD')
bill_id
str = Field(description='The ID of the bill')
paid
bool
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.PerformanceLevel

Bases: enum.Enum

EXCELLENT
= 'excellent'
FAIR
= 'fair'
GOOD
= 'good'
POOR
= 'poor'
UNKNOWN
= 'unknown'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.Plan()

Bases: BaseModelNoExtra

data_limit_gb
float
data_refueling_price_per_gb
float
name
str = Field(description='Display name of the plan')
plan_id
str
price_per_month
float
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.RebootDeviceParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.RefuelDataParams()

Bases: BaseModelNoExtra

Refuel a line with additional data (positive GB amount). Adds a one-time charge to the customer’s next bill at the plan’s refueling rate.

customer_id
str
gb_amount
float
line_id
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.ReseatSimCardParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.ResetApnSettingsParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.ResumeLineParams()

Bases: BaseModelNoExtra

Resume a Suspended or Pending Activation line.

customer_id
str
line_id
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.RunSpeedTestParams()

Bases: _NoArgsParams

No arguments. Returns the simulated mobile-data download speed.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.SendPaymentRequestParams()

Bases: BaseModelNoExtra

Send a payment request to the customer for a specific bill.

Sets the bill to AWAITING_PAYMENT. Fails if another bill is already awaiting payment for this customer (one open request at a time).

bill_id
str
customer_id
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.SetApnSettingsParams()

Bases: BaseModelNoExtra

Sets the active APN settings to a new APNSettings dict.

Upstream accepts Union[APNSettings, dict]. Voice mode receives dict shape only.

apn_settings
Dict[str, Any]
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.SetNetworkModePreferenceParams()

Bases: BaseModelNoExtra

Sets the preferred cellular network mode (5G, 4G, 3G, 2G).

mode is the string value of a NetworkModePreference enum (e.g. "4g_5g_preferred", "4g_only", "3g_only", "2g_only"). Invalid values are rejected by the tool with a failure message instead of a Pydantic ValidationError, so the schema accepts a plain str — matches upstream’s permissive signature.

mode
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.SignalStrength

Bases: enum.Enum

EXCELLENT
= 'excellent'
FAIR
= 'fair'
GOOD
= 'good'
NONE
= 'none'
POOR
= 'poor'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.SimStatus

Bases: enum.Enum

ACTIVE
= 'active'
LOCKED_PIN
= 'locked_pin'
LOCKED_PUK
= 'locked_puk'
MISSING
= 'missing'
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.StatusBar()

Bases: BaseModelNoExtra

Information displayed in the phone’s status bar.

Upstream uses this as a derived view in check_status_bar; we don’t consume it from the runtime DB (predicate code reads device fields directly). Kept for parity in case a future ported tool needs it.

airplane_mode
bool
battery_level
int
data_saver_active
bool
network_type
NetworkTechnology
signal_strength
SignalStrength
vpn_active
bool
wifi_connected
bool
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.SuspendLineParams()

Bases: BaseModelNoExtra

Suspend an Active line; records suspension start date + reason.

customer_id
str
line_id
str
reason
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.TelecomDB()

Bases: BaseModelNoExtra

Database interface for the telecom domain (agent-facing).

Round-trip target for scripts/prepare_tau2_data/prepare_telecom.py’s db.tomldb.json conversion. Materializes default fields on nested types (e.g. Bill.line_items=[]).

bills
List[Bill]
customers
List[Customer]
devices
List[Device]
lines
List[Line]
plans
List[Plan]
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.TelecomUserDB()

Bases: BaseModelNoExtra

Database interface for the telecom domain (user-facing).

Round-trip target for scripts/prepare_tau2_data/prepare_telecom.py’s user_db.tomluser_db.json conversion. Critical to materialize the default surroundings block so predicate / init functions can read its fields without dict-key-missing errors.

device
MockPhoneAttributes
surroundings
UserSurroundings
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.ToggleAirplaneModeParams()

Bases: _NoArgsParams

No arguments. Toggles Airplane Mode on the device.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.ToggleDataParams()

Bases: _NoArgsParams

No arguments. Toggles the mobile-data master switch on the device.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.ToggleDataSaverModeParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.ToggleRoamingParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.ToggleWifiCallingParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.ToggleWifiParams()

Bases: _NoArgsParams

No arguments.

class nemo_voice_agent.evaluation.tools.tau2_telecom_params.TransferToHumanAgentsParams()

Bases: BaseModelNoExtra

Transfer the call to a human agent with a summary of the issue.

summary
str
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.UserSurroundings()

Bases: BaseModelNoExtra

Physical surroundings of the user (per-task; populated by init actions).

Per-task user state — name, phone number, location, signal-strength table at the user’s current location, etc. Upstream’s user_db.toml only carries the device defaults; surroundings is populated per-task by initialization_actions like set_user_info and set_user_location. The Pydantic round-trip in prepare_telecom.py materializes the default surroundings block (with name=None, phone_number=None, is_abroad=False, etc.) so init functions can mutate fields without needing defensive .setdefault().

is_abroad
bool
line_active
bool = Field(True, description='User has an active line')
mobile_data_usage_exceeded
bool
name
Optional[str] = Field(None, description='The name of the user')
payment_request
Optional[PaymentRequest]
phone_number
Optional[str]
roaming_allowed
bool
signal_strength
Dict[NetworkTechnology, SignalStrength]
class nemo_voice_agent.evaluation.tools.tau2_telecom_params.VpnDetails()

Bases: BaseModelNoExtra

Details about the VPN connection if active.

protocol
Optional[str]
server_address
Optional[str] = Field(None, description='VPN server address')
server_performance
PerformanceLevel
class nemo_voice_agent.evaluation.tools.tau2_telecom_params._NoArgsParams()

Bases: BaseModelNoExtra

Shared no-arguments schema used by every parameter-less telecom tool.

nemo_voice_agent.evaluation.tools.tau2_telecom_params.validation_error_response(
exc: typing.Any
) -> dict

Mirror of the helper in tau2_retail_params.py — uniform shape for Pydantic validation errors raised inside _Tau2InvokeMixin.invoke().

nemo_voice_agent.evaluation.tools.tau2_telecom_params.DEFAULT_START_DATE = datetime.date(2025, 1, 1)
nemo_voice_agent.evaluation.tools.tau2_telecom_params.__all__ = ['BaseModelNoExtra', 'DeviceType', 'LineStatus', 'BillStatus', 'AccountStatus', ...