Skip to content

Commit e5054ce

Browse files
Hiteshydv001Hiteshydv001
authored
Update CONTRIBUTING.md
1 parent f8c2916 commit e5054ce

1 file changed

Lines changed: 201 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
<p align="center">
2+
<!-- A placeholder for your future logo -->
3+
<!-- <img src="URL_TO_YOUR_LOGO.svg" alt="DialogWeaver Logo" width="150"> -->
4+
</p>
5+
6+
<h1 align="center">DialogWeaver</h1>
7+
8+
<p align="center">
9+
<strong>The open-source framework for weaving intelligent, real-time voice conversations.</strong>
10+
</p>
11+
12+
<p align="center">
13+
<a href="https://github.com/Hiteshydv001/DialogWeaver/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Hiteshydv001/DialogWeaver?style=flat-square" alt="License: MIT"></a>
14+
<a href="https://github.com/Hiteshydv001/DialogWeaver/issues"><img src="https://img.shields.io/github/issues/Hiteshydv001/DialogWeaver?style=flat-square" alt="GitHub issues"></a>
15+
<a href="https://github.com/Hiteshydv001/DialogWeaver/blob/main/CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-Welcome-brightgreen?style=flat-square" alt="PRs Welcome"></a>
16+
<a href="#"><img src="https://img.shields.io/static/v1?label=Discord&message=Join%20Chat&color=7289DA&logo=discord&style=flat-square" alt="Join the community on Discord"></a>
17+
</p>
18+
19+
---
20+
21+
**DialogWeaver** is a complete, self-hostable framework designed to create, manage, and deploy sophisticated, real-time voice assistants. It provides a high-performance orchestration engine, a secure multi-tenant API, and a no-code UI playground—all fully open-source.
22+
23+
With DialogWeaver, you can seamlessly **weave** together best-in-class AI services (Speech-to-Text, LLMs, and Text-to-Speech) to build fluid, interruptible, and intelligent conversational agents for telephony, web applications, and more.
24+
25+
## Table of Contents
26+
27+
- [Core Features](#core-features)
28+
- [Architecture Explained](#architecture-explained)
29+
- [Local Development Setup](#local-development-setup)
30+
- [How to Test the Platform](#how-to-test-the-platform)
31+
- [API Overview & Endpoints](#api-overview--endpoints)
32+
- [How to Contribute](#how-to-contribute)
33+
- [License](#license)
34+
35+
## Core Features
36+
37+
- **🎙️ Real-Time & Interruptible:** Natural, human-like conversation logic that supports low-latency streaming and allows users to interrupt the agent.
38+
- **🧩 Extensible & Provider-Agnostic:** Easily integrate with any ASR, LLM, or TTS provider to find the perfect balance of cost and performance.
39+
- **🔐 Secure API & UI:** A FastAPI backend and Next.js UI for secure, multi-user agent management with encrypted key storage.
40+
- **📞 Telephony & Web Ready:** Natively supports both traditional phone calls (via Twilio/Plivo) and real-time web-based clients.
41+
- **🚀 Self-Hostable with Docker:** Deploy the entire platform on your own infrastructure with a single command for complete data privacy and control.
42+
- **🎨 No-Code Agent Builder:** A user-friendly interface to visually construct, test, and manage your voice agents.
43+
44+
## Architecture Explained
45+
46+
DialogWeaver is built with a clean, service-oriented architecture. Think of it as having three main parts that work together:
47+
48+
1. **The Control Panel (`api` service):**
49+
* This is the secure **FastAPI** backend that manages everything: user accounts, agent configurations, and all the secret API keys (which it encrypts in the database). When you want to make a call, you talk to this service.
50+
51+
2. **The Conversation Engine (`engine` service):**
52+
* This is a specialized **Python worker** built for one job: handling the live conversation. It processes the audio stream in real-time, talks to the AI services (for transcription, thinking, and speaking), and handles interruptions.
53+
54+
3. **The Dashboard (`ui` service):**
55+
* This is the **Next.js** web application you see in your browser. It's a user-friendly dashboard where you can build agents with forms and buttons instead of code. It only talks to the `api` service.
56+
57+
These three services, along with a **PostgreSQL** database and a **Redis** cache, run together in **Docker** containers, making the whole system self-contained and easy to run anywhere.
58+
59+
---
60+
61+
## Local Development Setup
62+
63+
Follow these steps to get the complete DialogWeaver platform running on your local machine.
64+
65+
### 1. Prerequisites
66+
67+
- **Git:** To clone the repository.
68+
- **Docker & Docker Compose:** The easiest way to get both is to [Install Docker Desktop](https://www.docker.com/products/docker-desktop/).
69+
- **An ngrok Account:** Required to receive webhooks from telephony providers. [Sign up for free](https://ngrok.com/).
70+
71+
### 2. Clone the Repository
72+
73+
```bash
74+
git clone https://github.com/Hiteshydv001/DialogWeaver.git
75+
cd DialogWeaver
76+
```
77+
78+
### 3. Configure Your Environment
79+
80+
This is the most important step. You need to provide API keys for the services you want to use.
81+
82+
- First, create your local environment file from the sample:
83+
```bash
84+
cp .env.sample .env
85+
```
86+
- Now, open the newly created `.env` file in your code editor and fill in the required values.
87+
- **Crucially, generate a new `SECRET_KEY`**. You can run `openssl rand -hex 32` in your terminal to get one.
88+
- Fill in your `NGROK_AUTHTOKEN`.
89+
- Fill in the credentials for at least one provider for each category (Telephony, ASR, LLM, TTS), for example: `TWILIO_*`, `DEEPGRAM_AUTH_TOKEN`, `OPENAI_API_KEY`, and `ELEVENLABS_API_KEY`.
90+
91+
### 4. Run the Platform
92+
93+
With your `.env` file configured, start all services using Docker Compose.
94+
```bash
95+
docker compose up --build
96+
```
97+
> **Tip:** Run this command *without* the `-d` flag the first time. This will show you the logs from all services directly in your terminal, which is essential for debugging.
98+
99+
### 5. Verify the Setup
100+
101+
Once the containers are running, check that each component is accessible:
102+
103+
- **Frontend UI**: Open `http://localhost:3000`
104+
- **Backend API Docs**: Open `http://localhost:8000/docs`
105+
- **Ngrok Dashboard**: Open `http://localhost:4040` to get your public URL (e.g., `https://random-string.ngrok-free.app`). **Copy this public URL.**
106+
107+
---
108+
109+
## How to Test the Platform
110+
111+
### 1. Configure Telephony Webhook
112+
113+
- Go to your Twilio (or Plivo) account's phone number settings.
114+
- Under "Voice & Fax", in the "A CALL COMES IN" section, set the webhook to your **ngrok public URL** from the previous step, pointing to the correct endpoint: `https://<your-ngrok-url>/twilio`.
115+
- Set the HTTP method to `POST` and save.
116+
117+
### 2. Use the DialogWeaver UI
118+
119+
1. **Register:** Go to `http://localhost:3000` and create a new user account.
120+
2. **Add Keys:** Navigate to the "API Keys" page and add your API keys for OpenAI, ElevenLabs, etc. The backend will encrypt and store them.
121+
3. **Create an Agent:** Go to the "Agents" page, click "Create New Agent", and use the form to configure its personality and tools.
122+
4. **Make a Call:** Click the "Make a Call" button, enter **your personal phone number**, and start a conversation!
123+
124+
---
125+
126+
## API Overview & Endpoints
127+
128+
You can interact with the API directly at `http://localhost:8000/docs`. Here are the key endpoints:
129+
130+
#### User Authentication
131+
132+
- `POST /api/v1/users/register`: Create a new user account.
133+
- `POST /api/v1/users/token`: Log in to get a JWT access token.
134+
135+
**Example: Get a token**
136+
```bash
137+
# First, set your token to an environment variable for convenience
138+
export TOKEN=$(curl -X POST "http://localhost:8000/api/v1/users/token" \
139+
-H "Content-Type: application/x-www-form-urlencoded" \
140+
-d "username=your-email@example.com&password=your-password" | jq -r .access_token)
141+
```
142+
143+
#### Agent Management
144+
145+
- `POST /api/v1/agents/`: Create a new agent.
146+
- `GET /api/v1/agents/`: List all of your agents.
147+
148+
**Example: Create an agent**
149+
```bash
150+
# Create a file named agent.json with your agent's configuration
151+
curl -X POST "http://localhost:8000/api/v1/agents/" \
152+
-H "Authorization: Bearer $TOKEN" \
153+
-H "Content-Type: application/json" \
154+
-d @agent.json
155+
```
156+
157+
#### Initiating Calls
158+
159+
- `POST /api/v1/calls/{agent_id}/initiate_call`: Start a call using a specific agent.
160+
161+
**Example: Make a call**
162+
```bash
163+
curl -X POST "http://localhost:8000/api/v1/calls/1/initiate_call" \
164+
-H "Authorization: Bearer $TOKEN" \
165+
-H "Content-Type: application/json" \
166+
-d '{"phone_number": "+12223334444"}'
167+
```
168+
169+
---
170+
171+
## How to Contribute
172+
173+
We welcome contributions of all kinds! This is how you can help.
174+
175+
### Reporting Bugs & Suggesting Features
176+
177+
- **Found a bug?** [Open a Bug Report](https://github.com/Hiteshydv001/DialogWeaver/issues/new?template=bug_report.md).
178+
- **Have an idea?** [Suggest a new Feature](https://github.com/Hiteshydv001/DialogWeaver/issues/new?template=feature_request.md).
179+
180+
### Your First Contribution (The 5-Minute PR)
181+
182+
A great way to start is by improving documentation.
183+
1. Find a typo or a sentence that could be clearer in this `README.md` or any other documentation file.
184+
2. Click the "Edit" (pencil) icon on the file in the GitHub UI.
185+
3. Make your change and write a clear commit message (e.g., `docs: Fix typo in setup guide`).
186+
4. Click "Propose changes" and open a pull request. That's it!
187+
188+
### Submitting a Pull Request
189+
190+
1. **Fork** the repository and clone your fork.
191+
2. **Create a branch** for your changes: `git checkout -b feat/add-new-provider`.
192+
3. **Make your changes** locally.
193+
4. **Commit your work** with a descriptive message: `git commit -m "feat(tts): Add support for a new TTS provider"`.
194+
5. **Push** to your fork: `git push origin feat/add-new-provider`.
195+
6. **Open a Pull Request** from your fork to the `main` branch of `Hiteshydv001/DialogWeaver`.
196+
7. In your PR description, link to the issue it resolves (e.g., `Closes #42`).
197+
198+
## License
199+
200+
DialogWeaver is released under the **[MIT License](LICENSE)**.
201+
```

0 commit comments

Comments
 (0)