How juspay/clairvoyance works
Clairvoyance is a FastAPI multi-agent conversational platform. A user request enters an API router, which delegates to Breeze Buddy call management; calls are dispatched into a workflow-driven voice agent that runs speech recognition, an LLM, and speech synthesis while integrating with telephony. The repository also contains text chat, commerce assistance, knowledge-base, analytics, and evaluation capabilities. Several subsystem relationships are documented in the README or visible in the source index; unsampled implementations are represented at their supported directory paths, and uncertain links are omitted.
Main entry points: handlers.py Chat API · agent Voice agent · main.py FastAPI app · breeze_buddy Breeze Buddy API
Components 22
API and orchestration
- FastAPI app
app/main.py - Breeze Buddy API
app/api/routers/breeze_buddy - Call manager
app/ai/voice/agents/breeze_buddy/managers/calls.py - Call dispatch
app/ai/voice/agents/breeze_buddy/dispatch
Voice workflows
- Voice agent
app/ai/voice/agents/breeze_buddy/agent - Speech pipeline
app/ai/voice/agents/breeze_buddy/agent/pipeline.py - Telephony providers
app/ai/voice/agents/breeze_buddy/services/telephony - STT / LLM / TTS
app/ai/voice - Workflow templates
app/ai/voice/agents/breeze_buddy/template - DragonTTS cache
dragontts/app/cache/service.py
Chat and commerce
- Chat API
app/api/routers/breeze_buddy/chat/handlers.py - Chat turn engine
app/ai/voice/agents/breeze_buddy/chat/turn_core.py - Commerce assistance
app/ai/voice/agents/breeze_buddy/assist/commerce - Commerce widget
app/api/routers/breeze_buddy/widget/handlers.py
Knowledge and evaluation
- Knowledge base
app/services/knowledge_base - Analytics API
app/api/routers/breeze_buddy/analytics/handlers.py - Conversation evaluation
app/ai/voice/agents/breeze_buddy/services/evals
State and infrastructure
- Chat session store
app/database/accessor/breeze_buddy/chat_session.py - Redis
app/services/redis/client.py
Other components
- API caller
- Telephony network
- Chat / widget user
Connections 21
- API caller → FastAPI app: requests
README.md - FastAPI app → Breeze Buddy API: initializes routes
README.md - Breeze Buddy API → Call manager: delegates calls
README.md - Call manager → Call dispatch: dispatches calls
app/ai/voice/agents/breeze_buddy/dispatch/v2/routes.py - Call manager → Voice agent: launches agent
README.md - Voice agent → Speech pipeline: builds pipeline
app/ai/voice/agents/breeze_buddy/agent/pipeline.py - Speech pipeline → STT / LLM / TTS: uses speech services
app/ai/voice/agents/breeze_buddy/agent/pipeline.py - Voice agent → Telephony providers: manages calls
README.md - Telephony providers → Telephony network: connects calls
README.md - Voice agent → Workflow templates: runs workflows
app/ai/voice/agents/breeze_buddy/agent/pipeline.py - Chat / widget user → Chat API: sends messages
README.md - Chat API → Chat turn engine: invokes turns
app/api/routers/breeze_buddy/chat/handlers.py - Chat API → Chat session store: reads and writes
app/api/routers/breeze_buddy/chat/handlers.py - Chat API → Redis: locks sessions
app/api/routers/breeze_buddy/chat/handlers.py - Chat / widget user → Commerce widget: uses widget
README.md - Commerce widget → Chat turn engine: invokes turns
app/api/routers/breeze_buddy/widget/handlers.py - Commerce widget → Commerce assistance: uses commerce policy
app/api/routers/breeze_buddy/widget/handlers.py - Chat API → Knowledge base: queues analysis
app/api/routers/breeze_buddy/chat/handlers.py - Breeze Buddy API → Analytics API: serves analytics
app/api/routers/breeze_buddy/analytics/handlers.py - FastAPI app → Conversation evaluation: starts evaluation services
app/main.py - STT / LLM / TTS → DragonTTS cache: synthesizes via proxy