financechatbotkit 2.0.0__py3-none-any.whl

orchestrator/mapping/update_raw_data.py

@@ -0,0 +1,96 @@
+"""CLI utility for refreshing the bundled OpenDart corp-code JSON."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Sequence
+
+from ..exceptions import MappingWorkflowError
+from .workflow import download_latest_raw_entries
+
+_DEFAULT_OUTPUT_PATH = Path(__file__).resolve().parent / "data" / "corp_codes_raw.json"
+
+
+def get_default_output_path() -> Path:
+    return _DEFAULT_OUTPUT_PATH
+
+
+def update_raw_corp_codes_file(
+    *,
+    api_key: str,
+    output_path: str | Path | None = None,
+) -> tuple[Path, int]:
+    target_path = Path(output_path) if output_path is not None else get_default_output_path()
+    raw_entries = download_latest_raw_entries(api_key)
+    payload = [
+        {
+            "corp_code": row["corp_code"],
+            "corp_name": row["stock_name"],
+            "stock_code": row["stock_code"],
+            "modify_date": row["modify_date"],
+        }
+        for row in raw_entries
+    ]
+    serialized = json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
+
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            "w",
+            encoding="utf-8",
+            dir=target_path.parent,
+            delete=False,
+        ) as handle:
+            handle.write(serialized)
+            temp_path = Path(handle.name)
+        temp_path.replace(target_path)
+    finally:
+        if temp_path is not None and temp_path.exists():
+            temp_path.unlink()
+    return target_path, len(payload)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Refresh the bundled OpenDart corp_codes_raw.json file.",
+    )
+    parser.add_argument(
+        "--api-key",
+        default=os.environ.get("DART_API_KEY"),
+        help="OpenDart API key. Defaults to the DART_API_KEY environment variable.",
+    )
+    parser.add_argument(
+        "--output",
+        default=None,
+        help=f"Output path. Defaults to {get_default_output_path()}",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.api_key:
+        parser.error("--api-key is required unless DART_API_KEY is set.")
+
+    try:
+        output_path, entry_count = update_raw_corp_codes_file(
+            api_key=args.api_key,
+            output_path=args.output,
+        )
+    except (MappingWorkflowError, OSError) as exc:
+        print(f"Failed to refresh corp codes: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"Updated {output_path} with {entry_count} entries.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

orchestrator/mapping/workflow.py

@@ -0,0 +1,303 @@
+"""Mapping workflow for OpenDart corp-code data."""
+
+from __future__ import annotations
+
+import io
+import json
+import ssl
+import urllib.error
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+import zipfile
+from collections import OrderedDict
+from importlib.resources import files
+from typing import Any
+
+from ..exceptions import DownloadError, InvalidInputError, NotFoundError
+
+_CORP_CODE_URL = "https://opendart.fss.or.kr/api/corpCode.xml"
+_BUNDLED_DATA_KEY = "__bundled__"
+_MISSING = object()
+
+
+def _normalize_entry(item: Any) -> dict[str, Any]:
+    if not isinstance(item, dict):
+        raise InvalidInputError("Each corp-code entry must be a JSON object.")
+    corp_code = _clean(item.get("corp_code"))
+    stock_name = _clean(item.get("corp_name") or item.get("stock_name"))
+    stock_code = _clean(item.get("stock_code"))
+    modify_date = _clean(item.get("modify_date"))
+    if corp_code is None or stock_name is None:
+        raise InvalidInputError("Each corp-code entry must include corp_code and corp_name.")
+    return {
+        "corp_code": corp_code,
+        "stock_name": stock_name,
+        "stock_code": stock_code,
+        "modify_date": modify_date,
+    }
+
+
+
+def _clean(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+
+def _normalize_name(value: str) -> str:
+    return " ".join(value.split()).casefold()
+
+
+
+def _build_input_payload(
+    *,
+    stock_code: str | None,
+    stock_name: str | None,
+    corp_code: str | None,
+    get_latest: bool,
+    get_all: bool,
+    include_nonlisted: bool,
+) -> dict[str, Any]:
+    return {
+        "stock_code": _clean(stock_code),
+        "stock_name": _clean(stock_name),
+        "corp_code": _clean(corp_code),
+        "get_latest": get_latest,
+        "get_all": get_all,
+        "include_nonlisted": include_nonlisted,
+    }
+
+
+
+def _detect_lookup_key(*, stock_code: str | None, stock_name: str | None, corp_code: str | None) -> tuple[str, str]:
+    provided = [
+        ("stock_code", _clean(stock_code)),
+        ("stock_name", _clean(stock_name)),
+        ("corp_code", _clean(corp_code)),
+    ]
+    provided = [(key, value) for key, value in provided if value is not None]
+    if len(provided) != 1:
+        raise InvalidInputError("Exactly one of stock_code, stock_name, or corp_code must be provided.")
+    return provided[0]
+
+
+
+def _filter_entries(entries: tuple[dict[str, Any], ...], lookup_key: str, lookup_value: str) -> list[dict[str, Any]]:
+    if lookup_key == "stock_name":
+        normalized = _normalize_name(lookup_value)
+        return [entry for entry in entries if _normalize_name(entry["stock_name"]) == normalized]
+    return [entry for entry in entries if entry[lookup_key] == lookup_value]
+
+
+
+def download_latest_raw_entries(api_key: str) -> tuple[dict[str, Any], ...]:
+    api_key = _clean(api_key)
+    if api_key is None:
+        raise InvalidInputError("api_key is required when get_latest=True.")
+
+    query = urllib.parse.urlencode({"crtfc_key": api_key})
+    request_url = f"{_CORP_CODE_URL}?{query}"
+    try:
+        with urllib.request.urlopen(request_url, timeout=60, context=ssl.create_default_context()) as response:
+            content = response.read()
+    except (urllib.error.URLError, TimeoutError) as exc:
+        raise DownloadError("Failed to download OpenDart corpCode.xml.") from exc
+
+    try:
+        with zipfile.ZipFile(io.BytesIO(content)) as zipped:
+            xml_name = next(name for name in zipped.namelist() if name.upper().endswith(".XML"))
+            xml_bytes = zipped.read(xml_name)
+    except (StopIteration, zipfile.BadZipFile, KeyError) as exc:
+        raise DownloadError("Downloaded OpenDart corpCode.xml payload is invalid.") from exc
+
+    try:
+        root = ET.fromstring(xml_bytes)
+    except ET.ParseError as exc:
+        raise DownloadError("OpenDart corpCode.xml could not be parsed.") from exc
+
+    rows: list[dict[str, Any]] = []
+    for item in root.iter("list"):
+        rows.append(
+            {
+                "corp_code": _clean(item.findtext("corp_code")),
+                "corp_name": _clean(item.findtext("corp_name")),
+                "stock_code": _clean(item.findtext("stock_code")),
+                "modify_date": _clean(item.findtext("modify_date")),
+            }
+        )
+    return tuple(_normalize_entry(row) for row in rows)
+
+
+class MappingWorkflow:
+    """Resolve stock_name, stock_code, and corp_code from OpenDart corp-code data."""
+
+    def __init__(self, *, cache_size: int = 0, data_path: str | None = None) -> None:
+        if cache_size < 0:
+            raise InvalidInputError("cache_size must be >= 0.")
+        self._cache_size = cache_size
+        self._data_path = data_path
+        self._raw_cache: OrderedDict[str, tuple[dict[str, Any], ...]] = OrderedDict()
+        self._processed_cache: OrderedDict[tuple[str, bool], tuple[dict[str, Any], ...]] = OrderedDict()
+
+    @property
+    def cache_size(self) -> int:
+        return self._cache_size
+
+    def clear_cache(self) -> None:
+        self._raw_cache.clear()
+        self._processed_cache.clear()
+
+    def run(
+        self,
+        *,
+        stock_code: str | None = None,
+        stock_name: str | None = None,
+        corp_code: str | None = None,
+        get_latest: bool = False,
+        get_all: bool = False,
+        include_nonlisted: bool = False,
+        api_key: str | None = None,
+        data_path: str | None = None,
+    ) -> dict[str, Any]:
+        input_payload = _build_input_payload(
+            stock_code=stock_code,
+            stock_name=stock_name,
+            corp_code=corp_code,
+            get_latest=get_latest,
+            get_all=get_all,
+            include_nonlisted=include_nonlisted,
+        )
+
+        if get_latest:
+            raw_entries = download_latest_raw_entries(api_key or "")
+            entries = tuple(
+                {
+                    "stock_name": row["stock_name"],
+                    "stock_code": row["stock_code"],
+                    "corp_code": row["corp_code"],
+                }
+                for row in raw_entries
+                if include_nonlisted or row["stock_code"] is not None
+            )
+        else:
+            entries = self._load_processed_entries(data_path, include_nonlisted)
+
+        if get_all:
+            return {
+                "input": input_payload,
+                "data": {"mappings": list(entries)},
+            }
+
+        lookup_key, lookup_value = _detect_lookup_key(
+            stock_code=stock_code,
+            stock_name=stock_name,
+            corp_code=corp_code,
+        )
+        matches = _filter_entries(entries, lookup_key, lookup_value)
+        if not matches:
+            raise NotFoundError(f"No mapping found for {lookup_key}={lookup_value!r}.")
+        return {
+            "input": input_payload,
+            "data": {"mappings": matches},
+        }
+
+    def _load_raw_entries(self, data_path: str | None) -> tuple[dict[str, Any], ...]:
+        resolved_data_path = self._resolve_data_path(data_path)
+        cache_key = resolved_data_path or _BUNDLED_DATA_KEY
+        cached = self._cache_get(self._raw_cache, cache_key)
+        if cached is not _MISSING:
+            return cached
+
+        if resolved_data_path is None:
+            resource = files("orchestrator.mapping.data").joinpath("corp_codes_raw.json")
+            text = resource.read_text(encoding="utf-8")
+        else:
+            with open(resolved_data_path, "r", encoding="utf-8") as handle:
+                text = handle.read()
+
+        data = json.loads(text)
+        if not isinstance(data, list):
+            raise InvalidInputError("Bundled corp-code JSON must contain a list of entries.")
+        rows = tuple(_normalize_entry(item) for item in data)
+        self._cache_set(self._raw_cache, cache_key, rows)
+        return rows
+
+    def _load_processed_entries(
+        self,
+        data_path: str | None,
+        include_nonlisted: bool,
+    ) -> tuple[dict[str, Any], ...]:
+        resolved_data_path = self._resolve_data_path(data_path)
+        cache_key = (resolved_data_path or _BUNDLED_DATA_KEY, include_nonlisted)
+        cached = self._cache_get(self._processed_cache, cache_key)
+        if cached is not _MISSING:
+            return cached
+
+        rows = self._load_raw_entries(resolved_data_path)
+        processed: list[dict[str, Any]] = []
+        for row in rows:
+            stock_code = row["stock_code"]
+            if not include_nonlisted and stock_code is None:
+                continue
+            processed.append(
+                {
+                    "stock_name": row["stock_name"],
+                    "stock_code": stock_code,
+                    "corp_code": row["corp_code"],
+                }
+            )
+        result = tuple(processed)
+        self._cache_set(self._processed_cache, cache_key, result)
+        return result
+
+    def _resolve_data_path(self, data_path: str | None) -> str | None:
+        return data_path if data_path is not None else self._data_path
+
+    def _cache_get(self, cache: OrderedDict[Any, Any], key: Any) -> Any:
+        if self._cache_size == 0:
+            return _MISSING
+        try:
+            value = cache.pop(key)
+        except KeyError:
+            return _MISSING
+        cache[key] = value
+        return value
+
+    def _cache_set(self, cache: OrderedDict[Any, Any], key: Any, value: Any) -> None:
+        if self._cache_size == 0:
+            return
+        if key in cache:
+            cache.pop(key)
+        cache[key] = value
+        while len(cache) > self._cache_size:
+            cache.popitem(last=False)
+
+
+_DEFAULT_WORKFLOW = MappingWorkflow(cache_size=0)
+
+
+
+def run_mapping_workflow(
+    *,
+    stock_code: str | None = None,
+    stock_name: str | None = None,
+    corp_code: str | None = None,
+    get_latest: bool = False,
+    get_all: bool = False,
+    include_nonlisted: bool = False,
+    api_key: str | None = None,
+    data_path: str | None = None,
+) -> dict[str, Any]:
+    return _DEFAULT_WORKFLOW.run(
+        stock_code=stock_code,
+        stock_name=stock_name,
+        corp_code=corp_code,
+        get_latest=get_latest,
+        get_all=get_all,
+        include_nonlisted=include_nonlisted,
+        api_key=api_key,
+        data_path=data_path,
+    )

orchestrator/price/__init__.py

@@ -0,0 +1,15 @@
+"""Price workflows for FinanceChatbot."""
+
+from .workflow import (
+    PricePeriodWorkflow,
+    PriceSnapshotWorkflow,
+    run_price_period_workflow,
+    run_price_snapshot_workflow,
+)
+
+__all__ = [
+    "PricePeriodWorkflow",
+    "PriceSnapshotWorkflow",
+    "run_price_period_workflow",
+    "run_price_snapshot_workflow",
+]

orchestrator/price/workflow.py

@@ -0,0 +1,250 @@
+"""Price workflows built on FinanceDataReader."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, timedelta
+from typing import Any
+
+from ..exceptions import InvalidInputError, NotFoundError
+
+
+@dataclass(frozen=True)
+class PriceBar:
+    """Normalized daily price bar."""
+
+    trade_date: str
+    open: int | None = None
+    close: int | None = None
+    low: int | None = None
+    high: int | None = None
+    volume: int | None = None
+
+    def has_fields(self, field_names: tuple[str, ...]) -> bool:
+        return all(getattr(self, field_name) is not None for field_name in field_names)
+
+    def to_dict(self, *, field_names: tuple[str, ...]) -> dict[str, int | str]:
+        payload: dict[str, int | str] = {"date": self.trade_date}
+        for field_name in field_names:
+            value = getattr(self, field_name)
+            if value is None:
+                raise InvalidInputError(f"Missing {field_name} value for trade_date={self.trade_date}.")
+            payload[field_name] = value
+        return payload
+
+
+_PRICE_FIELD_PRESETS: dict[str, tuple[str, ...]] = {
+    "close": ("close",),
+    "oclh": ("open", "close", "low", "high"),
+    "oclhv": ("open", "close", "low", "high", "volume"),
+}
+
+_PRICE_SOURCE_COLUMNS = {
+    "open": "Open",
+    "close": "Close",
+    "low": "Low",
+    "high": "High",
+    "volume": "Volume",
+}
+
+
+class PriceSnapshotWorkflow:
+    """Return the latest price and the closest previous price."""
+
+    def __init__(self, *, lookback_days: int = 30) -> None:
+        if lookback_days < 2:
+            raise InvalidInputError("lookback_days must be >= 2.")
+        self._lookback_days = lookback_days
+
+    def run(
+        self,
+        *,
+        stock_code: str,
+        lookback_days: int | None = None,
+        price_fields: str = "close",
+    ) -> dict[str, Any]:
+        stock_code = _normalize_stock_code(stock_code)
+        window = lookback_days if lookback_days is not None else self._lookback_days
+        if window < 2:
+            raise InvalidInputError("lookback_days must be >= 2.")
+        normalized_price_fields, field_names = _normalize_price_fields(price_fields)
+
+        bars = _fetch_price_bars(
+            stock_code=stock_code,
+            start=(date.today() - timedelta(days=window)).isoformat(),
+            end=date.today().isoformat(),
+            field_names=field_names,
+        )
+        if len(bars) < 2:
+            raise NotFoundError(f"Not enough price history found for stock_code={stock_code!r}.")
+
+        latest = bars[-1]
+        previous = bars[-2]
+        response = {
+            "input": {
+                "stock_code": stock_code,
+                "lookback_days": window,
+                "price_fields": normalized_price_fields,
+            },
+            "data": {},
+        }
+        if normalized_price_fields == "close":
+            response["data"] = {
+                "lastClose": previous.close,
+                "latestClose": latest.close,
+            }
+            return response
+
+        response["data"] = {
+            "lastPrice": previous.to_dict(field_names=field_names),
+            "latestPrice": latest.to_dict(field_names=field_names),
+        }
+        return response
+
+
+class PricePeriodWorkflow:
+    """Return daily prices for a specific period."""
+
+    def run(
+        self,
+        *,
+        stock_code: str,
+        start_date: str,
+        end_date: str | None = None,
+        price_fields: str = "close",
+    ) -> dict[str, Any]:
+        stock_code = _normalize_stock_code(stock_code)
+        start_date = _normalize_date_string(start_date, field_name="start_date")
+        end_date = _normalize_date_string(end_date, field_name="end_date") if end_date else date.today().isoformat()
+        if start_date > end_date:
+            raise InvalidInputError("start_date must be <= end_date.")
+        normalized_price_fields, field_names = _normalize_price_fields(price_fields)
+
+        bars = _fetch_price_bars(
+            stock_code=stock_code,
+            start=start_date,
+            end=end_date,
+            field_names=field_names,
+        )
+        if not bars:
+            raise NotFoundError(
+                f"No price data found for stock_code={stock_code!r} between {start_date} and {end_date}."
+            )
+
+        return {
+            "input": {
+                "stock_code": stock_code,
+                "start_date": start_date,
+                "end_date": end_date,
+                "price_fields": normalized_price_fields,
+            },
+            "data": {
+                "prices": [
+                    bar.to_dict(field_names=field_names)
+                    for bar in bars
+                ]
+            },
+        }
+
+
+_DEFAULT_SNAPSHOT_WORKFLOW = PriceSnapshotWorkflow()
+_DEFAULT_PERIOD_WORKFLOW = PricePeriodWorkflow()
+
+
+def run_price_snapshot_workflow(
+    *,
+    stock_code: str,
+    lookback_days: int = 30,
+    price_fields: str = "close",
+) -> dict[str, Any]:
+    return _DEFAULT_SNAPSHOT_WORKFLOW.run(
+        stock_code=stock_code,
+        lookback_days=lookback_days,
+        price_fields=price_fields,
+    )
+
+
+def run_price_period_workflow(
+    *,
+    stock_code: str,
+    start_date: str,
+    end_date: str | None = None,
+    price_fields: str = "close",
+) -> dict[str, Any]:
+    return _DEFAULT_PERIOD_WORKFLOW.run(
+        stock_code=stock_code,
+        start_date=start_date,
+        end_date=end_date,
+        price_fields=price_fields,
+    )
+
+
+
+def _fetch_price_bars(
+    *,
+    stock_code: str,
+    start: str,
+    end: str,
+    field_names: tuple[str, ...],
+) -> list[PriceBar]:
+    df = _load_price_frame(stock_code=stock_code, start=start, end=end)
+    if df is None or df.empty:
+        return []
+
+    bars: list[PriceBar] = []
+    for idx, row in df.iterrows():
+        bar = _build_price_bar(idx=idx, row=row)
+        if bar.has_fields(field_names):
+            bars.append(bar)
+    return bars
+
+
+
+def _load_price_frame(*, stock_code: str, start: str, end: str):
+    try:
+        import FinanceDataReader as fdr  # noqa: PLC0415
+    except ImportError as exc:
+        raise InvalidInputError("FinanceDataReader is required for price workflows.") from exc
+    return fdr.DataReader(stock_code, start, end)
+
+
+
+def _normalize_stock_code(stock_code: str) -> str:
+    normalized = str(stock_code or "").strip()
+    if not normalized:
+        raise InvalidInputError("stock_code is required.")
+    return normalized
+
+
+
+def _normalize_date_string(value: str | None, *, field_name: str) -> str:
+    normalized = str(value or "").strip()
+    if not normalized:
+        raise InvalidInputError(f"{field_name} is required.")
+    try:
+        return date.fromisoformat(normalized).isoformat()
+    except ValueError as exc:
+        raise InvalidInputError(f"{field_name} must be YYYY-MM-DD.") from exc
+
+
+def _normalize_price_fields(price_fields: str | None) -> tuple[str, tuple[str, ...]]:
+    normalized = str(price_fields or "close").strip().lower()
+    field_names = _PRICE_FIELD_PRESETS.get(normalized)
+    if field_names is None:
+        raise InvalidInputError("price_fields must be one of: close, oclh, oclhv.")
+    return normalized, field_names
+
+
+def _build_price_bar(*, idx: Any, row: Any) -> PriceBar:
+    values: dict[str, int] = {}
+    for field_name, column_name in _PRICE_SOURCE_COLUMNS.items():
+        value = row.get(column_name)
+        if _is_missing(value):
+            continue
+        values[field_name] = int(value)
+    trade_date = idx.date().isoformat() if hasattr(idx, "date") else str(idx)[:10]
+    return PriceBar(trade_date=trade_date, **values)
+
+
+def _is_missing(value: Any) -> bool:
+    return value is None or value != value