docs: stable SDK contract and strategy-neutral order helpers (#37)

* 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,81 +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
-  - `utils.py`: Constants, enums, parameter types, parsers, and export utilities
-  - `__main__.py`: Entry point for `python -m mt5cli`
-- `tests/`: Comprehensive test suite (pytest-based)
-  - `test_cli.py`: Tests for CLI commands and collect-history behavior
-  - `test_utils.py`: Tests for utility constants, parameter types, parsers, and export functions
-- `docs/`: MkDocs documentation with API reference
-  - `docs/index.md`: Main documentation
-  - `docs/api/`: Auto-generated API documentation for all modules
-- 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

@@ -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)

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

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.
 

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

docs/api/sdk.md

@@ -31,13 +31,25 @@ rates = collect_latest_rates_for_accounts_with_retries(
 ### Latest closed rate bars
 
 MetaTrader 5 `start_pos=0` includes the still-forming current bar as the last
-row. `collect_latest_closed_rates_for_accounts()` fetches `count + 1` bars,
-drops that row with `drop_forming_rate_bar()`, and validates each series is
-non-empty. Use `collect_latest_closed_rates_by_granularity()` when callers
-prefer keys such as `("EURUSD", "M1")` instead of integer timeframes.
+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
+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)],
@@ -48,6 +60,9 @@ rates = collect_latest_closed_rates_by_granularity(
 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

docs/api/trading.md

@@ -4,38 +4,60 @@
 
 ## Trading-capable MT5 sessions
 
-`mt5_trading_session()` complements the read-only `mt5_session()` helper in
-`sdk.py`. It yields a connected `pdmt5.Mt5TradingClient`, uses
-`Mt5Config.path` to launch the terminal when configured, and always calls
-`shutdown()` on exit.
+`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 pdmt5 import Mt5Config
-
-from mt5cli import mt5_trading_session
+from mt5cli import create_trading_client, mt5_trading_session
 
 with mt5_trading_session(
-    Mt5Config(path=r"C:\Program Files\MetaTrader 5\terminal64.exe", login=12345),
+    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.
 
-## Operational trading helpers
+## 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",
@@ -49,15 +71,84 @@ limits = determine_order_limits(
     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)
 ```
 
-Protective ratios must satisfy `0 <= ratio < 1`; `0` omits that level.
-`calculate_margin_and_volume()` clamps negative `margin_free` to `0.0`
-before sizing.
+`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.
 
-## Migration from mteor-local helpers
+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. `determine_order_limits()` pre-validates computed SL/TP prices against
+available `trade_stops_level * point` metadata when present; violations raise
+`Mt5TradingError`. This is a planning helper only: it does not guarantee broker
+acceptance because live validation can still depend on price movement, bid/ask
+side, freeze levels, and server-side rules, and it does not validate
+`trade_freeze_level`. When symbol metadata cannot be loaded, protective prices
+still round with `digits=8` and stop-level validation is skipped.
+`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 `OrderExecutionResult`
+dictionaries containing the request, response, status, retcode, and `dry_run`
+flag; `dry_run=True` never sends an order or mutates Market Watch visibility.
+`ensure_symbol_selected()` adds hidden symbols to Market Watch before live order
+placement and SL/TP updates. Failed, malformed, or unknown broker retcodes are
+fail-closed and returned as `status="failed"` while keeping the normalized
+response for inspection.
 
-| mteor-local concern                                      | mt5cli replacement                              |
+## Order planning return contracts
+
+```python
+from mt5cli import MarginVolume, OrderLimits, OrderExecutionResult
+
+sizing: MarginVolume = calculate_margin_and_volume(
+    client,
+    "EURUSD",
+    unit_margin_ratio=0.5,
+    preserved_margin_ratio=0.2,
+)
+limits: OrderLimits = determine_order_limits(
+    client,
+    "EURUSD",
+    side="long",
+    stop_loss_limit_ratio=0.01,
+    take_profit_limit_ratio=0.02,
+)
+preview: OrderExecutionResult = place_market_order(
+    client,
+    symbol="EURUSD",
+    volume=sizing["buy_volume"],
+    order_side="BUY",
+    sl=limits["stop_loss"],
+    tp=limits["take_profit"],
+    dry_run=True,
+)
+updates: list[OrderExecutionResult] = update_sltp_for_open_positions(
+    client,
+    symbol="EURUSD",
+    stop_loss=limits["stop_loss"],
+    dry_run=True,
+)
+```
+
+Closes issue #33: strategy-neutral order planning and execution helpers exposed
+through the stable package root without embedding entry/exit policy.
+
+## Migration from application-local helpers
+
+| Application-local concern                                | mt5cli replacement                              |
 | -------------------------------------------------------- | ----------------------------------------------- |
 | Manual terminal spawn/kill around trading code           | `mt5_trading_session()`                         |
 | Local position-side detection                            | `detect_position_side()`                        |

mkdocs.yml

@@ -56,6 +56,7 @@ nav:
   - Home: index.md
   - API Reference:
       - Overview: api/index.md
+      - Public API Contract: api/public-contract.md
       - Client: api/client.md
       - Schemas: api/schemas.md
       - Storage: api/storage.md

mt5cli/__init__.py

@@ -1,8 +1,17 @@
-"""mt5cli: Generic MT5 data and execution infrastructure for Python applications."""
+"""mt5cli: Generic MT5 data and execution infrastructure for Python applications.
+
+Downstream packages should import from this module (``from mt5cli import ...``)
+rather than private submodule helpers. See ``docs/api/public-contract.md`` for
+the stable SDK contract, CLI surface, internal modules, and out-of-scope
+strategy responsibilities.
+"""
 
 from importlib.metadata import version
 
+from pdmt5 import Mt5Config, Mt5RuntimeError, Mt5TradingClient, Mt5TradingError
+
 from .client import MT5Client, build_config, mt5_session
+from .contract import STABLE_SDK_EXPORTS
 from .converters import (
     ensure_utc,
     granularity_name,
@@ -32,6 +41,7 @@ from .history import (
     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,
@@ -63,6 +73,7 @@ from .sdk import (
     copy_rates_range,
     copy_ticks_from,
     copy_ticks_range,
+    fetch_latest_closed_rates,
     history_deals,
     history_orders,
     last_error,
@@ -96,10 +107,31 @@ from .storage import (
     export_dataframe_to_sqlite,
 )
 from .trading import (
+    POSITION_COLUMNS,
+    ExecutionStatus,
+    MarginVolume,
+    OrderExecutionResult,
+    OrderFillingMode,
+    OrderLimits,
+    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,
+    ensure_symbol_selected,
+    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,
@@ -114,20 +146,34 @@ __version__ = version(__package__) if __package__ else None
 __all__ = [
     "DEDUP_KEYS",
     "KNOWN_MT5_TIME_COLUMNS",
+    "POSITION_COLUMNS",
     "REQUIRED_COLUMNS",
+    "STABLE_SDK_EXPORTS",
     "TICK_FLAG_MAP",
     "TIMEFRAME_MAP",
     "TIME_COLUMNS",
     "AccountSpec",
     "DataKind",
     "Dataset",
+    "ExecutionStatus",
     "IfExists",
     "MT5Client",
+    "MarginVolume",
     "Mt5CliClient",
     "Mt5CliError",
+    "Mt5Config",
     "Mt5ConnectionError",
     "Mt5OperationError",
+    "Mt5RuntimeError",
     "Mt5SchemaError",
+    "Mt5TradingClient",
+    "Mt5TradingError",
+    "OrderExecutionResult",
+    "OrderFillingMode",
+    "OrderLimits",
+    "OrderSide",
+    "OrderTimeMode",
+    "PositionSide",
     "RateTarget",
     "ThrottledHistoryUpdater",
     "account_info",
@@ -135,7 +181,11 @@ __all__ = [
     "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",
@@ -147,13 +197,20 @@ __all__ = [
     "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_symbol_selected",
     "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",
@@ -181,6 +238,7 @@ __all__ = [
     "parse_datetime",
     "parse_tick_flags",
     "parse_timeframe",
+    "place_market_order",
     "positions",
     "recent_history_deals",
     "recent_ticks",
@@ -190,6 +248,7 @@ __all__ = [
     "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",
@@ -201,5 +260,6 @@ __all__ = [
     "terminal_info",
     "update_history",
     "update_history_with_config",
+    "update_sltp_for_open_positions",
     "validate_schema",
 ]

mt5cli/contract.py

@@ -0,0 +1,101 @@
+"""Stable downstream SDK export names for mt5cli."""
+
+from __future__ import annotations
+
+STABLE_SDK_EXPORTS: frozenset[str] = frozenset({
+    "AccountSpec",
+    "MT5Client",
+    "Mt5CliClient",
+    "Mt5CliError",
+    "Mt5Config",
+    "Mt5ConnectionError",
+    "Mt5OperationError",
+    "Mt5RuntimeError",
+    "Mt5SchemaError",
+    "Mt5TradingClient",
+    "Mt5TradingError",
+    "OrderFillingMode",
+    "OrderSide",
+    "OrderTimeMode",
+    "PositionSide",
+    "ExecutionStatus",
+    "MarginVolume",
+    "OrderExecutionResult",
+    "OrderLimits",
+    "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_position_side",
+    "determine_order_limits",
+    "drop_forming_rate_bar",
+    "ensure_symbol_selected",
+    "export_dataframe",
+    "export_dataframe_to_sqlite",
+    "fetch_latest_closed_rates",
+    "get_account_snapshot",
+    "get_positions_frame",
+    "get_symbol_snapshot",
+    "get_tick_snapshot",
+    "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_mt5_exception",
+    "orders",
+    "place_market_order",
+    "positions",
+    "recent_history_deals",
+    "recent_ticks",
+    "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",
+    "substitute_env_placeholders",
+    "symbol_info",
+    "symbol_info_tick",
+    "symbols",
+    "terminal_info",
+    "update_history",
+    "update_history_with_config",
+    "update_sltp_for_open_positions",
+})
+
+__all__ = ["STABLE_SDK_EXPORTS"]

mt5cli/history.py

@@ -7,7 +7,7 @@ import sqlite3
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from pathlib import Path
-from typing import TYPE_CHECKING, Literal, cast
+from typing import TYPE_CHECKING, Literal, cast, overload
 
 import pandas as pd
 from pdmt5 import get_timeframe_name as _get_timeframe_name
@@ -142,6 +142,26 @@ def build_rate_view_name(
     return f"rate_{symbol}__{granularity}_{timeframe}"
 
 
+def resolve_rate_table_name(symbol: str, granularity: str) -> str:
+    """Return the canonical normalized SQLite rate table name.
+
+    The normalized history table stores all symbols and timeframes in
+    ``rates``; use :func:`resolve_rate_view_name` for per-symbol compatibility
+    view names.
+
+    Returns:
+        Canonical normalized rates table name.
+
+    Raises:
+        ValueError: If ``symbol`` or ``granularity`` is invalid.
+    """
+    parse_timeframe(granularity)
+    if not symbol.strip():
+        msg = "symbol must not be empty."
+        raise ValueError(msg)
+    return Dataset.rates.table_name
+
+
 SqliteConnOrPath = sqlite3.Connection | Path | str
 
 
@@ -653,34 +673,76 @@ def resolve_rate_tables(
             conn.close()
 
 
+if TYPE_CHECKING:
+
+    @overload
+    def load_rate_series_from_sqlite(
+        conn_or_path: SqliteConnOrPath,
+        targets: None = None,
+        count: int | None = None,
+        explicit_tables: None = None,
+        *,
+        table: str,
+    ) -> pd.DataFrame: ...
+
+    @overload
+    def load_rate_series_from_sqlite(
+        conn_or_path: SqliteConnOrPath,
+        targets: None = None,
+        count: int | None = None,
+        explicit_tables: Sequence[str] | None = None,
+        *,
+        table: None = None,
+    ) -> dict[tuple[str | None, int], pd.DataFrame]: ...
+
+    @overload
+    def load_rate_series_from_sqlite(
+        conn_or_path: SqliteConnOrPath,
+        targets: Sequence[RateTarget],
+        count: int,
+        explicit_tables: Sequence[str] | None = None,
+        *,
+        table: None = None,
+    ) -> dict[tuple[str | None, int], pd.DataFrame]: ...
+
+
 def load_rate_series_from_sqlite(
     conn_or_path: SqliteConnOrPath,
-    targets: Sequence[RateTarget],
-    count: int,
+    targets: Sequence[RateTarget] | None = None,
+    count: int | None = None,
     explicit_tables: Sequence[str] | None = None,
-) -> dict[tuple[str | None, int], pd.DataFrame]:
-    """Load multiple rate series from a SQLite database.
+    *,
+    table: str | None = None,
+) -> dict[tuple[str | None, int], pd.DataFrame] | pd.DataFrame:
+    """Load one table/view or multiple rate series from a SQLite database.
 
     Args:
         conn_or_path: SQLite database path or open connection.
-        targets: Rate targets to load. Each ``(symbol, timeframe_int)`` pair
-            must be unique.
-        count: Number of most recent rows to load per series.
+        targets: Rate targets to load. Each ``(symbol, timeframe_int)`` pair must
+            be unique. Omit when loading a single explicit ``table``.
+        count: Optional number of most recent rows to load per series.
         explicit_tables: Optional explicit table or view names matching targets.
             When omitted, managed ``rate_*`` compatibility views must already
             exist in the database.
+        table: Optional single table or view name to load directly.
 
     Returns:
-        Mapping keyed by ``(symbol, timeframe_int)`` to each rate DataFrame.
+        A DataFrame when ``table`` is provided, otherwise a mapping keyed by
+        ``(symbol, timeframe_int)`` to each rate DataFrame.
 
     Raises:
         ValueError: If ``count`` is not positive, targets are empty, duplicate
             ``(symbol, timeframe_int)`` pairs are present, or table resolution
             fails.
     """
-    if count <= 0:
+    if table is not None:
+        return load_rate_data(conn_or_path, table, count=count)
+    if count is None or count <= 0:
         msg = "count must be positive."
         raise ValueError(msg)
+    if targets is None:
+        msg = "targets are required when table is not provided."
+        raise ValueError(msg)
     target_list = list(targets)
     if not target_list:
         msg = "At least one rate target is required."

mt5cli/sdk.py

@@ -37,6 +37,7 @@ from .utils import (
     parse_tick_flags,
     parse_timeframe,
 )
+from .utils import coerce_login as _coerce_login
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator, Sequence
@@ -122,6 +123,7 @@ __all__ = [
     "copy_rates_range",
     "copy_ticks_from",
     "copy_ticks_range",
+    "fetch_latest_closed_rates",
     "history_deals",
     "history_orders",
     "last_error",
@@ -1289,6 +1291,33 @@ def latest_rates(
     )
 
 
+def fetch_latest_closed_rates(
+    client: Mt5CliClient,
+    *,
+    symbol: str,
+    granularity: str,
+    count: int,
+) -> pd.DataFrame:
+    """Fetch up to ``count`` most recent closed bars, oldest to newest.
+
+    Returns:
+        Closed rate bars ordered oldest to newest.
+
+    Raises:
+        ValueError: If ``count`` is not positive or no closed bars are returned.
+    """
+    _require_positive(count, "count")
+    frame = client.latest_rates(symbol, granularity, count + 1, start_pos=0)
+    closed = drop_forming_rate_bar(frame)
+    if closed.empty:
+        msg = (
+            f"Rate data is empty for {symbol!r} at granularity {granularity!r} "
+            f"with count {count}."
+        )
+        raise ValueError(msg)
+    return closed.tail(count).reset_index(drop=True)
+
+
 def collect_latest_rates(
     symbols: Sequence[str],
     timeframes: Sequence[int | str],
@@ -1470,20 +1499,6 @@ def resolve_account_specs(
     ]
 
 
-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 _build_account_config(
     account: AccountSpec,
     base_config: Mt5Config | None,

mt5cli/utils.py

@@ -241,6 +241,20 @@ def detect_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,

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mt5cli"
-version = "0.7.2"
+version = "0.8.1"
 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"}]

tests/test_contracts.py

@@ -2,43 +2,66 @@
 
 from __future__ import annotations
 
+import sqlite3
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, get_type_hints
+from unittest.mock import MagicMock
 
 import pandas as pd
 import pytest
 from pdmt5 import Mt5RuntimeError, Mt5TradingError
 from pytest_mock import MockerFixture  # noqa: TC002
 
+import mt5cli
 from mt5cli import (
     DEDUP_KEYS,
     REQUIRED_COLUMNS,
+    STABLE_SDK_EXPORTS,
     TIME_COLUMNS,
+    AccountSpec,
     DataKind,
     Dataset,
+    ExecutionStatus,
+    MarginVolume,
     MT5Client,
     Mt5CliError,
     Mt5ConnectionError,
     Mt5OperationError,
     Mt5SchemaError,
+    OrderExecutionResult,
+    OrderLimits,
+    RateTarget,
     build_config,
+    build_rate_targets,
+    calculate_margin_and_volume,
     call_with_normalized_errors,
     detect_format,
+    drop_forming_rate_bar,
+    ensure_symbol_selected,
     ensure_utc,
     export_dataframe,
     export_dataframe_to_sqlite,
+    fetch_latest_closed_rates,
     granularity_name,
     is_recoverable_mt5_error,
+    load_rate_data,
+    load_rate_series_from_sqlite,
     mt5_session,
+    mt5_trading_session,
     normalize_dataframe,
     normalize_mt5_exception,
     normalize_symbol,
     normalize_symbols,
     parse_date_range,
+    place_market_order,
     recent_window,
+    resolve_account_spec,
+    resolve_account_specs,
+    resolve_rate_view_name,
     schema_columns,
     validate_schema,
 )
+from mt5cli.history import create_rate_compatibility_views
 from mt5cli.retry import retry_with_backoff
 from mt5cli.schemas import ensure_utc_columns, normalize_time_columns
 
@@ -510,3 +533,162 @@ def test_storage_export_round_trip_sqlite(tmp_path: Path) -> None:
     with __import__("sqlite3").connect(output) as conn:
         count = conn.execute("SELECT COUNT(*) FROM rates").fetchone()[0]
     assert count == 1
+
+
+class TestStableSdkContract:
+    """Tests for the documented stable downstream SDK contract."""
+
+    def test_stable_exports_are_subset_of_all(self) -> None:
+        """Every stable export is also listed in the package __all__."""
+        missing = sorted(STABLE_SDK_EXPORTS - set(mt5cli.__all__))
+        assert not missing, f"STABLE_SDK_EXPORTS missing from __all__: {missing}"
+
+    @pytest.mark.parametrize("name", sorted(STABLE_SDK_EXPORTS))
+    def test_stable_exports_are_importable_from_package_root(self, name: str) -> None:
+        """Stable SDK names resolve through ``from mt5cli import ...``."""
+        assert hasattr(mt5cli, name), f"{name!r} missing from mt5cli package root"
+
+    def test_drop_forming_rate_bar_from_package_root(self) -> None:
+        """Closed-bar trimming is available from the stable package surface."""
+        frame = pd.DataFrame({"time": [1, 2, 3], "close": [1.0, 1.1, 1.2]})
+        closed = drop_forming_rate_bar(frame)
+        assert list(closed["close"]) == [1.0, 1.1]
+        assert len(closed) == 2
+
+    def test_fetch_latest_closed_rates_from_package_root(self) -> None:
+        """Single-client closed-bar helper drops the forming row."""
+        client = MagicMock()
+        client.latest_rates.return_value = pd.DataFrame(
+            {"time": [1, 2, 3], "close": [1.0, 1.1, 1.2]},
+        )
+
+        result = fetch_latest_closed_rates(
+            client,
+            symbol="EURUSD",
+            granularity="M1",
+            count=2,
+        )
+
+        client.latest_rates.assert_called_once_with("EURUSD", "M1", 3, start_pos=0)
+        assert list(result["close"]) == [1.0, 1.1]
+
+    def test_resolve_rate_view_name_from_package_root(self, tmp_path: Path) -> None:
+        """Rate view resolution is importable and honors require_existing."""
+        db_path = tmp_path / "rates.db"
+        with sqlite3.connect(db_path) as conn:
+            conn.execute(
+                "CREATE TABLE rates("
+                " symbol TEXT, timeframe INTEGER, time TEXT, close REAL)",
+            )
+            conn.execute(
+                "INSERT INTO rates(symbol, timeframe, time, close) VALUES (?, ?, ?, ?)",
+                ("EURUSD", 1, "2024-01-01T00:00:00+00:00", 1.0),
+            )
+            create_rate_compatibility_views(conn)
+
+        assert resolve_rate_view_name(db_path, "EURUSD", "M1") == "rate_EURUSD__1"
+        missing = tmp_path / "missing.db"
+        with pytest.raises(ValueError, match="SQLite database not found"):
+            resolve_rate_view_name(missing, "EURUSD", "M1", require_existing=True)
+
+    def test_load_rate_data_from_package_root(self, tmp_path: Path) -> None:
+        """SQLite rate loading normalizes timestamps through the stable API."""
+        db_path = tmp_path / "view.db"
+        with sqlite3.connect(db_path) as conn:
+            conn.execute(
+                'CREATE VIEW "rate_EURUSD__1" AS'
+                " SELECT '2024-01-01T00:00:00+00:00' AS time, 1.1 AS close",
+            )
+
+        frame = load_rate_data(db_path, "rate_EURUSD__1")
+        assert frame.index.name == "time"
+        assert abs(float(frame.iloc[0]["close"]) - 1.1) < 1e-9
+
+    def test_load_rate_series_from_sqlite_requires_managed_views(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        """Multi-series loading fails clearly when managed views are absent."""
+        db_path = tmp_path / "empty-views.db"
+        with sqlite3.connect(db_path) as conn:
+            conn.execute(
+                "CREATE TABLE rates("
+                " symbol TEXT, timeframe INTEGER, time TEXT, close REAL)",
+            )
+
+        targets = build_rate_targets(["EURUSD"], ["M1"])
+        with pytest.raises(ValueError, match="No rate compatibility view exists"):
+            load_rate_series_from_sqlite(db_path, targets, count=10)
+
+        assert targets == [RateTarget(symbol="EURUSD", timeframe=1)]
+
+    def test_resolve_account_spec_from_package_root(
+        self,
+        monkeypatch: pytest.MonkeyPatch,
+    ) -> None:
+        """Account credential resolution uses generic ${ENV_VAR} placeholders."""
+        monkeypatch.setenv("APP_MT5_LOGIN", "555")
+        monkeypatch.setenv("APP_MT5_PASSWORD", "secret")
+        account = AccountSpec(
+            symbols=["EURUSD"],
+            login="${APP_MT5_LOGIN}",
+            password="${APP_MT5_PASSWORD}",
+            server="Broker-Demo",
+        )
+
+        resolved = resolve_account_spec(account, timeout=3000)
+        assert resolved.login == "555"
+        assert resolved.password == "secret"  # noqa: S105
+        assert resolved.timeout == 3000
+
+        batch = resolve_account_specs([account], server="Override")
+        assert batch[0].server == "Override"
+
+    def test_mt5_trading_session_lifecycle_from_package_root(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """Trading session helper initializes and always shuts down."""
+        mock_client = MagicMock()
+        mocker.patch(
+            "mt5cli.trading.Mt5TradingClient",
+            return_value=mock_client,
+        )
+
+        with mt5_trading_session(login=12345, server="Broker-Demo") as client:
+            assert client is mock_client
+            mock_client.initialize_and_login_mt5.assert_called_once()
+
+        mock_client.shutdown.assert_called_once()
+
+    def test_trading_order_helpers_importable_from_package_root(self) -> None:
+        """Order planning helpers resolve through the stable package surface."""
+        assert callable(calculate_margin_and_volume)
+        assert callable(ensure_symbol_selected)
+        assert callable(place_market_order)
+        margin_hints = get_type_hints(MarginVolume)
+        limits_hints = get_type_hints(OrderLimits)
+        execution_hints = get_type_hints(OrderExecutionResult)
+        assert margin_hints["buy_volume"] is float
+        assert limits_hints["stop_loss"] == float | None
+        assert execution_hints["status"] == ExecutionStatus
+
+    def test_mt5_trading_session_shuts_down_on_exception(
+        self,
+        mocker: MockerFixture,
+    ) -> None:
+        """Trading session helper shuts down even when the body raises."""
+        mock_client = MagicMock()
+        mocker.patch(
+            "mt5cli.trading.Mt5TradingClient",
+            return_value=mock_client,
+        )
+
+        message = "strategy error"
+        with (
+            pytest.raises(RuntimeError, match=message),
+            mt5_trading_session(login=12345, server="Broker-Demo"),
+        ):
+            raise RuntimeError(message)
+
+        mock_client.shutdown.assert_called_once()

tests/test_history.py

@@ -48,6 +48,7 @@ from mt5cli.history import (
     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,
@@ -63,6 +64,15 @@ from mt5cli.utils import TIMEFRAME_MAP, Dataset, IfExists
 class TestResolveRateViewName:
     """Tests for resolve_rate_view_name and resolve_rate_view_names."""
 
+    def test_resolve_rate_table_name_returns_normalized_table(self) -> None:
+        """Test canonical normalized rates table name is stable."""
+        assert resolve_rate_table_name("EURUSD", "M1") == "rates"
+
+    def test_resolve_rate_table_name_rejects_empty_symbol(self) -> None:
+        """Test canonical rate table resolution validates symbols."""
+        with pytest.raises(ValueError, match="symbol must not be empty"):
+            resolve_rate_table_name(" ", "M1")
+
     def test_missing_database_path_does_not_create_file(self, tmp_path: Path) -> None:
         """Test resolving against a missing path does not create a database."""
         db_path = tmp_path / "missing.db"
@@ -416,6 +426,32 @@ class TestLoadRateData:
             frame = load_rate_data_from_connection(conn, "rate_view")
         assert list(frame["close"]) == [1.0]
 
+    def test_load_rate_series_from_sqlite_table_style(
+        self,
+        tmp_path: Path,
+    ) -> None:
+        """Test public table-style loader returns one rate DataFrame."""
+        db_path = tmp_path / "table-style.db"
+        with sqlite3.connect(db_path) as conn:
+            conn.execute("CREATE TABLE rates(time TEXT, close REAL)")
+            conn.executemany(
+                "INSERT INTO rates(time, close) VALUES (?, ?)",
+                [
+                    ("2024-01-01T00:00:00+00:00", 1.0),
+                    ("2024-01-01T00:01:00+00:00", 1.1),
+                ],
+            )
+
+        frame = load_rate_series_from_sqlite(db_path, table="rates", count=1)
+
+        assert isinstance(frame, pd.DataFrame)
+        assert list(frame["close"]) == [1.1]
+
+    def test_load_rate_series_from_sqlite_requires_targets_without_table(self) -> None:
+        """Test multi-series loading requires targets when table is omitted."""
+        with pytest.raises(ValueError, match="targets are required"):
+            load_rate_series_from_sqlite("unused.db", count=1)
+
     def test_loads_quoted_identifier(self, tmp_path: Path) -> None:
         """Test table names are quoted safely."""
         db_path = tmp_path / "quoted.db"

tests/test_sdk.py

@@ -37,6 +37,7 @@ from mt5cli.sdk import (
     copy_rates_range,
     copy_ticks_from,
     copy_ticks_range,
+    fetch_latest_closed_rates,
     history_deals,
     history_orders,
     last_error,
@@ -61,7 +62,7 @@ from mt5cli.sdk import (
     update_history_with_config,
     version,
 )
-from mt5cli.utils import Dataset, IfExists
+from mt5cli.utils import Dataset, IfExists, coerce_login
 
 
 class _TerminalInfo(NamedTuple):
@@ -1301,12 +1302,12 @@ class TestAccountSpec:
         expected: int | None,
     ) -> None:
         """Test login values are normalized for account configs."""
-        assert sdk._coerce_login(login) == expected  # type: ignore[reportPrivateUsage]
+        assert coerce_login(login) == expected
 
     def test_coerce_login_rejects_non_numeric_string(self) -> None:
         """Test non-numeric login strings raise ValueError."""
         with pytest.raises(ValueError, match="invalid literal"):
-            sdk._coerce_login("abc")  # type: ignore[reportPrivateUsage]
+            coerce_login("abc")
 
 
 class TestCollectLatestRatesForAccounts:
@@ -1662,6 +1663,62 @@ class TestCollectLatestClosedRatesForAccounts:
         )
 
 
+class TestFetchLatestClosedRates:
+    """Tests for fetch_latest_closed_rates."""
+
+    def test_fetches_extra_bar_and_drops_forming_row(self) -> None:
+        """Test single-symbol closed-bar helper hides the forming bar."""
+        client = MagicMock()
+        client.latest_rates.return_value = pd.DataFrame(
+            {
+                "time": [1, 2, 3],
+                "close": [1.0, 1.1, 1.2],
+            },
+        )
+
+        result = fetch_latest_closed_rates(
+            client,
+            symbol="EURUSD",
+            granularity="M1",
+            count=2,
+        )
+
+        client.latest_rates.assert_called_once_with(
+            "EURUSD",
+            "M1",
+            3,
+            start_pos=0,
+        )
+        assert list(result["close"]) == [1.0, 1.1]
+
+    def test_raises_when_no_closed_bars_are_available(self) -> None:
+        """Test empty closed-bar results raise an actionable ValueError."""
+        client = MagicMock()
+        client.latest_rates.return_value = pd.DataFrame({"close": [1.0]})
+
+        with pytest.raises(ValueError, match="Rate data is empty"):
+            fetch_latest_closed_rates(
+                client,
+                symbol="EURUSD",
+                granularity="M1",
+                count=1,
+            )
+
+    def test_rejects_non_positive_count_before_fetching(self) -> None:
+        """Test invalid count values fail before calling MT5."""
+        client = MagicMock()
+
+        with pytest.raises(ValueError, match="count must be positive"):
+            fetch_latest_closed_rates(
+                client,
+                symbol="EURUSD",
+                granularity="M1",
+                count=0,
+            )
+
+        client.latest_rates.assert_not_called()
+
+
 class TestCollectLatestClosedRatesByGranularity:
     """Tests for collect_latest_closed_rates_by_granularity."""
 

uv.lock

@@ -487,7 +487,7 @@ wheels = [
 
 [[package]]
 name = "mt5cli"
-version = "0.7.2"
+version = "0.8.1"
 source = { editable = "." }
 dependencies = [
     { name = "click" },