QUICKSTART.md

# Quickstart Guide - Prompt A/B Tester

## Local Development

### 1. Install Dependencies

```bash
pip install -r requirements.txt
```

### 2. Configure API Key (Option A: Secrets)

Create `.streamlit/secrets.toml`:

```toml
OPENAI_API_KEY = "sk-your-actual-api-key"
```

**⚠️ Important:** Never commit `secrets.toml` to Git!

### 3. Configure API Key (Option B: In-App)

Skip step 2 and enter API key directly in the sidebar when the app starts.

### 4. Run Application

```bash
streamlit run app.py
```

The app will open automatically in your browser at `http://localhost:8501`

## Deployment on Hugging Face Spaces

### 1. Create New Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Choose:
   - **Space name**: your-space-name
   - **SDK**: Streamlit
   - **Visibility**: Public or Private

### 2. Upload Files

Upload all files from `HuggingFace_App/` directory:

```
app.py
config.py
api_handler.py
test_runner.py
requirements.txt
README.md
.gitignore
```

**Do NOT upload:**
- `.streamlit/secrets.toml` (use Repository secrets instead)
- `__pycache__/` directories

### 3. Configure Secret

1. Go to your Space → Settings → Repository secrets
2. Click "Add a secret"
3. Enter:
   - **Name**: `OPENAI_API_KEY`
   - **Value**: Your OpenAI API key (e.g., `sk-...`)
4. Save

### 4. Wait for Build

Your Space will automatically build and deploy. Check the build logs for any errors.

### 5. Access Your App

Your app will be available at: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`

## Usage Flow

### Step 1: Configure (Sidebar)

- **API Key**: Auto-loaded from secrets or enter manually
- **Model**: Select GPT model (gpt-4o recommended)
- **Temperature**: 0.1 for deterministic, 0.7 for creative
- **Max Tokens**: 2000 (typical for medical/technical prompts)
- **Num Responses**: 5 for quick test, 10-20 for reliable statistics

### Step 2: Run Test

1. Choose input method:
   - **Upload files**: Two `.md` or `.txt` files
   - **Paste text**: Directly in text areas
2. Click "🚀 Uruchom Test"
3. Wait for generation (progress bar shows status)

### Step 3: Rate Responses

1. Review each generated response
2. Rate 1-5:
   - 1 = Very poor
   - 2 = Poor
   - 3 = Average
   - 4 = Good
   - 5 = Excellent
3. Click "📊 Oblicz Wyniki"

### Step 4: View Results

- See statistics table (count, score, min, max)
- Identify winner (higher average score)
- Download CSV with full results and metadata

## Troubleshooting

### Error: "Invalid API key"

**Solution**: Check your API key in Hugging Face Spaces secrets or re-enter in sidebar.

### Error: "Rate limit exceeded"

**Solution**: Wait 1-2 minutes before retrying. Reduce number of responses if problem persists.

### Error: "Insufficient quota"

**Solution**: Add funds to your OpenAI account at https://platform.openai.com/account/billing

### App is slow

**Expected behavior**: Each response takes 3-10 seconds to generate. Total time for 10 responses (5A + 5B) ≈ 1-2 minutes.

## Cost Optimization Tips

1. **Start small**: Use 3-5 responses for initial tests
2. **Use gpt-4o**: Best quality/cost ratio ($0.05 per 10 responses)
3. **Check cost**: Use "💰 Szacuj koszt" before running large tests
4. **Reduce max_tokens**: If responses don't need to be long

## Local vs Cloud Differences

| Feature | Local (Streamlit) | Hugging Face Spaces |
|---------|-------------------|---------------------|
| API Key Storage | `.streamlit/secrets.toml` | Repository secrets |
| Performance | Depends on your machine | Hugging Face servers |
| Cost | Free (only OpenAI API) | Free (only OpenAI API) |
| Accessibility | localhost:8501 | Public URL |
| SSL/HTTPS | No | Yes |

## Support

For issues or questions:
- Check logs in "📋 Logi" tab
- Review Hugging Face Spaces build logs
- Verify OpenAI API key is valid and has funds

---

**Version**: 2.0 (Streamlit)
**Date**: 2025-10-14