financechatbotkit 2.0.0__py3-none-any.whl

orchestrator/bond/getOptiExerPricAdju.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+from typing import Any
+from .base_reader import get_datagokr_document
+
+
+"""
+Read https://www.data.go.kr/data/15059595/openapi.do
+"""
+
+
+def get_OptiExerPricAdju(
+    serviceKey: str,
+    isinCd: str,
+    timeout_seconds: float = 60.0,
+) -> Any | None:
+    """ 행사가 변동내역 및 현재 행사가 다운로드. """
+    if not isinCd:
+        return None
+
+    service_url = "1160100/service/GetBondRedeInfoService/getOptiExerPricAdju"
+    params: dict[str, Any] = {
+        "serviceKey": serviceKey,
+        "isinCd": isinCd,
+    }
+
+    return get_datagokr_document(
+        serviceUrl=service_url,
+        params=params,
+        timeout_seconds=timeout_seconds
+    )
+
+
+def parse_opti_exer_pric_adju(
+    serviceKey: str,
+    isinCd: str,
+    timeout_seconds: float = 60.0,
+) -> list[dict[str, Any]] | None:
+    """ Parse get_OptiExerPricAdju results. """
+    raw = get_OptiExerPricAdju(
+        serviceKey=serviceKey,
+        isinCd=isinCd,
+        timeout_seconds=timeout_seconds,
+    )
+    if raw is None:
+        return None
+
+    try:
+        body = raw["response"]["body"]
+        items_obj = body.get("items")
+    except Exception:
+        return None
+
+    def extract_items(items: Any) -> list[dict[str, Any]]:
+        if items is None:
+            return []
+        if isinstance(items, dict) and "item" in items:
+            inner = items.get("item")
+            if inner is None:
+                return []
+            if isinstance(inner, list):
+                return [i for i in inner if isinstance(i, dict)]
+            return [inner] if isinstance(inner, dict) else []
+        if isinstance(items, list):
+            return [i for i in items if isinstance(i, dict)]
+        return [items] if isinstance(items, dict) else []
+
+    items = extract_items(items_obj)
+    if not items:
+        return []
+
+    out: list[dict[str, Any]] = []
+    for it in items:
+        out.append(
+            {
+                "현재행사가": it.get("optnExertPrc", ""),
+                "변경일": it.get("rgtExertPricAdjDt"),
+                "이전행사가": it.get("rgtBchgExertPrc"),
+                "이후행사가": it.get("rgtAchgExertPrc"),
+            }
+        )
+
+    # items 에 "rgtExertPricAdjDt": "00010101" 하나만 있으면 items 를 None 으로 처리
+    out = [x for x in out if (x.get("rgtExertPricAdjDt") != "00010101")]
+    return out

orchestrator/bond/workflow.py

