README.md

metadata

title: Oppy
emoji: ✨
colorFrom: blue
colorTo: green
sdk: docker
app_port: 8000
pinned: false
license: mit
short_description: AI Voice Assistant for Multi-Project Management

Oppy — AI Voice Assistant for Multi-Project Management

Oppy is a voice-first AI assistant built on Google's Gemini ecosystem. It helps students and professionals juggling multiple projects (school, work, startup) stay on top of everything through natural voice conversation.

What it does

Oppy connects to your Gmail and Google Calendar, analyzes urgency across all your projects, and talks to you like a direct, caring mentor. Ask it about your schedule, your emails, or what to prioritize — it answers with actionable advice.

Key features:

• Voice conversation powered by Gemini 3 Flash (chat) and Gemini 2.5 Flash TTS (speech)
• Wake word activation — say "Oppy" to start hands-free
• Animated SVG avatar with eye tracking, blinking, and mouth animation
• Real Gmail and Google Calendar integration via OAuth 2.0
• Expandable project cards with direct action links
• Gemini-inspired UI (Google Sans, white theme, Google color palette)

Tech stack

Layer	Tech
Backend	Python, FastAPI, SSE streaming
AI	Gemini 3 Flash (chat + function calling), Gemini 2.5 Flash Preview TTS
Frontend	React 18, Vite, Web Speech API
APIs	Gmail API, Google Calendar API, Google Docs API
Auth	Google OAuth 2.0

How to use

1. Open the app — Oppy's avatar appears
2. Click the orb to authorize your microphone
3. Once the green "Micro actif" dot appears, say "Oppy" or click again
4. Ask anything: "What's my schedule today?", "Tell me about Sophie's email", "What should I prioritize?"
5. Oppy answers vocally and listens for your next question

API endpoints

Method	Path	Description
POST	/api/chat	Send a message, get SSE streamed response
POST	/api/tts	Convert text to speech (WAV audio)
GET	/api/run	Run the operator pipeline (SSE)
GET	/api/project/{id}/sources	Get emails, events, signals for a project
GET	/api/auth/status	Check Google OAuth status
GET	/api/auth/login	Start Google OAuth flow
GET	/api/health	Health check

Environment variables

Set these as HuggingFace Space secrets:

Variable	Description
GOOGLE_API_KEY	Google AI API key from AI Studio

License

MIT