Rename sqlite_history module to history (#17 )

* Rename sqlite_history module to history. Drop the sqlite-specific prefix now that history collection is the primary module name across SDK, tests, and docs. Co-authored-by: Cursor <cursoragent@cursor.com> * Address PR review feedback for history module rename. Add a sqlite_history compatibility shim, clarify docs naming, and align the module docstring with the collect-history SQLite scope. Co-authored-by: Cursor <cursoragent@cursor.com> * Remove sqlite_history compatibility shim. The rename to mt5cli.history is intentionally breaking; downstream code should update imports rather than rely on a deprecated re-export path. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>
Add incremental SQLite history SDK (#16 )
2026-06-09 02:40:25 +09:00 · 2026-06-09 01:28:22 +09:00 · 2026-06-08 22:54:53 +09:00 · 2026-06-07 23:47:32 +09:00 · 2026-05-29 01:22:59 +09:00 · 2026-05-25 02:12:28 +09:00
24 changed files with 6703 additions and 806 deletions
@@ -1,25 +1,22 @@
-# local-qa
+---
+name: local-qa
+description: Run local QA including formatting, linting, and testing for the repository. Use whenever any file has been updated.
+disable-model-invocation: false
+---

-Run local QA checks (format, lint, test) on the repository.
+# Local QA (format, lint, and test)

-## When to use
+Run the local QA script `scripts/qa.sh` in this skill.

-After making changes to repository files, run `scripts/qa.sh` to validate formatting, linting, and tests.
+## Procedure

-## Steps
-
-1. Execute `scripts/qa.sh` and capture the results.
-2. Report successes, failures, warnings, and any modified files.
-
-## If tools are missing
-
-Install them following this priority order:
-
-1. Project package managers (`uv`, `poetry`, npm scripts)
-2. System package managers (`brew`, `apt`)
-3. Language-specific installers (`pipx`, `pip`, `npm`, `go install`)
-
-## Constraints
-
- Only execute QA and tool-installation commands.
- If installation fails or requires unavailable privileges, report the attempt and exact failure, then stop.
+- Execute the script exactly as shown above when this skill is triggered.
+- Capture and summarize key output (success/failure, major warnings, and any files modified).
+- If the script fails due to missing tooling (`command not found`, missing executable, or equivalent), install the missing tool(s) and rerun `./scripts/qa.sh`.
+- Install tools using this order of preference:
+  1. Use the project's package manager when applicable (`uv`/`poetry` for Python, package manager scripts/dependencies for Node.js).
+  2. Use a system package manager (`brew` on macOS, `apt` on Debian/Ubuntu) when project-local install is not applicable.
+  3. Use language-specific installers as fallback (`pipx`/`pip`, `npm`, `go install`, etc.).
+- If multiple tools are missing, repeat install -> rerun until QA completes or you hit a blocker.
+- If installation fails or requires unavailable privileges, report what was attempted, the exact failure, and stop.
+- Do not run unrelated commands; only run commands needed for QA and missing-tool installation.
@@ -13,7 +13,14 @@ uv run pytest
 npx -y prettier --write './**/*.md'

 # GitHub Actions
-zizmor --fix=safe .github/workflows
-git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t actionlint
-git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t yamllint -d '{"extends": "relaxed", "rules": {"line-length": "disable"}}'
-checkov --framework=all --output=github_failed_only --directory=.
+case "${OSTYPE}" in
+  darwin* | linux* )
+    zizmor --fix=safe .github/workflows
+    git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t actionlint
+    git ls-files -z -- '.github/workflows/*.yml' | xargs -0 -t yamllint -d '{"extends": "relaxed", "rules": {"line-length": "disable"}}'
+    checkov --framework=all --output=github_failed_only --directory=.
+    ;;
+  * )
+    echo "GitHub Actions linting is only supported on Linux and macOS."
+    ;;
+esac
@@ -35,7 +35,7 @@ jobs:
      || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
    permissions:
      contents: read
-    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-lint-and-scan.yml@main  # zizmor: ignore[unpinned-uses]
+    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-lint-and-scan.yml@main   # zizmor: ignore[unpinned-uses]
    with:
      package-path: .
      runs-on: windows-latest
@@ -59,23 +59,9 @@ jobs:
    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-mkdocs-gh-deploy.yml@main  # zizmor: ignore[unpinned-uses]
    with:
      package-path: .
-      mkdocs-theme: material
      runs-on: ubuntu-slim
    secrets:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  python-package-release:
-    if: >
-      github.event_name == 'push'
-      || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
-    permissions:
-      contents: write
-      id-token: write
-    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-release-on-pypi-and-github.yml@main  # zizmor: ignore[unpinned-uses]
-    with:
-      package-path: .
-      create-releases: false
-    secrets:
-      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  dependabot-auto-merge:
    if: >
      github.event_name == 'pull_request' && github.actor == 'dependabot[bot]'
@@ -9,84 +9,34 @@ defaults:
    shell: bash -euo pipefail {0}
    working-directory: .
 jobs:
-  build:
+  build-and-release:
    permissions:
      contents: write
      id-token: write
    uses: dceoy/gh-actions-for-devops/.github/workflows/python-package-release-on-pypi-and-github.yml@main  # zizmor: ignore[unpinned-uses]
    with:
      package-path: .
-      create-releases: false
+      create-github-release: true
+      publish-to-pypi: false
    secrets:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  github-release:
