Add GCP deployment alternative for Alex Multi-Agent SaaS - Joshua (Andela's GenAI Bootcamp)

gcp-deployment/.env.example

@@ -0,0 +1,93 @@
+# Alex (GCP) - Environment Variables
+# Copy to .env and fill with your deployment values
+
+# ============================================================
+# Core GCP project settings
+# ============================================================
+PROJECT_ID=alex-multi-agent-saas-xxxxxx
+GCP_PROJECT_ID=alex-multi-agent-saas-xxxxxx
+GCP_REGION=us-central1
+
+# ============================================================
+# LLM configuration (Gemini 2.0 Flash by default)
+# ============================================================
+LLM_PROVIDER=vertex_ai           # vertex_ai | openai
+VERTEX_AI_MODEL=vertex_ai/gemini-2.0-flash-exp
+OPENAI_MODEL=openai/gpt-4o-mini
+OPENAI_API_KEY=
+OPENAI_API_BASE=
+
+# Optional per-agent overrides (leave blank to use defaults)
+PLANNER_MODEL=
+REPORTER_MODEL=
+REPORTER_JUDGE_MODEL=
+RETIREMENT_MODEL=
+CHARTER_MODEL=
+TAGGER_MODEL=
+RESEARCHER_MODEL=
+
+# ============================================================
+# Vertex AI training artifacts (Guide 2 outputs)
+# ============================================================
+MODEL_ARTIFACTS_BUCKET=
+TRAINING_DATA_BUCKET=
+TENSORBOARD_NAME=
+ANTHROPIC_API_KEY_SECRET_ID=
+OPENAI_API_KEY_SECRET_ID=
+
+# ============================================================
+# Ingestion / vectors (Guide 3)
+# ============================================================
+VECTOR_BUCKET=
+ALEX_API_ENDPOINT=
+ALEX_API_KEY=
+
+# ============================================================
+# Researcher service (Guide 4)
+# ============================================================
+POLYGON_API_KEY=
+POLYGON_PLAN=free
+
+# ============================================================
+# Database (Guide 5 - Cloud SQL)
+# ============================================================
+DATABASE_NAME=alex
+DATABASE_USER=alex_app
+INSTANCE_CONNECTION_NAME=
+DB_PASSWORD_SECRET_ID=
+DB_CONNECTION_STRING_SECRET_ID=
+PRIVATE_IP_ADDRESS=
+VPC_NETWORK_ID=
+VPC_SUBNET_ID=
+
+# ============================================================
+# Agents (Guide 6)
+# ============================================================
+TAGGER_FUNCTION=alex-tagger
+REPORTER_FUNCTION=alex-reporter
+CHARTER_FUNCTION=alex-charter
+RETIREMENT_FUNCTION=alex-retirement
+MOCK_LAMBDAS=false
+CLOUD_RUN_SERVICE_ACCOUNT_EMAIL=
+SQS_QUEUE_URL=
+
+# ============================================================
+# Frontend & API (Guide 7)
+# ============================================================
+FRONTEND_URL=http://localhost:3000
+CLOUDFRONT_URL=
+CLERK_JWKS_URL=
+CLERK_ISSUER=
+
+# ============================================================
+# Observability / misc
+# ============================================================
+LANGFUSE_PUBLIC_KEY=
+LANGFUSE_SECRET_KEY=
+LANGFUSE_HOST=https://cloud.langfuse.com
+
+# ============================================================
+# Legacy AWS compatibility (remove once not needed)
+# ============================================================
+DEFAULT_AWS_REGION=us-east-1
+SAGEMAKER_ENDPOINT=

gcp-deployment/.gitignore

@@ -0,0 +1,71 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+.venv
+*.egg-info/
+dist/
+build/
+*.egg
+# UV
+uv.lock
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Terraform
+*.tfstate
+*.tfstate.*
+.terraform/
+.terraform.lock.hcl
+terraform.tfvars
+*.tfvars
+!*.tfvars.example
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Secrets and credentials
+*.json
+!package.json
+!tsconfig.json
+!eslint.config.json
+*-terraform-key.json
+application_default_credentials.json
+service-account-*.json
+
+# Node
+node_modules/
+.next/
+out/
+
+# Docker
+*.dockerignore
+
+# Temporary files
+*.tmp
+*.bak
+*.backup
+
+# Local development
+Local Postgresql Kill and Start Commands.txt
+

gcp-deployment/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [Unreleased]
+
+### Fixed
+- **Missing pg8000 dependency in agent containers**: Fixed `ModuleNotFoundError: No module named 'pg8000'` in Reporter, Charter, and Retirement agents by explicitly installing the database package with all dependencies before syncing main project dependencies. See [guides/FIX_PG8000_DEPENDENCY.md](guides/FIX_PG8000_DEPENDENCY.md) for details.
+
+### Changed
+- Updated Dockerfiles for Reporter, Charter, and Retirement agents to explicitly install database package dependencies
+- Added troubleshooting section for pg8000 dependency issue
+
+### Files Modified
+- `backend/reporter/Dockerfile`
+- `backend/charter/Dockerfile`
+- `backend/retirement/Dockerfile`
+- `guides/TROUBLESHOOTING.md`
+- `guides/FIX_PG8000_DEPENDENCY.md` (new)
+

gcp-deployment/FIXES_APPLIED.md

@@ -0,0 +1,49 @@
+# Fixes Applied to GCP Deployment
+
+This document summarizes the fixes applied to resolve issues encountered during deployment.
+
+## Fix: Missing pg8000 Dependency
+
+### Issue
+Reporter, Charter, and Retirement agents were failing with:
+```
+ModuleNotFoundError: No module named 'pg8000'
+```
+
+This prevented agents from connecting to the Cloud SQL database, resulting in 500 Internal Server Error responses.
+
+### Root Cause
+The `pg8000` package is a transitive dependency of the `alex-database` package (required by Cloud SQL connector). When using `uv sync --no-install-project` with local path dependencies, transitive dependencies may not be installed correctly.
+
+### Solution
+Updated Dockerfiles to explicitly install the database package with all dependencies before syncing main project dependencies:
+
+```dockerfile
+# First install database package with all its dependencies (including pg8000)
+RUN cd database && uv pip install --system -e . && cd ..
+# Then sync the main project dependencies
+RUN uv sync --no-install-project
+```
+
+### Files Modified
+- `backend/reporter/Dockerfile`
+- `backend/charter/Dockerfile`
+- `backend/retirement/Dockerfile`
+
+### Documentation Added
+- `guides/FIX_PG8000_DEPENDENCY.md` - Detailed fix documentation
+- Updated `guides/TROUBLESHOOTING.md` - Added troubleshooting section
+- Updated `guides/6_agents.md` - Added Dockerfile example with fix
+- Updated `README.md` - Added reference to fix documentation
+
+### Verification
+After applying the fix:
+1. Rebuild Docker images
+2. Push to Artifact Registry
+3. Update Cloud Run services
+4. Verify no more `pg8000` errors in logs
+5. Test agent workflow end-to-end
+
+### Status
+✅ **Fixed and Verified** - All three agents now work correctly and can connect to the database.
+