pipecat-piopiy 0.1.0__tar.gz

pipecat_piopiy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TeleCMI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pipecat_piopiy-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: pipecat-piopiy
+Version: 0.1.0
+Summary: Piopiy (TeleCMI) telephony for Pipecat voice agents: take calls, transfer them, hang up
+Author-email: TeleCMI <support@telecmi.com>
+License: MIT
+Project-URL: Homepage, https://piopiy.com
+Project-URL: Repository, https://github.com/telecmi/pipecat-piopiy
+Project-URL: Documentation, https://github.com/telecmi/pipecat-piopiy#readme
+Keywords: pipecat,voice,telephony,sip,piopiy,telecmi
+Classifier: Development Status :: 4 - Beta
+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: Topic :: Communications :: Telephony
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pipecat-ai[livekit]<2,>=1.8.0
+Requires-Dist: piopiy-agent>=1.0.0
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: example
+Requires-Dist: pipecat-ai[deepgram,livekit,openai,silero]<2,>=1.8.0; extra == "example"
+Requires-Dist: python-dotenv>=1.0; extra == "example"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Dynamic: license-file
+
+# pipecat-piopiy
+
+Piopiy telephony for [Pipecat](https://github.com/pipecat-ai/pipecat) voice
+agents. Your Pipecat bot takes real phone calls on the Piopiy platform by
+TeleCMI: calls the Piopiy API places, calls arriving on your numbers, and
+calls arriving from your PBX over SIP Connect. Mid-call it can transfer the
+caller to a human, warm or blind, and hang up.
+
+Piopiy bridges each call into a LiveKit room and hands your worker the room.
+Media runs through Pipecat's own `LiveKitTransport`; this package supplies the
+rest - taking the call, knowing who is calling, acting on the call, and hearing
+about transfers.
+
+**Tested with Pipecat v1.8.1.** Community-maintained by
+[TeleCMI](https://telecmi.com); not part of the Pipecat core.
+
+## Install
+
+```bash
+pip install pipecat-piopiy
+# for the example, with Deepgram + OpenAI + Silero VAD:
+pip install "pipecat-piopiy[example]"
+```
+
+Python 3.10+. Depends on `pipecat-ai[livekit]` and `piopiy-agent`, the
+framework-agnostic Piopiy worker SDK.
+
+## Use with a pipeline
+
+```python
+from pipecat_piopiy import PiopiyRunner, PiopiyCallControl, piopiy_tools
+from pipecat_piopiy.processors import PiopiyEventsProcessor
+
+async def bot(transport, call):
+    control = PiopiyCallControl(call)
+    tools = piopiy_tools(control, transfer_number="919876543210",
+                         transfer_caller_id="911203134087")
+
+    context = LLMContext(messages=[{"role": "system", "content": PROMPT}],
+                         tools=tools.schemas)
+    aggregators = LLMContextAggregatorPair(
+        context, user_params=LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer()))
+
+    pipeline = Pipeline([
+        transport.input(),
+        PiopiyEventsProcessor(call),      # transfer progress -> frames + narration
+        stt, aggregators.user(), llm, tts,
+        transport.output(), aggregators.assistant(),
+    ])
+    task = PipelineTask(pipeline)
+
+    @transport.event_handler("on_first_participant_joined")
+    async def on_caller_joined(_t, participant_id):
+        await task.queue_frames([LLMRunFrame()])
+
+    @transport.event_handler("on_participant_left")
+    async def on_caller_left(_t, participant_id, reason):
+        await task.cancel()
+
+    await PipelineRunner(handle_sigint=False).run(task)
+
+PiopiyRunner().run(bot)
+```
+
+`PiopiyRunner` connects to Piopiy as a worker for your agent, and for every
+call builds a `LiveKitTransport` pointed at the call's room and calls `bot`.
+It accepts the call when the transport connects, which is when the caller is
+bridged in. Use `PipelineRunner(handle_sigint=False)`: the worker owns the
+process signals.
+
+## Run the example
+
+```bash
+cd examples/foundational
+cp .env.example .env        # agent id, token, API base, transfer number, keys
+python 01_piopiy_agent.py
+```
+
+Then call your agent: place a call with `POST /v3/voice/ai/call`, ring one of
+your numbers mapped to the agent, or dial the agent id from a PBX registered
+over SIP Connect. Ask for a person to see a warm transfer, ask for "the billing
+line" to see a blind transfer, and say goodbye to see it hang up.
+
+## Configuration
+
+| variable | what |
+|---|---|
+| `PIOPIY_AGENT_ID` | the agent this worker serves, from the dashboard |
+| `PIOPIY_TOKEN` | the Bearer token, the same one that creates calls |
+| `PIOPIY_API_URL` | the platform's `/v3` base URL, as given in your account |
+| `PIOPIY_REGISTER` | optional; `host:port` of the worker register |
+| `PIOPIY_TLS` | optional; `false` to talk to the register without TLS (development) |
+| `PIOPIY_MAX_SESSIONS` | calls one process handles at once |
+
+## What the package gives you
+
+**`PiopiyCall`** - who is calling whom: `call_id`, `direction`, `from_number`,
+`to_number`, `agent_id`, `variables` from the create request, and
+`sip_account_id` on SIP Connect calls so one agent can tell your PBXs apart.
+
+**`PiopiyCallControl`** - actions on the live call over the Piopiy API:
+
+```python
+result  = await control.warm_transfer(to_number="9198...", transfer_summary="Refund on order A-1042")
+result  = await control.warm_transfer(sip_uri="sip:desk@pbx.example.com", sip_headers={"X-Ticket": "A-1042"})
+result  = await control.blind_transfer(to_number="9198...", caller_id="9112...")
+await control.hangup(reason="resolved")
+verdict = await control.wait_for_transfer(result.request_id)   # queued -> completed | failed
+```
+
+A warm transfer rings the human while the caller stays in conversation with
+the agent; on answer the caller is handed over and the agent leaves; if nobody
+answers the conversation simply continues. A blind transfer hands the caller
+over at once. One transfer at a time per call: a second one is refused with
+`PiopiyAPIError(409, "transfer_in_progress")` carrying the running transfer's
+`request_id`.
+
+**`piopiy_tools()`** - `transfer_call` and `end_call` as LLM function calls.
+Each `FunctionSchema` carries its handler, so advertising `tools.schemas` on
+the `LLMContext` is all the wiring. The destination is fixed in code by
+default; pass `allow_model_destination=True` to let the model choose a
+number, and `transfer_caller_id` for the DID to present, which SIP Connect
+calls require.
+
+**`PiopiyEventsProcessor`** - the platform pushes every transfer's progress
+into the call's room. The processor turns each message into a
+`PiopiyTransferStatusFrame` (`started`, `failed` with a reason, `completed`)
+and, by default, speaks it: "I'm connecting you now" as the target rings, an
+apology when it fails, plus a note into the LLM context so the model carries
+on sensibly. Pass `narrate=False` to handle the frames yourself. `completed`
+is best-effort: at that moment the agent is being removed from the call, and
+`on_participant_left` fires.
+
+## Notes
+
+- Every action uses the call's customer leg, which `PiopiyCall.call_id` is.
+- SIP Connect calls consume no phone number, so a transfer to a phone from one
+  needs `transfer_caller_id` (a DID you own).
+- Accept timing is handled for you: the runner accepts on `on_connected`, and
+  if the join missed the platform's deadline it cancels the bot so two agents
+  never share a call.
+- Pipecat changes quickly. This release is tested against v1.8.1; the pinned
+  range in `pyproject.toml` is `>=1.8,<2`.
+
+## License
+
+MIT. Copyright TeleCMI.

pipecat_piopiy-0.1.0/README.md

@@ -0,0 +1,147 @@
+# pipecat-piopiy
+
+Piopiy telephony for [Pipecat](https://github.com/pipecat-ai/pipecat) voice
+agents. Your Pipecat bot takes real phone calls on the Piopiy platform by
+TeleCMI: calls the Piopiy API places, calls arriving on your numbers, and
+calls arriving from your PBX over SIP Connect. Mid-call it can transfer the
+caller to a human, warm or blind, and hang up.
+
+Piopiy bridges each call into a LiveKit room and hands your worker the room.
+Media runs through Pipecat's own `LiveKitTransport`; this package supplies the
+rest - taking the call, knowing who is calling, acting on the call, and hearing
+about transfers.
+
+**Tested with Pipecat v1.8.1.** Community-maintained by
+[TeleCMI](https://telecmi.com); not part of the Pipecat core.
+
+## Install
+
+```bash
+pip install pipecat-piopiy
+# for the example, with Deepgram + OpenAI + Silero VAD:
+pip install "pipecat-piopiy[example]"
+```
+
+Python 3.10+. Depends on `pipecat-ai[livekit]` and `piopiy-agent`, the
+framework-agnostic Piopiy worker SDK.
+
+## Use with a pipeline
+
+```python
+from pipecat_piopiy import PiopiyRunner, PiopiyCallControl, piopiy_tools
+from pipecat_piopiy.processors import PiopiyEventsProcessor
+
+async def bot(transport, call):
+    control = PiopiyCallControl(call)
+    tools = piopiy_tools(control, transfer_number="919876543210",
+                         transfer_caller_id="911203134087")
+
+    context = LLMContext(messages=[{"role": "system", "content": PROMPT}],
+                         tools=tools.schemas)
+    aggregators = LLMContextAggregatorPair(
+        context, user_params=LLMUserAggregatorParams(vad_analyzer=SileroVADAnalyzer()))
+
+    pipeline = Pipeline([
+        transport.input(),
+        PiopiyEventsProcessor(call),      # transfer progress -> frames + narration
+        stt, aggregators.user(), llm, tts,
+        transport.output(), aggregators.assistant(),
+    ])
+    task = PipelineTask(pipeline)
+
+    @transport.event_handler("on_first_participant_joined")
+    async def on_caller_joined(_t, participant_id):
+        await task.queue_frames([LLMRunFrame()])
+
+    @transport.event_handler("on_participant_left")
+    async def on_caller_left(_t, participant_id, reason):
+        await task.cancel()
+
+    await PipelineRunner(handle_sigint=False).run(task)
+
+PiopiyRunner().run(bot)
+```
+
+`PiopiyRunner` connects to Piopiy as a worker for your agent, and for every
+call builds a `LiveKitTransport` pointed at the call's room and calls `bot`.
+It accepts the call when the transport connects, which is when the caller is
+bridged in. Use `PipelineRunner(handle_sigint=False)`: the worker owns the
+process signals.
+
+## Run the example
+
+```bash
+cd examples/foundational
+cp .env.example .env        # agent id, token, API base, transfer number, keys
+python 01_piopiy_agent.py
+```
+
+Then call your agent: place a call with `POST /v3/voice/ai/call`, ring one of
+your numbers mapped to the agent, or dial the agent id from a PBX registered
+over SIP Connect. Ask for a person to see a warm transfer, ask for "the billing
+line" to see a blind transfer, and say goodbye to see it hang up.
+
+## Configuration
+
+| variable | what |
+|---|---|
+| `PIOPIY_AGENT_ID` | the agent this worker serves, from the dashboard |
+| `PIOPIY_TOKEN` | the Bearer token, the same one that creates calls |
+| `PIOPIY_API_URL` | the platform's `/v3` base URL, as given in your account |
+| `PIOPIY_REGISTER` | optional; `host:port` of the worker register |
+| `PIOPIY_TLS` | optional; `false` to talk to the register without TLS (development) |
+| `PIOPIY_MAX_SESSIONS` | calls one process handles at once |
+
+## What the package gives you
+
+**`PiopiyCall`** - who is calling whom: `call_id`, `direction`, `from_number`,
+`to_number`, `agent_id`, `variables` from the create request, and
+`sip_account_id` on SIP Connect calls so one agent can tell your PBXs apart.
+
+**`PiopiyCallControl`** - actions on the live call over the Piopiy API:
+
+```python
+result  = await control.warm_transfer(to_number="9198...", transfer_summary="Refund on order A-1042")
+result  = await control.warm_transfer(sip_uri="sip:desk@pbx.example.com", sip_headers={"X-Ticket": "A-1042"})
+result  = await control.blind_transfer(to_number="9198...", caller_id="9112...")
+await control.hangup(reason="resolved")
+verdict = await control.wait_for_transfer(result.request_id)   # queued -> completed | failed
+```
+
+A warm transfer rings the human while the caller stays in conversation with
+the agent; on answer the caller is handed over and the agent leaves; if nobody
+answers the conversation simply continues. A blind transfer hands the caller
+over at once. One transfer at a time per call: a second one is refused with
+`PiopiyAPIError(409, "transfer_in_progress")` carrying the running transfer's
+`request_id`.
+
+**`piopiy_tools()`** - `transfer_call` and `end_call` as LLM function calls.
+Each `FunctionSchema` carries its handler, so advertising `tools.schemas` on
+the `LLMContext` is all the wiring. The destination is fixed in code by
+default; pass `allow_model_destination=True` to let the model choose a
+number, and `transfer_caller_id` for the DID to present, which SIP Connect
+calls require.
+
+**`PiopiyEventsProcessor`** - the platform pushes every transfer's progress
+into the call's room. The processor turns each message into a
+`PiopiyTransferStatusFrame` (`started`, `failed` with a reason, `completed`)
+and, by default, speaks it: "I'm connecting you now" as the target rings, an
+apology when it fails, plus a note into the LLM context so the model carries
+on sensibly. Pass `narrate=False` to handle the frames yourself. `completed`
+is best-effort: at that moment the agent is being removed from the call, and
+`on_participant_left` fires.
+
+## Notes
+
+- Every action uses the call's customer leg, which `PiopiyCall.call_id` is.
+- SIP Connect calls consume no phone number, so a transfer to a phone from one
+  needs `transfer_caller_id` (a DID you own).
+- Accept timing is handled for you: the runner accepts on `on_connected`, and
+  if the join missed the platform's deadline it cancels the bot so two agents
+  never share a call.
+- Pipecat changes quickly. This release is tested against v1.8.1; the pinned
+  range in `pyproject.toml` is `>=1.8,<2`.
+
+## License
+
+MIT. Copyright TeleCMI.

pipecat_piopiy-0.1.0/pipecat_piopiy/__init__.py

@@ -0,0 +1,44 @@
+"""Piopiy (TeleCMI) telephony for Pipecat voice agents.
+
+    from pipecat_piopiy import PiopiyRunner, PiopiyCallControl, piopiy_tools
+    from pipecat_piopiy.processors import PiopiyEventsProcessor
+
+    async def bot(transport, call):
+        control = PiopiyCallControl(call)
+        tools = piopiy_tools(control, transfer_number="919876543210")
+        ...
+
+    PiopiyRunner().run(bot)
+"""
+
+from .call import PiopiyCall
+from .control import (
+    TRANSFER_FAILURE_REASONS,
+    PiopiyAPIError,
+    PiopiyCallControl,
+    TransferResult,
+    TransferStatus,
+    build_connect_pipeline,
+)
+from .frames import PiopiyTransferStatusFrame
+from .processors import PiopiyEventsProcessor
+from .runner import PiopiyRunner
+from .tools import PiopiyTools, piopiy_tools
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "TRANSFER_FAILURE_REASONS",
+    "PiopiyAPIError",
+    "PiopiyCall",
+    "PiopiyCallControl",
+    "PiopiyEventsProcessor",
+    "PiopiyRunner",
+    "PiopiyTools",
+    "PiopiyTransferStatusFrame",
+    "TransferResult",
+    "TransferStatus",
+    "__version__",
+    "build_connect_pipeline",
+    "piopiy_tools",
+]

pipecat_piopiy-0.1.0/pipecat_piopiy/call.py

@@ -0,0 +1,92 @@
+"""The call a Piopiy worker was handed: who is calling whom, and how to act on it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class PiopiyCall:
+    """One phone call, as offered to your agent.
+
+    Built by :class:`~pipecat_piopiy.runner.PiopiyRunner` from the job the
+    Piopiy platform dispatched. Every live-call action (transfer, hangup,
+    status) keys on ``call_id``, which is the customer leg of the call - the
+    id the platform expects on ``/v3/calls/{call_id}/actions/*``.
+
+    Attributes:
+        call_id: The customer leg's call id. Use it for every action.
+        room_name: The LiveKit room the call's media is bridged into.
+        direction: ``"inbound"`` when someone called the agent, ``"outbound"``
+            when the agent called them.
+        from_number: The caller's number. On SIP Connect calls this is the
+            PBX's SIP user, not a phone number.
+        to_number: The number dialled. On SIP Connect calls this is the agent
+            id or extension the PBX dialled.
+        agent_id: The Piopiy agent handling this call.
+        variables: Key/values passed on call creation as ``variables`` - a
+            campaign's context for the conversation. Empty on inbound calls
+            unless the platform attached any.
+        sip_headers: SIP headers the platform forwarded, when any.
+        sip_account_id: On SIP Connect calls, the SIP account the call came in
+            on, so one agent can tell PBXs or sites apart. ``None`` on calls
+            that arrived over a phone number.
+        trace_id: The platform's trace id for this call. Quote it to support.
+    """
+
+    call_id: str
+    room_name: str
+    direction: str
+    from_number: str
+    to_number: str
+    agent_id: str
+    variables: dict[str, str] = field(default_factory=dict)
+    sip_headers: dict[str, str] = field(default_factory=dict)
+    sip_account_id: str | None = None
+    trace_id: str = ""
+
+    # Processors that want the platform's room messages register here; the
+    # runner fans each message out to them. Not part of the public surface.
+    _listeners: list[Any] = field(default_factory=list, repr=False, compare=False)
+
+    @property
+    def is_inbound(self) -> bool:
+        """True when the person on the line called us."""
+        return self.direction == "inbound"
+
+    @property
+    def is_sip_connect(self) -> bool:
+        """True when the call arrived over SIP Connect rather than a phone number."""
+        return self.sip_account_id is not None
+
+    @classmethod
+    def from_job(cls, job: Any, *, agent_id: str) -> PiopiyCall:
+        """Build a call from a ``piopiy_agent.Job``.
+
+        Args:
+            job: The job the worker received.
+            agent_id: The agent id this worker serves.
+
+        Returns:
+            The call, ready to hand to your bot.
+        """
+        headers = dict(getattr(job.call, "sip_headers", {}) or {})
+        variables = dict(getattr(job.call, "variables", {}) or {})
+        sip_account_id = (
+            headers.get("X-SIP-Account-ID")
+            or headers.get("x-sip-account-id")
+            or variables.get("sip_account_id")
+        )
+        return cls(
+            call_id=job.call.call_uuid,
+            room_name=job.room_name,
+            direction=job.call.direction or "inbound",
+            from_number=job.call.from_number,
+            to_number=job.call.to_number,
+            agent_id=agent_id,
+            variables=variables,
+            sip_headers=headers,
+            sip_account_id=sip_account_id,
+            trace_id=getattr(job, "trace_id", "") or "",
+        )