DUCK-E stands for Digitally Unified Conversational Knowledge Engine — an AI-powered voice assistant that revolutionizes rubber duck debugging by actively engaging in your debugging process.
Rubber duck debugging is a time-honored programming technique where developers explain their code, line-by-line, to an inanimate rubber duck. The simple act of verbalizing the problem often leads to discovering the solution yourself.
The concept comes from The Pragmatic Programmer by Andrew Hunt and David Thomas:
"A very simple but particularly useful technique for finding the cause of a problem is simply to explain it to someone else... They do not need to say a word; the simple act of explaining, step by step, what the code is supposed to do often causes the problem to leap off the screen and announce itself."
Traditional rubber ducking is a one-way conversation - you talk, the duck listens silently.
DUCK-E (pronounced "ducky") flips this paradigm on its head. Instead of a silent listener, DUCK-E is an AI-powered voice assistant that actively engages in your debugging process. It's rubber ducking 2.0 - a conversation, not a monologue.
Traditional rubber ducking relies on self-reflection. DUCK-E enhances this by:
- 🗣️ Active Engagement: Ask questions and get intelligent responses in real-time
- 🧠 Contextual Understanding: DUCK-E comprehends your code and architecture
- 🔍 Intelligent Assistance: Offers suggestions, explains concepts, and helps debug
- 🌐 Real-time Information: Can search the web for current documentation and solutions
- 🌤️ Breaks the Monotony: Even checks the weather while you're debugging
- WebRTC Real-time Communication: Low-latency voice interaction using OpenAI's Realtime API
- Natural Conversation: Speak naturally, just like you would to a colleague
- Interrupt-friendly: DUCK-E can handle natural conversation flow
- Code Understanding: Discuss algorithms, architecture, and implementation details
- Web Search Integration: Search for documentation, Stack Overflow answers, and current solutions
- Weather Information: Because even ducks need to know if it's raining
- Context Retention: Maintains conversation context throughout your debugging session
- OpenAI GPT-5 Models: Powered by cutting-edge language models
gpt-5-mini: Fast responses for general queriesgpt-5: Deep reasoning for complex problemsgpt-realtime: Real-time voice interaction
- AutoGen Framework: Multi-agent orchestration for complex tasks
- FastAPI Backend: High-performance async Python API
- WebSocket Communication: Real-time bidirectional communication
┌─────────────────┐
│ Web Browser │
│ (User's Voice) │
└────────┬────────┘
│ WebSocket
│ (Audio Stream)
▼
┌─────────────────────────────────┐
│ FastAPI Backend │
│ │
│ ┌──────────────────────────┐ │
│ │ RealtimeAgent │ │
│ │ (AutoGen Framework) │ │
│ └──────────┬───────────────┘ │
│ │ │
│ ┌──────────▼───────────────┐ │
│ │ Registered Functions │ │
│ │ - get_current_weather │ │
│ │ - get_weather_forecast │ │
│ │ - web_search │ │
│ └──────────────────────────┘ │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ OpenAI Realtime API │
│ (gpt-realtime model) │
└─────────────────────────────────┘
- User speaks into their browser microphone
- Audio streams via WebSocket to the FastAPI backend
- RealtimeAgent processes the audio through OpenAI's Realtime API
- DUCK-E responds with intelligent, context-aware answers
- Tool calls are made when needed (web search, weather data)
- Conversation continues with maintained context
The FastAPI application with:
- WebSocket endpoint (
/session) for real-time audio communication - RealtimeAgent initialization with system prompts
- Function registration for tools (weather, web search)
- Configuration loading for OpenAI models
- Auto-generated configs: Automatically creates OpenAI model configurations
- Multiple model support: Switches between models based on task complexity
- Tag-based filtering: Organizes models by capability (realtime, chat, advanced)
get_current_weather(location): Real-time weather data via WeatherAPIget_weather_forecast(location): 3-day weather forecastweb_search(query): Web search using OpenAI's native capabilities
The easiest way to run DUCK-E is using our pre-built Docker container:
# Pull the latest image
docker pull ghcr.io/jedarden/duck-e:latest
# Run with your API keys (models auto-configured!)
docker run -d \
-p 8000:8000 \
-e OPENAI_API_KEY=your_openai_key \
-e WEATHER_API_KEY=your_weather_key \
ghcr.io/jedarden/duck-e:latestThen navigate to http://localhost:8000 and start talking!
Create a docker-compose.yml:
version: '3.8'
services:
duck-e:
image: ghcr.io/jedarden/duck-e:latest
ports:
- "8000:8000"
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
- WEATHER_API_KEY=${WEATHER_API_KEY}
restart: unless-stoppedRun with:
docker-compose up -d- Docker (for containerized deployment) OR
- Python 3.9+
- Node.js 16+ (for development tools)
- OpenAI API key with access to GPT-5/Realtime models
- WeatherAPI key (free at https://www.weatherapi.com/)
DUCK-E now features automatic configuration generation! Simply provide your OpenAI API key, and the system will automatically configure all necessary models.
Create a .env file in the ducke directory:
# OpenAI API Configuration
# REQUIRED: Just add your API key - models are configured automatically!
OPENAI_API_KEY=sk-proj-your-api-key-here
# Weather API Configuration
WEATHER_API_KEY=your_weather_api_key_hereThat's it! The application automatically configures:
- gpt-5-mini: Fast responses for general queries
- gpt-5: Advanced reasoning for complex problems
- gpt-realtime: Real-time voice interaction
Advanced Users: You can still manually override the configuration by providing OAI_CONFIG_LIST in your .env file (see .env.example for format).
# Navigate to the ducke directory
cd ducke
# Install Python dependencies
pip install -r requirements.txt
# Run the development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000# Build the Docker image
docker build -t ducke:latest .
# Run with docker-compose
docker-compose upThe application will be available at http://localhost:8000
- Navigate to
http://localhost:8000in your browser - Click the microphone icon to start
- Grant microphone permissions when prompted
- Start speaking to DUCK-E!
Debugging Help:
You: "I'm getting a TypeError when I try to iterate over my API response"
DUCK-E: "Let's debug this together. Can you tell me what type of object
you're receiving from the API? Is it a dictionary, list, or
something else?"
Web Search:
You: "What's the latest syntax for async/await in Python 3.12?"
DUCK-E: "Let me search for the latest Python 3.12 documentation on that..."
[Searches and provides accurate, current information]
Weather Check:
You: "What's the weather like in San Francisco?"
DUCK-E: "It's currently 62°F in San Francisco with partly cloudy skies..."
- FastAPI: Modern, high-performance web framework
- AutoGen: Microsoft's framework for AI agent orchestration
- OpenAI SDK: Official Python client for OpenAI API
- Uvicorn: ASGI server for production deployment
- OpenAI GPT-5 Models: Latest generation language models
- Realtime API: Low-latency voice interaction
- Function Calling: Tool integration for extended capabilities
- WebRTC: Real-time audio streaming
- WebSocket: Bidirectional communication
- Jinja2 Templates: Server-side rendering
- OpenAI Realtime API: Voice AI capabilities
- WeatherAPI: Weather data and forecasts
- Native Web Search: Built-in search functionality
DUCK-E uses three OpenAI models:
-
gpt-5-mini: Fast, efficient model for general queries
- Used for: Quick questions, simple explanations
- Response time: ~1-2 seconds
-
gpt-5: Advanced model for complex reasoning
- Used for: Deep debugging, architecture discussions
- Tagged:
gpt-5-full
-
gpt-realtime: Specialized for voice interaction
- Used for: Real-time conversation
- Tagged:
gpt-realtime - Features: Interruption handling, natural speech patterns
realtime_llm_config = {
"timeout": 86400, # 24-hour timeout
"config_list": realtime_config_list,
"temperature": 1.0, # Natural, varied responses
"parallel_tool_calls": True, # Execute multiple tools simultaneously
"tool_choice": "auto", # Intelligent tool selection
"tools": [{"type": "web_search_preview"}]
}ducke/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI application & WebSocket handler
│ └── website_files/
│ ├── static/ # CSS, JS, images
│ └── templates/ # HTML templates (Jinja2)
│ └── chat.html # Main chat interface
├── .env # Environment configuration (not in git)
├── .env.example # Example environment file
├── requirements.txt # Python dependencies
├── dockerfile # Docker container definition
├── docker-compose.yml # Docker orchestration
└── README.md # This file
Register new capabilities by decorating functions:
@realtime_agent.register_realtime_function(
name="your_function_name",
description="What this function does"
)
def your_function(param: Annotated[str, "description"]) -> str:
# Your implementation
return result| Variable | Required | Description |
|---|---|---|
OPENAI_API_KEY |
Yes | OpenAI API key with Realtime access |
WEATHER_API_KEY |
Yes | WeatherAPI key for weather functions |
OAI_CONFIG_LIST |
Yes | JSON configuration for AI models |
DUCK-E v0.2.0 includes comprehensive security hardening for public-facing deployments:
✅ Rate Limiting - DDoS protection with per-IP limits ✅ Cost Protection - $5/session budget, $100 circuit breaker ✅ Input Validation - Blocks SQL injection, XSS, SSRF, and 10+ attack vectors ✅ Security Headers - OWASP compliant (HSTS, CSP, X-Frame-Options, etc.) ✅ CORS Protection - Origin validation with whitelist ✅ WebSocket Security - Origin validation before connection ✅ API Authentication - Optional JWT-based tiered access
- Before v0.2.0: Potential $100,000+ API abuse
- After v0.2.0: $50/month normal operations (98.6% risk reduction)
# All security controls work out of the box!
docker-compose up -d
# Optional: Configure custom limits in .env
RATE_LIMIT_WEBSOCKET=5/minute
COST_PROTECTION_MAX_SESSION_COST_USD=5.0- 📚 Quick Start: See
docs/QUICK_START_SECURITY.md(8-hour deployment) - 📊 Complete Guide: See
docs/security/SECURITY_OVERVIEW.md - 🏢 Deployment: See
docs/IN_MEMORY_DEPLOYMENT.md - ✅ Test Coverage: 92% with 180+ security tests
All security controls active by default - no configuration required!
-
Security (✅ Built-in as of v0.2.0):
- ✅ Rate limiting (automatic)
- ✅ Cost protection (automatic)
- ✅ Input validation (automatic)
- ✅ Security headers (automatic)
⚠️ HTTPS/TLS: Configure reverse proxy (seedocs/security/)⚠️ Authentication: Optional JWT (seedocs/API_AUTHENTICATION.md)
-
Performance:
- Configure uvicorn workers based on CPU cores
- Use a reverse proxy (nginx) for load balancing
- Enable WebSocket compression
- Monitor timeout settings
- Security overhead: < 25ms total (excellent)
-
Monitoring:
- Prometheus metrics at
/metrics - Track rate limit violations
- Monitor API costs in real-time
- Circuit breaker activations
- Set up health check endpoints
- Prometheus metrics at
# docker-compose.prod.yml
version: '3.8'
services:
ducke:
build: .
ports:
- "8000:8000"
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
- WEATHER_API_KEY=${WEATHER_API_KEY}
- OAI_CONFIG_LIST=${OAI_CONFIG_LIST}
restart: always
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/status"]
interval: 30s
timeout: 10s
retries: 3Traditional debugging is often a solitary activity. You stare at code, trace execution paths, and hope inspiration strikes. Rubber duck debugging acknowledged that talking through problems helps - but it stopped short of true conversation.
DUCK-E represents a new paradigm:
Instead of solving problems alone, you have an intelligent partner who understands context, asks clarifying questions, and offers insights.
DUCK-E doesn't just help you fix bugs - it explains concepts, suggests best practices, and helps you grow as a developer.
Real-time feedback means less time stuck and more time shipping code.
Unlike generic AI assistants, DUCK-E maintains conversation context, understanding your codebase and the specific problem you're tackling.
- Brainstorm solutions when stuck
- Explain complex code to solidify understanding
- Get second opinions on architectural decisions
- Quick help when teammates are unavailable
- Onboarding new developers with 24/7 assistance
- Document decisions through conversation
- Interactive coding tutorials
- Concept explanation on-demand
- Practice explaining code to improve understanding
- Requires stable internet connection for OpenAI API
- API costs for usage
- Limited to audio interaction (no code viewing yet)
- No persistent memory across sessions
- 🖥️ Code Context Awareness: Share your editor contents with DUCK-E
- 💾 Session Memory: Remember previous conversations
- 🔗 IDE Integration: VSCode and JetBrains plugins
- 📊 Analytics Dashboard: Track debugging patterns and improvements
- 🌍 Multi-language Support: Support for non-English conversations
- 🎨 Customizable Personality: Adjust DUCK-E's communication style
Contributions are welcome! This project is about making debugging more collaborative and accessible.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Add new tool functions (database queries, git operations, etc.)
- Improve the web interface
- Add support for different OpenAI models
- Create IDE plugins
- Improve error handling and logging
- Add automated tests
This project is licensed under the MIT License - see the LICENSE file for details.
- Andrew Hunt & David Thomas for introducing rubber duck debugging in The Pragmatic Programmer
- OpenAI for the Realtime API and GPT models
- Microsoft AutoGen team for the agent framework
- FastAPI and Uvicorn communities for excellent tools
For issues, questions, or suggestions:
- 🐛 Bug Reports: Open an issue on GitHub
- 💡 Feature Requests: Start a discussion
- 📧 Contact: [Your contact information]
Remember: Every great developer has talked to a rubber duck. Now it's time for the duck to talk back. 🦆✨
"The best debugging sessions are conversations, not monologues."
