Metadata-Version: 2.4
Name: korean-pharma-data
Version: 0.1.0
Summary: Korean pharmaceutical open data collector, parser, and exporter from MFDS APIs
Project-URL: Homepage, https://github.com/pillright/korean-pharma-data
Project-URL: Repository, https://github.com/pillright/korean-pharma-data
Project-URL: Issues, https://github.com/pillright/korean-pharma-data/issues
Author-email: Pillright <dev@pillright.com>
License-Expression: MIT
License-File: LICENSE
Keywords: drug,korean,mfds,open-data,pharmaceutical,식약처,의약품
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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: click>=8.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: lxml>=4.9
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: aiosqlite>=0.19; extra == 'all'
Requires-Dist: pyarrow>=14.0; extra == 'all'
Provides-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.1.0; extra == 'dev'
Provides-Extra: parquet
Requires-Dist: pyarrow>=14.0; extra == 'parquet'
Provides-Extra: sqlite
Requires-Dist: aiosqlite>=0.19; extra == 'sqlite'
Description-Content-Type: text/markdown

# korean-pharma-data

[![CI](https://github.com/pillright/korean-pharma-data/actions/workflows/ci.yml/badge.svg)](https://github.com/pillright/korean-pharma-data/actions/workflows/ci.yml)
[![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-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/korean-pharma-data.svg)](https://pypi.org/project/korean-pharma-data/)

**한국 의약품 데이터를 쉽게 수집하고 활용하세요.**

A Python library for collecting, parsing, and cleaning Korean pharmaceutical open data from the Ministry of Food and Drug Safety (MFDS / 식약처) APIs.

---

## Features / 주요 기능

- **의약품 정보 수집** (e약은요 API) - Drug product information
- **DUR 상호작용 정보** - Drug interaction data (contraindicated combinations, age restrictions, pregnancy restrictions, dosage warnings)
- **의약품 성분 정보** - Drug ingredient data
- **건강기능식품 정보** - Health supplement data
- **다양한 내보내기 형식** - Export to JSON, CSV, SQLite (with FTS5 search), Parquet
- **비동기 수집** - Async collection with rate limiting and caching
- **CLI 도구** - Command-line interface for quick data collection

## Quick Start / 빠른 시작

### Installation / 설치

```bash
pip install korean-pharma-data

# With all optional dependencies
pip install korean-pharma-data[all]
```

### API Key / API 키 발급

1. [공공데이터포털](https://www.data.go.kr/) 회원가입
2. 다음 API 활용 신청:
   - [의약품 제품 허가정보 (e약은요)](https://www.data.go.kr/data/15075057/openapi.do)
   - [DUR 품목정보](https://www.data.go.kr/data/15075666/openapi.do)
   - [의약품 성분정보](https://www.data.go.kr/data/15075665/openapi.do)
   - [건강기능식품 정보](https://www.data.go.kr/data/15044734/openapi.do)
3. 발급받은 인증키를 환경변수로 설정:

```bash
export MFDS_API_KEY="your-api-key-here"
```

### Python API

```python
import asyncio
from korean_pharma_data.client import MFDSClient
from korean_pharma_data.collectors import DrugInfoCollector
from korean_pharma_data.exporters import export_json

async def main():
    async with MFDSClient(api_key="YOUR_KEY") as client:
        collector = DrugInfoCollector(client)

        # Search for drugs
        drugs = await collector.search("타이레놀", max_results=10)
        for drug in drugs:
            print(f"{drug.item_name} - {drug.entp_name}")

        # Export to JSON
        export_json(drugs, "results.json")

asyncio.run(main())
```

### CLI

```bash
# Collect drug data
korean-pharma-data collect drugs --api-key $MFDS_API_KEY --output drugs.json

# Collect DUR interactions
korean-pharma-data collect dur --api-key $MFDS_API_KEY --type 병용금기 --output dur.json

# Collect supplements
korean-pharma-data collect supplements --api-key $MFDS_API_KEY --output supplements.json

# Export to SQLite with full-text search
korean-pharma-data export drugs.json --format sqlite --output pharma.db

# Search in SQLite database
korean-pharma-data search "타이레놀" --db pharma.db
```

## Data Sources / 수집 가능한 데이터

| API | Description / 설명 | Endpoint |
|-----|-----------|----------|
| e약은요 | Drug product info / 의약품 제품 허가정보 | `DrbEasyDrugInfoService` |
| DUR 병용금기 | Contraindicated combinations | `DURPrdlstInfoService03` |
| DUR 연령금기 | Age restrictions | `DURPrdlstInfoService03` |
| DUR 임부금기 | Pregnancy restrictions | `DURPrdlstInfoService03` |
| DUR 용량주의 | Dosage warnings | `DURPrdlstInfoService03` |
| 성분정보 | Ingredient info | `DURIrdntInfoService03` |
| 건강기능식품 | Health supplements | `HtfsSleIrdntInfoService` |

## Data Models / 데이터 모델

### Drug (의약품)

| Field | Type | Description |
|-------|------|-------------|
| `item_seq` | `str` | 품목기준코드 |
| `item_name` | `str` | 제품명 |
| `entp_name` | `str` | 업체명 |
| `ingredients` | `list[Ingredient]` | 성분 목록 |
| `efcy_qesitm` | `str \| None` | 효능효과 |
| `use_method_qesitm` | `str \| None` | 용법용량 |
| `atpn_qesitm` | `str \| None` | 주의사항 |
| `se_qesitm` | `str \| None` | 부작용 |

### DURInteraction (DUR 상호작용)

| Field | Type | Description |
|-------|------|-------------|
| `item_seq_a` | `str` | 품목기준코드 A |
| `item_name_a` | `str` | 제품명 A |
| `item_seq_b` | `str` | 품목기준코드 B |
| `item_name_b` | `str` | 제품명 B |
| `type` | `str` | DUR 유형 |
| `prohibition_content` | `str` | 금기 내용 |

### Supplement (건강기능식품)

| Field | Type | Description |
|-------|------|-------------|
| `product_name` | `str` | 제품명 |
| `company` | `str` | 업체명 |
| `ingredients` | `list[SupplementIngredient]` | 원료 목록 |
| `functionality` | `str` | 기능성 내용 |

## Export Formats / 내보내기 형식

| Format | Features |
|--------|----------|
| **JSON** | Korean characters preserved (ensure_ascii=False) |
| **CSV** | UTF-8 with BOM, nested fields as JSON strings |
| **SQLite** | FTS5 full-text search on drug/supplement names |
| **Parquet** | Columnar format for data science workflows |

## Development / 개발

```bash
# Clone the repository
git clone https://github.com/pillright/korean-pharma-data.git
cd korean-pharma-data

# Install in development mode
pip install -e ".[dev,all]"

# Run tests
pytest -v

# Lint
ruff check src/ tests/
```

## 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
- [pharma-ai-agent](https://github.com/MOB-sys/pharma-ai-agent) — RAG-based drug information AI agent
- [awesome-drug-interactions](https://github.com/MOB-sys/awesome-drug-interactions) — Curated list of drug interaction resources
- [fastapi-health-template](https://github.com/MOB-sys/fastapi-health-template) — Healthcare FastAPI boilerplate

## Contributing / 기여

1. Fork the repository
2. Create a feature branch (`git checkout -b feat/amazing-feature`)
3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
4. Push to the branch (`git push origin feat/amazing-feature`)
5. Open a Pull Request

## License / 라이선스

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Disclaimer / 면책조항

This library provides access to publicly available pharmaceutical data from Korea's MFDS.
The data is provided as-is and should not be used as a substitute for professional medical advice.

이 라이브러리는 식약처의 공공데이터를 제공하며, 의사/약사의 전문적 판단을 대체하지 않습니다.
