Management Credibility Analyzer

A Streamlit application that helps retail investors evaluate how accurately and transparently company management communicates with investors — across multiple earnings quarters.

---

What It Does

For a given stock ticker and number of quarters, the app:

1. Retrieves 10-K/10-Q SEC filings, earnings call transcripts, analyst estimates, and stock price data
2. Scores management guidance accuracy — did they deliver on their own estimates for EPS, revenue, and net income?
3. Scores communication transparency — how evasive, jargon-heavy, or pivot-prone was the Q&A?
4. Scores conviction — how confidently did management commit to its guidance vs. hedging with vague language?
5. Computes a composite credibility score (guidance weighted ≥50%) per quarter and overall
6. Analyzes sentiment gap — compares management optimism to analyst sentiment to detect overconfidence or sandbagging
7. Explains stock price swings around each earnings date in a 3-day window
8. Generates a bull and bear case for the company's future, grounded in the credibility data and live market research
9. Audits the entire analysis for data gaps and score inconsistencies

Everything is displayed in a clean, dark-themed Streamlit UI with interactive Plotly charts.

---

Output Tabs

Tab	Contents
Overview	Company info, overall credibility gauge, sub-score breakdown, sentiment comparison chart, stock price vs. credibility line chart
Financials	Per-quarter table: management estimate vs. analyst consensus vs. actual result, color-coded by outcome
Transparency	Transparency and conviction gauges per quarter, detected hedging/confident phrases, Q&A excerpts
Sentiment	Management vs. market/media sentiment bar chart per quarter, gap interpretation, media article sources (WSJ, FT, CNBC, Reuters, MarketWatch)
Stock Movement	Candlestick chart with earnings date annotations, 3-day swing % and explanation per quarter
Outlook	Bull case / bear case side-by-side, risk and opportunity matrix

A collapsible Critique Panel in the sidebar shows data gaps and flags score inconsistencies throughout.

---

Prerequisites

• Python 3.10+
• API keys for: OpenAI, Polygon.io, Qdrant, and Tavily

---

Setup

1. Clone / navigate to the project

cd "Final Project"

2. Create a virtual environment

python -m venv venv
source venv/bin/activate        # macOS / Linux
# venv\Scripts\activate.bat     # Windows

3. Install dependencies

pip install -r requirements.txt

4. Configure API keys

Copy the template and fill in your keys:

cp .env.template .env

Then open .env and add your keys:

OPENAI_API_KEY=sk-...
POLYGON_API_KEY=...
QDRANT_URL=https://your-cluster.qdrant.io
QDRANT_API_KEY=...
TAVILY_API_KEY=tvly-...
FMP_API_KEY=demo           # Optional — Financial Modeling Prep free tier

Never commit .env to version control. It is excluded by .gitignore by convention.

Where to get each key

Key	Where to get it
OPENAI_API_KEY	platform.openai.com/api-keys
POLYGON_API_KEY	polygon.io/dashboard/api-keys
QDRANT_URL + QDRANT_API_KEY	cloud.qdrant.io — create a free cluster
TAVILY_API_KEY	app.tavily.com
FMP_API_KEY	financialmodelingprep.com — demo works for limited use

5. Run the app

streamlit run main.py

The app will open in your browser at http://localhost:8501.

---

How to Use

1. Enter a stock ticker in the sidebar (e.g., AAPL, MSFT, NVDA)
2. Set the number of quarters to analyze (1–12, starting from the most recent completed quarter)
3. Click ▶ Analyze
4. Watch the progress bar as each agent runs — analysis typically takes 2–5 minutes depending on data availability
5. Use ⏸ Pause / ▶ Resume to temporarily suspend the analysis
6. Use ⏹ Stop to cancel and start a new analysis at any time
7. Once complete, navigate the six tabs to explore results

---

Data Availability Notes

• Earnings transcripts are the most important input and the hardest to reliably source. The app tries Tavily web search, then FMP API, then Seeking Alpha. If a transcript cannot be found for a quarter, transparency, conviction, and sentiment scores will show "Insufficient data" — no scores are fabricated.
• Stock price data comes exclusively from Polygon.io. If Polygon is unavailable, price charts will be empty.
• 10-K/10-Q filings fall back to SEC EDGAR if Polygon does not have them.
• The Critique Panel in the sidebar explicitly flags every quarter where data was missing.

---

Scoring Methodology

Guidance Score (0–100)

Measures how accurately management's forward-looking statements predicted actual results.

• EPS, net income, revenue: weight 2.0
• All other metrics: weight 1.0
• exceeded (actual > estimate by >5%) → 100 points
• met (within 5%) → 75 points
• missed (actual < estimate by >5%) → 0 points

Transparency Score (0–100)

Measures openness in Q&A. Baseline 75.

• Penalizes: non-answers, topic pivots, legal boilerplate, high jargon density
• Rewards: direct numeric answers, unprompted negative disclosures

Conviction Score (0–100)

Measures confidence in forward guidance. Baseline 60.

• Penalizes: hedging language ("we hope", "potentially"), wide guidance ranges
• Rewards: definitive language ("we will", "we are on track"), raised or reiterated guidance

Credibility Score (0–100)

Weighted composite:

Credibility = Guidance × 50% + Transparency × 30% + Conviction × 20%

Weights are tunable constants in agents/compute_credibility.py.

Sentiment Gap

Gap = Management Sentiment − Market/Media Sentiment   (range: −2 to +2)

Market/media sentiment is scored from post-earnings coverage (WSJ, FT, CNBC, Reuters, MarketWatch) within 3 days of the earnings date, retrieved via Tavily live search.

Large positive gap = management more bullish than media coverage (potential overconfidence). Large negative gap = management more conservative than coverage (potential upside surprise signal).

---

Architecture

See architecture.md for a full description of the LangGraph workflow, agent responsibilities, data flow diagram, Qdrant schema, and threading model.

---

Project Structure

Final Project/
├── main.py              # Streamlit entry point
├── workflow.py          # LangGraph graph definition
├── requirements.txt
├── .env.template        # API key reference
├── schemas/             # Pydantic output schemas + AnalysisState
├── tools/               # API clients (Polygon, EDGAR, Tavily, Qdrant)
├── agents/              # One file per workflow node (11 total)
└── ui/                  # Streamlit UI components (sidebar, 6 tabs, charts)

---

Tech Stack

Component	Technology
UI	Streamlit + Plotly
Workflow orchestration	LangGraph StateGraph
LLM	OpenAI GPT-4o / GPT-4o-mini
Structured LLM output	Pydantic + with_structured_output
Vector store	Qdrant
Embeddings	OpenAI text-embedding-3-small
Financial data	Polygon.io
SEC filings	EDGAR full-text search API
Web / transcript search	Tavily
Retry logic	Tenacity
Async execution	Python threading + queue.Queue