StockTrader: a local portfolio checker for sell discipline, decision support only
A local tool that computes risk signals from a holdings file in Python and optionally has a grounded model write a cited brief. It executes no trades and connects to no brokerage.
Key facts
- 29TestsTest functions counted in the repository
Context and problem
Selling decisions are where discipline slips. I built a local tool that reads a holdings CSV, computes risk tiers and a rule-based review score, and can ask a search-grounded model to write a cited brief. It is decision support, not investment advice. It executes no trades, has no brokerage connection, and this page shows no balances, positions or claim about investment results.
Constraints
- Local and single-user: a React dashboard on localhost, backed by a FastAPI service.
- The model may only write prose from facts already computed in code.
- Screenshots show tickers, but no prices, amounts, share counts, cost basis or broker details.
Architecture
How to read it. Read left to right, top row then bottom row. All numbers are computed in code. The model only receives a constrained payload of those facts and writes prose around them. The highlighted box is that payload builder: it is where the rule of no invented numbers is enforced.
Holdings come from an operator-maintained CSV. Market data comes from yfinance, with Alpha Vantage as a fallback. A pure-Python signal engine computes indicators, a risk tier and a sell score. A constrained payload builder turns those results into JSON with a policy of no invented numbers. An optional, quota-checked model call then writes the brief with citations, and a local deterministic brief is used if the call is skipped or fails. Runs and call counts go to SQLite.
Decisions and trade-offs
- Math in code, prose from the model. Scores and thresholds are computed in Python. The model never produces numbers.
- Gemini on the Interactions API by default. The current build uses Gemini models with Search grounding through the Interactions API. Gemma stays on a legacy path with Search grounding, because grounding is not guaranteed for Gemma. An earlier description of the build as using a Google API with Gemma is therefore outdated.
- Graceful fallbacks. Yahoo data falls back to Alpha Vantage, and the model brief falls back to a local one.
Governance and cost
The model is called only on an explicit user action. Refreshing or switching tabs never calls it, and batch research is capped at five items. A daily call limit (default 20) is logged in SQLite and shown in Settings. Past the limit, the app returns the local brief. Prompt guardrails require decision support rather than advice, no trade commands and no new numbers, and limit conclusions to thesis intact, weakening, broken or insufficient evidence. Gemini 3 grounding is billed per search query, so one request can bill several searches.
Outcome
A working personal tool, labelled v1. There is no record of results and I make no claim about outcomes. The 29 tests cover indicators, CSV validation, risk tiers, the model payload, loss review and market fallback.
What comes next
Messaging delivery is paused. The repository holds only a setup guide for it and no code.
Screens
Screens from the working tool. Private details such as amounts, contacts and client posting text are covered or left out. Select a screen to enlarge it.


