tensortrade 1.0.3__tar.gz → 1.0.4__tar.gz

tensortrade-1.0.4/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: tensortrade
+Version: 1.0.4
+Summary: TensorTrade: A reinforcement learning library for training, evaluating, and deploying robust trading agents.
+Home-page: https://github.com/tensortrade-org/tensortrade
+Author: Adam King <adamjking3@gmail.com>, Matthew Brulhardt <mwbrulhardt@gmail.com>
+Maintainer: Carlo Grisetti <carlo.grisetti@gmail.com>
+License: Apache 2.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Natural Language :: English
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: pandas<3.0,>=2.2.3
+Requires-Dist: gymnasium>=0.28.1
+Requires-Dist: pyyaml>=5.1.2
+Requires-Dist: stochastic>=0.6.0
+Requires-Dist: tensorflow>=2.15.1
+Requires-Dist: ipython>=7.12.0
+Requires-Dist: matplotlib>=3.1.1
+Requires-Dist: plotly>=4.5.0
+Requires-Dist: deprecated>=1.2.13
+Requires-Dist: ta>=0.4.7
+Requires-Dist: pytest>=7.0.0
+Provides-Extra: tests
+Requires-Dist: pytest>=7.0.0; extra == "tests"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Requires-Dist: sphinxcontrib.apidoc; extra == "docs"
+Requires-Dist: nbsphinx; extra == "docs"
+Requires-Dist: nbsphinx_link; extra == "docs"
+Requires-Dist: recommonmark; extra == "docs"
+Requires-Dist: sphinx_markdown_tables; extra == "docs"
+Requires-Dist: ipykernel; extra == "docs"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: maintainer
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+TensorTrade: A reinforcement learning library for training, evaluating, and deploying robust trading agents.

tensortrade-1.0.4/README.md

