TaxAssist: full working release - light UI, email-approval agent runs, Drive/Sheets artifacts, per-user Google OAuth, Cloud Run deploy

- React frontend (light institutional design): landing page, dashboard, profile workspace with live agent activity, transparency panel, Drive/Sheets quick access
- Real human-in-the-loop: agent emails extracted figures, resumes on CONFIRM reply
- Agent creates a real Drive folder + results Sheet per profile and links them
- Per-user Google OAuth (web client) with encrypted tokens in the control plane
- Single-container Dockerfile (frontend baked in), Cloud Run deploy script
- Profile-created email notifications; cache and account-switch fixes

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: NihalMouni29

.dockerignore

@@ -0,0 +1,22 @@
+.git
+.github
+**/__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+venv
+.venv
+.env
+env.txt
+credentials.json
+client_secret.json
+token.json
+docs
+*.md
+mongodb-mcp
+frontend/node_modules
+frontend/dist
+app/static
+*.db
+.backend.log
+.oauth.log

.env.example

@@ -0,0 +1,45 @@
+# ── TaxAssist environment ─────────────────────────────────────────────────────
+# Copy to .env (gitignored) and fill in. 🔑 = secret, never commit.
+# Generate secrets:
+#   AGENT_SECRET_KEY   : python -c "import secrets; print(secrets.token_hex(32))"
+#   CONTROL_ENC_KEY    : python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+#   MONGODB_MCP_TOKEN  : python -c "import secrets; print(secrets.token_hex(24))"
+
+# ── Data plane (MongoDB Atlas + partner MCP server) ──
+MONGO_URI=mongodb+srv://USER:PASS@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority   # 🔑
+MONGODB_MCP_URL=http://mongodb-mcp:3000/mcp        # http://127.0.0.1:3000/mcp for local
+MONGODB_MCP_TOKEN=                                 # 🔑 static bearer (non-Cloud-Run)
+MONGODB_MCP_USE_IAM=                               # 1 on Cloud Run: use Google IAM ID tokens instead
+MONGODB_DB=tax_agent_db
+
+# ── Control plane (Postgres) + queue (Redis) ──
+POSTGRES_URL=postgresql+psycopg://tax:PASS@postgres:5432/tax_control   # 🔑 (omit -> SQLite dev)
+REDIS_URL=redis://redis:6379/0
+
+# ── Gemini ──
+GOOGLE_API_KEY=                                    # 🔑 Gemini API key (GEMINI_API_KEY also works)
+ORCHESTRATOR_MODEL=gemini-2.0-flash                # optional
+
+# ── Security ──
+AGENT_SECRET_KEY=                                  # 🔑 gateway HMAC
+AGENT_REQUIRE_SIGNATURE=1                           # 1 in prod (signed-request mode)
+CONTROL_ENC_KEY=                                   # 🔑 Fernet key (encrypts OAuth tokens)
+POLL_TOKEN=                                         # 🔑 guards /internal/poll (free-tier external cron)
+
+# ── Frontend (React) + Firebase auth ──
+FRONTEND_ORIGINS=http://localhost:5173,https://your-app.web.app   # CORS allow-list
+FIREBASE_PROJECT_ID=                               # verifies the frontend's Firebase ID token
+
+# ── Google OAuth client file (per-user web flow in prod) ──
+GOOGLE_CREDENTIALS_FILE=/etc/secrets/credentials.json   # Render Secret File path; defaults to ./credentials.json
+# GOOGLE_TOKEN_FILE=./token.json                   # single-user dev fallback only
+
+# ── Agent Engine deploy (only for `python -m app.orchestrator.agent_engine`) ──
+GOOGLE_CLOUD_PROJECT=
+GOOGLE_CLOUD_LOCATION=us-central1
+AGENT_ENGINE_STAGING_BUCKET=gs://your-staging-bucket
+
+# ── Deferred / dev-only ──
+# GWORKSPACE_MCP_URL=                              # leave unset (Phase 3b deferred)
+# USER_EMAIL=                                      # single-operator dev fallback only
+# Note: per-profile Drive folder / Sheet IDs live in Postgres (profiles table), NOT here.

.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI/CD
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  # (1) PRs + any push: lint + tool-schema gate + fully-mocked tests. NEVER deploys.
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -r requirements.txt
+      - run: pip install ruff pytest
+      - name: Lint
+        run: ruff check app
+      - name: Tool-schema compatibility gate (blocks breaking tool-contract changes)
+        run: python scripts/check_tool_schema.py
+      - name: Tests (all MongoDB + Google calls mocked)
+        run: pytest app/tests -q
+
+  # (2) Merge to main -> auto-deploy to Staging.
+  deploy-staging:
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment: staging
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build & deploy to staging
+        run: |
+          echo "Build images, push to registry, deploy to Cloud Run (staging),"
+          echo "and update the Vertex AI Agent Engine staging agent."
+          # gcloud auth + builds submit + run deploy + python -m app.orchestrator.agent_engine
+
+  # (3) GitHub Release OR manual dispatch -> Production, behind manual approval.
+  deploy-production:
+    needs: test
+    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment: production   # configure a required-reviewers protection rule on this env
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build & deploy to production
+        run: |
+          echo "Deploy to Cloud Run (prod) + Vertex AI Agent Engine (prod)."
+          # gcloud builds submit + run deploy + agent_engine deploy

