CP_Assessment_engine/docs/DEPLOYMENT_GUIDE.md

# Deployment Guide - Standalone Production

## ✅ Project Status: 100% Standalone

This project is **completely self-contained** - all files and dependencies are within the `Simulated_Assessment_Engine` directory. No external file dependencies.

---

## Quick Deployment

### Step 1: Copy Project

Copy the entire `Simulated_Assessment_Engine` folder to your target location:

```bash
# Example: Copy to production server
cp -r Simulated_Assessment_Engine /path/to/production/
# Or on Windows:
xcopy Simulated_Assessment_Engine C:\production\Simulated_Assessment_Engine /E /I
```

### Step 2: Set Up Python Environment

**Using Virtual Environment (Recommended)**:

```bash
cd Simulated_Assessment_Engine

# Create virtual environment
python -m venv venv

# Activate
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install pandas anthropic openpyxl python-dotenv
```

### Step 3: Configure API Key

Create `.env` file in project root:

```bash
# Windows (PowerShell)
echo "ANTHROPIC_API_KEY=sk-ant-api03-..." > .env

# macOS/Linux
echo "ANTHROPIC_API_KEY=sk-ant-api03-..." > .env
```

Or manually create `.env` file with:
```
ANTHROPIC_API_KEY=sk-ant-api03-...
```

### Step 4: Verify Standalone Status

Run production verification:

```bash
python scripts/final_production_verification.py
```

**Expected Output**: `✅ PRODUCTION READY - ALL CHECKS PASSED`

### Step 5: Prepare Data (First Time Only)

Ensure support files are in `support/` folder:
- `support/3000-students.xlsx`
- `support/3000_students_output.xlsx`
- `support/fixed_3k_personas.xlsx`

Then run:
```bash
python scripts/prepare_data.py
```

This creates `data/merged_personas.xlsx` (79 columns, 3000 rows).

### Step 6: Run Pipeline

**Option A: Complete Pipeline (All 3 Steps)**:
```bash
python run_complete_pipeline.py --all
```

**Option B: Individual Steps**:
```bash
# Step 1: Prepare personas (if needed)
python scripts/prepare_data.py

# Step 2: Run simulation
python main.py --full

# Step 3: Post-process
python scripts/comprehensive_post_processor.py
```

---

## File Structure Verification

After deployment, verify this structure exists:

```
Simulated_Assessment_Engine/
├── .env                          # API key (create this)
├── data/
│   ├── AllQuestions.xlsx         # ✅ Required
│   └── merged_personas.xlsx     # ✅ Generated by Step 1
├── support/
│   ├── 3000-students.xlsx       # ✅ Required for Step 1
│   ├── 3000_students_output.xlsx # ✅ Required for Step 1
│   └── fixed_3k_personas.xlsx   # ✅ Required for Step 1
├── scripts/
│   ├── prepare_data.py          # ✅ Step 1
│   ├── comprehensive_post_processor.py  # ✅ Step 3
│   └── final_production_verification.py # ✅ Verification
├── services/
│   ├── data_loader.py           # ✅ Core service
│   ├── simulator.py             # ✅ Core service
│   └── cognition_simulator.py   # ✅ Core service
├── main.py                       # ✅ Step 2
├── config.py                     # ✅ Configuration
└── run_complete_pipeline.py      # ✅ Orchestrator
```

---

## Verification Checklist

Before running production:

- [ ] Project folder copied to target location
- [ ] Python 3.8+ installed
- [ ] Virtual environment created and activated (recommended)
- [ ] Dependencies installed (`pip install pandas anthropic openpyxl python-dotenv`)
- [ ] `.env` file created with `ANTHROPIC_API_KEY`
- [ ] Support files present in `support/` folder
- [ ] Verification script passes: `python scripts/final_production_verification.py`
- [ ] `data/merged_personas.xlsx` generated (79 columns, 3000 rows)
- [ ] API connection verified: `python check_api.py`

---

## Troubleshooting

### Issue: "ModuleNotFoundError: No module named 'pandas'"

**Solution**: Activate virtual environment or install dependencies:
```bash
# Activate venv first
venv\Scripts\activate  # Windows
source venv/bin/activate  # macOS/Linux

# Then install
pip install pandas anthropic openpyxl python-dotenv
```

### Issue: "FileNotFoundError: 3000-students.xlsx not found"

**Solution**: Ensure files are in `support/` folder:
- `support/3000-students.xlsx`
- `support/3000_students_output.xlsx`
- `support/fixed_3k_personas.xlsx`

### Issue: "ANTHROPIC_API_KEY not found"

**Solution**: Create `.env` file in project root with:
```
ANTHROPIC_API_KEY=sk-ant-api03-...
```

### Issue: Verification fails

**Solution**: Run verification script to see specific issues:
```bash
python scripts/final_production_verification.py
```

Check the output for specific file path or dependency issues.

---

## Cross-Platform Compatibility

### Windows
- ✅ Tested on Windows 10/11
- ✅ Path handling: Uses `pathlib.Path` (cross-platform)
- ✅ Encoding: UTF-8 with Windows console fix

### macOS/Linux
- ✅ Compatible (uses relative paths)
- ✅ Virtual environment: `source venv/bin/activate`
- ✅ Path separators: Handled by `pathlib`

---

## Production Deployment Checklist

- [x] All file paths use relative resolution
- [x] No hardcoded external paths
- [x] All dependencies are Python packages (no external files)
- [x] Virtual environment instructions included
- [x] Verification script available
- [x] Documentation complete
- [x] Code evidence verified

---

## Support

For deployment issues:
1. Run `python scripts/final_production_verification.py` to identify issues
2. Check `production_verification_report.json` for detailed report
3. Verify all files in `support/` folder exist
4. Ensure `.env` file is in project root

---

**Status**: ✅ **100% Standalone - Ready for Production Deployment**