siphon-ai 0.1.2
Build calling agents in minutes, not months. The missing infrastructure layer for AI calling. Siphon handles state, interruptions, and scaling so you can ship reliable agents in minutes, not months.
License: Apache-2.0
Requires Python: >=3.10
Keywords: ai-call-processing, ai-calling, ai-calling-crm-integration, ai-phone-systems, ai-telephony, ai-voice-systems, automated-calling, call-analytics, call-center, call-routing, calling-agent, contact-center, contact-center-solutions, conversational-ai, ivr, ivr-systems, livekit, livekit-agents, pstn, realtime, realtime-ai, sip, speech-to-text, telephony, telephony-ai-solutions, telephony-api, telephony-automation, telephony-crm-integration, telephony-devices, telephony-integrations, telephony-platform, telephony-sdk, telephony-voice-platform, text-to-speech, voice-agents, voice-ai, voice-api, voice-assistant, voice-automation, voice-calling-platform, voice-communication-platform, voice-communications, voice-contact-center, voice-infrastructure, voice-integration, voice-messaging, voice-orchestration, voice-telephony, voice-to-voice, voice-workflow, webrtc

<p align="center">
  <img src="https://siphon.blackdwarf.in/logo.png" alt="SIPHON" width="100" />
</p>

<h1 align="center">SIPHON</h1>

<p align="center">
  <a href="https://siphon.blackdwarf.in/docs">
    <img src="https://img.shields.io/badge/Documentation-000000?style=for-the-badge&logo=readthedocs&logoColor=white" alt="Documentation">
  </a>
  <a href="https://opensource.org/license/apache-2-0">
    <img src="https://img.shields.io/badge/License-Apache%202.0-D22128?style=for-the-badge&logo=Apache&logoColor=white" alt="License">
  </a>
  <a href="https://pypi.org/project/siphon-ai/">
    <img src="https://img.shields.io/pypi/v/siphon-ai?style=for-the-badge&logo=pypi&logoColor=white" alt="PyPI">
  </a>
</p>

<p align="center">
  <strong>Build calling agents in minutes, not months.</strong>
</p>

<p>
  Building calling agents manually requires stitching together WebSockets, managing audio buffers, and synchronizing state across multiple AI models. Siphon abstracts this entire layer into a clean, developer-friendly API that scales effortlessly.
</p>

⭐ Drop a star to help us grow!


<br/>

<p align="center">
  <img src="https://siphon.blackdwarf.in/system_overview.png" alt="SIPHON Architecture" width="100%" />
</p>

<br/>

## Not another toy framework.

Siphon is built for production environments where reliability and latency are non-negotiable.

| ⚡ **Low Latency**                                                                                    | 🛡️ **Production Ready**                                                                             | 🚀 **Infinite Scale**                                                                         |
| :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- |
| Powered by WebRTC (LiveKit) for sub-500ms voice interactions that feel like real human conversation. | Handles the chaotic reality of phone networks—audio packet loss, SIP signaling, and interruptions. | Define your agent once and run it on 1 or 1,000 servers. It balances the load automatically. |

<br/>


## Quick Start
 