@@ -0,0 +1,204 @@
+<p align="center">
+  <img src="docs/source/_static/logo.jpg" width="200" alt="TensorTrade Logo">
+</p>
+
+# TensorTrade
+
+**Train RL agents to trade. Can they beat Buy-and-Hold?**
+
+[![Tests](https://github.com/tensortrade-org/tensortrade/actions/workflows/tests.yml/badge.svg)](https://github.com/tensortrade-org/tensortrade/actions/workflows/tests.yml)
+[![Documentation Status](https://readthedocs.org/projects/tensortrade/badge/?version=latest)](https://tensortrade.org)
+[![Apache License](https://img.shields.io/github/license/tensortrade-org/tensortrade.svg?color=brightgreen)](http://www.apache.org/licenses/LICENSE-2.0)
+[![Discord](https://img.shields.io/discord/592446624882491402.svg?color=brightgreen)](https://discord.gg/ZZ7BGWh)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+
+TensorTrade is an open-source Python framework for building, training, and evaluating reinforcement learning agents for algorithmic trading. The framework provides composable components for environments, action schemes, reward functions, and data feeds that can be combined to create custom trading systems.
+
+## Quick Start
+
+```bash
+# Requires Python 3.12+
+python3.12 -m venv tensortrade-env && source tensortrade-env/bin/activate
+pip install -e .
+
+# For training with Ray/RLlib (recommended)
+pip install -r examples/requirements.txt
+
+# Run training
+python examples/training/train_simple.py
+```
+
+## Documentation & Tutorials
+
+📚 **[Tutorial Index](docs/tutorials/index.md)** — Start here for the complete learning curriculum.
+
+### Foundations
+- [The Three Pillars](docs/tutorials/01-foundations/01-three-pillars.md) — RL + Trading + Data concepts
+- [Architecture](docs/tutorials/01-foundations/02-architecture.md) — How components work together
+- [Your First Run](docs/tutorials/01-foundations/03-your-first-run.md) — Run and understand output
+
+### Domain Knowledge
+- [Trading for RL Practitioners](docs/tutorials/02-domains/track-a-trading-for-rl/01-trading-basics.md)
+- [RL for Traders](docs/tutorials/02-domains/track-b-rl-for-traders/01-rl-fundamentals.md)
+- [Common Failures](docs/tutorials/02-domains/track-b-rl-for-traders/02-common-failures.md) — Critical pitfalls to avoid
+- [Full Introduction](docs/tutorials/02-domains/track-c-full-intro/README.md) — New to both domains
+
+### Core Components
+- [Action Schemes](docs/tutorials/03-components/01-action-schemes.md) — BSH and order execution
+- [Reward Schemes](docs/tutorials/03-components/02-reward-schemes.md) — Why PBR works
+- [Observers & Feeds](docs/tutorials/03-components/03-observers-feeds.md) — Feature engineering
+
+### Training
+- [First Training](docs/tutorials/04-training/01-first-training.md) — Train with Ray RLlib
+- [Ray RLlib Deep Dive](docs/tutorials/04-training/02-ray-rllib.md) — Configuration options
+- [Optuna Optimization](docs/tutorials/04-training/03-optuna.md) — Hyperparameter tuning
+
+### Advanced Topics
+- [Overfitting](docs/tutorials/05-advanced/01-overfitting.md) — Detection and prevention
+- [Commission Analysis](docs/tutorials/05-advanced/02-commission.md) — Key research findings
+- [Walk-Forward Validation](docs/tutorials/05-advanced/03-walk-forward.md) — Proper evaluation
+
+### Additional Resources
+- [Experiments Log](docs/EXPERIMENTS.md) — Full research documentation
+- [Environment Setup](docs/ENVIRONMENT_SETUP.md) — Detailed installation guide
+- [API Reference](https://www.tensortrade.org/en/latest/)
+
+---
+
+## Research Findings
+
+We conducted extensive experiments training PPO agents on BTC/USD. Key results:
+
+| Configuration | Test P&L | vs Buy-and-Hold |
+|---------------|----------|-----------------|
+| Agent (0% commission) | +$239 | +$594 |
+| Agent (0.1% commission) | -$650 | -$295 |
+| Buy-and-Hold | -$355 | — |
+
+The agent demonstrates directional prediction capability at zero commission. The primary challenge is trading frequency—commission costs currently exceed prediction profits. See [EXPERIMENTS.md](docs/EXPERIMENTS.md) for methodology and detailed analysis.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        TradingEnv                               │
+│                                                                 │
+│   Observer ──────> Agent ──────> ActionScheme ──────> Portfolio │
+│   (features)      (policy)      (BSH/Orders)        (wallets)  │
+│       ^                                                  │      │
+│       └──────────── RewardScheme <───────────────────────┘      │
+│                        (PBR)                                    │
+│                                                                 │
+│   DataFeed ──────> Exchange ──────> Broker ──────> Trades       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+| Component | Purpose | Default |
+|-----------|---------|---------|
+| ActionScheme | Converts agent output to orders | BSH (Buy/Sell/Hold) |
+| RewardScheme | Computes learning signal | PBR (Position-Based Returns) |
+| Observer | Generates observations | Windowed features |
+| Portfolio | Manages wallets and positions | USD + BTC |
+| Exchange | Simulates execution | Configurable commission |
+
+---
+
+## Training Scripts
+
+| Script | Description |
+|--------|-------------|
+| `examples/training/train_simple.py` | Basic demo with wallet tracking |
+| `examples/training/train_ray_long.py` | Distributed training with Ray RLlib |
+| `examples/training/train_optuna.py` | Hyperparameter optimization |
+| `examples/training/train_best.py` | Best configuration from experiments |
+
+---
+
+## Installation
+
+**Requirements:** Python 3.11 or 3.12
+
+```bash
+# Create environment
+python3.12 -m venv tensortrade-env
+source tensortrade-env/bin/activate  # Windows: tensortrade-env\Scripts\activate
+
+# Install
+pip install --upgrade pip
+pip install -r requirements.txt
+pip install -e .
+
+# Verify
+pytest tests/tensortrade/unit -v
+
+# Training dependencies (optional)
+pip install -r examples/requirements.txt
+```
+
+See [ENVIRONMENT_SETUP.md](docs/ENVIRONMENT_SETUP.md) for platform-specific instructions and troubleshooting.
+
+### Docker
+
+```bash
+make run-notebook  # Jupyter
+make run-docs      # Documentation
+make run-tests     # Test suite
+```
+
+---
+
+## Project Structure
+
+```
+tensortrade/
+├── tensortrade/           # Core library
+│   ├── env/              # Trading environments
+│   ├── feed/             # Data pipeline
+│   ├── oms/              # Order management
+│   └── data/             # Data fetching
+├── examples/
+│   ├── training/         # Training scripts
+│   └── notebooks/        # Jupyter tutorials
+├── docs/
+│   ├── tutorials/        # Learning curriculum
+│   └── EXPERIMENTS.md    # Research log
+└── tests/
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "No stream satisfies selector" | Update to v1.0.4-dev1+ |
+| Ray installation fails | Run `pip install --upgrade pip` first |
+| NumPy version conflict | `pip install "numpy>=1.26.4,<2.0"` |
+| TensorFlow CUDA issues | `pip install tensorflow[and-cuda]>=2.15.1` |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+Priority areas:
+1. Trading frequency reduction (position sizing, holding periods)
+2. Commission-aware reward schemes
+3. Alternative action spaces
+
+---
+
+## Community
+
+- [Discord](https://discord.gg/ZZ7BGWh)
+- [GitHub Issues](https://github.com/notadamking/tensortrade/issues)
+- [Documentation](https://www.tensortrade.org/)
+
+---
+
+## License
+
+[Apache 2.0](LICENSE)

{tensortrade-1.0.3 → tensortrade-1.0.4}/docs/.readthedocs.yml

@@ -9,10 +9,6 @@ version: 2
 sphinx:
   configuration: docs/conf.py
 
-# Build documentation with MkDocs
-#mkdocs:
-#  configuration: mkdocs.yml
-
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all
 

tensortrade-1.0.4/docs/ENVIRONMENT_SETUP.md

@@ -0,0 +1,420 @@
+# TensorTrade Environment Setup Guide
+
+This guide provides step-by-step instructions for setting up a working TensorTrade environment.
+
+## Prerequisites
+
+- **Python 3.12+** (required - Python 3.11 and below are NOT supported)
+- **pip** (latest version recommended)
+- **Virtual environment tool** (venv, conda, or virtualenv)
+
+## Quick Start (Recommended)
+
+```bash
+# Requires Python 3.12+
+python3.12 -m venv tensortrade-env
+source tensortrade-env/bin/activate  # Windows: tensortrade-env\Scripts\activate
+
+# Install core library
+pip install --upgrade pip
+pip install -e .
+
+# Verify (232 unit tests should pass, 2 skipped)
+pytest tests/tensortrade/unit -v
+```
+
+## Training with Ray/RLlib
+
+For reinforcement learning training, install additional dependencies:
+
+```bash
+# Install Ray with RLlib and other training dependencies
+pip install -r examples/requirements.txt
+
+# Verify full test suite including RLlib integration (251 passed, 2 skipped)
+pytest tests/ -v
+```
+
+## Alternative Installation Methods
+
+### Option 1: Using venv
+
+```bash
+# Create virtual environment
+python3.12 -m venv tensortrade-env
+
+# Activate virtual environment
+# On Windows:
+tensortrade-env\Scripts\activate
+# On Linux/macOS:
+source tensortrade-env/bin/activate
+
+# Upgrade pip
+python -m pip install --upgrade pip
+
+# Install TensorTrade
+pip install -r requirements.txt
+pip install -e .
+
+# Install example dependencies (optional)
+pip install -r examples/requirements.txt
+```
+
+### Option 2: Using Conda
+
+```bash
+# Create conda environment (use 3.11 or 3.12)
+conda create -n tensortrade python=3.12
+
+# Activate environment
+conda activate tensortrade
+
+# Install TensorTrade
+pip install -r requirements.txt
+pip install -e .
+
+# Install example dependencies (optional)
+pip install -r examples/requirements.txt
+```
+
+### Option 3: Google Colab
+
+```python
+# Run in Colab cell
+!pip install --upgrade pip
+!git clone https://github.com/tensortrade-org/tensortrade.git
+%cd tensortrade
+!pip install -r requirements.txt
+!pip install -r examples/requirements.txt
+!pip install -e .
+```
+
+## Detailed Installation Steps
+
+### Step 1: Verify Python Version
+
+```bash
+python --version
+# Should output: Python 3.11.x or 3.12.x
+# Note: Python 3.14 is NOT supported (TensorFlow incompatibility)
+```
+
+If you have an older version, download Python 3.11 or 3.12 from [python.org](https://www.python.org/downloads/).
+
+### Step 2: Create Virtual Environment
+
+**Why use a virtual environment?**
+- Isolates dependencies
+- Prevents version conflicts
+- Makes it easy to reproduce the environment
+
+```bash
+# Using venv (use python3.11 or python3.12)
+python3.12 -m venv tensortrade-env
+
+# Using conda
+conda create -n tensortrade python=3.12
+```
+
+### Step 3: Activate Virtual Environment
+
+```bash
+# Windows (venv)
+tensortrade-env\Scripts\activate
+
+# Linux/macOS (venv)
+source tensortrade-env/bin/activate
+
+# Conda (all platforms)
+conda activate tensortrade
+```
+
+### Step 4: Install Core Dependencies
+
+```bash
+# Upgrade pip first
+python -m pip install --upgrade pip
+
+# Install TensorTrade core dependencies
+pip install -r requirements.txt
+```
+
+**Core dependencies installed:**
+- numpy>=1.26.4,<2.0
+- pandas>=2.2.3,<3.0
+- gymnasium>=0.28.1,<1.0
+- tensorflow>=2.15.1
+- ta>=0.4.7
+- And more...
+
+### Step 5: Install TensorTrade
+
+```bash
+# Install in editable mode (for development)
+pip install -e .
+
+# Or install normally
+pip install .
+```
+
+### Step 6: Install Example Dependencies (Optional)
+
+```bash
+pip install -r examples/requirements.txt
+```
+
+**Example dependencies include:**
+- ray[default,tune,rllib,serve]==2.37.0
+- ccxt>=1.72.37
+- jupyterlab>=1.1.4
+- scikit-learn
+- optuna
+- feature_engine
+
+### Step 7: Verify Installation
+
+```python
+# Test import
+python -c "import tensortrade; print(tensortrade.__version__)"
+
+# Should output: 1.0.4.dev1
+```
+
+## Platform-Specific Instructions
+
+### Windows 10/11
+
+**Additional Requirements:**
+- Visual Studio Build Tools (for some packages)
+- Download from: https://visualstudio.microsoft.com/downloads/
+
+**Common Issues:**
+1. **Long path names**: Enable long path support in Windows
+   ```
+   Registry: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
+   Set LongPathsEnabled to 1
+   ```
+
+2. **Permission errors**: Run terminal as Administrator
+
+### Linux (Ubuntu 20.04+)
+
+**Additional Requirements:**
+```bash
+# Install system dependencies
+sudo apt-get update
+sudo apt-get install python3-dev python3-pip build-essential
+```
+
+**For CUDA support:**
+```bash
+# Install CUDA toolkit (for GPU support)
+# Follow: https://developer.nvidia.com/cuda-downloads
+
+# Install TensorFlow with CUDA
+pip install tensorflow[and-cuda]>=2.15.1
+```
+
+### macOS (12.0+)
+
+**Additional Requirements:**
+```bash
+# Install Xcode Command Line Tools
+xcode-select --install
+
+# Install Homebrew (if not installed)
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+## Troubleshooting
+
+### Issue: TensorFlow Not Found (Python 3.14)
+
+**Problem:** `No matching distribution found for tensorflow>=2.15.1`
+
+**Solution:** TensorFlow does not yet support Python 3.14. Use Python 3.11 or 3.12 instead:
+```bash
+# Check your Python version
+python --version
+
+# If using 3.14, switch to 3.12
+python3.12 -m venv tensortrade-env
+source tensortrade-env/bin/activate
+```
+
+### Issue: Ray Installation Fails
+
+**Solution:**
+```bash
+# Upgrade pip first
+pip install --upgrade pip
+
+# Install Ray separately
+pip install ray[default,tune,rllib,serve]==2.37.0
+
+# If still fails, try without extras
+pip install ray==2.37.0
+pip install ray[tune]
+pip install ray[rllib]
+```
+
+### Issue: TensorFlow CUDA Not Working
+
+**Solution:**
+```bash
+# Uninstall existing TensorFlow
+pip uninstall tensorflow
+
+# Install TensorFlow with CUDA support
+pip install tensorflow[and-cuda]>=2.15.1
+
+# Verify CUDA is available
+python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"
+```
+
+### Issue: NumPy Version Conflict
+
+**Solution:**
+```bash
+# Ensure NumPy < 2.0 for TensorFlow compatibility
+pip install "numpy>=1.26.4,<2.0" --force-reinstall
+```
+
+### Issue: Pandas API Errors (pct_change, ewm)
+
+**Problem:** Tests fail with pandas deprecation warnings or API errors.
+
+**Solution:** TensorTrade requires pandas < 3.0:
+```bash
+pip install "pandas>=2.2.3,<3.0" --force-reinstall
+```
+
+### Issue: importlib-metadata Error
+
+**Solution:**
+```bash
+# Install compatible version
+pip install "importlib-metadata>=4.13.0,<6.0"
+```
+
+### Issue: "No stream satisfies selector condition"
+
+**Solution:**
+This has been fixed in the latest version. Make sure you're using the updated code with the stream selector fix in `tensortrade/env/default/observers.py`.
+
+### Issue: Examples Don't Run
+
+**Solution:**
+```bash
+# Make sure example dependencies are installed
+pip install -r examples/requirements.txt
+
+# Verify Ray version
+python -c "import ray; print(ray.__version__)"
+# Should output: 2.37.0
+```
+
+## Testing Your Installation
+
+### Basic Test
+
+```python
+from tensortrade.feed.core import Stream, DataFeed
+from tensortrade.oms.instruments import USD, BTC
+from tensortrade.oms.wallets import Wallet, Portfolio
+from tensortrade.oms.exchanges import Exchange
+from tensortrade.oms.services.execution.simulated import execute_order
+import tensortrade.env.default as default
+
+# Create simple environment
+exchange = Exchange("simulated", service=execute_order)(
+    Stream.source([100, 101, 102], dtype="float").rename("USD-BTC")
+)
+
+portfolio = Portfolio(USD, [
+    Wallet(exchange, 10000 * USD),
+    Wallet(exchange, 0 * BTC)
+])
+
+feed = DataFeed([
+    Stream.source([100, 101, 102], dtype="float").rename("price")
+])
+
+env = default.create(
+    portfolio=portfolio,
+    action_scheme="simple",
+    reward_scheme="simple",
+    feed=feed,
+    window_size=1
+)
+
+# Test environment
+obs, info = env.reset()
+print(f"Environment created successfully! Observation shape: {obs.shape}")
+```
+
+### Run Tests
+
+```bash
+# Run unit tests
+pytest tests/tensortrade/unit -v
+
+# Run integration tests
+pytest tests/tensortrade/integration -v
+
+# Run all tests
+pytest tests/ -v
+```
+
+## Getting Help
+
+If you encounter issues not covered in this guide:
+
+1. Search [GitHub Issues](https://github.com/tensortrade-org/tensortrade/issues)
+3. Ask on [Discord](https://discord.gg/ZZ7BGWh)
+4. Open a new issue with:
+   - Your Python version
+   - Your OS
+   - Complete error message
+   - Steps to reproduce
+
+## Next Steps
+
+- Read the [Quick Start Guide](../README.md#quick-start)
+- Try the [Setup Environment Tutorial](../examples/setup_environment_tutorial.ipynb)
+- Explore [Example Notebooks](../examples/)
+- Read the [API Documentation](https://www.tensortrade.org/)
+
+## Maintenance
+
+### Updating TensorTrade
+
+```bash
+# Pull latest changes
+git pull origin master
+
+# Reinstall
+pip install -e . --upgrade
+
+# Update dependencies
+pip install -r requirements.txt --upgrade
+```
+
+### Cleaning Up
+
+```bash
+# Deactivate virtual environment
+deactivate  # or: conda deactivate
+
+# Remove virtual environment
+rm -rf tensortrade-env  # or: conda env remove -n tensortrade
+```
+
+## Best Practices
+
+1. **Always use a virtual environment**
+2. **Keep dependencies up to date**
+3. **Test after updates**
+4. **Document your environment** (use `pip freeze > my-requirements.txt`)
+5. **Use version control** for your code
+