# 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:
```bash
cd backend/python_service
pip install -r requirements.txt
```

2. Configure environment:
```bash
cp .env.example .env
# Edit .env with your database credentials
```

3. Run the service:
```bash
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:**
```bash
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:

```javascript
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