Metadata-Version: 2.4
Name: piopiy-ai
Version: 0.5.1
Summary: 📞 Telephonic-Grade Voice AI — 🌐 WebRTC-ready framework
License-Expression: BSD-2-Clause
Project-URL: Source, https://github.com/telecmi/agents
Project-URL: Website, https://piopiy.com
Keywords: telecmi,audio,telephone,ai,telephone-ai
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiofiles<25,>=24.1.0
Requires-Dist: aiohttp<4,>=3.11.12
Requires-Dist: audioop-lts~=0.2.1; python_version >= "3.13"
Requires-Dist: docstring_parser~=0.16
Requires-Dist: loguru~=0.7.3
Requires-Dist: Markdown<4,>=3.7
Requires-Dist: nltk<4,>=3.9.1
Requires-Dist: numpy<3,>=1.26.4
Requires-Dist: Pillow<12,>=11.1.0
Requires-Dist: protobuf~=5.29.3
Requires-Dist: pydantic<3,>=2.10.6
Requires-Dist: livekit~=1.0.13
Requires-Dist: livekit-api~=1.0.5
Requires-Dist: tenacity<10.0.0,>=8.2.3
Requires-Dist: pyloudnorm~=0.1.1
Requires-Dist: resampy~=0.4.3
Requires-Dist: soxr~=0.5.0
Requires-Dist: openai<3,>=1.74.0
Requires-Dist: wait_for2>=0.4.1; python_version < "3.12"
Requires-Dist: numba==0.61.2
Requires-Dist: python-socketio[asyncio_client]>=5.13.0
Provides-Extra: aic
Requires-Dist: aic-sdk~=1.2.0; extra == "aic"
Provides-Extra: anthropic
Requires-Dist: anthropic~=0.49.0; extra == "anthropic"
Provides-Extra: assemblyai
Requires-Dist: piopiy-ai[websockets-base]; extra == "assemblyai"
Provides-Extra: asyncai
Requires-Dist: piopiy-ai[websockets-base]; extra == "asyncai"
Provides-Extra: aws
Requires-Dist: aioboto3~=15.5.0; extra == "aws"
Requires-Dist: piopiy-ai[websockets-base]; extra == "aws"
Provides-Extra: aws-nova-sonic
Requires-Dist: aws_sdk_bedrock_runtime~=0.2.0; python_version >= "3.12" and extra == "aws-nova-sonic"
Provides-Extra: azure
Requires-Dist: azure-cognitiveservices-speech~=1.42.0; extra == "azure"
Provides-Extra: cartesia
Requires-Dist: cartesia~=2.0.3; extra == "cartesia"
Requires-Dist: piopiy-ai[websockets-base]; extra == "cartesia"
Provides-Extra: cerebras
Provides-Extra: daily
Requires-Dist: daily-python~=0.23.0; extra == "daily"
Provides-Extra: deepgram
Requires-Dist: deepgram-sdk~=4.7.0; extra == "deepgram"
Requires-Dist: piopiy-ai[websockets-base]; extra == "deepgram"
Provides-Extra: deepseek
Provides-Extra: elevenlabs
Requires-Dist: piopiy-ai[websockets-base]; extra == "elevenlabs"
Provides-Extra: fal
Requires-Dist: fal-client~=0.5.9; extra == "fal"
Provides-Extra: fireworks
Provides-Extra: fish
Requires-Dist: ormsgpack~=1.7.0; extra == "fish"
Requires-Dist: piopiy-ai[websockets-base]; extra == "fish"
Provides-Extra: gladia
Requires-Dist: piopiy-ai[websockets-base]; extra == "gladia"
Provides-Extra: google
Requires-Dist: google-cloud-speech<3,>=2.33.0; extra == "google"
Requires-Dist: google-cloud-texttospeech<3,>=2.31.0; extra == "google"
Requires-Dist: google-genai<2,>=1.51.0; extra == "google"
Requires-Dist: piopiy-ai[websockets-base]; extra == "google"
Provides-Extra: gradium
Requires-Dist: piopiy-ai[websockets-base]; extra == "gradium"
Provides-Extra: grok
Provides-Extra: groq
Requires-Dist: groq~=0.23.0; extra == "groq"
Provides-Extra: gstreamer
Requires-Dist: pygobject~=3.50.0; extra == "gstreamer"
Provides-Extra: heygen
Requires-Dist: livekit>=1.0.13; extra == "heygen"
Requires-Dist: piopiy-ai[websockets-base]; extra == "heygen"
Provides-Extra: hume
Requires-Dist: hume>=0.11.2; extra == "hume"
Provides-Extra: inworld
Provides-Extra: koala
Requires-Dist: pvkoala~=2.0.3; extra == "koala"
Provides-Extra: krisp
Requires-Dist: piopiy-ai-krisp~=0.4.0; extra == "krisp"
Provides-Extra: langchain
Requires-Dist: langchain~=0.3.20; extra == "langchain"
Requires-Dist: langchain-community~=0.3.20; extra == "langchain"
Requires-Dist: langchain-openai~=0.3.9; extra == "langchain"
Provides-Extra: livekit
Requires-Dist: livekit~=1.0.13; extra == "livekit"
Requires-Dist: livekit-api~=1.0.5; extra == "livekit"
Requires-Dist: tenacity<10.0.0,>=8.2.3; extra == "livekit"
Requires-Dist: pyjwt>=2.10.1; extra == "livekit"
Provides-Extra: lmnt
Requires-Dist: piopiy-ai[websockets-base]; extra == "lmnt"
Provides-Extra: local
Requires-Dist: pyaudio~=0.2.14; extra == "local"
Provides-Extra: local-smart-turn
Requires-Dist: coremltools>=8.0; extra == "local-smart-turn"
Requires-Dist: transformers; extra == "local-smart-turn"
Requires-Dist: torch<3,>=2.5.0; extra == "local-smart-turn"
Requires-Dist: torchaudio<3,>=2.5.0; extra == "local-smart-turn"
Provides-Extra: local-smart-turn-v3
Requires-Dist: transformers; extra == "local-smart-turn-v3"
Requires-Dist: onnxruntime<2,>=1.20.1; extra == "local-smart-turn-v3"
Provides-Extra: mcp
Requires-Dist: mcp[cli]<2,>=1.11.0; extra == "mcp"
Provides-Extra: mem0
Requires-Dist: mem0ai~=0.1.94; extra == "mem0"
Provides-Extra: mistral
Provides-Extra: mlx-whisper
Requires-Dist: mlx-whisper~=0.4.2; extra == "mlx-whisper"
Provides-Extra: moondream
Requires-Dist: accelerate~=1.10.0; extra == "moondream"
Requires-Dist: einops~=0.8.0; extra == "moondream"
Requires-Dist: pyvips[binary]~=3.0.0; extra == "moondream"
Requires-Dist: timm~=1.0.13; extra == "moondream"
Requires-Dist: transformers>=4.48.0; extra == "moondream"
Provides-Extra: neuphonic
Requires-Dist: piopiy-ai[websockets-base]; extra == "neuphonic"
Provides-Extra: noisereduce
Requires-Dist: noisereduce~=3.0.3; extra == "noisereduce"
Provides-Extra: nvidia
Requires-Dist: nvidia-riva-client~=2.21.1; extra == "nvidia"
Provides-Extra: openai
Requires-Dist: piopiy-ai[websockets-base]; extra == "openai"
Provides-Extra: rnnoise
Requires-Dist: pyrnnoise~=0.4.1; extra == "rnnoise"
Provides-Extra: openpipe
Requires-Dist: openpipe<6,>=4.50.0; extra == "openpipe"
Provides-Extra: openrouter
Provides-Extra: perplexity
Provides-Extra: playht
Requires-Dist: piopiy-ai[websockets-base]; extra == "playht"
Provides-Extra: qwen
Provides-Extra: remote-smart-turn
Provides-Extra: rime
Requires-Dist: piopiy-ai[websockets-base]; extra == "rime"
Provides-Extra: riva
Requires-Dist: piopiy-ai[nvidia]; extra == "riva"
Provides-Extra: runner
Requires-Dist: python-dotenv<2.0.0,>=1.0.0; extra == "runner"
Requires-Dist: uvicorn<1.0.0,>=0.32.0; extra == "runner"
Requires-Dist: fastapi<0.122.0,>=0.115.6; extra == "runner"
Requires-Dist: piopiy-ai-small-webrtc-prebuilt>=1.0.0; extra == "runner"
Provides-Extra: sagemaker
Requires-Dist: aws_sdk_sagemaker_runtime_http2; python_version >= "3.12" and extra == "sagemaker"
Provides-Extra: sambanova
Provides-Extra: sarvam
Requires-Dist: sarvamai==0.1.21; extra == "sarvam"
Requires-Dist: piopiy-ai[websockets-base]; extra == "sarvam"
Provides-Extra: sentry
Requires-Dist: sentry-sdk<3,>=2.28.0; extra == "sentry"
Provides-Extra: silero
Requires-Dist: onnxruntime<2,>=1.20.1; extra == "silero"
Provides-Extra: simli
Requires-Dist: simli-ai~=1.0.3; extra == "simli"
Provides-Extra: soniox
Requires-Dist: piopiy-ai[websockets-base]; extra == "soniox"
Provides-Extra: soundfile
Requires-Dist: soundfile~=0.13.1; extra == "soundfile"
Provides-Extra: speechmatics
Requires-Dist: speechmatics-voice[smart]>=0.2.4; extra == "speechmatics"
Provides-Extra: strands
Requires-Dist: strands-agents<2,>=1.9.1; extra == "strands"
Provides-Extra: tavus
Provides-Extra: together
Provides-Extra: tracing
Requires-Dist: opentelemetry-sdk>=1.33.0; extra == "tracing"
Requires-Dist: opentelemetry-api>=1.33.0; extra == "tracing"
Requires-Dist: opentelemetry-instrumentation>=0.54b0; extra == "tracing"
Provides-Extra: ultravox
Requires-Dist: piopiy-ai[websockets-base]; extra == "ultravox"
Provides-Extra: webrtc
Requires-Dist: aiortc<2,>=1.13.0; extra == "webrtc"
Requires-Dist: opencv-python<5,>=4.11.0.86; extra == "webrtc"
Provides-Extra: websocket
Requires-Dist: piopiy-ai[websockets-base]; extra == "websocket"
Requires-Dist: fastapi<0.122.0,>=0.115.6; extra == "websocket"
Provides-Extra: websockets-base
Requires-Dist: websockets<16.0,>=13.1; extra == "websockets-base"
Provides-Extra: whisper
Requires-Dist: faster-whisper~=1.1.1; extra == "whisper"
Dynamic: license-file

