TaxAssist – Agente Autônomo de Imposto de Renda
HR-coding/TaxAssist
Agente autônomo para declaração de imposto de renda indiano com OCR e confirmação por email
Ver no GitHubMCP server que automatiza o preenchimento de ITR-1 e ITR-2 (Índia) usando Gemini com arquitetura security-first. Lê documentos do Google Drive, confirma valores por email (human-in-the-loop) e calcula impostos de forma determinística a partir de alíquotas oficiais, sem risco de manipulação de dados sensíveis.
Instalação
npx convez-ai HR-coding/TaxAssist1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de preenchimento de formulários ITR-1 e ITR-2 para contribuintes indianos
- Extração OCR segura de documentos fiscais (Form 16, comprovantes) via Drive
- Fluxos multi-tenant com isolamento de dados e PII tokenizada
Veredito

Solução robusta e altamente especializada para conformidade fiscal indiana, com arquitetura de segurança exemplar (3-way handshake, PII vault, guards in-process). Excelente referência de MCP server em Python com integração Google Cloud + MongoDB, mas nicho restrito ao mercado indiano.
README
A tradução para o português deste README ainda está na fila.
TaxAssist
An autonomous, multi-user Indian Income Tax filing assistant (ITR-1 & ITR-2) powered by Gemini on Google Cloud Agent Builder, with MongoDB (via the official MongoDB MCP server) as the data layer.
The agent reads a taxpayer's documents from Google Drive, extracts the figures with Gemini vision OCR, asks the user to confirm over email (human-in-the-loop), computes tax deterministically from official slab rates, and writes the results back to Google Sheets — all under a strict, security-first architecture where the AI is treated as untrusted and can never tamper with tax data or leak personal information.
Architecture details: see SYSTEM_ARCHITECTURE.md.
What it does
- Drive → OCR: detects documents (Form 16, etc.), converts to PDF, extracts figures with Gemini 2.5-flash vision (handles dense tables and scans).
- Human-in-the-loop over email: emails the user to confirm extracted values / approve computation; reads the replies and resumes — as durable, resumable runs.
- Deterministic tax engine: ITR-1 & ITR-2 computed from gov slab rates (no LLM in the math), old vs new regime comparison.
- Google Workspace: Gmail, Calendar (deadline reminders), Sheets (findings + result), Drive — per user.
- Multi-tenant: one account → many profiles (e.g. self + spouse), each isolated.
Tech stack
| Layer | Tech |
|---|---|
| Agent | Gemini (2.0/2.5-flash) via Google ADK → Vertex AI Agent Engine |
| Data plane | MongoDB Atlas via the MongoDB MCP server (partner) |
| Control plane | PostgreSQL (users, profiles, encrypted tokens, feedback) |
| Queue | Redis + RQ (async runs) |
| API | FastAPI |
| OCR | Gemini vision + pdfplumber |
No competing AI or cloud services are used.
Security highlights
- 3-way handshake gateway (HMAC identity + state-gated authorization + intent reconciliation + payload sanitization; optional signed-request mode).
- PII vault — personal data is tokenized before the AI ever sees it; reconstructed only in the local layer for outbound writes.
- In-process guards — the agent cannot escalate the workflow or write fabricated tax data (provenance-checked); document registration is system-only.
- Strict email format — internal field keys / code never appear in emails (see
app/core/email_format.py). - Tenant isolation — every data access is validated against profile ownership.
Setup
- Install:
pip install -r requirements.txt - Env: copy
.env.example→.envand fill it (generation commands are in the file). Minimum to boot:MONGO_URI,GOOGLE_API_KEY,AGENT_SECRET_KEY,CONTROL_ENC_KEY(+POSTGRES_URLfor the control plane; omit for SQLite dev). - Google OAuth: place
credentials.jsonat the root (or setGOOGLE_CREDENTIALS_FILE). Production uses per-user web OAuth with tokens encrypted in Postgres. - MongoDB MCP server (optional locally; required for partner integration at runtime):
export MDB_MCP_CONNECTION_STRING="$MONGO_URI" npx -y mongodb-mcp-server --transport http --httpPort 3000 # then set MONGODB_MCP_URL=http://127.0.0.1:3000/mcp in .env
Run (local)
uvicorn app.main:app --reload # API + gateway
rq worker -u $REDIS_URL tax-agent # async run worker (if REDIS_URL set)
Test
pytest app/tests -q
165 tests — unit/, integration/, security/ — all MongoDB & Google calls mocked
(hermetic). Tool-contract gate: python scripts/check_tool_schema.py.
Deploy
- Agent → Vertex AI Agent Engine:
python -m app.orchestrator.agent_engine(setGOOGLE_CLOUD_PROJECT,GOOGLE_CLOUD_LOCATION,AGENT_ENGINE_STAGING_BUCKET). - Backend → Docker (
Dockerfile) → Google Cloud Run (app +mongodb-mcp/service). - CI/CD →
.github/workflows/ci.yml: PRs run lint + tool-schema gate + tests;main→ staging; release/dispatch → production (manual approval).