shayeeboy 的 Financial-Intelligence-Strategy-Agent：把加拿大公共数据变成银行零售策略简报

An autonomous business-intelligence agent that turns Canadian public demographic and housing data into executive retail-banking strategy briefs. It pulls live figures from Statistics Canada, CMHC, and the Bank of Canada, then synthesizes them into a structured brief that maps demographic and cost-of-living realities to specific banking product opportunities — served three ways: a hosted web generator, an MCP tool server, and a one-command CLI. Built as part of My AI Portfolio alongside the AI-Native Team Diagnostic and the Enterprise RAG Assistant.

Reports empirical trend realities only. It does not forecast interest rates or market crashes, and does not provide legal, compliance, or FINTRAC/Bank Act regulatory advice.

See it live

🍁 Open the brief generator → shayeeboy.github.io/Financial-Intelligence-Strategy-Agent

Pick a province, city, demographic, and product line, click Generate, and a complete, sourced strategy brief is built in your browser from live data — no sign-up, no cost, no backend. There are 13 cities × 7 demographics × 6 product lines to choose from. (web flow)

📬 Scheduled email delivery is live (R9): subscribe an email to any brief and receive it weekly or monthly, generated fresh from live data. Double opt-in, one-click unsubscribe, via a Cloudflare Worker + Neon + a daily GitHub Actions cron — verified in production, $0/month.

🖼️ Community gallery is live (R8): share a generated brief to a public "recently generated" feed, browse what others built, and click any entry to regenerate it with today's data — same Worker + Neon, still $0.

📄 Or read a pre-generated example → GTA Newcomer Credit & Daily Banking

Every figure is pulled from a public API at generation time (the CLI run also snapshots it to data/raw/). The endpoints are live and key-free — you can hit them right now:

• Bank of Canada overnight target — valet/observations/V39079
• Statistics Canada household leverage (Table 38-10-0238) — WDS getDataFromVectorsAndLatestNPeriods
• CMHC rents (via StatCan Table 34-10-0133) — tv.action?pid=3410013301

Prefer the CLI? npm install && npm run brief regenerates the example end-to-end.

Executive Summary

Problem. Financial institutions design products, price credit risk, and plan branch-vs-digital strategy against a picture of the Canadian consumer that is usually stale, siloed across agencies, and expressed in raw statistical tables rather than in product terms. The relevant facts already exist publicly — household leverage (Statistics Canada), shelter cost and vacancy (CMHC), and the rate environment (Bank of Canada) — but they live in three different APIs, on three different release cadences, and none of them says "…therefore, offer this product to this segment." Bridging that last mile is manual, slow analyst work. This agent automates it: it ingests the live public data and emits a decision-ready strategy brief that maps each data point to a concrete banking product play.

User. Three access tiers for three users. (1) A business user — a strategy / product analyst at a Canadian bank or credit union — who opens the hosted web generator, picks a segment and city, and gets a defensible, sourced brief in seconds, no install. (2) An AI/automation engineer who calls the same capability as composable MCP tools from Claude (or any MCP client) inside a larger workflow. (3) A developer/analyst running the CLI headless in a pipeline. The brief is written for a business reader; the tools are built for a technical one.

Objective. Build a production-shaped autonomous-agent pattern — live tool-use over real public APIs → structured synthesis → cited, guard-railed output — on a genuine, non-trivial domain (Canadian consumer banking strategy), and make it self-serve: any of 13 cities × 7 demographics × 6 product lines generates a complete brief with no backend and no cost. The banking briefs are the deliverable; the transferable pattern is "turn a set of authoritative live data sources into a trusted, sourced, decision-ready document, with the discipline of something meant to be relied on rather than demoed." Every number is traceable to its source; the agent refuses to stray into forecasting or regulatory advice; and low-evidence outputs flag themselves rather than bluffing.

Success criteria. Deliberately split into what is mechanically verified and what is honestly not yet measured:

Not yet measured (honest gaps). The brief's narrative reasoning (e.g. "newcomers are thin-file, not low-capacity") is presented as qualitative segment analysis, not auto-validated against the figures — there is no automated fact-check of the prose. Generational briefs now carry real age-cohort micro-data (R1, shipped); the non-age demographics (newcomers, students, families) still use national/metro proxies. CMHC data is annual, so intra-year shifts aren't captured. And while the app now generates many briefs on demand, their quality isn't systematically evaluated — cross-brief consistency and analyst-usefulness need a rubric/eval harness (roadmap item R5). See Gaps & roadmap.

Key decisions (the trade-offs that shaped the build).

