docs/QUICKSTART.md

# Science Storyteller - Quick Start Guide

## 🚀 Quick Setup (5 minutes)

### Step 1: Get API Keys

1. **Semantic Scholar API Key** (optional, for higher rate limits):
   - Visit https://www.semanticscholar.org/product/api
   - Sign up for API access
   - Copy your API key

2. **Anthropic API Key** (for Claude AI):
   - Visit https://console.anthropic.com/
   - Create account or sign in
   - Go to API Keys section
   - Create new key and copy it

3. **ElevenLabs API Key** (for text-to-speech):
   - Visit https://elevenlabs.io/
   - Create account or sign in
   - Go to Profile → API Keys
   - Copy your API key

### Step 2: Configure Environment

```bash
# Run setup script
./setup.sh

# Edit .env file
nano .env

# Add your keys:
SEMANTIC_SCHOLAR_API=your_key_here  # Optional but recommended
ANTHROPIC_API_KEY=sk-ant-...
ELEVENLABS_API_KEY=...
```

### Step 3: Test Components

```bash
# Test individual components
python test_components.py
```

Expected output:
```
✅ Utils         PASS
✅ Research      PASS
✅ Analysis      PASS
✅ Audio         PASS
```

### Step 4: Launch Application

```bash
# Start the Gradio app
python app.py
```

Open http://localhost:7860 in your browser!

## 🎯 First Podcast

1. Try example topic: "AlphaFold 3 protein structure prediction"
2. Click "Generate Podcast"
3. Wait ~1-2 minutes
4. Listen to your podcast in the Audio tab!

## ⚠️ Troubleshooting

### "API connection failed"
- Semantic Scholar works without API key (rate-limited)
- With API key: Verify it's correct in .env
- Check internet connection

### "LLM service not available"
- Check ANTHROPIC_API_KEY in .env
- Verify API key is valid
- Check API quota/credits

### "Audio conversion failed"
- Check ELEVENLABS_API_KEY in .env
- Verify API key is valid
- Check ElevenLabs account credits

### "No papers found"
- Semantic Scholar API works for all research fields
- Try different search terms
- Check internet connection
- Try more specific queries (e.g., "AlphaFold 2" instead of just "AlphaFold")
- Note: Without API key, you may hit rate limits faster

## 💡 Tips for Best Results

1. **Be Specific**: "CRISPR Cas9 gene editing" > "genetics"
2. **Use Keywords**: Include technical terms from the field
3. **Recent Topics**: Newer research usually has better papers
4. **Wait Patiently**: Audio generation can take 30-60 seconds

## 📊 Cost Estimates

- **Anthropic Claude API**: ~$0.02-0.05 per podcast
- **ElevenLabs TTS**: ~$0.10-0.30 per podcast (depends on length)
- **Total**: ~$0.15-0.35 per podcast

Both services offer free tiers for testing!

## 🔗 Useful Links

- **Semantic Scholar API**: https://www.semanticscholar.org/product/api
- **Anthropic Console**: https://console.anthropic.com/
- **ElevenLabs Dashboard**: https://elevenlabs.io/app/
- **Gradio Docs**: https://gradio.app/docs/

## 🎓 Example Topics to Try

**AI & Machine Learning:**
- Transformer neural network architecture
- AlphaFold 3 protein structure prediction
- GPT language models
- Diffusion models for image generation

**Biology & Medicine:**
- mRNA vaccine technology and development
- Tuberculosis vaccine BCG immunotherapy
- CRISPR Cas9 gene editing applications
- Cancer immunotherapy checkpoint inhibitors

**Astronomy & Physics:**
- Comet 3I/ATLAS interstellar trajectory
- Gravitational waves detection
- Quantum entanglement Bell inequality
- Dark matter detection experiments

**Climate & Environment:**
- Climate change ocean acidification
- Carbon capture and storage technologies
- Renewable energy grid integration
- Arctic ice sheet dynamics

## 🛠️ Development Mode

For development with auto-reload:

```bash
# Install gradio in dev mode
pip install gradio[dev]

# Run with reload
gradio app.py
```

## 📝 File Locations

- **Generated Audio**: `assets/audio/podcast_*.mp3`
- **Logs**: Console output
- **Configuration**: `.env`

## 🎯 Next Steps

After your first successful podcast:

1. Try different topics
2. Experiment with the examples
3. Share your podcasts!
4. Consider the enhancements in README.md

## 🆘 Need Help?

- Check full README.md for detailed documentation
- Review error messages carefully
- Ensure all API keys are valid
- Check that all dependencies are installed

---

**Ready to make science accessible? Let's go! 🚀**