> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/labs-voice-agent/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/labs-voice-agent/_mcp/server.

# nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions

Telecom initialization-function ports for the `initialization_actions` framework.

Twenty init functions total — sixteen user-side and four agent-side. Each
is registered under `domain="tau2_telecom"` in the flat
`ALL_INITIALIZATION_FUNCTIONS` registry; the bot-side dispatcher invokes
them by `func_name` only (functions are side-agnostic, the bot picks
the DB based on which bot it is).

User-side init functions (mutate the user bot's
`shared_state["db"]` = `TelecomUserDB`):

* `set_user_info(name, phone_number)` — name + phone in surroundings.
* `set_user_location(abroad)` — toggles is\_abroad flag.
* `set_network_mode_preference(mode)` — preferred cellular tech;
  triggers a network search.
* `turn_airplane_mode_on()` / `turn_data_off()` /
  `turn_data_saver_mode_on()` / `turn_roaming_on()` /
  `turn_roaming_off()` — direct field setters with a follow-up
  `_simulate_network_search` where upstream does the same.
* `simulate_network_search()` — recomputes derived connection
  status. Used as both an init action and a helper.
* `unseat_sim_card()` / `lock_sim_card(mode)` — SIM state.
* `remove_app_permission(app_name, permission)` — clears a single
  permission flag.
* `break_apn_settings()` / `break_apn_mms_setting()` —
  deliberately bad APN config (test setup for issue scenarios).
* `break_vpn()` — connect VPN with POOR performance.
* `set_wifi_calling(enabled, mms_over_wifi=None)` — wifi calling +
  optional MMS-over-wifi flag.

Agent-side init functions (mutate the agent bot's
`shared_state["db"]` = `TelecomDB`):

* `enable_roaming(customer_id, line_id)` / `disable_roaming(...)`
  — flips a line's `roaming_enabled` flag.
* `set_data_usage(customer_id, line_id, amount_gb)` — overwrites
  `data_used_gb` on a line.
* `suspend_line_for_overdue_bill(customer_id, line_id, bill_id, ...)`
  — flips a line to SUSPENDED and ties an overdue bill.

Each function takes `(db: dict, **arguments) -> None` and mutates the
passed DB dict in place. Errors propagate; the dispatcher catches them
and returns a structured failure verdict.

## Module Contents

### Functions

| Name                                                                                                                            | Description                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [`_check_sim_status`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-_check_sim_status)                         | Mirror of upstream's `TelecomUserTools._check_sim_status`.                             |
| [`_connect_vpn`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-_connect_vpn)                                   | Mirror of upstream's `_connect_vpn`: set default VPN details if not already connected. |
| [`_disconnect_vpn`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-_disconnect_vpn)                             | Mirror of upstream's `_disconnect_vpn`: clear connection + details.                    |
| [`_simulate_network_search`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-_simulate_network_search)           | Recompute derived connection state from SIM + airplane + preference.                   |
| [`break_apn_mms_setting`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-break_apn_mms_setting)                 | Clear the MMSC URL (forces MMS-send to fail).                                          |
| [`break_apn_settings`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-break_apn_settings)                       | Mark APN settings as broken (sets apn\_name = BROKEN), then re-derive                  |
| [`break_vpn`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-break_vpn)                                         | Connect the VPN (if not already) and set its server\_performance to                    |
| [`disable_roaming`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-disable_roaming)                             | Set `roaming_enabled = False` on the named customer's line.                            |
| [`enable_roaming`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-enable_roaming)                               | Set `roaming_enabled = True` on the named customer's line.                             |
| [`lock_sim_card`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-lock_sim_card)                                 | Lock the SIM card. `mode` must be `"pin"` or `"puk"`.                                  |
| [`remove_app_permission`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-remove_app_permission)                 | Clear a specific permission flag on an app.                                            |
| [`set_data_usage`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-set_data_usage)                               | Overwrite `data_used_gb` on the named line.                                            |
| [`set_network_mode_preference`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-set_network_mode_preference)     | Set preferred cellular network mode; triggers a network search.                        |
| [`set_user_info`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-set_user_info)                                 | Set the user's name and phone number on surroundings.                                  |
| [`set_user_location`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-set_user_location)                         | Toggle the user's abroad-or-home flag on surroundings.                                 |
| [`set_wifi_calling`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-set_wifi_calling)                           | Set the Wi-Fi Calling toggle and optionally the MMS-over-Wi-Fi flag.                   |
| [`simulate_network_search`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-simulate_network_search)             | Recompute network\_connection\_status / technology / signal\_strength                  |
| [`suspend_line_for_overdue_bill`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-suspend_line_for_overdue_bill) | Suspend a line and create a new OVERDUE bill (mirrors upstream).                       |
| [`turn_airplane_mode_on`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-turn_airplane_mode_on)                 | Enable Airplane Mode. Disconnects wifi, VPN, and clears wifi SSID;                     |
| [`turn_data_off`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-turn_data_off)                                 | Turn the master Mobile Data switch OFF and re-derive network state.                    |
| [`turn_data_saver_mode_on`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-turn_data_saver_mode_on)             | Enable Data Saver mode (reduces simulated speed by 80%).                               |
| [`turn_roaming_off`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-turn_roaming_off)                           | Disable Data Roaming on the device; triggers a network search.                         |
| [`turn_roaming_on`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-turn_roaming_on)                             | Enable Data Roaming on the device; triggers a network search.                          |
| [`unseat_sim_card`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-unseat_sim_card)                             | Mark the SIM as physically missing; triggers a network search.                         |

