Inspiration
A ticker tells you where a company is listed. It doesn't tell you where the company earns its money, and geopolitical shocks follow the money. A tariff war, sanctions or a crisis in the Taiwan Strait hits a portfolio through the countries its companies sell in. A "U.S. tech" portfolio can carry a lot of Asian risk without the investor ever seeing it.
We built PolyAi GeoRisk for the AlphaForge AI challenge (National Bank × AWS) at the PolyFinances Datathon 2026. The brief asked for an agentic tool that explains its own results across different investor profiles. Professional geopolitical research exists, but it rates countries, not portfolios, and it doesn't tell a 59-year-old near retirement whether his particular mix is too much for him.
Early on we made the decision that shaped the whole project. Ask a language model "how risky is this portfolio, 0 to 100?" and you get a confident answer that changes every time you ask. That's not acceptable for anything a bank or an advisor would put in front of a client. So we split the work: agents read documents and extract facts, and deterministic code computes every number.
What it does
You give PolyAi GeoRisk a portfolio and an investor profile. Holdings can be weights, quantities or market values, typed in or uploaded as a CSV, across a 150-asset universe (Canadian and U.S. stocks, equity and bond ETFs, gold, Bitcoin and Ether). The profile has a risk level from 1 to 5 plus the constraints real investors have: horizon, objective, ESG importance, excluded sectors and themes, a cap on any single holding, a crypto cap, countries to avoid.
You also pick an analysis date. Every agent only uses data published on or before that date, so you can ask what the risk looked like in 2022 without the answer leaking anything from later.
A live progress page shows each agent as it works: which filing it is reading, how many quotes it verified, which country it is scoring. The finished report has:
- a headline personal concern score (0 to 100), with the objective risk and a confidence value next to it
- a verdict: Clear (no trade needed) or Act
- holdings and countries tables, scored with the same formula as the headline
- the interactive scenario map
- suggested swaps into profile-approved funds, each re-scored
- an annex that lists every source once (filings, World Bank pages, think-tank reports) with the claims that cite it
First the exposure agent works out where each holding earns its revenue. It goes down a six-tier chain: the XBRL geographic table of the latest 10-K, 20-F or 40-F, then the filing text, then the previous year's filing, then sector peers, a home-bias prior and finally a returns-based estimate on country ETFs. Each split is tagged with its tier, so the report shows which exposures are disclosed and which are estimated. Combining these splits with the portfolio weights gives the portfolio's revenue by country.
Three specialised agents then supply the inputs to the score:
- Country health (A1). The country risk agent pulls World Bank indicators: inflation, unemployment, government debt, GDP growth, bank non-performing loans and bank capital. Code turns them into a macro fragility score for each country.
- Geopolitical tension (A2). The geopolitical agent combines World Bank political-stability estimates with the Caldara–Iacoviello Geopolitical Risk (GPR) index. It measures how tense a country is compared with other countries, scaled by how tense it is compared with its own history.
- Company warnings (A3). The filings agent reads each company's latest annual filing with search tools and flags eight risk channels: tariffs, export controls, sanctions, conflict exposure, supply chain, regulation, FX and capital controls, and financial stress. A channel only counts if it comes with a verbatim quote that code finds in the filing.
The country scores are weighted by where the portfolio earns its revenue. The company score is weighted by holding size, over single stocks only, since a bond fund has no 10-K to read.
Risk tolerance only affects the second stage. Objective risk is a property of the portfolio, the same for every investor. Each risk level then sets a comfort level and concern climbs steeply once objective risk passes it. One example: a profile-2 investor with objective risk 34 against a comfort level of 43 gets a concern of 31 and a Clear verdict. If any stated limit is broken, for example a single holding above its cap or exposure to an excluded country, the verdict is Act, even when the risk number looks fine. That's how the tool pushes back on Robert when he asks for a hyped stock his profile can't carry.
The map answers the question the tables can't: what's actually at stake if a particular scenario plays out. Each week a scenario agent reads Eurasia Group's Top Risks, BlackRock's Geopolitical Risk Dashboard, CFR's Preventive Priorities Survey and the Atlantic Council's Global Foresight series, and writes about twelve global scenarios (for example "China moves on Taiwan" or "USMCA trade pact unravels"). Each scenario has the countries it involves and quotes that code checks against the source text. You can select one scenario or several. Each one colours the countries it hits, with the shade showing intensity. Hovering over a country shows how much of the portfolio's revenue is earned there. A live readout updates as you select scenarios. In one saved analysis, 72% of revenue sat in countries directly involved in those two scenarios, and NVDA alone accounted for 42.5 of those points. You can also pick a country and get the five scenarios most dangerous for it.
How we built it
The backend is Python and FastAPI. The frontend is server-rendered Jinja templates with htmx and plain JavaScript, so there is no build step. The map uses D3 with TopoJSON world boundaries on an Equal Earth projection, and its colours come from the same CSS tokens as the rest of the UI. Scenario data reaches the map through a JSON endpoint on each run.
Each run is an async pipeline in seven steps. Market data and exposure splits come first, with up to six holdings fetched in parallel. Company disclosures, scenarios, and macro data with official sources then run at the same time. Country hazard follows, then the portfolio score, then recommendations. Each step writes progress events that the run page polls, which is how the live trace works.
All LLM calls go through one module (core/llm.py) that wraps the Amazon Bedrock Converse API with Anthropic's Claude Sonnet. Structured output uses a forced answer tool validated by Pydantic schemas. The filings agent instead runs a tool loop, calling risk_factors and search on the filing text before it answers. Every call is traced (tokens, input, output and Bedrock's request ID) to local JSONL logs, and optionally to AWS CloudTrail Lake, where it joins the matching CloudTrail Converse event. Data comes from SEC EDGAR (edgartools and edgar-geo-revenue for XBRL geographic tables), the World Bank API, the GPR index, Yahoo Finance via yfinance, think-tank pages scraped with httpx and BeautifulSoup and more. Caches and scenario sets can be stored locally or in Amazon S3.
We keep the LLMs honest with checks in code:
- Quotes are checked against the source text after whitespace normalisation. The filing-risk agent gets two repair rounds in which it can only pick contiguous passages of the filing.
- The risk agent writes the four plain-language sentences under the score. Code extracts every number in them and deletes any sentence containing a number that isn't in the computed facts.
- The source agent uses no LLM at all. It checks a curated list of central-bank, finance-ministry and statistics-office URLs and only lists them.
Severities, likelihoods and confidence grades written by models are shown as context only. The score only uses inputs that come from measured data or from quotes code has verified.
The score itself has two stages. Each input is shrunk toward a neutral 0.5 by its confidence $c_k$, which is the share of the portfolio it actually covers. Unknown data then pulls the score to the middle instead of pretending to be safe:
$$\tilde A_k = c_k A_k + (1 - c_k)\,0.5$$
Country health and company warnings form a structural block, $F_S = (1 - w_3)\tilde A_1 + w_3 \tilde A_3$, where $w_3 = 0.5\,s$ and $s$ is the share held in single stocks. Geopolitics is its own block, $F_G = \tilde A_2$. The blocks are combined with a quadratic mean, so the worse block weighs more. An interaction term covers the case where both are high, and a red-flag term kicks in when any input passes 0.70:
$$B = \sqrt{0.6\,F_S^2 + 0.4\,F_G^2}, \qquad R_0 = B + 0.25\,F_S F_G (1 - B)$$
$$R = R_0 + 0.35\,h\,(1 - R_0), \qquad h = \left(\frac{\max(0,\ \max_k \tilde A_k - 0.7)}{0.3}\right)^2$$
Personal concern is a normalised logistic of the gap between $R$ and the investor's comfort level $\rho = 0.15 + 0.70\,t$, where tolerance $t$ goes from 0.20 for risk level 1 to 0.85 for risk level 5:
$$C = 100 \cdot \frac{\sigma\big(8(R - \rho)\big) - \sigma(-8\rho)}{\sigma\big(8(1 - \rho)\big) - \sigma(-8\rho)}$$
The same inputs always give the same score. The same function scores the portfolio, each holding and each country, which keeps every table on the headline's scale.
Recommendations are deterministic too. Code fixes broken profile limits first, then moves the riskiest holdings into the best profile-approved fund in quarter steps until objective risk drops back under the comfort level. Every swap is re-scored with the full formula. A remediation agent can suggest alternative swaps, which code sizes and only keeps if re-scoring shows they lower the risk.
Exposure splits are cached per filing, company reads per month, scenarios per week, and agent answers per exact input. Concurrent runs share one read per company, and a whole analysis with the same inputs within seven days is reused. An offline pytest suite with stubbed services covers the formula, hazard maths, exposure chain, recommendations and pipeline. We also check scores against a "risk ladder" of ten portfolios, from Canadian cash to conflict zones.
Challenges we ran into
Our first geopolitical signal flagged everything. We had measured each country's GPR against its own history, but in late 2026 almost every country sits near the top of its own history: Canada at the 92nd percentile, Norway at the 98th. The first version scored a portfolio of Canadian bond funds at 74, higher than a China/Taiwan portfolio at 68. We rebuilt the hazard so a cross-country level (political stability plus the log GPR level) sets how dangerous a country is, and its own history only scales that between ×0.5 and ×1. The same Canadian cash portfolio now scores 26, and we can explain each step of that calculation by hand.
Companies don't report revenue by country in any consistent way. Some file a clean XBRL table. Others write "Asia Pacific" or "outside the U.S.", or only describe it in text. Some don't report it at all. That's why the exposure agent has six tiers. Regions are split by a prior country mix rather than evenly. Revenue a filing leaves unattributed counts as not covered, so it isn't silently assigned anywhere. SEC rate limits (HTTP 403/429) show up as "blocked" rather than as "no filing", which kept us from mistaking a throttled request for a company with no foreign revenue.
Keeping the models from inventing things took more engineering than calling them. Quotes came back slightly reworded, and early explanations included numbers we had never computed. That led to verbatim verification, the contiguous-segment repair rounds, and the rule that a sentence with an unknown number gets deleted.
Accomplishments that we're proud of
- A working end-to-end system: around ten agents and modules running on real public data (SEC filings, the World Bank, the GPR index, prices and think-tank reports), from a portfolio form to a sourced report. There is no mock data in the app.
- A strict boundary between AI and arithmetic. No number written by a language model enters the score, and that's enforced in code, not just stated in a prompt.
- A scoring model with stated assumptions and a step-by-step derivation. We recomputed real app runs by hand and matched the code's output.
- A map that translates scenarios into money: pick "China moves on Taiwan" and see what share of your revenue, and which holdings, are involved.
- Point-in-time analysis across five years, so the same portfolio can be scored as of any date between November 2021 and November 2026 without look-ahead.
- Full traceability: every exposure has a tier, every flag has a quote, every source has an annex letter, and every LLM call has a trace with its tokens.
- Results that differ by persona. The same portfolio produces different concern scores and verdicts for Amira, Mateo and Robert, and the tool flags conflicts with a profile's stated limits.
What we learned
The hard part of an agentic system is the contract between agents, not the prompts. Once we fixed the schemas and the rule that every agent may fail, we could build agents on separate branches and merge them.
Language models are strong at reading and weak at measuring. A model is very good at finding the sentence in a 10-K about export controls, but it isn't a reliable judge of how severe that is on a 0 to 5 scale. Making models extract facts while code scores them gave us results we could defend.
A risk score needs anchors. A formula can be mathematically clean and still rank Canadian bonds above Taiwan. The risk ladder of ten portfolios with intended scores made those failures visible within minutes.
Missing data has to be modelled explicitly. Treating "not read yet", "not applicable" (a bond fund has no filing) and "not covered" (revenue nobody attributes) as three different things changed the scores more than any weight did.
Explainability depends on the details: tagging each estimate, handling throttled requests correctly, and keeping a source annex. Those details are what let an advisor trust a number.
Built With
- amazon-bedrock
- amazon-web-services
- aws-cloudtrail
- beautiful-soup
- boto3
- css
- d3.js
- fastapi
- htmx
- httpx
- javascript
- jinja
- pandas
- pydantic
- pytest
- python
- topojson
- vercel