📈 finsight

A team of AI analysts that studies a stock — and briefs you like a real desk would.
A multi-agent equity-analysis assistant built with LangGraph + Gemini, with a Streamlit UI and a zero-key demo mode.

---

Overview

Instead of one prompt doing everything, finsight orchestrates five specialized agents — each an expert in its lane — that read live market data and hand off to a lead strategist. The result is a structured investment brief: snapshot, bull case, bear case, risks, and a clearly caveated view.

🧪 Runs out of the box. Without an Alpha Vantage key, finsight uses bundled demo data, so you can try the full pipeline in one command. Add keys to analyze real tickers.

🏗️ Architecture

flowchart LR
    U([Ticker]) --> C[📥 Data Collector<br/>Alpha Vantage + indicators]
    C --> F[📊 Fundamentals]
    F --> T[📈 Technical]
    T --> S[📰 Sentiment]
    S --> R[⚠️ Risk]
    R --> Y[🧠 Lead Strategist]
    Y --> B([Investment brief + citations])

Loading

State flows through a LangGraph StateGraph: each node reads what it needs and writes its own slice of a shared AnalysisState.

✨ Features

• 🤖 Five specialized agents — data, fundamentals, technicals, sentiment, risk — plus a synthesizing strategist.
• 🧩 LangGraph orchestration — a clean, inspectable state machine, not a tangle of prompts.
• 📊 Real signals — price indicators (SMA-50/200, momentum, volatility) computed in code, not hallucinated.
• 🧪 Zero-key demo mode — bundled sample data means it just runs.
• 🖥️ Streamlit UI — live per-agent progress, metrics, tabbed analyst breakdown, headlines.
• ✅ Solid — typed state, graceful data-error handling, unit tests, and CI.
• ⚖️ Honest — no invented accuracy numbers; every brief ends with a not financial advice disclaimer.

⚡ Quickstart

git clone https://github.com/Meriam-Inoubli/finsight.git
cd finsight
pip install -r requirements.txt
cp .env.example .env          # add GEMINI_API_KEY (Alpha Vantage optional)
streamlit run app.py

Free keys: Gemini · Alpha Vantage (optional — demo data is used without it).

Prefer code?

from finsight import analyze

state = analyze("AAPL")
print(state["report"])        # the final investment brief

🔬 The analyst team

Agent	Role	Uses an LLM?
Data Collector	Fetches overview, prices & news; computes indicators	No — deterministic
Fundamentals Analyst	Valuation & financial health	Yes
Technical Analyst	Trend & momentum from indicators	Yes
Sentiment Analyst	Tone of recent headlines	Yes
Risk Analyst	Key risks across the picture	Yes
Lead Strategist	Synthesizes the final brief	Yes

🧱 Project structure

finsight/
├── app.py                   # Streamlit UI
├── finsight/
│   ├── graph.py             # LangGraph assembly (build_graph / analyze)
│   ├── state.py             # shared AnalysisState (typed)
│   ├── agents/__init__.py   # the 6 agent nodes
│   ├── indicators.py        # price indicators (pure functions)
│   ├── llm.py               # Gemini wrapper
│   └── data/
│       ├── alpha_vantage.py # API client + demo fallback
│       └── sample/          # bundled demo data
└── tests/

🛠️ Tech stack

Python · LangGraph · Google Gemini · Alpha Vantage · pandas · Streamlit

⚖️ Disclaimer

finsight produces AI-generated, educational analysis. It is not financial advice, and nothing here is a recommendation to buy or sell any security.

📄 License

MIT © Meriam Inoubli