Stock Trading Helper

A local stock trading helper app — Python FastAPI backend, React + Vite frontend, Gemini 2.5 Flash AI agent. Everything runs on free tiers.

Vanik is the Sanskrit term for a merchant or trader.

Setup

1. Get free API keys

• Alpha Vantage (25 req/day free): https://www.alphavantage.co/support/#api-key
• Gemini (the app conservatively caps itself at 240 calls/day): https://aistudio.google.com/apikey

2. Backend

cd backend
cp .env.example .env   # fill in your keys
pip install -r requirements.txt
uvicorn main:app --reload

FastAPI interactive docs at: http://localhost:8000/docs

3. Frontend

cd frontend
npm install
npm run dev

App at: http://localhost:5173

---

Features

Tab	What it does
AI Assistant	Natural-language Gemini research with multi-turn context, explicit tool provenance, freshness details, follow-up actions, and privacy-aware Gmail/Calendar tools
Screener	Filter up to 25 tickers by P/E and 3-month average volume; sort and export results
Portfolio	Track/edit/import/export local holdings, refresh prices, and review P&L and concentration
Signals	RSI, MACD, SMA 50/200 position, crossover dates, and a composite research signal
Chart	Close-price line chart with SMA overlays and an optional volume chart
Earnings	Fetch next earnings dates and add reminders directly to Google Calendar
Predict	Experimental RandomForest estimate with held-out quality and uncertainty disclosures
Backtest	Walk-forward signal simulation with configurable period, costs, and slippage
Benchmarks	Local developer dashboard for latency, cache behavior, provider health, and AI usage

---

Notes

• Gemini usage: 10 RPM and a conservative 240-call/day app limit. The app warns at ≤20 remaining.
• Alpha Vantage free tier: 25 req/day. The SQLite cache (24 hr TTL for fundamentals) protects this limit.
• Data caching: Quotes → 5 min · History → 30 min · Signals → 15 min · Fundamentals → 24 hr
• Freshness: price-bearing screens display source/as-of metadata. Quotes may still be delayed.
• Gmail + Calendar features require the corresponding Google MCP connection to be authenticated.
• This app is a personal research helper. It does not place orders or give financial advice.

---

Project structure

vanik/
├── backend/
│   ├── main.py           # FastAPI app, all endpoints
│   ├── data.py           # yfinance + Alpha Vantage fetching
│   ├── signals.py        # RSI, MACD, SMA calculations
│   ├── indicators.py     # Shared technical indicators
│   ├── predictor.py      # Experimental ML estimates
│   ├── backtest.py       # Walk-forward strategy simulation
│   ├── metrics.py        # Local performance telemetry
│   ├── cache.py          # SQLite cache wrapper with TTL
│   ├── agent.py          # Gemini agent loop + function calling
│   ├── mcp_gmail.py      # Gmail MCP integration
│   ├── mcp_calendar.py   # Google Calendar MCP integration
│   ├── .env              # API keys (never commit)
│   └── requirements.txt
└── frontend/
    ├── src/
    │   ├── App.jsx
    │   ├── api.js
    │   └── components/
    │       ├── Chat.jsx
    │       ├── Screener.jsx
    │       ├── Portfolio.jsx
    │       ├── Signals.jsx
    │       ├── Chart.jsx
    │       ├── EarningsCalendar.jsx
    │       ├── Prediction.jsx
    │       ├── Backtest.jsx
    │       └── Benchmarks.jsx
    ├── index.html
    ├── vite.config.js
    └── package.json