Independent build

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.

Designer and builder · Personal finance tooling · Personal tool

  • Python
  • FastAPI
  • React
  • Gemini
  • Gemma
  • SQLite

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

Architecture

StockTrader: math in code, prose from the modelAn operator-maintained CSV and market data feed a pure-Python signal engine. A constrained payload builder passes only computed facts to an optional, quota-checked model call, which writes a cited brief. A local fallback brief is used if the call is skipped. Results go to SQLite and a local dashboard.fallbackHoldings CSVOperator-maintainedMarket dataWith fallback sourceSignal enginePure PythonConstrained payloadComputed facts onlyModel callOptional, quota-checkedLocal fallback briefIf skipped or failedSQLiteRuns and call logLocal dashboardOperator reads

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

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.

Questions and next steps

Danilo Salazar · Origo Solutions