Metadata-Version: 2.4
Name: concinno-skills-mobile
Version: 0.1.0
Summary: Mobile phone + SMS/Voice/WhatsApp agent skills for Concinno — Twilio (MIT) unified. HammerBench-adjacent blue ocean.
Project-URL: Homepage, https://github.com/aiking931931/concinno
Project-URL: Issues, https://github.com/aiking931931/concinno/issues
Project-URL: Changelog, https://github.com/aiking931931/concinno/blob/main/projects/concinno-skills-mobile/CHANGELOG.md
Author-email: "AI King (Chen-Xuan Wang)" <me@ai-king.dev>
License-Expression: Apache-2.0
Keywords: agent,concinno,hammerbench,mobile,skills,sms,telephony,twilio,voice,whatsapp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: concinno>=2.15.1
Requires-Dist: twilio>=9.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# concinno-skills-mobile

Mobile / telephony agent skills for [Concinno](https://pypi.org/project/concinno/).
Unified on the **MIT-licensed** [Twilio](https://pypi.org/project/twilio/)
Python SDK — the most mature programmatic-telephony provider for SMS,
voice, and WhatsApp Business. Device-side Android / iOS shell control
is intentionally out of scope; that belongs to the Sancio runtime
layer.

## Why this package exists

HammerBench (and adjacent benchmarks) evaluate agents on realistic
telephony / SaaS workflows. Concinno can drive Twilio today over plain
HTTPS — no device emulator, no OS-level hook — making this the
blue-ocean entry point for mobile skills in the Concinno ecosystem.

## Status

MVP (0.1.0) — three one-shot tools:

| Tool class         | Channel    | Underlying API                           | SDK licence |
|--------------------|------------|------------------------------------------|-------------|
| `TwilioSms`        | SMS        | Twilio Programmable Messaging            | MIT         |
| `TwilioWhatsApp`   | WhatsApp   | Twilio WhatsApp Business (Messaging)     | MIT         |
| `TwilioVoiceCall`  | Voice      | Twilio Programmable Voice                | MIT         |

Microsoft Teams / push-only providers (Pushover, ntfy) are deferred
until they land in a dedicated sibling sub-package.

## Install

```bash
pip install concinno-skills-mobile
```

`twilio>=9.0` is a hard dependency and is pulled in automatically.

## Twilio account requirements

You need **a Twilio account (trial or paid)**. Outbound SMS / WhatsApp
messages and voice calls **cost money** per Twilio's per-country
pricing. A `WARNING`-level log line is emitted to stderr before every
outbound call so the billing risk is visible in agent traces.

- SMS: buy (or port) a Twilio phone number in a country you need to
  send to; long-code numbers are rate-limited to roughly 1 msg/sec.
- WhatsApp: register a WhatsApp-enabled sender (Twilio Sandbox for
  trials or a fully-verified Business sender for production) — addresses
  use the `whatsapp:+<digits>` prefix on both `to` and `from_`.
- Voice: any Twilio number with Voice capability works; the call
  behaviour is driven by either inline TwiML XML or a URL pointing at a
  hosted TwiML document.

## Credentials

The Twilio `account_sid` + `auth_token` are read from the Concinno
`CredentialStore`, which consults (in order):

1. Process runtime overrides via `CredentialStore.set(...)`.
2. Env var `CONCINNO_CRED_<UPPER_KEY>`.
3. `~/.concinno/credentials.json`.

| Key                    | Env var                              |
|------------------------|--------------------------------------|
| `twilio_account_sid`   | `CONCINNO_CRED_TWILIO_ACCOUNT_SID`   |
| `twilio_auth_token`    | `CONCINNO_CRED_TWILIO_AUTH_TOKEN`    |

Example `~/.concinno/credentials.json`:

```jsonc
{
  "twilio_account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "twilio_auth_token":  "your_auth_token_here"
}
```

If either credential is missing the tool returns
`{"error": "no twilio credentials — set account_sid + auth_token via
CredentialStore / env"}` rather than crashing.

## Phone number formats

All destination / sender numbers are validated locally **before** the
network call, both to catch typos early and to avoid burning billable
round-trips on malformed input:

- SMS / Voice: E.164 only (`+<country_code><digits>`, max 15 digits).
- WhatsApp: `whatsapp:+<country_code><digits>`.

Both sides of every send / call are validated with the same rule.

## Usage via Concinno `ToolRegistry`

When the consumer sets `CONCINNO_LOAD_PLUGINS=1`, the default registry
auto-mounts every mobile tool:

```python
import os
os.environ["CONCINNO_LOAD_PLUGINS"] = "1"

from concinno.tools.registry import get_default_registry

reg = get_default_registry()
assert {"TwilioSms", "TwilioWhatsApp", "TwilioVoiceCall"} <= set(
    reg.list_deferred()
)

sms = reg.get("TwilioSms")
sms.call(
    action="send",
    to="+14155551234",
    from_="+14155550000",
    body="Hello from Concinno",
)
```

## Direct Python usage

```python
from concinno_skills_mobile import (
    TwilioSms,
    TwilioWhatsApp,
    TwilioVoiceCall,
)

TwilioSms().call(
    action="send",
    to="+14155551234",
    from_="+14155550000",
    body="hi",
)

TwilioWhatsApp().call(
    action="send",
    to="whatsapp:+14155551234",
    from_="whatsapp:+14155550000",
    body="hi",
)

TwilioVoiceCall().call(
    action="create",
    to="+14155551234",
    from_="+14155550000",
    twiml="<Response><Say>Hi from Concinno</Say></Response>",
)
```

All tools return `{"ok": True, ...}` on success or `{"error": "..."}`
on failure — same shape as other Concinno built-in tools. No
exceptions escape the `call()` surface.

## Concurrency

All three tools set `is_concurrency_safe = False`. Twilio rate limits
(per-from-number for SMS; per-subaccount for voice; per-sender for
WhatsApp) make serial dispatch the sane default; Concinno's scheduler
will honour this automatically.

## License

Apache-2.0. See `LICENSE` in the Concinno monorepo.
