title	StockWise-RL
emoji	📈
colorFrom	green
colorTo	blue
sdk	docker
app_port	7860
pinned	false
license	mit

StockWise-RL

An OpenEnv environment for financial portfolio management and trading optimization using reinforcement learning.

Overview

This environment simulates a real-world portfolio management scenario where an AI agent learns to make trading decisions across multiple assets. The environment implements the OpenEnv specification with full step(), reset(), and state() API.

Features

• Real-World Financial Simulation: Market data simulation with realistic price movements
• 3 Difficulty Levels: Easy (Buy & Hold), Medium (Rebalancing), Hard (Risk-Adjusted)
• Comprehensive Metrics: Portfolio value, returns, Sharpe ratio, max drawdown
• Graded Tasks: Automated scoring system (0.0-1.0 scale)
• Baseline Agent: Reference implementation with reproducible scores

Quick Start

Installation

# Clone the repository
git clone <repository-url>
cd StockWise-RL

# Install dependencies
pip install -r requirements.txt

Run Local Server

python api/server.py

The server will start on http://localhost:7860

Run Baseline Inference

# Run all tasks
python baseline/inference.py --task all

# Run specific task
python baseline/inference.py --task buy_hold
python baseline/inference.py --task rebalancing
python baseline/inference.py --task risk_adjusted

# Save results to file
python baseline/inference.py --task all --output results.json

API Endpoints

1. Reset Environment

POST /reset
{
    "task_id": "buy_hold",  // or "rebalancing", "risk_adjusted"
    "seed": 42              // optional
}

2. Execute Action

POST /step
{
    "env_id": "default",
    "action": {
        "action_type": "buy",   // buy, sell, hold
        "asset": "AAPL",        // asset symbol
        "quantity": 10          // quantity to trade
    }
}

3. Get Current State

GET /state?env_id=default

4. Run Baseline

POST /baseline

5. Grade Episode

POST /grader
{
    "task_id": "buy_hold",
    "env_id": "default"
}

6. List Tasks

GET /tasks

Task Descriptions

1. Buy & Hold (Easy)

• Duration: 30 days
• Goal: Buy stocks on day 1, hold until final day
• Initial Cash: $100,000
• Grading: Final portfolio value, Sharpe ratio, consistency

2. Portfolio Rebalancing (Medium)

• Duration: 60 days
• Goal: Maintain target allocation (30% AAPL, 30% GOOGL, 20% MSFT, 20% TSLA)
• Initial Cash: $100,000
• Grading: Allocation accuracy, returns, trading efficiency

3. Risk-Adjusted Optimization (Hard)

• Duration: 90 days
• Goal: Maximize Sharpe ratio while minimizing drawdown
• Initial Cash: $100,000
• Grading: Sharpe ratio, max drawdown, absolute return

State Space

{
    "portfolio_value": 105000.00,
    "cash": 50000.00,
    "holdings": {
        "AAPL": 100.5,
        "GOOGL": 50.0
    },
    "prices": {
        "AAPL": 180.50,
        "GOOGL": 140.20
    },
    "day": 15,
    "total_return": 0.05,
    "sharpe_ratio": 1.2,
    "max_drawdown": 0.03
}

Action Space

{
    "action_type": "buy",  // buy, sell, hold
    "asset": "AAPL",       // asset symbol
    "quantity": 10         // positive number
}

Reward Function

The reward function provides:

• Daily P&L: Portfolio value change
• Task-specific bonuses: Allocation accuracy (rebalancing), Sharpe ratio (risk-adjusted)
• Penalties: Transaction costs, excessive trading

Grading System

All tasks are graded on a 0.0-1.0 scale:

Task	Score Components
Buy & Hold	50% Return, 30% Sharpe, 20% Consistency
Rebalancing	40% Allocation, 40% Return, 20% Efficiency
Risk-Adjusted	50% Sharpe, 30% Drawdown, 20% Return

Available Assets

• AAPL (Apple)
• GOOGL (Alphabet)
• MSFT (Microsoft)
• TSLA (Tesla)
• AMZN (Amazon)
• META (Meta)
• NVDA (NVIDIA)
• JPM (JPMorgan)

Docker Deployment

# Build image
docker build -t portfolio-trading-env .

# Run container
docker run -p 7860:7860 portfolio-trading-env

Hugging Face Spaces Deployment

1. Create a new Space on Hugging Face
2. Choose Docker as the SDK
3. Upload all project files
4. The Space will automatically build and deploy

Project Structure

portfolio-trading-env/
├── openenv.yaml              # OpenEnv specification
├── requirements.txt          # Python dependencies
├── Dockerfile              # Container configuration
├── README.md              # This file
├── environment/
│   └── portfolio_env.py   # Core environment implementation
├── graders/
│   └── portfolio_grader.py # Scoring system
├── api/
│   └── server.py          # FastAPI server
└── baseline/
    └── inference.py       # Baseline agent

Environment Configuration

The openenv.yaml file specifies:

• API version and endpoints
• State and action schemas
• Task definitions
• Grading criteria

Development

Running Tests

# Test environment
python -c "
from environment.portfolio_env import PortfolioTradingEnv
env = PortfolioTradingEnv('buy_hold')
state = env.reset()
print('Reset successful:', state)
action = {'action_type': 'buy', 'asset': 'AAPL', 'quantity': 10}
state, reward, done, info = env.step(action)
print('Step successful:', state)
"

# Test baseline
python baseline/inference.py --task all

Submission Checklist

Before submitting, verify:

• HF Space deploys successfully
• /reset endpoint returns 200
• /step endpoint accepts actions and returns state
• /state endpoint returns current state
• /baseline runs baseline script
• /grader returns score in 0.0-1.0 range
• /tasks lists all 3 tasks
• openenv.yaml is valid
• Dockerfile builds successfully
• README includes setup instructions

License

This project was created for the Meta AI Hackathon - The Llama Impact Series.

Contact

For questions or issues, please refer to the hackathon guidelines.