Building PortVise to Decide When to Sell

The three pillars: risk, regime, and theme

When I first tried to write down what makes someone hold or liquidate a position, I kept coming back to three things:

1. Risk
2. Regime
3. Theme

They are not fully independent, and they do not take discretion out of the picture. What they give me is a repeatable structure. They combine with the core question: what was your thesis for taking that position, and does that thesis still hold in the current environment?

Risk comes first

Risk is the most important piece to me. I first learned to think about it through Kelly betting, which ties the size of a bet to both its expected advantage and the chance you are wrong. Later, I became a quant and began thinking more about market neutrality and factor-risk exposure.

A portfolio dominated by beta does fine while the market rises. The test comes when it breaks. Diversification helps then, but only if the holdings are actually exposed to different things. Owning a lot of tickers does very little for you when all of them ride on the same interest-rate environment, the same liquidity conditions, or the same technology theme.

So PortVise looks at risk through several lenses at once: concentration, factor exposure, drawdown scenarios, and how much each position contributes to total portfolio risk. I am not trying to flag volatility as bad. I want to know whether the amount and the kind of risk still match the conviction that put the position there in the first place.

Regime provides context

Whether AI is a bubble or a genuine leap forward is still open. History never repeats exactly, but it rhymes often enough, so regime is the second pillar.

The regime layer measures how close the current environment is to past ones, using market behavior and macro signals to find analogues. Are we in the middle of a long expansion, or near the end of a technology bubble? Is the market paying for growth, defensiveness, duration, or liquidity? No past period is identical to now, so none of this produces a forecast. Whether today looks like 1995 or 2000 still comes down to judgment, yours or your agent's. At least you make that call with both readings in front of you.

Theme is where portfolios repeat themselves

Then there is theme. How could an investing system built right now ignore the AI trade?

Two companies can sit in different sectors, trade under different tickers, and still express exactly the same belief. An AI infrastructure portfolio can look nicely spread across chips, networking, power, and data centers while being one bet on a single capital-spending cycle. So the theme pass asks whether a position still fits the thesis, whether several holdings are saying the same thing, and whether the trade has gotten crowded. It also watches for thesis drift, where a position bought for one reason is now defended for another.

None of this is a momentum filter, and it should not reject a trade for being popular—a strong theme can stay strong far longer than anyone expects. I mostly want the thematic exposure written down where I can see it, so I can tell when I have made the same bet several times over.

Turning the pillars into a review pipeline

Around the three pillars, I built the external data layer on Yahoo Finance and news APIs. Market data supplies prices, returns, and portfolio context. News research adds company-specific developments and the wider macro narrative. That evidence then flows into separate reasoning channels for risk, regime, and theme.

Keeping the channels separate mattered more than I expected. A single prompt will give you a polished answer, but it will also blend facts, calculations, and opinions until you cannot tell where a conclusion came from. Separate agents at least create the opportunity for disagreement, and a validation step can check the outputs for missing inputs or contradictions before anything gets written up as a recommendation.

Not every part of the process belongs to an LLM. I think that in finance—at least in quantitative finance—precision is key. I can live with some variability in the reasoning, but risk and regime are deterministic and computable. Code should calculate things like risk contributions, stress scenarios, and historical features. Models are better at interpreting that evidence, weighing competing explanations, and communicating the decision.

The system learned to sell everything

The three pillars became the main components of the application, and they did find positions worth trimming or dropping. They also exposed a flaw in my original design: given a portfolio, the system could nearly always find a reason to sell.

The bias was structural. The risk agent hunts for concentration and downside. The regime agent hunts for historical danger. The theme agent hunts for crowding, overlap, and thesis drift. Their whole job is to challenge a position, so the combined output leans negative by construction. Convert every concern straight into a reduction and you end up with a portfolio heading toward zero.

That was the useful lesson—and something you definitely don't want to miss in a bull market. To counter it, I designed an allocation agent that checks the minimum level of invested capital and argues the opportunity cost against the benchmark. With some risk appetite and a bit of your discretionary wisdom, this agent is no longer a doomsday teller.

What I learned from building PortVise

Really? I will skip that part. Topics normally covered in this section include design structure, better coding-agent usage and tools, reviewing for AI slop, and so on. I find them useful. If anything, the biggest lesson I learned is that, in the age of AI, you DO need to check your work—especially when you delegate most of the coding to AI. You also need to simplify or clean up the code occasionally, because I am still old-school enough to go into the code and check things myself.

Still, there is one place to put this through a real, fun test. I built an arena with two agents using the same prompt, but with one equipped with PortVise, trading against the real market (unfortunately, not through my own wallet). It looks like it survived that two-week competition ending 2026-07-31.

I think everyone always learns something from the market. That is why I open-sourced this repo—I hope to hear more thoughts on it. You can set it up with a local LLM or more powerful SOTA models. If anyone is interested, I am also sending out a sample brief every day for three small portfolios that cover different styles. It is still a long learning journey for me.

Thank you for taking the time to read through this. I hope you enjoy the article. Let's buy the dip! And sell the top!

Compliance

This is an open-source project. It is not financial advice, and it is not meant to solicit any investment decision. PortVise is decision support: model output can be wrong or incomplete, and market or news data can be delayed or inaccurate. The user bears full responsibility for how any recommendation is interpreted or acted on.