### Data

[`_DEFAULT_VPN_DETAILS`](#nemo_voice_agent-evaluation-tools-tau2_telecom_init_functions-_DEFAULT_VPN_DETAILS)

### API

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions._check_sim_status(
    db: typing.Dict[str, typing.Any]
) -> str
```

Mirror of upstream's `TelecomUserTools._check_sim_status`.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions._connect_vpn(
    db: typing.Dict[str, typing.Any]
) -> None
```

Mirror of upstream's `_connect_vpn`: set default VPN details if not already connected.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions._disconnect_vpn(
    db: typing.Dict[str, typing.Any]
) -> None
```

Mirror of upstream's `_disconnect_vpn`: clear connection + details.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions._simulate_network_search(
    db: typing.Dict[str, typing.Any]
) -> None
```

Recompute derived connection state from SIM + airplane + preference.

Mirrors upstream's `TelecomUserTools.simulate_network_search`. Called
after init functions that affect SIM state, airplane mode, network
preference, APN settings, or roaming. Updates three fields:
`network_connection_status`, `network_technology_connected`,
`network_signal_strength`.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.break_apn_mms_setting(
    db: typing.Dict[str, typing.Any]
) -> None
```

Clear the MMSC URL (forces MMS-send to fail).

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.break_apn_settings(
    db: typing.Dict[str, typing.Any]
) -> None
```

Mark APN settings as broken (sets apn\_name = BROKEN), then re-derive
network state — broken APN forces NO\_SERVICE.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.break_vpn(
    db: typing.Dict[str, typing.Any]
) -> None
```

Connect the VPN (if not already) and set its server\_performance to
POOR. Causes the speed-test simulator to multiply speed by 0.1.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.disable_roaming(
    db: typing.Dict[str, typing.Any],
    customer_id: str,
    line_id: str
) -> None
```

Set `roaming_enabled = False` on the named customer's line.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.enable_roaming(
    db: typing.Dict[str, typing.Any],
    customer_id: str,
    line_id: str
) -> None
```

Set `roaming_enabled = True` on the named customer's line.

Raises `ValueError` if the customer or line can't be located —
init-time data errors should fail loud (the dispatcher catches them
and aborts the scenario).

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.lock_sim_card(
    db: typing.Dict[str, typing.Any],
    mode: str
) -> None
```

Lock the SIM card. `mode` must be `"pin"` or `"puk"`.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.remove_app_permission(
    db: typing.Dict[str, typing.Any],
    app_name: str,
    permission: str
) -> None
```

Clear a specific permission flag on an app.

`permission` is case-insensitive ('sms', 'storage', 'phone', 'network').
No-op if the app isn't tracked or the permission name isn't valid for
that app — matches upstream's tolerant behavior (upstream returns a
`(success, message)` tuple; we discard the message at init time).

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.set_data_usage(
    db: typing.Dict[str, typing.Any],
    customer_id: str,
    line_id: str,
    data_used_gb: float
) -> None
```