@@ -0,0 +1,252 @@
+"""Data.go.kr bond workflows included directly in FinanceChatbot."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ..exceptions import InvalidInputError
+
+
+def _empty_market_bond_payload(issue: dict[str, Any] | None = None) -> dict[str, Any]:
+    return {
+        "issue": issue,
+        "optionRedemptions": [],
+        "optionExercises": [],
+        "priceAdjustments": [],
+        "optionSchedules": [],
+        "bondBasicInfo": [],
+    }
+
+
+def _compact_dict(value: dict[str, Any]) -> dict[str, Any]:
+    return {
+        key: item
+        for key, item in value.items()
+        if item is not None and item != "" and item != [] and item != {} and item != "-"
+    }
+
+
+def _coerce_list(value: Any) -> list[dict[str, Any]]:
+    if not isinstance(value, list):
+        return []
+    return [item for item in value if isinstance(item, dict)]
+
+
+def _normalize_items(items: Any, normalizer) -> list[dict[str, Any]]:
+    normalized_items: list[dict[str, Any]] = []
+    for item in _coerce_list(items):
+        normalized = normalizer(item)
+        if normalized:
+            normalized_items.append(normalized)
+    return normalized_items
+
+
+def _normalize_issue(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    normalized = _compact_dict(
+        {
+            "isinCdNm": value.get("isinCdNm"),
+            "isinCd": value.get("isinCd"),
+            "basDt": value.get("basDt") or value.get("기준일자"),
+            "bondIssuDt": value.get("bondIssuDt") or value.get("발행일"),
+            "bondExprDt": value.get("bondExprDt") or value.get("만기일"),
+            "bondIssuAmt": value.get("bondIssuAmt") or value.get("최초발행권면"),
+            "bondPymtAmt": value.get("bondPymtAmt") or value.get("최초납입금액"),
+        }
+    )
+    return normalized or None
+
+
+def _normalize_redemption_item(item: dict[str, Any]) -> dict[str, Any] | None:
+    normalized = _compact_dict(
+        {
+            "optnTcdNm": item.get("optnTcdNm") or item.get("옵션분류"),
+            "opbdClrdDt": item.get("opbdClrdDt") or item.get("행사일자"),
+            "opbdPamtPayAmt": item.get("opbdPamtPayAmt") or item.get("행사원금"),
+            "opbdIntPayAmt": item.get("opbdIntPayAmt") or item.get("행사이자"),
+            "bondIssuAmt": item.get("bondIssuAmt") or item.get("발행잔액"),
+        }
+    )
+    return normalized or None
+
+
+def _normalize_exercise_item(item: dict[str, Any]) -> dict[str, Any] | None:
+    normalized = _compact_dict(
+        {
+            "rgtOccrBasDt": item.get("rgtOccrBasDt") or item.get("행사일"),
+            "optnExertPrc": item.get("optnExertPrc") or item.get("현재행사단가"),
+            "exertPric": item.get("exertPric") or item.get("행사단가"),
+            "exertAmt": item.get("exertAmt") or item.get("행사금액"),
+        }
+    )
+    if normalized.get("rgtOccrBasDt") in {"00000000", "00010101"}:
+        return None
+    return normalized or None
+
+
+def _normalize_adjustment_item(item: dict[str, Any]) -> dict[str, Any] | None:
+    normalized = _compact_dict(
+        {
+            "optnExertPrc": item.get("optnExertPrc") or item.get("현재행사가"),
+            "rgtExertPricAdjDt": item.get("rgtExertPricAdjDt") or item.get("변경일"),
+            "rgtBchgExertPrc": item.get("rgtBchgExertPrc") or item.get("이전행사가"),
+            "rgtAchgExertPrc": item.get("rgtAchgExertPrc") or item.get("이후행사가"),
+        }
+    )
+    if normalized.get("rgtExertPricAdjDt") in {"00000000", "00010101"}:
+        return None
+    return normalized or None
+
+
+def _normalize_schedule_item(item: dict[str, Any]) -> dict[str, Any] | None:
+    dates = item.get("dates") or item.get("행사일정") or []
+    normalized = _compact_dict(
+        {
+            "type": item.get("type") or item.get("옵션분류"),
+            "dates": dates if isinstance(dates, list) else [],
+        }
+    )
+    return normalized or None
+
+
+def _normalize_basic_info_item(item: dict[str, Any]) -> dict[str, Any] | None:
+    normalized = _compact_dict(
+        {
+            "bondBal": item.get("bondBal") or item.get("발행잔액"),
+        }
+    )
+    return normalized or None
+
+
+def _orchestrate_bond_api_flow(
+    *,
+    api_key: str,
+    query: str,
+    parse_issue,
+    parse_redemptions,
+    parse_exercises,
+    parse_adjustments,
+    parse_schedules,
+    parse_basic_info,
+    issuer_name_from_bond_name,
+    normalize_name,
+) -> dict[str, Any]:
+    normalized_query = normalize_name(query)
+    issuer_name = issuer_name_from_bond_name(query)
+
+    issue = parse_issue(
+        serviceKey=api_key,
+        bondIsurNm=issuer_name,
+        bondNm=normalized_query,
+    )
+    if not isinstance(issue, dict):
+        return _empty_market_bond_payload()
+
+    isin_cd = str(issue.get("isinCd") or "").strip()
+    bas_dt = str(issue.get("기준일자") or issue.get("basDt") or "").strip()
+    if not isin_cd or not bas_dt:
+        return _empty_market_bond_payload(_normalize_issue(issue))
+
+    return {
+        "issue": _normalize_issue(issue),
+        "optionRedemptions": _normalize_items(
+            parse_redemptions(serviceKey=api_key, isinCd=isin_cd),
+            _normalize_redemption_item,
+        ),
+        "optionExercises": _normalize_items(
+            parse_exercises(serviceKey=api_key, isinCd=isin_cd),
+            _normalize_exercise_item,
+        ),
+        "priceAdjustments": _normalize_items(
+            parse_adjustments(serviceKey=api_key, isinCd=isin_cd),
+            _normalize_adjustment_item,
+        ),
+        "optionSchedules": _normalize_items(
+            parse_schedules(serviceKey=api_key, basDt=bas_dt, isinCd=isin_cd),
+            _normalize_schedule_item,
+        ),
+        "bondBasicInfo": _normalize_items(
+            parse_basic_info(serviceKey=api_key, basDt=bas_dt, isinCd=isin_cd),
+            _normalize_basic_info_item,
+        ),
+    }
+
+
+def _run_bond_api_flow(api_key: str, query: str) -> dict[str, Any]:
+    from .getBondBasiInfo import parse_bond_basi_info  # noqa: PLC0415
+    from .getBondWithOptiCallRede import parse_bond_with_opti_call_rede  # noqa: PLC0415
+    from .getEarlExerOpti import parse_earl_exer_opti  # noqa: PLC0415
+    from .getIssuIssuItemStat import parse_issu_issu_item_stat  # noqa: PLC0415
+    from .getOptiExer import parse_opti_exer  # noqa: PLC0415
+    from .getOptiExerPricAdju import parse_opti_exer_pric_adju  # noqa: PLC0415
+    from .base_reader import issuer_name_from_bond_name, normalize_name  # noqa: PLC0415
+
+    return _orchestrate_bond_api_flow(
+        api_key=api_key,
+        query=query,
+        parse_issue=parse_issu_issu_item_stat,
+        parse_redemptions=parse_bond_with_opti_call_rede,
+        parse_exercises=parse_opti_exer,
+        parse_adjustments=parse_opti_exer_pric_adju,
+        parse_schedules=parse_earl_exer_opti,
+        parse_basic_info=parse_bond_basi_info,
+        issuer_name_from_bond_name=issuer_name_from_bond_name,
+        normalize_name=normalize_name,
+    )
+
+
+class MarketBondWorkflow:
+    """Return normalized Data.go.kr bond payloads."""
+
+    def __init__(self, *, workflow_runner=None) -> None:
+        self._workflow_runner = workflow_runner or _run_bond_api_flow
+
+    def run(
+        self,
+        *,
+        query: str,
+        api_key: str,
+        save_path: str | None = None,
+    ) -> dict[str, Any]:
+        normalized_query = str(query or "").strip()
+        normalized_api_key = str(api_key or "").strip()
+        if not normalized_query:
+            raise InvalidInputError("query is required.")
+        if not normalized_api_key:
+            raise InvalidInputError("api_key is required.")
+
+        payload = self._workflow_runner(normalized_api_key, normalized_query)
+        if not isinstance(payload, dict):
+            raise InvalidInputError("bond workflow payload must be a JSON object.")
+
+        if save_path:
+            path = Path(save_path)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+        return {
+            "input": {
+                "query": normalized_query,
+                "save_path": save_path,
+            },
+            "data": payload,
+        }
+
+
+_DEFAULT_WORKFLOW = MarketBondWorkflow()
+
+
+def run_market_bond_workflow(
+    *,
+    query: str,
+    api_key: str,
+    save_path: str | None = None,
+) -> dict[str, Any]:
+    return _DEFAULT_WORKFLOW.run(
+        query=query,
+        api_key=api_key,
+        save_path=save_path,
+    )

orchestrator/exceptions.py

@@ -0,0 +1,17 @@
+"""Exceptions for the mapping workflow library."""
+
+
+class MappingWorkflowError(Exception):
+    """Base exception for mapping workflow failures."""
+
+
+class InvalidInputError(MappingWorkflowError):
+    """Raised when the workflow input contract is violated."""
+
+
+class NotFoundError(MappingWorkflowError):
+    """Raised when no mapping matches the requested lookup."""
+
+
+class DownloadError(MappingWorkflowError):
+    """Raised when latest OpenDart corp-code data cannot be downloaded."""

orchestrator/fnguide/__init__.py

@@ -0,0 +1,21 @@
+"""FnGuide workflows for FinanceChatbot."""
+
+from .workflow import (
+    FnGuideWorkflow,
+    build_finance_ratio_params,
+    build_finance_statement_params,
+    fetch_fnguide_page,
+    parse_fnguide_finance_ratio_html,
+    parse_fnguide_finance_statement_html,
+    run_fnguide_workflow,
+)
+
+__all__ = [
+    "FnGuideWorkflow",
+    "build_finance_ratio_params",
+    "build_finance_statement_params",
+    "fetch_fnguide_page",
+    "parse_fnguide_finance_ratio_html",
+    "parse_fnguide_finance_statement_html",
+    "run_fnguide_workflow",
+]