If you're new to Siphon, we recommend checking out:
- 📖 **[Documentation](https://siphon.blackdwarf.in/docs)**
- ⚡ **[Quick Start Guide](https://siphon.blackdwarf.in/docs/overview/getting-started)**

### 1. Install
```bash
pip install siphon-ai
```

### 2. Configure Environment
Siphon requires **LiveKit** for real-time media and API keys for your AI providers.

Create a `.env` file:
```bash
# LiveKit (Cloud: https://cloud.livekit.io/ or Self-hosted)
LIVEKIT_URL=...
LIVEKIT_API_KEY=...
LIVEKIT_API_SECRET=...

# AI Providers
OPENAI_API_KEY=...
DEEPGRAM_API_KEY=...
CARTESIA_API_KEY=...
```

### 3. Create your Agent
Create a file named `agent.py`. This simple agent acts as a helpful assistant.

```python
from siphon.agent import Agent
from siphon.plugins import openai, cartesia, deepgram
from dotenv import load_dotenv

load_dotenv()

# Initialize your AI stack
llm = openai.LLM()
tts = cartesia.TTS()
stt = deepgram.STT()

# Define the Agent
agent = Agent(
    agent_name="Receptionist",
    llm=llm,
    tts=tts,
    stt=stt,
    system_instructions="You are a helpful receptionist. Answer succinctly.",
)

if __name__ == "__main__":
    # One-time setup: downloads required files (only needed on fresh machines)
    agent.download_files()

    # Start the agent worker in development mode
    agent.dev()

    # Start the agent worker in production mode
    # agent.start()
```

For more details on configuring your **[Agent](https://siphon.blackdwarf.in/docs/agents/overview)** (latency, interruptions, VAD...etc) and exploring available **[Plugins](https://siphon.blackdwarf.in/docs/plugins/overview)** (Deepgram, Cartesia, OpenAI, ElevenLabs...etc), check out the documentation.


### 4. Run
Start your agent worker.

```bash
python agent.py
```

**Horizontal Scaling**: To scale, simply run this command on multiple servers. The worker architecture automatically detects new nodes and balances the load with **Zero Configuration**. [Learn more about Scaling](https://siphon.blackdwarf.in/docs/concepts/scaling)


## Capabilities

### 📞 Receive Calls (Inbound)
Bind a phone number to your agent using a Dispatch rule.

```python
import os
from siphon.telephony.inbound import Dispatch
from dotenv import load_dotenv

load_dotenv()

dispatch = Dispatch(
    dispatch_name="customer-support",
    agent_name="Receptionist", # Must match the name in agent.py
    sip_trunk_id=os.getenv("SIP_TRUNK_ID"),
    # Or: sip_number=os.getenv("SIP_NUMBER"),
)
dispatch.agent()
```

> **Note**: For more details, check out the **[Inbound Documentation](https://siphon.blackdwarf.in/docs/calling/inbound/overview)**. To configure numbers with providers like Twilio, see the **[Twilio Setup Guide](https://siphon.blackdwarf.in/docs/guides/twilio)**.

### 📱 Make Calls (Outbound)
Trigger calls programmatically from your code or API.

```python
import os
from siphon.telephony.outbound import Call
from dotenv import load_dotenv

load_dotenv()

call = Call(
    agent_name="Receptionist", # Must match the name in agent.py
    sip_trunk_setup={ ... }, # Your SIP credentials
    # Or: sip_trunk_id=os.getenv("SIP_TRUNK_ID"),
    number_to_call="+15550199"
)
call.start()
```

> **Note**: For more details, check out the **[Outbound Documentation](https://siphon.blackdwarf.in/docs/calling/outbound/overview)**. To configure trunks with providers like Twilio, see the **[Twilio Setup Guide](https://siphon.blackdwarf.in/docs/guides/twilio)**.

### 💾 Persist Call Data
Siphon enables call recordings, transcriptions, and metadata persistence via environment variables.

```bash
# Enable saving features
CALL_RECORDING=true
SAVE_METADATA=true
SAVE_TRANSCRIPTION=true

# Configure storage location (locally, S3, Redis, Postgres, etc)
METADATA_LOCATION=Metadata # saves locally
TRANSCRIPTION_LOCATION=postgresql://..... # saves to postgresql

# Configure S3 (Call Recordings are always saved to S3)
AWS_S3_ENDPOINT=
AWS_S3_ACCESS_KEY_ID=
AWS_S3_SECRET_ACCESS_KEY=
AWS_S3_BUCKET=
AWS_S3_REGION=
AWS_S3_FORCE_PATH_STYLE=true
```

> **Note**: Siphon supports multiple storage backends. For detailed configuration instructions, see the **[Call Data Documentation](https://siphon.blackdwarf.in/docs/agents/call-data)**.

## 🚀 Examples and demo

> [**More Examples**](https://siphon.blackdwarf.in/examples)

| Example | Description |
| :--- | :--- |
| [**A 24/7 AI Dental Receptionist in few lines**](https://github.com/blackdwarftech/siphon/tree/main/examples/Dental_Clinic_Receptionist) | A fully functional AI receptionist that handles appointment booking, modifications, and cancellations with Google Calendar integration. |

More coming and stay tuned 👀!

## 📖 Documentation

For detailed documentation, visit [Siphon Documentation](https://siphon.blackdwarf.in/docs), including a [Quickstart Guide](https://siphon.blackdwarf.in/docs/overview/getting-started).

## 🤝 Contributing

We love contributions from the community ❤️. For details on contributing or running the project for development, check out our [Contributing Guide](https://github.com/blackdwarftech/siphon/blob/main/CONTRIBUTING.md).

## Support us

We are constantly improving, and more features and examples are coming soon. If you love this project, please drop us a star ⭐ at [GitHub repo](https://github.com/blackdwarftech/siphon) to stay tuned and help us grow.

## License

Siphon is Apache 2.0 licensed.