hyean 0.4.0__tar.gz

hyean-0.4.0/PKG-INFO

@@ -0,0 +1,78 @@
+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

hyean-0.4.0/README.md

@@ -0,0 +1,46 @@
+# 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

hyean-0.4.0/hyean.egg-info/PKG-INFO

@@ -0,0 +1,78 @@
+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

hyean-0.4.0/hyean.egg-info/SOURCES.txt

@@ -0,0 +1,38 @@
+README.md
+pyproject.toml
+hyean.egg-info/PKG-INFO
+hyean.egg-info/SOURCES.txt
+hyean.egg-info/dependency_links.txt
+hyean.egg-info/requires.txt
+hyean.egg-info/top_level.txt
+sdk/__init__.py
+sdk/audit.py
+sdk/benchmark.py
+sdk/cache.py
+sdk/client.py
+sdk/companies.py
+sdk/config.py
+sdk/context.py
+sdk/coverage.py
+sdk/deep.py
+sdk/discover.py
+sdk/enhanced.py
+sdk/events.py
+sdk/exceptions.py
+sdk/filings.py
+sdk/financials.py
+sdk/grades.py
+sdk/groups.py
+sdk/hub.py
+sdk/index.py
+sdk/macro.py
+sdk/meta.py
+sdk/names.py
+sdk/prices.py
+sdk/profile.py
+sdk/segments.py
+sdk/source.py
+sdk/utils.py
+sdk/valuation.py
+tests/test_reference.py
+tests/test_smoke.py

hyean-0.4.0/hyean.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hyean-0.4.0/hyean.egg-info/requires.txt

@@ -0,0 +1,15 @@
+pandas>=2.0
+requests>=2.28
+
+[dev]
+pytest
+httpx
+
+[parquet]
+pyarrow>=12.0
+
+[server]
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+pydantic>=2.7.0
+pydantic-settings>=2.3.0

hyean-0.4.0/hyean.egg-info/top_level.txt

@@ -0,0 +1 @@
+hyean

