xtrade-ai 1.1.1
A comprehensive reinforcement learning framework for algorithmic trading
License: MIT
Requires Python: <3.14,>=3.8
Keywords: trading, reinforcement-learning, algorithmic-trading, machine-learning, finance, ai, trading-bot, quantitative-finance

# XTrade-AI Framework

A comprehensive AI-powered trading framework built with Python, featuring machine learning models, backtesting, and live trading capabilities.

## 🏗️ Architecture

XTrade-AI Framework follows the **Model-View-Controller (MVC)** architecture pattern, providing a clean separation of concerns:

- **Models** (`xtrade_ai/model/`): Database models and data access layer
- **Controllers** (`xtrade_ai/controller/`): Business logic and application logic
- **Routers** (`xtrade_ai/router/`): API endpoints and request handling
- **Database** (`xtrade_ai/database/`): Database connection and migration management

## ✨ Features

- **MVC Architecture**: Clean, maintainable code structure
- **PostgreSQL + TimescaleDB**: High-performance time-series database
- **FastAPI**: Modern, fast web framework for building APIs
- **Machine Learning**: Support for XGBoost, scikit-learn, and custom models
- **Backtesting Engine**: Comprehensive backtesting with performance metrics
- **Live Trading**: Real-time trading with multiple brokers
- **Data Management**: Efficient market data storage and retrieval
- **User Management**: Multi-user support with role-based access control
- **Migration System**: Database schema versioning and management

## 🚀 Quick Start

### Prerequisites

- Python 3.8+
- PostgreSQL 12+
- TimescaleDB extension

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/your-username/xtrade-ai-framework.git
   cd xtrade-ai-framework
   ```

2. **Create virtual environment**
   ```bash
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements/base.txt
   ```

4. **Set up environment variables**
   ```bash
   cp config/env.example .env
   # Edit .env with your configuration
   ```

5. **Set up database**
   ```bash
   # Create PostgreSQL database
   createdb xtrade_ai
   
   # Run migrations
   python -m xtrade_ai.cli db migrate
   ```

6. **Start the API server**
   ```bash
   python -m xtrade_ai.cli api serve
   ```

## 📁 Project Structure

```
xtrade_ai/
├── api.py                 # Main API application
├── cli.py                 # Command-line interface
├── database/              # Database layer
│   ├── connection.py      # Database connection manager
│   └── migration_manager.py # Migration system
├── model/                 # Data models (MVC Model)
│   ├── base_model.py      # Base model class
│   ├── user_model.py      # User management
│   ├── model_model.py     # ML model management
│   ├── training_model.py  # Training sessions
│   ├── backtest_model.py  # Backtest sessions
│   ├── prediction_model.py # Predictions
│   └── market_data_model.py # Market data
├── controller/            # Business logic (MVC Controller)
│   ├── base_controller.py # Base controller
│   ├── user_controller.py # User management logic
│   ├── model_controller.py # Model management logic
│   ├── training_controller.py # Training logic
│   ├── backtest_controller.py # Backtest logic
│   ├── prediction_controller.py # Prediction logic
│   └── market_data_controller.py # Market data logic
├── router/                # API endpoints (MVC View)
│   ├── base_router.py     # Base router
│   ├── user_router.py     # User endpoints
│   ├── model_router.py    # Model endpoints
│   ├── training_router.py # Training endpoints
│   ├── backtest_router.py # Backtest endpoints
│   ├── prediction_router.py # Prediction endpoints
│   └── market_data_router.py # Market data endpoints
├── migrations/            # Database migrations
│   └── migration_001_initial_schema.sql
└── utils/                 # Utility functions
    ├── logger.py          # Logging configuration
    └── ...                # Other utilities
```

## 🗄️ Database Schema

The framework uses PostgreSQL with TimescaleDB for efficient time-series data storage:

- **Users**: User authentication and management
- **Models**: Machine learning model registry
- **Training Sessions**: Model training tracking
- **Backtest Sessions**: Backtesting results and metrics
- **Market Data**: OHLCV data with TimescaleDB hypertables
- **Predictions**: Model prediction requests and results

## 🔧 CLI Commands

### Database Management
```bash
# Check migration status
python -m xtrade_ai.cli db status

# Run migrations
python -m xtrade_ai.cli db migrate

# Rollback migrations
python -m xtrade_ai.cli db rollback --steps 1

# Create new migration
python -m xtrade_ai.cli db create-migration add_new_table

# Test database connection
python -m xtrade_ai.cli db connect
```

### API Management
```bash
# Start API server
python -m xtrade_ai.cli api serve

# Open API documentation
python -m xtrade_ai.cli api docs
```

### General
```bash
# Show framework information
python -m xtrade_ai.cli info
```

## 🌐 API Endpoints

The framework provides RESTful API endpoints:

- **Authentication**: `/api/v1/users/auth/*`
- **User Management**: `/api/v1/users/*`
- **Models**: `/api/v1/models/*`
- **Training**: `/api/v1/training/*`
- **Backtesting**: `/api/v1/backtest/*`
- **Predictions**: `/api/v1/predictions/*`
- **Market Data**: `/api/v1/market-data/*`

## 🔐 Authentication

The framework supports:
- JWT-based authentication
- Role-based access control (User/Admin)
- API key management
- Secure password hashing with bcrypt

## 📊 Data Management

- **Market Data**: Efficient storage with TimescaleDB hypertables
- **Model Storage**: Local and cloud storage support (S3, GCS)
- **Data Validation**: Pydantic models for data validation
- **Bulk Operations**: Optimized for high-volume data processing

## 🧪 Testing

```bash
# Run tests
python -m pytest tests/

# Run with coverage
python -m pytest --cov=xtrade_ai tests/
```

## 📈 Performance

- **Database**: Connection pooling and optimized queries
- **API**: Async FastAPI with high concurrency
- **Data Processing**: Efficient pandas operations
- **Caching**: Redis integration for performance

## 🚀 Deployment

### Docker
```bash
# Build image
docker build -t xtrade-ai .

# Run container
docker run -p 8000:8000 xtrade-ai
```

### Production
- Use production-grade PostgreSQL
- Enable SSL/TLS
- Set up proper logging and monitoring
- Configure backup strategies

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Documentation**: [docs/](documentation/)
- **Issues**: [GitHub Issues](https://github.com/your-username/xtrade-ai-framework/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-username/xtrade-ai-framework/discussions)

## 🔮 Roadmap

- [ ] Advanced ML model support (PyTorch, TensorFlow)
- [ ] Real-time streaming data
- [ ] Advanced risk management
- [ ] Multi-asset portfolio optimization
- [ ] Cloud-native deployment
- [ ] Advanced analytics dashboard

---

**Built with ❤️ for the trading community**