Installation

System Requirements

Before installing OptionStrat AI, ensure your system meets these requirements:

Backend Requirements

Python: Version 3.8 or higher
pip: Python package manager
Operating System: Windows, macOS, or Linux
RAM: Minimum 4GB (8GB recommended for large option chains)
Storage: ~500MB for dependencies

Frontend Requirements

Node.js: Version 16 or higher
npm: Version 7 or higher (comes with Node.js)
Modern Browser: Chrome, Firefox, Safari, or Edge (latest version)

API Requirements

OpenAI API Key: Required for AI Insights feature (optional for other features)
Internet Connection: Required for fetching real-time market data from Yahoo Finance

You can verify your Python and Node.js versions:

python --version  # or python3 --version
node --version
npm --version

Backend Installation

Navigate to Backend Directory

Open your terminal and navigate to the backend folder:

cd ~/workspace/source/backend

Create Virtual Environment

Creating a virtual environment isolates your Python dependencies:

# Create virtual environment
python -m venv venv

# Activate the environment
venv\Scripts\activate

You’ll see (venv) in your terminal prompt when activated.

To deactivate the virtual environment later, simply run deactivate

Install Python Dependencies

With the virtual environment activated, install all required packages:

pip install -r requeriments.txt

This installs all dependencies including:

FastAPI - Async web framework
Uvicorn - ASGI server
Pydantic - Data validation
NumPy & Pandas - Numerical computing
SciPy - Black-Scholes calculations
yfinance & yahooquery - Market data
LiteLLM - LLM router (OpenAI/OpenRouter)
VaderSentiment - News sentiment analysis
BeautifulSoup4 - Web scraping

The installation may take 2-5 minutes depending on your internet speed.

Configure Environment Variables

Create a .env file in the backend directory:

cp .env.example .env

Edit the .env file with your preferred text editor and configure your API keys:

.env

# AI Provider Configuration
AI_PROVIDER=openai

# OpenAI Configuration (recommended)
OPENAI_API_KEY=sk-your-actual-openai-key-here
OPENAI_DEFAULT_CHAT_MODEL=gpt-4o

# Alternative: OpenRouter (if using OpenRouter instead)
# OPENROUTER_API_KEY=your-openrouter-key-here
# DEFAULT_CHAT_MODEL=openrouter/free

Never commit your .env file to version control. It contains sensitive API keys. The .env file is already in .gitignore to prevent accidental commits.

Getting an OpenAI API Key

Visit OpenAI Platform
Sign up or log in to your account
Navigate to API Keys section
Click Create new secret key
Copy the key and paste it in your .env file

The GPT-4o model (gpt-4o) provides excellent analysis. You can also use gpt-4-turbo or gpt-3.5-turbo for lower costs.

Verify Backend Installation

Start the FastAPI development server:

uvicorn app.main:app --reload

You should see output like:

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Test the API by opening your browser to http://127.0.0.1:8000/ or using curl:

curl http://127.0.0.1:8000/

Expected response:

{
  "status": "ok",
  "message": "OptionStrat Backend is running."
}

Frontend Installation

Navigate to Frontend Directory

Open a new terminal window (keep the backend running) and navigate to the frontend folder:

cd ~/workspace/source/frontend

Install Node Dependencies

Install all required npm packages:

npm install

This installs:

React 19 - UI framework
Vite - Fast build tool and dev server
Zustand - State management
Axios - HTTP client for API calls
Recharts - Data visualization
Lucide React - Icon library

The installation typically takes 1-3 minutes. You’ll see a node_modules/ folder created with all dependencies.

Configure API Endpoint (Optional)

The frontend is pre-configured to connect to http://127.0.0.1:8000/api. If you need to change this, edit src/api/client.js:

src/api/client.js

import axios from 'axios';

const api = axios.create({
    baseURL: 'http://127.0.0.1:8000/api',  // Change this if backend runs elsewhere
    timeout: 10000,
    headers: {
        'Content-Type': 'application/json',
    },
});

export default api;

Start Development Server

Launch the Vite development server:

npm run dev

