Metadata-Version: 2.5
Name: phound
Version: 0.3.1
Summary: Phound SDK
Project-URL: Homepage, https://bot-sdk.phound.app
Project-URL: Documentation, https://bot-sdk.phound.app
Project-URL: Changelog, https://bot-sdk.phound.app/changelog/
Author-email: Denys Varenyk <dvarenyk@carrierx.com>, Anatoliy Kachan <akachan@freeconferencecall.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT 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: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: pillow>=10.3.0
Requires-Dist: python-dotenv==1.0.1
Requires-Dist: requests>=2.34.2
Description-Content-Type: text/markdown

# Phound SDK

[![PyPI](https://img.shields.io/pypi/v/phound.svg)](https://pypi.org/project/phound/)
[![Python](https://img.shields.io/pypi/pyversions/phound.svg)](https://pypi.org/project/phound/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/badge/docs-bot--sdk.phound.app-1f6feb.svg)](https://bot-sdk.phound.app)

With this Python SDK, you can make chatbots and automate voice calls on the
[Phound](https://phound.app) messaging platform.

You write handler classes. The SDK runs one instance of your handler for each
chat and for each call, and calls its methods when events arrive. You do not
deploy a server, expose a webhook endpoint or write an event loop.
`start_listen_events()` blocks, and all other work occurs in your callbacks.

## What you can build

- **Chatbots** in private and group chats: text, attachments, quotes,
  `@mentions`, typing indicators, HTML and Markdown format, and chat history.
- **SMS to and from plain phone numbers**, also for people with no Phound
  account. Resolve the number to its persona on the platform, then send text
  messages to that persona.
- **Voice bots**: answer, reject or make calls, play audio (pause, resume,
  seek), and record the call in chunks during the call.
- **Realtime voice agents**: stream the call audio through a websocket to an AI
  service, and speak its reply into the call. Send and receive DTMF.
- **Voice messages**, with the transcription from the platform.

## Install

```bash
uv add phound      # or: pip install phound
```

You need Python 3.10 or later. Python 3.10 is tested but deprecated: on it,
`import phound` gives a `DeprecationWarning`. A future minor release will
need Python 3.11 or later.

## Quickstart

Put your token in a `.env` file in your project directory:

```
TOKEN=<token>
```

To get a token, ask the **Support Bot**. It is at the bottom of the Home page
of the Phound app.

The `TOKEN` line is all the configuration that the SDK needs. To reply to SMS,
answer phone calls or make outgoing calls, read
[Configuration](https://bot-sdk.phound.app/configuration/#getting-a-token).

```python
import time

from phound import Phound
from phound.handlers import BaseChatHandler


class ChatHandler(BaseChatHandler):
    def on_message(self, message):
        self.show_typing()
        time.sleep(1)
        self.send_message(f"You said: {message.text}")


if __name__ == "__main__":
    with Phound() as phound:
        phound.register_chat_handler(ChatHandler)
        phound.start_listen_events()
```

Run the script. Then send a message to the bot from the Phound app. The bot
replies.

## Three important things before you start

**The SDK makes the handlers. You do not make them.** Declare each dependency
of a handler as a keyword-only parameter. Then register
`functools.partial(ChatHandler, kb=kb)`. All instances of the handler share the
bound value, so the value must be thread-safe.
→ [Passing dependencies to handlers](https://bot-sdk.phound.app/usage/#passing-dependencies-to-handlers)

**Use the blocking methods only on the handler's own thread.** If you call
`send_message()`, `get_history()`, `lookup_phone_number()` or `open_chat()`
from a different thread, the method raises `ChatError` and sends nothing. On
other threads, use `send_message_nowait()`. It does not wait, and it is safe
on all threads.
→ [Usage](https://bot-sdk.phound.app/usage/)

**A caller on a plain phone has only a number, not an account.** In a
one-to-one call with that caller, the chat of the call *is* the SMS chat with
the caller. Thus, `self.chat.send_message_nowait(text)` reaches the phone with
no lookup. In other cases, resolve the number with `lookup_phone_number()` and
open the chat one time. Then send by `persona_uid`.
→ [Reaching someone by phone number](https://bot-sdk.phound.app/usage/#reaching-someone-by-phone-number)

## Documentation

The full documentation is at **[bot-sdk.phound.app](https://bot-sdk.phound.app)**.

| | |
|---|---|
| [Configuration](https://bot-sdk.phound.app/configuration/) | The `TOKEN`, logging, and what the SDK logs at each level |
| [Usage](https://bot-sdk.phound.app/usage/) | A complete chatbot, handler dependencies, and how to reach a person by phone number |
| [Examples](https://bot-sdk.phound.app/examples/) | Scripts that you can run: chat basics, chat patterns, call basics, an AI chatbot, an answering machine, realtime audio, a voice agent, SMS to a PSTN caller, an outgoing call |
| [API Reference](https://bot-sdk.phound.app/reference/) | `Phound`, the two handler base classes, all events and exceptions |
| [Text helpers](https://bot-sdk.phound.app/text-helpers/) | `bold`, `italic`, `underline`, `mention` |
| [Changelog](https://bot-sdk.phound.app/changelog/) | The changes in each release, and how to migrate |

## Versioning

The SDK version is `0.x`, so a **minor release can contain breaking changes**
([SemVer puts major version zero outside the compatibility
guarantee](https://semver.org/spec/v2.0.0.html#spec-item-4)). The changelog
lists each breaking change with what to do instead. Before the SDK removes a
feature, the SDK deprecates it, with a warning at runtime, for a minimum of one
minor release.

To migrate without surprises:

1. Pin `0.3.*`.
2. Upgrade.
3. Read your own warnings.

## Support

`phound` is developed in a private repository. The SDK and its documentation
are public, but the source is not open for contributions from outside.

For a bug or a feature request, send an email to
[support@phound.app](mailto:support@phound.app). For the information to
include, see [Feedback](https://bot-sdk.phound.app/feedback/). This command
gives the SDK version:

```bash
python -c "from importlib.metadata import version; print(version('phound'))"
```

## License

MIT. See [LICENSE](LICENSE).
