### Install StockBench

Source: https://github.com/chenyxxxx/stockbench/blob/main/README.md

Clone the repository, create a conda environment, and install project dependencies.

```bash
git clone <repository-url>
cd stockbench

conda create -n stockbench python=3.11
conda activate stockbench

pip install -r requirements.txt
```

--------------------------------

### Run Backtest with Default Settings

Source: https://github.com/chenyxxxx/stockbench/blob/main/README.md

Execute the backtest script using default start and end dates, and the specified LLM profile.

```bash
bash scripts/run_benchmark.sh
```

--------------------------------

### Run Backtest with Custom Dates and LLM Profile

Source: https://github.com/chenyxxxx/stockbench/blob/main/README.md

Run the backtest script with custom start and end dates, and a specific LLM profile using command-line arguments.

```bash
bash scripts/run_benchmark.sh \
    --start-date 2025-04-01 \
    --end-date 2025-05-31 \
    --llm-profile deepseek-v3.1
```

--------------------------------

### Decision JSON Example

Source: https://github.com/chenyxxxx/stockbench/blob/main/stockbench/agents/prompts/decision_agent_v1.txt

This JSON structure represents the output of the Decision Agent, detailing trading actions for specific stock symbols. It includes reasons for each decision, such as market trends, technical anomalies, valuation, news, and portfolio constraints.

```json
<DECISION>
{
  "decisions": {
    "SYMBOL1": {
      "action": "increase",
      "target_cash_amount": "example_amount",
      "reasons": [
        "Strong momentum with positive 7-day trend from market_data.close_7d",
        "Filter agent identified technical anomalies requiring fundamental validation",
        "Reasonable valuation with pe_ratio below sector average (fundamental data available)",
        "Solid dividend profile providing downside protection",
        "Positive earnings catalyst from recent news events",
        "Position size within portfolio allocation limits considering {stock_count} total stocks"
      ],
      "confidence": "example_confidence"
    },
    "SYMBOL2": {
      "action": "hold",
      "reasons": [
        "Filter agent determined technical patterns sufficient - no fundamental analysis needed",
        "Stable price trend from market_data.close_7d with normal volatility",
        "No significant news catalysts requiring position adjustments",
        "Current position size from position_state appropriate for risk management",
        "Maintaining position to preserve capital for better opportunities within total_assets constraint"
      ],
      "confidence": "example_confidence"
    }
  }
}
</DECISION>
```

--------------------------------

### Configure API Keys

Source: https://github.com/chenyxxxx/stockbench/blob/main/README.md

Set environment variables for Polygon, Finnhub, and OpenAI API keys. Free tiers are available for Polygon.io and Finnhub.io.

```bash
export POLYGON_API_KEY="your_polygon_api_key"
export FINNHUB_API_KEY="your_finnhub_api_key"
export OPENAI_API_KEY="your_openai_api_key"
```

--------------------------------

### Load Backtest Results with Pandas

Source: https://github.com/chenyxxxx/stockbench/blob/main/storage/README.md

Load trade and daily Net Asset Value (NAV) data from parquet files for backtest analysis.

```python
# Load trade data
trades = pd.read_parquet('storage/reports/backtest/EXP_OPENAI_MAR_7/trades.parquet')

# Load daily NAV
nav = pd.read_parquet('storage/reports/backtest/EXP_OPENAI_MAR_7/daily_nav.parquet')
```

--------------------------------

### Load Daily Market Data with Pandas

Source: https://github.com/chenyxxxx/stockbench/blob/main/storage/README.md

Load daily market data for a specific stock symbol using pandas. Requires pandas and parquet file access.

```python
import pandas as pd

# Load daily data for AAPL
df = pd.read_parquet('storage/parquet/AAPL/day/2025-01-01.parquet')
```

--------------------------------

### Load Backtest Performance Metrics

Source: https://github.com/chenyxxxx/stockbench/blob/main/storage/README.md

Load comprehensive performance metrics for a backtest from a JSON file.

```python
import json

# Load comprehensive metrics
with open('storage/reports/backtest/EXP_OPENAI_MAR_7/metrics.json', 'r') as f:
    metrics = json.load(f)
```

--------------------------------

### Load Financial Data

Source: https://github.com/chenyxxxx/stockbench/blob/main/storage/README.md

Load complete and quarterly financial data for a stock symbol from JSON files.

```python
# Load complete financial dataset
with open('storage/cache/financials/AAPL.all.json', 'r') as f:
    all_financials = json.load(f)

# Load quarterly financials only
with open('storage/cache/financials/AAPL.quarterly.json', 'r') as f:
    quarterly_financials = json.load(f)
```

--------------------------------

### Load Daily News Data

Source: https://github.com/chenyxxxx/stockbench/blob/main/storage/README.md

Load daily news for a specific stock symbol on a given date from a JSON file.

```python
# Load daily news for AAPL
with open('storage/cache/news_by_day/AAPL/2024-12-01.json', 'r') as f:
    daily_news = json.load(f)
```

--------------------------------

### Load Corporate Actions Data

Source: https://github.com/chenyxxxx/stockbench/blob/main/storage/README.md

Load dividend and stock split data for a stock symbol from JSON files. Filters dividends by date.

```python
import json
import pandas as pd

# Load dividend data for AAPL
with open('storage/cache/corporate_actions/AAPL.dividends.json', 'r') as f:
    dividends = json.load(f)
    dividends_df = pd.DataFrame(dividends)

# Load stock split data for AAPL  
with open('storage/cache/corporate_actions/AAPL.splits.json', 'r') as f:
    splits = json.load(f)
    splits_df = pd.DataFrame(splits)

# Filter dividends for specific date range
recent_dividends = dividends_df[
    pd.to_datetime(dividends_df['ex_dividend_date']) >= '2024-01-01'
]
```

--------------------------------

### Fundamental Filter JSON Output

Source: https://github.com/chenyxxxx/stockbench/blob/main/stockbench/agents/prompts/fundamental_filter_v1.txt

This JSON output shows stocks flagged for fundamental validation and the specific reasons, such as earnings announcements, high volatility, or significant position value.

```json
<FILTER_RESULT>
{
  "stocks_need_fundamental": ["AAPL", "MSFT"],
  "reasoning": {
    "AAPL": "Earnings announcement in news_events requires fundamental validation; unusual 15% volatility in close_7d pattern exceeds technical analysis reliability",
    "MSFT": "Large position value (25% of portfolio) approaching 52-week highs requires fundamental risk assessment for continued exposure",
    "GOOGL": "Technical pattern sufficient: stable close_7d trend, no significant news events, position size within normal allocation limits",
    "TSLA": "Routine technical signals: normal volatility range, no material news catalysts, standard position management adequate"
  }
}
</FILTER_RESULT>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.