institutional-trader/backend/python_service

Python Options Flow Processing Service

This service extracts complex SQL logic into Python/pandas for better maintainability and easier testing.

Architecture

• FastAPI: Modern async web framework
• pandas: Data processing and analytics
• asyncpg: Async PostgreSQL driver
• Replaces: Complex 593-line SQL queries with modular Python code

Setup

1. Install dependencies:

cd backend/python_service
pip install -r requirements.txt

2. Configure environment:

cp .env.example .env
# Edit .env with your database credentials

3. Run the service:

python main.py
# Or with uvicorn:
uvicorn main:app --reload --port 8010

API Endpoints

GET /health

Health check endpoint

GET /api/options-flow

Get processed options flow data

Query Parameters:

• start_date (optional): Start date (YYYY-MM-DD), defaults to yesterday
• end_date (optional): End date (YYYY-MM-DD), defaults to today
• min_premium (optional): Minimum premium filter, defaults to 80000
• tol_pct (optional): Tape alignment tolerance, defaults to 0.20

Example:

curl http://localhost:8010/api/options-flow?start_date=2024-01-01&end_date=2024-01-02

GET /api/options-flow/stats

Get flow statistics

Query Parameters:

• symbol (optional): Filter by symbol

Integration with Node.js

The Node.js API layer can call this service via HTTP:

const response = await fetch('http://localhost:8010/api/options-flow?start_date=2024-01-01');
const data = await response.json();

Benefits

1. Maintainability: Complex SQL logic broken into Python functions
2. Testability: Each processing step can be unit tested
3. Flexibility: Easy to add new analytics or modify existing ones
4. Performance: Can leverage pandas vectorization and parallel processing
5. Debugging: Easier to debug Python code than complex SQL

Migration Path

1. ✅ Python service created
2. ⏳ Node.js routes updated to call Python service
3. ⏳ Additional SQL scripts migrated
4. ⏳ Full testing and validation