# PIOPIY AI
Build Telephonic-Grade Voice AI — WebRTC-Ready Framework

Piopiy AI is an open-source, telephony-grade framework for building real-time voice agents that blend large language models (LLM), automatic speech recognition (ASR), and text-to-speech (TTS) engines. Purchase numbers, configure agents, and let Piopiy handle call routing, audio streaming, and connectivity while you focus on conversation design. Combine cloud or open-source providers to tailor the voice stack to your latency, privacy, and cost targets.

## Installation

Requires Python 3.10+.

```bash
pip install piopiy-ai
```

To install extras for the providers you plan to use:

```bash
pip install "piopiy-ai[cartesia,deepgram,openai]"
```

Set provider API keys in the environment (for example, `OPENAI_API_KEY`).

## Quick Example

```python
import asyncio
import os

from piopiy.agent import Agent
from piopiy.voice_agent import VoiceAgent
from piopiy.services.deepgram.stt import DeepgramSTTService
from piopiy.services.openai.llm import OpenAILLMService
from piopiy.services.cartesia.tts import CartesiaTTSService


async def create_session():
    voice_agent = VoiceAgent(
        instructions="You are an advanced voice AI.",
        greeting="Hello! How can I help you today?",
    )

    stt = DeepgramSTTService(api_key=os.getenv("DEEPGRAM_API_KEY"))
    llm = OpenAILLMService(api_key=os.getenv("OPENAI_API_KEY"))
    tts = CartesiaTTSService(api_key=os.getenv("CARTESIA_API_KEY"))

    await voice_agent.Action(stt=stt, llm=llm, tts=tts)
    await voice_agent.start()


async def main():
    agent = Agent(
        agent_id=os.getenv("AGENT_ID"),
        agent_token=os.getenv("AGENT_TOKEN"),
        create_session=create_session,
    )
    await agent.connect()


if __name__ == "__main__":
    asyncio.run(main())
```

