Metadata-Version: 2.4
Name: hermes-plivo-tools
Version: 0.1.2
Summary: Plivo tools for Hermes Agent. Enables the agent to make live calls, send SMS and look up numbers.
Author: Plivo
License: MIT
Project-URL: Homepage, https://github.com/plivo-dev/hermes-plivo-tools
Project-URL: Repository, https://github.com/plivo-dev/hermes-plivo-tools
Project-URL: Issues, https://github.com/plivo-dev/hermes-plivo-tools/issues
Project-URL: Plivo API, https://www.plivo.com/docs/
Keywords: hermes,hermes-agent,plivo,sms,voice,lookup,plugin
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# hermes-plivo-tools

Plivo tools for [Hermes Agent](https://github.com/NousResearch/hermes-agent). The agent sends
text messages, places phone calls and looks up numbers through
[Plivo](https://cx.plivo.com/?utm_source=github&utm_medium=oss&utm_campaign=hermes-plivo-tools).

| Tool | Detail |
|---|---|
| `send_sms` | Sends a text message to a phone number |
| `make_call` | Places a call answered by Plivo call-control XML, for notifications and alerts |
| `lookup_number` | Returns carrier, country, line type and formatting details |

The plugin registers tools only. It hosts no server and registers no messaging platform, and
runs anywhere a Hermes agent runs. Standard library only, with no third-party dependencies.

## Requirements

| | |
|---|---|
| Hermes Agent | Python 3.11 or later |
| Plivo | An account, an SMS-capable number for `send_sms`, a voice-capable number for `make_call` |

## Installation

### 1. Install

```bash
pip install hermes-plivo-tools
```

Installing `hermes-plivo-phone-gateway` brings the plugin in as a dependency.

### 2. Enable

```bash
hermes plugins enable plivo-tools
hermes tools list
```

Hermes is opt-in and loads no plugin until enabled. Each tool is its own toolset, listed as
`plivo_send_sms`, `plivo_make_call` and `plivo_lookup_number`, and each one can be enabled or
disabled separately.

### 3. Add credentials

In `~/.hermes/.env`:

```dotenv
PLIVO_AUTH_ID=MAxxxxxxxxxxxxxxxxxx
PLIVO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
PLIVO_PHONE_NUMBER=+14155550100
```

The tools register whether or not credentials are present and refuse to dispatch without them,
leaving the plugin safe to install before the account is configured.

## Configuration

| Variable | Required | Purpose |
|---|---|---|
| `PLIVO_AUTH_ID` | yes | Plivo account auth ID |
| `PLIVO_AUTH_TOKEN` | yes | Plivo account auth token |
| `PLIVO_PHONE_NUMBER` | yes | Default sender and caller ID, E.164 |
| `PLIVO_ANSWER_URL` | no | Default document returning call-control XML for `make_call`. Plivo's demo document answers when absent |

Credentials are read through the Hermes profile-scoped secret store, with an environment
fallback, matching the bundled plugins.

## What an outbound call says

`make_call` needs a Plivo answer URL, a fetchable document returning call-control XML. The
Plivo API accepts no inline text and rejects a `data:` URI.

With none configured, calls reach Plivo's demo document, which speaks a single fixed sentence.
The tool result carries a warning whenever the demo document answers.

| To control what is said | Result |
|---|---|
| Install [hermes-plivo-phone-gateway](https://github.com/plivo-dev/hermes-plivo-phone-gateway) | The agent answers the call and holds a real-time conversation |
| Pass `answer_url` and `answer_method` | Whatever the document returns, for example `<Response><Speak>Deploy finished</Speak></Response>` |
| Set `PLIVO_ANSWER_URL` in `~/.hermes/.env` | The same, applied to every call |

## Security

- Credentials are read from the Hermes secret store or the environment, never from a file the
  plugin ships
- Phone numbers in tool results are masked to their last four digits
- Failures return structured JSON rather than raising, and a failed send leaves the agent turn
  intact

## Troubleshooting

| Symptom | Cause |
|---|---|
| Agent has no `send_sms`, `make_call` or `lookup_number` | The plugin is not enabled as `plivo-tools` |
| Only some of the three appear | Each tool is its own toolset and can be disabled separately |
| A call speaks one fixed sentence | No answer URL is configured, and Plivo's demo document answered |
| A tool reports missing credentials | `PLIVO_AUTH_ID` or `PLIVO_AUTH_TOKEN` is unset in `~/.hermes/.env` |

## Tests

```bash
python -m unittest discover -s tests
ruff check .
```

The suite covers number normalisation, credential handling, schema shapes and the handler
contract with the REST layer stubbed. It needs no Hermes install and touches no network.

## Limitations

- `make_call` on its own plays a fixed document. A spoken conversation needs
  `hermes-plivo-phone-gateway`
- Inbound SMS is a separate plugin, `hermes-plivo-sms`

## License

MIT
