Metadata-Version: 2.4
Name: voicematic
Version: 0.4.0
Summary: A vendor-neutral phone voice agent: a telephony transport in, a voice engine, a brain with tools and call control, each part from the vendor you choose.
Author: Flowmatic, UniForceMusic
License-Expression: MIT
Project-URL: Homepage, https://github.com/Flowmatic-AI/flowmatic-toolkit
Project-URL: Repository, https://github.com/Flowmatic-AI/flowmatic-toolkit
Project-URL: Documentation, https://github.com/Flowmatic-AI/flowmatic-toolkit/tree/main/packages/python/voicematic/project/docs
Project-URL: Issues, https://github.com/Flowmatic-AI/flowmatic-toolkit/issues
Keywords: voice,agent,telephony,genesys,audiohook,openai,anthropic,mistral,elevenlabs,deepgram,cartesia,azure,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: openai
Requires-Dist: openai[realtime]>=3.19; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=1.8; extra == "anthropic"
Provides-Extra: mistral
Requires-Dist: mistralai>=2.10; extra == "mistral"
Provides-Extra: elevenlabs
Requires-Dist: elevenlabs>=2.70; extra == "elevenlabs"
Provides-Extra: deepgram
Requires-Dist: deepgram-sdk>=7.11; extra == "deepgram"
Provides-Extra: cartesia
Requires-Dist: cartesia>=4.2; extra == "cartesia"
Provides-Extra: azure
Requires-Dist: azure-cognitiveservices-speech>=1.52; extra == "azure"
Provides-Extra: mcp
Requires-Dist: mcp>=2.2; extra == "mcp"
Provides-Extra: genesys
Requires-Dist: httpx>=0.28; extra == "genesys"
Provides-Extra: testing
Requires-Dist: websockets>=15; extra == "testing"
Provides-Extra: langchain
Requires-Dist: langchain-core>=1.6; extra == "langchain"
Requires-Dist: langchain>=1.4; extra == "langchain"
Provides-Extra: settings
Requires-Dist: pydantic-settings>=2.10; extra == "settings"
Provides-Extra: all
Requires-Dist: openai[realtime]>=3.19; extra == "all"
Requires-Dist: anthropic>=1.8; extra == "all"
Requires-Dist: mistralai>=2.10; extra == "all"
Requires-Dist: elevenlabs>=2.70; extra == "all"
Requires-Dist: deepgram-sdk>=7.11; extra == "all"
Requires-Dist: cartesia>=4.2; extra == "all"
Requires-Dist: azure-cognitiveservices-speech>=1.52; extra == "all"
Requires-Dist: mcp>=2.2; extra == "all"
Requires-Dist: httpx>=0.28; extra == "all"
Requires-Dist: websockets>=15; extra == "all"
Requires-Dist: langchain-core>=1.6; extra == "all"
Requires-Dist: langchain>=1.4; extra == "all"
Requires-Dist: pydantic-settings>=2.10; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: mypy>=2.0; extra == "dev"
Requires-Dist: ruff>=0.16; extra == "dev"
Requires-Dist: openai[realtime]>=3.19; extra == "dev"
Requires-Dist: anthropic>=1.8; extra == "dev"
Requires-Dist: mistralai>=2.10; extra == "dev"
Requires-Dist: elevenlabs>=2.70; extra == "dev"
Requires-Dist: deepgram-sdk>=7.11; extra == "dev"
Requires-Dist: cartesia>=4.2; extra == "dev"
Requires-Dist: azure-cognitiveservices-speech>=1.52; extra == "dev"
Requires-Dist: mcp>=2.2; extra == "dev"
Requires-Dist: httpx>=0.28; extra == "dev"
Requires-Dist: websockets>=15; extra == "dev"
Requires-Dist: langchain-core>=1.6; extra == "dev"
Requires-Dist: langchain>=1.4; extra == "dev"
Requires-Dist: langgraph>=1.2; extra == "dev"
Requires-Dist: pydantic-settings>=2.10; extra == "dev"
Dynamic: license-file

# voicematic

