🎙️ DevWhisper — Voice-Native Developer Experience Agent

DevWhisper is a voice-first AI agent built for developers. Instead of stopping to search through files or documentation, you just ask out loud — and it answers based on your actual codebase.

---

🚨 The Problem

Developers lose focus constantly. Switching between your editor, a browser, Stack Overflow, and documentation breaks the flow of thinking. Most AI tools still require you to type, copy-paste code, and wait.

DevWhisper lets you stay in flow. Ask a question with your voice, get an answer in seconds, and keep coding.

---

✨ What It Does

🎤 You ask a question about your code 🔍 It searches your actual codebase with hybrid vector + keyword search 🔊 It responds in plain spoken English, like a senior dev sitting next to you

Example questions that work:

• "What does the preprocess function do?"
• "Where is the model saved after training?"
• "How do I debug a KeyError in the pipeline?"

---

🏗️ Architecture

Developer speaks
      ↓
Vapi — Speech to Text
      ↓
FastAPI Webhook Server
      ↓
Qdrant + BM25 Hybrid Search
      ↓
Groq LLaMA 3.3 70B
      ↓
FastAPI sends answer back
      ↓
Vapi — Text to Speech
      ↓
Developer hears the response

---

🛠️ Tech Stack

Component	Role
🎙️ Vapi	Handles voice input and output
🗄️ Qdrant + BM25	Hybrid vector + keyword search
🤖 Groq (LLaMA 3.3 70B)	Generates the response
⚡ FastAPI	Receives webhooks from Vapi and orchestrates everything

---

🚀 Getting Started

Prerequisites

• Python 3.10+
• API keys for:
  • Groq
  • Vapi
  • Qdrant (cluster URL + API key)
• ngrok (or similar tunneling tool) to expose your local server to Vapi

Setup

1. Clone the repository

   git clone https://github.com/Aharshi3614/Devwhisper.git
   cd Devwhisper

2. Create and activate a virtual environment

   python -m venv venv
   source venv/bin/activate   # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment variables

   Copy the example file and fill in your keys:

   cp .env.example .env

   Then edit .env:

   QDRANT_URL=your_qdrant_cluster_url
   QDRANT_API_KEY=your_qdrant_api_key
   GROQ_API_KEY=your_groq_api_key
   

5. Add your codebase

   Drop the Python files you want DevWhisper to answer questions about into the sample_codebase/ folder.

6. Index your codebase

   python indexer.py

7. Start the server

   uvicorn main:app --reload --port 8000

8. Create a .env file in the root folder:cp ./.env.example ./.env

9. Expose it publicly

   ngrok http 8000

10. Connect Vapi

    Update your Vapi tool's Server URL to your ngrok URL plus /webhook.

✅ Verify it's working

With the server running, confirm it responds:

curl http://localhost:8000/health

You should get a response back confirming the server is live. You can also run the standalone test client (see below) to check the full pipeline end-to-end without needing a live voice call.

---

🐳 Run with Docker

1. Build the image:

   docker build -t devwhisper .

2. Create a .env file with your API keys (same as above).
3. Run the container:

   docker run -p 8000:8000 --env-file .env devwhisper

4. Expose it with ngrok and update your Vapi tool's Server URL as in the steps above.

---

🧪 Testing Locally

You can test DevWhisper's conversation flow directly from your terminal — without using Vapi or making a voice call — using the standalone test client. This is useful for local development and debugging.

1. Make sure your FastAPI server is running:

   uvicorn main:app --reload --port 8000

2. Run the test client in interactive mode:

   python test_client.py

3. Or pass a one-off query:

   python test_client.py --query "What does the preprocess function do?"

---

📁 Project Structure

File / Folder	Purpose
main.py	FastAPI webhook server, handles all Vapi events
indexer.py	Chunks, embeds, and uploads to Qdrant plus builds BM25 keyword index
retriever.py	Hybrid search: vector + BM25 + symbol matching fused via RRF
llm.py	Sends the query and context to Groq and returns the answer
test_client.py	Standalone CLI client for testing without Vapi
sample_codebase/	Put your own Python project files here

---

⚠️ Notes

• The ngrok URL changes every time you restart it — remember to update the Server URL in your Vapi tool settings each time.
• The .env file is not included in this repo for security. Create your own using .env.example as a starting point.

---

🤝 Contributing

Contributions are welcome! Check out the open issues — issues labeled good first issue are a great place to start.

📄 License

See the LICENSE file for details.