• Generation stays fully client-side — no backend on the hot path. All three sources send Access-Control-Allow-Origin: *, so the browser calls them directly; the generator is static on GitHub Pages with no server to host or keep warm and $0. Generation still needs no database. A backend was added only for the feature that genuinely needs one — scheduled email delivery (R9): a Cloudflare Worker + Neon Postgres, introduced deliberately and late, not as a default. (That same Neon + Worker now also unblocks the shared-gallery idea, R8.)
• CMHC sourced through Statistics Canada, not scraped from HMIP. CMHC's portal has no stable public JSON API (it returns HTML); its Rental Market Survey is republished as StatCan cubes. Reading those cubes gives versioned, citable data instead of a brittle scraper — a deliberate reliability-over-directness call. (details)
• A generic coordinate resolver over thousands of hard-coded vector IDs. CMHC tables are multi-dimensional (geography × structure × bedroom). Rather than pin one vector per combination, the StatCan adapter resolves human selectors ('Toronto', 'Two bedroom') to member IDs and builds the 10-part coordinate WDS expects — any CMA/bedroom works.
• Curated, smoke-validated vectors over blind table queries. Headline concepts map to specific validated vectors so the brief always gets a meaningful series; two wrong placeholder vectors (returning null at 2018) were caught by the smoke test during the build and corrected against live metadata — the test drove the fix.
• Guardrails that flag over guardrails that hide. A low-evidence brief is still produced, but stamped Low Confidence in memory.md and on the console, rather than silently emitted as if fully backed. Fewer false "high-confidence" outputs, at the cost of some flagged ones.
• MCP server + CLI over the same core. The four tools are exposed for interactive use by an MCP client and driven headless by the orchestrator — one implementation, two delivery modes, no divergence.

How it works

Three entry points over one synthesis pattern: a web generator (static, client-side, on GitHub Pages), an MCP server (four live-data tools an analyst can call from Claude), and an orchestrator (runs the full Standard Operating Procedure headless and writes a finished brief).

Navigate: See it live · Architecture · Web generator · Orchestrator SOP · Adapters & tools · MCP tools · Run it · Test cases · Repo structure · Tools & services · Lessons learned · Gaps & roadmap

Architecture

Consumers (an MCP client or the CLI) share one agent core. The core calls three adapters, which each normalize a public Canadian open-data API into a cited, uniform shape. The write-side persists briefs, a business-facing matrix, raw provenance snapshots, and a running-state log.

• Consumers — an MCP client (Claude Desktop/Code) calling the tools interactively, or the Analyst CLI (npm run brief) running the whole SOP.
• Agent core — the MCP server exposes four tools over stdio; the orchestrator sequences them into the SOP with the confidence guardrail.
• Adapters (src/mcp/adapters/) — statcan.js (WDS + coordinate resolver), cmhc.js (rents/vacancy via StatCan), bankofcanada.js (Valet), all over a shared http.js with timeout + retry.
• Sources — Statistics Canada WDS, CMHC (no public API → via StatCan), Bank of Canada Valet. All public, all key-free.
• Outputs — data/briefs/ (+ master_index.md matrix), data/raw/ snapshots, and memory.md.

The web generator is a fourth consumer, but it deliberately bypasses the Node core: it's a static browser app that talks to the three public APIs directly (client-side), so it needs no server. Its data flow is diagrammed below.

↑ Back to top

Web generator (GitHub Pages)

The hosted generator is a fully static, client-side app — the CTA the business user actually touches. Generating a brief runs entirely in the browser: no backend, no database, no build step, $0 — possible because all three sources send Access-Control-Allow-Origin: *, so the page can fetch() them directly. (The optional email delivery (R9) and community gallery (R8) on the same page do use a small Cloudflare Worker + Neon — see Gaps & roadmap.)

Studio snapshot (auto-refreshed). npm run studio:snapshot emits a compact, machine-readable web/studio-snapshot.json of the agent's real output for the AI Product & Leadership Studio to consume live (served from Pages with Access-Control-Allow-Origin: *). A daily workflow (refresh-snapshot.yml) re-pulls the live indicators, regenerates the snapshot and deploys Pages — no secrets, since the sources are keyless — so the Studio always sees the latest figures.

Beyond the indicators (each with value, source, trend, per-series retrievedAt / nPeriods, and a forecast-free delta + sparkline — R6), executive summary and recommendations, the snapshot carries an honest observability block derived only from the provenance data: source/indicator counts, when data was last pulled (dataRetrievedAt), how current the underlying data is (sourceDataAsOf, the stalest series), its inherent reporting lag (sourceDataLagDays), and the freshness-SLA roll-up (seriesWithinSla / staleSeries — R4). It deliberately omits latency/cost/error — this agent is a static data pull with no request telemetry, so inventing runtime metrics would be dishonest.

