# 🚀 Deployment Guide — Medicine Safety Agent on Hugging Face Spaces

---

## 1. Prerequisites

| Tool | Install |
|------|---------|
| Python 3.10+ | https://python.org |
| Git | https://git-scm.com |
| Git-LFS | `git lfs install` |
| Hugging Face account | https://huggingface.co/join |
| `huggingface_hub` CLI | `pip install huggingface_hub` |

---

## 2. Run Locally First

```bash
# 1 — Clone / enter your project folder
cd med-agent

# 2 — Create a virtual environment
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

# 3 — Install dependencies
pip install -r requirements.txt

# 4 — Set up your API key
cp .env .env
#   Edit .env → set LLM_PROVIDER and the matching API key

# 5 — Launch
python app.py
# Open http://localhost:7860
```

---

## 3. Create a Hugging Face Space

### Option A — via the Web UI (easiest)

1. Go to https://huggingface.co/new-space
2. Fill in:
   - **Owner**: your HF username / org
   - **Space name**: `medicine-safety-agent` (or any name)
   - **License**: MIT
   - **SDK**: **Gradio**
   - **SDK version**: 4.27.0
3. Click **Create Space**.

### Option B — via CLI

```bash
huggingface-cli login          # paste your HF token

python - <<'EOF'
from huggingface_hub import HfApi
api = HfApi()
api.create_repo(
    repo_id="YOUR_USERNAME/medicine-safety-agent",
    repo_type="space",
    space_sdk="gradio",
    private=False,           # set True for a private Space
)
EOF
```

---

## 4. Push Code to the Space

```bash
# Inside your project folder

# 4-a  Initialise git (skip if already a git repo)
git init
git add .
git commit -m "initial commit: Medicine Safety Agent"

# 4-b  Add the HF Space as a remote
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/medicine-safety-agent

# 4-c  Push
git push space main
```

> 💡 Replace `YOUR_USERNAME` with your actual Hugging Face username.

---

## 5. Set Secret API Keys in the Space

**Never commit your `.env` file.**  
Add secrets via the Space Settings UI:

1. Open your Space → **Settings** tab → **Repository secrets**.
2. Add each secret:

| Name | Value |
|------|-------|
| `LLM_PROVIDER` | `openai` (or `gemini` / `claude`) |
| `LLM_MODEL` | *(optional)* e.g. `gpt-4o` |
| `OPENAI_API_KEY` | `sk-...` |
| `GEMINI_API_KEY` | `AIza...` |
| `ANTHROPIC_API_KEY` | `sk-ant-...` |

Hugging Face injects these as environment variables at runtime — exactly what `python-dotenv` / `os.getenv` reads.

---

## 6. Verify the Deployment

1. Visit `https://huggingface.co/spaces/YOUR_USERNAME/medicine-safety-agent`
2. Wait for the **Building** badge to turn **Running** (≈ 2–3 minutes on first build).
3. Enter a medicine name and click **Analyse Medicine**.

---

## 7. Switching LLM Providers

Update the `LLM_PROVIDER` secret in Space Settings (and the matching key) — no code change needed.

| Provider | `LLM_PROVIDER` | Key secret |
|----------|---------------|------------|
| OpenAI   | `openai`      | `OPENAI_API_KEY` |
| Google   | `gemini`      | `GEMINI_API_KEY` |
| Anthropic| `claude`      | `ANTHROPIC_API_KEY` |

---

## 8. Updating the App

```bash
# Make your code changes, then:
git add .
git commit -m "feat: your change description"
git push space main
```

The Space auto-rebuilds on every push.

---

## 9. Project Structure Reference

```
med-agent/
├── app.py                  ← Gradio UI entry point
├── requirements.txt        ← Python dependencies
├── README.md               ← HF Space card metadata + docs
├── .env.example            ← API key template (never commit .env)
│
├── agents/
│   ├── __init__.py
│   └── medicine_agent.py   ← Orchestrates the 3 AI tasks
│
├── llm/
│   ├── __init__.py
│   └── connector.py        ← Generic multi-provider LLM interface
│
└── utils/
    ├── __init__.py
    └── search.py           ← DuckDuckGo web search utility
```

---

## 10. Troubleshooting

| Symptom | Fix |
|---------|-----|
| `ModuleNotFoundError` | Ensure all packages are in `requirements.txt` |
| `AuthenticationError` | Check your API key secret in Space Settings |
| Space stuck at "Building" | Check the **Logs** tab for the error |
| Empty search results | DuckDuckGo may rate-limit; add a short `time.sleep(1)` in `search.py` |
| JSON parse error from LLM | The model returned markdown fences — the strip logic in `medicine_agent.py` handles this, but try a different model if it persists |