You should see:

  VITE v7.3.1  ready in 523 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Open your browser to the URL shown (typically http://localhost:5173/).

Verify Frontend Installation

You should see the OptionStrat AI welcome screen with:

The application header showing “OptionStrat AI”
A search box for entering tickers
Quick-select buttons for AAPL, TSLA, NVDA, and SPY
A mascot/welcome message

The frontend supports hot-reload. Any changes you make to the code will automatically refresh in the browser.

Complete Setup Verification

With both backend and frontend running, verify the complete integration:

Load a Ticker

In your browser at http://localhost:5173/
Type AAPL in the search box
Press Enter

You should see:

The current AAPL spot price appear in the header
Available expiration dates load in the dropdown
The option chain table populates with calls and puts

Test API Endpoints

Verify each backend endpoint is working:

# Health check
curl http://127.0.0.1:8000/

# Get expirations for a ticker
curl http://127.0.0.1:8000/api/options/expirations/SPY

# Get option chain
curl "http://127.0.0.1:8000/api/options/chain/SPY?expiration=2026-06-19"

# Test strategy recommender
curl -X GET "http://127.0.0.1:8000/api/options/recommend/AAPL?bias=neutral&risk_profile=balanced&min_dte=30&max_dte=60"

Test AI Insights

If you configured your OpenAI API key:

Build a simple strategy (e.g., buy a call)
Click “Analizar con IA” in the AI Insights panel
You should see the AI analysis appear with risk score and recommendations

If the AI Insights don’t work, verify your OPENAI_API_KEY is correctly set in the .env file and the backend has been restarted.

Environment Variables Reference

Here’s a complete reference of all available environment variables:

Variable	Required	Default	Description
`AI_PROVIDER`	No	`openai`	AI provider to use (`openai` or `openrouter`)
`OPENAI_API_KEY`	Yes*	-	Your OpenAI API key for AI insights
`OPENAI_DEFAULT_CHAT_MODEL`	No	`gpt-4o`	OpenAI model to use for analysis
`OPENROUTER_API_KEY`	Yes**	-	Your OpenRouter API key (if using OpenRouter)
`DEFAULT_CHAT_MODEL`	No	`openrouter/free`	OpenRouter model selection

*Required only if AI_PROVIDER=openai
**Required only if AI_PROVIDER=openrouter

Troubleshooting

Backend Issues

ModuleNotFoundError: No module named 'fastapi'

Problem: Dependencies not installed or wrong Python environmentSolution:

# Ensure virtual environment is activated
source venv/bin/activate  # macOS/Linux
venv\Scripts\activate      # Windows

# Reinstall dependencies
pip install -r requeriments.txt

Port 8000 is already in use

Problem: Another application is using port 8000Solution:

# Option 1: Kill the process using port 8000
# Windows
netstat -ano | findstr :8000
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:8000 | xargs kill -9

# Option 2: Use a different port
uvicorn app.main:app --reload --port 8001

Update the frontend src/api/client.js baseURL to match the new port.

OpenAI API Error: Invalid API Key

Problem: API key is incorrect or not properly setSolution:

Verify your .env file exists in the backend/ directory
Check the API key format (starts with sk-)
Ensure no extra spaces or quotes around the key
Restart the backend server after editing .env

# Stop the server (Ctrl+C)
# Verify .env content
cat .env

# Restart server
uvicorn app.main:app --reload

Yahoo Finance data not loading

Problem: Network issues or Yahoo Finance rate limitingSolution:

Check your internet connection
Try a different ticker symbol
Wait a few minutes if rate-limited
Verify yfinance is installed: pip show yfinance

'venv' is not recognized (Windows)

Problem: Virtual environment not created properlySolution:

# Try using py launcher
py -m venv venv

# Or specify Python version
python3 -m venv venv

# If still failing, install virtualenv
pip install virtualenv
virtualenv venv

Frontend Issues

npm ERR! code ENOENT

Problem: npm not installed or not in PATHSolution:

Install Node.js from nodejs.org
Restart your terminal
Verify installation: node --version && npm --version

Port 5173 is already in use

Problem: Another Vite dev server is runningSolution:

# Vite will automatically use the next available port
# Or specify a different port:
npm run dev -- --port 5174

Cannot connect to backend / Network Error

Problem: Backend not running or CORS issueSolution:

Verify backend is running: curl http://127.0.0.1:8000/
Check the frontend is using correct API URL in src/api/client.js
Verify no firewall is blocking connections
Check browser console (F12) for detailed error messages

npm install fails with EACCES

Problem: Permission issues on macOS/LinuxSolution:

# Option 1: Fix npm permissions
sudo chown -R $USER /usr/local/lib/node_modules

# Option 2: Use nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install node

React components not rendering

Problem: Build or dependency issueSolution:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear Vite cache
rm -rf node_modules/.vite

# Restart dev server
npm run dev

Data and API Issues

Option chain returns empty data

Problem: No options available for selected ticker/expirationSolution:

Try a more liquid ticker (AAPL, SPY, TSLA)
Select a different expiration date
Some stocks don’t have listed options
Check if market is open (data updates during trading hours)

Greeks calculation errors

Problem: Invalid inputs for Black-Scholes modelSolution: The system handles this automatically, but if you see issues:

Check that implied volatility > 0
Verify expiration date is in the future
Ensure strike prices are valid numbers

AI Insights not appearing

Problem: OpenAI API key not configured or quota exceededSolution:

Verify .env file has valid OPENAI_API_KEY
Check OpenAI account has available credits
View backend logs for detailed error messages
Try using gpt-3.5-turbo model for lower costs

Production Deployment

For deploying OptionStrat AI to production:

Production deployment requires additional security configurations including:

Proper CORS settings (replace allow_origins=["*"] in app/main.py)
Environment-specific API keys
HTTPS/SSL certificates
Rate limiting and authentication
Database for user portfolios (optional)

Backend Production

# Install production server
pip install gunicorn

# Run with production settings
gunicorn app.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Frontend Production

# Build production bundle
npm run build

# Serve with a static file server
npm install -g serve
serve -s dist -p 5173

For production deployment, consider using Docker, AWS, Heroku, or Vercel for easy scaling and management.

Performance Optimization

Backend Performance

Caching: Implement Redis for caching option chains and market data
Database: Add PostgreSQL for storing historical strategies and user data
Rate Limiting: Add rate limiting to prevent API abuse
Async Processing: Use Celery for long-running calculations

Frontend Performance

Code Splitting: Vite handles this automatically
Lazy Loading: Components load on demand
Debouncing: Already implemented in Zustand store for API calls
CDN: Serve static assets from a CDN in production

Next Steps

Quickstart Guide

Build your first strategy in 5 minutes

API Reference

Explore all available endpoints

Architecture

Understand the system design

Core Features

Explore the platform’s powerful features

Additional Resources

FastAPI Docs: fastapi.tiangolo.com
React Docs: react.dev
Vite Docs: vitejs.dev
Options Trading Basics: Understanding Greeks, spreads, and risk management

Get Started

Core Features

Guides

Technical Reference

System Requirements

Backend Requirements

Frontend Requirements

API Requirements

Backend Installation

Getting an OpenAI API Key

Frontend Installation

Complete Setup Verification

Environment Variables Reference

Troubleshooting

Backend Issues

Frontend Issues

Data and API Issues

Production Deployment

Backend Production

Frontend Production

Performance Optimization

Backend Performance

Frontend Performance

Next Steps

Quickstart Guide

API Reference

Architecture

Core Features

Additional Resources

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Technical Reference

​System Requirements

​Backend Requirements

​Frontend Requirements

​API Requirements

​Backend Installation

​Getting an OpenAI API Key

​Frontend Installation

​Complete Setup Verification

​Environment Variables Reference

​Troubleshooting

​Backend Issues

​Frontend Issues

​Data and API Issues

​Production Deployment

​Backend Production

​Frontend Production

​Performance Optimization

​Backend Performance

​Frontend Performance

​Next Steps

Quickstart Guide

API Reference

Architecture

Core Features

​Additional Resources

Build docs developers (and LLMs) love

System Requirements

Backend Requirements

Frontend Requirements

API Requirements

Backend Installation

Getting an OpenAI API Key

Frontend Installation

Complete Setup Verification

Environment Variables Reference

Troubleshooting

Backend Issues

Frontend Issues

Data and API Issues

Production Deployment

Backend Production

Frontend Production

Performance Optimization

Backend Performance

Frontend Performance

Next Steps

Additional Resources