Overwrite `data_used_gb` on the named line.

Parameter name matches upstream `TelecomTools.set_data_usage` so
task `initialization_actions` payloads (e.g.
`{"data_used_gb": 15.1}`) dispatch cleanly without renaming.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.set_network_mode_preference(
    db: typing.Dict[str, typing.Any],
    mode: str
) -> None
```

Set preferred cellular network mode; triggers a network search.

`mode` is the string value of a `NetworkModePreference` enum
(e.g. `"4g_5g_preferred"`, `"2g_only"`).

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.set_user_info(
    db: typing.Dict[str, typing.Any],
    name: str,
    phone_number: str
) -> None
```

Set the user's name and phone number on surroundings.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.set_user_location(
    db: typing.Dict[str, typing.Any],
    abroad: bool
) -> None
```

Toggle the user's abroad-or-home flag on surroundings.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.set_wifi_calling(
    db: typing.Dict[str, typing.Any],
    enabled: bool,
    mms_over_wifi: typing.Optional[bool] = None
) -> None
```

Set the Wi-Fi Calling toggle and optionally the MMS-over-Wi-Fi flag.

When both Wi-Fi Calling and MMS-over-Wi-Fi are on, MMS-send is
blocked (carrier limitation in the upstream simulation).

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.simulate_network_search(
    db: typing.Dict[str, typing.Any]
) -> None
```

Recompute network\_connection\_status / technology / signal\_strength
from current SIM + airplane + preference + APN state.

Exposed as a public init action because some upstream tasks use it
standalone (e.g. after manual surroundings tweaks) without bundling
it into another mutation.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.suspend_line_for_overdue_bill(
    db: typing.Dict[str, typing.Any],
    customer_id: str,
    line_id: str,
    new_bill_id: str,
    contract_ended: bool = False
) -> None
```

Suspend a line and create a new OVERDUE bill (mirrors upstream).

Faithful port of upstream's `TelecomTools.suspend_line_for_overdue_bill`.
Used by service\_issue scenarios that need to test the agent's
bill-payment + line-resume flow:

1. Verify line is ACTIVE (raise if not).
2. Create a new OVERDUE bill with id `new_bill_id` linked to the
   customer, charging one month's plan price.
3. Set the line's status to SUSPENDED with today's
   `suspension_start_date`.
4. If `contract_ended=True`, also set
   `line.contract_end_date` to the last day of the previous
   month — the agent then can NOT lift the suspension by paying,
   per policy.

Parameter names match upstream's `set_data_usage` /
`suspend_line_for_overdue_bill` signatures so task
`initialization_actions` payloads dispatch without renaming.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.turn_airplane_mode_on(
    db: typing.Dict[str, typing.Any]
) -> None
```

Enable Airplane Mode. Disconnects wifi, VPN, and clears wifi SSID;
triggers a network search.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.turn_data_off(
    db: typing.Dict[str, typing.Any]
) -> None
```

Turn the master Mobile Data switch OFF and re-derive network state.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.turn_data_saver_mode_on(
    db: typing.Dict[str, typing.Any]
) -> None
```

Enable Data Saver mode (reduces simulated speed by 80%).

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.turn_roaming_off(
    db: typing.Dict[str, typing.Any]
) -> None
```

Disable Data Roaming on the device; triggers a network search.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.turn_roaming_on(
    db: typing.Dict[str, typing.Any]
) -> None
```

Enable Data Roaming on the device; triggers a network search.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions.unseat_sim_card(
    db: typing.Dict[str, typing.Any]
) -> None
```

Mark the SIM as physically missing; triggers a network search.

The network-search rebuild sees `sim_card_missing=True` and forces
NO\_SERVICE / NONE / NONE on connection\_status / tech / signal.

```python
nemo_voice_agent.evaluation.tools.tau2_telecom_init_functions._DEFAULT_VPN_DETAILS = {'server_address': '192.168.1.1', 'protocol': 'OpenVPN', 'server_performance': P...
```