A phone voice agent, assembled from independent parts: a telephony transport
brings the call in (Genesys Cloud AudioHook out of the box), a voice engine
hears and speaks, a brain with tools does the thinking, and call control hands
the call back to the platform for a transfer. Each AI role picks its vendor:
OpenAI, Anthropic and Mistral are built in, and for
ears and mouth also ElevenLabs, Deepgram, Cartesia and Azure AI Speech; and any vendor that speaks the
OpenAI or Anthropic protocol, or has a LangChain integration, is configuration.

```bash
pip install "voicematic[openai]"        # or [anthropic], [mistral], [elevenlabs], [deepgram], [cartesia], [azure], [langchain], [settings], [mcp], [genesys], [testing], [all]
```

The core is standard library only. Each vendor's SDK is an extra and loads only
when that provider is used.

```python
from fastapi import FastAPI, WebSocket

from voicematic import DUTCH, AgentProfile, VoiceAgent
from voicematic.telephony import StarletteWebSocket
from voicematic.telephony.genesys import AudioHookTransport
from voicematic.voice import EchoEngine

agent = VoiceAgent(
    AgentProfile(
        name="Voorbeeld",
        persona="Je bent de telefonische assistent van Voorbeeld BV.",
        instructions="Beantwoord vragen kort en eerlijk.",
        greeting="Goedendag, waarmee kan ik u helpen?",
        language=DUTCH,
    ),
    engine=EchoEngine,
)

app = FastAPI()


@app.websocket("/audiohook")
async def audiohook(ws: WebSocket) -> None:
    await ws.accept()
    await agent.handle(AudioHookTransport(StarletteWebSocket(ws), languages=[agent.profile.language.tag]))
```

`EchoEngine` needs no model: two tones, then the caller's own audio back. Swap
it for a speech-to-speech engine (`voicematic.providers.openai.GPTLiveEngine`)
or a `PipelineEngine` of ears, brain and mouth from any vendor.

## Swappable components

Every part is an interface with built-in implementations. Your own subclass,
or an adapter around a system you already have, slots in the same way:

| Part | Interface | Built in | Bring your own |
|---|---|---|---|
| Telephony | `TransportABC`, `CallControlABC` | Genesys AudioHook, Architect flow and Platform API transfers | subclass |
| Voice engine | `VoiceEngineABC` | `PipelineEngine`, GPT-Live, gpt-realtime, `EchoEngine` | subclass, or `adapters.voicebot` for an existing voice bot |
| Turn detection | `TurnDetectorABC` | `EnergyTurnDetector` | subclass (a VAD, a semantic end-of-turn model) |
| Brain | `ReasonerABC` | `ToolLoopReasoner`, `CallableReasoner` | subclass, an async function, or `adapters.langchain` for an existing agent |
| Chat model | `ChatModelABC` | OpenAI, OpenAI-compatible, Anthropic, Mistral; LangChain as the fallback for any other vendor | subclass, or `adapters.langchain` for any LangChain model |
| Ears, mouth | `SpeechToTextABC`, `TextToSpeechABC` | OpenAI, Mistral, ElevenLabs, Deepgram, Cartesia, Azure | subclass |
| Tools | `Tool`, `ToolRegistry` | MCP, the transfer tool | a `Tool`, or LangChain tools via `from_langchain_tools` |
| Prompts | `PromptsABC` | `DefaultPrompts` | subclass |

A LangChain agent you already have, with its own tools and memory, as the brain:

```python
from langgraph.prebuilt import create_react_agent

from voicematic import VoiceAgent
from voicematic.adapters.langchain import LangChainAgentReasoner

brain = LangChainAgentReasoner(
    # Called once per call with that call's tools, the transfer tool included.
    lambda tools: create_react_agent(model, [*my_tools, *tools], checkpointer=memory),
    history="latest",  # the agent remembers the call itself, keyed by the call id
    stream=True,       # speak sentence by sentence as the agent writes
)
agent = VoiceAgent.pipeline(profile, stt=ears, brain=brain, tts=mouth)
```

Just a LangChain model, with voicematic's prompt, tools and tool loop:
`brain=LangChainChatModel(ChatAnthropic(...))`.

A voice bot you already have, behind the telephony (pacing, format
conversion, transfers, hand-back timing, drain on deploy):

