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

# 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

# Test individual components
python test_components.py

Expected output:

✅ Utils         PASS
✅ Research      PASS
✅ Analysis      PASS
✅ Audio         PASS

Step 4: Launch Application

# 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:

# 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! 🚀