QUICKSTART.md

Quickstart Guide - Prompt A/B Tester

Local Development

1. Install Dependencies

pip install -r requirements.txt

2. Configure API Key (Option A: Secrets)

Create .streamlit/secrets.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

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