Metadata-Version: 2.4
Name: pharma-ai-agent
Version: 0.1.0
Summary: AI agent for drug information queries using RAG to minimize hallucination
Project-URL: Homepage, https://github.com/pillright/pharma-ai-agent
Project-URL: Repository, https://github.com/pillright/pharma-ai-agent
Project-URL: Issues, https://github.com/pillright/pharma-ai-agent/issues
Author-email: Pillright <dev@pillright.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,drug-interaction,pharmacology,rag,safety
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Healthcare Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.30
Requires-Dist: click>=8.0
Requires-Dist: llm-medical-guard>=0.3.0
Requires-Dist: openai>=1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Pharma AI Agent

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![CI](https://github.com/pillright/pharma-ai-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/pillright/pharma-ai-agent/actions)

**Ask about drugs. Get evidence-based answers.**

An AI agent for drug information queries that uses RAG (Retrieval Augmented Generation) to ground every response in verified pharmacological data. No hallucinated drug interactions. No fabricated dosage recommendations. Just evidence.

## Why?

LLMs hallucinate drug information. They invent interactions that don't exist, miss critical ones that do, and confidently state incorrect dosages. In healthcare, hallucination isn't just wrong -- it's dangerous.

Pharma AI Agent solves this by:

1. **Embedding verified data** -- 200+ drug interactions and 30+ supplement safety profiles sourced from FDA, NIH, and WHO
2. **Retrieving before generating** -- Every query first searches the knowledge base; the LLM only sees verified data
3. **Checking after generating** -- Safety guardrails validate every response before it reaches the user
4. **Always citing sources** -- No answer without a reference

## Demo

```python
from pharma_ai_agent import PharmaAgent

agent = PharmaAgent(provider="openai", api_key="sk-...")

response = agent.ask("Can I take ibuprofen with warfarin?")
print(response.answer)
# => [MAJOR INTERACTION] Warfarin + Ibuprofen
#    NSAIDs inhibit platelet aggregation and may cause GI bleeding;
#    combined with warfarin's anticoagulant effect, bleeding risk
#    increases significantly.
#    Management: Avoid concurrent use if possible...
#    Sources: FDA Drug Safety Communication (2015), NIH DailyMed

print(response.safety_score)  # 0.95
print(response.sources)       # ['FDA Drug Safety Communication (2015)', ...]
```

### Batch Check

```python
results = agent.check_medications(["warfarin", "ibuprofen", "vitamin D", "fish oil"])
for pair, result in results.items():
    if result["found"]:
        print(f"[{result['severity'].upper()}] {pair[0]} + {pair[1]}")
```

## Quick Start

### Install

```bash
pip install pharma-ai-agent
```

### Configure

```bash
# Set your LLM provider API key
export OPENAI_API_KEY=sk-...
# Or for Anthropic:
# export ANTHROPIC_API_KEY=sk-ant-...
# export PHARMA_PROVIDER=anthropic
```

### Use

```python
from pharma_ai_agent import PharmaAgent

agent = PharmaAgent()
response = agent.ask("Is it safe to take vitamin D with atorvastatin?")
print(response.answer)
```

### CLI

```bash
pharma-ai-agent
# Or run offline (knowledge base only, no LLM):
pharma-ai-agent --offline
```

## Architecture

```
User Query
    |
    v
[Pre-Check Safety] -- block harmful queries
    |
    v
[Knowledge Retrieval] -- BM25 text search over embedded DB
    |                     200+ drug interactions
    |                     30+ supplement profiles
    v
[Context Injection] -- verified data injected into system prompt
    |
    v
[LLM Generation] -- OpenAI or Anthropic with tool use
    |                 interaction_checker | dosage_checker
    |                 drug_lookup | source_finder
    v
[Post-Check Safety] -- validate response, check for unsafe advice
    |
    v
[Disclaimer Injection] -- auto-append medical disclaimer
    |
    v
Structured Response
  .answer           -- natural language response
  .interactions     -- structured interaction data
  .sources          -- FDA/NIH/WHO citations
  .safety_score     -- 0.0-1.0 safety rating
  .disclaimer       -- legal disclaimer
```

## Features

### Knowledge Base (Zero Infrastructure)

- **No vector database required** -- uses BM25-like text matching
- **No embedding model needed** -- pure algorithmic retrieval
- **Embedded data** -- ships with 200+ verified drug interactions
- **Extensible** -- add custom interactions programmatically

### Safety First

- **Pre-check**: Blocks queries about self-harm, drug abuse, synthesis
- **Post-check**: Flags responses with false assurances or missing citations
- **Auto-disclaimer**: Every response includes a medical disclaimer
- **Source requirement**: Refuses to answer without verified data
- **llm-medical-guard integration**: Optional enhanced safety checks

### Provider Agnostic

- **OpenAI**: GPT-4o, GPT-4-turbo, GPT-3.5-turbo
- **Anthropic**: Claude Sonnet, Claude Haiku, Claude Opus
- Easy to add new providers

### Tools

The agent uses structured tools rather than free-form generation:

| Tool | Purpose |
|------|---------|
| `interaction_checker` | Check drug pairs against verified database |
| `dosage_checker` | Validate dosages against known safety limits |
| `drug_lookup` | Get comprehensive drug/supplement information |
| `source_finder` | Find FDA/NIH/WHO citations |

### Multilingual

- English (`en`) and Korean (`ko`) supported
- System prompts, disclaimers, and safety messages localized

## Configuration

```python
from pharma_ai_agent import PharmaAgent, AgentConfig

config = AgentConfig(
    provider="openai",           # "openai" or "anthropic"
    api_key="sk-...",            # or set via env var
    model="gpt-4o",             # model override
    locale="en",                 # "en" or "ko"
    strict_mode=True,            # enforce all safety checks
    temperature=0.1,             # low temp for factual responses
    max_tokens=2048,             # response length limit
    require_sources=True,        # refuse to answer without sources
)

agent = PharmaAgent(config=config)
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENAI_API_KEY` | -- | OpenAI API key |
| `ANTHROPIC_API_KEY` | -- | Anthropic API key |
| `PHARMA_PROVIDER` | `openai` | LLM provider |
| `PHARMA_MODEL` | (auto) | Model name override |
| `PHARMA_LOCALE` | `en` | Response language |
| `PHARMA_STRICT_MODE` | `true` | Strict safety checks |

## Data Sources

All embedded data is sourced from public, authoritative databases:

- **FDA Drug Interaction Table** -- Substrates, Inhibitors, and Inducers
- **NIH DailyMed** -- Drug labeling and safety information
- **NIH Office of Dietary Supplements** -- Supplement fact sheets
- **NIH NCCIH** -- Herbal supplement safety data
- **WHO Essential Medicines** -- Global drug safety standards
- **Published clinical trials** -- Peer-reviewed interaction studies

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/my-feature`)
3. Add tests for new functionality
4. Ensure all tests pass (`pytest tests/ -v`)
5. Submit a pull request

### Adding Drug Interactions

When adding new interactions to `drug_db.py`:

- Include both generic and brand names
- Cite at least one authoritative source (FDA, NIH, WHO)
- Provide both clinical and patient-friendly descriptions
- Include management recommendations
- Set appropriate severity (major/moderate/minor)

## Related Projects

Part of the [Pillright](https://github.com/MOB-sys) open-source healthcare ecosystem:

- [llm-medical-guard](https://github.com/MOB-sys/llm-medical-guard) — Safety guardrails for LLM medical content
- [drug-interaction-mcp](https://github.com/MOB-sys/drug-interaction-mcp) — MCP server for drug interaction checking
- [awesome-drug-interactions](https://github.com/MOB-sys/awesome-drug-interactions) — Curated list of drug interaction resources
- [korean-pharma-data](https://github.com/MOB-sys/korean-pharma-data) — Korean pharmaceutical open data pipeline
- [fastapi-health-template](https://github.com/MOB-sys/fastapi-health-template) — Healthcare FastAPI boilerplate

## Disclaimer

This software is for **educational and informational purposes only**. It does not constitute medical advice and should not be used as a substitute for professional medical consultation, diagnosis, or treatment. Always seek the advice of a qualified healthcare provider with any questions regarding medications, supplements, or medical conditions.

The drug interaction data embedded in this software is sourced from publicly available databases and may not be complete or up-to-date. Do not make medication decisions based solely on this software.

## License

MIT License. See [LICENSE](LICENSE) for details.
