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:

```bash
# .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:

```python
# 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)**:
```
NCBI[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
```bash
# 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:
```python
# 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!** 📧🔬