Controls (the "any brief" matrix). Province → filters City (13 CMAs); Rent basis (1/2/3-bedroom); Demographic group (7 cohorts); Brief type / product focus (6 lines) — 42 demographic×product combinations per city.

Choose (province · city · bedroom · demographic · product)
  → fetch() StatCan + CMHC(via StatCan) + BoC  in parallel, client-side (CORS-open)
  → derive  YoY · annualized rent · 30%-rule income · confidence guardrail
  → compose Markdown (same mandated hierarchy as the CLI)  → render to HTML
  → Download .md  ·  Copy Markdown

Files (web/): index.html + styles.css (theme-aware, responsive); js/catalog.js (options + precomputed CMHC coordinates, so the browser skips the heavy metadata fetch); js/sources.js (browser data adapters); js/compose.js (pure brief composer); js/markdown.js (dependency-free renderer); js/app.js (DOM wiring). The composer, catalog, metrics, and renderer are pure ES modules that also run in Node, so they're unit-tested (AC-W1…W6) and kept in parity with the CLI's src/lib/metrics.js.

Deployed by .github/workflows/pages.yml (uploads web/ as the Pages artifact on every push that touches it).

↑ Back to top

Orchestrator SOP

One npm run brief run executes the six-step Standard Operating Procedure below. Data gathering is parallelized; the confidence guardrail sits between gathering and synthesis so a thin-evidence brief is flagged, not silently shipped.

1. Identify gaps        read data/briefs/master_index.md
2. Gather live data     StatCan (debt, CPI) ‖ CMHC (rent, vacancy) ‖ BoC (rates)   → snapshot to data/raw/
3. Derive metrics       YoY · annualized rent · 30%-rule required income
4. Confidence check     any series < 3yr baseline?  → flag "Low Confidence" in memory.md + console
5. Strategic synthesis  Exec Summary → Demographic Profile → Impediments → Product Opportunities
                        (every section carries a "Financial Services Implication")
6. Update loop state    write timestamps, ingestion vectors, confidence, backlog to memory.md

The synthesis step enforces the mandated brief hierarchy and the house style (Canadian English — chequing, RRSP, behaviours; segment every section by demographic group and product category). The safety guardrails (no rate forecasts, no legal/FINTRAC advice) are baked into the brief template as an explicit disclaimer and honoured in the prose.

↑ Back to top

Adapters and tools

Each adapter returns a uniform, source-stamped object (source, source_url, latest, trend, retrieved_at) so synthesis never handles a raw API payload.

MCP tools

Exposed by src/mcp/server.js over stdio (JSON Schema, no zod dep):

Wire it into Claude Code / Desktop — a project-scoped .mcp.json is included:

{ "mcpServers": { "financial-intelligence-strategy-agent": { "command": "node", "args": ["src/mcp/server.js"] } } }

↑ Back to top

Run it

npm install

npm run smoke     # live: verify all 8 data pulls against StatCan/CMHC/BoC
npm run check     # offline: 33 unit-acceptance tests (node --test)
npm run brief     # run the SOP → writes data/briefs/*.md + master_index.md + memory.md
npm run mcp       # start the MCP server on stdio (for an MCP client)

All three data sources are public and need no API key. Optional client tuning (FISA_HTTP_TIMEOUT_MS, FISA_HTTP_RETRIES) is in .env.example.

↑ Back to top

Test cases and acceptance criteria

Two suites, mapping to the success criteria above.

npm run check — offline unit-acceptance of the deterministic core (no network, no API keys; node --test). Each test asserts one acceptance criterion:

ℹ tests 33   ℹ pass 33   ℹ fail 0

npm run smoke — live integration acceptance against the real APIs (read-only):

CI (.github/workflows/ci.yml) runs check as a required job on every push/PR and smoke as a non-blocking job (so live-API availability never red-lights a PR).

↑ Back to top

Repo structure

