financechatbotkit 3.1.0

FinanceChatbot workflows (orchestrator) and Telegram/Firestore helpers (TeleBotKit)

FinanceChatbot

FinanceChatbot bundles three installable code areas under src/:

• orchestrator: finance data workflows
• utilitykit: reusable utility helpers
• telebotkit: Telegram / Firestore helpers

The package name is financechatbotkit, and it currently requires Python 3.11+.

Orchestrator

orchestrator is the main workflow library for:

• mapping
• price
• fnguide
• bond
• kind

Public API

from orchestrator import (
    FnGuideWorkflow,
    KindWorkflow,
    MappingWorkflow,
    MarketBondWorkflow,
    PricePeriodWorkflow,
)

Feature-level imports are also available:

from orchestrator.mapping import MappingWorkflow
from orchestrator.price import PricePeriodWorkflow
from orchestrator.fnguide import FnGuideWorkflow
from orchestrator.bond import MarketBondWorkflow
from orchestrator.kind import KindWorkflow, parse_kind_html_to_json

Most workflow classes return a normalized payload shaped like:

{
    "input": {...},
    "data": {...},
}

price workflows support price_fields="close" (default), price_fields="oclh", price_fields="oclhv", price_fields="oclhva", and comma-separated field lists such as price_fields="volume,amount" to control which price columns are returned. PricePeriodWorkflow also supports price_source="krx" when KRX Amount data is required for VWAP.

Workflow Classes

The main usage pattern is class-based:

• MappingWorkflow
• PricePeriodWorkflow
• PriceSnapshotWorkflow
• FnGuideWorkflow
• MarketBondWorkflow
• KindWorkflow

For example, FnGuideWorkflow is used like this:

from orchestrator.fnguide import FnGuideWorkflow

workflow = FnGuideWorkflow()
result = workflow.run(stock_code="005930", statement_type="consolidated")

KIND Workflow

kind is slightly different from the other workflow modules because it supports both:

• request payload construction and raw response download
• HTML file parsing into structured JSON

The recommended entry point is KindWorkflow.

from pathlib import Path

from orchestrator.kind import KindWorkflow
from run import KIND_REQUEST_HEADERS

workflow = KindWorkflow()
result = workflow.run(
    output_directory=Path("resources/kind_2012"),
    request_headers=KIND_REQUEST_HEADERS,
    start_date="2012-01-01",
    end_date="2012-12-31",
    start_page=1,
    end_page=10,
    disclosure_type_groups={"01": ["0119"]},
    last_report_only=True,
    save=True,
)

print(result["input_snapshot_path"])
print(result["checkpoint_path"])

KindWorkflow stores normalized input state and, when save=True, writes:

• raw .body files page by page
• kind_workflow.input.json
• kind_workflow.checkpoint.json

This makes long-running downloads easier to inspect and recover.

Lower-level helpers remain available when needed:

from orchestrator.kind import (
    build_kind_search_request_data,
    parse_kind_file_to_json,
    parse_kind_html_to_json,
    save_kind_search_results,
)

Example Script

run.py shows one concrete KIND pipeline:

1. Download paged KIND responses through KindWorkflow
2. Merge downloaded .body files into a single JSON file
3. Convert the merged JSON into Excel using utilitykit

UtilityKit

utilitykit is a shared utilities package for repo-wide helpers that do not belong to orchestrator.

Current public utilities:

• utilitykit.excel.read_xlsx_sheet_as_json()
• utilitykit.excel.write_json_to_xlsx()
• utilitykit.excel.records_to_table()
• utilitykit.excel.project_records_to_table()
• utilitykit.excel.row_cell_records_to_table()

Excel Examples

Read an Excel sheet as list[list] using A1-start automatic bounds detection:

from utilitykit import read_xlsx_sheet_as_json

table = read_xlsx_sheet_as_json("sample.xlsx", sheet_name="Data")

Write row-oriented data:

from utilitykit import write_json_to_xlsx

write_json_to_xlsx(
    [
        {"company": "Samsung", "sales": 100},
        {"company": "LG", "sales": 80},
    ],
    "rows.xlsx",
    sheet_name="Rows",
    axis="rows",
    item_mode="dict",
)

Write column-oriented data:

from utilitykit import write_json_to_xlsx

write_json_to_xlsx(
    {"company": ["Samsung", "LG"], "sales": [100, 80]},
    "columns.xlsx",
    sheet_name="Columns",
    axis="columns",
    item_mode="dict",
)

TeleBotKit

TeleBotKit is a shared helper package that lives under src/telebotkit and is packaged together with this project.

It provides helpers for:

• Telegram bot command parsing, routing, MarkdownV2 escaping, and reply payload generation (telebotkit.bot)
• Firestore client bootstrap, typed repositories, shared document access, and lease/lock helpers (telebotkit.firestore)
• Excel row parsing and typed JSON payload generation for Firestore imports (telebotkit.sheets)

Example Usage

from telebotkit.bot import Reply, Router
from telebotkit.firestore import DocumentStore, get_client
from telebotkit.sheets import build_typed_rows_payload_from_xlsx

See src/telebotkit/README.md for fuller API documentation and examples.