Metadata-Version: 2.4
Name: hyean
Version: 0.4.0
Summary: Korean financial data SDK — DART 5소스 교차검증, LLM-ready
Author-email: Hyean <support@hyean.io>
License: MIT
Project-URL: Homepage, https://hyean.io
Project-URL: Documentation, https://hyean.io/docs
Project-URL: Repository, https://github.com/twiw49/hyean
Keywords: korea,finance,dart,financial-data,xbrl,valuation,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pandas>=2.0
Requires-Dist: requests>=2.28
Provides-Extra: parquet
Requires-Dist: pyarrow>=12.0; extra == "parquet"
Provides-Extra: server
Requires-Dist: fastapi>=0.115.0; extra == "server"
Requires-Dist: uvicorn[standard]>=0.30.0; extra == "server"
Requires-Dist: pydantic>=2.7.0; extra == "server"
Requires-Dist: pydantic-settings>=2.3.0; extra == "server"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: httpx; extra == "dev"

# hyean — Korean financial data SDK

DART 원문 기반 **5소스 교차검증** 한국 상장기업 재무 데이터. 모든 수치에 confidence 등급과 원문 출처(report_url + anchor)가 따라옵니다.

```bash
pip install git+https://github.com/twiw49/hyean-sdk.git   # 또는: pip install hyean
```

```python
import hyean as hy

hy.set_api_key("hyn_live_xxxx")        # 또는 export HYEAN_API_KEY=...
# base_url 기본값 = https://api.hyean.io (생략 가능)

# 재무제표 → pandas DataFrame (식별자: 종목코드 / corp_code / 기업명)
bs = hy.load_balance("삼성전자")
is_ = hy.load_income("005930", min_confidence="high")   # 품질 필터
cf  = hy.load_cashflow("00126380")
```

### dart-fss와 다른 점 — point-in-time(정정 소급반영)

```python
# 특정 시점 기준으로 본 재무 — 이후 정정공시를 반영/미반영해 백테스트 무결성 확보
bs_then = hy.load_balance("005930", as_of="2023-03-31")
```

`as_of`는 survivorship bias와 미반영 정정으로 백테스트가 틀어지는 문제를 막습니다 — 무료 오픈소스가 싸게 제공하지 못하는 지점입니다.

### 원문 추적

```python
bs = hy.load_balance("005930")
url = hy.source_url(bs, "BS_AST_TOT", "2024")   # 이 숫자의 DART 원문 위치
```

### CompanyHub — 한 기업, 여러 관점

```python
hub = hy.CompanyHub("005930")
hub.balance, hub.income, hub.cashflow, hub.audit, hub.profile, hub.risk
```

---

API 키 발급: https://hyean.io · 문서: https://api.hyean.io/docs · 가격: https://hyean.io/pricing
