From cf92a9b1b944f182989a2e969f0ddfd1b319ea2f Mon Sep 17 00:00:00 2001 From: SectumpSempra Date: Thu, 30 Apr 2026 02:29:58 +0530 Subject: [PATCH] Igniters - Week 4 - Alex financial planner multi agent on GCP --- .../a3_igniters_amitb/week4_final_exercise.md | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 community_contributions/a3_igniters_amitb/week4_final_exercise.md diff --git a/community_contributions/a3_igniters_amitb/week4_final_exercise.md b/community_contributions/a3_igniters_amitb/week4_final_exercise.md new file mode 100644 index 00000000..8b2da3eb --- /dev/null +++ b/community_contributions/a3_igniters_amitb/week4_final_exercise.md @@ -0,0 +1,65 @@ +# Week 4 Final Exercise - Alex: AI Financial Planner (Multi-Agent) + +**Repository:** https://github.com/SectumPsempra/production/tree/week3-exercise-local/alex_financial_planner/backend/agents +**Deployed App:** https://alex-frontend-ajg5nndceq-uc.a.run.app + +--- + +## What is Being Built + +Alex is a cloud-native AI financial planning assistant built on a **multi-agent architecture**. Users sign in, register their investment accounts and holdings, and trigger a portfolio analysis. Rather than a single LLM call, the work is broken across five specialised agents that run concurrently, each with a focused responsibility. The results are stitched together by a Planner agent and written back to the database for the frontend to display. + +A sixth agent - the Researcher - runs on a separate Cloud Run service on a scheduled basis, autonomously browsing the web and writing market research into a vector knowledge base. That knowledge base is retrieved at analysis time to ground the report in current financial context. + +--- + +## The Six Agents + +| Agent | Responsibility | +|---|---| +| **Planner** | Orchestrates the pipeline: loads portfolio data, fans out to the four specialist agents in parallel, merges results, writes the completed job to the database | +| **Instrument Tagger** | Classifies each holding by asset class, sector, and region using an LLM with structured output (Pydantic schema) | +| **Report Writer** | Generates the full written portfolio analysis, pulling relevant context from the pgvector knowledge base via semantic search | +| **Chart Maker** | Produces structured JSON describing allocation charts (asset class, region, sector breakdowns) ready for the frontend to render | +| **Retirement Specialist** | Projects retirement income based on current portfolio value, expected return, years to retirement, and withdrawal rate | +| **Researcher** | Runs on a schedule (every 2 hours via Cloud Scheduler), searches the web for relevant financial news, and stores embeddings into the knowledge base for retrieval by the Report Writer | + +--- + +## Architecture and Services + +| Layer | GCP Service Used | AWS Equivalent | +|---|---|---| +| Frontend (Next.js) | Cloud Run | Elastic Beanstalk / App Runner | +| REST API (FastAPI) | Cloud Run | API Gateway + Lambda / App Runner | +| Agents Worker - 5 agents (FastAPI) | Cloud Run | ECS Fargate | +| Researcher Agent (FastAPI) | Cloud Run (separate service) | ECS Fargate | +| Job Queue | Cloud Tasks | SQS | +| Scheduled Research Trigger | Cloud Scheduler | EventBridge Scheduler | +| Relational Database | Cloud SQL (PostgreSQL) | RDS PostgreSQL | +| Vector Store | pgvector extension on Cloud SQL | RDS + pgvector or OpenSearch | +| Secrets | Secret Manager | Secrets Manager | +| Container Registry | Artifact Registry | ECR | +| Authentication | Clerk (third-party, same on both) | Cognito | +| LLM Calls | OpenRouter API | Amazon Bedrock | +| Embeddings | OpenAI text-embedding-3-small | Amazon Titan Embeddings | + +--- + +## How it Works End-to-End + +1. The user logs in via Clerk and views their portfolio on the Next.js frontend (Cloud Run). +2. They click "Run Analysis". The frontend calls the FastAPI REST API. +3. The API creates a `pending` job record in Cloud SQL, then enqueues a task to **Cloud Tasks** (analogous to SQS). The response returns immediately with the job ID. +4. Cloud Tasks invokes the **Agents Worker** service with an OIDC-authenticated HTTP POST. +5. The **Planner** agent loads the user's full portfolio from Cloud SQL, then fans out to the four specialist agents concurrently using `asyncio.gather`: + - Instrument Tagger classifies all holdings. + - Report Writer retrieves relevant research from the pgvector knowledge base via cosine similarity search, then writes the full analysis. + - Chart Maker generates chart-ready JSON for the UI. + - Retirement Specialist calculates projected income. +6. The Planner merges all results and writes them back to the `jobs` table with status `completed`. +7. The frontend polls the API every 4 seconds until the job is complete, then renders the report, charts, and retirement projection. + +In parallel, the **Researcher** service runs every 2 hours via **Cloud Scheduler**. It searches financial news sources, scrapes article text, generates embeddings via the OpenAI embeddings API, and stores them in the `knowledge_base` table - keeping the Report Writer's context current without any manual intervention. + +All six services are containerised with Docker (`linux/amd64` for Cloud Run compatibility) and the entire infrastructure is defined in Terraform across four modules: database, researcher, agents, and frontend+API.