Financial-Intelligence-Strategy-Agent/
├── README.md                     ← this file
├── package.json                  ← scripts: brief · mcp · check · smoke
├── .mcp.json                     ← wire the server into an MCP client
├── assets/                       ← architecture.svg · workflow.svg · web-flow.svg
├── docs/DATA-SOURCES.md          ← provenance: tables, vectors, how to extend
├── web/                          ← static client-side generator (GitHub Pages)
│   ├── index.html  styles.css    ← theme-aware, responsive UI
│   └── js/
│       ├── catalog.js            ← options + precomputed CMHC coordinates
│       ├── sources.js            ← browser data adapters (fetch the 3 APIs)
│       ├── compose.js            ← pure brief composer (Node-testable)
│       ├── markdown.js           ← dependency-free Markdown → HTML
│       ├── metrics.js            ← pure helpers (parity with src/lib/metrics.js)
│       ├── config.js            ← API_BASE for the Worker (email + gallery); empty until deployed
│       └── app.js                ← DOM wiring: generate/download/copy/subscribe/gallery
├── src/
│   ├── orchestrator.js           ← runs the 6-step SOP → one brief
│   ├── lib/{http.js, metrics.js, freshness.js, apply-schema.js} ← fetch · figures+deltas · freshness SLA · migrator
│   ├── email/                    ← R9 scheduled delivery — shared by Worker + cron
│   │   ├── subscription.js       ← validation + next-run schedule (pure)
│   │   ├── template.js           ← confirm + brief email HTML (pure)
│   │   ├── send.js               ← Resend send via fetch (runtime-agnostic)
│   │   └── db.js                 ← Neon queries (@neondatabase/serverless)
│   ├── gallery/                  ← R8 shared brief gallery — shared by Worker + tests
│   │   ├── validate.js           ← entry validation + human label (pure)
│   │   └── db.js                 ← Neon queries (insert/recent/stats/rate-limit)
│   └── mcp/
│       ├── server.js             ← MCP server (stdio) exposing the 4 tools
│       ├── adapters/{statcan,cmhc,bankofcanada}.js
│       └── tools/compile_strategy_brief.js
├── server/index.js               ← Cloudflare Worker: /api/subscribe|confirm|unsubscribe + /api/briefs (gallery)
├── wrangler.toml                 ← Worker config (non-secret vars only)
├── sql/{email_schema.sql, gallery_schema.sql}   ← subscriptions · briefs tables (Neon)
├── scripts/
│   ├── check.js  smoke.js        ← offline acceptance · live integration
│   ├── deliver.js                ← cron job: generate + email due subscriptions
│   └── migrate-email.js  migrate-gallery.js     ← apply each schema to Neon
├── data/
│   ├── raw/                      ← per-run JSON provenance snapshots (gitignored)
│   └── briefs/{master_index.md, gta_newcomer_credit_opportunity.md}
├── memory.md                     ← running-state log
├── .github/workflows/
│   ├── ci.yml                    ← check (required) + live smoke (non-blocking)
│   ├── pages.yml                 ← deploy web/ to GitHub Pages
│   └── deliver.yml               ← daily cron → scripts/deliver.js
└── LICENSE

Tools and services

Lessons learned

Gaps and roadmap

Honest about what this is (a solid, live-data, well-tested agent generating briefs across 13 cities × 42 demographic×product combos, with scheduled email delivery and a community gallery live) and what would make it genuinely production-grade.

Qualitative gaps

• Cohort specificity — mostly closed (R1). Generational briefs now carry real age-cohort figures (net worth, debt, income, DTI) from StatCan DHEA. Remaining gap: the non-age demographics (newcomers, students, families) still use national/metro proxies — StatCan has immigration/income-decile micro-data that a future pass (income quintile is in the same DHEA cube) could wire in for those.
• No narrative fact-check. Figures are sourced; the prose isn't automatically validated against data. A confidently-worded but unsupported sentence could slip through.
• Autonomy vs. self-serve. The web app now covers 13 cities × 42 demographic×product combos on demand, but the headless orchestrator is still hard-targeted at one brief — it doesn't yet pick its next brief from master_index coverage holes (R2).

(Resolved since the first cut: persistence + a shared gallery — briefs can now be saved to a public community gallery, R8, shipped; and off-site delivery via scheduled email, R9, shipped.)

Roadmap (with measurable targets). Convention: when an item ships it's marked ✅ SHIPPED with its go-live date (— live YYYY-MM-DD) next to the item name.

See docs/DATA-SOURCES.md for the provenance reference and the step-by-step for adding an indicator (R1/R7). On Neon: brief generation still needs no database (it's stateless client-side). A backend arrived with R9 (scheduled email delivery) — a Cloudflare Worker + Neon Postgres, now deployed and live at $0/month. The shared gallery (R8) reuses that same Worker + Neon and is also now deployed and live — one backend, two features, no extra cost.

↑ Back to top

License

MIT © shayeeboy