PUBMED_SETUP.md

🔬 PubMed Tool Configuration Guide

Environment Variable Required

To enable the PubMed search tool in your ID Agents app, you need to set the following environment variable:

NCBI_EMAIL

This is your email address that will be sent to NCBI (National Center for Biotechnology Information) with each API request.

---

Why is Email Required?

NCBI requires an email address for E-utilities API access for the following reasons:

1. API Usage Monitoring: NCBI uses email to track API usage patterns
2. Contact for Issues: If there are problems with your requests, NCBI can contact you
3. Terms of Service: It's part of NCBI's E-utilities usage guidelines
4. Rate Limiting: Helps NCBI manage and enforce rate limits appropriately

---

How to Set It Up

Option 1: HuggingFace Space (Recommended)

1. Go to your HuggingFace Space: https://huggingface.co/spaces/John-jero/IDWeekAgents
2. Click on "Settings" (gear icon)
3. Navigate to "Repository secrets"
4. Click "Add a secret"
5. Enter:
   • Name: NCBI_EMAIL
   • Value: Your email address (e.g., [email protected])
6. Click "Save"
7. Restart your space for changes to take effect

Option 2: Local Development (.env file)

If running locally, create/edit your .env file:

# .env file
OPENAI_API_KEY=your-openai-api-key-here
[email protected]

---

What Email Should I Use?

✅ Recommended:

• Institutional email: [email protected]
• Work email: [email protected]
• Academic email: [email protected]

⚠️ Acceptable:

• Personal email (Gmail, Yahoo, etc.)
• Any valid email address

❌ Not Recommended:

• Fake or invalid emails
• Generic emails like [email protected]
• Temporary/disposable emails

Best Practice: Use a real, professional email address associated with your institution or work.

---

Optional: NCBI API Key

For higher rate limits, you can also register for a free NCBI API key:

How to Get an NCBI API Key:

1. Go to: https://www.ncbi.nlm.nih.gov/account/
2. Sign in or Register for an NCBI account
3. Go to Settings → API Key Management
4. Click "Create an API Key"
5. Copy your API key

Add to HuggingFace Space:

• Name: NCBI_API_KEY
• Value: Your NCBI API key

Benefits:

• Without API Key: 3 requests/second
• With API Key: 10 requests/second

---

Default Behavior

If you don't set NCBI_EMAIL, the tool will use a default:

# From tools/pubmed_search.py line 67:
if not email:
    email = "[email protected]"
    logger.info("Using default email for NCBI API access")

This will work, but it's better to set your own email for:

• ✅ Proper attribution
• ✅ NCBI can contact you if needed
• ✅ Better compliance with NCBI guidelines

---

How to Verify It's Working

Test in Your Agent:

1. Create an agent with the "search_pubmed" skill
2. Chat with the agent and ask:

   "Search PubMed for recent articles on C. difficile treatment"
   

3. Check the response:
   • ✅ Should return recent articles with titles, authors, PMIDs
   • ❌ If error, check your email is set correctly

Check Logs:

In your HuggingFace Space logs, you should see:

INFO: Using email: [email protected] for NCBI API access

---

Complete Environment Variables Setup

For full functionality, set these in HuggingFace Space Settings → Repository secrets:

Required:

OPENAI_API_KEY=sk-...your-openai-key
AUTH_CREDENTIALS=username:password,user2:pass2

Optional (but recommended):

[email protected]
NCBI_API_KEY=your-ncbi-api-key
SERPER_API_KEY=your-serper-key

---

Troubleshooting

Problem: PubMed search returns no results or errors

Solution 1: Check email is set

# In Space Settings → Secrets, verify:
NCBI_EMAIL = [email protected]

Solution 2: Restart your space after adding the secret

Solution 3: Check logs for specific error messages

Problem: Rate limit errors

Solution: Add NCBI_API_KEY to increase rate limit from 3 to 10 requests/second

Problem: "Invalid email" errors

Solution: Use a properly formatted email address: [email protected]

---

Code Reference

The PubMed tool code is in: tools/pubmed_search.py

Key lines:

# Line 37: Email parameter with environment variable default
"email": {"type": "string", "description": "user email for NCBI API", 
          "default": os.getenv("NCBI_EMAIL", "")}

# Line 62-67: Email fallback logic
if not email:
    email = os.getenv("NCBI_EMAIL", "")

if not email:
    email = "[email protected]"
    logger.info("Using default email for NCBI API access")

---

Quick Setup Checklist

• Go to HuggingFace Space Settings
• Navigate to Repository secrets
• Add secret: NCBI_EMAIL = your email
• (Optional) Add secret: NCBI_API_KEY = your API key
• Restart your space
• Test PubMed search with an agent
• Verify results are returned

---

Summary

Environment Variable: NCBI_EMAIL
Value: Your email address
Location: HuggingFace Space Settings → Repository secrets
Required: Technically optional, but strongly recommended
Format: [email protected]

After setting it, restart your space and the PubMed tool will work with your email! 📧🔬