-    name: Sign the Python 🐍 distribution 📦 with Sigstore and upload them to GitHub Release
-    if: >
-      startsWith(github.ref, 'refs/tags/')
-    needs:
-      - build
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write  # IMPORTANT: mandatory for making GitHub Releases
-      id-token: write  # IMPORTANT: mandatory for sigstore
-    steps:
-      - name: Download all the dists
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
-        with:
-          name: ${{ needs.build.outputs.distribution-artifact-name }}
-          path: dist/
-      - name: Validate the version-tag consistency
-        env:
-          TAG_NAME: ${{ github.ref_name }}
-          NEEDS_BUILD_OUTPUTS_PROJECT_NAME: ${{ needs.build.outputs.project-name }}
-        run: |
-          v="$( \
-            find dist -type f -name "${NEEDS_BUILD_OUTPUTS_PROJECT_NAME}-*" -exec basename {} \; \
-              | head -n 1 \
-              | cut -d '-' -f 2 \
-          )"
-          v="${v%.tar.gz}"
-          if [[ "${TAG_NAME}" != "${v}" ]] && [[ "${TAG_NAME}" != "v${v}" ]]; then
-            echo "The tag (${TAG_NAME}) is inconsistent with the version (${v})." && exit 1
-          fi
-      - name: Sign the dists with Sigstore
-        uses: sigstore/gh-action-sigstore-python@04cffa1d795717b140764e8b640de88853c92acc  # v3.3.0
-        with:
-          inputs: >-
-            ./dist/*.whl
-      - name: Create GitHub Release
-        env:
-          REPOSITORY: ${{ github.repository }}
-          GH_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}  # zizmor: ignore[secrets-outside-env] caller-provided secret
-        run: |
-          gh release create "${GITHUB_REF_NAME}" --repo "${REPOSITORY}" --generate-notes --verify-tag
-      - name: Upload artifact signatures to GitHub Release
-        env:
-          REPOSITORY: ${{ github.repository }}
-          GH_TOKEN: ${{ secrets.GH_TOKEN || secrets.GITHUB_TOKEN }}  # zizmor: ignore[secrets-outside-env] caller-provided secret
-        # Upload to GitHub Release using the `gh` CLI.
-        # `dist/` contains the built packages, and the
-        # sigstore-produced signatures and certificates.
-        run: |
-          gh release upload "${GITHUB_REF_NAME}" dist/** --repo "${REPOSITORY}"
  publish-to-pypi:
    name: Publish the Python 🐍 distribution 📦 to PyPI
    if: >
      startsWith(github.ref, 'refs/tags/')
    needs:
-      - build
-      - github-release
+      - build-and-release
    runs-on: ubuntu-latest
    environment:
      name: pypi
-      url: https://pypi.org/p/${{ needs.build.outputs.project-name }}
+      url: https://pypi.org/p/${{ needs.build-and-release.outputs.project-name }}
    permissions:
      id-token: write  # IMPORTANT: mandatory for trusted publishing
    steps:
      - name: Download all the dists
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
        with:
-          name: ${{ needs.build.outputs.distribution-artifact-name }}
+          name: ${{ needs.build-and-release.outputs.distribution-artifact-name }}
          path: dist/
      - name: Publish distribution 📦 to PyPI
        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
@@ -29,9 +29,11 @@ uv sync
 - `mt5cli/`: Main package directory
  - `__init__.py`: Package initialization and exports (`detect_format`, `export_dataframe`)
  - `cli.py`: CLI application with typer-based commands for data export
+  - `utils.py`: Constants, enums, parameter types, parsers, and export utilities
  - `__main__.py`: Entry point for `python -m mt5cli`
 - `tests/`: Comprehensive test suite (pytest-based)
-  - `test_cli.py`: Tests for CLI commands, parameter types, and export functions
+  - `test_cli.py`: Tests for CLI commands and collect-history behavior
+  - `test_utils.py`: Tests for utility constants, parameter types, parsers, and export functions
 - `docs/`: MkDocs documentation with API reference
  - `docs/index.md`: Main documentation
  - `docs/api/`: Auto-generated API documentation for all modules
@@ -50,21 +50,83 @@ python -m mt5cli -o account.csv account-info

 ## Commands

-| Command          | Description                        |
-| ---------------- | ---------------------------------- |
-| `rates-from`     | Export rates from a start date     |
-| `rates-from-pos` | Export rates from a start position |
-| `rates-range`    | Export rates for a date range      |
-| `ticks-from`     | Export ticks from a start date     |
-| `ticks-range`    | Export ticks for a date range      |
-| `account-info`   | Export account information         |
-| `terminal-info`  | Export terminal information        |
-| `symbols`        | Export symbol list                 |
-| `symbol-info`    | Export symbol details              |
-| `orders`         | Export active orders               |
-| `positions`      | Export open positions              |
-| `history-orders` | Export historical orders           |
-| `history-deals`  | Export historical deals            |
+| Command            | Description                                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `rates-from`       | Export rates from a start date                                                                               |
+| `rates-from-pos`   | Export rates from a start position                                                                           |
+| `rates-range`      | Export rates for a date range                                                                                |
+| `ticks-from`       | Export ticks from a start date                                                                               |
+| `ticks-range`      | Export ticks for a date range                                                                                |
+| `account-info`     | Export account information                                                                                   |
+| `terminal-info`    | Export terminal information                                                                                  |
+| `version`          | Export MetaTrader 5 version information                                                                      |
+| `last-error`       | Export the last error information                                                                            |
+| `symbols`          | Export symbol list                                                                                           |
+| `symbol-info`      | Export symbol details                                                                                        |
+| `symbol-info-tick` | Export the last tick for a symbol                                                                            |
+| `market-book`      | Export market depth (order book)                                                                             |
+| `orders`           | Export active orders                                                                                         |
+| `positions`        | Export open positions                                                                                        |
+| `history-orders`   | Export historical orders                                                                                     |
+| `history-deals`    | Export historical deals                                                                                      |
+| `order-check`      | Check funds sufficiency for a trade request                                                                  |
+| `order-send`       | Send a trade request to the trade server (`--yes` required)                                                  |
+| `collect-history`  | Bundle rates, ticks, history-orders, and history-deals for one or more symbols into a single SQLite database |
+
+Use `order-check` to validate a request payload before running `order-send --yes`.
+
+### `collect-history`
+
+Collect several historical datasets per symbol into one SQLite database in a single MT5 session. Pick datasets with repeatable `--dataset` (default: all four), choose conflict behavior with `--if-exists append|replace|fail` (default: `fail`), and optionally derive `cash_events` / `positions_reconstructed` views from `history_deals` via `--with-views`.
+
+```bash
+mt5cli -o history.db collect-history \
+  --symbol EURUSD --symbol GBPUSD \
+  --date-from 2024-01-01 --date-to 2024-02-01 \
+  --dataset rates --dataset history-deals \
+  --timeframe M1 --flags ALL --if-exists append --with-views
+```
+
+History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The `cash_events` view is derived from symbol-filtered `history_deals`, so account-level cash events with empty or non-matching symbols may be excluded. The `rates` table records the requested `timeframe` so appended runs at different timeframes remain distinguishable. The `positions_reconstructed` view aggregates trade deals by `position_id`, excludes positions without closing-side entries, and uses volume-weighted open/close prices; reversal deals (`DEAL_ENTRY_INOUT`) are reported via `volume_reversal` / `reversal_count` columns.
+
+### Incremental history SDK
+
+For automated pipelines, use the importable incremental API instead of re-fetching fixed date ranges:
+
+```python
+from pdmt5 import Mt5Config, Mt5DataClient
+from mt5cli import Dataset, update_history, update_history_with_config
+
+# Reuse an already-connected pdmt5 client (does not open/close MT5)
+client = Mt5DataClient(config=Mt5Config(login=12345))
+client.initialize_and_login_mt5()
+try:
+    update_history(
+        client=client,
+        output="history.db",
+        symbols=["EURUSD", "GBPUSD"],
+        datasets={Dataset.rates, Dataset.history_deals},
+        timeframes=["M1", "H1"],  # default: all fixed MT5 timeframes
+        lookback_hours=24,
+        create_rate_views=True,
+        with_views=True,
+        include_account_events=True,
+    )
+finally:
+    client.shutdown()
+
+# Standalone wrapper that opens and closes MT5 for you
+update_history_with_config(
+    output="history.db",
+    symbols=["EURUSD"],
+    config=Mt5Config(login=12345),
+)
+```
+
+- **`collect-history`**: explicit date-range export into SQLite.
+- **`update_history`**: incremental append based on existing SQLite `MAX(time)` per symbol (and timeframe for rates); account-level deals use a separate cursor when `include_account_events=True`.
+- **`rates` table**: normalized storage with `symbol` and `timeframe` columns.
+- **Rate compatibility views**: mt5cli manages all `rate_*` views. Naming is `rate_<symbol>__<timeframe>` when a symbol has one timeframe, otherwise `rate_<symbol>__<granularity>_<timeframe>` (for example `rate_EURUSD__M1_1`). Stale `rate_*` views are dropped and recreated when rates change for offline tools such as mteor optimize.

 ## Requirements

@@ -0,0 +1,131 @@
+# History Collection (SQLite)
+
+::: mt5cli.history
+
+## `collect-history` schema
+
+The `collect-history` command (and the matching `collect_history` SDK function) writes
+selected MT5 datasets into one SQLite database. Each dataset becomes a table; column
+names and types mirror the pdmt5 DataFrame schema for that export, with two additions:
+
+- `symbol` is prepended on every table.
+- `timeframe` is prepended on `rates` so appended runs at different bar sizes stay
+  distinguishable.
+
+SQLite does not declare foreign keys. Rows are linked logically by `symbol`, time
+windows, and (for deals) `position_id` / `order`. Duplicate rows are removed on
+append using dataset-specific keys (for example `ticket` on history tables, or
+`(symbol, timeframe, time)` on rates).
+
+Optional views are created when `--with-views` is set and the `history-deals` dataset
+was written.
+
+### Entity-relationship diagram
+
+Sample layout for a full collection with `--with-views`:
+
+```mermaid
+erDiagram
+    rates {
+        TEXT symbol "dedup key"
+        INTEGER timeframe "dedup key"
+        TEXT time "dedup key"
+        REAL open
+        REAL high
+        REAL low
+        REAL close
+        INTEGER tick_volume
+        INTEGER spread
+        INTEGER real_volume
+    }
+
+    ticks {
+        TEXT symbol "dedup key"
+        TEXT time "dedup key"
+        INTEGER time_msc "dedup key (preferred)"
+        REAL bid
+        REAL ask
+        REAL last
+        INTEGER volume
+        INTEGER flags
+        REAL volume_real
+    }
+
+    history_orders {
+        INTEGER ticket "dedup key"
+        TEXT symbol
+        TEXT time
+        INTEGER type
+        INTEGER state
+        REAL volume_initial
+        REAL price_open
+        REAL price_current
+        INTEGER magic
+    }
+
+    history_deals {
+        INTEGER ticket "dedup key"
+        INTEGER order
+        INTEGER position_id "groups position view"
+        TEXT symbol
+        TEXT time
+        INTEGER type "0/1 trade, else cash event"
+        INTEGER entry "0 IN, 1 OUT, 2 INOUT, 3 OUT_BY"
+        REAL volume
+        REAL price
+        REAL profit
+        REAL commission
+        REAL swap
+        REAL fee
+    }
+
+    cash_events {
+        INTEGER ticket
+        TEXT symbol
+        TEXT time
+        INTEGER type
+        REAL profit
+    }
+
+    positions_reconstructed {
+        INTEGER position_id
+        TEXT symbol
+        TEXT open_time
+        TEXT close_time
+        INTEGER direction
+        REAL volume_open
+        REAL volume_close
+        REAL volume_reversal
+        REAL open_price
+        REAL close_price
+        REAL total_profit
+        INTEGER reversal_count
+        INTEGER deals_count
+    }
+
+    rates ||--o{ history_deals : "symbol (logical)"
+    ticks ||--o{ history_deals : "symbol (logical)"
+    history_orders ||--o{ history_deals : "order ~ ticket (logical)"
+    history_deals ||--|| cash_events : "VIEW: type NOT IN (0,1)"
+    history_deals ||--o{ positions_reconstructed : "VIEW: GROUP BY position_id"
+```
+
+### Tables and views
+
+| Object                    | Kind  | Source               | Notes                                                                                       |
+| ------------------------- | ----- | -------------------- | ------------------------------------------------------------------------------------------- |
+| `rates`                   | table | `copy_rates_range`   | Indexed on `(symbol, timeframe, time)` when columns exist.                                  |
+| `ticks`                   | table | `copy_ticks_range`   | Indexed on `(symbol, time)` when columns exist.                                             |
+| `history_orders`          | table | `history_orders_get` | Fetched per `--symbol`, then concatenated.                                                  |
+| `history_deals`           | table | `history_deals_get`  | Fetched per `--symbol`, then concatenated. Indexed on `(position_id, symbol)` when present. |
+| `cash_events`             | view  | `history_deals`      | Non-trade deal types (deposits, balance ops, etc.). Requires `type` column.                 |
+| `positions_reconstructed` | view  | `history_deals`      | One row per closed `position_id`; volume-weighted prices and reversal stats.                |
+
+Column sets can vary with terminal and pdmt5 version. Views are skipped with a warning
+when required columns are missing.
+
+### Incremental collection
+
+The `update_history` SDK path uses the same base tables and optional
+`cash_events` / `positions_reconstructed` views. It additionally maintains
+`rate_<symbol>__<timeframe>` compatibility views when `create_rate_views=True`.
@@ -10,12 +10,26 @@ The mt5cli package consists of the following modules:

 Command-line interface module providing typer-based commands for exporting MetaTrader 5 data to CSV, JSON, Parquet, and SQLite3 formats.

+### [Utils](utils.md)
+
+Utility module providing constants, enums, Click parameter types, and helper functions for parsing and exporting data.
+
+### [SDK](sdk.md)
+
+Programmatic SDK for read-only MetaTrader 5 data collection. Returns pandas DataFrames and provides `collect_history` for SQLite bulk collection.
+
+### [History Collection (SQLite)](history.md)
+
+SQLite storage helpers for the `collect-history` command schema, incremental updates, deduplication, indexes, and optional views.
+
 ## Architecture Overview

 The package follows a simple architecture built on top of pdmt5:

-1. **CLI Layer** (`cli.py`): Typer application with subcommands for each data type, custom Click parameter types for datetime/timeframe/tick flags parsing, and format detection/export utilities.
-2. **Data Layer** (via `pdmt5`): Uses `Mt5DataClient` and `Mt5Config` from the pdmt5 package for all MetaTrader 5 data access.
+1. **CLI Layer** (`cli.py`): Typer application with subcommands that delegate to the SDK and export results.
+2. **SDK Layer** (`sdk.py`): Read-only data access functions, `Mt5CliClient`, and `collect_history` orchestration.
+3. **Utils Layer** (`utils.py`): Constants, enums, custom Click parameter types, parsing helpers, and format detection/export utilities.
+4. **Data Layer** (via `pdmt5`): Uses `Mt5DataClient` and `Mt5Config` from the pdmt5 package for all MetaTrader 5 data access.

 ## Usage Guidelines

@@ -47,15 +61,38 @@ mt5cli -o data.db --table symbols symbols --group "*USD*"
 ## Python API

 ```python
-from mt5cli import detect_format, export_dataframe
-import pandas as pd
+from datetime import UTC, datetime
+from pathlib import Path
+
+from mt5cli import (
+    Mt5CliClient,
+    collect_history,
+    copy_rates_range,
+    detect_format,
+    export_dataframe,
+)
+
+# Fetch rates programmatically
+rates = copy_rates_range(
+    "EURUSD",
+    timeframe="H1",
+    date_from="2024-01-01",
+    date_to="2024-02-01",
+)

 # Detect output format from file extension
 fmt = detect_format(Path("output.parquet"))  # Returns "parquet"

 # Export a DataFrame
-df = pd.DataFrame({"symbol": ["EURUSD"], "bid": [1.1234]})
-export_dataframe(df, Path("output.csv"), "csv")
+export_dataframe(rates, Path("output.csv"), "csv")
+
+# Collect history into SQLite
+collect_history(
+    Path("history.db"),
+    symbols=["EURUSD"],
+    date_from=datetime(2024, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+)
 ```

 ## Examples
@@ -0,0 +1,3 @@
+# SDK Module
+
+::: mt5cli.sdk
@@ -0,0 +1,3 @@
+# Utils Module
+
+::: mt5cli.utils
@@ -20,6 +20,44 @@ mt5cli is a CLI application that exports MetaTrader 5 trading data to multiple f
 pip install mt5cli
 ```

+## Programmatic usage / SDK usage
+
+mt5cli can be used as a small Python SDK for read-only MetaTrader 5 data collection. SDK functions return pandas DataFrames without writing files. Use `export_dataframe` when you need to persist results.
+
+```python
+from datetime import UTC, datetime
+from pathlib import Path
+
+from mt5cli import Mt5CliClient, collect_history, copy_rates_range, export_dataframe
+
+# One-off fetch with module-level helpers
+rates = copy_rates_range(
+    "EURUSD",
+    timeframe="H1",
+    date_from="2024-01-01",
+    date_to="2024-02-01",
+)
+export_dataframe(rates, Path("rates.csv"), "csv")
+
+# Reuse one MT5 connection for multiple calls
+with Mt5CliClient(login=12345, password="secret", server="Broker-Demo") as client:
+    account = client.account_info()
+    positions = client.positions()
+
+# Bulk SQLite collection (same behavior as the collect-history CLI command)
+collect_history(
+    Path("history.db"),
+    symbols=["EURUSD", "GBPUSD"],
+    date_from=datetime(2024, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+    timeframe="M1",
+    flags="ALL",
+    with_views=True,
+)
+```
+
+Timeframes, tick flags, and ISO 8601 date strings are accepted wherever noted in the SDK API.
+
 ## Quick Start

 ```bash
@@ -61,21 +99,60 @@ mt5cli --login 12345 --password mypass --server MyBroker-Demo \

 ### Information

-| Command         | Description                 |
-| --------------- | --------------------------- |
-| `account-info`  | Export account information  |
-| `terminal-info` | Export terminal information |
-| `symbols`       | Export symbol list          |
-| `symbol-info`   | Export symbol details       |
+| Command            | Description                             |
+| ------------------ | --------------------------------------- |
+| `account-info`     | Export account information              |
+| `terminal-info`    | Export terminal information             |
+| `version`          | Export MetaTrader 5 version information |
+| `last-error`       | Export the last error information       |
+| `symbols`          | Export symbol list                      |
+| `symbol-info`      | Export symbol details                   |
+| `symbol-info-tick` | Export the last tick for a symbol       |
+| `market-book`      | Export market depth (order book)        |

 ### Trading

-| Command          | Description              |
-| ---------------- | ------------------------ |
-| `orders`         | Export active orders     |
-| `positions`      | Export open positions    |
-| `history-orders` | Export historical orders |
-| `history-deals`  | Export historical deals  |
+| Command          | Description                                                 |
+| ---------------- | ----------------------------------------------------------- |
+| `orders`         | Export active orders                                        |
+| `positions`      | Export open positions                                       |
+| `history-orders` | Export historical orders                                    |
+| `history-deals`  | Export historical deals                                     |
+| `order-check`    | Check funds sufficiency for a trade request                 |
+| `order-send`     | Send a trade request to the trade server (`--yes` required) |
+
+Use `order-check` to validate a request payload before running `order-send --yes`.
+
+### Bulk Collection
+
+| Command           | Description                                                                                                                                        |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `collect-history` | Collect rates, ticks, history-orders, and history-deals for one or more symbols into a single SQLite database (optional cash-event/position views) |
+
+```bash
+mt5cli -o history.db collect-history \
+  --symbol EURUSD --symbol GBPUSD \
+  --date-from 2024-01-01 --date-to 2024-02-01 \
+  --dataset rates --dataset history-deals \
+  --timeframe M1 --flags ALL --if-exists append --with-views
+```
+
+`collect-history` options:
+
+| Option         | Default    | Description                                                                                   |
+| -------------- | ---------- | --------------------------------------------------------------------------------------------- |
+| `--symbol/-s`  | _required_ | Symbol to collect (repeat for multiple).                                                      |
+| `--date-from`  | _required_ | Start date in ISO 8601.                                                                       |
+| `--date-to`    | _required_ | End date in ISO 8601.                                                                         |
+| `--dataset`    | all four   | Repeatable: `rates`, `ticks`, `history-orders`, `history-deals`.                              |
+| `--timeframe`  | `M1`       | Rates timeframe; recorded in a `timeframe` column on the `rates` table.                       |
+| `--flags`      | `ALL`      | Tick copy flags forwarded to `copy_ticks_range`.                                              |
+| `--if-exists`  | `fail`     | `append`, `replace`, or `fail` when a target table already exists.                            |
+| `--with-views` | off        | Add `cash_events` and `positions_reconstructed` views (requires the `history-deals` dataset). |
+
+History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The `cash_events` view is derived from symbol-filtered `history_deals`, so account-level cash events with empty or non-matching symbols may be excluded. The `positions_reconstructed` view excludes positions with no closing deal, uses volume-weighted open/close prices, and reports reversal deals (`DEAL_ENTRY_INOUT`) via `volume_reversal` / `reversal_count`.
+
+See the [History schema diagram](api/history.md#entity-relationship-diagram) for a sample ER layout of the resulting database.

 ## Global Options

@@ -101,7 +178,9 @@ mt5cli --login 12345 --password mypass --server MyBroker-Demo \

 Browse the API documentation for detailed module information:

- [CLI Module](api/cli.md) - CLI application with export commands and utility functions
+- [CLI Module](api/cli.md) - CLI application with export commands
+- [SDK Module](api/sdk.md) - Programmatic read-only data collection API
+- [Utils Module](api/utils.md) - Constants, parameter types, parsers, and export utilities

 ## Development

@@ -24,6 +24,7 @@ theme:
  features:
    - content.code.annotate
    - content.code.copy
+    - content.code.mermaid
    - navigation.indexes
    - navigation.sections
    - navigation.tabs
@@ -56,6 +57,9 @@ nav:
  - API Reference:
      - Overview: api/index.md
      - CLI: api/cli.md
+      - SDK: api/sdk.md
+      - History Collection (SQLite): api/history.md
+      - Utils: api/utils.md

 markdown_extensions:
  - admonition
@@ -1,12 +1,62 @@
-"""mt5cli: Command-line tool for MetaTrader 5."""
+"""mt5cli: Command-line tool and SDK for MetaTrader 5."""

 from importlib.metadata import version

-from .cli import detect_format, export_dataframe
+from .sdk import (
+    Mt5CliClient,
+    account_info,
+    build_config,
+    collect_history,
+    copy_rates_from,
+    copy_rates_from_pos,
+    copy_rates_range,
+    copy_ticks_from,
+    copy_ticks_range,
+    history_deals,
+    history_orders,
+    last_error,
+    market_book,
+    orders,
+    positions,
+    symbol_info,
+    symbol_info_tick,
+    symbols,
+    terminal_info,
+    update_history,
+    update_history_with_config,
+)
+from .sdk import (
+    version as mt5_version,
+)
+from .utils import Dataset, IfExists, detect_format, export_dataframe

 __version__ = version(__package__) if __package__ else None

 __all__ = [
+    "Dataset",
+    "IfExists",
+    "Mt5CliClient",
+    "account_info",
+    "build_config",
+    "collect_history",
+    "copy_rates_from",
+    "copy_rates_from_pos",
+    "copy_rates_range",
+    "copy_ticks_from",
+    "copy_ticks_range",
    "detect_format",
    "export_dataframe",
+    "history_deals",
+    "history_orders",
+    "last_error",
+    "market_book",
+    "mt5_version",
+    "orders",
+    "positions",
+    "symbol_info",
+    "symbol_info_tick",
+    "symbols",
+    "terminal_info",
+    "update_history",
+    "update_history_with_config",
 ]
@@ -3,16 +3,27 @@
 from __future__ import annotations

 import logging
-import sqlite3
 from dataclasses import dataclass
-from datetime import UTC, datetime
-from enum import StrEnum
+from datetime import datetime  # noqa: TC003
 from pathlib import Path  # noqa: TC003
-from typing import TYPE_CHECKING, Annotated, cast
+from typing import TYPE_CHECKING, Annotated, Any, cast

-import click
 import typer
-from pdmt5 import Mt5Config, Mt5DataClient
+from pdmt5 import Mt5Config
+
+from . import sdk
+from .utils import (
+    DATETIME_TYPE,
+    REQUEST_TYPE,
+    TICK_FLAGS_TYPE,
+    TIMEFRAME_TYPE,
+    Dataset,
+    IfExists,
+    LogLevel,
+    OutputFormat,
+    detect_format,
+    export_dataframe,
+)

 if TYPE_CHECKING:
    from collections.abc import Callable
@@ -21,169 +32,6 @@ if TYPE_CHECKING:

 logger = logging.getLogger(__name__)

-# ---------------------------------------------------------------------------
-# Constants
-# ---------------------------------------------------------------------------
-
-TIMEFRAME_MAP: dict[str, int] = {
-    "M1": 1,
-    "M2": 2,
-    "M3": 3,
-    "M4": 4,
-    "M5": 5,
-    "M6": 6,
-    "M10": 10,
-    "M12": 12,
-    "M15": 15,
-    "M20": 20,
-    "M30": 30,
-    "H1": 16385,
-    "H2": 16386,
-    "H3": 16387,
-    "H4": 16388,
-    "H6": 16390,
-    "H8": 16392,
-    "H12": 16396,
-    "D1": 16408,
-    "W1": 32769,
-    "MN1": 49153,
-}
-
-TICK_FLAG_MAP: dict[str, int] = {
-    "ALL": 1,
-    "INFO": 2,
-    "TRADE": 4,
-}
-
-_FORMAT_EXTENSIONS: dict[str, str] = {
-    ".csv": "csv",
-    ".json": "json",
-    ".parquet": "parquet",
-    ".pq": "parquet",
-    ".db": "sqlite3",
-    ".sqlite": "sqlite3",
-    ".sqlite3": "sqlite3",
-}
-
-# ---------------------------------------------------------------------------
-# Enums
-# ---------------------------------------------------------------------------
-
-
-class OutputFormat(StrEnum):
-    """Supported output file formats."""
-
-    csv = "csv"
-    json = "json"
-    parquet = "parquet"
-    sqlite3 = "sqlite3"
-
-
-class LogLevel(StrEnum):
-    """Logging verbosity levels."""
-
-    DEBUG = "DEBUG"
-    INFO = "INFO"
-    WARNING = "WARNING"
-    ERROR = "ERROR"
-
-
-# ---------------------------------------------------------------------------
-# Click parameter types
-# ---------------------------------------------------------------------------
-
-
-class _DateTimeType(click.ParamType):
-    """Click parameter type for ISO 8601 datetime strings."""
-
-    name = "DATETIME"
-
-    def convert(
-        self,
-        value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
-    ) -> datetime:
-        """Convert a string value to a timezone-aware datetime.
-
-        Args:
-            value: Raw value from the command line.
-            param: Click parameter instance.
-            ctx: Click context.
-
-        Returns:
-            Parsed datetime.
-        """
-        if isinstance(value, datetime):
-            return value
-        try:
-            return parse_datetime(str(value))
-        except ValueError as exc:
-            self.fail(str(exc), param, ctx)
-
-
-class _TimeframeType(click.ParamType):
-    """Click parameter type for MT5 timeframe values."""
-
-    name = "TIMEFRAME"
-
-    def convert(
-        self,
-        value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
-    ) -> int:
-        """Convert a string or integer value to a timeframe integer.
-
-        Args:
-            value: Raw value from the command line.
-            param: Click parameter instance.
-            ctx: Click context.
-
-        Returns:
-            Integer timeframe value.
-        """
-        if isinstance(value, int):
-            return value
-        try:
-            return parse_timeframe(str(value))
-        except ValueError as exc:
-            self.fail(str(exc), param, ctx)
-
-
-class _TickFlagsType(click.ParamType):
-    """Click parameter type for MT5 tick copy flags."""
-
-    name = "FLAGS"
-
-    def convert(
-        self,
-        value: object,
-        param: click.Parameter | None,
-        ctx: click.Context | None,
-    ) -> int:
-        """Convert a string or integer value to a tick flags integer.
-
-        Args:
-            value: Raw value from the command line.
-            param: Click parameter instance.
-            ctx: Click context.
-
-        Returns:
-            Integer tick flag value.
-        """
-        if isinstance(value, int):
-            return value
-        try:
-            return parse_tick_flags(str(value))
-        except ValueError as exc:
-            self.fail(str(exc), param, ctx)
-
-
-DATETIME_TYPE = _DateTimeType()
-TIMEFRAME_TYPE = _TimeframeType()
-TICK_FLAGS_TYPE = _TickFlagsType()
-
 # ---------------------------------------------------------------------------
 # Export context
 # ---------------------------------------------------------------------------
@@ -199,149 +47,6 @@ class _ExportContext:
    config: Mt5Config


-# ---------------------------------------------------------------------------
-# Public utility functions
-# ---------------------------------------------------------------------------
-
-
-def detect_format(
-    output_path: Path,
-    explicit_format: str | None = None,
-) -> str:
-    """Detect the output format from a file extension or explicit format string.
-
-    Args:
-        output_path: Path to the output file.
-        explicit_format: Explicitly specified format, if any.
-
-    Returns:
-        The detected format string.
-
-    Raises:
-        ValueError: If the format cannot be determined.
-    """
-    if explicit_format is not None:
-        return explicit_format
-    suffix = output_path.suffix.lower()
-    if suffix in _FORMAT_EXTENSIONS:
-        return _FORMAT_EXTENSIONS[suffix]
-    msg = (
-        f"Cannot detect format from extension '{suffix}'."
-        " Use --format to specify the output format."
-    )
-    raise ValueError(msg)
-
-
-def export_dataframe(
-    df: pd.DataFrame,
-    output_path: Path,
-    output_format: str,
-    table_name: str = "data",
-) -> None:
-    """Export a pandas DataFrame to the specified file format.
-
-    Args:
-        df: DataFrame to export.
-        output_path: Path to the output file.
-        output_format: Output format (csv, json, parquet, or sqlite3).
-        table_name: Table name for SQLite3 output.
-
-    Raises:
-        ValueError: If the output format is not supported.
-    """
-    if output_format == "csv":
-        df.to_csv(output_path, index=False)
-    elif output_format == "json":
-        df.to_json(
-            output_path,
-            orient="records",
-            date_format="iso",
-            indent=2,
-        )
-    elif output_format == "parquet":
-        df.to_parquet(output_path, index=False)
-    elif output_format == "sqlite3":
-        with sqlite3.connect(output_path) as conn:
-            df.to_sql(  # type: ignore[reportUnknownMemberType]
-                table_name,
-                conn,
-                if_exists="replace",
-                index=False,
-            )
-    else:
-        msg = f"Unsupported output format: {output_format}"
-        raise ValueError(msg)
-
-
-def parse_datetime(value: str) -> datetime:
-    """Parse an ISO 8601 datetime string to a timezone-aware datetime.
-
-    Args:
-        value: ISO 8601 datetime string (e.g., '2024-01-01' or
-            '2024-01-01T12:00:00+00:00').
-
-    Returns:
-        Parsed datetime with UTC timezone if no timezone is specified.
-
-    Raises:
-        ValueError: If the string cannot be parsed.
-    """
-    try:
-        dt = datetime.fromisoformat(value)
-    except ValueError:
-        msg = f"Invalid datetime format: '{value}'. Use ISO 8601 format."
-        raise ValueError(msg) from None
-    if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=UTC)
-    return dt
-
-
-def parse_timeframe(value: str) -> int:
-    """Parse a timeframe string or integer value.
-
-    Args:
-        value: Timeframe name (e.g., 'M1', 'H1', 'D1') or integer value.
-
-    Returns:
-        Integer timeframe value.
-
-    Raises:
-        ValueError: If the timeframe is invalid.
-    """
-    upper = value.upper()
-    if upper in TIMEFRAME_MAP:
-        return TIMEFRAME_MAP[upper]
-    try:
-        return int(value)
-    except ValueError:
-        valid = ", ".join(TIMEFRAME_MAP)
-        msg = f"Invalid timeframe: '{value}'. Use one of: {valid}, or an integer."
-        raise ValueError(msg) from None
-
-
-def parse_tick_flags(value: str) -> int:
-    """Parse tick flags string or integer value.
-
-    Args:
-        value: Tick flag name (ALL, INFO, TRADE) or integer value.
-
-    Returns:
-        Integer tick flag value.
-
-    Raises:
-        ValueError: If the flag is invalid.
-    """
-    upper = value.upper()
-    if upper in TICK_FLAG_MAP:
-        return TICK_FLAG_MAP[upper]
-    try:
-        return int(value)
-    except ValueError:
-        valid = ", ".join(TICK_FLAG_MAP)
-        msg = f"Invalid tick flags: '{value}'. Use one of: {valid}, or an integer."
-        raise ValueError(msg) from None
-
-
 # ---------------------------------------------------------------------------
 # Typer application
 # ---------------------------------------------------------------------------
@@ -351,6 +56,10 @@ app = typer.Typer(
    help="Export MetaTrader5 data to CSV, JSON, Parquet, or SQLite3.",
 )

+_REQUEST_OPTION_HELP = (
+    "Order request as a JSON object string, or '@path' to load JSON from a file."
+)
+

 def _get_export_context(ctx: typer.Context) -> _ExportContext:
    return cast("_ExportContext", ctx.obj)
@@ -358,34 +67,33 @@ def _get_export_context(ctx: typer.Context) -> _ExportContext:

 def _execute_export(
    ctx: typer.Context,
-    fetch_fn: Callable[[Mt5DataClient], pd.DataFrame],
+    fetch_fn: Callable[[], pd.DataFrame],
 ) -> None:
-    """Execute the common connect-fetch-export-shutdown workflow.
+    """Execute the common fetch-export workflow.

    Args:
        ctx: Typer context carrying shared options.
-        fetch_fn: Callable that receives a connected client and returns a
-            DataFrame.
+        fetch_fn: Callable that returns a DataFrame via the SDK layer.
    """
    export_ctx = _get_export_context(ctx)
-    client = Mt5DataClient(config=export_ctx.config)
-    client.initialize_and_login_mt5()
-    try:
-        df = fetch_fn(client)
-        export_dataframe(
-            df=df,
-            output_path=export_ctx.output,
-            output_format=export_ctx.output_format,
-            table_name=export_ctx.table,
-        )
-        logger.info(
-            "Exported %d rows to %s (%s)",
-            len(df),
-            export_ctx.output,
-            export_ctx.output_format,
-        )
-    finally:
-        client.shutdown()
+    df = fetch_fn()
+    export_dataframe(
+        df=df,
+        output_path=export_ctx.output,
+        output_format=export_ctx.output_format,
+        table_name=export_ctx.table,
+    )
+    logger.info(
+        "Exported %d rows to %s (%s)",
+        len(df),
+        export_ctx.output,
+        export_ctx.output_format,
+    )
+
+
+def _sdk_client(ctx: typer.Context) -> sdk.Mt5CliClient:
+    export_ctx = _get_export_context(ctx)
+    return sdk.Mt5CliClient(config=export_ctx.config)


@app.callback()
@@ -485,14 +193,10 @@ def rates_from(
    count: Annotated[int, typer.Option(help="Number of records.")],
 ) -> None:
    """Export rates from a start date."""
+    client = _sdk_client(ctx)
    _execute_export(
        ctx,
-        lambda c: c.copy_rates_from_as_df(
-            symbol=symbol,
-            timeframe=timeframe,
-            date_from=date_from,
-            count=count,
-        ),
+        lambda: client.copy_rates_from(symbol, timeframe, date_from, count),
    )


@@ -511,14 +215,10 @@ def rates_from_pos(
    count: Annotated[int, typer.Option(help="Number of records.")],
 ) -> None:
    """Export rates from a start position."""
+    client = _sdk_client(ctx)
    _execute_export(
        ctx,
-        lambda c: c.copy_rates_from_pos_as_df(
-            symbol=symbol,
-            timeframe=timeframe,
-            start_pos=start_pos,
-            count=count,
-        ),
+        lambda: client.copy_rates_from_pos(symbol, timeframe, start_pos, count),
    )


@@ -543,14 +243,10 @@ def rates_range(
    ],
 ) -> None:
    """Export rates for a date range."""
+    client = _sdk_client(ctx)
    _execute_export(
        ctx,
-        lambda c: c.copy_rates_range_as_df(
-            symbol=symbol,
-            timeframe=timeframe,
-            date_from=date_from,
-            date_to=date_to,
-        ),
+        lambda: client.copy_rates_range(symbol, timeframe, date_from, date_to),
    )


@@ -572,14 +268,10 @@ def ticks_from(
    ],
 ) -> None:
    """Export ticks from a start date."""
+    client = _sdk_client(ctx)
    _execute_export(
        ctx,
-        lambda c: c.copy_ticks_from_as_df(
-            symbol=symbol,
-            date_from=date_from,
-            count=count,
-            flags=flags,
-        ),
+        lambda: client.copy_ticks_from(symbol, date_from, count, flags),
    )


@@ -601,27 +293,23 @@ def ticks_range(
    ],
 ) -> None:
    """Export ticks for a date range."""
+    client = _sdk_client(ctx)
    _execute_export(
        ctx,
-        lambda c: c.copy_ticks_range_as_df(
-            symbol=symbol,
-            date_from=date_from,
-            date_to=date_to,
-            flags=flags,
-        ),
+        lambda: client.copy_ticks_range(symbol, date_from, date_to, flags),
    )


@app.command()
 def account_info(ctx: typer.Context) -> None:
    """Export account information."""
-    _execute_export(ctx, lambda c: c.account_info_as_df())
+    _execute_export(ctx, _sdk_client(ctx).account_info)


@app.command()
 def terminal_info(ctx: typer.Context) -> None:
    """Export terminal information."""
-    _execute_export(ctx, lambda c: c.terminal_info_as_df())
+    _execute_export(ctx, _sdk_client(ctx).terminal_info)


@app.command()
@@ -633,10 +321,8 @@ def symbols(
    ] = None,
 ) -> None:
    """Export symbol list."""
-    _execute_export(
-        ctx,
-        lambda c: c.symbols_get_as_df(group=group),
-    )
+    client = _sdk_client(ctx)
+    _execute_export(ctx, lambda: client.symbols(group=group))


@app.command()
@@ -645,10 +331,8 @@ def symbol_info(
    symbol: Annotated[str, typer.Option(help="Symbol name.")],
 ) -> None:
    """Export symbol details."""
-    _execute_export(
-        ctx,
-        lambda c: c.symbol_info_as_df(symbol=symbol),
-    )
+    client = _sdk_client(ctx)
+    _execute_export(ctx, lambda: client.symbol_info(symbol))


@app.command()
@@ -659,13 +343,10 @@ def orders(
    ticket: Annotated[int | None, typer.Option(help="Ticket filter.")] = None,
 ) -> None:
    """Export active orders."""
+    client = _sdk_client(ctx)
    _execute_export(
        ctx,
-        lambda c: c.orders_get_as_df(
-            symbol=symbol,
-            group=group,
-            ticket=ticket,
-        ),
+        lambda: client.orders(symbol=symbol, group=group, ticket=ticket),
    )


@@ -677,13 +358,10 @@ def positions(
    ticket: Annotated[int | None, typer.Option(help="Ticket filter.")] = None,
 ) -> None:
    """Export open positions."""
+    client = _sdk_client(ctx)
    _execute_export(
        ctx,
-        lambda c: c.positions_get_as_df(
-            symbol=symbol,
-            group=group,
-            ticket=ticket,
-        ),
+        lambda: client.positions(symbol=symbol, group=group, ticket=ticket),
    )


@@ -704,9 +382,10 @@ def history_orders(
    position: Annotated[int | None, typer.Option(help="Position ticket.")] = None,
 ) -> None:
    """Export historical orders."""
+    client = _sdk_client(ctx)
    _execute_export(
        ctx,
-        lambda c: c.history_orders_get_as_df(
+        lambda: client.history_orders(
            date_from=date_from,
            date_to=date_to,
            group=group,
@@ -734,9 +413,10 @@ def history_deals(
    position: Annotated[int | None, typer.Option(help="Position ticket.")] = None,
 ) -> None:
    """Export historical deals."""
+    client = _sdk_client(ctx)
    _execute_export(
        ctx,
-        lambda c: c.history_deals_get_as_df(
+        lambda: client.history_deals(
            date_from=date_from,
            date_to=date_to,
            group=group,
@@ -747,6 +427,186 @@ def history_deals(
    )


+@app.command()
+def version(ctx: typer.Context) -> None:
+    """Export MetaTrader5 version information."""
+    _execute_export(ctx, _sdk_client(ctx).version)
+
+
+@app.command()
+def last_error(ctx: typer.Context) -> None:
+    """Export the last error information."""
+    _execute_export(ctx, _sdk_client(ctx).last_error)
+
+
+@app.command()
+def symbol_info_tick(
+    ctx: typer.Context,
+    symbol: Annotated[str, typer.Option(help="Symbol name.")],
+) -> None:
+    """Export the last tick for a symbol."""
+    client = _sdk_client(ctx)
+    _execute_export(ctx, lambda: client.symbol_info_tick(symbol))
+
+
+@app.command()
+def market_book(
+    ctx: typer.Context,
+    symbol: Annotated[str, typer.Option(help="Symbol name.")],
+) -> None:
+    """Export market depth (order book) for a symbol."""
+    client = _sdk_client(ctx)
+    _execute_export(ctx, lambda: client.market_book(symbol))
+
+
+@app.command()
+def order_check(
+    ctx: typer.Context,
+    request: Annotated[
+        dict[str, Any],
+        typer.Option(click_type=REQUEST_TYPE, help=_REQUEST_OPTION_HELP),
+    ],
+) -> None:
+    """Check funds sufficiency for a trading operation."""
+    export_ctx = _get_export_context(ctx)
+
+    def _fetch() -> pd.DataFrame:
+        return sdk._run_with_client(  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
+            export_ctx.config,
+            lambda c: c.order_check_as_df(request=request),
+        )
+
+    _execute_export(ctx, _fetch)
+
+
+@app.command()
+def order_send(
+    ctx: typer.Context,
+    request: Annotated[
+        dict[str, Any],
+        typer.Option(click_type=REQUEST_TYPE, help=_REQUEST_OPTION_HELP),
+    ],
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", help="Confirm the live trade request."),
+    ] = False,
+) -> None:
+    """Send a trading operation request to the trade server.
+
+    Raises:
+        typer.BadParameter: If --yes is not provided.
+    """
+    if not yes:
+        msg = "Pass --yes to send a live trade request."
+        raise typer.BadParameter(msg, param_hint="--yes")
+    export_ctx = _get_export_context(ctx)
+
+    def _fetch() -> pd.DataFrame:
+        return sdk._run_with_client(  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
+            export_ctx.config,
+            lambda c: c.order_send_as_df(request=request),
+        )
+
+    _execute_export(ctx, _fetch)
+
+
+@app.command()
+def collect_history(
+    ctx: typer.Context,
+    symbol: Annotated[
+        list[str],
+        typer.Option(
+            "--symbol",
+            "-s",
+            help="Symbol to collect (repeat for multiple symbols).",
+        ),
+    ],
+    date_from: Annotated[
+        datetime,
+        typer.Option(click_type=DATETIME_TYPE, help="Start date."),
+    ],
+    date_to: Annotated[
+        datetime,
+        typer.Option(click_type=DATETIME_TYPE, help="End date."),
+    ],
+    dataset: Annotated[
+        list[Dataset] | None,
+        typer.Option(
+            "--dataset",
+            help=(
+                "Dataset to include (repeat for multiple)."
+                " Defaults to all: rates, ticks, history-orders, history-deals."
+            ),
+        ),
+    ] = None,
+    timeframe: Annotated[
+        int,
+        typer.Option(
+            click_type=TIMEFRAME_TYPE,
+            help="Rates timeframe (e.g., M1, H1, D1).",
+        ),
+    ] = 1,
+    flags: Annotated[
+        int,
+        typer.Option(
+            click_type=TICK_FLAGS_TYPE,
+            help="Tick copy flags (ALL, INFO, TRADE, or integer).",
+        ),
+    ] = 1,
+    if_exists: Annotated[
+        IfExists,
+        typer.Option(
+            "--if-exists",
+            help="Behavior when a target table already exists.",
+        ),
+    ] = IfExists.FAIL,
+    with_views: Annotated[
+        bool,
+        typer.Option(
+            "--with-views",
+            help=(
+                "Add cash_events and positions_reconstructed SQLite views"
+                " derived from history_deals."
+            ),
+        ),
+    ] = False,
+) -> None:
+    """Collect historical datasets into a single SQLite database.
+
+    Tables written depend on ``--dataset``: ``rates``, ``ticks``,
+    ``history_orders``, ``history_deals``. History datasets are fetched per
+    symbol and concatenated. Rates rows carry the requested ``timeframe`` so
+    appended runs at different timeframes remain distinguishable.
+
+    With ``--with-views`` (requires the ``history-deals`` dataset), optional
+    views ``cash_events`` and ``positions_reconstructed`` are derived from
+    ``history_deals`` when the required columns are present.
+
+    Raises:
+        typer.BadParameter: If the output format is not SQLite3.
+    """
+    export_ctx = _get_export_context(ctx)
+    if export_ctx.output_format != "sqlite3":
+        msg = (
+            "collect-history requires SQLite3 output."
+            " Use a .db/.sqlite/.sqlite3 extension or --format sqlite3."
+        )
+        raise typer.BadParameter(msg)
+    datasets = set(dataset) if dataset else set(Dataset)
+    sdk.collect_history(
+        output=export_ctx.output,
+        symbols=symbol,
+        date_from=date_from,
+        date_to=date_to,
+        datasets=datasets,
+        timeframe=timeframe,
+        flags=flags,
+        if_exists=if_exists,
+        with_views=with_views,
+        config=export_ctx.config,
+    )
+
+
 def main() -> None:
    """Run the mt5cli CLI."""
    app()
@@ -0,0 +1,917 @@
+"""Programmatic SDK for MetaTrader 5 data collection."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import TYPE_CHECKING, Self, TypeVar
+
+from pdmt5 import Mt5Config, Mt5DataClient
+
+from .history import (
+    create_cash_events_view,
+    create_history_indexes,
+    create_positions_reconstructed_view,
+    resolve_history_datasets,
+    resolve_history_tick_flags,
+    resolve_history_timeframes,
+    write_collected_datasets,
+    write_incremental_datasets,
+)
+from .utils import (
+    Dataset,
+    IfExists,
+    parse_datetime,
+    parse_tick_flags,
+    parse_timeframe,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterator, Sequence
+
+    import pandas as pd
+
+T = TypeVar("T")
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "Mt5CliClient",
+    "account_info",
+    "build_config",
+    "collect_history",
+    "copy_rates_from",
+    "copy_rates_from_pos",
+    "copy_rates_range",
+    "copy_ticks_from",
+    "copy_ticks_range",
+    "history_deals",
+    "history_orders",
+    "last_error",
+    "market_book",
+    "orders",
+    "positions",
+    "symbol_info",
+    "symbol_info_tick",
+    "symbols",
+    "terminal_info",
+    "update_history",
+    "update_history_with_config",
+    "version",
+]
+
+
+def _coerce_timeframe(timeframe: int | str) -> int:
+    if isinstance(timeframe, int):
+        return timeframe
+    return parse_timeframe(timeframe)
+
+
+def _coerce_tick_flags(flags: int | str) -> int:
+    if isinstance(flags, int):
+        return flags
+    return parse_tick_flags(flags)
+
+
+def _require_datetime(value: datetime | str) -> datetime:
+    if isinstance(value, datetime):
+        return value
+    return parse_datetime(value)
+
+
+def _coerce_datetime(value: datetime | str | None) -> datetime | None:
+    if value is None or isinstance(value, datetime):
+        return value
+    return parse_datetime(value)
+
+
+def build_config(
+    *,
+    path: str | None = None,
+    login: int | None = None,
+    password: str | None = None,
+    server: str | None = None,
+    timeout: int | None = None,
+) -> Mt5Config:
+    """Build an ``Mt5Config`` from optional connection parameters.
+
+    Returns:
+        Configured ``Mt5Config`` instance.
+    """
+    return Mt5Config(
+        path=path,
+        login=login,
+        password=password,
+        server=server,
+        timeout=timeout,
+    )
+
+
+@contextmanager
+def _connected_client(config: Mt5Config) -> Iterator[Mt5DataClient]:
+    """Initialize MT5, yield a connected client, and always shut down.
+
+    Args:
+        config: MT5 connection configuration.
+
+    Yields:
+        Connected ``Mt5DataClient`` instance.
+    """
+    client = Mt5DataClient(config=config)
+    try:
+        client.initialize_and_login_mt5()
+        yield client
+    finally:
+        client.shutdown()
+
+
+def _run_with_client(
+    config: Mt5Config,
+    fetch_fn: Callable[[Mt5DataClient], T],
+) -> T:
+    """Connect, run ``fetch_fn``, and shut down safely.
+
+    Args:
+        config: MT5 connection configuration.
+        fetch_fn: Callable receiving a connected client.
+
+    Returns:
+        Value returned by ``fetch_fn``.
+    """
+    with _connected_client(config) as client:
+        return fetch_fn(client)
+
+
+class Mt5CliClient:
+    """Programmatic client for read-only MetaTrader 5 data access."""
+
+    def __init__(
+        self,
+        *,
+        path: str | None = None,
+        login: int | None = None,
+        password: str | None = None,
+        server: str | None = None,
+        timeout: int | None = None,
+        config: Mt5Config | None = None,
+    ) -> None:
+        """Initialize the SDK client.
+
+        Args:
+            path: Path to MetaTrader5 terminal EXE file.
+            login: Trading account login.
+            password: Trading account password.
+            server: Trading server name.
+            timeout: Connection timeout in milliseconds.
+            config: Optional pre-built ``Mt5Config`` (overrides other args).
+        """
+        self._config = config or build_config(
+            path=path,
+            login=login,
+            password=password,
+            server=server,
+            timeout=timeout,
+        )
+        self._client: Mt5DataClient | None = None
+
+    @property
+    def config(self) -> Mt5Config:
+        """Return the underlying MT5 configuration."""
+        return self._config
+
+    def __enter__(self) -> Self:
+        """Open a persistent MT5 connection for multiple calls.
+
+        Returns:
+            This client instance.
+        """
+        client = Mt5DataClient(config=self._config)
+        try:
+            client.initialize_and_login_mt5()
+        except Exception:
+            client.shutdown()
+            raise
+        self._client = client
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: object,
+    ) -> None:
+        """Shut down the persistent MT5 connection."""
+        if self._client is not None:
+            self._client.shutdown()
+            self._client = None
+
+    def _fetch(self, fetch_fn: Callable[[Mt5DataClient], pd.DataFrame]) -> pd.DataFrame:
+        if self._client is not None:
+            return fetch_fn(self._client)
+        return _run_with_client(self._config, fetch_fn)
+
+    def copy_rates_from(
+        self,
+        symbol: str,
+        timeframe: int | str,
+        date_from: datetime | str,
+        count: int,
+    ) -> pd.DataFrame:
+        """Return rates starting from a date."""
+        tf = _coerce_timeframe(timeframe)
+        start = _require_datetime(date_from)
+        return self._fetch(
+            lambda c: c.copy_rates_from_as_df(
+                symbol=symbol,
+                timeframe=tf,
+                date_from=start,
+                count=count,
+            ),
+        )
+
+    def copy_rates_from_pos(
+        self,
+        symbol: str,
+        timeframe: int | str,
+        start_pos: int,
+        count: int,
+    ) -> pd.DataFrame:
+        """Return rates starting from a bar position."""
+        tf = _coerce_timeframe(timeframe)
+        return self._fetch(
+            lambda c: c.copy_rates_from_pos_as_df(
+                symbol=symbol,
+                timeframe=tf,
+                start_pos=start_pos,
+                count=count,
+            ),
+        )
+
+    def copy_rates_range(
+        self,
+        symbol: str,
+        timeframe: int | str,
+        date_from: datetime | str,
+        date_to: datetime | str,
+    ) -> pd.DataFrame:
+        """Return rates for a date range."""
+        tf = _coerce_timeframe(timeframe)
+        start = _require_datetime(date_from)
+        end = _require_datetime(date_to)
+        return self._fetch(
+            lambda c: c.copy_rates_range_as_df(
+                symbol=symbol,
+                timeframe=tf,
+                date_from=start,
+                date_to=end,
+            ),
+        )
+
+    def copy_ticks_from(
+        self,
+        symbol: str,
+        date_from: datetime | str,
+        count: int,
+        flags: int | str,
+    ) -> pd.DataFrame:
+        """Return ticks starting from a date."""
+        start = _require_datetime(date_from)
+        tick_flags = _coerce_tick_flags(flags)
+        return self._fetch(
+            lambda c: c.copy_ticks_from_as_df(
+                symbol=symbol,
+                date_from=start,
+                count=count,
+                flags=tick_flags,
+            ),
+        )
+
+    def copy_ticks_range(
+        self,
+        symbol: str,
+        date_from: datetime | str,
+        date_to: datetime | str,
+        flags: int | str,
+    ) -> pd.DataFrame:
+        """Return ticks for a date range."""
+        start = _require_datetime(date_from)
+        end = _require_datetime(date_to)
+        tick_flags = _coerce_tick_flags(flags)
+        return self._fetch(
+            lambda c: c.copy_ticks_range_as_df(
+                symbol=symbol,
+                date_from=start,
+                date_to=end,
+                flags=tick_flags,
+            ),
+        )
+
+    def account_info(self) -> pd.DataFrame:
+        """Return account information."""
+        return self._fetch(lambda c: c.account_info_as_df())
+
+    def terminal_info(self) -> pd.DataFrame:
+        """Return terminal information."""
+        return self._fetch(lambda c: c.terminal_info_as_df())
+
+    def symbols(self, group: str | None = None) -> pd.DataFrame:
+        """Return the symbol list."""
+        return self._fetch(lambda c: c.symbols_get_as_df(group=group))
+
+    def symbol_info(self, symbol: str) -> pd.DataFrame:
+        """Return details for one symbol."""
+        return self._fetch(lambda c: c.symbol_info_as_df(symbol=symbol))
+
+    def orders(
+        self,
+        symbol: str | None = None,
+        group: str | None = None,
+        ticket: int | None = None,
+    ) -> pd.DataFrame:
+        """Return active orders."""
+        return self._fetch(
+            lambda c: c.orders_get_as_df(
+                symbol=symbol,
+                group=group,
+                ticket=ticket,
+            ),
+        )
+
+    def positions(
+        self,
+        symbol: str | None = None,
+        group: str | None = None,
+        ticket: int | None = None,
+    ) -> pd.DataFrame:
+        """Return open positions."""
+        return self._fetch(
+            lambda c: c.positions_get_as_df(
+                symbol=symbol,
+                group=group,
+                ticket=ticket,
+            ),
+        )
+
+    def history_orders(
+        self,
+        date_from: datetime | str | None = None,
+        date_to: datetime | str | None = None,
+        group: str | None = None,
+        symbol: str | None = None,
+        ticket: int | None = None,
+        position: int | None = None,
+    ) -> pd.DataFrame:
+        """Return historical orders."""
+        start = _coerce_datetime(date_from)
+        end = _coerce_datetime(date_to)
+        return self._fetch(
+            lambda c: c.history_orders_get_as_df(
+                date_from=start,
+                date_to=end,
+                group=group,
+                symbol=symbol,
+                ticket=ticket,
+                position=position,
+            ),
+        )
+
+    def history_deals(
+        self,
+        date_from: datetime | str | None = None,
+        date_to: datetime | str | None = None,
+        group: str | None = None,
+        symbol: str | None = None,
+        ticket: int | None = None,
+        position: int | None = None,
+    ) -> pd.DataFrame:
+        """Return historical deals."""
+        start = _coerce_datetime(date_from)
+        end = _coerce_datetime(date_to)
+        return self._fetch(
+            lambda c: c.history_deals_get_as_df(
+                date_from=start,
+                date_to=end,
+                group=group,
+                symbol=symbol,
+                ticket=ticket,
+                position=position,
+            ),
+        )
+
+    def version(self) -> pd.DataFrame:
+        """Return MetaTrader5 version information."""
+        return self._fetch(lambda c: c.version_as_df())
+
+    def last_error(self) -> pd.DataFrame:
+        """Return the last error information."""
+        return self._fetch(lambda c: c.last_error_as_df())
+
+    def symbol_info_tick(self, symbol: str) -> pd.DataFrame:
+        """Return the last tick for a symbol."""
+        return self._fetch(lambda c: c.symbol_info_tick_as_df(symbol=symbol))
+
+    def market_book(self, symbol: str) -> pd.DataFrame:
+        """Return market depth for a symbol."""
+        return self._fetch(lambda c: c.market_book_get_as_df(symbol=symbol))
+
+
+def _resolve_incremental_settings(
+    selected_datasets: set[Dataset],
+    timeframes: Sequence[int | str] | None,
+    flags: int | str,
+) -> tuple[list[int], int]:
+    """Resolve dataset-specific incremental update settings.
+
+    Returns:
+        Tuple of resolved rate timeframes and tick copy flags.
+
+    Raises:
+        ValueError: If timeframe or tick flag values are invalid.
+    """
+    resolved_timeframes: list[int] = []
+    if Dataset.rates in selected_datasets:
+        try:
+            resolved_timeframes = resolve_history_timeframes(timeframes)
+        except ValueError as exc:
+            msg = str(exc)
+            raise ValueError(msg) from exc
+    resolved_tick_flags = 0
+    if Dataset.ticks in selected_datasets:
+        try:
+            resolved_tick_flags = resolve_history_tick_flags(flags)
+        except ValueError as exc:
+            msg = str(exc)
+            raise ValueError(msg) from exc
+    return resolved_timeframes, resolved_tick_flags
+
+
+@dataclass(frozen=True)
+class _UpdateHistoryRequest:
+    selected: set[Dataset]
+    end: datetime
+    fallback_start: datetime
+    resolved_timeframes: list[int]
+    resolved_tick_flags: int
+    output_path: Path
+
+
+def _resolve_update_history_request(
+    *,
+    output: Path | str,
+    symbols: Sequence[str],
+    datasets: set[Dataset] | None,
+    timeframes: Sequence[int | str] | None,
+    flags: int | str,
+    lookback_hours: float,
+    date_to: datetime | str | None,
+) -> _UpdateHistoryRequest | None:
+    """Validate and resolve incremental history update inputs.
+
+    Returns:
+        Resolved request parameters, or None when no datasets are selected.
+
+    Raises:
+        ValueError: If symbols are empty, lookback_hours is not positive, or
+            timeframe/flag values are invalid.
+    """
+    if lookback_hours <= 0:
+        msg = "lookback_hours must be positive."
+        raise ValueError(msg)
+    selected = resolve_history_datasets(datasets)
+    if not selected:
+        logger.info("Skipping SQLite history update: no datasets selected.")
+        return None
+    if not symbols:
+        msg = "At least one symbol is required."
+        raise ValueError(msg)
+
+    if date_to is not None:
+        resolved_end = _coerce_datetime(date_to)
+    else:
+        resolved_end = datetime.now(UTC)
+    end = resolved_end if resolved_end is not None else datetime.now(UTC)
+    fallback_start = end - timedelta(hours=lookback_hours)
+    resolved_timeframes, resolved_tick_flags = _resolve_incremental_settings(
+        selected,
+        timeframes,
+        flags,
+    )
+    return _UpdateHistoryRequest(
+        selected=selected,
+        end=end,
+        fallback_start=fallback_start,
+        resolved_timeframes=resolved_timeframes,
+        resolved_tick_flags=resolved_tick_flags,
+        output_path=Path(output),
+    )
+
+
+def update_history(  # noqa: PLR0913
+    *,
+    client: Mt5DataClient,
+    output: Path | str,
+    symbols: Sequence[str],
+    datasets: set[Dataset] | None = None,
+    timeframes: Sequence[int | str] | None = None,
+    flags: int | str = "ALL",
+    lookback_hours: float = 24.0,
+    date_to: datetime | str | None = None,
+    deduplicate: bool = True,
+    create_rate_views: bool = True,
+    with_views: bool = False,
+    include_account_events: bool = True,
+) -> None:
+    """Incrementally append MT5 history into a SQLite database.
+
+    Uses an already-connected ``Mt5DataClient`` and does not create or close
+    the MT5 connection. For first-time tables, data is fetched from
+    ``date_to - lookback_hours``. Subsequent runs resume from existing
+    ``MAX(time)`` per symbol (and timeframe for rates); when
+    ``include_account_events=True``, account-level deals use a separate cursor
+    over ``type NOT IN (0, 1)`` / empty-symbol rows.
+
+    Args:
+        client: Connected MT5 data client.
+        output: SQLite database path.
+        symbols: Symbols to update.
+        datasets: Datasets to include (defaults to all).
+        timeframes: Rate timeframes to update (defaults to all fixed MT5
+            timeframes when None).
+        flags: Tick copy flags as integer or name (e.g. ``ALL``).
+        lookback_hours: First-run lookback when a table has no prior rows.
+        date_to: Optional update end datetime. Defaults to now (UTC).
+        deduplicate: Remove duplicate rows after append, keeping latest ROWID.
+        create_rate_views: Create ``rate_<symbol>__<timeframe>`` views.
+        with_views: Create ``cash_events`` and ``positions_reconstructed`` views.
+        include_account_events: Include account-level cash events in
+            ``history_deals`` when True.
+    """
+    request = _resolve_update_history_request(
+        output=output,
+        symbols=symbols,
+        datasets=datasets,
+        timeframes=timeframes,
+        flags=flags,
+        lookback_hours=lookback_hours,
+        date_to=date_to,
+    )
+    if request is None:
+        return
+    logger.info(
+        "Updating history in SQLite: symbols=%s, datasets=%s, path=%s",
+        list(symbols),
+        sorted(dataset.value for dataset in request.selected),
+        request.output_path,
+    )
+    with sqlite3.connect(request.output_path) as conn:
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA synchronous=NORMAL")
+        write_incremental_datasets(
+            conn,
+            client,
+            symbols,
+            request.selected,
+            request.resolved_timeframes,
+            request.resolved_tick_flags,
+            request.fallback_start,
+            request.end,
+            deduplicate=deduplicate,
+            create_rate_views=create_rate_views,
+            with_views=with_views,
+            include_account_events=include_account_events,
+        )
+
+
+def update_history_with_config(  # noqa: PLR0913
+    *,
+    output: Path | str,
+    symbols: Sequence[str],
+    config: Mt5Config | None = None,
+    datasets: set[Dataset] | None = None,
+    timeframes: Sequence[int | str] | None = None,
+    flags: int | str = "ALL",
+    lookback_hours: float = 24.0,
+    date_to: datetime | str | None = None,
+    deduplicate: bool = True,
+    create_rate_views: bool = True,
+    with_views: bool = False,
+    include_account_events: bool = True,
+) -> None:
+    """Incrementally append MT5 history, opening and closing the MT5 connection.
+
+    Convenience wrapper around :func:`update_history` for standalone use.
+    """
+    request = _resolve_update_history_request(
+        output=output,
+        symbols=symbols,
+        datasets=datasets,
+        timeframes=timeframes,
+        flags=flags,
+        lookback_hours=lookback_hours,
+        date_to=date_to,
+    )
+    if request is None:
+        return
+    mt5_config = config or build_config()
+    with _connected_client(mt5_config) as client:
+        update_history(
+            client=client,
+            output=output,
+            symbols=symbols,
+            datasets=datasets,
+            timeframes=timeframes,
+            flags=flags,
+            lookback_hours=lookback_hours,
+            date_to=date_to,
+            deduplicate=deduplicate,
+            create_rate_views=create_rate_views,
+            with_views=with_views,
+            include_account_events=include_account_events,
+        )
+
+
+def collect_history(
+    output: Path,
+    symbols: list[str],
+    date_from: datetime | str,
+    date_to: datetime | str,
+    *,
+    datasets: set[Dataset] | None = None,
+    timeframe: int | str = 1,
+    flags: int | str = 1,
+    if_exists: IfExists = IfExists.FAIL,
+    with_views: bool = False,
+    config: Mt5Config | None = None,
+) -> None:
+    """Collect historical datasets into a single SQLite database.
+
+    Args:
+        output: SQLite database path.
+        symbols: Symbols to collect.
+        date_from: Start date.
+        date_to: End date.
+        datasets: Datasets to include (defaults to all).
+        timeframe: Rates timeframe as integer or name (e.g. ``M1``).
+        flags: Tick copy flags as integer or name (e.g. ``ALL``).
+        if_exists: Behavior when a target table already exists.
+        with_views: Create ``cash_events`` and ``positions_reconstructed`` views.
+        config: MT5 connection configuration.
+    """
+    start = _require_datetime(date_from)
+    end = _require_datetime(date_to)
+    selected = datasets if datasets is not None else set(Dataset)
+    tf = _coerce_timeframe(timeframe)
+    tick_flags = _coerce_tick_flags(flags)
+    mt5_config = config or build_config()
+    with _connected_client(mt5_config) as client, sqlite3.connect(output) as conn:
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA synchronous=NORMAL")
+        written_tables, written_columns = write_collected_datasets(
+            conn,
+            client,
+            symbols,
+            selected,
+            tf,
+            tick_flags,
+            start,
+            end,
+            if_exists,
+        )
+        create_history_indexes(conn, written_columns)
+        if with_views and Dataset.history_deals in written_tables:
+            create_cash_events_view(conn, written_columns[Dataset.history_deals])
+            create_positions_reconstructed_view(
+                conn,
+                written_columns[Dataset.history_deals],
+            )
+        elif with_views:
+            logger.warning(
+                "--with-views ignored: history_deals table was not written",
+            )
+    logger.info(
+        "Collected %s for %d symbol(s) into %s",
+        ", ".join(sorted(ds.value for ds in selected)),
+        len(symbols),
+        output,
+    )
+
+
+def _make_client(*, config: Mt5Config | None = None) -> Mt5CliClient:
+    return Mt5CliClient(config=config) if config is not None else Mt5CliClient()
+
+
+def copy_rates_from(
+    symbol: str,
+    timeframe: int | str,
+    date_from: datetime | str,
+    count: int,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return rates starting from a date."""
+    return _make_client(config=config).copy_rates_from(
+        symbol,
+        timeframe,
+        date_from,
+        count,
+    )
+
+
+def copy_rates_from_pos(
+    symbol: str,
+    timeframe: int | str,
+    start_pos: int,
+    count: int,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return rates starting from a bar position."""
+    return _make_client(config=config).copy_rates_from_pos(
+        symbol,
+        timeframe,
+        start_pos,
+        count,
+    )
+
+
+def copy_rates_range(
+    symbol: str,
+    timeframe: int | str,
+    date_from: datetime | str,
+    date_to: datetime | str,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return rates for a date range."""
+    return _make_client(config=config).copy_rates_range(
+        symbol,
+        timeframe,
+        date_from,
+        date_to,
+    )
+
+
+def copy_ticks_from(
+    symbol: str,
+    date_from: datetime | str,
+    count: int,
+    flags: int | str,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return ticks starting from a date."""
+    return _make_client(config=config).copy_ticks_from(
+        symbol,
+        date_from,
+        count,
+        flags,
+    )
+
+
+def copy_ticks_range(
+    symbol: str,
+    date_from: datetime | str,
+    date_to: datetime | str,
+    flags: int | str,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return ticks for a date range."""
+    return _make_client(config=config).copy_ticks_range(
+        symbol,
+        date_from,
+        date_to,
+        flags,
+    )
+
+
+def account_info(*, config: Mt5Config | None = None) -> pd.DataFrame:
+    """Return account information."""
+    return _make_client(config=config).account_info()
+
+
+def terminal_info(*, config: Mt5Config | None = None) -> pd.DataFrame:
+    """Return terminal information."""
+    return _make_client(config=config).terminal_info()
+
+
+def symbols(
+    group: str | None = None,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return the symbol list."""
+    return _make_client(config=config).symbols(group=group)
+
+
+def symbol_info(
+    symbol: str,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return details for one symbol."""
+    return _make_client(config=config).symbol_info(symbol)
+
+
+def orders(
+    symbol: str | None = None,
+    group: str | None = None,
+    ticket: int | None = None,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return active orders."""
+    return _make_client(config=config).orders(
+        symbol=symbol,
+        group=group,
+        ticket=ticket,
+    )
+
+
+def positions(
+    symbol: str | None = None,
+    group: str | None = None,
+    ticket: int | None = None,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return open positions."""
+    return _make_client(config=config).positions(
+        symbol=symbol,
+        group=group,
+        ticket=ticket,
+    )
+
+
+def history_orders(
+    date_from: datetime | str | None = None,
+    date_to: datetime | str | None = None,
+    group: str | None = None,
+    symbol: str | None = None,
+    ticket: int | None = None,
+    position: int | None = None,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return historical orders."""
+    return _make_client(config=config).history_orders(
+        date_from=date_from,
+        date_to=date_to,
+        group=group,
+        symbol=symbol,
+        ticket=ticket,
+        position=position,
+    )
+
+
+def history_deals(
+    date_from: datetime | str | None = None,
+    date_to: datetime | str | None = None,
+    group: str | None = None,
+    symbol: str | None = None,
+    ticket: int | None = None,
+    position: int | None = None,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return historical deals."""
+    return _make_client(config=config).history_deals(
+        date_from=date_from,
+        date_to=date_to,
+        group=group,
+        symbol=symbol,
+        ticket=ticket,
+        position=position,
+    )
+
+
+def version(*, config: Mt5Config | None = None) -> pd.DataFrame:
+    """Return MetaTrader5 version information."""
+    return _make_client(config=config).version()
+
+
+def last_error(*, config: Mt5Config | None = None) -> pd.DataFrame:
+    """Return the last error information."""
+    return _make_client(config=config).last_error()
+
+
+def symbol_info_tick(
+    symbol: str,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return the last tick for a symbol."""
+    return _make_client(config=config).symbol_info_tick(symbol)
+
+
+def market_book(
+    symbol: str,
+    *,
+    config: Mt5Config | None = None,
+) -> pd.DataFrame:
+    """Return market depth for a symbol."""
+    return _make_client(config=config).market_book(symbol)
@@ -0,0 +1,408 @@
+"""Utility constants, types, and functions for the mt5cli package."""
+
+from __future__ import annotations
+
+import importlib
+import json
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, TypeGuard, cast
+
+import click
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+TIMEFRAME_MAP: dict[str, int] = {
+    "M1": 1,
+    "M2": 2,
+    "M3": 3,
+    "M4": 4,
+    "M5": 5,
+    "M6": 6,
+    "M10": 10,
+    "M12": 12,
+    "M15": 15,
+    "M20": 20,
+    "M30": 30,
+    "H1": 16385,
+    "H2": 16386,
+    "H3": 16387,
+    "H4": 16388,
+    "H6": 16390,
+    "H8": 16392,
+    "H12": 16396,
+    "D1": 16408,
+    "W1": 32769,
+    "MN1": 49153,
+}
+
+TICK_FLAG_MAP: dict[str, int] = {
+    "ALL": 1,
+    "INFO": 2,
+    "TRADE": 4,
+}
+
+_FORMAT_EXTENSIONS: dict[str, str] = {
+    ".csv": "csv",
+    ".json": "json",
+    ".parquet": "parquet",
+    ".pq": "parquet",
+    ".db": "sqlite3",
+    ".sqlite": "sqlite3",
+    ".sqlite3": "sqlite3",
+}
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class OutputFormat(StrEnum):
+    """Supported output file formats."""
+
+    csv = "csv"
+    json = "json"
+    parquet = "parquet"
+    sqlite3 = "sqlite3"
+
+
+class LogLevel(StrEnum):
+    """Logging verbosity levels."""
+
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+
+
+class Dataset(StrEnum):
+    """Datasets supported by the ``collect-history`` command."""
+
+    rates = "rates"
+    ticks = "ticks"
+    history_orders = "history-orders"
+    history_deals = "history-deals"
+
+    @property
+    def table_name(self) -> str:
+        """Return the SQLite table name for this dataset."""
+        return self.value.replace("-", "_")
+
+
+class IfExists(StrEnum):
+    """SQLite table conflict behavior for the ``collect-history`` command."""
+
+    APPEND = "append"
+    REPLACE = "replace"
+    FAIL = "fail"
+
+
+# ---------------------------------------------------------------------------
+# Click parameter types
+# ---------------------------------------------------------------------------
+
+
+class _DateTimeType(click.ParamType):
+    """Click parameter type for ISO 8601 datetime strings."""
+
+    name = "DATETIME"
+
+    def convert(
+        self,
+        value: object,
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> datetime:
+        """Convert a string value to a timezone-aware datetime.
+
+        Args:
+            value: Raw value from the command line.
+            param: Click parameter instance.
+            ctx: Click context.
+
+        Returns:
+            Parsed datetime.
+        """
+        if isinstance(value, datetime):
+            return value
+        try:
+            return parse_datetime(str(value))
+        except ValueError as exc:
+            self.fail(str(exc), param, ctx)
+
+
+class _TimeframeType(click.ParamType):
+    """Click parameter type for MT5 timeframe values."""
+
+    name = "TIMEFRAME"
+
+    def convert(
+        self,
+        value: object,
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> int:
+        """Convert a string or integer value to a timeframe integer.
+
+        Args:
+            value: Raw value from the command line.
+            param: Click parameter instance.
+            ctx: Click context.
+
+        Returns:
+            Integer timeframe value.
+        """
+        if isinstance(value, int):
+            return value
+        try:
+            return parse_timeframe(str(value))
+        except ValueError as exc:
+            self.fail(str(exc), param, ctx)
+
+
+class _TickFlagsType(click.ParamType):
+    """Click parameter type for MT5 tick copy flags."""
+
+    name = "FLAGS"
+
+    def convert(
+        self,
+        value: object,
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> int:
+        """Convert a string or integer value to a tick flags integer.
+
+        Args:
+            value: Raw value from the command line.
+            param: Click parameter instance.
+            ctx: Click context.
+
+        Returns:
+            Integer tick flag value.
+        """
+        if isinstance(value, int):
+            return value
+        try:
+            return parse_tick_flags(str(value))
+        except ValueError as exc:
+            self.fail(str(exc), param, ctx)
+
+
+class _RequestType(click.ParamType):
+    """Click parameter type for JSON order requests."""
+
+    name = "REQUEST"
+
+    def convert(
+        self,
+        value: object,
+        param: click.Parameter | None,
+        ctx: click.Context | None,
+    ) -> dict[str, Any]:
+        """Convert a raw CLI value to an order request dictionary.
+
+        Args:
+            value: Raw value from the command line.
+            param: Click parameter instance.
+            ctx: Click context.
+
+        Returns:
+            Parsed request dictionary.
+        """
+        try:
+            return parse_request(str(value))
+        except ValueError as exc:
+            self.fail(str(exc), param, ctx)
+
+
+DATETIME_TYPE = _DateTimeType()
+TIMEFRAME_TYPE = _TimeframeType()
+TICK_FLAGS_TYPE = _TickFlagsType()
+REQUEST_TYPE = _RequestType()
+
+# ---------------------------------------------------------------------------
+# Public utility functions
+# ---------------------------------------------------------------------------
+
+
+def detect_format(
+    output_path: Path,
+    explicit_format: str | None = None,
+) -> str:
+    """Detect the output format from a file extension or explicit format string.
+
+    Args:
+        output_path: Path to the output file.
+        explicit_format: Explicitly specified format, if any.
+
+    Returns:
+        The detected format string.
+
+    Raises:
+        ValueError: If the format cannot be determined.
+    """
+    if explicit_format is not None:
+        return explicit_format
+    suffix = output_path.suffix.lower()
+    if suffix in _FORMAT_EXTENSIONS:
+        return _FORMAT_EXTENSIONS[suffix]
+    msg = (
+        f"Cannot detect format from extension '{suffix}'."
+        " Use --format to specify the output format."
+    )
+    raise ValueError(msg)
+
+
+def export_dataframe(
+    df: pd.DataFrame,
+    output_path: Path,
+    output_format: str,
+    table_name: str = "data",
+) -> None:
+    """Export a pandas DataFrame to the specified file format.
+
+    Args:
+        df: DataFrame to export.
+        output_path: Path to the output file.
+        output_format: Output format (csv, json, parquet, or sqlite3).
+        table_name: Table name for SQLite3 output.
+
+    Raises:
+        ValueError: If the output format is not supported.
+    """
+    if output_format == "csv":
+        df.to_csv(output_path, index=False)
+    elif output_format == "json":
+        df.to_json(
+            output_path,
+            orient="records",
+            date_format="iso",
+            indent=2,
+        )
+    elif output_format == "parquet":
+        df.to_parquet(output_path, index=False)
+    elif output_format == "sqlite3":
+        sqlite3 = cast("Any", importlib.import_module("sqlite3"))
+        with sqlite3.connect(output_path) as conn:
+            df.to_sql(  # type: ignore[reportUnknownMemberType]
+                table_name,
+                conn,
+                if_exists="replace",
+                index=False,
+            )
+    else:
+        msg = f"Unsupported output format: {output_format}"
+        raise ValueError(msg)
+
+
+def parse_datetime(value: str) -> datetime:
+    """Parse an ISO 8601 datetime string to a timezone-aware datetime.
+
+    Args:
+        value: ISO 8601 datetime string (e.g., '2024-01-01' or
+            '2024-01-01T12:00:00+00:00').
+
+    Returns:
+        Parsed datetime with UTC timezone if no timezone is specified.
+
+    Raises:
+        ValueError: If the string cannot be parsed.
+    """
+    try:
+        dt = datetime.fromisoformat(value)
+    except ValueError:
+        msg = f"Invalid datetime format: '{value}'. Use ISO 8601 format."
+        raise ValueError(msg) from None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt
+
+
+def parse_timeframe(value: str) -> int:
+    """Parse a timeframe string or integer value.
+
+    Args:
+        value: Timeframe name (e.g., 'M1', 'H1', 'D1') or integer value.
+
+    Returns:
+        Integer timeframe value.
+
+    Raises:
+        ValueError: If the timeframe is invalid.
+    """
+    upper = value.upper()
+    if upper in TIMEFRAME_MAP:
+        return TIMEFRAME_MAP[upper]
+    try:
+        return int(value)
+    except ValueError:
+        valid = ", ".join(TIMEFRAME_MAP)
+        msg = f"Invalid timeframe: '{value}'. Use one of: {valid}, or an integer."
+        raise ValueError(msg) from None
+
+
+def parse_tick_flags(value: str) -> int:
+    """Parse tick flags string or integer value.
+
+    Args:
+        value: Tick flag name (ALL, INFO, TRADE) or integer value.
+
+    Returns:
+        Integer tick flag value.
+
+    Raises:
+        ValueError: If the flag is invalid.
+    """
+    upper = value.upper()
+    if upper in TICK_FLAG_MAP:
+        return TICK_FLAG_MAP[upper]
+    try:
+        return int(value)
+    except ValueError:
+        valid = ", ".join(TICK_FLAG_MAP)
+        msg = f"Invalid tick flags: '{value}'. Use one of: {valid}, or an integer."
+        raise ValueError(msg) from None
+
+
+def _is_request_dict(value: object) -> TypeGuard[dict[str, Any]]:
+    return isinstance(value, dict)
+
+
+def parse_request(value: str) -> dict[str, Any]:
+    """Parse a JSON-formatted order request string or file reference.
+
+    Args:
+        value: JSON object string, or '@path' to read JSON from a file.
+
+    Returns:
+        Parsed request dictionary.
+
+    Raises:
+        ValueError: If the request file cannot be read or the value is not a
+            JSON object.
+    """
+    if value.startswith("@"):
+        path = Path(value[1:])
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            msg = f"Failed to read JSON request file '{path}': {exc}"
+            raise ValueError(msg) from exc
+    else:
+        text = value
+    try:
+        parsed: object = json.loads(text)
+    except json.JSONDecodeError as exc:
+        msg = f"Invalid JSON request: {exc}"
+        raise ValueError(msg) from exc
+    if not _is_request_dict(parsed):
+        msg = "Order request must be a JSON object."
+        raise ValueError(msg)
+    return parsed
@@ -1,6 +1,6 @@
 [project]
 name = "mt5cli"
-version = "0.1.0"
+version = "0.4.2"
 description = "Command-line tool for MetaTrader 5"
 authors = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
 maintainers = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
@@ -48,10 +48,6 @@ dev = [
  "pymdown-extensions >= 10.21.2",
 ]

-[tool.uv.build-backend]
-source-include = ["mt5cli/**", "LICENSE"]
-source-exclude = ["tests/**"]
-
 [tool.ruff]
 line-length = 88
 exclude = ["build", ".venv"]
@@ -128,6 +124,7 @@ ignore = [
 ]

 [tool.ruff.lint.per-file-ignores]
+"mt5cli/history.py" = ["TC003"]
 "tests/**/*.py" = [
  "DOC201",   # Missing return documentation
  "DOC501",   # Raised exception missing from docstring
