[codex] fix mt5 adapter APIs (#36)

* fix mt5 adapter APIs

* address PR feedback

* fix zero ratio minimum volume sizing

* Bump version to v0.8.0

.agents/skills/pr-feedback-triage/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: pr-feedback-triage
+description: Triage pull request review comments into fixes, replies, clarification requests, or open follow-ups while respecting safe execution modes.
+---
+
+# PR Feedback Triage
+
+Triage pull request review feedback, decide what action each thread needs, make focused fixes when allowed, and report or resolve only what is actually handled.
+
+## When to Use
+
+- A PR has review comments, requested changes, unresolved review threads, or bot review findings.
+- The user asks to address, respond to, or resolve PR feedback.
+- The user provides a PR URL/number, a branch with an associated PR, or copied comments.
+
+Do not use this skill for a first-pass code review with no existing feedback; use a code review skill instead.
+
+## Inputs
+
+- Pull request URL or number, or a current branch that has an associated pull request.
+- Repository checkout or platform access sufficient to inspect the PR diff and review feedback.
+- Optional reviewer priorities from the user, such as "only address blocking comments" or "do not reply on the PR platform".
+- Optional operating mode flags: `dry_run`, `no_push`, and `no_reply`.
+
+If no PR or review comments are identifiable, ask for the target PR or the copied comments before proceeding.
+
+## Modes
+
+- `dry_run`: inspect review feedback and report the triage only. Do not edit files, run write-mode formatters, commit, push, post replies, or resolve review threads.
+- `no_push`: local edits and verification are allowed, but do not push commits or otherwise update the remote branch. Report the local diff or local commits that still need to be pushed.
+- `no_reply`: do not post replies, submit reviews, or resolve review threads. Provide suggested replies and resolution actions in the final report instead.
+
+When a mode disables an action, skip that destructive or externally visible action even if normal workflow text would otherwise allow it.
+
+## Preflight
+
+1. Identify the current branch and target PR.
+2. Check tracked local changes with `git diff --name-only` and `git diff --cached --name-only`. Ignore untracked files unless the review feedback explicitly concerns them.
+3. Check unpushed commits before relying on remote review feedback.
+4. If tracked local changes or unpushed commits exist, warn that existing PR comments may not cover the latest local state. In `normal` mode, push only when the user request or repository workflow allows it; otherwise continue with a clearly reported limitation.
+
+## Feedback Collection
+
+Gather the complete feedback set before editing:
+
+- Fetch unresolved review threads, requested-change reviews, PR-level summary comments, and copied comments.
+- Use platform-native APIs/CLI when available. Paginate results; do not inspect only the first page of threads or comments.
+- For bot reviewers that post both summary comments and inline comments, collect both. Summary comments often contain severity, rationale, and fix instructions; inline comments contain the exact file and line context.
+- Preserve each thread/comment identifier needed to reply or resolve later.
+- Compare each comment with the current diff and file contents because review lines can become outdated.
+
+## Deduplication and Ordering
+
+Build one triage record per distinct finding:
+
+- Prefer exact review-thread identity when available.
+- For duplicate bot findings appearing in both summary and inline comments, merge by exact issue title first, then by file path plus line range as a fallback.
+- Prefer inline comments for location and current code context.
+- Prefer summary comments for severity, category, rationale, and detailed agent prompts.
+- Preserve the reviewer’s exact issue title and original wording where practical. Do not rename findings in a way that would make replies hard to map back to comments.
+- Preserve the reviewer’s original ordering unless the user asks for priority reordering. Many review bots already order findings by severity.
+
+Each triage record should track: original title, reviewer, source IDs, location, current applicability, severity/priority if available, disposition, planned action, verification, reply text if any, and resolution decision.
+
+## Resolution Policy
+
+In normal mode, `Resolve conversation` is the default action for any review thread that has been fully handled. A thread is handled when the requested change is implemented and verified, the current code already satisfies the comment, the comment is outdated and no longer applies, or a deliberate deferral/won't-fix response has been posted with a clear reason.
+
+Keep a thread open only when it still needs reviewer, maintainer, or product input, the fix is local-only and not pushed, verification is missing for a material change, or the user explicitly requested `dry_run`, `no_push`, or `no_reply` behavior that prevents resolution.
+
+When resolving a thread, add a concise reply first only if it provides useful context, such as what changed, why no code change was needed, why a finding was intentionally deferred, or why the original comment is now outdated. Do not add noisy replies for self-evident fixes unless project norms require them.
+
+## Flow
+
+```mermaid
+flowchart TD
+  A[Identify PR and branch state] --> B[Collect all review feedback]
+  B --> C[Deduplicate and preserve source IDs]
+  C --> D[Inspect current diff and code]
+  D --> E{Classify each triage record}
+  E -->|Fix| F[Implement minimal change]
+  E -->|Answer| G[Prepare concise reply]
+  E -->|Clarify| H[Leave open with question]
+  E -->|Already addressed or Outdated| I[Prepare evidence]
+  E -->|Defer or Won't fix| J[Document reason]
+  F --> K[Verify]
+  G --> L{Mode}
+  H --> L
+  I --> L
+  J --> L
+  K --> L
+  L -->|dry_run| M[Report triage only]
+  L -->|no_push| N[Report local diff or commits]
+  L -->|no_reply| O[Report suggested replies/actions]
+  L -->|normal| P[Commit/push if changed, then batch reply and resolve handled threads]
+  M --> Q[Final summary]
+  N --> Q
+  O --> Q
+  P --> Q
+```
+
+## Compact Workflow
+
+1. **Collect all relevant feedback**
+   - Identify the PR and gather unresolved review threads, requested-change reviews, PR-level summaries, inline comments, and copied comments.
+   - Paginate all platform calls and keep comment/thread IDs for later replies and resolution.
+   - For bot reviews, collect both summary and inline comments, then merge duplicates rather than fixing the same finding twice.
+
+2. **Classify each triage record**
+   - **Fix**: Valid requested change; make the smallest focused edit when not in `dry_run`.
+   - **Answer**: No code change needed; prepare a concise explanation.
+   - **Clarify**: Ambiguous, conflicting, or missing context; leave open with a question.
+   - **Already addressed**: Current code already satisfies it; prepare evidence.
+   - **Outdated**: Commented code or issue no longer exists; prepare evidence.
+   - **Defer / Won't fix**: Valid concern intentionally not changed now; document a specific reason.
+
+3. **Act according to the classification and mode**
+   - Keep edits scoped to the review feedback.
+   - Follow reviewer-provided fix instructions literally when they are still applicable; deviate only when the current code proves the instruction is stale or unsafe.
+   - In `dry_run`, stop at triage, proposed fixes, suggested replies, and verification plan.
+   - In `no_push`, local edits are allowed, but do not push or resolve threads for local-only fixes.
+   - In `no_reply`, do not post replies or resolve threads; report suggested replies/actions instead.
+   - In normal mode, batch replies where practical, then resolve every handled thread by default after the fix, explanation, or deferral reason is available on the PR.
+
+4. **Verify before claiming completion**
+   - For fixes, run appropriate checks or explain why they could not run.
+   - Re-inspect the updated diff and comment context to confirm the concern is resolved.
+   - Do not mark a thread resolved if it still needs reviewer, maintainer, or product input.
+
+5. **Finish**
+   - Normal mode: commit/push changes when appropriate, post useful replies or a summary, and resolve all handled threads by default.
+   - Safe modes: report the local state and the exact replies/resolution actions a human could take.
+
+## Reply Guidance
+
+- Keep inline replies short and tied to the original title or concern.
+- For fixed findings, mention the concrete change or commit if useful.
+- For already-addressed or outdated findings, cite the current code path or behavior that makes the finding no longer applicable.
+- For deferred or won't-fix findings, provide the reason and any follow-up issue or owner if known.
+- If a reply or resolve operation fails, continue with the remaining threads and report the failure in the final summary.
+
+## Final Summary Checklist
+
+- Mode used: `normal`, `dry_run`, `no_push`, or `no_reply`
+- Counts by disposition: fixed, answered, clarified/left open, already addressed, outdated, deferred/won't-fix
+- Threads resolved, intentionally left open, or resolution actions skipped by mode
+- Verification run or planned
+- Commits pushed, local diff/commits, or "none"
+- Remaining open items and who needs to respond

.github/workflows/ci.yml

@@ -62,6 +62,19 @@ jobs:
       runs-on: ubuntu-slim
     secrets:
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  github-codeql-analysis:
+    if: >
+      github.event_name == 'push'
+      || github.event_name == 'pull_request'
+      || (github.event_name == 'workflow_dispatch' && inputs.workflow == 'lint-and-test')
+    permissions:
+      contents: read
+      security-events: write
+      actions: read
+    uses: dceoy/gh-actions-for-devops/.github/workflows/github-codeql-analysis.yml@main  # zizmor: ignore[unpinned-uses]
+    with:
+      language: >
+        ["python"]
   dependabot-auto-merge:
     if: >
       github.event_name == 'pull_request' && github.actor == 'dependabot[bot]'
@@ -73,5 +86,7 @@ jobs:
       contents: write
       pull-requests: write
       actions: read
+      checks: read
+      statuses: read
     with:
       unconditional: true

AGENTS.md

@@ -1,79 +1,37 @@
 # Repository Guidelines
 
-## Commands
+## Project Structure & Module Organization
 
-### Development Setup
+`mt5cli/` contains the package source. Important modules include `cli.py` for the Typer command-line app, `client.py` and `sdk.py` for public MT5 client/session APIs, `history.py` for SQLite history collection, `storage.py` and `converters.py` for export behavior, and `schemas.py` for normalized dataset contracts. `tests/` holds pytest coverage for CLI behavior, SDK contracts, trading helpers, history, and utilities. `docs/` and `mkdocs.yml` define the MkDocs site and API reference. `skills/mt5cli/SKILL.md` documents the mt5cli agent skill.
 
-```bash
-uv sync
-```
+## Build, Test, and Development Commands
 
-### Code Quality and Documentation
+- `uv sync` installs runtime and development dependencies from `pyproject.toml` and `uv.lock`.
+- `uv run mt5cli --help` runs the local CLI entry point.
+- `uv run ruff format .` formats Python files.
+- `uv run ruff check --fix .` lints and applies safe fixes.
+- `uv run pyright .` runs strict type checking.
+- `uv run pytest` runs doctests, branch coverage, and the test suite.
+- `uv run mkdocs serve` previews documentation locally; `uv run mkdocs build` validates the docs build.
 
-**Important**: Run these before committing or creating a PR.
+Use `.agents/skills/local-qa/SKILL.md` for pre-handoff QA. It runs `.agents/skills/local-qa/scripts/qa.sh`, which formats, lints, type-checks, tests, formats Markdown, and checks GitHub workflows.
 
-1. **format, lint, and test**: Use `local-qa` skill.
-2. **Documentation build** (if any public API changes): `uv run mkdocs build`
+## Coding Style & Naming Conventions
 
-## Architecture
+Target Python `>=3.11,<3.14`. Use Ruff’s configured 88-character line length and Google-style docstrings. Pyright is strict, so prefer explicit public type annotations and narrow exception handling. Keep module, function, and variable names in `snake_case`; classes and enums use `PascalCase`. Preserve the package’s small, typed helper style rather than adding broad abstractions.
 
-### Key Dependencies
+## Design Principles
 
-- **pdmt5**: Pandas-based data handler for MetaTrader 5 (core library)
-- **typer**: CLI framework for building command-line interfaces
-- **click**: Parameter type customization for CLI options
-- **pandas**: Core data manipulation and analysis
+Apply KISS, DRY, and YAGNI when changing code. Prefer the simplest implementation that satisfies the current CLI/API contract. Remove duplication when shared behavior is already proven by at least two concrete call sites, but avoid generic helpers for speculative reuse. Do not add configuration flags, extension hooks, or alternate backends until a real repository use case requires them.
 
-### Package Structure
+## Testing Guidelines
 
-- `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
-  - `__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
-- `docs/`: MkDocs documentation with API reference
-  - `docs/index.md`: Main documentation
-  - `docs/api/`: Auto-generated API documentation for all modules
-- Modern Python packaging with `pyproject.toml` and uv dependency management
-
-### Quality Standards
-
-- Type hints required (pyright strict mode)
-- Comprehensive linting with 35+ rule categories (ruff)
-- Test coverage tracking with 100% (pytest-cov)
-- Parametrized tests for input/result matrices using `pytest.mark.parametrize` (pytest)
-- Test doubles (mocks, stubs) using `pytest_mock` for external dependencies (pytest-mock)
-- Pydantic models for data validation and configuration
-
-### Documentation workflow
-
-1. Add Google-style docstrings to functions/classes
-2. Local preview: `uv run mkdocs serve`
-3. Build: `uv run mkdocs build`
-4. Deploy: `uv run mkdocs gh-deploy`
+Tests use pytest, pytest-mock, doctests, and pytest-cov. Test files should match `tests/test_*.py`, classes `Test*`, and functions `test_*`. Coverage is configured with `fail_under = 100`, so add focused tests for every behavior change. Mock MT5/pdmt5 boundaries; do not require a live MetaTrader terminal in unit tests.
 
 ## Commit & Pull Request Guidelines
 
-- Run QA checks using `local-qa` skill before committing or creating a PR.
-- Branch names use appropriate prefixes on creation (e.g., `feature/...`, `bugfix/...`, `refactor/...`, `docs/...`, `chore/...`).
-- When instructed to create a PR, create it as a draft with appropriate labels by default.
+Recent history uses concise imperative commits, sometimes with conventional prefixes such as `feat:` or `chore:` and PR numbers appended by GitHub. Keep commits scoped to one logical change. Pull requests should describe behavior changes, note tests run, link related issues, and call out MT5/live-trading risk where relevant.
 
-## Code Design Principles
+## Security & Configuration Tips
 
-Always prefer the simplest design that works.
-
-- **KISS**: Choose straightforward solutions and avoid unnecessary abstraction.
-- **DRY**: Remove duplication when it improves clarity and maintainability.
-- **YAGNI**: Do not add features, hooks, or flexibility until they are needed.
-- **SOLID/Clean Code**: Apply these as tools, only when they keep the design simpler and easier to change.
-
-## Development Methodology
-
-Keep delivery incremental, test-backed, and easy to review.
-
-- Make small, safe, reversible changes.
-- Prefer `Red -> Green -> Refactor`.
-- Do not mix feature work and refactoring in the same commit.
-- Refactor when it improves clarity or removes real duplication (Rule of Three).
-- Keep tests fast, focused, and self-validating.
+Never commit account credentials, broker passwords, exported private data, or local `.venv` contents. Treat `order_send` and CLI `order-send --yes` as live execution paths; gate examples and tests so they cannot place real trades accidentally.

README.md

@@ -2,10 +2,16 @@
 
 [![CI/CD](https://github.com/dceoy/mt5cli/actions/workflows/ci.yml/badge.svg)](https://github.com/dceoy/mt5cli/actions/workflows/ci.yml)
 
-Command-line tool for exporting MetaTrader 5 data to CSV, JSON, Parquet, and SQLite3.
+Generic MT5 data and execution infrastructure for Python applications. Export from the CLI or import a small, stable Python API in downstream packages.
 
 Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data handler for MetaTrader 5.
 
+## Architecture
+
+- **pdmt5** — canonical MT5 client, DataFrame/trading primitives, and MT5 constant parsing (`TIMEFRAME_*`, `COPY_TICKS_*`, order types).
+- **mt5cli** — public `MT5Client` API, standardized dataset schemas, storage helpers, CLI commands, and SQLite history collection built on pdmt5.
+- **mt5api** — sibling HTTP adapter for remote MT5 access; not a dependency of mt5cli.
+
 ## Features
 
 - **Multi-format export**: CSV, JSON, Parquet, and SQLite3 output formats
@@ -13,6 +19,7 @@ Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data han
 - **Comprehensive data access**: Rates, ticks, account info, symbols, orders, positions, and trading history
 - **Flexible timeframes**: Named timeframes (M1, H1, D1, etc.) and numeric values
 - **Connection management**: Optional credentials, server, and timeout configuration
+- **SQLite rate loading**: Load mt5cli-managed rate tables/views for offline workflows
 
 ## Installation
 
@@ -20,7 +27,96 @@ Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data han
 pip install -U mt5cli MetaTrader5
 ```
 
-## Usage
+## Python API (downstream packages)
+
+Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives. `Mt5CliClient` remains available as a backward-compatible alias.
+
+```python
+from datetime import UTC, datetime
+from pathlib import Path
+
+from mt5cli import (
+    DataKind,
+    Dataset,
+    MT5Client,
+    build_config,
+    collect_history,
+    export_dataframe,
+    mt5_session,
+    normalize_dataframe,
+    update_history_with_config,
+)
+
+# Persistent session for multiple calls
+with mt5_session(build_config(login=12345, server="Broker-Demo")) as client:
+    rates = client.copy_rates_range(
+        "EURUSD",
+        timeframe="H1",
+        date_from="2024-01-01",
+        date_to="2024-02-01",
+    )
+    positions = client.positions()
+    check = client.order_check({"action": 1, "symbol": "EURUSD", "volume": 0.1})
+
+# Normalize MT5 frames to the public schema contract before storage
+closed_rates = normalize_dataframe(
+    rates, DataKind.rates, symbol="EURUSD", timeframe="H1"
+)
+export_dataframe(closed_rates, Path("rates.csv"), "csv")
+
+# Bulk SQLite history (same behavior as collect-history CLI command)
+collect_history(
+    Path("history.db"),
+    symbols=["EURUSD"],
+    date_from=datetime(2024, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+    datasets={Dataset.rates, Dataset.history_deals},
+)
+
+# Incremental append for automated pipelines
+update_history_with_config(
+    output="history.db",
+    symbols=["EURUSD"],
+    config=build_config(login=12345),
+)
+```
+
+Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Storage helpers are re-exported from `mt5cli.storage` and the package root.
+
+`MT5Client.order_send()` is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly.
+
+### Trading lifecycle and state helpers
+
+Trading applications can depend on `mt5cli` imports only; terminal path,
+credentials, server, and timeout are forwarded to `pdmt5.Mt5Config`, numeric
+login strings are coerced to integers, and empty login strings are treated as
+unset.
+
+```python
+from mt5cli import (
+    calculate_spread_ratio,
+    create_trading_client,
+    get_account_snapshot,
+    mt5_trading_session,
+)
+
+with mt5_trading_session(
+    path=r"C:\Program Files\MetaTrader 5\terminal64.exe",
+    login="12345",
+    password="from-env-or-secret-store",
+    server="Broker-Demo",
+) as client:
+    account = get_account_snapshot(client)
+    spread = calculate_spread_ratio(client, "EURUSD")
+
+client = create_trading_client(login=12345, server="Broker-Demo")
+try:
+    positions = client.positions_get_as_df(symbol="EURUSD")
+finally:
+    client.shutdown()
+```
+
+## CLI usage
 
 ```bash
 # Export account information to CSV
@@ -50,28 +146,33 @@ 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                                                                                  |
-| `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 |
+| Command                | Description                                                                                                  |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `rates-from`           | Export rates from a start date                                                                               |
+| `rates-from-pos`       | Export rates from a start position                                                                           |
+| `latest-rates`         | Export latest 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                                                                                |
+| `ticks-recent`         | Export ticks from a recent trailing window                                                                   |
+| `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                                                                            |
+| `minimum-margins`      | Export minimum-volume buy and sell margin requirements                                                       |
+| `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                                                                                      |
+| `recent-history-deals` | Export historical deals from a recent trailing window                                                        |
+| `mt5-summary`          | Export terminal/account status summary                                                                       |
+| `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`.
 
@@ -87,7 +188,71 @@ mt5cli -o history.db collect-history \
   --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 deals, and uses volume-weighted open/close prices; reversal deals (`DEAL_ENTRY_INOUT`) are reported via `volume_reversal` / `reversal_count` columns and do not contribute to the weighted prices.
+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.
+- **Rate view resolution**: use `resolve_rate_view_name()` / `resolve_rate_view_names()` to map symbols and granularities to existing SQLite compatibility views without creating databases. Both accept `None` (or a missing path) and return deterministic default names unless `require_existing=True`.
+- **Rate view loading**: use `load_rate_data()` / `load_rate_data_from_connection()` to load a SQLite rate table or view into a `DatetimeIndex` DataFrame.
+- **Multi-series rate loading**: use `build_rate_targets()` to build neutral `RateTarget(symbol, timeframe)` pairs, `resolve_rate_tables()` to map them to table/view names (pass `require_existing=True` for strict resolution), and `load_rate_series_from_sqlite()` to load them into a mapping keyed by `(symbol, integer timeframe)`. The loader requires existing managed views unless `explicit_tables` is supplied, and rejects duplicate `(symbol, timeframe)` targets.
+- **Multi-account latest rates**: use `collect_latest_rates_for_accounts()` with `AccountSpec` to read the latest bars for several account groups, merged into a `(symbol, integer timeframe)` mapping. For long-running pollers, `collect_latest_rates_for_accounts_with_retries()` adds bounded exponential backoff that retries only `pdmt5.Mt5TradingError` / `pdmt5.Mt5RuntimeError` and re-raises once `retry_count` is exhausted.
+- **Latest closed bars**: use `collect_latest_closed_rates_for_accounts()` when downstream logic must exclude the still-forming current bar. It fetches `count + 1` bars at `start_pos=0`, drops the last row with `drop_forming_rate_bar()`, and validates each series is non-empty. `collect_latest_closed_rates_by_granularity()` returns the same data keyed by `(symbol, granularity_name)` such as `("EURUSD", "M1")`.
+
+```python
+from mt5cli import AccountSpec, collect_latest_closed_rates_by_granularity
+
+rates = collect_latest_closed_rates_by_granularity(
+    [AccountSpec(symbols=["EURUSD", "GBPUSD"], login=12345)],
+    ["M1", "H1"],
+    count=500,
+    retry_count=3,
+)
+eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
+```
+
+- **Credential resolution**: use `resolve_account_spec()` / `resolve_account_specs()` to merge explicit override values over `AccountSpec` fields and expand `${ENV_VAR}` placeholders (via `substitute_env_placeholders()`), raising `ValueError` for missing variables. This keeps secrets out of plan/config files without coupling to any strategy code.
+- **Throttled history updates**: use `ThrottledHistoryUpdater` to wrap `update_history()` with a minimum `interval_seconds` between successful runs (monotonic clock). Call `should_update()` / `update(client, symbols)` from an application loop; errors propagate by default, or pass `suppress_errors=True` to swallow recoverable `Mt5*Error`, `sqlite3.Error`, `ValueError`, `OSError`, and MT5 client capability errors for history API methods without advancing the throttle (other `AttributeError` / `TypeError` values always propagate).
+- **Trading session helpers**: use `mt5_trading_session()` for a trading-capable `pdmt5.Mt5TradingClient` that initializes/logs in via `Mt5Config.path` and always shuts down safely. Pair with `detect_position_side()`, `calculate_margin_and_volume()`, and `determine_order_limits()` for generic position and sizing utilities. The read-only `mt5_session()` / `Mt5CliClient` SDK is unchanged.
+- **Granularity-keyed rate loading**: `load_rate_series_by_granularity()` builds targets with `build_rate_targets()`, loads them with `load_rate_series_from_sqlite()`, and returns a mapping keyed by `(symbol | None, granularity_name)` such as `("EURUSD", "M1")` to reduce downstream boilerplate.
+- **MT5 session helper**: use the `mt5_session()` context manager to attach to (or, when `Mt5Config.path` is set, launch) an MT5 terminal, log in, and yield a connected `MT5Client` that shuts down on exit.
+- **SQLite export helpers**: use `export_dataframe_to_sqlite()` for append mode, optional index export, and post-write deduplication by key columns.
+- **Recent ticks and margins**: `recent_ticks()` and `minimum_margins()` SDK helpers (and matching CLI commands) cover common downstream read-only queries.
 
 ## Requirements
 
@@ -95,6 +260,63 @@ History orders and deals are fetched per symbol and concatenated, so the symbol
 - Windows OS (MetaTrader 5 requirement)
 - MetaTrader 5 platform installed
 
+### Migration note for mteor
+
+Replace local MT5 lifecycle and trading helper code with mt5cli imports:
+
+```python
+# Before (local mteor helpers)
+# with local_mt5_trading_session(config) as client:
+#     side = local_detect_position_side(client, symbol)
+#     sizing = local_calculate_margin_and_volume(client, symbol, unit_ratio, preserved_ratio)
+#     limits = local_determine_order_limits(client, symbol, side, sl_ratio, tp_ratio)
+
+# After (mt5cli shared layer)
+from pdmt5 import Mt5Config
+from mt5cli import (
+    calculate_margin_and_volume,
+    detect_position_side,
+    determine_order_limits,
+    mt5_trading_session,
+)
+
+with mt5_trading_session(
+    Mt5Config(path=terminal_path, login=login), retry_count=2
+) as client:
+    side = detect_position_side(client, symbol)
+    sizing = calculate_margin_and_volume(
+        client, symbol, unit_margin_ratio=0.5, preserved_margin_ratio=0.2
+    )
+    if side is not None:
+        limits = determine_order_limits(
+            client,
+            symbol,
+            side,
+            stop_loss_limit_ratio=0.01,
+            take_profit_limit_ratio=0.02,
+        )
+```
+
+Throttled history updates use a separate read-only session:
+
+```python
+from pdmt5 import Mt5Config, Mt5DataClient
+
+from mt5cli import ThrottledHistoryUpdater
+
+updater = ThrottledHistoryUpdater(
+    output="history.db", interval_seconds=60, suppress_errors=True
+)
+client = Mt5DataClient(config=Mt5Config(login=login))
+client.initialize_and_login_mt5()
+try:
+    updater.update(client, ["EURUSD"])
+finally:
+    client.shutdown()
+```
+
+Read-only collectors can keep using `mt5_session()` and `MT5Client` (or the `Mt5CliClient` alias) without changes.
+
 ## Development
 
 ```bash

docs/api/client.md

@@ -0,0 +1,3 @@
+# Client
+
+::: mt5cli.client

docs/api/converters.md

@@ -0,0 +1,3 @@
+# Converters
+
+::: mt5cli.converters

docs/api/exceptions.md

@@ -0,0 +1,3 @@
+# Exceptions
+
+::: mt5cli.exceptions

docs/api/history.md

@@ -0,0 +1,255 @@
+# 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`.
+
+### Rate view resolution
+
+Downstream tools can resolve mt5cli-managed compatibility view names from an
+existing SQLite history database without creating files or guessing naming
+schemes:
+
+```python
+from pathlib import Path
+
+from mt5cli.history import resolve_rate_view_name, resolve_rate_view_names
+
+# Single symbol and granularity
+view = resolve_rate_view_name(Path("history.db"), "EURUSD", "M1")
+
+# Batch resolution in row-major order
+views = resolve_rate_view_names(
+    Path("history.db"),
+    ["EURUSD", "GBPUSD"],
+    ["M1", "H1"],
+)
+```
+
+Resolution rules:
+
+- Returns `rate_<symbol>__<timeframe>` when a symbol stores one timeframe.
+- Returns `rate_<symbol>__<granularity>_<timeframe>` when multiple timeframes
+  are stored for the same symbol.
+- When multiple naming candidates apply, prefers an existing managed
+  `rate_*__*` view from the candidate list.
+- Falls back to single-timeframe naming when the database path is missing or
+  `rates` metadata is unavailable.
+- Pass `require_existing=True` to raise `ValueError` instead of returning a
+  best-guess name when the database or view is missing.
+- Accepts either a SQLite path or an open `sqlite3.Connection`.
+
+### Rate data loading
+
+The canonical normalized rate table is `rates`; compatibility views are named
+with `rate_<symbol>__<timeframe>` for single-timeframe symbols or
+`rate_<symbol>__<granularity>_<timeframe>` when a symbol has multiple stored
+timeframes. `resolve_rate_table_name()` returns `rates`, while
+`resolve_rate_view_name()` returns the per-symbol compatibility view name.
+
+Use `load_rate_data()` or `load_rate_series_from_sqlite(..., table=...)` to load
+a single table or view from a SQLite path. Use
+`load_rate_series_by_granularity()` to load multiple instrument/granularity
+targets without hard-coding view names:
+
+```python
+from pathlib import Path
+
+from mt5cli import (
+    load_rate_data,
+    load_rate_series_by_granularity,
+    load_rate_series_from_sqlite,
+    resolve_rate_table_name,
+)
+from mt5cli.history import resolve_rate_view_name
+
+view = resolve_rate_view_name(Path("history.db"), "EURUSD", "M1", require_existing=True)
+rates = load_rate_data(Path("history.db"), view, count=1000)
+same_rates = load_rate_series_from_sqlite(Path("history.db"), table=view, count=1000)
+
+table = resolve_rate_table_name("EURUSD", "M1")  # "rates"
+series = load_rate_series_by_granularity(
+    Path("history.db"),
+    symbols=["EURUSD", "GBPUSD"],
+    granularities=["M1", "H1"],
+    count=500,
+)
+```
+
+`count` returns the latest rows while preserving chronological order. Missing
+tables/views and mismatched `explicit_tables` lengths raise `ValueError` with
+the requested database target in the message.
+
+The loader accepts close-based OHLC rate data or tick-like bid/ask data. It
+validates that `time` exists, parses timestamps with pandas, and returns a
+DataFrame indexed by ascending `DatetimeIndex` named `time`.
+
+### Multi-series rate loading
+
+For loading many rate series at once, build neutral `RateTarget` pairs and load
+them from SQLite in one call. View names are resolved via the same
+compatibility-view rules, or you can pass `explicit_tables` to bypass resolution:
+
+```python
+from pathlib import Path
+
+from mt5cli import build_rate_targets, load_rate_series_from_sqlite
+
+targets = build_rate_targets(["EURUSD", "GBPUSD"], ["M1", "H1"])
+series = load_rate_series_from_sqlite(Path("history.db"), targets, count=1000)
+frame = series["EURUSD", 1]  # keyed by (symbol, integer timeframe)
+```
+
+- `build_rate_targets()` returns `RateTarget(symbol, timeframe)` pairs in
+  row-major order, normalizing timeframe names such as `"M1"` to their integer
+  values; set `allow_missing_symbol=True` to address series solely by
+  `explicit_tables` (targets carry `symbol=None`).
+- `resolve_rate_tables()` maps targets to table or view names and validates that
+  any `explicit_tables` count matches the target count. Pass
+  `require_existing=True` to raise `ValueError` instead of returning a
+  best-guess name when the database or managed view is missing. When
+  `explicit_tables` is provided, names are returned as-is and
+  `require_existing` is ignored.
+- `load_rate_series_from_sqlite()` returns a mapping keyed by
+  `(symbol, integer timeframe)`. Unless `explicit_tables` is supplied, it
+  requires existing managed `rate_*` compatibility views and raises
+  `ValueError` when they are missing. Duplicate `(symbol, timeframe)` targets
+  are rejected.
+- `load_rate_series_by_granularity()` is a thin wrapper that builds the targets,
+  loads the series, and rekeys the result by granularity name to avoid
+  converting integer timeframes downstream:
+
+  ```python
+  from mt5cli import load_rate_series_by_granularity
+
+  series = load_rate_series_by_granularity(
+      "history.db", ["EURUSD"], ["M1", "H1"], count=1000
+  )
+  frame = series["EURUSD", "M1"]  # keyed by (symbol | None, granularity_name)
+  ```

docs/api/index.md

@@ -1,63 +1,53 @@
 # API Reference
 
-This section contains the complete API documentation for mt5cli.
+This section documents the mt5cli public Python API and CLI modules.
 
-## Modules
+## Public API layers
 
-The mt5cli package consists of the following modules:
+| Module                                    | Purpose                                                                   |
+| ----------------------------------------- | ------------------------------------------------------------------------- |
+| [Client](client.md)                       | `MT5Client` session abstraction for data access and order primitives      |
+| [Schemas](schemas.md)                     | Canonical DataFrame contracts and normalization helpers                   |
+| [Storage](storage.md)                     | CSV/JSON/Parquet/SQLite export and history collection helpers             |
+| [Converters](converters.md)               | Symbol, timeframe, timezone, and date-range utilities                     |
+| [Exceptions](exceptions.md)               | Stable mt5cli exception types and MT5 error normalization                 |
+| [SDK](sdk.md)                             | Module-level fetch helpers, multi-account collectors, incremental history |
+| [Trading](trading.md)                     | Trading-capable sessions and operational helpers                          |
+| [History Collection (SQLite)](history.md) | SQLite schema, incremental writes, dedup, and rate views                  |
+| [CLI](cli.md)                             | Typer commands that delegate to the Python API                            |
+| [Utils](utils.md)                         | Parsing helpers and Click parameter types                                 |
 
-### [CLI](cli.md)
+## Architecture overview
 
-Command-line interface module providing typer-based commands for exporting MetaTrader 5 data to CSV, JSON, Parquet, and SQLite3 formats.
-
-## 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.
-
-## Usage Guidelines
-
-All modules follow these conventions:
-
-- **Type Safety**: All functions include comprehensive type hints
-- **Error Handling**: User-friendly error messages via typer
-- **Documentation**: Google-style docstrings with examples
-- **Validation**: Custom Click parameter types for input validation
-
-## Quick Start
-
-```bash
-# Export account information to CSV
-mt5cli -o account.csv account-info
-
-# Export EURUSD H1 rates to Parquet
-mt5cli -o rates.parquet rates-from --symbol EURUSD --timeframe H1 \
-  --date-from 2024-01-01 --count 1000
-
-# Export ticks to JSON
-mt5cli -o ticks.json ticks-from --symbol EURUSD \
-  --date-from 2024-01-01 --count 500 --flags ALL
-
-# Export to SQLite3 with custom table name
-mt5cli -o data.db --table symbols symbols --group "*USD*"
+```mermaid
+flowchart TD
+    App["Downstream application"] --> Client["MT5Client"]
+    CLI["mt5cli CLI"] --> Client
+    Client --> SDK["sdk / pdmt5"]
+    Client --> Schemas["schemas"]
+    Storage["storage"] --> History["history SQLite"]
+    Storage --> Utils["utils export"]
+    SDK --> PDMT5["pdmt5.Mt5DataClient"]
 ```
 
-## Python API
+Downstream packages should depend on the package root exports (`MT5Client`, `DataKind`, `normalize_dataframe`, `export_dataframe`, `collect_history`, etc.) rather than private modules.
+
+`MT5Client.order_send()` is a live execution primitive that can place real trades. mt5cli exposes minimal execution helpers only; strategy logic, signals, backtests, and optimization remain out of scope and must be implemented downstream with explicit execution gating.
+
+## Quick start
 
 ```python
-from mt5cli import detect_format, export_dataframe
-import pandas as pd
+from mt5cli import MT5Client, build_config, mt5_session
 
-# 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")
+with mt5_session(build_config(login=12345)) as client:
+    rates = client.copy_rates_range("EURUSD", "H1", "2024-01-01", "2024-02-01")
+    positions = client.positions()
 ```
 
-## Examples
+```bash
+mt5cli -o account.csv account-info
+mt5cli -o rates.parquet rates-range --symbol EURUSD --timeframe H1 \
+  --date-from 2024-01-01 --date-to 2024-02-01
+```
 
-See individual module pages for detailed usage examples and code samples.
+See individual module pages for detailed usage examples.

docs/api/schemas.md

@@ -0,0 +1,3 @@
+# Schemas
+
+::: mt5cli.schemas

docs/api/sdk.md

@@ -0,0 +1,129 @@
+# SDK Module
+
+::: mt5cli.sdk
+
+## Resilient multi-account orchestration
+
+The SDK ships strategy-agnostic helpers for building long-running collectors on
+top of the read-only client. None of them depend on a particular trading
+application.
+
+### Retrying transient rate collection
+
+`collect_latest_rates_for_accounts_with_retries()` wraps
+`collect_latest_rates_for_accounts()` with bounded exponential backoff. Only
+`pdmt5.Mt5TradingError` and `pdmt5.Mt5RuntimeError` are retried; the final
+failure is re-raised once `retry_count` is exhausted.
+
+```python
+from mt5cli import AccountSpec, collect_latest_rates_for_accounts_with_retries
+
+accounts = [AccountSpec(symbols=["EURUSD"], login=12345)]
+rates = collect_latest_rates_for_accounts_with_retries(
+    accounts,
+    ["M1", "H1"],
+    count=500,
+    retry_count=3,
+    backoff_base=2,  # sleeps 2s, 4s, 8s between attempts
+)
+```
+
+### Latest closed rate bars
+
+MetaTrader 5 `start_pos=0` includes the still-forming current bar as the last
+row. `fetch_latest_closed_rates()` handles one connected client; multi-account
+helpers fetch `count + 1` bars, drop that row with `drop_forming_rate_bar()`,
+and validate each series is non-empty. Returned frames are ordered
+oldest-to-newest and may contain fewer than `count` rows only when MT5 returns
+fewer closed bars.
+
+```python
+from mt5cli import (
+    AccountSpec,
+    collect_latest_closed_rates_by_granularity,
+    fetch_latest_closed_rates,
+)
+
+closed = fetch_latest_closed_rates(
+    client,
+    symbol="EURUSD",
+    granularity="M1",
+    count=500,
+)
+
+rates = collect_latest_closed_rates_by_granularity(
+    [AccountSpec(symbols=["EURUSD"], login=12345)],
+    ["M1", "H1"],
+    count=500,
+    retry_count=3,
+)
+closed_m1 = rates["EURUSD", "M1"]
+```
+
+Use `collect_latest_closed_rates_by_granularity()` when callers prefer keys such
+as `("EURUSD", "M1")` instead of integer timeframes.
+
+### Resolving credentials and `${ENV_VAR}` placeholders
+
+`resolve_account_spec()` / `resolve_account_specs()` merge explicit override
+values over `AccountSpec` fields and expand `${ENV_VAR}` placeholders, keeping
+secrets out of plan/config files. A missing environment variable raises
+`ValueError`.
+
+```python
+import os
+
+from mt5cli import AccountSpec, resolve_account_specs
+
+os.environ["MT5_LOGIN"] = "12345"
+os.environ["MT5_PASSWORD"] = "secret"
+accounts = [
+    AccountSpec(symbols=["EURUSD"], login="${MT5_LOGIN}", password="${MT5_PASSWORD}")
+]
+
+resolved = resolve_account_specs(accounts, server="Broker-Demo")
+# resolved[0].login == "12345", resolved[0].server == "Broker-Demo"
+```
+
+### Throttled incremental history updates
+
+`ThrottledHistoryUpdater` wraps `update_history()` with a minimum interval
+between successful runs (using a monotonic clock), so an application loop can
+call it every iteration without over-fetching.
+
+```python
+from pdmt5 import Mt5Config, Mt5DataClient
+
+from mt5cli import Dataset, ThrottledHistoryUpdater
+
+updater = ThrottledHistoryUpdater(
+    output="history.db",
+    datasets={Dataset.rates},
+    timeframes=["M1"],
+    interval_seconds=60,  # <= 0 updates on every call
+)
+
+client = Mt5DataClient(config=Mt5Config(login=12345))
+client.initialize_and_login_mt5()
+try:
+    while True:
+        updater.update(client, ["EURUSD", "GBPUSD"])  # no-op until 60s elapse
+        # ... do other work; break when shutting down ...
+finally:
+    client.shutdown()
+```
+
+By default recoverable errors (`Mt5TradingError`, `Mt5RuntimeError`,
+`sqlite3.Error`, `ValueError`, `OSError`, and MT5 client capability
+`AttributeError` / `TypeError` for history API methods) propagate so the caller
+controls logging; pass `suppress_errors=True` to swallow them and return
+`False` without advancing the throttle. Other `AttributeError` / `TypeError`
+values always propagate. Input validation (`_resolve_update_history_request`)
+runs before any MT5 or SQLite calls, but when `suppress_errors=True` the
+resulting `ValueError` is suppressed along with other recoverable errors.
+
+## Trading-capable sessions
+
+For order placement and trading calculations, use the dedicated
+[Trading module](trading.md). The read-only `Mt5CliClient` and `mt5_session()`
+helpers in this module are unchanged.

docs/api/storage.md

@@ -0,0 +1,3 @@
+# Storage
+
+::: mt5cli.storage

docs/api/trading.md

@@ -0,0 +1,114 @@
+# Trading Module
+
+::: mt5cli.trading
+
+## Trading-capable MT5 sessions
+
+`create_trading_client()` and `mt5_trading_session()` complement the read-only
+`mt5_session()` helper in `sdk.py`. They return or yield an initialized
+`pdmt5.Mt5TradingClient`, use `Mt5Config.path` to launch the terminal when
+configured, and `mt5_trading_session()` always calls `shutdown()` on exit.
+
+```python
+from mt5cli import create_trading_client, mt5_trading_session
+
+with mt5_trading_session(
+    path=r"C:\Program Files\MetaTrader 5\terminal64.exe",
+    login="12345",
+    password="secret",
+    server="Broker-Demo",
+    retry_count=2,
+) as client:
+    positions = client.positions_get_as_df(symbol="EURUSD")
+
+client = create_trading_client(login=12345, server="Broker-Demo")
+try:
+    account = client.account_info_as_dict()
+finally:
+    client.shutdown()
+```
+
+`login` accepts `int`, numeric `str`, or an empty string; empty strings are
+treated as unset. `path`, `password`, `server`, and `timeout` are forwarded to
+`pdmt5.Mt5Config`, and omitted `timeout` values keep the lower-level default.
+The read-only `Mt5CliClient` / `mt5_session()` API is unchanged.
+
+## State and order helpers
+
+These helpers are strategy-agnostic and do not depend on signal detection,
+betting logic, or scheduling code in downstream applications.
+
+```python
+from mt5cli import (
+    calculate_spread_ratio,
+    calculate_margin_and_volume,
+    close_open_positions,
+    detect_position_side,
+    determine_order_limits,
+    get_account_snapshot,
+    get_positions_frame,
+    get_symbol_snapshot,
+    get_tick_snapshot,
+    place_market_order,
+)
+
+account = get_account_snapshot(client)
+symbol = get_symbol_snapshot(client, "EURUSD")
+tick = get_tick_snapshot(client, "EURUSD")
+positions = get_positions_frame(client, "EURUSD")
+side = detect_position_side(client, "EURUSD")
+spread_ratio = calculate_spread_ratio(client, "EURUSD")
+sizing = calculate_margin_and_volume(
+    client,
+    "EURUSD",
+    unit_margin_ratio=0.5,
+    preserved_margin_ratio=0.2,
+)
+limits = determine_order_limits(
+    client,
+    "EURUSD",
+    side="long",
+    stop_loss_limit_ratio=0.01,
+    take_profit_limit_ratio=0.02,
+)
+preview = place_market_order(
+    client,
+    symbol="EURUSD",
+    volume=sizing["buy_volume"],
+    order_side="BUY",
+    sl=limits["stop_loss"],
+    tp=limits["take_profit"],
+    dry_run=True,
+)
+closed = close_open_positions(client, symbols="EURUSD", dry_run=True)
+```
+
+`detect_position_side()` returns `long` for buy-only exposure, `short` for
+sell-only exposure, and `None` for no positions or mixed long/short exposure.
+`calculate_spread_ratio()` uses `(ask - bid) / ((ask + bid) / 2)` and raises
+`Mt5TradingError` when bid or ask is missing or non-positive.
+
+SL/TP ratios for `determine_order_limits()` must satisfy `0 <= ratio < 1`; `0`
+omits that level. SL/TP prices are rounded with symbol `digits` metadata when
+available. `unit_margin_ratio` and `preserved_margin_ratio` for
+`calculate_margin_and_volume()` accept `0 <= ratio <= 1`; `unit_margin_ratio=0`
+requests one minimum valid unit when the post-reserve margin can afford it.
+Negative `margin_free` is clamped to `0.0` before sizing. Execution helpers
+return normalized dictionaries containing the request, response, status,
+retcode, and `dry_run` flag; `dry_run=True` never sends an order. Market order
+helpers mark known non-success MT5 retcodes as `status="failed"` while keeping
+the normalized response for inspection.
+
+## Migration from mteor-local helpers
+
+| mteor-local concern                                      | mt5cli replacement                              |
+| -------------------------------------------------------- | ----------------------------------------------- |
+| Manual terminal spawn/kill around trading code           | `mt5_trading_session()`                         |
+| Local position-side detection                            | `detect_position_side()`                        |
+| Local margin/volume sizing                               | `calculate_margin_and_volume()`                 |
+| Local SL/TP price derivation                             | `determine_order_limits()`                      |
+| Throttled SQLite history loop with ad-hoc error handling | `ThrottledHistoryUpdater(suppress_errors=True)` |
+
+Keep read-only data collection on `mt5_session()` / `Mt5CliClient`; use
+`mt5_trading_session()` only where order placement or trading calculations are
+required.

docs/api/utils.md

@@ -0,0 +1,3 @@
+# Utils Module
+
+::: mt5cli.utils

docs/index.md

@@ -1,10 +1,16 @@
 # mt5cli
 
-Command-line tool for MetaTrader 5 data export.
+Generic MT5 data and execution infrastructure for Python applications.
 
 ## Overview
 
-mt5cli is a CLI application that exports MetaTrader 5 trading data to multiple file formats. It is built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data handler for MetaTrader 5.
+mt5cli provides a stable `MT5Client` Python API, standardized dataset schemas, storage helpers, and a CLI for exporting MetaTrader 5 data. It is built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data handler for MetaTrader 5.
+
+## Architecture
+
+- **pdmt5** — canonical MT5 client, DataFrame/trading primitives, and MT5 constant parsing (`TIMEFRAME_*`, `COPY_TICKS_*`, order types).
+- **mt5cli** — public `MT5Client` API, schema contracts, storage helpers, CLI commands, and SQLite history collection built on pdmt5.
+- **mt5api** — sibling HTTP adapter for remote MT5 access; not a dependency of mt5cli.
 
 ## Features
 
@@ -13,6 +19,7 @@ mt5cli is a CLI application that exports MetaTrader 5 trading data to multiple f
 - **Comprehensive data access**: Rates, ticks, account info, symbols, orders, positions, and trading history
 - **Flexible timeframes**: Named timeframes (M1, H1, D1, etc.) and numeric values
 - **Connection management**: Optional credentials, server, and timeout configuration
+- **SQLite rate loading**: Load mt5cli-managed rate tables/views for offline workflows
 
 ## Installation
 
@@ -20,6 +27,69 @@ mt5cli is a CLI application that exports MetaTrader 5 trading data to multiple f
 pip install mt5cli
 ```
 
+## Python API for downstream packages
+
+Import `MT5Client` for generic MT5 data access, schema normalization, and optional order primitives. `Mt5CliClient` remains available as a backward-compatible alias.
+
+```python
+from datetime import UTC, datetime
+from pathlib import Path
+
+from mt5cli import (
+    DataKind,
+    Dataset,
+    MT5Client,
+    build_config,
+    collect_history,
+    export_dataframe,
+    load_rate_data,
+    minimum_margins,
+    mt5_session,
+    normalize_dataframe,
+    recent_ticks,
+    resolve_rate_view_name,
+)
+
+# Persistent session for multiple calls
+with mt5_session(build_config(login=12345, server="Broker-Demo")) as client:
+    rates = client.copy_rates_range(
+        "EURUSD",
+        timeframe="H1",
+        date_from="2024-01-01",
+        date_to="2024-02-01",
+    )
+    positions = client.positions()
+    check = client.order_check({"action": 1, "symbol": "EURUSD", "volume": 0.1})
+
+# Normalize MT5 frames to the public schema contract before storage
+closed_rates = normalize_dataframe(
+    rates, DataKind.rates, symbol="EURUSD", timeframe="H1"
+)
+export_dataframe(closed_rates, Path("rates.csv"), "csv")
+
+# Offline rate loading from mt5cli-managed SQLite history
+view = resolve_rate_view_name(Path("history.db"), "EURUSD", "M1", require_existing=True)
+offline_rates = load_rate_data(Path("history.db"), view, count=1000)
+
+# One-off helpers still work without instantiating a client
+ticks = recent_ticks("EURUSD", seconds=300)
+margins = minimum_margins("EURUSD")
+
+collect_history(
+    Path("history.db"),
+    symbols=["EURUSD", "GBPUSD"],
+    date_from=datetime(2024, 1, 1, tzinfo=UTC),
+    date_to=datetime(2024, 2, 1, tzinfo=UTC),
+    datasets={Dataset.rates, Dataset.history_deals},
+)
+```
+
+Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `normalize_dataframe`). Storage helpers are re-exported from `mt5cli.storage` and the package root.
+
+`MT5Client.order_send()` is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly (the CLI requires `--yes` for `order-send`).
+
+`MT5Client.mt5_summary()` returns structured nested Python values. Use `MT5Client.mt5_summary_as_df()` when you need a one-row DataFrame for export.
+
 ## Quick Start
 
 ```bash
@@ -50,14 +120,16 @@ mt5cli --login 12345 --password mypass --server MyBroker-Demo \
 | ---------------- | ---------------------------------- |
 | `rates-from`     | Export rates from a start date     |
 | `rates-from-pos` | Export rates from a start position |
+| `latest-rates`   | Export latest rates                |
 | `rates-range`    | Export rates for a date range      |
 
 ### Ticks
 
-| Command       | Description                    |
-| ------------- | ------------------------------ |
-| `ticks-from`  | Export ticks from a start date |
-| `ticks-range` | Export ticks for a date range  |
+| Command        | Description                         |
+| -------------- | ----------------------------------- |
+| `ticks-from`   | Export ticks from a start date      |
+| `ticks-range`  | Export ticks for a date range       |
+| `ticks-recent` | Export ticks from a trailing window |
 
 ### Information
 
@@ -70,18 +142,21 @@ mt5cli --login 12345 --password mypass --server MyBroker-Demo \
 | `symbols`          | Export symbol list                      |
 | `symbol-info`      | Export symbol details                   |
 | `symbol-info-tick` | Export the last tick for a symbol       |
+| `minimum-margins`  | Export minimum-volume margin summary    |
 | `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                                     |
-| `order-check`    | Check funds sufficiency for a trade request                 |
-| `order-send`     | Send a trade request to the trade server (`--yes` required) |
+| Command                | Description                                                 |
+| ---------------------- | ----------------------------------------------------------- |
+| `orders`               | Export active orders                                        |
+| `positions`            | Export open positions                                       |
+| `history-orders`       | Export historical orders                                    |
+| `history-deals`        | Export historical deals                                     |
+| `recent-history-deals` | Export historical deals from a trailing window              |
+| `mt5-summary`          | Export terminal/account status summary                      |
+| `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`.
 
@@ -114,6 +189,8 @@ mt5cli -o history.db collect-history \
 
 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
 
 | Option         | Description                                             |
@@ -138,7 +215,9 @@ History orders and deals are fetched per symbol and concatenated, so the symbol
 
 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
 

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: mt5cli API Documentation
-site_description: Command-line tool for MetaTrader 5
+site_description: Generic MT5 data and execution infrastructure for Python
 site_author: dceoy
 site_url: https://github.com/dceoy/mt5cli
 
@@ -24,6 +24,7 @@ theme:
   features:
     - content.code.annotate
     - content.code.copy
+    - content.code.mermaid
     - navigation.indexes
     - navigation.sections
     - navigation.tabs
@@ -55,7 +56,16 @@ nav:
   - Home: index.md
   - API Reference:
       - Overview: api/index.md
+      - Client: api/client.md
+      - Schemas: api/schemas.md
+      - Storage: api/storage.md
+      - Converters: api/converters.md
+      - Exceptions: api/exceptions.md
       - CLI: api/cli.md
+      - SDK: api/sdk.md
+      - Trading: api/trading.md
+      - History Collection (SQLite): api/history.md
+      - Utils: api/utils.md
 
 markdown_extensions:
   - admonition

mt5cli/__init__.py

@@ -1,12 +1,247 @@
-"""mt5cli: Command-line tool for MetaTrader 5."""
+"""mt5cli: Generic MT5 data and execution infrastructure for Python applications."""
 
 from importlib.metadata import version
 
-from .cli import detect_format, export_dataframe
+from pdmt5 import Mt5Config, Mt5RuntimeError, Mt5TradingClient, Mt5TradingError
+
+from .client import MT5Client, build_config, mt5_session
+from .converters import (
+    ensure_utc,
+    granularity_name,
+    normalize_symbol,
+    normalize_symbols,
+    parse_date_range,
+    recent_window,
+)
+from .exceptions import (
+    Mt5CliError,
+    Mt5ConnectionError,
+    Mt5OperationError,
+    Mt5SchemaError,
+    call_with_normalized_errors,
+    is_recoverable_mt5_error,
+    normalize_mt5_exception,
+)
+from .history import (
+    RateTarget,
+    build_rate_targets,
+    build_rate_view_name,
+    drop_forming_rate_bar,
+    load_rate_data,
+    load_rate_data_from_connection,
+    load_rate_series_by_granularity,
+    load_rate_series_from_sqlite,
+    resolve_history_datasets,
+    resolve_history_tick_flags,
+    resolve_history_timeframes,
+    resolve_rate_table_name,
+    resolve_rate_tables,
+    resolve_rate_view_name,
+    resolve_rate_view_names,
+)
+from .schemas import (
+    DEDUP_KEYS,
+    KNOWN_MT5_TIME_COLUMNS,
+    REQUIRED_COLUMNS,
+    TIME_COLUMNS,
+    DataKind,
+    normalize_dataframe,
+    normalize_time_columns,
+    schema_columns,
+    validate_schema,
+)
+from .sdk import (
+    AccountSpec,
+    Mt5CliClient,
+    ThrottledHistoryUpdater,
+    account_info,
+    collect_history,
+    collect_latest_closed_rates_by_granularity,
+    collect_latest_closed_rates_for_accounts,
+    collect_latest_rates,
+    collect_latest_rates_for_accounts,
+    collect_latest_rates_for_accounts_with_retries,
+    copy_rates_from,
+    copy_rates_from_pos,
+    copy_rates_range,
+    copy_ticks_from,
+    copy_ticks_range,
+    fetch_latest_closed_rates,
+    history_deals,
+    history_orders,
+    last_error,
+    latest_rates,
+    market_book,
+    minimum_margins,
+    mt5_summary,
+    mt5_summary_as_df,
+    orders,
+    positions,
+    recent_history_deals,
+    recent_ticks,
+    resolve_account_spec,
+    resolve_account_specs,
+    substitute_env_placeholders,
+    symbol_info,
+    symbol_info_tick,
+    symbols,
+    terminal_info,
+    update_history,
+    update_history_with_config,
+)
+from .sdk import (
+    version as mt5_version,
+)
+from .storage import (
+    Dataset,
+    IfExists,
+    detect_format,
+    export_dataframe,
+    export_dataframe_to_sqlite,
+)
+from .trading import (
+    POSITION_COLUMNS,
+    OrderFillingMode,
+    OrderSide,
+    OrderTimeMode,
+    PositionSide,
+    calculate_margin_and_volume,
+    calculate_new_position_margin_ratio,
+    calculate_spread_ratio,
+    calculate_volume_by_margin,
+    close_open_positions,
+    create_trading_client,
+    detect_position_side,
+    determine_order_limits,
+    get_account_snapshot,
+    get_positions_frame,
+    get_symbol_snapshot,
+    get_tick_snapshot,
+    mt5_trading_session,
+    place_market_order,
+    update_sltp_for_open_positions,
+)
+from .utils import (
+    TICK_FLAG_MAP,
+    TIMEFRAME_MAP,
+    parse_datetime,
+    parse_tick_flags,
+    parse_timeframe,
+)
 
 __version__ = version(__package__) if __package__ else None
 
 __all__ = [
+    "DEDUP_KEYS",
+    "KNOWN_MT5_TIME_COLUMNS",
+    "POSITION_COLUMNS",
+    "REQUIRED_COLUMNS",
+    "TICK_FLAG_MAP",
+    "TIMEFRAME_MAP",
+    "TIME_COLUMNS",
+    "AccountSpec",
+    "DataKind",
+    "Dataset",
+    "IfExists",
+    "MT5Client",
+    "Mt5CliClient",
+    "Mt5CliError",
+    "Mt5Config",
+    "Mt5ConnectionError",
+    "Mt5OperationError",
+    "Mt5RuntimeError",
+    "Mt5SchemaError",
+    "Mt5TradingClient",
+    "Mt5TradingError",
+    "OrderFillingMode",
+    "OrderSide",
+    "OrderTimeMode",
+    "PositionSide",
+    "RateTarget",
+    "ThrottledHistoryUpdater",
+    "account_info",
+    "build_config",
+    "build_rate_targets",
+    "build_rate_view_name",
+    "calculate_margin_and_volume",
+    "calculate_new_position_margin_ratio",
+    "calculate_spread_ratio",
+    "calculate_volume_by_margin",
+    "call_with_normalized_errors",
+    "close_open_positions",
+    "collect_history",
+    "collect_latest_closed_rates_by_granularity",
+    "collect_latest_closed_rates_for_accounts",
+    "collect_latest_rates",
+    "collect_latest_rates_for_accounts",
+    "collect_latest_rates_for_accounts_with_retries",
+    "copy_rates_from",
+    "copy_rates_from_pos",
+    "copy_rates_range",
+    "copy_ticks_from",
+    "copy_ticks_range",
+    "create_trading_client",
     "detect_format",
+    "detect_position_side",
+    "determine_order_limits",
+    "drop_forming_rate_bar",
+    "ensure_utc",
     "export_dataframe",
+    "export_dataframe_to_sqlite",
+    "fetch_latest_closed_rates",
+    "get_account_snapshot",
+    "get_positions_frame",
+    "get_symbol_snapshot",
+    "get_tick_snapshot",
+    "granularity_name",
+    "history_deals",
+    "history_orders",
+    "is_recoverable_mt5_error",
+    "last_error",
+    "latest_rates",
+    "load_rate_data",
+    "load_rate_data_from_connection",
+    "load_rate_series_by_granularity",
+    "load_rate_series_from_sqlite",
+    "market_book",
+    "minimum_margins",
+    "mt5_session",
+    "mt5_summary",
+    "mt5_summary_as_df",
+    "mt5_trading_session",
+    "mt5_version",
+    "normalize_dataframe",
+    "normalize_mt5_exception",
+    "normalize_symbol",
+    "normalize_symbols",
+    "normalize_time_columns",
+    "orders",
+    "parse_date_range",
+    "parse_datetime",
+    "parse_tick_flags",
+    "parse_timeframe",
+    "place_market_order",
+    "positions",
+    "recent_history_deals",
+    "recent_ticks",
+    "recent_window",
+    "resolve_account_spec",
+    "resolve_account_specs",
+    "resolve_history_datasets",
+    "resolve_history_tick_flags",
+    "resolve_history_timeframes",
+    "resolve_rate_table_name",
+    "resolve_rate_tables",
+    "resolve_rate_view_name",
+    "resolve_rate_view_names",
+    "schema_columns",
+    "substitute_env_placeholders",
+    "symbol_info",
+    "symbol_info_tick",
+    "symbols",
+    "terminal_info",
+    "update_history",
+    "update_history_with_config",
+    "update_sltp_for_open_positions",
+    "validate_schema",
 ]

mt5cli/client.py

@@ -0,0 +1,88 @@
+"""Stable public client abstraction for MT5 data and execution operations."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any, Self
+
+from .sdk import Mt5CliClient, build_config, connected_client
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    import pandas as pd
+    from pdmt5 import Mt5Config, Mt5DataClient
+
+__all__ = [
+    "MT5Client",
+    "build_config",
+    "mt5_session",
+]
+
+
+class MT5Client(Mt5CliClient):
+    """Public client for generic MT5 data access and order primitives.
+
+    Extends the read-only SDK client with optional order check/send helpers and
+    exposes the same connection lifecycle as :class:`~mt5cli.sdk.Mt5CliClient`.
+    Downstream applications such as private trading packages should prefer this
+    type over the legacy ``Mt5CliClient`` name.
+
+    mt5cli intentionally exposes minimal execution primitives only. Trading
+    decisions, signals, strategies, backtests, and optimization remain the
+    responsibility of downstream applications.
+    """
+
+    def order_check(self, request: dict[str, Any]) -> pd.DataFrame:
+        """Check funds sufficiency for a trade request.
+
+        Args:
+            request: MT5 order request dictionary.
+
+        Returns:
+            One-row DataFrame with the order-check result.
+        """
+        return self._fetch(lambda client: client.order_check_as_df(request=request))
+
+    def order_send(self, request: dict[str, Any]) -> pd.DataFrame:
+        """Send a live trade request to the MT5 trade server.
+
+        Warning:
+            This is a live execution primitive. A successful call can place,
+            modify, or close real trades on the connected account. Downstream
+            applications must gate usage explicitly (for example behind manual
+            confirmation or application-specific risk controls). mt5cli does
+            not implement strategy logic, signal generation, or trade sizing.
+
+        Args:
+            request: MT5 order request dictionary.
+
+        Returns:
+            One-row DataFrame with the order-send result.
+        """
+        return self._fetch(lambda client: client.order_send_as_df(request=request))
+
+    @classmethod
+    def from_connected_client(cls, client: Mt5DataClient) -> Self:
+        """Bind to an already-connected ``Mt5DataClient`` without owning it.
+
+        Returns:
+            Client wrapper bound to the injected connection.
+        """
+        return cls(client=client)
+
+
+@contextmanager
+def mt5_session(config: Mt5Config | None = None) -> Iterator[MT5Client]:
+    """Open an MT5 terminal session and yield a connected :class:`MT5Client`.
+
+    Args:
+        config: MT5 connection configuration. Defaults to an empty config that
+            attaches to a running terminal.
+
+    Yields:
+        Connected :class:`MT5Client` bound to the session.
+    """
+    mt5_config = config or build_config()
+    with connected_client(mt5_config) as client:
+        yield MT5Client.from_connected_client(client)

mt5cli/converters.py

@@ -0,0 +1,162 @@
+"""Shared conversion helpers for MT5 symbols, timeframes, and date ranges."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+from pdmt5 import get_timeframe_name as _get_timeframe_name
+
+from .utils import parse_datetime, parse_tick_flags, parse_timeframe
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = [
+    "ensure_utc",
+    "granularity_name",
+    "normalize_symbol",
+    "normalize_symbols",
+    "parse_date_range",
+    "parse_datetime",
+    "parse_tick_flags",
+    "parse_timeframe",
+    "recent_window",
+]
+
+
+def normalize_symbol(symbol: str) -> str:
+    """Normalize a broker symbol name for MT5 API calls.
+
+    Strips surrounding whitespace while preserving broker-specific casing and
+    suffixes (for example ``XAUUSDm``, ``US500.cash``, or ``EURUSD.r``).
+
+    Args:
+        symbol: Raw symbol name.
+
+    Returns:
+        Normalized symbol string.
+
+    Raises:
+        ValueError: If the symbol is empty after normalization.
+    """
+    normalized = symbol.strip()
+    if not normalized:
+        msg = "Symbol must not be empty."
+        raise ValueError(msg)
+    return normalized
+
+
+def normalize_symbols(symbols: Sequence[str]) -> list[str]:
+    """Normalize a sequence of broker symbol names.
+
+    Args:
+        symbols: Raw symbol names.
+
+    Returns:
+        List of normalized, de-duplicated symbols preserving first-seen order.
+    """
+    seen: set[str] = set()
+    resolved: list[str] = []
+    for symbol in symbols:
+        normalized = normalize_symbol(symbol)
+        if normalized not in seen:
+            seen.add(normalized)
+            resolved.append(normalized)
+    return resolved
+
+
+def ensure_utc(value: datetime | str) -> datetime:
+    """Return a timezone-aware UTC datetime.
+
+    Args:
+        value: Datetime instance or ISO 8601 string.
+
+    Returns:
+        UTC-aware datetime.
+    """
+    if isinstance(value, str):
+        return parse_datetime(value)
+    if value.tzinfo is None:
+        return value.replace(tzinfo=UTC)
+    return value.astimezone(UTC)
+
+
+def parse_date_range(
+    date_from: datetime | str,
+    date_to: datetime | str,
+) -> tuple[datetime, datetime]:
+    """Parse and validate an inclusive UTC date range.
+
+    Args:
+        date_from: Range start as datetime or ISO 8601 string.
+        date_to: Range end as datetime or ISO 8601 string.
+
+    Returns:
+        Tuple of UTC-aware ``(start, end)`` datetimes.
+
+    Raises:
+        ValueError: If ``date_from`` is after ``date_to``.
+    """
+    start = ensure_utc(date_from)
+    end = ensure_utc(date_to)
+    if start > end:
+        msg = (
+            f"date_from ({start.isoformat()}) must not be after "
+            f"date_to ({end.isoformat()})."
+        )
+        raise ValueError(msg)
+    return start, end
+
+
+def recent_window(
+    *,
+    hours: float | None = None,
+    seconds: float | None = None,
+    date_to: datetime | str | None = None,
+) -> tuple[datetime, datetime]:
+    """Build a trailing UTC window ending at ``date_to`` or now.
+
+    Exactly one of ``hours`` or ``seconds`` must be provided.
+
+    Args:
+        hours: Trailing window length in hours.
+        seconds: Trailing window length in seconds.
+        date_to: Window end. Defaults to current UTC time.
+
+    Returns:
+        Tuple of UTC-aware ``(start, end)`` datetimes.
+
+    Raises:
+        ValueError: If neither or both window lengths are provided, or if a
+            length is not positive.
+    """
+    if (hours is None) == (seconds is None):
+        msg = "Provide exactly one of hours or seconds."
+        raise ValueError(msg)
+    if hours is not None:
+        length = timedelta(hours=hours)
+    else:
+        length = timedelta(seconds=seconds if seconds is not None else 0)
+    if length.total_seconds() <= 0:
+        msg = "Window length must be positive."
+        raise ValueError(msg)
+    end = ensure_utc(date_to) if date_to is not None else datetime.now(UTC)
+    return end - length, end
+
+
+def granularity_name(timeframe: int | str) -> str:
+    """Return a short granularity label for a timeframe integer or name.
+
+    Args:
+        timeframe: MT5 timeframe as integer or name (for example ``M1``).
+
+    Returns:
+        Short name such as ``M1`` or the stringified integer when unknown.
+    """
+    tf = parse_timeframe(timeframe)
+    try:
+        name = _get_timeframe_name(tf)
+    except ValueError:
+        return str(tf)
+    return name.removeprefix("TIMEFRAME_")

mt5cli/exceptions.py

@@ -0,0 +1,90 @@
+"""Normalized exception types for MT5 and mt5cli operations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar
+
+from pdmt5 import Mt5RuntimeError, Mt5TradingError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar("T")
+
+__all__ = [
+    "Mt5CliError",
+    "Mt5ConnectionError",
+    "Mt5OperationError",
+    "Mt5SchemaError",
+    "call_with_normalized_errors",
+    "is_recoverable_mt5_error",
+    "normalize_mt5_exception",
+]
+
+_RECOVERABLE_MT5_ERRORS: tuple[type[BaseException], ...] = (
+    Mt5TradingError,
+    Mt5RuntimeError,
+)
+
+
+class Mt5CliError(Exception):
+    """Base exception for mt5cli public API errors."""
+
+
+class Mt5ConnectionError(Mt5CliError):
+    """Raised when MT5 initialization, login, or shutdown fails."""
+
+
+class Mt5OperationError(Mt5CliError):
+    """Raised when an MT5 data or trading operation fails."""
+
+
+class Mt5SchemaError(Mt5CliError):
+    """Raised when a DataFrame does not match an expected dataset schema."""
+
+
+def is_recoverable_mt5_error(exc: BaseException) -> bool:
+    """Return whether an exception is a transient MT5 failure worth retrying.
+
+    Args:
+        exc: Exception raised by MT5 or pdmt5.
+
+    Returns:
+        True for ``Mt5RuntimeError`` and ``Mt5TradingError``.
+    """
+    return isinstance(exc, _RECOVERABLE_MT5_ERRORS)
+
+
+def normalize_mt5_exception(exc: BaseException) -> Mt5CliError:
+    """Map pdmt5/MT5 exceptions to stable mt5cli exception types.
+
+    Args:
+        exc: Original exception from MT5 or pdmt5.
+
+    Returns:
+        ``Mt5ConnectionError`` for runtime failures, ``Mt5OperationError`` for
+        trading failures, or the original exception when it is not recognized.
+    """
+    if isinstance(exc, Mt5TradingError):
+        return Mt5OperationError(str(exc))
+    if isinstance(exc, Mt5RuntimeError):
+        return Mt5ConnectionError(str(exc))
+    if isinstance(exc, Mt5CliError):
+        return exc
+    return Mt5CliError(str(exc))
+
+
+def call_with_normalized_errors(fn: Callable[[], T]) -> T:
+    """Run ``fn`` and map recoverable MT5 errors to mt5cli types.
+
+    Args:
+        fn: Callable performing MT5 work.
+
+    Returns:
+        Value returned by ``fn``.
+    """
+    try:
+        return fn()
+    except _RECOVERABLE_MT5_ERRORS as exc:
+        normalized = normalize_mt5_exception(exc)
+        raise normalized from exc

mt5cli/retry.py

@@ -0,0 +1,64 @@
+"""Retry and reconnect helpers for transient MT5 failures."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import TYPE_CHECKING, TypeVar
+
+from .exceptions import is_recoverable_mt5_error
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+T = TypeVar("T")
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "retry_with_backoff",
+]
+
+
+def retry_with_backoff(
+    fn: Callable[[], T],
+    *,
+    retry_count: int = 0,
+    backoff_base: float = 2.0,
+    operation: str = "MT5 operation",
+) -> T:
+    """Call ``fn`` with bounded exponential backoff on recoverable MT5 errors.
+
+    Only ``pdmt5.Mt5RuntimeError`` and ``pdmt5.Mt5TradingError`` are retried.
+    Other exceptions propagate immediately. The final failure is re-raised once
+    retries are exhausted.
+
+    Args:
+        fn: Callable performing MT5 work.
+        retry_count: Maximum number of retries after the first attempt. ``0``
+            disables retries.
+        backoff_base: Base for exponential backoff. The delay before retry
+            attempt ``n`` (1-indexed) is ``backoff_base ** n`` seconds.
+        operation: Label used in warning logs.
+
+    Returns:
+        Value returned by ``fn`` on success.
+    """
+    attempts = max(retry_count, 0) + 1
+    for attempt in range(attempts - 1):
+        try:
+            return fn()
+        except Exception as exc:
+            if not is_recoverable_mt5_error(exc):
+                raise
+            delay = backoff_base ** (attempt + 1)
+            logger.warning(
+                "%s failed (attempt %d/%d): %s; retrying in %.1fs",
+                operation,
+                attempt + 1,
+                attempts,
+                exc,
+                delay,
+            )
+            time.sleep(delay)
+    return fn()

mt5cli/schemas.py

@@ -0,0 +1,291 @@
+"""Canonical DataFrame schemas for MT5 market and account datasets."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import TYPE_CHECKING, Final
+
+import pandas as pd
+
+from .converters import normalize_symbol, parse_timeframe
+from .exceptions import Mt5SchemaError
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+__all__ = [
+    "DEDUP_KEYS",
+    "KNOWN_MT5_TIME_COLUMNS",
+    "REQUIRED_COLUMNS",
+    "TIME_COLUMNS",
+    "DataKind",
+    "normalize_dataframe",
+    "normalize_time_columns",
+    "schema_columns",
+    "validate_schema",
+]
+
+KNOWN_MT5_TIME_COLUMNS: Final[frozenset[str]] = frozenset({
+    "time",
+    "time_setup",
+    "time_setup_msc",
+    "time_done",
+    "time_done_msc",
+    "time_msc",
+})
+
+_TIME_COLUMN_NAMES = KNOWN_MT5_TIME_COLUMNS
+
+
+class DataKind(StrEnum):
+    """Supported MT5 dataset kinds with canonical column contracts."""
+
+    rates = "rates"
+    ticks = "ticks"
+    orders = "orders"
+    positions = "positions"
+    history_orders = "history_orders"
+    history_deals = "history_deals"
+
+
+REQUIRED_COLUMNS: dict[DataKind, frozenset[str]] = {
+    DataKind.rates: frozenset({
+        "time",
+        "open",
+        "high",
+        "low",
+        "close",
+        "tick_volume",
+        "spread",
+        "real_volume",
+    }),
+    DataKind.ticks: frozenset({
+        "time",
+        "bid",
+        "ask",
+        "last",
+        "volume",
+        "time_msc",
+        "flags",
+        "volume_real",
+    }),
+    DataKind.orders: frozenset({
+        "ticket",
+        "time_setup",
+        "type",
+        "state",
+        "symbol",
+        "volume_current",
+        "price_open",
+    }),
+    DataKind.positions: frozenset({
+        "ticket",
+        "time",
+        "type",
+        "symbol",
+        "volume",
+        "price_open",
+        "price_current",
+        "profit",
+    }),
+    DataKind.history_orders: frozenset({
+        "ticket",
+        "time_setup",
+        "type",
+        "state",
+        "symbol",
+        "volume_initial",
+        "price_open",
+    }),
+    DataKind.history_deals: frozenset({
+        "ticket",
+        "order",
+        "time",
+        "type",
+        "entry",
+        "symbol",
+        "volume",
+        "price",
+        "profit",
+    }),
+}
+
+_OPTIONAL_TIME_COLUMNS_BY_KIND: dict[DataKind, frozenset[str]] = {
+    DataKind.orders: frozenset({
+        "time_setup_msc",
+        "time_done",
+        "time_done_msc",
+    }),
+    DataKind.history_orders: frozenset({
+        "time_setup_msc",
+        "time_done",
+        "time_done_msc",
+    }),
+    DataKind.positions: frozenset({"time_msc"}),
+}
+
+TIME_COLUMNS: dict[DataKind, frozenset[str]] = {
+    kind: (REQUIRED_COLUMNS[kind] & _TIME_COLUMN_NAMES)
+    | _OPTIONAL_TIME_COLUMNS_BY_KIND.get(kind, frozenset())
+    for kind in DataKind
+}
+
+DEDUP_KEYS: dict[DataKind, tuple[tuple[str, ...], ...]] = {
+    DataKind.rates: (("symbol", "timeframe", "time"), ("symbol", "time")),
+    DataKind.ticks: (("symbol", "time_msc"), ("symbol", "time")),
+    DataKind.history_orders: (("ticket",), ("symbol", "time", "type")),
+    DataKind.history_deals: (("ticket",), ("symbol", "time", "type", "entry")),
+}
+
+
+def schema_columns(kind: DataKind) -> frozenset[str]:
+    """Return required column names for a dataset kind.
+
+    Args:
+        kind: Dataset kind.
+
+    Returns:
+        Required column names for ``kind``.
+    """
+    return REQUIRED_COLUMNS[kind]
+
+
+def validate_schema(
+    frame: pd.DataFrame,
+    kind: DataKind,
+    *,
+    extra_required: Iterable[str] | None = None,
+) -> None:
+    """Validate that a DataFrame includes required columns for a dataset kind.
+
+    Args:
+        frame: DataFrame to validate.
+        kind: Expected dataset kind.
+        extra_required: Additional columns that must be present (for example
+            ``symbol`` and ``timeframe`` on stored rate history).
+
+    Raises:
+        Mt5SchemaError: If required columns are missing.
+    """
+    if frame.empty and len(frame.columns) == 0:
+        return
+    required = set(REQUIRED_COLUMNS[kind])
+    if extra_required is not None:
+        required.update(extra_required)
+    missing = required - set(frame.columns)
+    if missing:
+        msg = (
+            f"{kind.value} schema is missing required columns: "
+            f"{', '.join(sorted(missing))}."
+        )
+        raise Mt5SchemaError(msg)
+
+
+def _coerce_mt5_time_column(series: pd.Series, column: str) -> pd.Series:
+    """Coerce one MT5 time column to UTC-aware datetimes.
+
+    Returns:
+        Series with UTC-aware datetime values.
+    """
+    if pd.api.types.is_datetime64_any_dtype(series):
+        return pd.to_datetime(series, utc=True, errors="coerce")
+    if pd.api.types.is_numeric_dtype(series):
+        unit = "ms" if column.endswith("_msc") else "s"
+        return pd.to_datetime(series, unit=unit, utc=True, errors="coerce")
+    return pd.to_datetime(series, utc=True, errors="coerce")
+
+
+def normalize_time_columns(frame: pd.DataFrame, kind: DataKind) -> pd.DataFrame:
+    """Coerce dataset time columns to UTC-aware datetimes when present.
+
+    Any column in :data:`KNOWN_MT5_TIME_COLUMNS` that is present in ``frame``
+    is normalized. Numeric MT5 epoch values use seconds for ``time``,
+    ``time_setup``, and ``time_done``, and milliseconds for ``*_msc`` columns.
+
+    Args:
+        frame: Source DataFrame from MT5 or pdmt5.
+        kind: Dataset kind (retained for API compatibility).
+
+    Returns:
+        DataFrame copy with normalized time columns.
+    """
+    del kind
+    normalized = frame.copy()
+    for column in normalized.columns:
+        if column not in _TIME_COLUMN_NAMES:
+            continue
+        normalized[column] = _coerce_mt5_time_column(normalized[column], column)
+    return normalized
+
+
+def normalize_dataframe(
+    frame: pd.DataFrame,
+    kind: DataKind,
+    *,
+    symbol: str | None = None,
+    timeframe: int | str | None = None,
+    sort: bool = True,
+) -> pd.DataFrame:
+    """Normalize MT5 DataFrame columns, timestamps, and storage metadata.
+
+    Ensures UTC timestamps, optionally injects ``symbol`` / ``timeframe`` for
+    storage-oriented datasets, and sorts chronologically when a ``time`` column
+    exists.
+
+    Args:
+        frame: Source DataFrame from MT5 or pdmt5.
+        kind: Dataset kind guiding normalization rules.
+        symbol: Optional symbol to inject when missing.
+        timeframe: Optional timeframe integer or name to inject for rates.
+        sort: Whether to sort by ``time`` or ``time_msc`` when present.
+
+    Returns:
+        Normalized DataFrame copy.
+    """
+    if frame.empty and len(frame.columns) == 0:
+        return frame.copy()
+
+    normalized = normalize_time_columns(frame, kind)
+
+    if symbol is not None and "symbol" not in normalized.columns:
+        normalized.insert(0, "symbol", normalize_symbol(symbol))
+
+    if timeframe is not None and kind is DataKind.rates:
+        tf = parse_timeframe(timeframe)
+        if "timeframe" not in normalized.columns:
+            insert_at = 1 if "symbol" in normalized.columns else 0
+            normalized.insert(insert_at, "timeframe", tf)
+
+    validate_schema(normalized, kind)
+
+    if sort:
+        if "time" in normalized.columns:
+            normalized = normalized.sort_values("time", kind="stable")
+        elif "time_msc" in normalized.columns:
+            normalized = normalized.sort_values("time_msc", kind="stable")
+        normalized = normalized.reset_index(drop=True)
+
+    return normalized
+
+
+def ensure_utc_columns(frame: pd.DataFrame, columns: Iterable[str]) -> pd.DataFrame:
+    """Return a copy with selected columns coerced to UTC datetimes.
+
+    Args:
+        frame: Source DataFrame.
+        columns: Column names to coerce.
+
+    Returns:
+        DataFrame copy with UTC-aware datetime columns.
+    """
+    normalized = frame.copy()
+    for column in columns:
+        if column not in normalized.columns:
+            continue
+        if column in _TIME_COLUMN_NAMES:
+            normalized[column] = _coerce_mt5_time_column(normalized[column], column)
+        else:
+            normalized[column] = pd.to_datetime(
+                normalized[column], utc=True, errors="coerce"
+            )
+    return normalized

mt5cli/storage.py

@@ -0,0 +1,49 @@
+"""Generic storage helpers for MT5 market and account history."""
+
+from __future__ import annotations
+
+from .history import (
+    RateTarget,
+    build_rate_targets,
+    build_rate_view_name,
+    drop_forming_rate_bar,
+    load_rate_data,
+    load_rate_data_from_connection,
+    load_rate_series_by_granularity,
+    load_rate_series_from_sqlite,
+    resolve_rate_tables,
+    resolve_rate_view_name,
+    resolve_rate_view_names,
+)
+from .sdk import collect_history, update_history, update_history_with_config
+from .utils import (
+    Dataset,
+    IfExists,
+    OutputFormat,
+    detect_format,
+    export_dataframe,
+    export_dataframe_to_sqlite,
+)
+
+__all__ = [
+    "Dataset",
+    "IfExists",
+    "OutputFormat",
+    "RateTarget",
+    "build_rate_targets",
+    "build_rate_view_name",
+    "collect_history",
+    "detect_format",
+    "drop_forming_rate_bar",
+    "export_dataframe",
+    "export_dataframe_to_sqlite",
+    "load_rate_data",
+    "load_rate_data_from_connection",
+    "load_rate_series_by_granularity",
+    "load_rate_series_from_sqlite",
+    "resolve_rate_tables",
+    "resolve_rate_view_name",
+    "resolve_rate_view_names",
+    "update_history",
+    "update_history_with_config",
+]

mt5cli/trading.py

@@ -0,0 +1,861 @@
+"""Trading-capable MetaTrader 5 session helpers and operational utilities."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from math import floor, isfinite
+from typing import TYPE_CHECKING, Literal, cast
+
+import pandas as pd
+from pdmt5 import Mt5Config, Mt5TradingClient, Mt5TradingError
+
+from .sdk import build_config
+from .utils import coerce_login as _coerce_login
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+PositionSide = Literal["long", "short"]
+OrderSide = Literal["BUY", "SELL"]
+OrderFillingMode = Literal["IOC", "FOK", "RETURN"]
+OrderTimeMode = Literal["GTC", "DAY", "SPECIFIED", "SPECIFIED_DAY"]
+_ORDER_FILLING_MODES: frozenset[str] = frozenset({"IOC", "FOK", "RETURN"})
+_ORDER_TIME_MODES: frozenset[str] = frozenset({
+    "GTC",
+    "DAY",
+    "SPECIFIED",
+    "SPECIFIED_DAY",
+})
+_SUCCESS_RETCODE_NAMES: tuple[str, ...] = (
+    "TRADE_RETCODE_DONE",
+    "TRADE_RETCODE_DONE_PARTIAL",
+    "TRADE_RETCODE_PLACED",
+)
+_SUCCESS_RETCODE_FALLBACKS: frozenset[int] = frozenset({10008, 10009, 10010})
+
+_ACCOUNT_SNAPSHOT_FIELDS = (
+    "login",
+    "balance",
+    "equity",
+    "margin",
+    "margin_free",
+    "margin_level",
+    "leverage",
+    "currency",
+)
+_SYMBOL_SNAPSHOT_FIELDS = (
+    "symbol",
+    "visible",
+    "trade_mode",
+    "digits",
+    "point",
+    "volume_min",
+    "volume_max",
+    "volume_step",
+    "trade_contract_size",
+    "trade_tick_size",
+    "trade_tick_value",
+    "trade_stops_level",
+    "filling_mode",
+)
+_TICK_SNAPSHOT_FIELDS = ("symbol", "time", "bid", "ask", "last", "volume")
+POSITION_COLUMNS = (
+    "ticket",
+    "time",
+    "symbol",
+    "type",
+    "volume",
+    "price_open",
+    "sl",
+    "tp",
+    "price_current",
+    "profit",
+    "swap",
+    "comment",
+)
+
+__all__ = [
+    "POSITION_COLUMNS",
+    "OrderFillingMode",
+    "OrderSide",
+    "OrderTimeMode",
+    "PositionSide",
+    "calculate_margin_and_volume",
+    "calculate_new_position_margin_ratio",
+    "calculate_spread_ratio",
+    "calculate_volume_by_margin",
+    "close_open_positions",
+    "create_trading_client",
+    "detect_position_side",
+    "determine_order_limits",
+    "get_account_snapshot",
+    "get_positions_frame",
+    "get_symbol_snapshot",
+    "get_tick_snapshot",
+    "mt5_trading_session",
+    "place_market_order",
+    "update_sltp_for_open_positions",
+]
+
+
+def _require_unit_ratio(value: float, name: str) -> None:
+    if not 0.0 <= value <= 1.0:
+        msg = f"{name} must be between 0 and 1 inclusive."
+        raise ValueError(msg)
+
+
+def _require_protective_ratio(value: float, name: str) -> None:
+    if not 0.0 <= value < 1.0:
+        msg = f"{name} must be at least 0 and less than 1."
+        raise ValueError(msg)
+
+
+def _sum_position_volume(positions: pd.DataFrame, position_type: object) -> float:
+    matched = positions.loc[positions["type"] == position_type, "volume"]
+    if matched.empty:
+        return 0.0
+    return float(matched.to_numpy(dtype=float).sum())
+
+
+def _resolve_config(
+    *,
+    config: Mt5Config | None,
+    login: int | str | None,
+    password: str | None,
+    server: str | None,
+    path: str | None,
+    timeout: int | None,
+) -> Mt5Config:
+    if config is not None:
+        return config
+    return build_config(
+        path=path,
+        login=_coerce_login(login),
+        password=password,
+        server=server,
+        timeout=timeout,
+    )
+
+
+def _normalize_order_side(side: str) -> OrderSide:
+    normalized = side.upper()
+    if normalized in {"BUY", "LONG"}:
+        return "BUY"
+    if normalized in {"SELL", "SHORT"}:
+        return "SELL"
+    msg = f"Unsupported order side: {side!r}. Expected 'BUY' or 'SELL'."
+    raise ValueError(msg)
+
+
+def _position_side_from_order_side(side: str) -> PositionSide:
+    normalized = side.lower()
+    if normalized in {"long", "buy"}:
+        return "long"
+    if normalized in {"short", "sell"}:
+        return "short"
+    msg = f"Unsupported position side: {side!r}. Expected 'long' or 'short'."
+    raise ValueError(msg)
+
+
+def _snapshot_from_value(value: object, fields: tuple[str, ...]) -> dict[str, object]:
+    if isinstance(value, pd.DataFrame):
+        row: dict[str, object] = (
+            {} if value.empty else cast("dict[str, object]", value.iloc[0].to_dict())
+        )
+    else:
+        asdict = getattr(value, "_asdict", None)
+        if callable(asdict):
+            row = cast("dict[str, object]", asdict())
+        elif isinstance(value, dict):
+            typed_value = cast("dict[object, object]", value)
+            row = {str(key): item for key, item in typed_value.items()}
+        else:
+            row = {
+                field: getattr(value, field)
+                for field in fields
+                if hasattr(value, field)
+            }
+    if not fields:
+        return row
+    return {field: row.get(field) for field in fields}
+
+
+def _call_snapshot_method(client: Mt5TradingClient, *names: str) -> object:
+    for name in names:
+        method = getattr(client, name, None)
+        if callable(method):
+            return method()
+    msg = f"MT5 client is missing required method: {' or '.join(names)}"
+    raise AttributeError(msg)
+
+
+def _resolve_mt5_constant(
+    mt5: object,
+    prefix: str,
+    value: str,
+    allowed: frozenset[str],
+) -> int:
+    normalized = value.upper()
+    if normalized not in allowed:
+        msg = f"Unsupported {prefix.lower()} mode: {value!r}."
+        raise ValueError(msg)
+    name = f"{prefix}_{normalized}"
+    try:
+        return cast("int", getattr(mt5, name))
+    except AttributeError as exc:
+        msg = f"MT5 module is missing required constant: {name}"
+        raise Mt5TradingError(msg) from exc
+
+
+def _optional_price(value: object) -> float | None:
+    if value is None:
+        return None
+    if not isinstance(value, int | float):
+        return None
+    price = float(value)
+    if price <= 0 or not isfinite(price):
+        return None
+    return price
+
+
+def _success_retcodes(mt5: object) -> frozenset[int]:
+    values = {
+        value
+        for name in _SUCCESS_RETCODE_NAMES
+        if isinstance(value := getattr(mt5, name, None), int)
+    }
+    return frozenset(values) or _SUCCESS_RETCODE_FALLBACKS
+
+
+def _order_status_from_retcode(mt5: object, retcode: object) -> str:
+    if retcode is None:
+        return "executed"
+    if isinstance(retcode, int) and retcode not in _success_retcodes(mt5):
+        return "failed"
+    return "executed"
+
+
+def _calculate_min_volume_if_affordable(
+    client: Mt5TradingClient,
+    symbol: str,
+    available_margin: float,
+    order_side: OrderSide,
+) -> float:
+    if available_margin <= 0:
+        return 0.0
+    symbol_info = get_symbol_snapshot(client, symbol)
+    volume_min = float(symbol_info.get("volume_min") or 0.0)
+    volume_max = float(symbol_info.get("volume_max") or 0.0)
+    volume_step = float(symbol_info.get("volume_step") or volume_min or 0.0)
+    if (
+        volume_min <= 0
+        or volume_step <= 0
+        or (volume_max > 0 and volume_min > volume_max)
+    ):
+        msg = f"Invalid volume constraints for {symbol!r}."
+        raise Mt5TradingError(msg)
+    side = _normalize_order_side(order_side)
+    tick = get_tick_snapshot(client, symbol)
+    price = tick["ask"] if side == "BUY" else tick["bid"]
+    if not isinstance(price, int | float) or price <= 0:
+        msg = f"Tick price is unavailable for {symbol!r}."
+        raise Mt5TradingError(msg)
+    order_type = (
+        client.mt5.ORDER_TYPE_BUY if side == "BUY" else client.mt5.ORDER_TYPE_SELL
+    )
+    min_margin = float(client.order_calc_margin(order_type, symbol, volume_min, price))
+    return round(volume_min, 10) if 0 < min_margin <= available_margin else 0.0
+
+
+def create_trading_client(
+    *,
+    config: Mt5Config | None = None,
+    login: int | str | None = None,
+    password: str | None = None,
+    server: str | None = None,
+    path: str | None = None,
+    timeout: int | None = None,
+    retry_count: int = 0,
+) -> Mt5TradingClient:
+    """Return an initialized and logged-in trading client."""
+    mt5_config = _resolve_config(
+        config=config,
+        login=login,
+        password=password,
+        server=server,
+        path=path,
+        timeout=timeout,
+    )
+    client = Mt5TradingClient(config=mt5_config, retry_count=retry_count)
+    try:
+        client.initialize_and_login_mt5()
+    except Exception:
+        client.shutdown()
+        raise
+    return client
+
+
+def detect_position_side(
+    client: Mt5TradingClient,
+    symbol: str,
+) -> PositionSide | None:
+    """Detect the net open position side for a symbol.
+
+    Args:
+        client: Connected ``Mt5TradingClient`` instance.
+        symbol: Symbol to inspect.
+
+    Returns:
+        ``"long"`` when there are buy positions and no sell positions,
+        ``"short"`` when there are sell positions and no buy positions, or
+        ``None`` when no positions or mixed exposure exists.
+    """
+    positions = get_positions_frame(client, symbol=symbol)
+    if positions.empty:
+        return None
+
+    buy_type = client.mt5.POSITION_TYPE_BUY
+    sell_type = client.mt5.POSITION_TYPE_SELL
+    buy_volume = _sum_position_volume(positions, buy_type)
+    sell_volume = _sum_position_volume(positions, sell_type)
+    if buy_volume > 0 and sell_volume == 0:
+        return "long"
+    if sell_volume > 0 and buy_volume == 0:
+        return "short"
+    return None
+
+
+def get_account_snapshot(
+    client: Mt5TradingClient,
+) -> dict[str, float | int | str | None]:
+    """Return normalized account state with stable keys."""
+    value = _call_snapshot_method(client, "account_info_as_dict", "account_info")
+    return cast(
+        "dict[str, float | int | str | None]",
+        _snapshot_from_value(value, _ACCOUNT_SNAPSHOT_FIELDS),
+    )
+
+
+def get_symbol_snapshot(
+    client: Mt5TradingClient,
+    symbol: str,
+) -> dict[str, float | int | str | bool | None]:
+    """Return normalized symbol metadata required for trading decisions."""
+    method = getattr(client, "symbol_info_as_dict", None)
+    value = method(symbol=symbol) if callable(method) else client.symbol_info(symbol)
+    snapshot = _snapshot_from_value(value, _SYMBOL_SNAPSHOT_FIELDS)
+    snapshot["symbol"] = snapshot.get("symbol") or symbol
+    return cast("dict[str, float | int | str | bool | None]", snapshot)
+
+
+def get_tick_snapshot(
+    client: Mt5TradingClient,
+    symbol: str,
+) -> dict[str, float | int | None]:
+    """Return normalized latest tick data, including bid, ask, and timestamp."""
+    method = getattr(client, "symbol_info_tick_as_dict", None)
+    value = (
+        method(symbol=symbol) if callable(method) else client.symbol_info_tick(symbol)
+    )
+    snapshot = _snapshot_from_value(value, _TICK_SNAPSHOT_FIELDS)
+    snapshot["symbol"] = snapshot.get("symbol") or symbol
+    return cast("dict[str, float | int | None]", snapshot)
+
+
+def get_positions_frame(
+    client: Mt5TradingClient,
+    symbol: str | None = None,
+) -> pd.DataFrame:
+    """Return open positions as a DataFrame with stable baseline columns."""
+    frame = client.positions_get_as_df(symbol=symbol)
+    for column in POSITION_COLUMNS:
+        if column not in frame.columns:
+            frame[column] = pd.Series(dtype="object")
+    return frame
+
+
+def calculate_spread_ratio(client: Mt5TradingClient, symbol: str) -> float:
+    """Return ``(ask - bid) / ((ask + bid) / 2)`` for the latest tick.
+
+    Raises:
+        Mt5TradingError: If bid or ask is unavailable or non-positive.
+    """
+    tick = get_tick_snapshot(client, symbol)
+    bid = tick.get("bid")
+    ask = tick.get("ask")
+    if not isinstance(bid, int | float) or not isinstance(ask, int | float):
+        msg = f"Tick bid/ask is unavailable for {symbol!r}."
+        raise Mt5TradingError(msg)
+    if bid <= 0 or ask <= 0:
+        msg = f"Tick bid/ask must be positive for {symbol!r}."
+        raise Mt5TradingError(msg)
+    return (float(ask) - float(bid)) / ((float(ask) + float(bid)) / 2.0)
+
+
+def calculate_new_position_margin_ratio(
+    client: Mt5TradingClient,
+    *,
+    symbol: str,
+    new_position_side: OrderSide | None = None,
+    new_position_volume: float = 0.0,
+) -> float:
+    """Return total margin/equity ratio after an optional hypothetical position.
+
+    Raises:
+        Mt5TradingError: If equity or required tick data is invalid.
+    """
+    account = get_account_snapshot(client)
+    equity = float(account.get("equity") or 0.0)
+    if equity <= 0:
+        msg = "Account equity must be positive to calculate margin ratio."
+        raise Mt5TradingError(msg)
+    margin = float(account.get("margin") or 0.0)
+    if new_position_side is not None and new_position_volume > 0:
+        side = _normalize_order_side(new_position_side)
+        tick = get_tick_snapshot(client, symbol)
+        price = tick["ask"] if side == "BUY" else tick["bid"]
+        if not isinstance(price, int | float) or price <= 0:
+            msg = f"Tick price is unavailable for {symbol!r}."
+            raise Mt5TradingError(msg)
+        order_type = (
+            client.mt5.ORDER_TYPE_BUY if side == "BUY" else client.mt5.ORDER_TYPE_SELL
+        )
+        margin += float(
+            client.order_calc_margin(order_type, symbol, new_position_volume, price),
+        )
+    return margin / equity
+
+
+def calculate_margin_and_volume(
+    client: Mt5TradingClient,
+    symbol: str,
+    unit_margin_ratio: float,
+    preserved_margin_ratio: float,
+) -> dict[str, float]:
+    """Calculate tradable margin and volumes from account free margin.
+
+    Applies ``preserved_margin_ratio`` to keep a reserve off ``margin_free``,
+    then allocates ``unit_margin_ratio`` of the remainder as the margin budget
+    for proportional volume sizing on both buy and sell sides. A
+    ``unit_margin_ratio`` of ``0`` requests exactly one minimum valid unit per
+    side when the post-reserve margin can afford it.
+
+    Args:
+        client: Connected ``Mt5TradingClient`` instance.
+        symbol: Symbol used for minimum-lot margin and volume calculations.
+        unit_margin_ratio: Fraction of post-reserve margin to allocate per unit.
+        preserved_margin_ratio: Fraction of ``margin_free`` to preserve.
+
+    Returns:
+        Dictionary with ``margin_free``, ``available_margin``, ``trade_margin``,
+        ``buy_volume``, and ``sell_volume``. Negative ``margin_free`` values are
+        clamped to ``0.0`` before sizing.
+    """
+    _require_unit_ratio(unit_margin_ratio, "unit_margin_ratio")
+    _require_unit_ratio(preserved_margin_ratio, "preserved_margin_ratio")
+
+    account = client.account_info_as_dict()
+    margin_free = max(0.0, float(account.get("margin_free") or 0.0))
+    available_margin = margin_free * (1.0 - preserved_margin_ratio)
+    trade_margin = available_margin * unit_margin_ratio
+    if unit_margin_ratio == 0:
+        buy_volume = _calculate_min_volume_if_affordable(
+            client,
+            symbol,
+            available_margin,
+            "BUY",
+        )
+        sell_volume = _calculate_min_volume_if_affordable(
+            client,
+            symbol,
+            available_margin,
+            "SELL",
+        )
+    else:
+        native_calculate_volume = getattr(client, "calculate_volume_by_margin", None)
+        if callable(native_calculate_volume):
+            buy_volume = float(
+                cast(
+                    "float | int | str",
+                    native_calculate_volume(symbol, trade_margin, "BUY"),
+                ),
+            )
+            sell_volume = float(
+                cast(
+                    "float | int | str",
+                    native_calculate_volume(symbol, trade_margin, "SELL"),
+                ),
+            )
+        else:
+            buy_volume = calculate_volume_by_margin(client, symbol, trade_margin, "BUY")
+            sell_volume = calculate_volume_by_margin(
+                client,
+                symbol,
+                trade_margin,
+                "SELL",
+            )
+    try:
+        symbol_info = get_symbol_snapshot(client, symbol)
+        volume_min = float(symbol_info.get("volume_min") or 0.0)
+        volume_max = float(symbol_info.get("volume_max") or 0.0)
+        volume_step = float(symbol_info.get("volume_step") or 0.0)
+    except AttributeError:
+        volume_min = volume_max = volume_step = 0.0
+    return {
+        "margin_free": margin_free,
+        "available_margin": available_margin,
+        "trade_margin": trade_margin,
+        "buy_volume": float(buy_volume),
+        "sell_volume": float(sell_volume),
+        "volume_min": volume_min,
+        "volume_max": volume_max,
+        "volume_step": volume_step,
+    }
+
+
+def calculate_volume_by_margin(
+    client: Mt5TradingClient,
+    symbol: str,
+    available_margin: float,
+    order_side: OrderSide,
+) -> float:
+    """Calculate max normalized volume affordable for one side.
+
+    Returns:
+        Affordable volume rounded down to symbol volume constraints.
+
+    Raises:
+        Mt5TradingError: If symbol volume constraints or tick data are invalid.
+    """
+    if available_margin <= 0:
+        return 0.0
+    symbol_info = get_symbol_snapshot(client, symbol)
+    volume_min = float(symbol_info.get("volume_min") or 0.0)
+    volume_max = float(symbol_info.get("volume_max") or 0.0)
+    volume_step = float(symbol_info.get("volume_step") or volume_min or 0.0)
+    if volume_min <= 0 or volume_step <= 0:
+        msg = f"Invalid volume constraints for {symbol!r}."
+        raise Mt5TradingError(msg)
+    side = _normalize_order_side(order_side)
+    tick = get_tick_snapshot(client, symbol)
+    price = tick["ask"] if side == "BUY" else tick["bid"]
+    if not isinstance(price, int | float) or price <= 0:
+        msg = f"Tick price is unavailable for {symbol!r}."
+        raise Mt5TradingError(msg)
+    order_type = (
+        client.mt5.ORDER_TYPE_BUY if side == "BUY" else client.mt5.ORDER_TYPE_SELL
+    )
+    min_margin = float(client.order_calc_margin(order_type, symbol, volume_min, price))
+    if min_margin <= 0 or min_margin > available_margin:
+        return 0.0
+    raw_volume = available_margin / min_margin * volume_min
+    capped = min(raw_volume, volume_max) if volume_max > 0 else raw_volume
+    steps = floor(((capped - volume_min) / volume_step) + 1e-12)
+    normalized = volume_min + max(0, steps) * volume_step
+    return round(normalized, 10) if normalized >= volume_min else 0.0
+
+
+def determine_order_limits(
+    client: Mt5TradingClient,
+    symbol: str,
+    side: PositionSide | str,
+    stop_loss_limit_ratio: float | None = None,
+    take_profit_limit_ratio: float | None = None,
+) -> dict[str, float | None]:
+    """Derive entry and protective order prices from current market quotes.
+
+    Args:
+        client: Connected ``Mt5TradingClient`` instance.
+        symbol: Symbol used for the quote lookup.
+        side: Position side as ``"long"``/``"short"`` (``"buy"``/``"sell"``
+            aliases are accepted).
+        stop_loss_limit_ratio: Relative distance from entry for stop loss in
+            ``[0, 1)``. A value of ``0`` omits the stop loss.
+        take_profit_limit_ratio: Relative distance from entry for take profit in
+            ``[0, 1)``. A value of ``0`` omits the take profit.
+
+    Returns:
+        Dictionary with ``entry``, ``stop_loss``, and ``take_profit`` keys.
+        Omitted protective levels are returned as ``None``.
+
+    Raises:
+        Mt5TradingError: If required tick data is invalid.
+    """
+    stop_loss_ratio = stop_loss_limit_ratio or 0.0
+    take_profit_ratio = take_profit_limit_ratio or 0.0
+    _require_protective_ratio(stop_loss_ratio, "stop_loss_limit_ratio")
+    _require_protective_ratio(take_profit_ratio, "take_profit_limit_ratio")
+    normalized_side = _position_side_from_order_side(side)
+    tick = get_tick_snapshot(client, symbol)
+    entry_value = tick["ask"] if normalized_side == "long" else tick["bid"]
+    if not isinstance(entry_value, int | float):
+        msg = f"Tick price is unavailable for {symbol!r}."
+        raise Mt5TradingError(msg)
+    entry = float(entry_value)
+    try:
+        digits = int(get_symbol_snapshot(client, symbol).get("digits") or 8)
+    except AttributeError:
+        digits = 8
+
+    stop_loss: float | None = None
+    if stop_loss_ratio > 0:
+        if normalized_side == "long":
+            stop_loss = entry * (1.0 - stop_loss_ratio)
+        else:
+            stop_loss = entry * (1.0 + stop_loss_ratio)
+        stop_loss = round(stop_loss, digits)
+
+    take_profit: float | None = None
+    if take_profit_ratio > 0:
+        if normalized_side == "long":
+            take_profit = entry * (1.0 + take_profit_ratio)
+        else:
+            take_profit = entry * (1.0 - take_profit_ratio)
+        take_profit = round(take_profit, digits)
+
+    return {
+        "entry": entry,
+        "stop_loss": stop_loss,
+        "take_profit": take_profit,
+    }
+
+
+def place_market_order(
+    client: Mt5TradingClient,
+    *,
+    symbol: str,
+    volume: float,
+    order_side: OrderSide,
+    order_filling_mode: OrderFillingMode = "IOC",
+    order_time_mode: OrderTimeMode = "GTC",
+    sl: float | None = None,
+    tp: float | None = None,
+    position: int | None = None,
+    dry_run: bool = False,
+) -> dict[str, object]:
+    """Place one normalized market order or return a dry-run result.
+
+    ``pdmt5.Mt5TradingClient.order_send()`` raises only when MT5 returns no
+    response. When MT5 returns a response with a known non-success retcode, this
+    helper returns ``status="failed"`` and keeps the normalized response
+    details for callers to inspect.
+
+    Returns:
+        Normalized execution result containing request and response details.
+
+    Raises:
+        Mt5TradingError: If volume or required tick data is invalid.
+    """
+    if volume <= 0:
+        msg = "volume must be positive."
+        raise Mt5TradingError(msg)
+    side = _normalize_order_side(order_side)
+    tick = get_tick_snapshot(client, symbol)
+    price = tick["ask"] if side == "BUY" else tick["bid"]
+    if not isinstance(price, int | float) or price <= 0:
+        msg = f"Tick price is unavailable for {symbol!r}."
+        raise Mt5TradingError(msg)
+    request = {
+        "action": client.mt5.TRADE_ACTION_DEAL,
+        "symbol": symbol,
+        "volume": volume,
+        "type": (
+            client.mt5.ORDER_TYPE_BUY if side == "BUY" else client.mt5.ORDER_TYPE_SELL
+        ),
+        "price": float(price),
+        "type_filling": _resolve_mt5_constant(
+            client.mt5,
+            "ORDER_FILLING",
+            order_filling_mode,
+            _ORDER_FILLING_MODES,
+        ),
+        "type_time": _resolve_mt5_constant(
+            client.mt5,
+            "ORDER_TIME",
+            order_time_mode,
+            _ORDER_TIME_MODES,
+        ),
+    }
+    if sl is not None:
+        request["sl"] = sl
+    if tp is not None:
+        request["tp"] = tp
+    if position is not None:
+        request["position"] = position
+    if dry_run:
+        return {
+            "status": "dry_run",
+            "symbol": symbol,
+            "order_side": side,
+            "volume": volume,
+            "retcode": None,
+            "comment": None,
+            "request": request,
+            "response": None,
+            "dry_run": True,
+        }
+    response = client.order_send(request)
+    response_dict = _snapshot_from_value(response, ())
+    retcode = response_dict.get("retcode")
+    return {
+        "status": _order_status_from_retcode(client.mt5, retcode),
+        "symbol": symbol,
+        "order_side": side,
+        "volume": volume,
+        "retcode": retcode,
+        "comment": response_dict.get("comment"),
+        "request": request,
+        "response": response_dict,
+        "dry_run": False,
+    }
+
+
+def _filter_positions(
+    positions: pd.DataFrame,
+    *,
+    symbols: str | list[str] | None = None,
+    tickets: list[int] | None = None,
+) -> pd.DataFrame:
+    frame = positions
+    if symbols is not None:
+        symbol_set = {symbols} if isinstance(symbols, str) else set(symbols)
+        frame = frame.loc[frame["symbol"].isin(symbol_set)]
+    if tickets is not None:
+        frame = frame.loc[frame["ticket"].isin(tickets)]
+    return frame
+
+
+def close_open_positions(
+    client: Mt5TradingClient,
+    *,
+    symbols: str | list[str] | None = None,
+    tickets: list[int] | None = None,
+    dry_run: bool = False,
+) -> list[dict[str, object]]:
+    """Close matching open positions.
+
+    Returns:
+        Normalized execution results for matching positions.
+    """
+    positions = _filter_positions(
+        get_positions_frame(client),
+        symbols=symbols,
+        tickets=tickets,
+    )
+    results: list[dict[str, object]] = []
+    for row in positions.to_dict("records"):
+        pos_type = row["type"]
+        side: OrderSide = "SELL" if pos_type == client.mt5.POSITION_TYPE_BUY else "BUY"
+        result = place_market_order(
+            client,
+            symbol=str(row["symbol"]),
+            volume=float(row["volume"]),
+            order_side=side,
+            position=int(row["ticket"]),
+            dry_run=dry_run,
+        )
+        results.append(result)
+    return results
+
+
+def update_sltp_for_open_positions(
+    client: Mt5TradingClient,
+    *,
+    symbol: str | None = None,
+    tickets: list[int] | None = None,
+    stop_loss: float | None = None,
+    take_profit: float | None = None,
+    dry_run: bool = False,
+) -> list[dict[str, object]]:
+    """Update SL/TP for matching open positions.
+
+    Returns:
+        Normalized execution results for matching positions.
+    """
+    positions = _filter_positions(
+        get_positions_frame(client),
+        symbols=symbol,
+        tickets=tickets,
+    )
+    results: list[dict[str, object]] = []
+    for row in positions.to_dict("records"):
+        request = {
+            "action": client.mt5.TRADE_ACTION_SLTP,
+            "symbol": row["symbol"],
+            "position": row["ticket"],
+        }
+        sl = _optional_price(row.get("sl") if stop_loss is None else stop_loss)
+        tp = _optional_price(row.get("tp") if take_profit is None else take_profit)
+        if sl is not None:
+            request["sl"] = sl
+        if tp is not None:
+            request["tp"] = tp
+        if dry_run:
+            response = None
+            status = "dry_run"
+        else:
+            response = _snapshot_from_value(client.order_send(request), ())
+            status = "executed"
+        results.append(
+            {
+                "status": status,
+                "symbol": row["symbol"],
+                "order_side": "BUY"
+                if row["type"] == client.mt5.POSITION_TYPE_BUY
+                else "SELL",
+                "volume": row["volume"],
+                "retcode": None if response is None else response.get("retcode"),
+                "comment": None if response is None else response.get("comment"),
+                "request": request,
+                "response": response,
+                "dry_run": dry_run,
+            },
+        )
+    return results
+
+
+@contextmanager
+def mt5_trading_session(
+    config: Mt5Config | None = None,
+    *,
+    login: int | str | None = None,
+    password: str | None = None,
+    server: str | None = None,
+    path: str | None = None,
+    timeout: int | None = None,
+    retry_count: int = 0,
+) -> Iterator[Mt5TradingClient]:
+    """Open a trading-capable MT5 session and always shut down safely.
+
+    Launches the MetaTrader 5 terminal using ``Mt5Config.path`` when set,
+    initializes and logs in via ``initialize_and_login_mt5()``, yields a
+    connected :class:`~pdmt5.Mt5TradingClient`, and calls ``shutdown()`` on
+    exit even when an error is raised inside the context.
+
+    Args:
+        config: MT5 connection configuration. Defaults to an empty config that
+            attaches to a running terminal.
+        login: Optional trading account login.
+        password: Optional trading account password.
+        server: Optional trading server name.
+        path: Optional terminal executable path.
+        timeout: Optional connection timeout in milliseconds.
+        retry_count: Number of initialization retries passed to
+            ``Mt5TradingClient``.
+
+    Yields:
+        Connected ``Mt5TradingClient`` bound to the session.
+    """
+    client = create_trading_client(
+        config=config,
+        login=login,
+        password=password,
+        server=server,
+        path=path,
+        timeout=timeout,
+        retry_count=retry_count,
+    )
+    try:
+        yield client
+    finally:
+        client.shutdown()

mt5cli/utils.py

@@ -0,0 +1,448 @@
+"""Utility constants, types, and functions for the mt5cli package."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, TypeGuard
+
+import click
+from pdmt5 import COPY_TICKS_MAP, TIMEFRAME_MAP
+from pdmt5 import parse_copy_ticks as _parse_copy_ticks
+from pdmt5 import parse_timeframe as _parse_timeframe
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    import pandas as pd
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# Backward-compatible snapshot; prefer ``COPY_TICKS_MAP`` from pdmt5 directly.
+TICK_FLAG_MAP: dict[str, int] = dict(COPY_TICKS_MAP)
+
+TIMEFRAME_NAMES: tuple[str, ...] = tuple(
+    name for name in TIMEFRAME_MAP if not name.startswith("TIMEFRAME_")
+)
+_TICK_FLAG_NAMES: tuple[str, ...] = tuple(
+    name for name in COPY_TICKS_MAP if not name.startswith("COPY_TICKS_")
+)
+
+_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.
+        """
+        try:
+            return parse_timeframe(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.
+        """
+        try:
+            return parse_tick_flags(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 coerce_login(login: int | str | None) -> int | None:
+    """Coerce a login value to int, treating empty strings as unset.
+
+    Returns:
+        Integer login, or None when unset or an empty string.
+    """
+    if login is None or isinstance(login, int):
+        return login
+    text = login.strip()
+    if not text:
+        return None
+    return int(text)
+
+
+def export_dataframe_to_sqlite(
+    df: pd.DataFrame,
+    output_path: Path,
+    table_name: str = "data",
+    *,
+    if_exists: IfExists = IfExists.APPEND,
+    index: bool = False,
+    index_label: str | None = None,
+    deduplicate_on: Sequence[str] | None = None,
+) -> None:
+    """Write a DataFrame to SQLite with configurable append and deduplication.
+
+    Args:
+        df: DataFrame to export.
+        output_path: SQLite database path.
+        table_name: Target table name.
+        if_exists: Conflict behavior when the table already exists.
+        index: Whether to write the DataFrame index as a column.
+        index_label: Column name for the index when ``index=True``.
+        deduplicate_on: Optional key columns to deduplicate after writing,
+            keeping the latest ``ROWID`` per key group. Deduplication scans the
+            full table, so repeated appends cost O(table size); index the key
+            columns when appending frequently.
+    """
+    with sqlite3.connect(output_path) as conn:
+        df.to_sql(  # type: ignore[reportUnknownMemberType]
+            table_name,
+            conn,
+            if_exists=if_exists.value,
+            index=index,
+            index_label=index_label,
+        )
+        if deduplicate_on:
+            from .history import drop_duplicates_in_table  # noqa: PLC0415
+
+            drop_duplicates_in_table(
+                conn.cursor(),
+                table_name,
+                list(deduplicate_on),
+                keep="last",
+            )
+            conn.commit()
+
+
+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":
+        export_dataframe_to_sqlite(
+            df,
+            output_path,
+            table_name,
+            if_exists=IfExists.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: object) -> 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.
+    """
+    try:
+        return _parse_timeframe(value)
+    except ValueError:
+        display = value if isinstance(value, str) else repr(value)
+        valid = ", ".join(TIMEFRAME_NAMES)
+        msg = (
+            f"Invalid timeframe: '{display}'. "
+            f"Use one of: {valid}, or a supported integer."
+        )
+        raise ValueError(msg) from None
+
+
+def parse_tick_flags(value: object) -> int:
+    """Parse tick flags string or integer value.
+
+    Args:
+        value: Tick flag name (ALL, INFO, TRADE, COPY_TICKS_*) or integer value.
+
+    Returns:
+        Integer tick flag value compatible with MetaTrader 5 ``COPY_TICKS_*``.
+
+    Raises:
+        ValueError: If the flag is invalid.
+    """
+    try:
+        return _parse_copy_ticks(value)
+    except ValueError:
+        display = value if isinstance(value, str) else repr(value)
+        valid = ", ".join(_TICK_FLAG_NAMES)
+        msg = (
+            f"Invalid tick flags: '{display}'. "
+            f"Use one of: {valid}, or a supported 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

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "mt5cli"
-version = "0.3.0"
-description = "Command-line tool for MetaTrader 5"
+version = "0.8.0"
+description = "Generic MT5 data and execution infrastructure for Python applications"
 authors = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
 maintainers = [{name = "dceoy", email = "dceoy@users.noreply.github.com"}]
 license = "MIT"
@@ -9,7 +9,7 @@ license-files = ["LICENSE"]
 readme = "README.md"
 requires-python = ">= 3.11, < 3.14"
 dependencies = [
-  "pdmt5 >= 0.2.3",
+  "pdmt5>=0.3.0",
   "click >= 8.1.0",
   "pyarrow >= 19.0.0",
   "typer >= 0.15.0",
@@ -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

tests/conftest.py

@@ -0,0 +1,52 @@
+"""Shared pytest fixtures for mt5cli tests."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pandas as pd
+import pytest
+from pytest_mock import MockerFixture  # noqa: TC002
+
+_DATAFRAME_METHODS = (
+    "copy_rates_from_as_df",
+    "copy_rates_from_pos_as_df",
+    "copy_rates_range_as_df",
+    "copy_ticks_from_as_df",
+    "copy_ticks_range_as_df",
+    "account_info_as_df",
+    "terminal_info_as_df",
+    "symbols_get_as_df",
+    "symbol_info_as_df",
+    "orders_get_as_df",
+    "positions_get_as_df",
+    "history_orders_get_as_df",
+    "history_deals_get_as_df",
+    "version_as_df",
+    "last_error_as_df",
+    "symbol_info_tick_as_df",
+    "market_book_get_as_df",
+    "order_check_as_df",
+    "order_send_as_df",
+)
+
+
+def build_mock_mt5_data_client() -> MagicMock:
+    """Return a MagicMock Mt5DataClient with common DataFrame stubs."""
+    client = MagicMock()
+    sample_df = pd.DataFrame({"col": [1]})
+    for method_name in _DATAFRAME_METHODS:
+        getattr(client, method_name).return_value = sample_df
+    client.version.return_value = (5, 0, 1)
+    client.terminal_info.return_value = {"connected": True, "paths": ["terminal.exe"]}
+    client.account_info.return_value = {"login": 123, "limits": {"modes": ["demo"]}}
+    client.symbols_total.return_value = 42
+    return client
+
+
+@pytest.fixture
+def mock_client(mocker: MockerFixture) -> MagicMock:
+    """Create and patch a mock Mt5DataClient for CLI and SDK tests."""
+    client = build_mock_mt5_data_client()
+    mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=client)
+    return client

tests/test_cli.py

@@ -6,7 +6,7 @@ import json
 import logging
 import re
 import sqlite3
-from datetime import UTC, datetime
+from datetime import UTC, datetime, timedelta
 from typing import TYPE_CHECKING
 from unittest.mock import MagicMock
 
@@ -19,22 +19,11 @@ if TYPE_CHECKING:
     from pathlib import Path
 
 from mt5cli.cli import (
-    DATETIME_TYPE,
-    REQUEST_TYPE,
-    TICK_FLAG_MAP,
-    TICK_FLAGS_TYPE,
-    TIMEFRAME_MAP,
-    TIMEFRAME_TYPE,
     _execute_export,  # type: ignore[reportPrivateUsage]
     _ExportContext,  # type: ignore[reportPrivateUsage]
+    _sdk_client,  # type: ignore[reportPrivateUsage]
     app,
-    detect_format,
-    export_dataframe,
     main,
-    parse_datetime,
-    parse_request,
-    parse_tick_flags,
-    parse_timeframe,
 )
 
 runner = CliRunner()
@@ -46,299 +35,6 @@ def normalize_cli_output(output: str) -> str:
     return " ".join(_ANSI_ESCAPE_RE.sub("", output).split())
 
 
-# ---------------------------------------------------------------------------
-# 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"}
-
-
-# ---------------------------------------------------------------------------
-# 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)
-
-
 # ---------------------------------------------------------------------------
 # _execute_export
 # ---------------------------------------------------------------------------
@@ -355,7 +51,7 @@ class TestExecuteExport:
         """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.cli.Mt5DataClient", return_value=mock_client)
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=mock_client)
         ctx = MagicMock()
         ctx.obj = _ExportContext(
             output=tmp_path / "out.csv",
@@ -364,7 +60,7 @@ class TestExecuteExport:
             config=MagicMock(),
         )
         with pytest.raises(RuntimeError, match="boom"):
-            _execute_export(ctx, lambda c: c.account_info_as_df())
+            _execute_export(ctx, _sdk_client(ctx).account_info)
         mock_client.shutdown.assert_called_once()
 
 
@@ -373,34 +69,6 @@ class TestExecuteExport:
 # ---------------------------------------------------------------------------
 
 
-@pytest.fixture
-def mock_client(mocker: MockerFixture) -> MagicMock:
-    """Create and patch a mock Mt5DataClient for CLI 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
-    client.order_check_as_df.return_value = sample_df
-    client.order_send_as_df.return_value = sample_df
-    mocker.patch("mt5cli.cli.Mt5DataClient", return_value=client)
-    return client
-
-
 class TestCommands:
     """Tests for all CLI subcommands via CliRunner."""
 
@@ -527,6 +195,37 @@ class TestCommands:
             count=50,
         )
 
+    def test_latest_rates(
+        self,
+        tmp_path: Path,
+        mock_client: MagicMock,
+    ) -> None:
+        """Test latest-rates command."""
+        output = tmp_path / "out.csv"
+        result = runner.invoke(
+            app,
+            [
+                "-o",
+                str(output),
+                "latest-rates",
+                "--symbol",
+                "GBPUSD",
+                "--timeframe",
+                "H1",
+                "--count",
+                "50",
+                "--start-pos",
+                "2",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        mock_client.copy_rates_from_pos_as_df.assert_called_once_with(
+            symbol="GBPUSD",
+            timeframe=16385,
+            start_pos=2,
+            count=50,
+        )
+
     def test_rates_range(
         self,
         tmp_path: Path,
@@ -586,7 +285,7 @@ class TestCommands:
             symbol="EURUSD",
             date_from=datetime(2024, 1, 1, tzinfo=UTC),
             count=100,
-            flags=1,
+            flags=-1,
         )
 
     def test_ticks_range(
@@ -617,9 +316,68 @@ class TestCommands:
             symbol="EURUSD",
             date_from=datetime(2024, 1, 1, tzinfo=UTC),
             date_to=datetime(2024, 2, 1, tzinfo=UTC),
-            flags=2,
+            flags=1,
         )
 
+    def test_ticks_recent(
+        self,
+        tmp_path: Path,
+        mock_client: MagicMock,
+    ) -> None:
+        """Test ticks-recent command."""
+        output = tmp_path / "out.csv"
+        result = runner.invoke(
+            app,
+            [
+                "-o",
+                str(output),
+                "ticks-recent",
+                "--symbol",
+                "EURUSD",
+                "--seconds",
+                "120",
+                "--date-to",
+                "2024-01-02",
+                "--count",
+                "500",
+                "--flags",
+                "ALL",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        mock_client.copy_ticks_from_as_df.assert_called_once_with(
+            symbol="EURUSD",
+            date_from=datetime(2024, 1, 2, tzinfo=UTC) - timedelta(seconds=120),
+            count=500,
+            flags=-1,
+        )
+        mock_client.copy_ticks_range_as_df.assert_not_called()
+
+    def test_minimum_margins(
+        self,
+        tmp_path: Path,
+        mock_client: MagicMock,
+    ) -> None:
+        """Test minimum-margins command."""
+        sym = MagicMock(volume_min=0.01)
+        account = MagicMock(currency="USD")
+        tick = MagicMock(ask=1.1010, bid=1.1000)
+        mock_client.symbol_info.return_value = sym
+        mock_client.account_info.return_value = account
+        mock_client.symbol_info_tick.return_value = tick
+        mock_client.order_calc_margin.side_effect = [12.5, 12.4]
+        mock_client.mt5.ORDER_TYPE_BUY = 0
+        mock_client.mt5.ORDER_TYPE_SELL = 1
+        output = tmp_path / "out.csv"
+        result = runner.invoke(
+            app,
+            ["-o", str(output), "minimum-margins", "--symbol", "EURUSD"],
+        )
+        assert result.exit_code == 0, result.output
+        mock_client.symbol_info.assert_called_once_with("EURUSD")
+        mock_client.order_calc_margin.assert_any_call(0, "EURUSD", 0.01, 1.1010)
+        mock_client.order_calc_margin.assert_any_call(1, "EURUSD", 0.01, 1.1000)
+
     def test_orders(
         self,
         tmp_path: Path,
@@ -696,6 +454,84 @@ class TestCommands:
         assert result.exit_code == 0, result.output
         mock_client.history_deals_get_as_df.assert_called_once()
 
+    def test_recent_history_deals(
+        self,
+        tmp_path: Path,
+        mock_client: MagicMock,
+    ) -> None:
+        """Test recent-history-deals command."""
+        output = tmp_path / "out.csv"
+        result = runner.invoke(
+            app,
+            [
+                "-o",
+                str(output),
+                "recent-history-deals",
+                "--hours",
+                "6",
+                "--date-to",
+                "2024-01-02",
+                "--symbol",
+                "EURUSD",
+            ],
+        )
+        assert result.exit_code == 0, result.output
+        mock_client.history_deals_get_as_df.assert_called_once_with(
+            date_from=datetime(2024, 1, 1, 18, tzinfo=UTC),
+            date_to=datetime(2024, 1, 2, tzinfo=UTC),
+            group=None,
+            symbol="EURUSD",
+            ticket=None,
+            position=None,
+        )
+
+    @pytest.mark.parametrize(
+        ("filename", "reader"),
+        [
+            ("summary.csv", "csv"),
+            ("summary.json", "json"),
+            ("summary.db", "sqlite3"),
+            ("summary.parquet", "parquet"),
+        ],
+    )
+    def test_mt5_summary_export_formats(
+        self,
+        tmp_path: Path,
+        mock_client: MagicMock,
+        filename: str,
+        reader: str,
+    ) -> None:
+        """Test mt5-summary writes export-safe files for supported formats."""
+        output = tmp_path / filename
+        result = runner.invoke(app, ["-o", str(output), "mt5-summary"])
+        assert result.exit_code == 0, result.output
+        assert output.exists()
+        mock_client.version.assert_called_once()
+        mock_client.terminal_info.assert_called_once()
+        mock_client.account_info.assert_called_once()
+        mock_client.symbols_total.assert_called_once()
+        if reader == "csv":
+            frame = pd.read_csv(output)
+        elif reader == "json":
+            with output.open() as f:
+                records = json.load(f)
+            frame = pd.DataFrame(records)
+        elif reader == "sqlite3":
+            with sqlite3.connect(output) as conn:
+                frame = pd.read_sql(  # type: ignore[reportUnknownMemberType]
+                    "SELECT * FROM data",
+                    conn,
+                )
+        else:
+            frame = pd.read_parquet(output)
+        assert len(frame) == 1
+        assert frame.iloc[0].to_dict() == {
+            "version": "[5,0,1]",
+            "terminal_info": '{"connected":true,"paths":["terminal.exe"]}',
+            "account_info": '{"limits":{"modes":["demo"]},"login":123}',
+            "symbols_total": 42,
+        }
+
     def test_version(
         self,
         tmp_path: Path,
@@ -931,7 +767,7 @@ class TestCallback:
         mock_client = MagicMock()
         mock_client.account_info_as_df.return_value = pd.DataFrame({"a": [1]})
         mocker.patch(
-            "mt5cli.cli.Mt5DataClient",
+            "mt5cli.sdk.Mt5DataClient",
             return_value=mock_client,
         )
         mock_config = mocker.patch("mt5cli.cli.Mt5Config")
@@ -984,7 +820,7 @@ class TestCallback:
             {"s": ["EURUSD"]},
         )
         mocker.patch(
-            "mt5cli.cli.Mt5DataClient",
+            "mt5cli.sdk.Mt5DataClient",
             return_value=mock_client,
         )
         output = tmp_path / "out.db"
@@ -1090,7 +926,7 @@ def _build_history_client(mocker: MockerFixture) -> MagicMock:
 
     client.history_orders_get_as_df.side_effect = _orders
     client.history_deals_get_as_df.side_effect = _deals
-    mocker.patch("mt5cli.cli.Mt5DataClient", return_value=client)
+    mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=client)
     return client
 
 
@@ -1132,7 +968,7 @@ class TestCollectHistory:
             symbol="EURUSD",
             date_from=datetime(2024, 1, 1, tzinfo=UTC),
             date_to=datetime(2024, 2, 1, tzinfo=UTC),
-            flags=1,
+            flags=-1,
         )
         with sqlite3.connect(output) as conn:
             tables = {
@@ -1345,7 +1181,7 @@ class TestCollectHistory:
             symbol="EURUSD",
             date_from=datetime(2024, 1, 1, tzinfo=UTC),
             date_to=datetime(2024, 2, 1, tzinfo=UTC),
-            flags=1,
+            flags=-1,
         )
 
     def test_collect_history_with_views(
@@ -1393,7 +1229,7 @@ class TestCollectHistory:
         assert all(row[0] not in {0, 1} for row in cash)
         # Position 100 (BUY 1@1.10 + BUY 3@1.20 then SELL 4@1.50) is closed.
         # Position 200 (BUY 2@2.00 then SELL 2@2.20) is closed.
-        # Position 300 (open-only) and 400 (reversal-only) are excluded.
+        # Position 400 (reversal-only with non-trade deal type) stays excluded.
         assert set(positions) == {100, 200, 500, 600}
         pos_100 = positions[100]
         tol = 1e-9
@@ -1410,10 +1246,10 @@ class TestCollectHistory:
         assert abs(pos_500[5] - 1.05) < tol
         pos_600 = positions[600]
         assert abs(pos_600[1] - 3.0) < tol
-        assert abs(pos_600[2] - 3.0) < tol
+        assert abs(pos_600[2] - 4.0) < tol  # reversal + close volumes
         assert abs(pos_600[3] - 1.0) < tol
         assert abs(pos_600[4] - 1.10) < tol
-        assert abs(pos_600[5] - 1.40) < tol
+        assert abs(pos_600[5] - 3.5475) < tol
         assert pos_600[6] == 1
 
     def test_collect_history_filters_history_symbols_exactly(
@@ -1431,7 +1267,7 @@ class TestCollectHistory:
             "ticket": [3, 4],
             "symbol": ["EURUSD", "EURUSDm"],
         })
-        mocker.patch("mt5cli.cli.Mt5DataClient", return_value=client)
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=client)
         output = tmp_path / "history.db"
         result = runner.invoke(
             app,
@@ -1519,9 +1355,9 @@ class TestCollectHistory:
         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.cli.Mt5DataClient", return_value=client)
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=client)
         output = tmp_path / "history.db"
-        with caplog.at_level(logging.WARNING, logger="mt5cli.cli"):
+        with caplog.at_level(logging.WARNING, logger="mt5cli.sdk"):
             result = runner.invoke(
                 app,
                 [
@@ -1559,7 +1395,7 @@ class TestCollectHistory:
         client = MagicMock()
         client.copy_rates_range_as_df.return_value = pd.DataFrame({"time": [1]})
         client.history_deals_get_as_df.return_value = pd.DataFrame()
-        mocker.patch("mt5cli.cli.Mt5DataClient", return_value=client)
+        mocker.patch("mt5cli.sdk.Mt5DataClient", return_value=client)
         output = tmp_path / "history.db"
         result = runner.invoke(
             app,
@@ -1598,7 +1434,7 @@ class TestCollectHistory:
     ) -> None:
         """Test that --with-views warns when history_deals is not written."""
         output = tmp_path / "history.db"
-        with caplog.at_level(logging.WARNING, logger="mt5cli.cli"):
+        with caplog.at_level(logging.WARNING, logger="mt5cli.sdk"):
             result = runner.invoke(
                 app,
                 [

tests/test_contracts.py

@@ -0,0 +1,512 @@
+"""Contract tests for the mt5cli public API and dataset schemas."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+import pandas as pd
+import pytest
+from pdmt5 import Mt5RuntimeError, Mt5TradingError
+from pytest_mock import MockerFixture  # noqa: TC002
+
+from mt5cli import (
+    DEDUP_KEYS,
+    REQUIRED_COLUMNS,
+    TIME_COLUMNS,
+    DataKind,
+    Dataset,
+    MT5Client,
+    Mt5CliError,
+    Mt5ConnectionError,
+    Mt5OperationError,
+    Mt5SchemaError,
+    build_config,
+    call_with_normalized_errors,
+    detect_format,
+    ensure_utc,
+    export_dataframe,
+    export_dataframe_to_sqlite,
+    granularity_name,
+    is_recoverable_mt5_error,
+    mt5_session,
+    normalize_dataframe,
+    normalize_mt5_exception,
+    normalize_symbol,
+    normalize_symbols,
+    parse_date_range,
+    recent_window,
+    schema_columns,
+    validate_schema,
+)
+from mt5cli.retry import retry_with_backoff
+from mt5cli.schemas import ensure_utc_columns, normalize_time_columns
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def _sample_frame(kind: DataKind) -> pd.DataFrame:
+    if kind is DataKind.rates:
+        return pd.DataFrame({
+            "time": [datetime(2024, 1, 1, tzinfo=UTC)],
+            "open": [1.1],
+            "high": [1.2],
+            "low": [1.0],
+            "close": [1.15],
+            "tick_volume": [10],
+            "spread": [1],
+            "real_volume": [0],
+        })
+    if kind is DataKind.ticks:
+        return pd.DataFrame({
+            "time": [datetime(2024, 1, 1, tzinfo=UTC)],
+            "bid": [1.1],
+            "ask": [1.11],
+            "last": [1.105],
+            "volume": [1],
+            "time_msc": [datetime(2024, 1, 1, tzinfo=UTC)],
+            "flags": [2],
+            "volume_real": [0.0],
+        })
+    if kind is DataKind.orders:
+        return pd.DataFrame({
+            "ticket": [1],
+            "time_setup": [datetime(2024, 1, 1, tzinfo=UTC)],
+            "type": [0],
+            "state": [1],
+            "symbol": ["EURUSD"],
+            "volume_current": [0.1],
+            "price_open": [1.1],
+        })
+    if kind is DataKind.positions:
+        return pd.DataFrame({
+            "ticket": [1],
+            "time": [datetime(2024, 1, 1, tzinfo=UTC)],
+            "type": [0],
+            "symbol": ["EURUSD"],
+            "volume": [0.1],
+            "price_open": [1.1],
+            "price_current": [1.11],
+            "profit": [1.0],
+        })
+    if kind is DataKind.history_orders:
+        return pd.DataFrame({
+            "ticket": [1],
+            "time_setup": [datetime(2024, 1, 1, tzinfo=UTC)],
+            "type": [0],
+            "state": [3],
+            "symbol": ["EURUSD"],
+            "volume_initial": [0.1],
+            "price_open": [1.1],
+        })
+    return pd.DataFrame({
+        "ticket": [1],
+        "order": [2],
+        "time": [datetime(2024, 1, 1, tzinfo=UTC)],
+        "type": [0],
+        "entry": [0],
+        "symbol": ["EURUSD"],
+        "volume": [0.1],
+        "price": [1.1],
+        "profit": [0.0],
+    })
+
+
+@pytest.mark.parametrize("kind", list(DataKind))
+def test_required_columns_contract(kind: DataKind) -> None:
+    """Each dataset kind exposes a non-empty required column contract."""
+    assert REQUIRED_COLUMNS[kind]
+    validate_schema(_sample_frame(kind), kind)
+
+
+@pytest.mark.parametrize("kind", list(DataKind))
+def test_normalize_dataframe_injects_storage_metadata(kind: DataKind) -> None:
+    """Normalization accepts MT5 frames and optional storage metadata."""
+    frame = _sample_frame(kind)
+    normalized = normalize_dataframe(
+        frame,
+        kind,
+        symbol="eurusd",
+        timeframe="M1" if kind is DataKind.rates else None,
+    )
+    if kind is DataKind.rates:
+        assert normalized.loc[0, "symbol"] == "eurusd"
+        assert normalized.loc[0, "timeframe"] == 1
+    validate_schema(normalized, kind)
+
+
+def test_validate_schema_raises_for_missing_columns() -> None:
+    """Schema validation fails fast on missing required columns."""
+    with pytest.raises(Mt5SchemaError, match="missing required columns"):
+        validate_schema(pd.DataFrame({"time": [1]}), DataKind.rates)
+
+
+def test_history_dedup_keys_match_schema_contract() -> None:
+    """SQLite history dedup keys stay aligned with schema contracts."""
+    assert DEDUP_KEYS[DataKind.rates][0] == ("symbol", "timeframe", "time")
+    assert DEDUP_KEYS[DataKind.ticks][0] == ("symbol", "time_msc")
+    assert Dataset.rates.table_name == "rates"
+
+
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [
+        (" eurusd ", "eurusd"),
+        ("GbpJpy", "GbpJpy"),
+        ("XAUUSDm", "XAUUSDm"),
+        ("US500.cash", "US500.cash"),
+        ("EURUSD.r", "EURUSD.r"),
+    ],
+)
+def test_normalize_symbol(raw: str, expected: str) -> None:
+    """Symbol normalization trims whitespace and preserves broker casing."""
+    assert normalize_symbol(raw) == expected
+
+
+def test_normalize_symbols_deduplicates() -> None:
+    """Symbol lists are normalized and de-duplicated in order."""
+    assert normalize_symbols(["XAUUSDm", " XAUUSDm ", "EURUSD.r", "eurusd"]) == [
+        "XAUUSDm",
+        "EURUSD.r",
+        "eurusd",
+    ]
+
+
+def test_parse_date_range_rejects_inverted_bounds() -> None:
+    """Date ranges must not be inverted."""
+    with pytest.raises(ValueError, match="must not be after"):
+        parse_date_range("2024-02-01", "2024-01-01")
+
+
+def test_recent_window_builds_trailing_bounds() -> None:
+    """Recent windows end at the provided timestamp."""
+    end = datetime(2024, 1, 2, tzinfo=UTC)
+    start, resolved_end = recent_window(hours=24, date_to=end)
+    assert resolved_end == end
+    assert start < end
+
+
+def test_granularity_name_maps_timeframe_alias() -> None:
+    """Granularity labels resolve MT5 timeframe aliases."""
+    assert granularity_name("M1") == "M1"
+
+
+@pytest.mark.parametrize(
+    "exc",
+    [Mt5RuntimeError("init failed"), Mt5TradingError("trade failed")],
+)
+def test_is_recoverable_mt5_error(exc: Exception) -> None:
+    """Recoverable MT5 errors are classified consistently."""
+    assert is_recoverable_mt5_error(exc)
+
+
+def test_normalize_mt5_exception_maps_types() -> None:
+    """MT5 exceptions map to stable mt5cli types."""
+    assert isinstance(
+        normalize_mt5_exception(Mt5RuntimeError("x")),
+        Mt5ConnectionError,
+    )
+    assert isinstance(
+        normalize_mt5_exception(Mt5TradingError("x")),
+        Mt5OperationError,
+    )
+
+
+def test_call_with_normalized_errors_reraises_mapped_type() -> None:
+    """Normalized error helper re-raises mapped mt5cli exceptions."""
+
+    def _raise() -> None:
+        message = "boom"
+        raise Mt5RuntimeError(message)
+
+    with pytest.raises(Mt5ConnectionError):
+        call_with_normalized_errors(_raise)
+
+
+def test_retry_with_backoff_retries_recoverable_errors(
+    mocker: MockerFixture,
+) -> None:
+    """Retry helper retries recoverable MT5 failures."""
+    calls = {"count": 0}
+
+    def _flaky() -> str:
+        calls["count"] += 1
+        if calls["count"] == 1:
+            message = "transient"
+            raise Mt5RuntimeError(message)
+        return "ok"
+
+    mocker.patch("mt5cli.retry.time.sleep")
+    assert retry_with_backoff(_flaky, retry_count=1) == "ok"
+    assert calls["count"] == 2
+
+
+def test_public_api_exports_mt5_client() -> None:
+    """MT5Client is the primary importable client abstraction."""
+    client = MT5Client(config=build_config())
+    assert isinstance(client, MT5Client)
+    assert isinstance(client, MT5Client.__mro__[1])
+
+
+def test_mt5_client_order_primitives_use_connected_client(
+    mock_client: object,
+) -> None:
+    """Order check/send route through the same client fetch path as exports."""
+    request = {"action": 1}
+    client = MT5Client()
+    client.order_check(request)
+    client.order_send(request)
+    assert mock_client.order_check_as_df.call_count == 1  # type: ignore[attr-defined]
+    assert mock_client.order_send_as_df.call_count == 1  # type: ignore[attr-defined]
+
+
+def test_storage_export_round_trip_csv(tmp_path: Path) -> None:
+    """Storage helpers export normalized rate frames to CSV."""
+    frame = normalize_dataframe(
+        _sample_frame(DataKind.rates),
+        DataKind.rates,
+        symbol="EURUSD",
+        timeframe="M1",
+    )
+    output = tmp_path / "rates.csv"
+    export_dataframe(frame, output, detect_format(output))
+    loaded = pd.read_csv(output)
+    assert len(loaded) == 1
+    assert "close" in loaded.columns
+
+
+def test_normalize_symbol_rejects_empty_value() -> None:
+    """Empty symbols are rejected after trimming."""
+    with pytest.raises(ValueError, match="must not be empty"):
+        normalize_symbol("   ")
+
+
+def test_ensure_utc_handles_naive_and_aware_datetimes() -> None:
+    """UTC coercion accepts naive and timezone-aware datetimes."""
+    naive = datetime(2024, 1, 1, tzinfo=UTC).replace(tzinfo=None)
+    aware = datetime(2024, 1, 1, tzinfo=UTC)
+    assert ensure_utc(naive).tzinfo == UTC
+    assert ensure_utc(aware).tzinfo == UTC
+    assert ensure_utc("2024-01-01T00:00:00+00:00").tzinfo == UTC
+
+
+def test_recent_window_validation_errors() -> None:
+    """Recent window helpers validate mutually exclusive length arguments."""
+    with pytest.raises(ValueError, match="exactly one"):
+        recent_window()
+    with pytest.raises(ValueError, match="exactly one"):
+        recent_window(hours=1, seconds=1)
+    with pytest.raises(ValueError, match="positive"):
+        recent_window(hours=0)
+
+
+def test_recent_window_supports_seconds_argument() -> None:
+    """Recent windows can be built from a seconds-based length."""
+    end = datetime(2024, 1, 2, tzinfo=UTC)
+    start, resolved_end = recent_window(seconds=3600, date_to=end)
+    assert resolved_end == end
+    assert start < end
+
+
+def test_parse_date_range_returns_ordered_bounds() -> None:
+    """Valid date ranges return UTC-aware bounds."""
+    start, end = parse_date_range("2024-01-01", "2024-02-01")
+    assert start < end
+
+
+def test_granularity_name_falls_back_for_unknown_timeframe(
+    mocker: MockerFixture,
+) -> None:
+    """Unknown timeframe integers stringify as granularity labels."""
+    mocker.patch(
+        "mt5cli.converters._get_timeframe_name",
+        side_effect=ValueError("unknown"),
+    )
+    assert granularity_name(1) == "1"
+
+
+def test_normalize_mt5_exception_passthrough_and_generic() -> None:
+    """Normalization preserves mt5cli errors and wraps unknown exceptions."""
+    original = Mt5CliError("known")
+    assert normalize_mt5_exception(original) is original
+    assert isinstance(normalize_mt5_exception(ValueError("x")), Mt5CliError)
+
+
+def test_schema_columns_and_extra_required_validation() -> None:
+    """Schema helpers expose contracts and honor extra required columns."""
+    assert schema_columns(DataKind.rates) == REQUIRED_COLUMNS[DataKind.rates]
+    validate_schema(pd.DataFrame(), DataKind.rates)
+    frame = _sample_frame(DataKind.rates)
+    with pytest.raises(Mt5SchemaError, match="storage_symbol"):
+        validate_schema(frame, DataKind.rates, extra_required=["storage_symbol"])
+
+
+def test_normalize_dataframe_empty_and_tick_sort_paths() -> None:
+    """Normalization handles empty frames and tick time_msc sorting."""
+    empty = pd.DataFrame()
+    assert normalize_dataframe(empty, DataKind.rates).empty
+
+    ticks = _sample_frame(DataKind.ticks)
+    ticks = pd.concat([ticks, ticks], ignore_index=True)
+    sorted_ticks = normalize_dataframe(ticks, DataKind.ticks, sort=True)
+    assert len(sorted_ticks) == 2
+    unsorted_ticks = normalize_dataframe(ticks, DataKind.ticks, sort=False)
+    assert len(unsorted_ticks) == 2
+
+
+def test_normalize_dataframe_rate_timeframe_without_symbol() -> None:
+    """Rate normalization can inject timeframe without symbol metadata."""
+    frame = _sample_frame(DataKind.rates)
+    normalized = normalize_dataframe(frame, DataKind.rates, timeframe="M1")
+    assert "timeframe" in normalized.columns
+
+
+def test_normalize_dataframe_keeps_existing_symbol_and_timeframe() -> None:
+    """Normalization does not duplicate existing storage metadata columns."""
+    frame = normalize_dataframe(
+        _sample_frame(DataKind.rates),
+        DataKind.rates,
+        symbol="EURUSD",
+        timeframe="M1",
+    )
+    normalized = normalize_dataframe(
+        frame,
+        DataKind.rates,
+        symbol="GBPUSD",
+        timeframe="H1",
+    )
+    assert normalized.loc[0, "symbol"] == "EURUSD"
+    assert normalized.loc[0, "timeframe"] == 1
+
+
+def test_normalize_time_columns_skips_absent_time_fields() -> None:
+    """Time normalization ignores absent optional time columns."""
+    frame = pd.DataFrame({"open": [1.0]})
+    result = normalize_time_columns(frame, DataKind.rates)
+    assert list(result.columns) == ["open"]
+
+
+def test_normalize_time_columns_converts_unix_seconds() -> None:
+    """Numeric MT5 ``time`` values are interpreted as Unix seconds."""
+    frame = pd.DataFrame({"time": [1704067200]})
+    result = normalize_time_columns(frame, DataKind.rates)
+    assert result.loc[0, "time"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
+
+
+def test_normalize_time_columns_converts_unix_milliseconds() -> None:
+    """Numeric MT5 ``time_msc`` values are interpreted as Unix milliseconds."""
+    frame = pd.DataFrame({"time_msc": [1704067200000]})
+    result = normalize_time_columns(frame, DataKind.ticks)
+    assert result.loc[0, "time_msc"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
+
+
+def test_normalize_time_columns_preserves_utc_datetimes() -> None:
+    """Already-converted datetime values remain UTC-normalized."""
+    aware = datetime(2024, 1, 1, tzinfo=UTC)
+    frame = pd.DataFrame({"time": [aware]})
+    result = normalize_time_columns(frame, DataKind.rates)
+    assert result.loc[0, "time"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
+
+
+def test_normalize_time_columns_handles_optional_order_times() -> None:
+    """Optional order/history time columns are normalized when present."""
+    frame = pd.DataFrame({
+        "time_setup": [1704067200],
+        "time_setup_msc": [1704067200000],
+        "time_done": [1704153600],
+        "time_done_msc": [1704153600000],
+    })
+    result = normalize_time_columns(frame, DataKind.orders)
+    assert result.loc[0, "time_setup"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
+    assert result.loc[0, "time_setup_msc"] == pd.Timestamp(
+        "2024-01-01T00:00:00+00:00",
+    )
+    assert result.loc[0, "time_done"] == pd.Timestamp("2024-01-02T00:00:00+00:00")
+    assert result.loc[0, "time_done_msc"] == pd.Timestamp(
+        "2024-01-02T00:00:00+00:00",
+    )
+
+
+def test_time_columns_include_optional_order_fields() -> None:
+    """Schema contracts document optional MT5 time columns per dataset kind."""
+    assert "time_done" in TIME_COLUMNS[DataKind.orders]
+    assert "time_setup_msc" in TIME_COLUMNS[DataKind.history_orders]
+
+
+def test_normalize_dataframe_sorts_ticks_by_time_msc(
+    mocker: MockerFixture,
+) -> None:
+    """Tick frames without ``time`` can still sort on ``time_msc``."""
+    mocker.patch("mt5cli.schemas.validate_schema")
+    ticks = pd.concat([_sample_frame(DataKind.ticks)] * 2, ignore_index=True).drop(
+        columns=["time"],
+    )
+    ticks.loc[0, "time_msc"] = datetime(2024, 1, 1, tzinfo=UTC)
+    ticks.loc[1, "time_msc"] = datetime(2024, 1, 2, tzinfo=UTC)
+    ticks = pd.concat([ticks.iloc[[1]], ticks.iloc[[0]]], ignore_index=True)
+    normalized = normalize_dataframe(ticks, DataKind.ticks, sort=True)
+    assert normalized.iloc[0]["time_msc"] <= normalized.iloc[1]["time_msc"]
+
+
+def test_ensure_utc_columns_skips_missing_columns() -> None:
+    """UTC column coercion ignores absent columns."""
+    frame = _sample_frame(DataKind.rates)
+    result = ensure_utc_columns(frame, ["time", "missing"])
+    assert "time" in result.columns
+
+
+def test_normalize_time_columns_coerces_string_timestamps() -> None:
+    """String timestamps are parsed with timezone-aware datetime coercion."""
+    frame = pd.DataFrame({"time": ["2024-01-01T00:00:00+00:00"]})
+    result = normalize_time_columns(frame, DataKind.rates)
+    assert result.loc[0, "time"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
+
+
+def test_ensure_utc_columns_coerces_non_mt5_columns() -> None:
+    """Non-MT5 columns still coerce to UTC datetimes."""
+    frame = pd.DataFrame({"created_at": ["2024-01-01T00:00:00+00:00"]})
+    result = ensure_utc_columns(frame, ["created_at"])
+    assert result.loc[0, "created_at"] == pd.Timestamp("2024-01-01T00:00:00+00:00")
+
+
+def test_mt5_session_yields_connected_client(mocker: MockerFixture) -> None:
+    """Public mt5_session yields an MT5Client bound to a connected session."""
+    connected = mocker.MagicMock()
+    context = mocker.MagicMock()
+    context.__enter__.return_value = connected
+    context.__exit__.return_value = False
+    mocker.patch("mt5cli.client.connected_client", return_value=context)
+    with mt5_session(build_config()) as client:
+        assert isinstance(client, MT5Client)
+
+
+def test_retry_with_backoff_reraises_non_recoverable_errors() -> None:
+    """Non-MT5 errors are not retried."""
+
+    def _raise() -> None:
+        message = "fatal"
+        raise ValueError(message)
+
+    with pytest.raises(ValueError, match="fatal"):
+        retry_with_backoff(_raise, retry_count=2)
+
+
+def test_storage_export_round_trip_sqlite(tmp_path: Path) -> None:
+    """Storage helpers append deduplicated frames to SQLite."""
+    frame = normalize_dataframe(
+        _sample_frame(DataKind.rates),
+        DataKind.rates,
+        symbol="EURUSD",
+        timeframe="M1",
+    )
+    output = tmp_path / "rates.db"
+    export_dataframe_to_sqlite(
+        frame,
+        output,
+        "rates",
+        deduplicate_on=DEDUP_KEYS[DataKind.rates][0],
+    )
+    with __import__("sqlite3").connect(output) as conn:
+        count = conn.execute("SELECT COUNT(*) FROM rates").fetchone()[0]
+    assert count == 1

tests/test_utils.py

@@ -0,0 +1,480 @@
+"""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,
+    IfExists,
+    detect_format,
+    export_dataframe,
+    export_dataframe_to_sqlite,
+    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")
+
+
+class TestExportDataframeToSqlite:
+    """Tests for export_dataframe_to_sqlite."""
+
+    def test_append_preserves_existing_rows(self, tmp_path: Path) -> None:
+        """Test append mode keeps prior rows in the SQLite table."""
+        output = tmp_path / "append.db"
+        first = pd.DataFrame({"id": [1], "value": ["a"]})
+        second = pd.DataFrame({"id": [2], "value": ["b"]})
+        export_dataframe_to_sqlite(first, output, "items", if_exists=IfExists.REPLACE)
+        export_dataframe_to_sqlite(second, output, "items", if_exists=IfExists.APPEND)
+        with sqlite3.connect(output) as conn:
+            result = pd.read_sql(  # type: ignore[reportUnknownMemberType]
+                "SELECT id, value FROM items ORDER BY id",
+                conn,
+            )
+        pd.testing.assert_frame_equal(
+            result,
+            pd.DataFrame({"id": [1, 2], "value": ["a", "b"]}),
+        )
+
+    def test_deduplicate_keeps_latest_row(self, tmp_path: Path) -> None:
+        """Test deduplication keeps the latest ROWID for key columns."""
+        output = tmp_path / "dedup.db"
+        first = pd.DataFrame({
+            "symbol": ["EURUSD", "EURUSD"],
+            "time": ["2024-01-01", "2024-01-01"],
+            "bid": [1.0, 1.1],
+        })
+        second = pd.DataFrame({
+            "symbol": ["EURUSD"],
+            "time": ["2024-01-01"],
+            "bid": [1.2],
+        })
+        export_dataframe_to_sqlite(
+            first,
+            output,
+            "ticks",
+            if_exists=IfExists.REPLACE,
+            deduplicate_on=("symbol", "time"),
+        )
+        export_dataframe_to_sqlite(
+            second,
+            output,
+            "ticks",
+            if_exists=IfExists.APPEND,
+            deduplicate_on=("symbol", "time"),
+        )
+        with sqlite3.connect(output) as conn:
+            result = pd.read_sql(  # type: ignore[reportUnknownMemberType]
+                "SELECT symbol, time, bid FROM ticks",
+                conn,
+            )
+        pd.testing.assert_frame_equal(
+            result.reset_index(drop=True),
+            pd.DataFrame({
+                "symbol": ["EURUSD"],
+                "time": ["2024-01-01"],
+                "bid": [1.2],
+            }),
+        )
+
+    def test_default_if_exists_appends_without_dropping_rows(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        """Test the default append mode keeps prior rows."""
+        output = tmp_path / "default-append.db"
+        first = pd.DataFrame({"id": [1], "value": ["a"]})
+        second = pd.DataFrame({"id": [2], "value": ["b"]})
+        export_dataframe_to_sqlite(first, output, "items")
+        export_dataframe_to_sqlite(second, output, "items")
+        with sqlite3.connect(output) as conn:
+            result = pd.read_sql(  # type: ignore[reportUnknownMemberType]
+                "SELECT id, value FROM items ORDER BY id",
+                conn,
+            )
+        pd.testing.assert_frame_equal(
+            result,
+            pd.DataFrame({"id": [1, 2], "value": ["a", "b"]}),
+        )
+
+    def test_writes_index_with_label(self, tmp_path: Path) -> None:
+        """Test optional index export with a custom label."""
+        output = tmp_path / "index.db"
+        frame = pd.DataFrame(
+            {"value": [1.0]}, index=pd.Index(["EURUSD"], name="symbol")
+        )
+        export_dataframe_to_sqlite(
+            frame,
+            output,
+            "margins",
+            if_exists=IfExists.REPLACE,
+            index=True,
+            index_label="symbol",
+        )
+        with sqlite3.connect(output) as conn:
+            result = pd.read_sql(  # type: ignore[reportUnknownMemberType]
+                "SELECT symbol, value FROM margins",
+                conn,
+            )
+        pd.testing.assert_frame_equal(
+            result,
+            pd.DataFrame({"symbol": ["EURUSD"], "value": [1.0]}),
+        )
+
+
+# ---------------------------------------------------------------------------
+# 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 supported integer timeframes."""
+        assert parse_timeframe("1") == 1
+        assert parse_timeframe(16385) == 16385
+
+    def test_unsupported_integer_timeframe_raises(self) -> None:
+        """Test that unsupported integer timeframes raise ValueError."""
+        with pytest.raises(ValueError, match="Invalid timeframe"):
+            parse_timeframe("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", 1), ("TRADE", 2), ("COPY_TICKS_ALL", -1)],
+    )
+    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 supported integer tick flags."""
+        assert parse_tick_flags("-1") == -1
+        assert parse_tick_flags(2) == 2
+
+    def test_unsupported_integer_flag_raises(self) -> None:
+        """Test that unsupported integer tick flags raise ValueError."""
+        with pytest.raises(ValueError, match="Invalid tick flags"):
+            parse_tick_flags("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 with MT5 values."""
+        assert {"ALL", "INFO", "TRADE"} <= set(TICK_FLAG_MAP)
+        assert TICK_FLAG_MAP["ALL"] == -1
+        assert TICK_FLAG_MAP["INFO"] == 1
+        assert TICK_FLAG_MAP["TRADE"] == 2
+
+    @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(self) -> None:
+        """Test converting supported integer timeframe values."""
+        assert TIMEFRAME_TYPE.convert(16385, None, None) == 16385
+
+    def test_convert_unsupported_int(self) -> None:
+        """Test that unsupported integer values raise BadParameter."""
+        with pytest.raises(Exception, match="Invalid timeframe"):
+            TIMEFRAME_TYPE.convert(42, None, None)
+
+    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)
+
+    @pytest.mark.parametrize("value", [True, False, None, 1.5])
+    def test_convert_invalid_types(self, value: object) -> None:
+        """Test that bool, float, and None values raise BadParameter."""
+        with pytest.raises(Exception, match="Invalid timeframe"):
+            TIMEFRAME_TYPE.convert(value, 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(self) -> None:
+        """Test converting supported integer tick flag values."""
+        assert TICK_FLAGS_TYPE.convert(2, None, None) == 2
+
+    def test_convert_unsupported_int(self) -> None:
+        """Test that unsupported integer values raise BadParameter."""
+        with pytest.raises(Exception, match="Invalid tick flags"):
+            TICK_FLAGS_TYPE.convert(7, None, None)
+
+    @pytest.mark.parametrize("value", [True, False, None, 1.5])
+    def test_convert_invalid_types(self, value: object) -> None:
+        """Test that bool, float, and None values raise BadParameter."""
+        with pytest.raises(Exception, match="Invalid tick flags"):
+            TICK_FLAGS_TYPE.convert(value, None, None)
+
+    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)

uv.lock

@@ -487,7 +487,7 @@ wheels = [
 
 [[package]]
 name = "mt5cli"
-version = "0.3.0"
+version = "0.8.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -513,7 +513,7 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "click", specifier = ">=8.1.0" },
-    { name = "pdmt5", specifier = ">=0.2.3" },
+    { name = "pdmt5", specifier = ">=0.3.0" },
     { name = "pyarrow", specifier = ">=19.0.0" },
     { name = "typer", specifier = ">=0.15.0" },
 ]
@@ -684,16 +684,16 @@ wheels = [
 
 [[package]]
 name = "pdmt5"
-version = "0.2.3"
+version = "0.3.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "metatrader5", marker = "sys_platform == 'win32'" },
     { name = "pandas" },
     { name = "pydantic" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/02/25/52d9d954504ccdd0fe91f715ab74c424d61234b237cc4160d3ebe20070f1/pdmt5-0.2.3.tar.gz", hash = "sha256:21384f5826fb0125fee3f93c90b108340f55ab53b1c819d229ceac162289d2ec", size = 226665, upload-time = "2026-02-05T13:28:21.071Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/bf/cc/c8fa3a01e0e34178fec8527992f7bb8eda5881477ce23aaacaa9b2ef7bec/pdmt5-0.3.0.tar.gz", hash = "sha256:bb612d5c2695eafac9b2a7b74756e13bd383d7e5517bd90c9a2efa92492c484c", size = 215100, upload-time = "2026-06-11T13:26:46.976Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c1/75/c5e52a9cf459b85b2dd52f83e70857571b1b45805c9fe610b3959a26ac15/pdmt5-0.2.3-py3-none-any.whl", hash = "sha256:f92246a05cfc3b7feb3ab0cc5b48768a4d84aad6b02e7a68060948f5828718a1", size = 22967, upload-time = "2026-02-05T13:28:19.523Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/03/b12cc4c9db983d971c9172b3765161b6d91136d0624e6718a04dd815e7a1/pdmt5-0.3.0-py3-none-any.whl", hash = "sha256:5388b406cc583202600cfe22c9d781679b1d931b1ed5a2b5dcf37c566149b49f", size = 26250, upload-time = "2026-06-11T13:26:45.689Z" },
 ]
 
 [[package]]
@@ -836,11 +836,11 @@ wheels = [
 
 [[package]]
 name = "pygments"
-version = "2.19.2"
+version = "2.20.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/b0/77/a5b8c569bf593b0140bde72ea885a803b82086995367bf2037de0159d924/pygments-2.19.2.tar.gz", hash = "sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887", size = 4968631, upload-time = "2025-06-21T13:39:12.283Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/c7/21/705964c7812476f378728bdf590ca4b771ec72385c533964653c68e86bdc/pygments-2.19.2-py3-none-any.whl", hash = "sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b", size = 1225217, upload-time = "2025-06-21T13:39:07.939Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
 ]
 
 [[package]]