AI Stock Analysis

An AI-powered stock research tool that generates professional BUY / HOLD / SELL investment reports using a multi-agent system built with CrewAI, Groq LLM, and Yahoo Finance — completely free to run.

Table of Contents

• What It Does
• Result
• Multi-Agent Architecture
• Tech Stack
• Project Structure
• Getting Started
• Alternative Setup Options
• Key Technical Decisions
• Known Limitations
• Future Improvements
• Skills Demonstrated

What It Does

Enter any stock ticker and the system deploys 3 specialized AI agents that collaborate to produce a comprehensive 1-page investment research report in under 60 seconds. The report includes:

• Executive Summary
• Key Financial Metrics (Revenue, EBITDA, PE Ratio, ROE, Margins)
• News Sentiment & Business Outlook
• Risk Analysis
• Clear BUY / HOLD / SELL recommendation with reasoning
• Interactive 3-month price chart
• Downloadable report as .txt

Result

Enter ticker: AAPL → Stock Data Agent fetches prices, ratios, financials → News Analyst Agent fetches headlines, sector info → Research Agent synthesizes → BUY/HOLD/SELL report

The system uses a sequential multi-agent pipeline — each agent has a specialized role and passes its output to the next:

Multi-Agent Architecture

The system uses a sequential multi-agent pipeline — each agent has a specialized role and passes its output to the next:

┌──────────────────────────┐      ┌──────────────────────────┐
│    Stock Data Analyst    │      │   Financial News Analyst  │
│                          │      │                           │
│  Tools:                  │      │  Tools:                   │
│  • Stock Price Tool      │      │  • Stock News Tool        │
│  • Company Financials    │      │  • SEC Filing Tool        │
│                          │      │                           │
│  Output:                 │      │  Output:                  │
│  • Current price         │      │  • Recent headlines       │
│  • 52-week range         │      │  • News sentiment         │
│  • PE, ROE, margins      │      │  • Business description   │
│  • Revenue & EBITDA      │      │  • Sector & industry      │
│  • 1-month return        │      │                           │
└────────────┬─────────────┘      └─────────────┬─────────────┘
             │                                   │
             └──────────────┬────────────────────┘
                            │  context passed via CrewAI
                            ▼
            ┌───────────────────────────────┐
            │   Senior Research Analyst     │
            │                               │
            │  Tools: None (synthesis only) │
            │                               │
            │  Output:                      │
            │  • Executive Summary          │
            │  • Key Financial Metrics      │
            │  • News Sentiment & Outlook   │
            │  • Risks to Consider          │
            │  • BUY / HOLD / SELL          │
            └───────────────────────────────┘

Why 3 Agents?

| Design Choice | Reasoning | |---|---| | Separate data vs news agents | Each agent is more focused and reliable with a narrow scope | | No tools for research agent | Forces it to synthesize only — prevents it going off-track fetching its own data | | Sequential over hierarchical | Simpler, predictable execution for a linear pipeline | | Context chaining | CrewAI passes agent outputs downstream automatically via context=[] |

Tech Stack

| Tool | Purpose | Why This Choice | |---|---|---| | CrewAI | Multi-agent orchestration | Best framework for role-based agent teams with task chaining | | Groq (llama-3.3-70b-versatile) | LLM inference | Free tier, 10x faster than OpenAI, excellent tool-calling | | yfinance | Stock data & financials | Free, no API key, covers prices + ratios + news | | Streamlit | Web UI | Fastest way to ship a data app with no frontend experience needed | | Plotly | Interactive charts | More control over styling than Streamlit's built-in charts | | python-dotenv | Environment variables | Keeps API keys out of the codebase |

Project Structure

StockAnalysis/
│
├── tools.py          # Data fetching tools — yfinance wrappers for agents
│                     # get_stock_data, get_financials, get_sec_filings, get_stock_news
│
├── agents.py         # Agent definitions — roles, goals, backstories, tool assignments
│                     # data_analyst, news_analyst, research_analyst
│
├── tasks.py          # Task definitions — descriptions, expected outputs, context chaining
│                     # data_task → news_task → report_task
│
├── main.py           # Crew orchestration — wires agents + tasks, CLI entry point
│
├── app.py            # Streamlit UI — price chart, quick stats, AI report rendering
│
├── .env              # API keys (never committed to git)
├── .gitignore        # Excludes .env, venv, __pycache__
└── requirements.txt  # All dependencies

Getting Started

Prerequisites

• Python 3.10 or higher
• A free Groq API key from console.groq.com

1. Clone the repository

git clone https://github.com/yourusername/StockAnalysis.git
cd StockAnalysis

2. Create a virtual environment

# Create
python -m venv venv
 
# Activate — Mac/Linux
source venv/bin/activate
 
# Activate — Windows
venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Set up your API key

Create a .env file in the root directory:

GROQ_API_KEY=your_groq_api_key_here

Get your free key at console.groq.com → API Keys → Create API Key. No credit card required.

5. Run the app

# Streamlit UI (recommended)
streamlit run app.py
 
# OR terminal only
python main.py

Open your browser at http://localhost:8501, enter a ticker and click Run Analysis.

Alternative Setup Options

Alternative LLM Providers

You can swap Groq for any other provider by changing one line in agents.py:

