Real-Time Voice AI Assistant na may Function Calling & Bidirectional Audio Streaming

Binuo namin ang isang real-time voice AI assistant na pinapagana ng Google's Gemini Live API na may native audio capabilities, custom function calling para sa domain-specific calculations, at isang React frontend na may WebSocket-based audio streaming.

Arkitektura

• AI Model: Gemini na may native audio input/output at function calling
• Backend: Python/FastAPI na may WebSocket endpoint para sa bidirectional audio
• Audio Pipeline: PyAudio para sa microphone/speaker I/O na may real-time streaming
• Frontend: React na may Vite at Tailwind CSS para sa session control UI
• Communication: WebSocket para sa low-latency JSON messaging at binary audio transport
• Multimodal: Opsyonal na camera at screen capture para sa visual context

Real-Time Audio Pipeline

Bidirectional Streaming

Ang sistema ay nagpapanatili ng tuloy-tuloy na audio streams sa parehong direksyon:

• Input: Microphone audio na nakukuha sa 16kHz mono, hinahati sa maliliit na frames, at ini-stream sa AI model sa real-time
• Output: AI-generated speech na natatanggap sa 24kHz at agad na pinapatugtog sa mga speaker
• No Batching: Ang mga audio chunks ay ipinapadala habang kinukuha — walang accumulation delays
• Interrupt Handling: Maaaring i-interrupt ng user ang assistant sa kalagitnaan ng tugon nang natural

Audio Processing

• 16-bit PCM format para sa parehong input at output
• Magkahiwalay na sample rates na optimized para sa pagsasalita (16kHz capture, 24kHz playback)
• Maliit na buffer sizes para sa minimal na latency
• Tuloy-tuloy na streaming na walang start/stop gaps sa pagitan ng mga pagliko

Function Calling Integration

Paano Ito Gumagana

Ang AI model ay maaaring mag-imbita ng lokal na mga Python function sa kalagitnaan ng pag-uusap kapag kinakailangan ang domain-specific calculations:

1. Nagsasalita ang user ng isang kahilingan (hal., "I missed lunch today")
2. Ang AI model ay nagta-transcribe at nauunawaan ang intensyon
3. Tinutukoy ng model na kinakailangan ang isang function call at nagpapadala ng structured request
4. Inilalabas ng backend ang pangalan ng function, mga argumento, at call ID
5. Isinasagawa ng lokal na function ang domain calculation
6. Ipinapadala ang resulta pabalik sa model bilang isang structured response
7. Ang model ay bumubuo ng natural na wika na tugon sa boses na isinama ang resulta

Domain Functions

Ang sistema ay sumusuporta sa nutrition-focused function calling para sa mga senaryo tulad ng:

• Missed Meals — Muling ipinamamahagi ang mga na-miss na macronutrients sa natitirang mga pagkain
• Unplanned Food — Inaayos ang mga paparating na pagkain upang mabawi ang hindi inaasahang intake
• Meal Substitutions — Pinapalitan ang mga sangkap habang pinapanatili ang mga macro target
• Activity Tracking — Tinatantya ang calorie burn at inaayos ang nutrition buffer

Bawat function ay gumagamit ng macro database na may per-food nutritional profiles at nagsasagawa ng dynamic calculations na may bahagyang stochastic variation para sa natural-feeling na mga tugon.

Execution Safety

• Ang input ng mikropono ay pinapahinto sa panahon ng function execution upang maiwasan ang overlap
• Ang mga pending audio frames ay itinatapon upang maiwasan ang stale context
• Ang mga error responses ay ipinapadala pabalik nang maayos kung nabigo ang function execution
• Ang normal na streaming ay agad na nagreresume pagkatapos ng function completion

Backend Architecture

FastAPI WebSocket Server

• Isang WebSocket endpoint para sa lahat ng client communication
• Session lifecycle management (start, stop, ping/pong health checks)
• Isang aktibong session lamang sa isang pagkakataon na may session locking
• CORS middleware para sa mga development environments
• Health check endpoint para sa monitoring

Session Management

• Ang mga session ay nilikha sa client connect na may mode selection (audio-only, camera, o screen)
• Ang mga background async tasks ay humahawak ng audio capture, processing, at playback nang sabay-sabay
• Maayos na disconnection na may resource cleanup
• API key validation at error propagation

Multimodal Input (Opsyonal)

Higit pa sa boses, ang sistema ay sumusuporta sa opsyonal na visual context:

• Camera Mode — Nag-stream ng webcam frames (1fps) para sa visual context sa mga pag-uusap
• Screen Mode — Kinukuha ang screen content para sa pagtalakay ng on-screen information
• Ang mga imahe ay nire-resize at kinokompress bago ipadala
• Ang visual context ay nagpapahusay sa kakayahan ng AI na magbigay ng mga kaugnay na tugon

Frontend Interface

• Session Control — Simulan/ihinto ang pakikinig na may malinaw na status indicators
• Status Display — Real-time na koneksyon at session state (idle, connecting, active, error)
• Theme Support — Light/dark mode na may persistence
• Guided Walkthrough — Step-by-step demo para sa mga unang beses na user
• WebSocket Management — Automatic reconnection logic

AI Model Configuration

• Native audio modality (walang hiwalay na STT/TTS pipeline)
• Configurable voice selection mula sa maraming preset voices
• System instructions na nagtatakda ng assistant personality, response style, at language handling
• Tool definitions para sa lahat ng available functions na may parameter schemas
• Automatic language detection na may same-language response

Key Features

1. Sub-Second Latency — Native audio model na nag-aalis ng STT/TTS pipeline overhead
2. Real-Time Bidirectional Audio — Tuloy-tuloy na streaming na may < 50ms per-chunk latency
3. Function Calling — Domain-specific calculations na isinasagawa sa kalagitnaan ng pag-uusap
4. Natural Interruption — Maaaring i-interrupt ng mga user ang assistant nang natural na walang espesyal na commands
5. Multi-Language — Automatic language detection na may same-language responses
6. Multimodal Input — Opsyonal na camera at screen context para sa visual understanding
7. Session Management — Session lifecycle control na may locking at resource cleanup
8. Macro Calculations — Dynamic nutritional adjustments na may per-food macro profiles
9. Error Recovery — Maayos na paghawak ng function failures at network interruptions
10. Extensible — Bagong functions na idinadagdag sa pamamagitan ng pagde-define ng schema at handler — walang pagbabago sa arkitektura