StockSense

Inspiration

Investors have more information than ever: news, filings, prices, economic updates. But it's scattered across dozens of sites and full of jargon. As college students who just started investing, we couldn't answer basic questions about our own money: What's happening with the stocks I own? Why did this one drop? Am I taking on too much risk? Brokerage apps show numbers without explaining them, and professional tools are expensive and built for experts. We wanted an app that tells you what the news means, not just what it says.

What it does

StockSense turns scattered financial information into plain-English insight about your own portfolio.

My Stocks: add the stocks you own and see live prices and daily changes at a glance.
Stock Detail: StockSense reads the latest news for a stock and turns dozens of headlines into a short plain-English summary. Every sentence cites the article it came from, and a Beginner Insight explains one finance term related to the news.
Daily Summary: a quick recap of what happened to your money today.
Portfolio Risk: real risk math on your holdings (beta, volatility, max drawdown, Sharpe ratio, and concentration by stock and sector), with every number explained simply and warnings when too much of your money is in one place.
Ask StockSense: ask questions about your portfolio in plain English.
Goal Benchmarking: an interactive map of major private equity firms across the US, color-coded by sector, with details on hover.

How we built it

StockSense is a Python + Streamlit web app, organized so four people could build in parallel: screens live in pages/, and all data and logic live in a services/ layer.

Market data: Finnhub for live quotes, company profiles, and news; yfinance for price history.
News pipeline: a cleaner removes near-duplicate stories (text similarity via difflib), filters out articles that aren't really about the company, trims the text, and numbers each article so the AI can cite it.
AI summaries: Claude (Haiku) receives only the cleaned, numbered articles plus the day's price move, with strict rules: use only these sources, cite them, and explain, don't advise. It replies in structured JSON.
Trustworthy AI: we don't just trust the model. Our code validates every response: the JSON must parse, every citation must point to a real article, and summaries containing advice phrases (like "safe bet" or "you should buy") are rejected and retried. Article text is sanitized and treated as data, never instructions, to guard against prompt injection.
Risk engine: computed with pandas and numpy from a year of daily returns, using SPY as the market benchmark:

$$\beta = \frac{\text{Cov}(R_p, R_m)}{\text{Var}(R_m)} \qquad \sigma_{\text{annual}} = \sigma_{\text{daily}}\sqrt{252} \qquad \text{Sharpe} = \frac{R_p - R_f}{\sigma_p}$$

Max drawdown is the largest drop from a peak in the portfolio's value over the past year.

Visuals: Plotly charts and a pydeck map, styled with a custom dark theme based on our Figma designs.
Performance and cost: results are cached (quotes for 1 minute, news for 15 minutes, AI summaries by stock and article set) to stay within free API limits and keep AI costs low.
Testing: pytest tests for the news cleaner, AI response validator, and risk math, using made-up data with known answers.

Challenges we ran into

First time collaborating on code: most of our team had never used GitHub, a terminal, or virtual environments. We wrote setup scripts and guides for both Mac and Windows to get everyone running.
"Works on my machine" bugs: one teammate's computer used Python 3.9, which installed an older Streamlit that crashed on newer features. We learned to pin library versions and require a minimum Python version.
A circular import that broke a page right after a merge, which taught us to read tracebacks carefully instead of guessing.
API keys: keeping them out of GitHub with secrets.toml and .gitignore, and debugging a key that got corrupted while being shared.
Keeping the AI honest: early summaries sometimes added outside opinions or sounded like investment advice. Tightening the prompt and adding code-level validation fixed that.
Weekend data: the market was closed all weekend, so we had to handle "last close" prices gracefully.

Accomplishments that we're proud of

AI summaries that cite their sources and are checked by our own code, not just generated and displayed.
A real risk engine with tested math instead of AI-guessed numbers.
A clean, beginner-friendly design that explains every metric in plain English.
Going from barely knowing Git to shipping a multi-page app as a team in one weekend.

What we learned

How to split a project into clear, independent pieces so a team can build in parallel without conflicts.
How APIs, caching, and rate limits work in practice.
Core portfolio risk concepts: beta, volatility, drawdown, Sharpe ratio, and diversification.
That using AI well means constraining and verifying it, not just prompting it.

What's next for StockSense

Import holdings directly from brokerage accounts.
Alerts when big news or risk changes hit your stocks.
A measured accuracy benchmark comparing AI sentiment labels against human-labeled headlines.
Economic context (interest rates, inflation) from FRED, linked to how it affects your holdings.
Cyber alerts that flag hacks and data breaches at companies you own.

StockSense is for learning only and is not financial advice.