# Current (Free - Groq)
llm = LLM(model="groq/llama-3.3-70b-versatile", api_key=os.getenv("GROQ_API_KEY"))
 
# OpenAI (Paid)
llm = LLM(model="gpt-4o", api_key=os.getenv("OPENAI_API_KEY"))
 
# Anthropic Claude (Paid)
llm = LLM(model="claude-sonnet-4-20250514", api_key=os.getenv("ANTHROPIC_API_KEY"))
 
# Ollama (Free, runs locally — no internet needed)
llm = LLM(model="ollama/llama3.2", base_url="http://localhost:11434")
 
# OpenRouter (Free tier available — access 100+ models)
llm = LLM(model="openrouter/meta-llama/llama-3.3-70b-instruct", api_key=os.getenv("OPENROUTER_API_KEY"))

Alternative Data Sources

You can swap yfinance for richer data sources in tools.py:

# Alpha Vantage (free tier: 25 requests/day)
# https://www.alphavantage.co/support/#api-key
import requests
url = f"https://www.alphavantage.co/query?function=OVERVIEW&symbol={ticker}&apikey={AV_KEY}"
 
# Polygon.io (free tier: 5 requests/min)
# https://polygon.io/
from polygon import RESTClient
client = RESTClient(api_key=POLYGON_KEY)
 
# FMP - Financial Modeling Prep (free tier: 250 requests/day)
# https://financialmodelingprep.com/
url = f"https://financialmodelingprep.com/api/v3/profile/{ticker}?apikey={FMP_KEY}"
 
# SEC EDGAR (completely free, no key needed)
# https://www.sec.gov/cgi-bin/browse-edgar
url = f"https://data.sec.gov/submissions/CIK{cik_number}.json"

Alternative Agent Frameworks

The agent logic can be ported to other frameworks:

# LangGraph — better for complex stateful workflows
from langgraph.graph import StateGraph
 
# AutoGen — better for conversational multi-agent systems
from autogen import AssistantAgent, UserProxyAgent
 
# LlamaIndex Workflows — better if your data is document-heavy
from llama_index.core.workflow import Workflow
 
# Agno (formerly phidata) — lightweight, great for tool-heavy agents
from agno.agent import Agent

Alternative Deployment Options

# Streamlit Cloud (free)
# Push to GitHub → go to share.streamlit.io → connect repo
 
# Render (free tier)
# Add render.yaml to repo → connect at render.com
 
# Hugging Face Spaces (free)
# Create a Space → choose Streamlit → upload files
 
# Docker
docker build -t stock-assistant .
docker run -p 8501:8501 stock-assistant

Key Technical Decisions

Why sequential process over hierarchical? Hierarchical adds a manager agent that delegates to workers — useful for dynamic task assignment. For this project, the pipeline is always the same 3 steps, so sequential is simpler and more predictable.

Why Groq over OpenAI? Groq's free tier is fast enough for real-time use and llama-3.3-70b-versatile handles tool calling reliably. OpenAI would cost ~$0.01–0.05 per analysis which adds up quickly during development.

Why yfinance over paid APIs? The project is fully reproducible without any paid subscriptions. yfinance covers all the financial data needed for a research report. In production, you'd upgrade to Polygon.io or Bloomberg.

Why separate UI from agent logic? app.py only handles rendering. The core pipeline (main.py, agents.py, tasks.py, tools.py) can be wrapped in a FastAPI endpoint or called from a CLI without touching any UI code.

Why show the chart before the AI report? The price chart renders instantly from yfinance. Showing it first gives the user immediate feedback while the 30-60 second agent pipeline runs, improving perceived performance.

Known Limitations

• News titles — yfinance news API recently changed its schema; headlines may show "No title" for some tickers. Fix: replace with NewsAPI or Serper.
• Rate limits — Groq free tier has token-per-minute limits; very long reports on complex tickers may occasionally hit the limit.
• Real-time data — yfinance data has a 15-minute delay for most tickers; not suitable for day trading.
• No historical backtesting — the report is a snapshot, not a backtested strategy.

Future Improvements

• [ ] Add RAG over SEC 10-K/10-Q filings using ChromaDB for deeper analysis
• [ ] Add RAGAS evaluation to score report quality (faithfulness, relevance)
• [ ] Replace yfinance news with NewsAPI for real headlines
• [ ] Add competitor comparison (e.g. AAPL vs MSFT vs GOOGL side by side)
• [ ] Add portfolio analysis — analyze multiple tickers at once
• [ ] Deploy to Streamlit Cloud with a public URL
• [ ] Add email report delivery via SendGrid
• [ ] Add historical report storage so you can track how recommendations change

Skills Demonstrated

| Skill | Where | |---|---| | Multi-agent system design | agents.py — 3 agents with distinct roles and tool assignments | | LLM integration & prompt engineering | agents.py, tasks.py — backstories, goals, expected outputs | | API integration | tools.py — yfinance, error handling, data parsing | | Data pipeline design | tasks.py — sequential context chaining between agents | | Python best practices | Comments, separation of concerns, .env for secrets | | Data visualization | app.py — Plotly interactive charts | | Web app development | app.py — Streamlit UI with responsive layout | | Error handling | app.py — graceful try/catch with user-friendly messages | | Git & version control | .gitignore, structured commits |