Metadata-Version: 2.4
Name: xtrade-ai
Version: 1.1.1
Summary: A comprehensive reinforcement learning framework for algorithmic trading
Author-email: Anas Amu <anasamu7@gmail.com>
Maintainer-email: Anas Amu <anasamu7@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/anasamu/xtrade-ai-framework
Project-URL: Documentation, https://xtrade-ai-framework.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/anasamu/xtrade-ai-framework.git
Project-URL: Bug Tracker, https://github.com/anasamu/xtrade-ai-framework/issues
Project-URL: Source Code, https://github.com/anasamu/xtrade-ai-framework
Keywords: trading,reinforcement-learning,algorithmic-trading,machine-learning,finance,ai,trading-bot,quantitative-finance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: psycopg2-binary>=2.9.7
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pandas>=2.2.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: scikit-learn>=1.5.0
Requires-Dist: yfinance>=0.2.18
Requires-Dist: ta>=0.10.2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: click>=8.1.0
Requires-Dist: requests>=2.31.0
Requires-Dist: aiofiles>=23.2.0
Requires-Dist: structlog>=23.2.0
Requires-Dist: psutil>=6.0.0
Provides-Extra: development
Requires-Dist: pytest>=7.4.0; extra == "development"
Requires-Dist: pytest-cov>=4.1.0; extra == "development"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "development"
Requires-Dist: black>=23.0.0; extra == "development"
Requires-Dist: isort>=5.12.0; extra == "development"
Requires-Dist: flake8>=6.0.0; extra == "development"
Requires-Dist: mypy>=1.5.0; extra == "development"
Requires-Dist: pre-commit>=3.3.0; extra == "development"
Requires-Dist: sphinx>=7.0.0; extra == "development"
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "development"
Requires-Dist: myst-parser>=2.0.0; extra == "development"
Requires-Dist: ipython>=8.15.0; extra == "development"
Requires-Dist: jupyter>=1.0.0; extra == "development"
Requires-Dist: notebook>=7.0.0; extra == "development"
Requires-Dist: pytest-mock>=3.11.0; extra == "development"
Requires-Dist: pytest-xdist>=3.3.0; extra == "development"
Requires-Dist: bandit>=1.7.0; extra == "development"
Requires-Dist: safety>=2.3.0; extra == "development"
Requires-Dist: coverage>=7.3.0; extra == "development"
Provides-Extra: gpu
Requires-Dist: torch>=2.2.0; extra == "gpu"
Requires-Dist: torchvision>=0.17.0; extra == "gpu"
Requires-Dist: torchaudio>=2.2.0; extra == "gpu"
Requires-Dist: tensorflow>=2.15.0; extra == "gpu"
Requires-Dist: cupy>=12.0.0; extra == "gpu"
Requires-Dist: scipy>=1.14.0; extra == "gpu"
Requires-Dist: scikit-learn>=1.5.0; extra == "gpu"
Requires-Dist: nvidia-ml-py>=11.0.0; extra == "gpu"
Requires-Dist: gputil>=1.4.0; extra == "gpu"
Requires-Dist: jax[cuda12_pip]>=0.4.0; extra == "gpu"
Requires-Dist: jaxlib[cuda12_pip]>=0.4.0; extra == "gpu"
Provides-Extra: cpu
Requires-Dist: torch>=2.2.0; extra == "cpu"
Requires-Dist: torchvision>=0.17.0; extra == "cpu"
Requires-Dist: torchaudio>=2.2.0; extra == "cpu"
Requires-Dist: tensorflow-cpu>=2.15.0; extra == "cpu"
Requires-Dist: numpy>=1.26.0; extra == "cpu"
Requires-Dist: scipy>=1.14.0; extra == "cpu"
Requires-Dist: scikit-learn>=1.5.0; extra == "cpu"
Requires-Dist: pandas>=2.2.0; extra == "cpu"
Requires-Dist: mkl>=2023.0.0; extra == "cpu"
Requires-Dist: mkl-service>=2.3.0; extra == "cpu"
Dynamic: license-file

# 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**