.gitignore

@@ -0,0 +1,34 @@
+.env
+env.txt
+venv/
+uploads/
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+# Google OAuth secrets — never commit these
+credentials.json
+client_secret.json
+token.json
+*.zip
+*.db
+mock_drive/
+**/mock_drive/
+temp/
+**/temp/
+*.png
+*.pdf
+*.docx
+structure.txt
+**/.adk/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+
+# Runtime artifacts
+.ocr_findings.json
+demo_run.log
+*.log
+.oauth.log
+app/static/

CLAUDE.md

@@ -0,0 +1,41 @@
+# CLAUDE.md - Tax Automation Agent (Gemini / Google Cloud Agent Builder)
+
+## Project Overview
+This repository contains a functional, multi-step autonomous agent powered by Gemini and Google Cloud Agent Builder. The agent streamlines personal tax workflows by integrating State Management, Google Workspace (Gmail, Calendar, Drive, Sheets), and a deterministic tax calculator supporting ITR-1 and ITR-2 forms.
+
+---
+
+## System Workflow & Tool Execution
+
+### 1. State Management (Mandatory First Step)
+- **Rule:** Before initiating *any* task, the agent must query the State Management MCP server to check current task flags, execution history, and unmet dependencies.
+- **Rule:** The agent state is strictly isolated. State transitions must be written immediately back to the State Management MCP upon step completion.
+
+### 2. Communication & Document Pipeline
+- **Google Drive:** Used as the primary shared medium for all file tasks (e.g., document uploads, PDFs).
+- **Google Sheets:** Acts as the interaction UI for unvouched transaction values (real estate amounts, gold deals, etc.).
+- **Gmail & Calendar:** Used strictly for sending verification requests, action reminders, and file upload prompts to the user.
+
+### 3. Deterministic Tax Calculator (ITR-1 & ITR-2)
+- **Constraint:** The tax calculator tool must only be executed after the agent confirms via the State Management MCP that all user inputs and documentation requirements are fully met.
+- **Data Grounding:** For all tax-related logic, parameters, and computations, the system must strictly rely on the official government data source: https://www.incometaxindia.gov.in/ (it should be deterministic and should not use an ai agent)
+
+---
+
+## Security & Data Protection Guardrails
+
+### 1. PII Anonymization (Gateway Pattern)
+- **Data Isolation:** The agent must never ingest raw personally identifiable information (PII). 
+- **Inbound Data:** All data coming from Google Sheets/Drive must pass through the local gateway logic to replace names, PANs, and tracking info with synthetic tokens.
+- **Outbound Data:** The agent generates outputs using synthetic tokens. The local execution layer reconstructs the personal data immediately prior to final Google Sheet/Gmail updates.
+
+### 2. Authorization Limits
+- **Strict Scope:** The agent is forbidden from executing tasks outside the predefined State Management workflow. 
+- **Zero Drift:** If an ambiguous step is encountered, the agent must halt execution and issue a clarification request via Gmail.
+
+---
+
+## Development Environment & Resources
+- **Tech Stack:** Gemini API, Google Cloud Agent Builder, Node.js/Python, MongoDB.
+- **Credentials:** All runtime configurations, MongoDB connection uris, and Google OAuth keys are read strictly from the root `.env` file. Never commit these keys.
+- **License:** Distributed under an open-source license. Ensure the license file remains visible in the repository's About section.

Dockerfile

@@ -0,0 +1,30 @@
+# syntax=docker/dockerfile:1
+# Single-container TaxAssist: builds the React frontend, then serves it from FastAPI
+# alongside the API. One image, one Cloud Run / Render service.
+
+# ── 1. Build the React frontend ──────────────────────────────────────────────
+FROM node:20-slim AS frontend
+WORKDIR /frontend
+COPY frontend/package*.json ./
+RUN npm ci
+COPY frontend/ ./
+# Same-origin API in production (BASE defaults to "" → calls go to "/me" on this server).
+RUN npm run build
+
+# ── 2. Install Python deps ───────────────────────────────────────────────────
+FROM python:3.12-slim AS builder
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir --prefix=/install -r requirements.txt
+
+# ── 3. Runtime ───────────────────────────────────────────────────────────────
+FROM python:3.12-slim
+WORKDIR /app
+ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
+COPY --from=builder /install /usr/local
+COPY app ./app
+# Bundle the built SPA so FastAPI can serve it at "/".
+COPY --from=frontend /frontend/dist ./app/static
+EXPOSE 8080
+# Honors Cloud Run's injected $PORT (defaults to 8080).
+CMD uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8080} --proxy-headers --forwarded-allow-ips=*