agentic-google-workspace-orchestrator

# Agentic Google Workspace Orchestrator A secure, multi-service orchestration platform for Gmail, Google Calendar, and Google Drive. This repository combines: - FastAPI backend with PostgreSQL + `pgvector` and Redis - Next.js chat and orchestration frontend - Hybrid retrieval across full-text search, semantic embeddings, and Reciprocal Rank Fusion (RRF) - Typed execution plan DAG generation and Python-controlled action gating - Google OAuth sync for Gmail, Calendar, and Drive data ## What this project does The system can: - classify user intent and extract structured entities from natural language - execute parallel search across Gmail, Calendar, and Drive - generate safe workflow plans using a type-driven LLM + Python validator - gate mutating actions behind explicit confirmation - persist conversations, orchestration state, and audit records - provide an interactive frontend + OpenAPI backend docs ## Architecture Overview Primary components: - `app/main.py` — FastAPI application entrypoint, CORS, middleware, health endpoints - `app/api/` — REST routers for auth, sync, search, query, actions, orchestration, and conversations - `app/orchestration/` — intent classification, planning, validation, execution, and confirmation flow - `app/retrieval/` — hybrid search implementation using PostgreSQL FTS, pgvector embeddings, and RRF fusion - `app/models/` — SQLAlchemy model definitions for users, workspace items, orchestration runs, and pending actions - `frontend/` — Next.js UI for conversation-driven orchestration and action confirmation

A secure, multi-service orchestration platform for Gmail, Google Calendar, and Google Drive.

• ```text
• Host Machine:
• ├─ Next.js frontend http://localhost:3000
• ├─ FastAPI backend http://localhost:8000
• ├─ PostgreSQL + pgvector localhost:5432
• └─ Redis localhost:6379
• ```
• ## Prerequisites
• Python 3.12+
• Node.js 20+ and `pnpm`
• Docker Engine + Docker Compose
• Google Cloud OAuth application credentials
• OpenRouter API key
• ## Quick Start
• 1. Install Python and frontend dependencies:
• ```bash
• uv sync
• cd frontend && pnpm install && cd ..
• ```
• 2. Copy the example environment variables:
• ```bash
• cp .env.example .env
• ```
• 3. Update `.env` with your credentials:
• ```ini
• DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/orchestrator
• REDIS_URL=redis://localhost:6379/0
• OPENROUTER_API_KEY=sk-or-v1-...
• OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
• LLM_MODEL=openai/gpt-oss-120b:free
• EMBEDDING_MODEL=nvidia/llama-nemotron-embed-vl-1b-v2:free
• GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
• GOOGLE_CLIENT_SECRET=your-client-secret
• GOOGLE_REDIRECT_URI=http://localhost:8000/api/v1/auth/google/callback
• CORS_ORIGINS=http://localhost:3000
• FRONTEND_URL=http://localhost:3000
• NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
• ```
• > Google OAuth Redirect URI must be configured as:
• > `http://localhost:8000/api/v1/auth/google/callback`
• 4. Start the app:
• ```bash
• make dev
• ```
• ## Common commands
• ```bash
• make infra # start PostgreSQL + Redis only
• make migrate # apply Alembic migrations
• make backend # run backend on port 8000
• make frontend # run frontend on port 3000
• make test # run backend tests + frontend build check
• make benchmark # run hybrid retrieval benchmark
• make clean # remove local caches
• make reset # destroy local PostgreSQL/Redis volumes
• ```
• ## API and user-facing endpoints
• Frontend UI: `http://localhost:3000`
• Backend API: `http://localhost:8000`
• OpenAPI: `http://localhost:8000/docs`
• Health probe: `GET /health`
• Readiness probe: `GET /ready`
• Detailed API reference is available in `API.md`.
• ## Project documentation
• `API.md` — API reference and endpoint examples
• `DEMO.md` — demo script and evaluation query guidance
• `DESIGN.md` — system architecture, ER diagram, and scaling rationale
• `SAMPLE_QUERIES.md` — sample orchestrator prompts and expected behavior
• `RETRIEVAL_EVAL.md` — retrieval evaluation methodology and metrics
• ## Security and responsible use
• This project uses OAuth tokens and API keys. Keep credentials private and never commit them to source control.
• For vulnerability reporting, see `SECURITY.md`.
• ## Contribution guide
• Contributions are welcome. Please read `CONTRIBUTING.md` before opening issues or pull requests.
• ## License
• This project is licensed under the MIT License. See `LICENSE` for details.