How mohitxhkr/smart-scheduler works
Project type and purpose
• This is a full-stack “voice & text” scheduling assistant.
• It provides two frontends:
• Desktop/CLI voice agent (main.py + voice_agent.py + audio I/O libs)
• Web UI via Streamlit (app.py)
• It orchestrates speech-to-text (Whisper), intent understanding (OpenRouter LLM), date parsing, calendar integration (Google Calendar API), and text-to-speech (ElevenLabs).
File structure
• Top-level scripts:
• main.py – desktop entrypoint
• app.py – Streamlit web entrypoint
• Core modules:
• voice_agent.py – audio capture/playback and CLI loop
• llm_engine.py – OpenRouter LLM wrapper and intent extraction
• calendar_api.py – Google Calendar client and event creation
• calendar/date-parsing – uses dateparser & pytz (invoked in llm_engine or a helper)
• Config & dependencies:
• requirements.txt, .env for API keys, credentials.json for Google OAuth
README insights
• Pipeline stages are clearly defined (STT → NLU → parse → confirm → API call → TTS/UI feedback).
• Tech stack table highlights key libraries/services.
• Workflow section describes user interaction and sequencing.
Main components and their relationships
a. Frontend layer
• Voice/CLI frontend (main.py + voice_agent.py + sounddevice/pygame/scipy)
• Web frontend (app.py + Streamlit UI + chat history)
b. Application layer
• Orchestrator logic in main.py/app.py that drives the pipeline
c. Processing services
1. ASR Service – OpenAI Whisper
2. NLU/Intent Engine – OpenRouter via llm_engine.py
3. Date/Time Parser – dateparser & pytz (inline in llm_engine or helper)
4. Confirmation Flow – simple yes/no prompt in UI or voice
5. Calendar Integration – calendar_api.py talking to Google Calendar REST API
6. TTS Service – ElevenLabs
d. External services
• OpenRouter API
• Google Calendar API
• ElevenLabs TTS
• Whisper (local or OpenAI endpoint)
e. Configuration & Auth
• .env for LLM/TTS keys
• credentials.json for Google API
Architectural patterns & design principles
• Modular pipeline: each processing step is isolated in its own module
• Separation of concerns: UI layer vs. service layer vs. external integrations
• Single orchestrator per interface (desktop vs. web)
• Environment-driven configuration for secrets
Detail without over-complication
• Don’t merge ASR & LLM—show them as distinct processing steps.
• Both user pathways (voice vs. text) converging into the same pipeline.
• Keep the visual hierarchy: frontends on top, pipeline in middle, external services at edges, config store aside.