DialogWeaver

This project is now OFFICIALLY accepted for:

🌟 Stars	🍴 Forks	🐛 Issues	🔔 Open PRs	🔕 Closed PRs	🛠️ Languages	👥 Contributors

DialogWeaver

Weave complex, real-time voice AI conversations. The end-to-end, open-source orchestration platform for building intelligent voice agents.

---

DialogWeaver is a complete, self-hostable framework designed to create, manage, and deploy sophisticated, real-time voice-first conversational assistants. It provides all the necessary components as open-source, giving you full control and ownership over your voice AI applications.

Whether you're a developer prototyping a new voice-driven feature, a business building a customer service agent, or a researcher experimenting with conversational AI, DialogWeaver provides the production-grade foundation you need.

Key Features

• 🎙️ Real-Time & Interruptible: A high-performance core that orchestrates complex voice conversations, allowing agents to be interrupted mid-sentence for a natural and fluid user experience.
• 🧩 Extensible & Provider-Agnostic: Seamlessly integrates with best-in-class ASR (Speech-to-Text), LLM (Large Language Model), and TTS (Text-to-Speech) providers. Easily add new providers to suit your needs.
• 🔐 Secure & Multi-Tenant API: A robust FastAPI backend handles user authentication, agent management, and the secure, encrypted storage of provider API keys, making it ready for multi-user environments.
• 🎨 No-Code UI Playground: A modern Next.js web interface provides a visual playground to build, test, and manage your voice agents without writing a single line of code.
• 📞 Telephony & Web Ready: Natively supports both traditional telephony (via providers like Twilio and Plivo) and web-based clients through a unified, containerized architecture.
• 🚀 Dockerized & Self-Hostable: The entire platform is orchestrated with Docker Compose, allowing you to deploy it on your own infrastructure with a single command, ensuring data privacy and control.

Architecture

DialogWeaver is built as a modern, service-oriented monorepo. This design provides a clean separation of concerns and enhances scalability and maintainability.

Service	Description	Key Technologies
ui	User-facing dashboard and no-code agent builder.	Next.js, React, TypeScript, Tailwind CSS
api	Secure RESTful control plane for managing users, agents, and calls.	FastAPI, Python, PostgreSQL, SQLAlchemy
engine	The real-time worker that orchestrates the voice conversation logic.	FastAPI (as worker), Python, WebSockets
database	Persistent relational data storage.	PostgreSQL
cache	In-memory data store for caching and session management.	Redis

---

📁 Project Structure

📦 DialogWeaver
├─ 📂 .github                   # GitHub configurations and automation
│  ├─ 📂 ISSUE_TEMPLATE         # Templates for reporting issues (bugs, features)
│  └─ 📂 workflows              # GitHub Actions workflows (CI/CD, automated tests)
│
├─ 📂 api                        # Backend API service
│  ├─ 📂 alembic                 # Database migration scripts (versioned)
│  ├─ 📂 app                     # Core API logic (routes, controllers, models)
│  ├─ 📂 tests                   # Unit & integration tests for API
│  ├─ 📄 Dockerfile              # Dockerfile to containerize the API
│  ├─ 📄 alembic.ini             # Alembic config for database migrations
│  ├─ 📄 main.py                 # API server entry point
│  └─ 📄 requirements.txt        # Python dependencies for API
│
├─ 📂 docs                       # Documentation and images
│  ├─ 📄 Architecture.png        # Project architecture diagram
│  ├─ 📄 gssoc.png               # GSSoC-related image
│  └─ 📄 logo.jpg                # Project logo
│
├─ 📂 engine                     # Core engine/service module
│  ├─ 📂 openvoiceos_engine      # Main engine logic for OpenVoiceOS
│  ├─ 📂 telephony_server        # Telephony server logic (SIP, VoIP, calls)
│  ├─ 📄 Dockerfile              # Dockerfile to containerize engine service
│  ├─ 📄 main.py                 # Engine service entry point
│  └─ 📄 requirements.txt        # Python dependencies for engine
│
├─ 📄 .env.sample                # Sample environment variables template
├─ 📄 .gitignore                 # Git ignore rules
├─ 📄 CONTRIBUTING.md            # Guidelines for contributors
├─ 📄 LICENSE                    # Project license
├─ 📄 README.md                  # Project documentation
└─ 📄 docker-compose.yml         # Docker Compose config for multi-service setup

Quick Start

Get the entire DialogWeaver platform running on your local machine in just a few steps.

Prerequisites:

• Docker and Docker Compose
• API keys from your chosen AI and telephony providers (see .env.sample)

1. Clone the Repository

git clone https://github.com/OpenVoiceX/DialogWeaver.git
cd DialogWeaver

2. Configure Your Environment

Create your local environment file from the template. This file will store your secret keys and is ignored by Git.

cp .env.sample .env

Now, open the .env file and fill in your API keys and credentials. A SECRET_KEY and NGROK_AUTHTOKEN are required for the initial setup.

3. Build and Run the Platform

This single command builds all the service images and starts the containers.

docker compose up --build

For the first run, omit the -d flag to see the logs from all services in your terminal. This is the best way to debug any setup issues.

4. Initialize the Database

Once the containers are running, open a new terminal window and run the database migrations to set up your tables.

docker compose exec api alembic revision --autogenerate -m "Initial schema"
docker compose exec api alembic upgrade head

5. Access Your Platform

Your DialogWeaver instance is now live!

• UI Playground: http://localhost:3000
• API Documentation: http://localhost:8000/docs
• Ngrok Dashboard (for your public telephony URL): http://localhost:4040

To learn how to configure your telephony provider and make your first call, please see our detailed Contributor Guide.

---

Contributing

DialogWeaver is a community-driven project. We welcome contributions of all kinds, from bug reports to new features and documentation improvements.

Please read our CONTRIBUTING.md to get started with the development workflow and code style.

License

This project is licensed under the MIT License - see the LICENSE file for details.