GitHub: github.com/crewwithravi/stockbot
What is StockBot?
StockBot is a personal research project I built to explore multi-agent AI architectures applied to financial data. The idea is simple:
- You ask — "Analyze QQQ" (via the API or web dashboard)
- StockBot fetches — Real-time price, 11 technical indicators, and the latest news from Yahoo Finance
- AI interprets — A CrewAI agent reads all the data and produces a human-readable analysis
- You receive — Structured JSON with verified market data and an AI-generated buy/hold/sell recommendation
The key design principle: the numbers are always real. The AI interprets — it never fabricates data.
Why I Built It
As someone working in enterprise application development within financial services — and currently pursuing a Master's in Data Science — I wanted a project that sits at the intersection of production engineering and applied AI.
Most AI demos treat the model as a black box that generates everything. I wanted the opposite: a system where all data is fetched from real APIs, computed locally, and the AI layer is strictly limited to interpretation. If the AI hallucinates, the raw data is still there for the user to verify.
Key Features
| Feature | Description |
|---|---|
| Stock Analysis | Deep-dive into any ticker with price, technicals, news, and an AI recommendation |
| Morning Briefing | AI-generated summary for your entire watchlist in a single request |
| Portfolio Tracking | Track holdings with real-time P&L calculations and AI commentary |
| Price Alerts | Set price targets and check for triggered conditions |
| Quick Quote | Instant data endpoint with zero AI latency |
| Web Dashboard | Built-in dark-themed UI with watchlist, analysis, portfolio, alerts, and briefing tabs |
| Multi-LLM Support | Switch between Ollama (local), Google Gemini, OpenAI, or Anthropic with one env variable |
Architecture: Data-First Design
This is the part I'm most intentional about. StockBot follows a data-first architecture — all market data is fetched directly from external APIs and computed locally. The AI layer receives verified data and is responsible only for interpretation.
Step 1 Fetch real-time data → yfinance (prices, volume, 52-week range) Step 2 Compute technical indicators → ta library (RSI, MACD, SMA, Bollinger, ATR) Step 3 Gather news headlines → yfinance news feed (real headlines with sources) Step 4 AI interpretation → LLM reads verified data and writes analysis Step 5 Structured response → JSON with raw data fields + AI summary
Every API response separates verified data (price, change_pct, technicals) from AI output (ai_analysis, ai_recommendation). Users can trust the numbers independently of whatever the model says.
Tech Stack
| Component | Technology | Purpose |
|---|---|---|
| API Server | FastAPI + Gunicorn | Production-grade async API with OpenAPI docs |
| AI Agents | CrewAI + LiteLLM | Multi-agent orchestration with provider-agnostic LLM support |
| Market Data | yfinance | Real-time prices, company fundamentals, and news |
| Technical Analysis | ta (Python) | RSI, MACD, SMA, Bollinger Bands, ATR computation |
| Database | SQLite (WAL mode) | Persistent storage for portfolio, watchlist, alerts |
| Web Dashboard | HTML + Tailwind CSS + JS | Built-in UI served by FastAPI — zero build step |
| Containerization | Docker Compose | Single-command deployment with volume persistence |
| Reverse Proxy | Caddy (optional) | Auto-HTTPS with Let's Encrypt |
The Web Dashboard
StockBot ships with a built-in web dashboard — no separate frontend build required. It features:
- Dark theme with glass-morphism design
- Live watchlist cards with prices and signal summaries
- Full AI analysis with color-coded BUY / HOLD / SELL badges
- Portfolio table with real-time P&L tracking
- Price alerts with one-click condition checking
- AI morning briefing for your entire watchlist
- Keyboard shortcuts —
Enterfor quick quote,Shift+Enterfor AI analysis
The frontend is pure HTML, JavaScript, and CSS served directly by FastAPI. Zero build step, zero npm.
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET |
/health |
Health check — LLM connection status and provider info |
GET |
/quote/{symbol} |
Quick quote — price, technicals, news (instant, no AI) |
GET |
/analyze/{symbol} |
Full AI analysis with buy/hold/sell recommendation |
POST |
/briefing |
Morning briefing for all watchlist symbols |
GET |
/portfolio |
Portfolio overview with AI summary |
POST / DELETE |
/portfolio |
Add or remove holdings |
GET / POST / DELETE |
/watchlist |
Manage watchlist symbols |
GET / POST |
/alerts |
Create and check price alerts |
Interactive API documentation is auto-generated at /docs (Swagger UI) and /redoc.
Running It Yourself
The quickest way to try StockBot locally:
git clone https://github.com/crewwithravi/stockbot.git cd stockbot pip install -r requirements.txt LLM_PROVIDER=gemini \ LLM_MODEL=gemini-2.0-flash \ GEMINI_API_KEY=your-api-key \ STOCKBOT_DB_PATH=/tmp/stockbot.db \ PYTHONPATH=app \ uvicorn main:app --host 0.0.0.0 --port 5050
Then open http://localhost:5050 in your browser.
For Docker deployment, production configuration, and all LLM provider options, check the full documentation on GitHub.
Technical Indicators
StockBot computes the following indicators from historical OHLCV data:
| Indicator | Parameters | Signal |
|---|---|---|
| RSI | 14-period | Overbought (> 70), Oversold (< 30), Neutral |
| MACD | 12, 26, 9 | Bullish when MACD crosses above signal line |
| SMA 20 / 50 / 200 | 20, 50, 200-day | Short, medium, and long-term trend direction |
| Golden / Death Cross | SMA 50 vs 200 | Golden cross (bullish), Death cross (bearish) |
| Bollinger Bands | 20-period, 2 std dev | Overextended at upper band, oversold at lower |
| ATR | 14-period | Average daily range — measures volatility |
What's Next
- Scheduled alert scanning on configurable intervals
- Push notifications via Telegram and n8n
- Historical backtesting to evaluate signal accuracy
- Interactive charting in the dashboard
Disclaimer
StockBot is an educational project for learning and demonstration purposes. It is not financial advice. AI-generated recommendations are produced by a language model and should never be interpreted as professional financial guidance. Market data is sourced from Yahoo Finance and may be delayed or incomplete. Always consult a qualified financial advisor before making investment decisions. Use at your own risk.
Full source code, deployment guide, and API docs:
github.com/crewwithravi/stockbot
Licensed under MIT · Built with CrewAI, FastAPI, and yfinance