@@ -50,21 +50,22 @@ Global options MUST precede the subcommand.

 ## Commands

-| Command          | Required options                                      | Optional options                                                            |
-| ---------------- | ----------------------------------------------------- | --------------------------------------------------------------------------- |
-| `rates-from`     | `--symbol`, `--timeframe`, `--date-from`, `--count`   | —                                                                           |
-| `rates-from-pos` | `--symbol`, `--timeframe`, `--start-pos`, `--count`   | —                                                                           |
-| `rates-range`    | `--symbol`, `--timeframe`, `--date-from`, `--date-to` | —                                                                           |
-| `ticks-from`     | `--symbol`, `--date-from`, `--count`, `--flags`       | —                                                                           |
-| `ticks-range`    | `--symbol`, `--date-from`, `--date-to`, `--flags`     | —                                                                           |
-| `account-info`   | —                                                     | —                                                                           |
-| `terminal-info`  | —                                                     | —                                                                           |
-| `symbols`        | —                                                     | `--group` (e.g., `*USD*`)                                                   |
-| `symbol-info`    | `--symbol`                                            | —                                                                           |
-| `orders`         | —                                                     | `--symbol`, `--group`, `--ticket`                                           |
-| `positions`      | —                                                     | `--symbol`, `--group`, `--ticket`                                           |
-| `history-orders` | —                                                     | `--date-from`, `--date-to`, `--group`, `--symbol`, `--ticket`, `--position` |
-| `history-deals`  | —                                                     | `--date-from`, `--date-to`, `--group`, `--symbol`, `--ticket`, `--position` |
+| Command           | Required options                                      | Optional options                                                                                                                                                                                                                 |
+| ----------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rates-from`      | `--symbol`, `--timeframe`, `--date-from`, `--count`   | —                                                                                                                                                                                                                                |
+| `rates-from-pos`  | `--symbol`, `--timeframe`, `--start-pos`, `--count`   | —                                                                                                                                                                                                                                |
+| `rates-range`     | `--symbol`, `--timeframe`, `--date-from`, `--date-to` | —                                                                                                                                                                                                                                |
+| `ticks-from`      | `--symbol`, `--date-from`, `--count`, `--flags`       | —                                                                                                                                                                                                                                |
+| `ticks-range`     | `--symbol`, `--date-from`, `--date-to`, `--flags`     | —                                                                                                                                                                                                                                |
+| `account-info`    | —                                                     | —                                                                                                                                                                                                                                |
+| `terminal-info`   | —                                                     | —                                                                                                                                                                                                                                |
+| `symbols`         | —                                                     | `--group` (e.g., `*USD*`)                                                                                                                                                                                                        |
+| `symbol-info`     | `--symbol`                                            | —                                                                                                                                                                                                                                |
+| `orders`          | —                                                     | `--symbol`, `--group`, `--ticket`                                                                                                                                                                                                |
+| `positions`       | —                                                     | `--symbol`, `--group`, `--ticket`                                                                                                                                                                                                |
+| `history-orders`  | —                                                     | `--date-from`, `--date-to`, `--group`, `--symbol`, `--ticket`, `--position`                                                                                                                                                      |
+| `history-deals`   | —                                                     | `--date-from`, `--date-to`, `--group`, `--symbol`, `--ticket`, `--position`                                                                                                                                                      |
+| `collect-history` | `--symbol` (repeatable), `--date-from`, `--date-to`   | `--dataset` (repeatable; rates/ticks/history-orders/history-deals; default all), `--timeframe` (M1; recorded on rates), `--flags` (ALL), `--if-exists` (append/replace/fail; default fail), `--with-views` (SQLite3 output only) |

 ## Examples

@@ -85,6 +86,14 @@ mt5cli -o data.db --table symbols symbols --group "*USD*"

 # Historical deals filtered by symbol (using an already-logged-in MT5 terminal).
 mt5cli -o deals.csv history-deals --symbol EURUSD --date-from 2024-01-01
+
+# Bundle selected historical datasets into one SQLite db, appending to any
+# existing tables, plus cash_events and positions_reconstructed views.
+mt5cli -o history.db collect-history \
+  --symbol EURUSD --symbol GBPUSD \
+  --date-from 2024-01-01 --date-to 2024-02-01 \
+  --dataset rates --dataset history-deals \
+  --timeframe M1 --flags ALL --if-exists append --with-views
 ```

 ## Guidelines