hyean-0.4.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hyean"
+version = "0.4.0"
+description = "Korean financial data SDK — DART 5소스 교차검증, LLM-ready"
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Hyean", email = "support@hyean.io" }]
+keywords = ["korea", "finance", "dart", "financial-data", "xbrl", "valuation", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = [
+    "pandas>=2.0",
+    "requests>=2.28",
+]
+
+[project.urls]
+Homepage = "https://hyean.io"
+Documentation = "https://hyean.io/docs"
+Repository = "https://github.com/twiw49/hyean"
+
+[project.optional-dependencies]
+parquet = ["pyarrow>=12.0"]
+server = [
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "pydantic>=2.7.0",
+    "pydantic-settings>=2.3.0",
+]
+dev = ["pytest", "httpx"]
+
+# pip install hyean       → sdk/ 만 설치됨
+# pip install hyean[server] → 서버 의존성 포함
+[tool.setuptools]
+packages = ["hyean"]
+
+[tool.setuptools.package-dir]
+hyean = "sdk"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# 스모크 테스트는 DB가 떠 있어야 의미 있음 (데이터 의존 테스트는 db_up fixture로 자동 skip)

hyean-0.4.0/sdk/__init__.py

@@ -0,0 +1,115 @@
+"""
+Hyean — Korean financial data SDK
+===================================
+DART 원문 기반, 5소스 교차검증 한국 상장기업 재무 데이터.
+
+Quick start:
+    import hyean as hy
+
+    hy.set_api_key("hyn_live_xxxx")
+    hy.set_base_url("https://api.hyean.io/v1")
+
+    # 스마트 식별자 — corp_code, stock_code, 기업명 모두 가능
+    bs = hy.load_balance("005930")
+    bs = hy.load_balance("삼성전자")
+    bs = hy.load_balance("00126380")
+
+    # 복수 기업
+    bs = hy.load_balance(["005930", "000660"])
+
+    # 품질 필터
+    bs = hy.load_balance("005930", min_confidence="high")
+
+    # 원문 추적
+    url = hy.source_url(bs, "BS_AST_TOT", "2024")
+
+    # CompanyHub
+    hub = hy.CompanyHub("005930")
+    hub.balance, hub.income, hub.audit
+"""
+
+__version__ = "0.4.0"
+
+# ── Config ──
+from .config import (
+    set_api_key, get_api_key, load_api_key,
+    set_base_url, get_base_url,
+    set_data_dir, get_data_dir,
+    set_cache, get_cache_format, get_refresh_days,
+)
+
+# ── Companies ──
+from .companies import load_companies, search_companies, company_detail, load_company, resolve
+
+# ── Discover (AI 카탈로그) ──
+from .discover import discover
+
+# ── Financials (core) ──
+from .financials import (
+    load_financials,
+    load_balance, load_income, load_cashflow,
+    load_derived,
+)
+
+# ── Events & Anomalies ──
+from .events import load_events, search_events, load_anomalies
+
+# ── Groups / Rank / Grades ──
+from .groups import load_groups, load_rank
+from .grades import load_grades
+
+# ── Profile / Risk / Quality / Notes / Insight ──
+from .profile import (
+    load_profile, load_risk, load_quality,
+    load_notes, load_note_elements, load_insight_context,
+)
+
+# ── Segments ──
+from .segments import load_segments, load_segment_axes
+
+# ── Insight S1 context ──
+from .context import (
+    load_context_categories, load_context, load_context_available, search_context,
+)
+
+# ── Audit / Coverage / Benchmark / Deep ──
+from .audit import load_audit
+from .coverage import load_coverage
+from .benchmark import load_benchmark
+from .deep import load_deep
+
+# ── Valuation ──
+from .valuation import load_valuation
+
+# ── Filings ──
+from .filings import load_filings, load_filing
+
+# ── Prices ──
+from .prices import load_prices
+
+# ── Enhanced (AI Agent 최적화) ──
+from .enhanced import (
+    load_summary, load_price, load_price_stats,
+    load_quarterly, load_peers, load_prices_bulk, screening,
+)
+
+# ── Macro (ECOS) ──
+from .macro import load_macro, load_macro_rates, load_macro_indicators, load_macro_context
+
+# ── KRX Index ──
+from .index import load_index_list, load_index_timeseries, load_index_constituents
+
+# ── Source provenance ──
+from .source import load_source_detail, load_source_items
+
+# ── Meta ──
+from .meta import load_items, load_stats
+
+# ── Utils ──
+from .utils import pivot_financials, source_url, source_detail
+
+# ── Hub ──
+from .hub import CompanyHub
+
+# ── Exceptions ──
+from .exceptions import HyeanError, APIError, NotFoundError, ConfigError

hyean-0.4.0/sdk/audit.py

@@ -0,0 +1,17 @@
+"""Audit opinions, going concern, KAM"""
+from .client import get_client
+from .companies import resolve
+
+
+def load_audit(code: str | None = None, *, corp_code: str | None = None, stock_code: str | None = None) -> dict:
+    """
+    Load audit opinions, going concern warnings, and KAM.
+
+    Args:
+        code: Smart identifier (corp_code/stock_code/name)
+
+    Returns:
+        Dict with keys: corp_code, total, has_going_concern, reports[]
+    """
+    cc = resolve(code or corp_code or stock_code)
+    return get_client().get(f"/api/companies/{cc}/audit")

hyean-0.4.0/sdk/benchmark.py

@@ -0,0 +1,32 @@
+"""Sector benchmark comparison"""
+from .client import get_client
+from .companies import resolve
+
+
+def load_benchmark(
+    code: str | None = None,
+    *,
+    corp_code: str | None = None,
+    stock_code: str | None = None,
+    consol: int = 1,
+    group_by: str | None = None,
+    group_code: str | None = None,
+) -> dict:
+    """
+    Compare company metrics against group benchmarks.
+
+    Args:
+        code: Smart identifier (corp_code/stock_code/name)
+        group_by: Comparison dimension (industry/krx_index/market/size/ecos_sector)
+        group_code: Specific group within dimension (auto-resolved if omitted)
+
+    Returns:
+        Dict with keys: corp_name, sector_code, items[]
+    """
+    cc = resolve(code or corp_code or stock_code)
+    params: dict = {"consol": consol}
+    if group_by:
+        params["group_by"] = group_by
+    if group_code:
+        params["group_code"] = group_code
+    return get_client().get(f"/api/companies/{cc}/benchmark", params)

hyean-0.4.0/sdk/cache.py

@@ -0,0 +1,89 @@
+"""
+Caching decorator for Hyean SDK
+=================================
+Caches DataFrame results to local disk.
+"""
+import time
+import hashlib
+import functools
+from pathlib import Path
+
+import pandas as pd
+
+from .config import get_data_dir, get_cache_format, get_refresh_days
+
+
+def _cache_path(name: str, fmt: str) -> Path | None:
+    data_dir = get_data_dir()
+    if data_dir is None:
+        return None
+    ext = {"pickle": ".pkl", "parquet": ".parquet"}.get(fmt, ".pkl")
+    return data_dir / "cache" / f"{name}{ext}"
+
+
+def _file_age_days(path: Path) -> float:
+    if not path.exists():
+        return float("inf")
+    return (time.time() - path.stat().st_mtime) / 86400
+
+
+def _save_df(df: pd.DataFrame, path: Path, fmt: str):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if fmt == "parquet":
+        df.to_parquet(path)
+    else:
+        df.to_pickle(path)
+
+
+def _load_df(path: Path, fmt: str) -> pd.DataFrame:
+    if fmt == "parquet":
+        return pd.read_parquet(path)
+    else:
+        return pd.read_pickle(path)
+
+
+def cache(name_template: str, refresh_days: int | None = None):
+    """
+    Decorator that caches DataFrame results to disk.
+
+    Args:
+        name_template: Cache file name template with {param} placeholders.
+                       e.g. "balance_{corp_code}_{consol}"
+        refresh_days: Override global refresh_days setting.
+
+    Usage:
+        @cache("balance_{corp_code}_{consol}")
+        def load_balance(corp_code, consol=1):
+            ...
+    """
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # Build cache key from function args
+            import inspect
+            sig = inspect.signature(func)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+
+            try:
+                cache_name = name_template.format(**bound.arguments)
+            except (KeyError, IndexError):
+                # Can't build cache name, skip caching
+                return func(*args, **kwargs)
+
+            fmt = get_cache_format()
+            path = _cache_path(cache_name, fmt)
+
+            if path is not None:
+                max_age = refresh_days if refresh_days is not None else get_refresh_days()
+                if _file_age_days(path) < max_age:
+                    return _load_df(path, fmt)
+
+            result = func(*args, **kwargs)
+
+            if path is not None and isinstance(result, pd.DataFrame) and not result.empty:
+                _save_df(result, path, fmt)
+
+            return result
+        return wrapper
+    return decorator

hyean-0.4.0/sdk/client.py

@@ -0,0 +1,97 @@
+"""
+HTTP client for Hyean API
+==========================
+Handles requests, retries, error mapping.
+"""
+import requests
+from urllib.parse import urljoin
+
+from .config import get_base_url, get_api_key
+from .exceptions import APIError, NotFoundError, HyeanError
+
+
+class HyeanClient:
+    """HTTP client with retry and error handling"""
+
+    def __init__(self, base_url: str | None = None, api_key: str | None = None):
+        self._base_url = base_url
+        self._api_key = api_key
+        self._session = requests.Session()
+        self._session.headers["User-Agent"] = "hyean-sdk/0.4.0"
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url or get_base_url()
+
+    @property
+    def api_key(self) -> str | None:
+        return self._api_key or get_api_key()
+
+    def get(self, path: str, params: dict | None = None) -> dict:
+        """GET request, returns parsed JSON"""
+        url = urljoin(self.base_url + "/", path.lstrip("/"))
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        try:
+            resp = self._session.get(url, params=params, headers=headers, timeout=30)
+        except requests.ConnectionError:
+            raise HyeanError(f"서버 연결 실패: {self.base_url}")
+        except requests.Timeout:
+            raise HyeanError("요청 타임아웃 (30초)")
+
+        if resp.status_code == 404:
+            raise NotFoundError(resp.text)
+        if resp.status_code >= 400:
+            detail = ""
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise APIError(resp.status_code, detail)
+
+        return resp.json()
+
+    def post(self, path: str, json_body: dict | None = None) -> dict:
+        """POST request, returns parsed JSON"""
+        url = urljoin(self.base_url + "/", path.lstrip("/"))
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        try:
+            resp = self._session.post(url, json=json_body, headers=headers, timeout=60)
+        except requests.ConnectionError:
+            raise HyeanError(f"서버 연결 실패: {self.base_url}")
+        except requests.Timeout:
+            raise HyeanError("요청 타임아웃 (60초)")
+
+        if resp.status_code == 404:
+            raise NotFoundError(resp.text)
+        if resp.status_code >= 400:
+            detail = ""
+            try:
+                detail = resp.json().get("detail", resp.text)
+            except Exception:
+                detail = resp.text
+            raise APIError(resp.status_code, detail)
+
+        return resp.json()
+
+
+# Module-level singleton
+_client: HyeanClient | None = None
+
+
+def get_client() -> HyeanClient:
+    global _client
+    if _client is None:
+        _client = HyeanClient()
+    return _client
+
+
+def reset_client():
+    """Reset client (e.g. after changing base_url)"""
+    global _client
+    _client = None