## Providers

| Provider | Categories |
|---------|------------|
| [Anthropic](docs/llm/anthropic.md) | LLM |
| [AssemblyAI](docs/stt/assemblyai.md) | STT |
| [AsyncAI](docs/tts/asyncai.md) | TTS |
| [AWS](docs/llm/aws.md) | LLM, STT, TTS |
| [Azure](docs/llm/azure.md) | LLM, STT, TTS |
| [Cartesia](docs/stt/cartesia.md) | STT, TTS |
| [Cerebras](docs/llm/cerebras.md) | LLM |
| [Deepgram](docs/stt/deepgram.md) | STT, TTS |
| [DeepSeek](docs/llm/deepseek.md) | LLM |
| [ElevenLabs](docs/tts/elevenlabs.md) | TTS |
| [Fal](docs/stt/fal.md) | STT |
| [Fireworks](docs/llm/fireworks.md) | LLM |
| [Fish](docs/tts/fish.md) | TTS |
| [Gladia](docs/stt/gladia.md) | STT |
| [Google](docs/llm/google.md) | LLM, STT, TTS |
| [Grok](docs/llm/grok.md) | LLM |
| [Groq](docs/llm/groq.md) | LLM, STT, TTS |
| [Inworld](docs/tts/inworld.md) | TTS |
| [LMNT](docs/tts/lmnt.md) | TTS |
| [Mistral](docs/llm/mistral.md) | LLM |
| [Minimax](docs/tts/minimax.md) | TTS |
| [Neuphonic](docs/tts/neuphonic.md) | TTS |
| [NIM](docs/llm/nim.md) | LLM |
| [Ollama](docs/llm/ollama.md) | LLM |
| [OpenAI](docs/llm/openai.md) | LLM, STT, TTS |
| [OpenPipe](docs/llm/openpipe.md) | LLM |
| [OpenRouter](docs/llm/openrouter.md) | LLM |
| [Perplexity](docs/llm/perplexity.md) | LLM |
| [Piper](docs/tts/piper.md) | TTS |
| [PlayHT](docs/tts/playht.md) | TTS |
| [Qwen](docs/llm/qwen.md) | LLM |
| [Rime](docs/tts/rime.md) | TTS |
| [Riva](docs/stt/riva.md) | STT, TTS |
| [SambaNova](docs/llm/sambanova.md) | LLM, STT |
| [Sarvam](docs/tts/sarvam.md) | TTS |
| [Soniox](docs/stt/soniox.md) | STT |
| [Speechmatics](docs/stt/speechmatics.md) | STT |
| [TeleCMI](docs/transport/telecmi.md) | Transport |
| [Together](docs/llm/together.md) | LLM |
| [Ultravox](docs/stt/ultravox.md) | STT |
| [Whisper](docs/stt/whisper.md) | STT |
| [XTTS](docs/tts/xtts.md) | TTS |

