-
AWS : build and deployment
-
Sensitivity to the time period
-
Comparing two profiles on the same request
-
Plain-language conclusion: accessible to any investor, whatever their level!
-
Verified explanation
-
AWS : analysis flow
-
Reproducible evidence drawer
-
Verdict, limits and margins
-
Request and agent decisions
-
Transaction request blocked
Inspiration
Investors have more information than ever (prices, filings, rates, news) but little help connecting it to their own situation. Most "AI finance" tools jump straight to a recommendation, and nobody can check where it came from. The PolyFinances × National Bank × AWS case asked for the opposite: an agentic, self-explaining assistant that shows which facts support a conclusion and what their limits are, and that never gives advice.
So we set one rule: the app presents facts, never advice. It compares an investment idea with a fictional investor's profile, says where it fits and where it does not, links every figure to its evidence, and leaves the decision to the human.
What it does
You choose a fictional profile (Amira, Mateo, Robert, or one you create), an analysis date and a base currency, then ask in plain language: "Evaluate NVDA", "Compare NVDA and TLT", "60% SPY and 40% AGG, no rebalancing".
Five agents work in turn and write everything to a shared evidence ledger:
- Orchestrator: loads and validates the profile. Amazon Bedrock (Claude Haiku 4.5) reads the request: intent, assets ("gold" → GLD) and out-of-scope signals (prediction, transaction, personal advice). The code then re-checks everything the model proposed. The orchestrator plans the work and decides whether enrichment is needed.
- Enrichment: fetches public data that the starter dataset lacks, such as SEC EDGAR filings and annual-report fundamentals for US stocks. Each item is dated, rated A/B/C for confidence and given a source card. A missing source becomes a named gap, never an assumed value.
- Quantitative analyst: deterministic tools only, with no network and no language model. Returns, volatility, maximum drawdown, worst day and month, results by period, correlations, and historical portfolio replays, with CAD/USD converted at the same day's rate before computing returns.
- Governance: compares the evidence with limits derived from the profile (risk level and horizon). It gives each asset a status of consistent, warning or blocked. When an asset is not consistent, it asks the analyst to assess other assets for comparison, each with its own status. These statuses describe consistency with a fictional profile under documented rules, not advice and not a suitability assessment.
- Explainability: writes the explanation from the ledger only, then verifies every sentence before showing it. A plain-language "In short" conclusion follows, with no numbers and no jargon.
Every number on screen has an Evidence button. It opens a window, right where you are, that says what the calculation measures, shows its results, compares them with the profile's limits, and gives the Python command that reproduces it exactly. An "Agent decisions" panel shows the choices the agents made and why.
How we built it
Facts first. No number ever comes from a language model. Bedrock only interprets the request; every figure comes from a deterministic tool or an official source. For example:
Annualized volatility
$$\sigma_{\text{ann}} = s(r_t)\cdot\sqrt{N}, \qquad N = 252 \text{ (stocks, ETFs, gold) or } 365 \text{ (crypto)}$$
- \( \sigma_{\text{ann}} \): annualized volatility, the typical size of price swings over a year, expressed as a percentage.
- \( r_t \): daily return on day \( t \), that is \( r_t = \dfrac{P_t}{P_{t-1}} - 1 \).
- \( s(\cdot) \): standard deviation of the daily returns over the analysis period.
- \( N \): number of return periods per year. \( N = 252 \) for stocks, ETFs and gold (trading days), \( N = 365 \) for crypto (trades every day), and \( N = 52 \) for weekly series that mix crypto and stocks.
- \( \sqrt{N} \): annualization factor, because variance grows in proportion to time (assuming independent returns).
Maximum drawdown
$$\text{MDD} = \max_{t}\left(1 - \frac{P_t}{\max_{u \le t} P_u}\right)$$
- \( \text{MDD} \): largest drop from a peak to the following trough, as a fraction of the peak (0.45 means a 45% loss).
- \( P_t \): price of the asset on day \( t \), adjusted for dividends and splits.
- \( \max_{u \le t} P_u \): highest price reached from the start of the period up to day \( t \) inclusive.
- \( P_t / \max_{u \le t} P_u \): where the current price stands relative to the previous peak (1 at the peak, 0.6 when 40% below it).
- \( 1 - P_t / \max_{u \le t} P_u \): loss from the peak on day \( t \), the drawdown of the day.
- \( \max_{t} \): we keep the worst drawdown observed over the whole period.
Annualized return
$$R_{\text{ann}} = (1 + R)^{1/T} - 1$$
- \( R \): cumulative return over the period.
- \( T \): length of the period in years.
- Shown only when the period covers at least 350 days.
A measure is called sensitive to the period when it differs by more than 25% between windows, unless the absolute gap stays under 2 points.
An explanation that cannot say more than the evidence. Before display, each sentence must pass four checks:
- every reference exists in the ledger;
- every number matches its evidence, rounded as shown;
- no advice, prediction or promise wording;
- provenance: every word comes from a writing template or from the ledger, never from the user's free text.
A failing sentence is removed and the explanation is written again.
Point-in-time by design. Every tool takes an as_of date, and no data published after it is read. Each piece of evidence stores a SHA-256 fingerprint of the rows it read, so the same analysis gives the same ledger fingerprint.
Profiles are data, not code. Limits are derived from risk level and horizon. No rule is written for a specific persona.
AWS. Amazon Bedrock interprets requests. Amazon S3 archives each ledger under its fingerprint (private, encrypted, 60-day expiry). The app runs on ECS Fargate behind an Application Load Balancer and CloudFront. CodeBuild builds the image and stores it in ECR, and CloudFormation deploys everything. The task role can only call that one model and write archives. Without AWS, the app falls back to rule-based parsing and an offline SEC snapshot, and the screen says so.
Validation.
- Model choice: a benchmark of 12 requests × 3 checks gives Claude Haiku 4.5 36/36 on each of 3 passes, Nova 2 Lite 35/36 and rules alone 30/36. Haiku was the only one that caught the "transaction" signal in "Everyone's talking about Tesla, should I buy some?". Twelve requests is a small sample.
- Metrics: recomputed independently with pandas from the raw CSV for 5 assets; the largest gap measured was 0 (tolerance 1e-9).
- Reproducibility: the same analysis run 3 times gives the same ledger fingerprint (3 analyses out of 3).
- Tests: 641 automated tests run on every push in GitHub Actions, with Bedrock, S3 and EDGAR replaced by test doubles.
Challenges we ran into
- Keeping an LLM out of the numbers and the advice. A blacklist of advice words was not enough: a disguised recommendation or a look-alike character slips through. The fix was a whitelist, so every word must come from a template or the ledger.
- Calendars and currencies. Crypto trades every day and stocks do not. Correlations use common dates only, with no forward fill, because filling would create fake zero returns. The "excluding 2022" window removes 2022 returns, not prices, so that no fake return bridges the gap.
- Block or warn? We block only on explicit rules: a declared exclusion, a documented controversy on an excluded theme, an asset class the risk level does not allow, or a real transaction request. A volatility breach stays a warning, with the figures and the margin to the limit, and the full analysis is always shown.
- Honest gaps. Mateo cares about ESG, but no free and documented ESG or controversy source was available. Rather than guess, the app says it cannot verify ESG alignment and names ESGV (a fund screened by its issuer) as a declared substitute. Sector exclusions, which can be checked against the dataset, do block.
- Shipping on AWS without Docker on our machines. CodeBuild builds the image, and image tags are the code-archive fingerprint, so one tag always means one version of the code.
Accomplishments that we're proud of
- Every figure can be traced and replayed: running the same analysis again gives the same ledger fingerprint.
- An explanation verifier that removes any sentence it cannot prove.
- A bilingual (FR/EN) interface that a beginner can read, with a 16-term glossary and an "In short" conclusion.
- The app still works fully offline, without AWS.
What we learned
- Self-explaining means verifiable, not just talkative: a short sentence tied to evidence beats a long fluent one.
- An LLM is most useful at the edges (understanding the request) and most risky at the core (numbers and conclusions).
- Writing down what the system does not know (ESG data, Canadian filings, forecasts) builds more trust than covering it up.
What's next
- Requests: compare a single position's weight with the profile's per-asset cap ("a 25% position in TSLA"), accept dollar amounts and custom periods, and explain on screen why a scenario whose weights do not add up to 100% is not computed. Today these details are ignored and documented in the README.
- A SEDAR+ provider for Canadian filings, using the same provider interface as SEC EDGAR.
- A documented ESG and controversy source, so the existing level A/B controversy rule can actually trigger.
- An adversarial request set (injection attempts, typos) measured with and without Bedrock.
- For real-world use: rate limiting (AWS WAF), authentication (Amazon Cognito), budget alerts, and an anonymized profile in the archive.
Simulation only. No real transactions, no personalized financial advice, no return predictions. Past data describes the past.
Built With
- altair
- amazon-bedrock
- amazon-cloudfront
- amazon-cloudwatch
- amazon-ecr
- amazon-ecs
- amazon-web-services
- aws-cloudformation
- aws-codebuild
- aws-fargate
- boto3
- claude-haiku-4.5
- docker
- elastic-load-balancing
- github-actions
- numpy
- pandas
- pydantic
- pytest
- python
- sec-edgar
- streamlit