Repository navigation
Technologies
Design principle: a language model never produces a number. Financial figures and verdicts come from deterministic code. Models only score headlines, write explanations, or choose which lookup to run.
| Layer | Technology | Used for |
|---|---|---|
| Web app | Next.js 16, React 19, TypeScript, Tailwind CSS 4 | Persona and account selection, Holdings panel with a Buy/Sell pop-up, chat, execution trace, English and French UI. A missing French string fails the build. |
| Gateway | FastAPI, Pydantic, Python 3.12 | Validates requests, signs them with AWS credentials and forwards every call to the Orchestrator |
| Agents | Amazon Bedrock AgentCore Runtime, Strands Agents SDK | Five agents, each its own runtime (code upload, Python 3.12, ARM64): Orchestrator, Intake, Market, Classifier, Explainer |
| Calculation | AWS Lambda (Python 3.12, ARM64) | Every metric, score and verdict, from versioned S3 data |
| Verdict engine | Pure Python (sell_guard, sentiment_tools) |
Panic sell, buying after a drop and the other verdicts; identical code runs in Lambda and in tests |
| Storage | Amazon S3 (private, encrypted, versioned) | Market data with SHA-256 manifest, starter dataset, investor records, agent packages |
| Language model | Amazon Bedrock, Amazon Nova Lite (us.amazon.nova-lite-v1:0), Converse API |
Chat routing, headline scoring, explanations |
| Agent connector | Remote MCP server (Streamable HTTP) | Receives the persona from your own AI agent |
| Infrastructure | AWS SAM / CloudFormation, IAM, CloudWatch Logs | Reviewed change sets, least-privilege roles, per-agent logs |
| Quality | pytest, unittest, ESLint, TypeScript, GitHub Actions | Backend, Lambda, agent and frontend checks |
Your assistant stays outside the app and reaches it through a remote MCP server.
sequenceDiagram
actor You
participant AI as Your AI agent<br/>(Claude · Muse · Dots)
participant MCP as MCP server<br/>/mcp/USER.SIGNATURE
participant API as FastAPI
participant IN as Intake agent
participant S3 as S3 investor record
You->>AI: "Give me a persona based on my profile"
AI->>MCP: tools/call submit_persona({risk, horizon, goals})
MCP->>MCP: validate schema strictly
MCP->>API: save persona
API->>IN: set_investor (via Orchestrator)
IN->>S3: personas/USER/current.json
IN-->>AI: saved (risk band after account rules)
| Aspect | Detail |
|---|---|
| Tools |
submit_persona(risk: low|mid|high, horizon, goals[1..6], name?, account_type?) and get_persona
|
| Transport | MCP Streamable HTTP, one JSON-RPC message per POST, no sessions |
| Authentication | Per-user URL /mcp/<user>.<signature>: an HMAC of the user id under a server secret, so it cannot be forged or moved to another user. Authorization: Bearer is accepted too. |
| Hardening | Strict schema (additionalProperties: false, length limits), origin allow-list, 60 requests per token per minute |
| Effect | The risk band selects the investor template; goals and horizon are the person's own. From then on every trade check is personalised. |
| Scope | Simulation only; it changes no real account |
The Connect Claude button in the dashboard shows the URL and the steps. Claude's web connectors need a public HTTPS address; for local development use claude mcp add.
| Does | Does not |
|---|---|
| Scores each headline once, offline: sentiment from -1 to +1, company or market scope, topic. Results are saved, so no model runs at trade time for scoring. | Decide a verdict, calculate a metric or predict a price |
| Routes a chat message to the right agent and picks which agent tool to call | Write any figure: its free-text route is rejected if it contains a digit or a prediction |
| Writes the pop-up and chat explanation | Cite evidence that does not exist, or give advice: output is validated and falls back to fixed wording |
Why Nova Lite and not FinBERT or RoBERTa: a general model with a short prompt needs no labelled training data, hosting or GPU, and returns score, scope and category in one call. The project has no labelled finance-news set to train or fairly evaluate a classifier. A specialised model could be swapped in later by changing only the scoring script.
- Test suites: backend, Lambda (63 tests) and AgentCore (15 tests), plus TypeScript and ESLint, run clean.
- Original thresholds: a grid search over the three fixed verdict thresholds against 33 labelled simulated cases classified all 33 and sat in the most robust region.
- Added later and not re-tuned: the risk-band gates, the volatility gate and the persona adjustments are covered by unit tests, not by a new grid search or backtest.
-
Live checks: each button is exercised against the real AWS agents by
scripts/test_buttons_call_agents.py.
- No price forecasts; the app says so on screen.
- The simulated dataset covers a few days and 11 tracked tickers, so "typical daily move" comes from a 60-day history and is a rough estimate.
- Persona stances, the plain-language cutoffs and the persona adjustments are rules of thumb, not tuned values.
- AgentCore observability (traces, token cost) is not enabled yet; per-step runtime names appear in the in-app trace instead.