### Interruption & Silero VAD

Enable interruption handling with Silero voice activity detection:

```bash
pip install "piopiy-ai[silero]"
```

Silero VAD detects speech during playback, allowing callers to interrupt the agent.

## Open-Source Voice Stack (LLM + ASR + TTS)

Pair Piopiy’s realtime orchestration with open-source engines across the full speech stack:

| Layer | Default | Alternatives |
|-------|---------|--------------|
| **LLM** | [Ollama](https://ollama.ai) running `llama3.1` (or another local model) | [LM Studio](https://lmstudio.ai), [GPT4All](https://gpt4all.io) via Ollama-compatible APIs |
| **ASR** | `WhisperSTTService` with Whisper small/medium models | [`mlx-whisper`](https://github.com/ml-explore/mlx-examples/tree/main/whisper) for Apple silicon |
| **TTS** | `ChatterboxTTSService` pointed at a self-hosted [Chatterbox TTS](https://github.com/piopiy-ai/chatterbox-tts) server | Piper, XTTS, Kokoro |

Install the optional dependencies and runtimes:

```bash
pip install "piopiy-ai[whisper]"
# Install and run Ollama separately: https://ollama.ai
# Start the Chatterbox TTS WebSocket server (https://github.com/piopiy-ai/chatterbox-tts)
```

Example session factory using the open-source trio:

```python
from piopiy.voice_agent import VoiceAgent
from piopiy.services.whisper.stt import WhisperSTTService
from piopiy.services.ollama.llm import OLLamaLLMService
from piopiy.services.opensource.chatterbox.tts import ChatterboxTTSService


async def create_session():
    voice_agent = VoiceAgent(
        instructions="You are a helpful local-first voice assistant.",
        greeting="Hi there! Running fully on open-source models today.",
    )

    stt = WhisperSTTService(model="small")
    llm = OLLamaLLMService(model="llama3.1")  # points to your local Ollama runtime
    tts = ChatterboxTTSService(base_url="ws://localhost:6078")

    await voice_agent.Action(stt=stt, llm=llm, tts=tts, vad=True)
    await voice_agent.start()
```

Swap in other open-source providers such as Piper, XTTS, or Kokoro for TTS, and adjust the Chatterbox base URL or voice ID for your deployment. You can also run Whisper on Apple silicon with the `mlx-whisper` extra. Piopiy's abstraction layer lets you mix these with managed services whenever needed.

## Telephony Integration

Connect phone calls in minutes using the Piopiy dashboard:

1. Sign in at [dashboard.piopiy.com](https://dashboard.piopiy.com) and purchase a phone number.
2. Create a voice AI agent to receive `AGENT_ID` and `AGENT_TOKEN`.
3. Use those credentials with the SDK for instant connectivity.

No SIP setup or third-party telephony vendors are required—Piopiy handles the calls so you can focus on your agent logic.

Thanks to Pipecat for making client SDK implementation easy.