@@ -0,0 +1,810 @@
+"""Tests for mt5cli.sdk module."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+from unittest.mock import MagicMock
+
+import pandas as pd
+import pytest
+from pytest_mock import MockerFixture  # noqa: TC002
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from mt5cli import sdk
+from mt5cli.history import DEFAULT_HISTORY_TIMEFRAMES
+from mt5cli.sdk import (
+    Mt5CliClient,
+    account_info,
+    build_config,
+    collect_history,
+    copy_rates_from,
+    copy_rates_from_pos,
+    copy_rates_range,
+    copy_ticks_from,
+    copy_ticks_range,
+    history_deals,
+    history_orders,
+    last_error,
+    market_book,
+    orders,
+    positions,
+    symbol_info,
+    symbol_info_tick,
+    symbols,
+    terminal_info,
+    update_history,
+    update_history_with_config,
+    version,
+)
+from mt5cli.utils import Dataset
+
+_DEALS_FIXTURE: dict[str, list[object]] = {
+    "ticket": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14],
+    "position_id": [100, 100, 100, 0, 200, 200, 300, 400, 400, 500, 500, 600, 600, 600],
+    "symbol": [
+        "EURUSD",
+        "EURUSD",
+        "EURUSD",
+        "",
+        "EURUSD",
+        "EURUSD",
+        "GBPUSD",
+        "GBPUSD",
+        "GBPUSD",
+        "EURUSD",
+        "EURUSD",
+        "GBPUSD",
+        "GBPUSD",
+        "GBPUSD",
+    ],
+    "time": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14],
+    "type": [0, 0, 1, 2, 0, 1, 0, 0, 2, 0, 1, 0, 1, 1],
+    "entry": [0, 0, 1, 0, 0, 1, 0, 0, 2, 0, 3, 0, 2, 1],
+    "volume": [1.0, 3.0, 4.0, 0.0, 2.0, 2.0, 5.0, 1.0, 1.0, 2.0, 2.0, 3.0, 1.0, 3.0],
+    "price": [
+        1.10,
+        1.20,
+        1.50,
+        0.0,
+        2.00,
+        2.20,
+        1.30,
+        1.30,
+        1.40,
+        1.00,
+        1.05,
+        1.10,
+        9.99,
+        1.40,
+    ],
+    "profit": [0.0, 0.0, 10.0, 5.0, 0.0, 8.0, 0.0, 0.0, -1.0, 0.0, 3.0, 0.0, -2.0, 7.0],
+}
+
+
+@pytest.fixture
+def mock_client(mocker: MockerFixture) -> MagicMock:
+    """Create and patch a mock Mt5DataClient for SDK tests."""
+    client = MagicMock()
+    sample_df = pd.DataFrame({"col": [1]})
+    client.copy_rates_from_as_df.return_value = sample_df
+    client.copy_rates_from_pos_as_df.return_value = sample_df
+    client.copy_rates_range_as_df.return_value = sample_df
+    client.copy_ticks_from_as_df.return_value = sample_df
+    client.copy_ticks_range_as_df.return_value = sample_df
+    client.account_info_as_df.return_value = sample_df
+    client.terminal_info_as_df.return_value = sample_df
+    client.symbols_get_as_df.return_value = sample_df
+    client.symbol_info_as_df.return_value = sample_df
+    client.orders_get_as_df.return_value = sample_df
+    client.positions_get_as_df.return_value = sample_df
+    client.history_orders_get_as_df.return_value = sample_df
+    client.history_deals_get_as_df.return_value = sample_df
+    client.version_as_df.return_value = sample_df
+    client.last_error_as_df.return_value = sample_df
+    client.symbol_info_tick_as_df.return_value = sample_df
+    client.market_book_get_as_df.return_value = sample_df
+    mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=client)
+    return client
+
+
+def _build_history_client(mocker: MockerFixture) -> MagicMock:
+    """Build a mocked Mt5DataClient with per-symbol history results."""
+    client = MagicMock()
+
+    def _rates(**kwargs: object) -> pd.DataFrame:
+        return pd.DataFrame({
+            "time": [1],
+            "open": [1.0],
+            "symbol_arg": [kwargs.get("symbol")],
+        })
+
+    def _ticks(**kwargs: object) -> pd.DataFrame:
+        return pd.DataFrame({
+            "time": [1],
+            "bid": [1.0],
+            "symbol_arg": [kwargs.get("symbol")],
+        })
+
+    client.copy_rates_range_as_df.side_effect = _rates
+    client.copy_ticks_range_as_df.side_effect = _ticks
+
+    def _orders(**kwargs: object) -> pd.DataFrame:
+        return pd.DataFrame({"ticket": [10], "symbol": [kwargs.get("symbol")]})
+
+    def _deals(**kwargs: object) -> pd.DataFrame:
+        sym = kwargs.get("symbol")
+        df = pd.DataFrame(_DEALS_FIXTURE)
+        return df[df["symbol"] == sym].reset_index(drop=True)
+
+    client.history_orders_get_as_df.side_effect = _orders
+    client.history_deals_get_as_df.side_effect = _deals
+    mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=client)
+    return client
+
+
+class TestConnectionLifecycle:
+    """Tests for MT5 connection lifecycle helpers."""
+
+    def test_connected_client_shuts_down(self, mocker: MockerFixture) -> None:
+        """Test that _connected_client always shuts down."""
+        mock_client = MagicMock()
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=mock_client)
+        config = MagicMock()
+        with sdk._connected_client(config):  # type: ignore[reportPrivateUsage]
+            mock_client.initialize_and_login_mt5.assert_called_once()
+        mock_client.shutdown.assert_called_once()
+
+    def test_connected_client_shutdown_on_init_failure(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """Test that shutdown is called when initialize/login fails."""
+        mock_client = MagicMock()
+        mock_client.initialize_and_login_mt5.side_effect = RuntimeError(
+            "login failed",
+        )
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=mock_client)
+        with (
+            pytest.raises(RuntimeError, match="login failed"),
+            sdk._connected_client(MagicMock()),  # type: ignore[reportPrivateUsage]
+        ):
+            pass
+        mock_client.shutdown.assert_called_once()
+
+    def test_run_with_client_shutdown_on_error(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """Test that shutdown is called even when fetch raises."""
+        mock_client = MagicMock()
+        mock_client.account_info_as_df.side_effect = RuntimeError("boom")
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=mock_client)
+        with pytest.raises(RuntimeError, match="boom"):
+            sdk._run_with_client(  # type: ignore[reportPrivateUsage]
+                MagicMock(),
+                lambda c: c.account_info_as_df(),
+            )
+        mock_client.shutdown.assert_called_once()
+
+    def test_client_context_manager_reuses_connection(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """Test that context-managed client reuses one connection."""
+        mock_client = MagicMock()
+        mock_client.account_info_as_df.return_value = pd.DataFrame({"a": [1]})
+        mock_client.terminal_info_as_df.return_value = pd.DataFrame({"b": [2]})
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=mock_client)
+        with Mt5CliClient() as client:
+            client.account_info()
+            client.terminal_info()
+            assert client.config is not None
+        mock_client.initialize_and_login_mt5.assert_called_once()
+        mock_client.shutdown.assert_called_once()
+        assert mock_client.account_info_as_df.call_count == 1
+        assert mock_client.terminal_info_as_df.call_count == 1
+
+    def test_client_context_manager_shutdown_on_init_failure(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """Test that shutdown is called when context manager login fails."""
+        mock_client = MagicMock()
+        mock_client.initialize_and_login_mt5.side_effect = RuntimeError(
+            "login failed",
+        )
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=mock_client)
+        client = Mt5CliClient()
+        with pytest.raises(RuntimeError, match="login failed"), client:
+            pass
+        mock_client.shutdown.assert_called_once()
+        assert client._client is None  # type: ignore[reportPrivateUsage]
+
+    def test_exit_without_enter_is_noop(self) -> None:
+        """Test that __exit__ without __enter__ does not fail."""
+        client = Mt5CliClient()
+        client.__exit__(None, None, None)
+
+
+class TestModuleFunctions:
+    """Tests for module-level SDK wrappers."""
+
+    @pytest.mark.parametrize(
+        ("fn", "args", "method"),
+        [
+            (
+                copy_rates_from,
+                ("EURUSD", "M1", "2024-01-01", 10),
+                "copy_rates_from_as_df",
+            ),
+            (
+                copy_rates_from_pos,
+                ("EURUSD", "M1", 0, 10),
+                "copy_rates_from_pos_as_df",
+            ),
+            (
+                copy_ticks_from,
+                ("EURUSD", "2024-01-01", 10, "ALL"),
+                "copy_ticks_from_as_df",
+            ),
+            (
+                copy_ticks_range,
+                ("EURUSD", "2024-01-01", "2024-02-01", "ALL"),
+                "copy_ticks_range_as_df",
+            ),
+            (account_info, (), "account_info_as_df"),
+            (terminal_info, (), "terminal_info_as_df"),
+            (symbols, ("*USD*",), "symbols_get_as_df"),
+            (symbol_info, ("EURUSD",), "symbol_info_as_df"),
+            (orders, (), "orders_get_as_df"),
+            (positions, (), "positions_get_as_df"),
+            (history_orders, (), "history_orders_get_as_df"),
+            (history_deals, (), "history_deals_get_as_df"),
+            (version, (), "version_as_df"),
+            (last_error, (), "last_error_as_df"),
+            (symbol_info_tick, ("EURUSD",), "symbol_info_tick_as_df"),
+            (market_book, ("EURUSD",), "market_book_get_as_df"),
+        ],
+    )
+    def test_module_functions_delegate(
+        self,
+        mock_client: MagicMock,
+        fn: object,
+        args: tuple[object, ...],
+        method: str,
+    ) -> None:
+        """Test module-level functions call the expected client methods."""
+        config = build_config(login=123)
+        result = fn(*args, config=config)  # type: ignore[operator]
+        assert isinstance(result, pd.DataFrame)
+        getattr(mock_client, method).assert_called_once()
+
+
+class TestMt5CliClient:
+    """Tests for Mt5CliClient SDK methods."""
+
+    def test_copy_rates_range_returns_dataframe(
+        self,
+        mock_client: MagicMock,
+    ) -> None:
+        """Test that copy_rates_range returns a DataFrame."""
+        df = Mt5CliClient().copy_rates_range(
+            "EURUSD",
+            "D1",
+            "2024-01-01",
+            "2024-02-01",
+        )
+        assert isinstance(df, pd.DataFrame)
+        mock_client.copy_rates_range_as_df.assert_called_once_with(
+            symbol="EURUSD",
+            timeframe=16408,
+            date_from=datetime(2024, 1, 1, tzinfo=UTC),
+            date_to=datetime(2024, 2, 1, tzinfo=UTC),
+        )
+
+    def test_copy_ticks_from_parses_flags(
+        self,
+        mock_client: MagicMock,
+    ) -> None:
+        """Test that string tick flags are parsed."""
+        Mt5CliClient().copy_ticks_from("EURUSD", "2024-01-01", 100, "INFO")
+        mock_client.copy_ticks_from_as_df.assert_called_once_with(
+            symbol="EURUSD",
+            date_from=datetime(2024, 1, 1, tzinfo=UTC),
+            count=100,
+            flags=2,
+        )
+
+    def test_history_orders_accepts_string_dates(
+        self,
+        mock_client: MagicMock,
+    ) -> None:
+        """Test that string datetime inputs are parsed."""
+        Mt5CliClient().history_orders(
+            date_from="2024-01-01",
+            date_to="2024-02-01",
+        )
+        mock_client.history_orders_get_as_df.assert_called_once_with(
+            date_from=datetime(2024, 1, 1, tzinfo=UTC),
+            date_to=datetime(2024, 2, 1, tzinfo=UTC),
+            group=None,
+            symbol=None,
+            ticket=None,
+            position=None,
+        )
+
+    def test_module_function_delegates_to_client(
+        self,
+        mock_client: MagicMock,
+    ) -> None:
+        """Test module-level copy_rates_range delegates to the client."""
+        df = copy_rates_range(
+            "USDJPY",
+            "M1",
+            "2024-01-01",
+            "2024-02-01",
+        )
+        assert isinstance(df, pd.DataFrame)
+        mock_client.copy_rates_range_as_df.assert_called_once()
+
+
+class TestCollectHistory:
+    """Tests for collect_history SDK function."""
+
+    @pytest.fixture
+    def history_client(self, mocker: MockerFixture) -> MagicMock:
+        """Create a mocked Mt5DataClient with history-style DataFrames."""
+        return _build_history_client(mocker)
+
+    def test_collect_history_writes_all_tables(
+        self,
+        tmp_path: Path,
+        history_client: MagicMock,
+    ) -> None:
+        """Test that collect_history writes rates, ticks, and history tables."""
+        output = tmp_path / "history.db"
+        collect_history(
+            output,
+            ["EURUSD", "GBPUSD"],
+            "2024-01-01",
+            "2024-02-01",
+        )
+        assert history_client.copy_rates_range_as_df.call_count == 2
+        assert history_client.copy_ticks_range_as_df.call_count == 2
+        with sqlite3.connect(output) as conn:
+            tables = {
+                row[0]
+                for row in conn.execute(
+                    "SELECT name FROM sqlite_master WHERE type='table'",
+                ).fetchall()
+            }
+        assert {"rates", "ticks", "history_orders", "history_deals"} <= tables
+
+    def test_collect_history_with_views(
+        self,
+        tmp_path: Path,
+        history_client: MagicMock,  # noqa: ARG002
+    ) -> None:
+        """Test that with_views creates cash_events and positions views."""
+        output = tmp_path / "history.db"
+        collect_history(
+            output,
+            ["EURUSD", "GBPUSD"],
+            "2024-01-01",
+            "2024-02-01",
+            with_views=True,
+        )
+        with sqlite3.connect(output) as conn:
+            views = {
+                row[0]
+                for row in conn.execute(
+                    "SELECT name FROM sqlite_master WHERE type='view'",
+                ).fetchall()
+            }
+            positions = {
+                row[0]
+                for row in conn.execute(
+                    "SELECT position_id FROM positions_reconstructed",
+                ).fetchall()
+            }
+        assert {"cash_events", "positions_reconstructed"} <= views
+        assert set(positions) == {100, 200, 500, 600}
+
+    def test_collect_history_rates_table_has_timeframe(
+        self,
+        tmp_path: Path,
+        history_client: MagicMock,  # noqa: ARG002
+    ) -> None:
+        """Test that the rates table carries the requested timeframe value."""
+        output = tmp_path / "history.db"
+        collect_history(
+            output,
+            ["EURUSD"],
+            "2024-01-01",
+            "2024-02-01",
+            datasets={Dataset.rates},
+            timeframe="H1",
+        )
+        with sqlite3.connect(output) as conn:
+            rows = conn.execute(
+                "SELECT DISTINCT timeframe FROM rates",
+            ).fetchall()
+        assert rows == [(16385,)]
+
+    def test_collect_history_views_skipped_when_columns_missing(
+        self,
+        tmp_path: Path,
+        mocker: MockerFixture,
+        caplog: pytest.LogCaptureFixture,
+    ) -> None:
+        """Test that views are not created when required columns are missing."""
+        client = MagicMock()
+        client.copy_rates_range_as_df.return_value = pd.DataFrame({"x": [1]})
+        client.copy_ticks_range_as_df.return_value = pd.DataFrame({"x": [1]})
+        client.history_orders_get_as_df.return_value = pd.DataFrame({"x": [1]})
+        client.history_deals_get_as_df.return_value = pd.DataFrame({"x": [1]})
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=client)
+        output = tmp_path / "history.db"
+        with caplog.at_level(logging.WARNING, logger="mt5cli.sdk"):
+            collect_history(
+                output,
+                ["EURUSD"],
+                "2024-01-01",
+                "2024-02-01",
+                with_views=True,
+            )
+        with sqlite3.connect(output) as conn:
+            views = {
+                row[0]
+                for row in conn.execute(
+                    "SELECT name FROM sqlite_master WHERE type='view'",
+                ).fetchall()
+            }
+        assert "cash_events" not in views
+        assert "positions_reconstructed" not in views
+
+
+class TestUpdateHistory:
+    """Tests for update_history SDK functions."""
+
+    @pytest.fixture
+    def connected_client(self) -> MagicMock:
+        """Create a connected mock client without MT5 lifecycle patching."""
+        return MagicMock()
+
+    def test_update_history_appends_incrementally(
+        self,
+        connected_client: MagicMock,
+        mocker: MockerFixture,
+        tmp_path: Path,
+    ) -> None:
+        """Test sequential SQLite history updates use existing max timestamps."""
+        date_to = datetime(2024, 1, 2, tzinfo=UTC)
+        first_expected_start = datetime(2024, 1, 1, tzinfo=UTC)
+        second_expected_start = datetime(2024, 1, 1, 12, tzinfo=UTC)
+        rate_starts: list[datetime] = []
+        deal_starts: list[datetime] = []
+
+        def make_rates(**kwargs: object) -> pd.DataFrame:
+            assert kwargs["symbol"] == "EURUSD"
+            assert kwargs["timeframe"] == 1
+            assert kwargs["date_to"] == date_to
+            rate_starts.append(kwargs["date_from"])  # type: ignore[arg-type]
+            return pd.DataFrame({
+                "time": ["2024-01-01T12:00:00+00:00"],
+                "open": [1.0 + len(rate_starts) / 10],
+            })
+
+        def make_deals(**kwargs: object) -> pd.DataFrame:
+            assert kwargs["date_to"] == date_to
+            deal_starts.append(kwargs["date_from"])  # type: ignore[arg-type]
+            return pd.DataFrame({
+                "ticket": [10],
+                "position_id": [100],
+                "symbol": ["EURUSD"],
+                "time": ["2024-01-01T12:00:00+00:00"],
+                "type": [0],
+                "entry": [0],
+                "volume": [1.0],
+                "price": [1.1],
+                "profit": [0.0],
+            })
+
+        connected_client.copy_rates_range_as_df.side_effect = make_rates
+        connected_client.history_deals_get_as_df.side_effect = make_deals
+        mocker.patch("mt5cli.sdk.Mt5DataClient")
+        output = tmp_path / "incremental-history.db"
+
+        for _ in range(2):
+            update_history(
+                client=connected_client,
+                output=output,
+                symbols=["EURUSD"],
+                datasets={Dataset.rates, Dataset.history_deals},
+                timeframes=["M1"],
+                lookback_hours=24,
+                date_to=date_to,
+                with_views=True,
+            )
+
+        assert rate_starts == [first_expected_start, second_expected_start]
+        assert deal_starts == [first_expected_start, first_expected_start]
+        connected_client.initialize_and_login_mt5.assert_not_called()
+        connected_client.shutdown.assert_not_called()
+        with sqlite3.connect(output) as conn:
+            assert conn.execute("SELECT COUNT(*) FROM rates").fetchone() == (1,)
+            assert conn.execute("SELECT open FROM rates").fetchone() == (1.2,)
+            assert conn.execute(
+                "SELECT COUNT(*) FROM history_deals",
+            ).fetchone() == (1,)
+            assert conn.execute(
+                "SELECT name FROM sqlite_master WHERE name = 'cash_events'",
+            ).fetchone() == ("cash_events",)
+
+    def test_update_history_rejects_invalid_inputs(
+        self,
+        connected_client: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        """Test validation errors for incremental history updates."""
+        output = tmp_path / "invalid-update.db"
+        with pytest.raises(ValueError, match="At least one symbol"):
+            update_history(
+                client=connected_client,
+                output=output,
+                symbols=[],
+            )
+        with pytest.raises(ValueError, match="lookback_hours must be positive"):
+            update_history(
+                client=connected_client,
+                output=output,
+                symbols=["EURUSD"],
+                lookback_hours=0,
+            )
+        with pytest.raises(ValueError, match="Invalid timeframe"):
+            update_history(
+                client=connected_client,
+                output=output,
+                symbols=["EURUSD"],
+                datasets={Dataset.rates},
+                timeframes=["BAD"],
+            )
+        with pytest.raises(ValueError, match="Invalid tick flags"):
+            update_history(
+                client=connected_client,
+                output=output,
+                symbols=["EURUSD"],
+                datasets={Dataset.ticks},
+                flags="BAD",
+            )
+
+    def test_update_history_noops_for_empty_datasets(
+        self,
+        connected_client: MagicMock,
+        mocker: MockerFixture,
+        tmp_path: Path,
+    ) -> None:
+        """Test empty dataset selection skips MT5 and SQLite writes."""
+        writer = mocker.patch("mt5cli.sdk.write_incremental_datasets")
+        connect = mocker.patch("mt5cli.sdk.sqlite3.connect")
+        update_history(
+            client=connected_client,
+            output=tmp_path / "empty-datasets.db",
+            symbols=["EURUSD"],
+            datasets=set(),
+        )
+        writer.assert_not_called()
+        connect.assert_not_called()
+
+    def test_update_history_uses_all_default_timeframes(
+        self,
+        connected_client: MagicMock,
+        mocker: MockerFixture,
+        tmp_path: Path,
+    ) -> None:
+        """Test that timeframes=None writes rates for all default MT5 timeframes."""
+        timeframes_written: list[int] = []
+
+        def capture(
+            *args: object,
+            **_kwargs: object,
+        ) -> tuple[set[Dataset], dict[Dataset, set[str]]]:
+            timeframes_written.extend(args[4])  # type: ignore[arg-type]
+            return set(), {}
+
+        mocker.patch("mt5cli.sdk.write_incremental_datasets", side_effect=capture)
+        update_history(
+            client=connected_client,
+            output=tmp_path / "default-timeframes.db",
+            symbols=["EURUSD"],
+            datasets={Dataset.rates},
+            timeframes=None,
+            lookback_hours=1,
+            date_to=datetime(2024, 1, 1, tzinfo=UTC),
+        )
+        assert len(timeframes_written) == len(DEFAULT_HISTORY_TIMEFRAMES)
+
+    def test_update_history_uses_specified_timeframes(
+        self,
+        connected_client: MagicMock,
+        mocker: MockerFixture,
+        tmp_path: Path,
+    ) -> None:
+        """Test explicit timeframes limit rate updates."""
+        timeframes_written: list[int] = []
+
+        def capture(
+            *args: object,
+            **_kwargs: object,
+        ) -> tuple[set[Dataset], dict[Dataset, set[str]]]:
+            timeframes_written.extend(args[4])  # type: ignore[arg-type]
+            return set(), {}
+
+        mocker.patch("mt5cli.sdk.write_incremental_datasets", side_effect=capture)
+        update_history(
+            client=connected_client,
+            output=tmp_path / "specific-timeframes.db",
+            symbols=["EURUSD"],
+            datasets={Dataset.rates},
+            timeframes=["M1", "H1"],
+            lookback_hours=1,
+            date_to=datetime(2024, 1, 1, tzinfo=UTC),
+        )
+        assert timeframes_written == [1, 16385]
+
+    def test_update_history_updates_ticks_and_orders(
+        self,
+        connected_client: MagicMock,
+        tmp_path: Path,
+    ) -> None:
+        """Test incremental update writes selected ticks and orders datasets."""
+        date_to = datetime(2024, 1, 2, tzinfo=UTC)
+        expected_start = datetime(2024, 1, 1, tzinfo=UTC)
+
+        def make_ticks(**kwargs: object) -> pd.DataFrame:
+            assert kwargs["symbol"] == "EURUSD"
+            assert kwargs["date_from"] == expected_start
+            assert kwargs["date_to"] == date_to
+            assert kwargs["flags"] == 1
+            return pd.DataFrame({
+                "time": ["2024-01-01T12:00:00+00:00"],
+                "time_msc": [1_704_110_400_000],
+                "bid": [1.1],
+            })
+
+        def make_orders(**kwargs: object) -> pd.DataFrame:
+            assert kwargs["symbol"] == "EURUSD"
+            assert kwargs["date_from"] == expected_start
+            assert kwargs["date_to"] == date_to
+            return pd.DataFrame({
+                "ticket": [1],
+                "symbol": ["EURUSD"],
+                "time": ["2024-01-01T12:00:00+00:00"],
+                "type": [0],
+            })
+
+        connected_client.copy_ticks_range_as_df.side_effect = make_ticks
+        connected_client.history_orders_get_as_df.side_effect = make_orders
+        output = tmp_path / "ticks-orders.db"
+        update_history(
+            client=connected_client,
+            output=output,
+            symbols=["EURUSD"],
+            datasets={Dataset.ticks, Dataset.history_orders},
+            lookback_hours=24,
+            date_to=date_to,
+        )
+        with sqlite3.connect(output) as conn:
+            assert conn.execute("SELECT COUNT(*) FROM ticks").fetchone() == (1,)
+            assert conn.execute(
+                "SELECT COUNT(*) FROM history_orders",
+            ).fetchone() == (1,)
+
+    def test_update_history_with_config_opens_and_closes_connection(
+        self,
+        mocker: MockerFixture,
+        tmp_path: Path,
+    ) -> None:
+        """Test update_history_with_config manages MT5 connection lifecycle."""
+        mock_client = MagicMock()
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=mock_client)
+        updater = mocker.patch("mt5cli.sdk.update_history")
+        update_history_with_config(
+            output=tmp_path / "config-wrapper.db",
+            symbols=["EURUSD"],
+            datasets={Dataset.history_deals},
+            timeframes=["M1"],
+            flags="ALL",
+            lookback_hours=1,
+            date_to=datetime(2024, 1, 1, tzinfo=UTC),
+            deduplicate=False,
+            create_rate_views=False,
+            with_views=True,
+            include_account_events=False,
+        )
+        mock_client.initialize_and_login_mt5.assert_called_once()
+        mock_client.shutdown.assert_called_once()
+        updater.assert_called_once()
+        assert updater.call_args.kwargs == {
+            "client": mock_client,
+            "output": tmp_path / "config-wrapper.db",
+            "symbols": ["EURUSD"],
+            "datasets": {Dataset.history_deals},
+            "timeframes": ["M1"],
+            "flags": "ALL",
+            "lookback_hours": 1,
+            "date_to": datetime(2024, 1, 1, tzinfo=UTC),
+            "deduplicate": False,
+            "create_rate_views": False,
+            "with_views": True,
+            "include_account_events": False,
+        }
+
+    def test_update_history_with_config_validates_before_connecting(
+        self,
+        mocker: MockerFixture,
+        tmp_path: Path,
+    ) -> None:
+        """Test invalid inputs fail before MT5 is initialized."""
+        mock_client = MagicMock()
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=mock_client)
+        with pytest.raises(ValueError, match="lookback_hours must be positive"):
+            update_history_with_config(
+                output=tmp_path / "invalid-config.db",
+                symbols=["EURUSD"],
+                lookback_hours=0,
+            )
+        mock_client.initialize_and_login_mt5.assert_not_called()
+        mock_client.shutdown.assert_not_called()
+
+    def test_update_history_with_config_noops_for_empty_datasets(
+        self,
+        mocker: MockerFixture,
+        tmp_path: Path,
+    ) -> None:
+        """Test empty dataset selection skips MT5 initialization."""
+        mock_client = MagicMock()
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=mock_client)
+        updater = mocker.patch("mt5cli.sdk.update_history")
+        update_history_with_config(
+            output=tmp_path / "empty-config.db",
+            symbols=["EURUSD"],
+            datasets=set(),
+        )
+        mock_client.initialize_and_login_mt5.assert_not_called()
+        mock_client.shutdown.assert_not_called()
+        updater.assert_not_called()
+
+    def test_update_history_defaults_date_to_now(
+        self,
+        connected_client: MagicMock,
+        mocker: MockerFixture,
+        tmp_path: Path,
+    ) -> None:
+        """Test update_history uses current UTC time when date_to is omitted."""
+        captured: dict[str, datetime] = {}
+
+        def capture(
+            *args: object,
+            **_kwargs: object,
+        ) -> tuple[set[Dataset], dict[Dataset, set[str]]]:
+            captured["end"] = args[7]  # type: ignore[assignment]
+            return set(), {}
+
+        mocker.patch("mt5cli.sdk.write_incremental_datasets", side_effect=capture)
+        before = datetime.now(UTC)
+        update_history(
+            client=connected_client,
+            output=tmp_path / "now-default.db",
+            symbols=["EURUSD"],
+            datasets={Dataset.rates},
+            timeframes=["M1"],
+            lookback_hours=12,
+        )
+        after = datetime.now(UTC)
+        assert before <= captured["end"] <= after
@@ -0,0 +1,335 @@
+"""Tests for mt5cli.utils module."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+import pandas as pd
+import pytest
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from mt5cli.utils import (
+    DATETIME_TYPE,
+    REQUEST_TYPE,
+    TICK_FLAG_MAP,
+    TICK_FLAGS_TYPE,
+    TIMEFRAME_MAP,
+    TIMEFRAME_TYPE,
+    Dataset,
+    detect_format,
+    export_dataframe,
+    parse_datetime,
+    parse_request,
+    parse_tick_flags,
+    parse_timeframe,
+)
+
+# ---------------------------------------------------------------------------
+# detect_format
+# ---------------------------------------------------------------------------
+
+
+class TestDetectFormat:
+    """Tests for detect_format."""
+
+    def test_explicit_format_returned(self, tmp_path: Path) -> None:
+        """Test that explicit format overrides extension."""
+        result = detect_format(tmp_path / "data.txt", explicit_format="csv")
+        assert result == "csv"
+
+    @pytest.mark.parametrize(
+        ("filename", "expected"),
+        [
+            ("data.csv", "csv"),
+            ("data.json", "json"),
+            ("data.parquet", "parquet"),
+            ("data.pq", "parquet"),
+            ("data.db", "sqlite3"),
+            ("data.sqlite", "sqlite3"),
+            ("data.sqlite3", "sqlite3"),
+            ("DATA.CSV", "csv"),
+            ("DATA.JSON", "json"),
+            ("DATA.PARQUET", "parquet"),
+        ],
+    )
+    def test_auto_detect_from_extension(
+        self,
+        tmp_path: Path,
+        filename: str,
+        expected: str,
+    ) -> None:
+        """Test format auto-detection from file extension."""
+        result = detect_format(tmp_path / filename)
+        assert result == expected
+
+    def test_unknown_extension_raises(self, tmp_path: Path) -> None:
+        """Test that unknown extension raises ValueError."""
+        with pytest.raises(ValueError, match="Cannot detect format"):
+            detect_format(tmp_path / "data.xyz")
+
+
+# ---------------------------------------------------------------------------
+# export_dataframe
+# ---------------------------------------------------------------------------
+
+
+class TestExportDataframe:
+    """Tests for export_dataframe."""
+
+    @pytest.fixture
+    def sample_df(self) -> pd.DataFrame:
+        """Create a sample DataFrame for testing."""
+        return pd.DataFrame({"a": [1, 2, 3], "b": ["x", "y", "z"]})
+
+    def test_export_csv(self, tmp_path: Path, sample_df: pd.DataFrame) -> None:
+        """Test CSV export."""
+        output = tmp_path / "out.csv"
+        export_dataframe(sample_df, output, "csv")
+        result = pd.read_csv(output)
+        pd.testing.assert_frame_equal(result, sample_df)
+
+    def test_export_json(self, tmp_path: Path, sample_df: pd.DataFrame) -> None:
+        """Test JSON export."""
+        output = tmp_path / "out.json"
+        export_dataframe(sample_df, output, "json")
+        with output.open() as f:
+            records = json.load(f)
+        assert len(records) == 3
+        assert records[0]["a"] == 1
+
+    def test_export_parquet(self, tmp_path: Path, sample_df: pd.DataFrame) -> None:
+        """Test Parquet export."""
+        output = tmp_path / "out.parquet"
+        export_dataframe(sample_df, output, "parquet")
+        result = pd.read_parquet(output)
+        pd.testing.assert_frame_equal(result, sample_df)
+
+    def test_export_sqlite3(self, tmp_path: Path, sample_df: pd.DataFrame) -> None:
+        """Test SQLite3 export."""
+        output = tmp_path / "out.db"
+        export_dataframe(sample_df, output, "sqlite3", table_name="test_table")
+        with sqlite3.connect(output) as conn:
+            result = pd.read_sql(  # type: ignore[reportUnknownMemberType]
+                "SELECT * FROM test_table",
+                conn,
+            )
+        pd.testing.assert_frame_equal(result, sample_df)
+
+    def test_unsupported_format_raises(
+        self,
+        tmp_path: Path,
+        sample_df: pd.DataFrame,
+    ) -> None:
+        """Test that unsupported format raises ValueError."""
+        with pytest.raises(ValueError, match="Unsupported output format"):
+            export_dataframe(sample_df, tmp_path / "out.txt", "xml")
+
+
+# ---------------------------------------------------------------------------
+# Parse helpers
+# ---------------------------------------------------------------------------
+
+
+class TestParseDatetime:
+    """Tests for parse_datetime."""
+
+    def test_valid_date(self) -> None:
+        """Test parsing a date string."""
+        result = parse_datetime("2024-01-15")
+        assert result == datetime(2024, 1, 15, tzinfo=UTC)
+
+    def test_valid_datetime_with_tz(self) -> None:
+        """Test parsing a datetime with timezone."""
+        result = parse_datetime("2024-01-15T12:00:00+00:00")
+        assert result == datetime(2024, 1, 15, 12, 0, 0, tzinfo=UTC)
+
+    def test_invalid_format_raises(self) -> None:
+        """Test that invalid format raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid datetime"):
+            parse_datetime("not-a-date")
+
+
+class TestParseTimeframe:
+    """Tests for parse_timeframe."""
+
+    @pytest.mark.parametrize(
+        ("value", "expected"),
+        [("M1", 1), ("h1", 16385), ("D1", 16408), ("MN1", 49153)],
+    )
+    def test_named_timeframe(self, value: str, expected: int) -> None:
+        """Test parsing named timeframes."""
+        assert parse_timeframe(value) == expected
+
+    def test_integer_timeframe(self) -> None:
+        """Test parsing integer timeframe."""
+        assert parse_timeframe("42") == 42
+
+    def test_invalid_timeframe_raises(self) -> None:
+        """Test that invalid timeframe raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid timeframe"):
+            parse_timeframe("INVALID")
+
+
+class TestParseTickFlags:
+    """Tests for parse_tick_flags."""
+
+    @pytest.mark.parametrize(
+        ("value", "expected"),
+        [("ALL", 1), ("info", 2), ("TRADE", 4)],
+    )
+    def test_named_flag(self, value: str, expected: int) -> None:
+        """Test parsing named tick flags."""
+        assert parse_tick_flags(value) == expected
+
+    def test_integer_flag(self) -> None:
+        """Test parsing integer tick flag."""
+        assert parse_tick_flags("7") == 7
+
+    def test_invalid_flag_raises(self) -> None:
+        """Test that invalid flag raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid tick flags"):
+            parse_tick_flags("INVALID")
+
+
+# ---------------------------------------------------------------------------
+# parse_request
+# ---------------------------------------------------------------------------
+
+
+class TestParseRequest:
+    """Tests for parse_request."""
+
+    def test_inline_json(self) -> None:
+        """Test parsing an inline JSON object string."""
+        result = parse_request('{"action": 1, "symbol": "EURUSD"}')
+        assert result == {"action": 1, "symbol": "EURUSD"}
+
+    def test_file_reference(self, tmp_path: Path) -> None:
+        """Test parsing JSON from a file via the @path syntax."""
+        path = tmp_path / "req.json"
+        path.write_text('{"action": 2}', encoding="utf-8")
+        result = parse_request(f"@{path}")
+        assert result == {"action": 2}
+
+    def test_invalid_json_raises(self) -> None:
+        """Test that invalid JSON raises ValueError."""
+        with pytest.raises(ValueError, match="Invalid JSON request"):
+            parse_request("not json")
+
+    def test_non_object_raises(self) -> None:
+        """Test that a non-object JSON raises ValueError."""
+        with pytest.raises(ValueError, match="must be a JSON object"):
+            parse_request("[1, 2, 3]")
+
+    def test_missing_file_raises(self, tmp_path: Path) -> None:
+        """Test that a missing request file raises ValueError."""
+        path = tmp_path / "missing.json"
+        with pytest.raises(ValueError, match="Failed to read JSON request file"):
+            parse_request(f"@{path}")
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+
+class TestConstants:
+    """Tests for module constants."""
+
+    def test_timeframe_map_has_expected_keys(self) -> None:
+        """Test that TIMEFRAME_MAP contains standard timeframes."""
+        for key in ("M1", "M5", "M15", "M30", "H1", "H4", "D1", "W1", "MN1"):
+            assert key in TIMEFRAME_MAP
+
+    def test_tick_flag_map_has_expected_keys(self) -> None:
+        """Test that TICK_FLAG_MAP contains standard flags."""
+        assert set(TICK_FLAG_MAP) == {"ALL", "INFO", "TRADE"}
+
+    @pytest.mark.parametrize(
+        ("dataset", "expected"),
+        [
+            (Dataset.rates, "rates"),
+            (Dataset.ticks, "ticks"),
+            (Dataset.history_orders, "history_orders"),
+            (Dataset.history_deals, "history_deals"),
+        ],
+    )
+    def test_dataset_table_name(self, dataset: Dataset, expected: str) -> None:
+        """Test dataset SQLite table names."""
+        assert dataset.table_name == expected
+
+
+# ---------------------------------------------------------------------------
+# Click ParamTypes
+# ---------------------------------------------------------------------------
+
+
+class TestDateTimeType:
+    """Tests for _DateTimeType."""
+
+    def test_convert_string(self) -> None:
+        """Test converting a string to datetime."""
+        result = DATETIME_TYPE.convert("2024-06-15", None, None)
+        assert result == datetime(2024, 6, 15, tzinfo=UTC)
+
+    def test_convert_datetime_passthrough(self) -> None:
+        """Test that datetime values pass through unchanged."""
+        dt = datetime(2024, 1, 1, tzinfo=UTC)
+        assert DATETIME_TYPE.convert(dt, None, None) is dt
+
+    def test_convert_invalid(self) -> None:
+        """Test that invalid values raise BadParameter."""
+        with pytest.raises(Exception, match="Invalid datetime"):
+            DATETIME_TYPE.convert("bad", None, None)
+
+
+class TestTimeframeType:
+    """Tests for _TimeframeType."""
+
+    def test_convert_string(self) -> None:
+        """Test converting a string to timeframe integer."""
+        assert TIMEFRAME_TYPE.convert("H1", None, None) == 16385
+
+    def test_convert_int_passthrough(self) -> None:
+        """Test that integer values pass through unchanged."""
+        assert TIMEFRAME_TYPE.convert(42, None, None) == 42
+
+    def test_convert_invalid(self) -> None:
+        """Test that invalid values raise BadParameter."""
+        with pytest.raises(Exception, match="Invalid timeframe"):
+            TIMEFRAME_TYPE.convert("bad", None, None)
+
+
+class TestTickFlagsType:
+    """Tests for _TickFlagsType."""
+
+    def test_convert_string(self) -> None:
+        """Test converting a string to tick flags integer."""
+        assert TICK_FLAGS_TYPE.convert("ALL", None, None) == 1
+
+    def test_convert_int_passthrough(self) -> None:
+        """Test that integer values pass through unchanged."""
+        assert TICK_FLAGS_TYPE.convert(7, None, None) == 7
+
+    def test_convert_invalid(self) -> None:
+        """Test that invalid values raise BadParameter."""
+        with pytest.raises(Exception, match="Invalid tick flags"):
+            TICK_FLAGS_TYPE.convert("bad", None, None)
+
+
+class TestRequestType:
+    """Tests for _RequestType."""
+
+    def test_convert_string(self) -> None:
+        """Test converting a JSON string to a request dictionary."""
+        assert REQUEST_TYPE.convert('{"action": 1}', None, None) == {"action": 1}
+
+    def test_convert_invalid(self) -> None:
+        """Test that invalid values raise BadParameter."""
+        with pytest.raises(Exception, match="Invalid JSON request"):
+            REQUEST_TYPE.convert("bad", None, None)
@@ -234,11 +234,11 @@ wheels = [

 [[package]]
 name = "idna"
-version = "3.13"
+version = "3.15"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ce/cc/762dfb036166873f0059f3b7de4565e1b5bc3d6f28a414c13da27e442f99/idna-3.13.tar.gz", hash = "sha256:585ea8fe5d69b9181ec1afba340451fba6ba764af97026f92a91d4eef164a242", size = 194210, upload-time = "2026-04-22T16:42:42.314Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/82/77/7b3966d0b9d1d31a36ddf1746926a11dface89a83409bf1483f0237aa758/idna-3.15.tar.gz", hash = "sha256:ca962446ea538f7092a95e057da437618e886f4d349216d2b1e294abfdb65fdc", size = 199245, upload-time = "2026-05-12T22:45:57.011Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/5d/13/ad7d7ca3808a898b4612b6fe93cde56b53f3034dcde235acb1f0e1df24c6/idna-3.13-py3-none-any.whl", hash = "sha256:892ea0cde124a99ce773decba204c5552b69c3c67ffd5f232eb7696135bc8bb3", size = 68629, upload-time = "2026-04-22T16:42:40.909Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/23/408243171aa9aaba178d3e2559159c24c1171a641aa83b67bdd3394ead8e/idna-3.15-py3-none-any.whl", hash = "sha256:048adeaf8c2d788c40fee287673ccaa74c24ffd8dcf09ffa555a2fbb59f10ac8", size = 72340, upload-time = "2026-05-12T22:45:55.733Z" },
 ]

 [[package]]
@@ -487,7 +487,7 @@ wheels = [

 [[package]]
 name = "mt5cli"
-version = "0.1.0"
+version = "0.4.2"
 source = { editable = "." }
 dependencies = [
    { name = "click" },
@@ -845,15 +845,15 @@ wheels = [

 [[package]]
 name = "pymdown-extensions"
-version = "10.21.2"
+version = "10.21.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
    { name = "markdown" },
    { name = "pyyaml" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/df/08/f1c908c581fd11913da4711ea7ba32c0eee40b0190000996bb863b0c9349/pymdown_extensions-10.21.2.tar.gz", hash = "sha256:c3f55a5b8a1d0edf6699e35dcbea71d978d34ff3fa79f3d807b8a5b3fa90fbdc", size = 853922, upload-time = "2026-03-29T15:01:55.233Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/9e/26/d1015444da4d952a1ca487a236b522eb979766f0295a0bd0c5fc089989a9/pymdown_extensions-10.21.3.tar.gz", hash = "sha256:72cfcf55f07aea0d4af2c4f11dd4e52466ddfb1bb819673146398e0bd3a77354", size = 854140, upload-time = "2026-05-13T12:57:32.267Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/f7/27/a2fc51a4a122dfd1015e921ae9d22fee3d20b0b8080d9a704578bf9deece/pymdown_extensions-10.21.2-py3-none-any.whl", hash = "sha256:5c0fd2a2bea14eb39af8ff284f1066d898ab2187d81b889b75d46d4348c01638", size = 268901, upload-time = "2026-03-29T15:01:53.244Z" },
+    { url = "https://files.pythonhosted.org/packages/7e/85/545a951eecc270fcd688288c600017e2050a1aacb56c711d208586d3e470/pymdown_extensions-10.21.3-py3-none-any.whl", hash = "sha256:d7a5d08014fc571e80ca21dd6f854e31f94c489800350564d55d15b3c41e76b6", size = 269002, upload-time = "2026-05-13T12:57:30.296Z" },
 ]

 [[package]]
@@ -1126,11 +1126,11 @@ wheels = [

 [[package]]
 name = "urllib3"
-version = "2.6.3"
+version = "2.7.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" },
 ]

 [[package]]
Author	SHA1	Message	Date
Daichi Narushima	756faf747b	Rename sqlite_history module to history (#17 ) * Rename sqlite_history module to history. Drop the sqlite-specific prefix now that history collection is the primary module name across SDK, tests, and docs. Co-authored-by: Cursor <cursoragent@cursor.com> * Address PR review feedback for history module rename. Add a sqlite_history compatibility shim, clarify docs naming, and align the module docstring with the collect-history SQLite scope. Co-authored-by: Cursor <cursoragent@cursor.com> * Remove sqlite_history compatibility shim. The rename to mt5cli.history is intentionally breaking; downstream code should update imports rather than rely on a deprecated re-export path. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>	2026-06-09 02:40:25 +09:00
Daichi Narushima	c4232bf44d	Add incremental SQLite history SDK (#16 ) * Add incremental SQLite history SDK for automated pipelines. Extract sqlite history helpers into a dedicated module and expose update_history APIs that resume from existing MAX(time) values instead of re-fetching fixed date ranges. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix incremental history deals and stale rate view cleanup. Fetch account events once during incremental updates, drop stale rate_* views when timeframes change, and avoid SQLite variable limits on wide frames. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix incremental deal filtering edge cases Co-authored-by: Cursor <cursoragent@cursor.com> * Address PR review feedback for incremental SQLite history. Make rate views collision-free, batch incremental resume queries, scope deduplication to appended boundaries, validate before opening MT5, use atomic SQLite transactions, and expand docs/tests for the new helpers. Co-authored-by: Cursor <cursoragent@cursor.com> * Document collect-history SQLite schema with ER diagram. Co-authored-by: Cursor <cursoragent@cursor.com> * Fix account-event filtering and drop legacy rates resume. Account events must follow only account_event_start, not per-symbol trade cursors. Require normalized rates schema and fail fast when timeframe is missing. Co-authored-by: Cursor <cursoragent@cursor.com> * Validate normalized rates schema before incremental resume. Require symbol, timeframe, and time on existing rates tables with clear ValueError messages, and add regression tests for malformed schemas. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>	2026-06-09 01:28:22 +09:00
Daichi Narushima	5b44318d55	Add programmatic SDK and refactor mt5cli into cli, sdk, and utils (#15 ) * Refactor cli.py into cli and utils modules Extract constants, enums, Click parameter types, and parse/export utility functions into a new mt5cli/utils.py module, keeping the typer app, commands, and collect-history SQLite helpers in cli.py. https://claude.ai/code/session_016JwSEhPyq6phXySktQ1FGU * Address review comments * Add programmatic SDK layer for read-only MT5 data collection. Expose Mt5CliClient and collect_history through the package API while keeping CLI commands as thin adapters over the SDK. Co-authored-by: Cursor <cursoragent@cursor.com> * Harden SDK connection lifecycle and scope internal helpers as private. Co-authored-by: Cursor <cursoragent@cursor.com> * Export build_config in the public API and bump version to 0.4.0. Co-authored-by: Cursor <cursoragent@cursor.com> * Remove duplicate scripts/ in favor of local-qa skill script. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>	2026-06-08 22:54:53 +09:00
dceoy	7f70073301	Update pyproject.toml	2026-06-07 23:47:32 +09:00
Daichi Narushima	da74c11087	Add collect-history command for bulk data collection (#14 ) * Add collect-history command for bulk SQLite export Bundles rates, ticks, history-orders, and history-deals for one or more symbols into a single SQLite database. Tick collection uses copy_ticks_range_as_df with a --flags option defaulting to ALL. With --with-views, optional cash_events and positions_reconstructed views are derived from history_deals when the required columns are present. * Extend collect-history with datasets, if-exists, timeframe, view fixes - Fetch history-orders and history-deals per symbol so --symbol applies consistently across all four datasets. - Add repeatable --dataset (rates, ticks, history-orders, history-deals) so ticks are no longer required and any subset can be collected. - Add --if-exists append\|replace\|fail to control SQLite table conflict behavior instead of hard-coding replace. - Record the requested timeframe in a timeframe column on the rates table so appended runs at different timeframes stay distinguishable. - Fix positions_reconstructed to exclude positions with no closing deals, use volume-weighted open/close prices, and report reversal deals (DEAL_ENTRY_INOUT) via volume_reversal / reversal_count without contributing to weighted prices. - Update tests, README, docs, and skill to match. * Address collect-history review feedback * Stream collect-history writes per symbol * Address PR cleanup for collect-history --------- Co-authored-by: Claude <noreply@anthropic.com>	2026-05-29 01:22:59 +09:00
Daichi Narushima	c45efb953c	Update local QA skill workflow (#13 )	2026-05-25 02:12:28 +09:00
dceoy	c1eea3fa3d	Update .github/workflows/ci.yml	2026-05-25 01:48:43 +09:00
github-actions[bot]	62e5f438f0	Merge pull request #12 from dceoy/dependabot/uv/uv-d665ee01e3 Bump idna from 3.13 to 3.15 in the uv group across 1 directory	2026-05-19 21:12:38 +00:00
dependabot[bot]	50f62bca73	Bump idna from 3.13 to 3.15 in the uv group across 1 directory Bumps the uv group with 1 update in the / directory: [idna](https://github.com/kjd/idna). Updates `idna` from 3.13 to 3.15 - [Release notes](https://github.com/kjd/idna/releases) - [Changelog](https://github.com/kjd/idna/blob/master/HISTORY.md) - [Commits](https://github.com/kjd/idna/compare/v3.13...v3.15) --- updated-dependencies: - dependency-name: idna dependency-version: '3.15' dependency-type: indirect dependency-group: uv ... Signed-off-by: dependabot[bot] <support@github.com>	2026-05-19 21:11:32 +00:00
github-actions[bot]	0b7dfdc621	Merge pull request #11 from dceoy/dependabot/uv/uv-ab67d3f053 Bump pymdown-extensions from 10.21.2 to 10.21.3 in the uv group across 1 directory	2026-05-19 20:48:47 +00:00
dependabot[bot]	bab776e700	Bump pymdown-extensions in the uv group across 1 directory Bumps the uv group with 1 update in the / directory: [pymdown-extensions](https://github.com/facelessuser/pymdown-extensions). Updates `pymdown-extensions` from 10.21.2 to 10.21.3 - [Release notes](https://github.com/facelessuser/pymdown-extensions/releases) - [Commits](https://github.com/facelessuser/pymdown-extensions/compare/10.21.2...10.21.3) --- updated-dependencies: - dependency-name: pymdown-extensions dependency-version: 10.21.3 dependency-type: direct:development dependency-group: uv ... Signed-off-by: dependabot[bot] <support@github.com>	2026-05-19 20:47:23 +00:00
github-actions[bot]	9bf9a6a72c	Merge pull request #10 from dceoy/dependabot/uv/uv-c30c77f42d Bump urllib3 from 2.6.3 to 2.7.0 in the uv group across 1 directory	2026-05-11 18:22:00 +00:00
dependabot[bot]	d7594ddc43	Bump urllib3 from 2.6.3 to 2.7.0 in the uv group across 1 directory Bumps the uv group with 1 update in the / directory: [urllib3](https://github.com/urllib3/urllib3). Updates `urllib3` from 2.6.3 to 2.7.0 - [Release notes](https://github.com/urllib3/urllib3/releases) - [Changelog](https://github.com/urllib3/urllib3/blob/main/CHANGES.rst) - [Commits](https://github.com/urllib3/urllib3/compare/2.6.3...2.7.0) --- updated-dependencies: - dependency-name: urllib3 dependency-version: 2.7.0 dependency-type: indirect dependency-group: uv ... Signed-off-by: dependabot[bot] <support@github.com>	2026-05-11 18:20:57 +00:00
Daichi Narushima	b8ce76c9d6	Add CLI commands for remaining pdmt5.dataframe methods (#9 ) * Add CLI commands for remaining pdmt5.dataframe methods Add the following subcommands so the CLI fully covers pdmt5.dataframe's public _as_df methods: - version - last-error - symbol-info-tick - market-book - order-check (request via inline JSON or @path/to/file.json) - order-send (request via inline JSON or @path/to/file.json) Also export a new parse_request helper for parsing JSON order requests, add tests for every new command, and update the README and docs command tables. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Bump version to 0.2.0 Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com> * Address PR review feedback Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Harden CLI error assertions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>	2026-04-26 21:50:19 +09:00
dceoy	5750625e14	Remove python-package-release job	2026-04-26 06:21:18 +09:00
Daichi Narushima	2cf4d1cf6b	Update GitHub workflows to use new reusable workflow parameters (#8 )	2026-04-23 06:01:54 +09:00