README.md

---
title: TradeVerse AI Trading Experiment
emoji: 📈
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
---

# TradeVerse AI Trading Experiment

A psychology research tool for studying human-AI interaction in financial decision-making.

## Overview

This application combines:
- **Trading Game**: Scenario-based trading decisions in a fictional financial universe
- **AI Chatbot**: RAG-based advisor with tunable parameters
- **Experiment Tracking**: Comprehensive data collection for research analysis

## Features

### For Participants
- Interactive trading scenarios with fictional companies
- AI advisor that provides recommendations and answers questions
- Adjustable AI settings (explanation depth, communication style)
- Real-time portfolio tracking

### For Researchers
- Pre-defined experimental conditions for A/B testing
- Hidden parameters (accuracy rate, confidence framing, risk bias)
- Comprehensive tracking of:
  - Trading decisions and outcomes
  - AI consultation patterns
  - Trust metrics and confidence changes
  - Response timing
- Data export utilities (CSV, Excel reports)

## Experimental Conditions

| Condition | Accuracy | Confidence | Description |
|-----------|----------|------------|-------------|
| high_accuracy_high_confidence | 85% | High | Correct AI, assertive |
| high_accuracy_low_confidence | 85% | Low | Correct AI, hedging |
| low_accuracy_high_confidence | 40% | High | Often wrong, assertive |
| low_accuracy_low_confidence | 40% | Low | Often wrong, hedging |
| conservative_advisor | 70% | Medium | Risk-averse recommendations |
| aggressive_advisor | 70% | Medium | Risk-seeking recommendations |
| passive_advisor | 70% | Low proactivity | Rarely initiates |
| active_advisor | 70% | High proactivity | Frequently initiates |

## Setup

### LLM Provider Options

The chatbot supports multiple LLM providers (auto-detected based on available API keys):

| Provider | Env Variable | Cost | Notes |
|----------|--------------|------|-------|
| **HuggingFace** | `HF_TOKEN` | Free tier available | Recommended for HF Spaces |
| DeepSeek | `DEEPSEEK_API_KEY` | Pay-per-use | Higher quality |
| Fallback | None needed | Free | Rule-based, limited |

#### Recommended HuggingFace Models (free tier)

```python
# In chatbot.py, change DEFAULT_HF_MODEL to any of these:
"Qwen/Qwen2-1.5B-Instruct"             # Smallest, fastest
"microsoft/Phi-3-mini-4k-instruct"     # Small, good quality
"HuggingFaceH4/zephyr-7b-beta"         # Default, best quality
"mistralai/Mistral-7B-Instruct-v0.2"   # Popular alternative
```

### Environment Variables

**Option 1: HuggingFace (Recommended for HF Spaces)**
```bash
export HF_TOKEN="hf_your_token_here"
```
Get your token at: https://huggingface.co/settings/tokens

**Option 2: DeepSeek**
```bash
export DEEPSEEK_API_KEY="your-api-key-here"
```

### Local Development

```bash
pip install -r requirements.txt
python app.py
```

### Hugging Face Spaces

1. Create a new Space with Gradio SDK
2. Upload all files
3. Add `HF_TOKEN` as a secret in Space settings (Settings → Repository secrets)
   - Your HF token works automatically in Spaces

## Data Export

```bash
# Quick statistics
python export_data.py stats

# Export all data to CSV
python export_data.py export

# Generate full Excel report
python export_data.py report
```

## Project Structure

```
IntegratedGame/
├── app.py                 # Main Gradio application
├── trading.py             # Trading engine and portfolio management
├── chatbot.py             # RAG chatbot with parameter-aware responses
├── tracking.py            # Database and experiment tracking
├── config.py              # Scenarios, conditions, parameters
├── export_data.py         # Data analysis and export
├── requirements.txt
├── knowledge_base/
│   ├── companies.txt      # Fictional company profiles
│   ├── market_context.txt # TradeVerse economic backdrop
│   ├── trading_basics.txt # Trading fundamentals
│   └── ai_persona.txt     # AI behavior guidelines
└── db/
    └── experiment.db      # SQLite database (auto-created)
```

## Database Schema

### sessions
- Participant sessions with portfolio tracking
- AI reliance metrics

### decisions
- Individual trading decisions
- AI parameters at decision time
- Timing and confidence data

### chat_interactions
- All AI-participant conversations
- Proactive vs reactive classification
- Engagement metrics

### trust_metrics
- Pre/post advice confidence
- Advice adherence
- Outcome tracking

## Research Applications

This tool supports research into:
- Trust calibration in AI advisors
- Effect of AI confidence framing on decision-making
- Proactive vs reactive AI assistance preferences
- Risk perception under AI guidance
- Learning and adaptation to AI accuracy

## License

MIT License