mt5cli 0.7.2__tar.gz → 0.8.1__tar.gz

mt5cli-0.8.1/.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

{mt5cli-0.7.2 → mt5cli-0.8.1}/.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

mt5cli-0.8.1/AGENTS.md

@@ -0,0 +1,37 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+`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.
+
+## Build, Test, and Development Commands
+
+- `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.
+
+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.
+
+## Coding Style & Naming Conventions
+
+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.
+
+## Design Principles
+
+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.
+
+## Testing Guidelines
+
+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
+
+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.
+
+## Security & Configuration Tips
+
+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.

{mt5cli-0.7.2 → mt5cli-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 0.7.2
+Version: 0.8.1
 Summary: Generic MT5 data and execution infrastructure for Python applications
 Project-URL: Repository, https://github.com/dceoy/mt5cli.git
 Author-email: dceoy <dceoy@users.noreply.github.com>
@@ -28,6 +28,8 @@ Description-Content-Type: text/markdown
 
 Generic MT5 data and execution infrastructure for Python applications. Export from the CLI or import a small, stable Python API in downstream packages.
 
+The [Public API Contract](docs/api/public-contract.md) lists stable SDK exports (`mt5cli.STABLE_SDK_EXPORTS`), CLI commands, internal helpers, and responsibilities that remain out of scope (strategy logic, backtests, optimization).
+
 Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data handler for MetaTrader 5.
 
 ## Architecture
@@ -109,6 +111,37 @@ Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `norma
 
 `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
@@ -220,7 +253,7 @@ update_history_with_config(
 - **`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 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 downstream tools.
 - **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.
@@ -253,12 +286,12 @@ eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 - Windows OS (MetaTrader 5 requirement)
 - MetaTrader 5 platform installed
 
-### Migration note for mteor
+### Migration note for downstream trading apps
 
 Replace local MT5 lifecycle and trading helper code with mt5cli imports:
 
 ```python
-# Before (local mteor helpers)
+# Before (local application 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)

{mt5cli-0.7.2 → mt5cli-0.8.1}/README.md

@@ -4,6 +4,8 @@
 
 Generic MT5 data and execution infrastructure for Python applications. Export from the CLI or import a small, stable Python API in downstream packages.
 
+The [Public API Contract](docs/api/public-contract.md) lists stable SDK exports (`mt5cli.STABLE_SDK_EXPORTS`), CLI commands, internal helpers, and responsibilities that remain out of scope (strategy logic, backtests, optimization).
+
 Built on top of [pdmt5](https://github.com/dceoy/pdmt5), a pandas-based data handler for MetaTrader 5.
 
 ## Architecture
@@ -85,6 +87,37 @@ Schema contracts live in `mt5cli.schemas` (`DataKind`, `validate_schema`, `norma
 
 `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
@@ -196,7 +229,7 @@ update_history_with_config(
 - **`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 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 downstream tools.
 - **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.
@@ -229,12 +262,12 @@ eurusd_m1 = rates["EURUSD", "M1"]  # closed bars only
 - Windows OS (MetaTrader 5 requirement)
 - MetaTrader 5 platform installed
 
-### Migration note for mteor
+### Migration note for downstream trading apps
 
 Replace local MT5 lifecycle and trading helper code with mt5cli imports:
 
 ```python
-# Before (local mteor helpers)
+# Before (local application 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)

{mt5cli-0.7.2 → mt5cli-0.8.1}/docs/api/history.md

@@ -167,19 +167,45 @@ Resolution rules:
 
 ### Rate data loading
 
-Use `load_rate_data()` to load a table or view from a SQLite path, or
-`load_rate_data_from_connection()` when you already have a connection:
+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
+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`.

{mt5cli-0.7.2 → mt5cli-0.8.1}/docs/api/index.md

@@ -2,10 +2,15 @@
 
 This section documents the mt5cli public Python API and CLI modules.
 
+Start with the [Public API Contract](public-contract.md) for the stable
+downstream SDK surface, CLI boundary, internal modules, and out-of-scope strategy
+responsibilities.
+
 ## Public API layers
 
 | Module                                    | Purpose                                                                   |
 | ----------------------------------------- | ------------------------------------------------------------------------- |
+| [Public API Contract](public-contract.md) | Stable downstream SDK exports, CLI boundary, and out-of-scope items       |
 | [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             |
@@ -30,7 +35,10 @@ flowchart TD
     SDK --> PDMT5["pdmt5.Mt5DataClient"]
 ```
 
-Downstream packages should depend on the package root exports (`MT5Client`, `DataKind`, `normalize_dataframe`, `export_dataframe`, `collect_history`, etc.) rather than private modules.
+Downstream packages should depend on the package root exports documented in the
+[Public API Contract](public-contract.md) (`MT5Client`,
+`DataKind`, `normalize_dataframe`, `collect_history`, `load_rate_data`,
+`resolve_rate_view_name`, 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.
 

mt5cli-0.8.1/docs/api/public-contract.md

@@ -0,0 +1,184 @@
+# Public API Contract
+
+mt5cli is the generic MT5 data and execution infrastructure layer for downstream
+Python applications. The intended dependency direction is:
+
+```text
+downstream app -> mt5cli -> pdmt5 -> MetaTrader 5
+```
+
+Downstream packages should import from the package root (`from mt5cli import
+...`) and treat the symbols listed below as the stable SDK contract. CLI
+commands mirror the same behavior but are not importable Python APIs.
+
+## Stable downstream SDK API
+
+These names are exported from `mt5cli` and covered by the contract in
+`mt5cli.STABLE_SDK_EXPORTS` (defined in `mt5cli.contract`). Prefer `MT5Client` over the legacy `Mt5CliClient`
+alias for new code.
+
+### Session lifecycle and configuration
+
+| Symbol                                          | Role                                                             |
+| ----------------------------------------------- | ---------------------------------------------------------------- |
+| `MT5Client`, `Mt5CliClient`                     | Read-only data client with optional `order_check` / `order_send` |
+| `build_config`                                  | Build `pdmt5.Mt5Config` from connection fields                   |
+| `mt5_session`                                   | Context manager: initialize, login, yield client, shutdown       |
+| `create_trading_client`, `mt5_trading_session`  | Trading-capable `pdmt5.Mt5TradingClient` lifecycle               |
+| `AccountSpec`                                   | Generic account group: symbols plus optional credentials         |
+| `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders             |
+| `substitute_env_placeholders`                   | Replace `${NAME}` substrings from the environment                |
+
+Credential resolution is generic: any environment variable name may appear inside
+`${...}`. mt5cli does not hard-code application-specific keys such as
+`mt5_login` or `mt5_exe`.
+
+### Read-only MT5 data access
+
+Module-level helpers open a transient connection per call. Prefer `mt5_session`
+or `MT5Client` when making many requests in one process.
+
+| Area                 | Symbols                                                                                              |
+| -------------------- | ---------------------------------------------------------------------------------------------------- |
+| Rates                | `copy_rates_from`, `copy_rates_from_pos`, `copy_rates_range`, `latest_rates`, `collect_latest_rates` |
+| Ticks                | `copy_ticks_from`, `copy_ticks_range`, `recent_ticks`                                                |
+| Account / terminal   | `account_info`, `terminal_info`, `mt5_version`, `last_error`, `mt5_summary`, `mt5_summary_as_df`     |
+| Symbols / market     | `symbols`, `symbol_info`, `symbol_info_tick`, `market_book`, `minimum_margins`                       |
+| Trading state (read) | `orders`, `positions`, `history_orders`, `history_deals`, `recent_history_deals`                     |
+
+Use `mt5_version` for MetaTrader 5 terminal version data. The name `version` at
+the package root refers to `importlib.metadata.version` (package metadata), not
+the MT5 SDK helper.
+
+### Closed-bar rate helpers
+
+MetaTrader 5 returns the still-forming bar as the last row when
+`start_pos=0`. Use these helpers instead of reimplementing bar trimming or
+timestamp normalization in downstream apps.
+
+| Symbol                                           | Role                                                         |
+| ------------------------------------------------ | ------------------------------------------------------------ |
+| `drop_forming_rate_bar`                          | Remove the last row from chronologically ordered rate data   |
+| `fetch_latest_closed_rates`                      | Single connected client: fetch `count + 1`, drop forming bar |
+| `collect_latest_closed_rates_for_accounts`       | Multi-account closed bars with optional retry wrapper        |
+| `collect_latest_closed_rates_by_granularity`     | Same data keyed by `(symbol, granularity_name)`              |
+| `collect_latest_rates_for_accounts`              | Latest bars including the forming bar when `start_pos=0`     |
+| `collect_latest_rates_for_accounts_with_retries` | Bounded exponential backoff for transient MT5 errors         |
+
+### SQLite history collection and rate loading
+
+| Symbol                                                                                                                        | Role                                                                 |
+| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `collect_history`                                                                                                             | One-shot date-range export into SQLite                               |
+| `update_history`, `update_history_with_config`                                                                                | Incremental append from `MAX(time)` cursors                          |
+| `ThrottledHistoryUpdater`                                                                                                     | Minimum interval between successful incremental updates              |
+| `resolve_history_datasets`, `resolve_history_timeframes`, `resolve_history_tick_flags`                                        | History pipeline configuration                                       |
+| `build_rate_view_name`, `resolve_rate_table_name`, `resolve_rate_view_name`, `resolve_rate_view_names`, `resolve_rate_tables` | Map symbols/timeframes to mt5cli-managed table or view names         |
+| `RateTarget`, `build_rate_targets`                                                                                            | Neutral `(symbol, timeframe)` series descriptors                     |
+| `load_rate_data`, `load_rate_data_from_connection`                                                                            | Load one table/view into a time-indexed DataFrame                    |
+| `load_rate_series_from_sqlite`, `load_rate_series_by_granularity`                                                             | Load one or many series; fail clearly when managed views are missing |
+
+Pass `require_existing=True` to rate view resolution helpers when downstream
+code must fail instead of receiving a best-guess view name. Multi-series loaders
+require existing managed `rate_*__*` views unless `explicit_tables` is supplied.
+
+See [History Collection (SQLite)](history.md) for schema, view naming, and ER
+diagrams.
+
+### Trading and sizing primitives (generic)
+
+These helpers implement broker-facing calculations only. They do not encode
+strategy entries, exits, Kelly sizing, or signal logic.
+
+| Symbol                                                                                             | Role                                          |
+| -------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| `get_account_snapshot`, `get_symbol_snapshot`, `get_tick_snapshot`, `get_positions_frame`          | Normalized account/symbol/tick/position views |
+| `detect_position_side`                                                                             | Net long / short / flat from open positions   |
+| `calculate_spread_ratio`                                                                           | Relative bid-ask spread                       |
+| `calculate_margin_and_volume`, `calculate_volume_by_margin`, `calculate_new_position_margin_ratio` | Margin budget and volume sizing               |
+| `determine_order_limits`                                                                           | SL/TP price levels from ratios                |
+| `ensure_symbol_selected`                                                                           | Select/verify Market Watch visibility         |
+| `place_market_order`, `close_open_positions`, `update_sltp_for_open_positions`                     | Order execution helpers (`dry_run` supported) |
+| `MarginVolume`, `OrderLimits`, `OrderExecutionResult`                                              | Typed return contracts for order helpers      |
+| `OrderSide`, `OrderFillingMode`, `OrderTimeMode`, `PositionSide`, `ExecutionStatus`                | Typed enums for order helpers                 |
+
+`MT5Client.order_send()` and CLI `order-send --yes` are live execution paths.
+
+Order helpers validate broker stop-level distance in `determine_order_limits()` and
+raise `Mt5TradingError` when computed SL/TP prices are too close to the entry
+quote. Validation uses `trade_stops_level * point` from the current quote and
+symbol metadata as a pre-check only; it does not guarantee live order acceptance
+after price movement and does not inspect `trade_freeze_level`. Live
+`place_market_order()` and SL/TP updates call
+`ensure_symbol_selected()` so hidden symbols are added to Market Watch before
+sending requests. Failed, malformed, or unknown broker retcodes are fail-closed
+and returned as `status="failed"` with normalized `request` / `response` details;
+`dry_run=True` never calls `ensure_symbol_selected()` or `order_send()`.
+
+### Errors and MT5 type re-exports
+
+| Symbol                                                                               | Role                                            |
+| ------------------------------------------------------------------------------------ | ----------------------------------------------- |
+| `Mt5CliError`, `Mt5ConnectionError`, `Mt5OperationError`, `Mt5SchemaError`           | Stable mt5cli exception types                   |
+| `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error` | Error normalization and retry classification    |
+| `Mt5Config`, `Mt5RuntimeError`, `Mt5TradingClient`, `Mt5TradingError`                | Re-exported pdmt5 types for adapter convenience |
+
+### Additional public exports (secondary)
+
+The package root also exports schema, storage, and parsing helpers (for example
+`DataKind`, `Dataset`, `normalize_dataframe`, `export_dataframe`,
+`parse_timeframe`, `TIMEFRAME_MAP`). These are public but oriented toward export
+pipelines and advanced integration. Prefer the stable symbols above for core
+infrastructure.
+
+## CLI commands
+
+The Typer application in `mt5cli.cli` exposes file-export commands documented in
+[CLI Module](cli.md) and the project README. CLI commands:
+
+- Require `-o/--output` and write CSV, JSON, Parquet, or SQLite.
+- Accept global MT5 connection options (`--login`, `--password`, `--server`,
+  `--path`, `--timeout`).
+- Delegate to the same Python APIs described here; they are not duplicated
+  business logic.
+
+`order-send` requires `--yes` before placing live trades.
+
+## Internal helpers (not stable)
+
+Do not import these for downstream contracts; they may change without a semver
+notice:
+
+| Module                   | Examples                                                                  |
+| ------------------------ | ------------------------------------------------------------------------- |
+| `mt5cli.sdk`             | `connected_client`, `_run_with_client`, private coercion helpers          |
+| `mt5cli.history`         | `write_*_dataset`, `deduplicate_history_tables`, `parse_sqlite_timestamp` |
+| `mt5cli.retry`           | `retry_with_backoff`                                                      |
+| `mt5cli.cli`             | Typer command handlers and Click parameter types                          |
+| Leading-underscore names | Any `_`-prefixed function or method                                       |
+
+Use the package-root stable exports instead of reaching into submodule
+internals.
+
+## Explicitly out of scope
+
+mt5cli must **not** implement downstream strategy or research responsibilities.
+The following belong in consuming applications, not in mt5cli:
+
+- Signal detection (for example AR-GARCH or other model-specific triggers)
+- Backtesting, walk-forward analysis, or parameter optimization
+- Strategy-specific risk policy, position sizing systems, or Kelly fractions
+- Entry/exit decision logic or YAML strategy semantics
+- Application-specific credential schema keys wired into mt5cli internals
+
+mt5cli provides connection lifecycle, normalized data access, SQLite history
+machinery, closed-bar helpers, generic margin/volume/spread/SL/TP utilities, and
+optional order primitives so downstream apps can focus on strategy code behind
+their own adapter layer.
+
+## Contract verification
+
+`tests/test_contracts.py` asserts that every name in `STABLE_SDK_EXPORTS` is
+importable from `mt5cli`, documents key closed-bar, rate-view, SQLite loading,
+account-resolution, and trading-session behaviors, and keeps the contract set
+aligned with `__all__`.