```python
import websockets

from voicematic import VoiceAgent
from voicematic.adapters.voicebot import JsonBotProtocol, VoiceBotEngine, WebSocketVoiceBot


async def connect(session):
    return await websockets.connect("wss://bot.example.com/call")


agent = VoiceAgent(profile, engine=VoiceBotEngine.factory(lambda: WebSocketVoiceBot(connect, JsonBotProtocol())))
```

A bot with a wire protocol of its own subclasses `BotProtocolABC`, and one that
is not a websocket implements `VoiceBotABC`. The bot reaches the agent's tools,
the transfer tool included, through tool-call events.

## Packages

| Package | What it holds |
|---|---|
| `voicematic` | `VoiceAgent` (`.pipeline`, `.echo`), `CallSession`, `AgentProfile`, `Tool`, `drain_on_signals` |
| `voicematic.telephony` | `TransportABC`, `CallControlABC`; `genesys/` for AudioHook, Architect flow and Platform API transfers |
| `voicematic.voice` | `VoiceEngineABC`, `PipelineEngine`, `EchoEngine`, `TurnDetectorABC`, `EnergyTurnDetector`, `TurnHints` |
| `voicematic.reasoning` | `ReasonerABC`, `ToolLoopReasoner`, `CallableReasoner`, `as_reasoner` |
| `voicematic.llm` / `speech` | `ChatModelABC`, `SpeechToTextABC`, `TextToSpeechABC` and the neutral conversation types |
| `voicematic.providers` | the `PROVIDERS` registry; `openai/`, `anthropic/`, `mistral/`, `elevenlabs/`, `deepgram/`, `cartesia/`, `azure/`, and `langchain` as the fallback brain |
| `voicematic.adapters` | existing systems: `langchain/` (models, agents, tools), `voicebot/` (a voice bot of your own) |
| `voicematic.tools` | tool registry, parallel tool calls, the transfer tool, MCP |
| `voicematic.prompts` | `AgentProfile`, `Language`, `PromptsABC`, `DefaultPrompts` |
| `voicematic.audio` | formats, G.711, resampling, WAV |
| `voicematic.settings` | `VoicematicSettings`: the voice layer from environment variables (extra) |
| `voicematic.testing` | an AudioHook simulator (`python -m voicematic.testing`) and a browser test phone |

## Settings

`voicematic[settings]` adds `VoicematicSettings`, a pydantic `BaseSettings`
with only what it takes to build the voice engine from the environment:
`VOICE_ENGINE`, the vendor behind each role (`REASONING_*`, `STT_*`, `TTS_*`,
`VOICE_*`), the vendor keys and pipeline turn-taking. It checks all of them at
startup. A project subclasses it with its own settings:

```python
from pydantic_settings import SettingsConfigDict

from voicematic import VoiceAgent
from voicematic.settings import VoicematicSettings


class Settings(VoicematicSettings):
    model_config = SettingsConfigDict(env_file=".env")
    audiohook_api_key: str | None = None


settings = Settings()
agent = VoiceAgent(profile, engine=settings.engine_factory())
```

The pipeline's turn-taking (`PIPELINE_END_SILENCE`, `PIPELINE_FILLER_AFTER`,
`PIPELINE_FILLER_ON=silence|lookup`, `PIPELINE_DETAILS_END_SILENCE`,
`PIPELINE_ANSWER_GAP`) comes from the environment; what only the project knows
about its conversation goes in as code, `settings.engine_factory(hints=TurnHints(...))`:
whether the agent's last reply asked for details callers give in parts (the
next turn then waits `PIPELINE_DETAILS_END_SILENCE`), and whether what the
caller said will certainly be looked up (the "one moment" line then plays at
once).

Outside `voicematic.settings`, which the core never imports, the library reads
no environment and knows no application: profile and tools come from the
project. `tests/test_boundary.py` enforces that, and
that each vendor SDK or framework is imported only in its own `providers/<vendor>/` or
`adapters/<name>/`.

A complete application, with settings, a Dutch profile, tools, MCP, transfers,
Docker images and the full documentation, is in [`../project`](../project).

## Development

```bash
./test.sh                # ruff, mypy and pytest in .venv, with voicematic[dev] installed editable
./publish.sh             # the checks, a build, and an upload to PyPI (PYPI_API_KEY in .env)
```
