Metadata-Version: 2.4
Name: financechatbotkit
Version: 3.1.0
Summary: FinanceChatbot workflows (orchestrator) and Telegram/Firestore helpers (TeleBotKit)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27
Requires-Dist: python-dotenv<2,>=1
Provides-Extra: orchestrator
Requires-Dist: beautifulsoup4<5,>=4.12; extra == "orchestrator"
Requires-Dist: finance-datareader==0.9.110; extra == "orchestrator"
Requires-Dist: lxml>=5; extra == "orchestrator"
Provides-Extra: firestore
Requires-Dist: google-cloud-firestore>=2.16.0; extra == "firestore"
Requires-Dist: google-api-core>=2.15.0; extra == "firestore"
Requires-Dist: google-auth>=2.28.0; extra == "firestore"
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1.0; extra == "excel"
Provides-Extra: all
Requires-Dist: financechatbotkit[excel,firestore,orchestrator]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

## 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

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

Feature-level imports are also available:

```python
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:

```python
{
    "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:

```python
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`.

```python
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:

```python
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:

```python
from utilitykit import read_xlsx_sheet_as_json

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

Write row-oriented data:

```python
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:

```python
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

```python
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.
