mt5cli 1.0.3__tar.gz → 1.1.1__tar.gz

{mt5cli-1.0.3 → mt5cli-1.1.1}/.agents/skills/local-qa/scripts/qa.sh

@@ -10,7 +10,7 @@ uv run pyright .
 uv run pytest
 
 # Markdown
-npx -y prettier --write './**/*.md'
+npx -y prettier --write './**/*.{md,json}'
 
 # GitHub Actions
 case "${OSTYPE}" in

{mt5cli-1.0.3 → mt5cli-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mt5cli
-Version: 1.0.3
+Version: 1.1.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>
@@ -19,6 +19,10 @@ Requires-Python: <3.14,>=3.11
 Requires-Dist: click>=8.1.0
 Requires-Dist: pdmt5>=1.0.0
 Requires-Dist: typer>=0.15.0
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http; extra == 'otel'
+Requires-Dist: opentelemetry-sdk; extra == 'otel'
 Provides-Extra: parquet
 Requires-Dist: pyarrow>=19.0.0; extra == 'parquet'
 Description-Content-Type: text/markdown
@@ -210,6 +214,8 @@ python -m mt5cli -o account.csv account-info
 | `order-send`           | Send a raw trade request to the trade server (`--yes` required; expert path)                                                                |
 | `close-positions`      | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` available)                                         |
 | `collect-history`      | Collect rates, history-orders, and history-deals for one or more symbols into a single SQLite database (ticks opt-in via `--dataset ticks`) |
+| `grafana-schema`       | Create or refresh Grafana-ready views and indexes in an existing SQLite database (idempotent, no MT5 connection)                            |
+| `snapshot`             | Snapshot current account, position, order, and terminal state into SQLite for live Grafana dashboards                                       |
 
 Use `order-check` to validate a request payload before running `order-send --yes`.
 `close-positions` is the safer high-level alternative that builds correct close
@@ -229,6 +235,104 @@ mt5cli -o history.db collect-history \
 
 History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The `cash_events` view is derived from symbol-filtered `history_deals`, so account-level cash events with empty or non-matching symbols may be excluded. The `rates` table records the requested `timeframe` so appended runs at different timeframes remain distinguishable. The `positions_reconstructed` view aggregates trade deals by `position_id`, excludes positions without closing-side entries, and uses volume-weighted open/close prices; reversal deals (`DEAL_ENTRY_INOUT`) are reported via `volume_reversal` / `reversal_count` columns.
 
+### Grafana-ready SQLite dashboards
+
+mt5cli can prepare a SQLite database for use as a Grafana datasource (via the [SQLite plugin](https://grafana.com/grafana/plugins/frser-sqlite-datasource/) or similar). Most `grafana_*` views expose an integer epoch-second `time` column for use in Grafana time-series panels. Two views (`grafana_realized_pnl`, `grafana_trade_stats`) are static symbol-level summaries with no `time` column — use them in table or stat panels.
+
+#### Prepare the schema (idempotent, no MT5 connection needed)
+
+```bash
+mt5cli -o history.db grafana-schema
+```
+
+This creates snapshot tables (`account_snapshots`, `position_snapshots`, `order_snapshots`, `terminal_snapshots`, `snapshot_runs`) and all `grafana_*` views and indexes in the SQLite database. Safe to run repeatedly — all operations are idempotent.
+
+#### Snapshot current account state
+
+```bash
+mt5cli -o history.db snapshot \
+  --symbol JP225 --symbol HK50 --symbol NL25 \
+  --with-account --with-positions --with-orders --with-terminal \
+  --with-grafana-schema
+```
+
+Appends one timestamped row per data type. Never places orders or modifies trading state. Run periodically (e.g. from a cron job or a loop) to build a time-series account history.
+
+#### SDK usage
+
+```python
+from pdmt5 import Mt5DataClient, Mt5Config
+from mt5cli import update_observability, update_observability_with_config
+
+# Reuse an already-connected client
+client = Mt5DataClient(config=Mt5Config(login=12345))
+client.initialize_and_login_mt5()
+try:
+    update_observability(
+        client=client,
+        output="history.db",
+        symbols=["EURUSD", "GBPUSD"],  # optional position/order filter
+        include_account=True,
+        include_positions=True,
+        include_orders=True,
+        include_terminal=True,
+        with_grafana_schema=True,
+    )
+finally:
+    client.shutdown()
+
+# Standalone wrapper that opens/closes MT5 automatically
+update_observability_with_config(
+    output="history.db",
+    config=Mt5Config(login=12345),
+)
+```
+
+#### Available Grafana views
+
+**Time-series views** (integer epoch-second `time` column; snapshot views also expose `run_id`):
+
+| View                         | Source               | Description                                                |
+| ---------------------------- | -------------------- | ---------------------------------------------------------- |
+| `grafana_rates`              | `rates`              | OHLCV bars with integer epoch `time`                       |
+| `grafana_ticks`              | `ticks`              | Tick data with integer epoch `time`                        |
+| `grafana_history_deals`      | `history_deals`      | All deals with epoch `time`                                |
+| `grafana_history_orders`     | `history_orders`     | All historical orders; adds epoch `time` from `time_setup` |
+| `grafana_trade_deals`        | `history_deals`      | Trade deals only (`type IN (0,1)`)                         |
+| `grafana_cash_events`        | `history_deals`      | Non-trade deals (deposits, dividends, etc.)                |
+| `grafana_symbol_pnl`         | `history_deals`      | Per-close-deal profit/loss per symbol                      |
+| `grafana_account_snapshots`  | `account_snapshots`  | Account balance/equity/margin time series                  |
+| `grafana_position_snapshots` | `position_snapshots` | Open position snapshots over time                          |
+| `grafana_order_snapshots`    | `order_snapshots`    | Active order snapshots over time                           |
+| `grafana_terminal_snapshots` | `terminal_snapshots` | Terminal connectivity snapshots                            |
+
+**Static summary views** (no `time` column; use in table or stat panels, not time-series):
+
+| View                   | Source          | Description                           |
+| ---------------------- | --------------- | ------------------------------------- |
+| `grafana_realized_pnl` | `history_deals` | Cumulative realized PnL per symbol    |
+| `grafana_trade_stats`  | `history_deals` | Win/loss counts and profit per symbol |
+
+#### Example Grafana queries
+
+```sql
+-- Equity curve over time
+SELECT time, equity FROM grafana_account_snapshots ORDER BY time;
+
+-- Rolling balance by account login
+SELECT time, login, balance FROM grafana_account_snapshots
+WHERE login = $login ORDER BY time;
+
+-- Open positions at latest successful snapshot
+SELECT symbol, volume, profit FROM grafana_position_snapshots
+WHERE run_id = (SELECT MAX(run_id) FROM snapshot_runs WHERE status = 'ok');
+
+-- Realized PnL by symbol
+SELECT symbol, total_profit FROM grafana_trade_stats ORDER BY total_profit DESC;
+```
+
+> **Note**: OpenTelemetry integration is intentionally not part of this release and is tracked separately.
+
 ### Incremental history SDK
 
 For automated pipelines, use the importable incremental API instead of re-fetching fixed date ranges:

{mt5cli-1.0.3 → mt5cli-1.1.1}/README.md

@@ -185,6 +185,8 @@ python -m mt5cli -o account.csv account-info
 | `order-send`           | Send a raw trade request to the trade server (`--yes` required; expert path)                                                                |
 | `close-positions`      | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` available)                                         |
 | `collect-history`      | Collect rates, history-orders, and history-deals for one or more symbols into a single SQLite database (ticks opt-in via `--dataset ticks`) |
+| `grafana-schema`       | Create or refresh Grafana-ready views and indexes in an existing SQLite database (idempotent, no MT5 connection)                            |
+| `snapshot`             | Snapshot current account, position, order, and terminal state into SQLite for live Grafana dashboards                                       |
 
 Use `order-check` to validate a request payload before running `order-send --yes`.
 `close-positions` is the safer high-level alternative that builds correct close
@@ -204,6 +206,104 @@ mt5cli -o history.db collect-history \
 
 History orders and deals are fetched per symbol and concatenated, so the symbol filter is applied consistently across all datasets. The `cash_events` view is derived from symbol-filtered `history_deals`, so account-level cash events with empty or non-matching symbols may be excluded. The `rates` table records the requested `timeframe` so appended runs at different timeframes remain distinguishable. The `positions_reconstructed` view aggregates trade deals by `position_id`, excludes positions without closing-side entries, and uses volume-weighted open/close prices; reversal deals (`DEAL_ENTRY_INOUT`) are reported via `volume_reversal` / `reversal_count` columns.
 
+### Grafana-ready SQLite dashboards
+
+mt5cli can prepare a SQLite database for use as a Grafana datasource (via the [SQLite plugin](https://grafana.com/grafana/plugins/frser-sqlite-datasource/) or similar). Most `grafana_*` views expose an integer epoch-second `time` column for use in Grafana time-series panels. Two views (`grafana_realized_pnl`, `grafana_trade_stats`) are static symbol-level summaries with no `time` column — use them in table or stat panels.
+
+#### Prepare the schema (idempotent, no MT5 connection needed)
+
+```bash
+mt5cli -o history.db grafana-schema
+```
+
+This creates snapshot tables (`account_snapshots`, `position_snapshots`, `order_snapshots`, `terminal_snapshots`, `snapshot_runs`) and all `grafana_*` views and indexes in the SQLite database. Safe to run repeatedly — all operations are idempotent.
+
+#### Snapshot current account state
+
+```bash
+mt5cli -o history.db snapshot \
+  --symbol JP225 --symbol HK50 --symbol NL25 \
+  --with-account --with-positions --with-orders --with-terminal \
+  --with-grafana-schema
+```
+
+Appends one timestamped row per data type. Never places orders or modifies trading state. Run periodically (e.g. from a cron job or a loop) to build a time-series account history.
+
+#### SDK usage
+
+```python
+from pdmt5 import Mt5DataClient, Mt5Config
+from mt5cli import update_observability, update_observability_with_config
+
+# Reuse an already-connected client
+client = Mt5DataClient(config=Mt5Config(login=12345))
+client.initialize_and_login_mt5()
+try:
+    update_observability(
+        client=client,
+        output="history.db",
+        symbols=["EURUSD", "GBPUSD"],  # optional position/order filter
+        include_account=True,
+        include_positions=True,
+        include_orders=True,
+        include_terminal=True,
+        with_grafana_schema=True,
+    )
+finally:
+    client.shutdown()
+
+# Standalone wrapper that opens/closes MT5 automatically
+update_observability_with_config(
+    output="history.db",
+    config=Mt5Config(login=12345),
+)
+```
+
+#### Available Grafana views
+
+**Time-series views** (integer epoch-second `time` column; snapshot views also expose `run_id`):
+
+| View                         | Source               | Description                                                |
+| ---------------------------- | -------------------- | ---------------------------------------------------------- |
+| `grafana_rates`              | `rates`              | OHLCV bars with integer epoch `time`                       |
+| `grafana_ticks`              | `ticks`              | Tick data with integer epoch `time`                        |
+| `grafana_history_deals`      | `history_deals`      | All deals with epoch `time`                                |
+| `grafana_history_orders`     | `history_orders`     | All historical orders; adds epoch `time` from `time_setup` |
+| `grafana_trade_deals`        | `history_deals`      | Trade deals only (`type IN (0,1)`)                         |
+| `grafana_cash_events`        | `history_deals`      | Non-trade deals (deposits, dividends, etc.)                |
+| `grafana_symbol_pnl`         | `history_deals`      | Per-close-deal profit/loss per symbol                      |
+| `grafana_account_snapshots`  | `account_snapshots`  | Account balance/equity/margin time series                  |
+| `grafana_position_snapshots` | `position_snapshots` | Open position snapshots over time                          |
+| `grafana_order_snapshots`    | `order_snapshots`    | Active order snapshots over time                           |
+| `grafana_terminal_snapshots` | `terminal_snapshots` | Terminal connectivity snapshots                            |
+
+**Static summary views** (no `time` column; use in table or stat panels, not time-series):
+
+| View                   | Source          | Description                           |
+| ---------------------- | --------------- | ------------------------------------- |
+| `grafana_realized_pnl` | `history_deals` | Cumulative realized PnL per symbol    |
+| `grafana_trade_stats`  | `history_deals` | Win/loss counts and profit per symbol |
+
+#### Example Grafana queries
+
+```sql
+-- Equity curve over time
+SELECT time, equity FROM grafana_account_snapshots ORDER BY time;
+
+-- Rolling balance by account login
+SELECT time, login, balance FROM grafana_account_snapshots
+WHERE login = $login ORDER BY time;
+
+-- Open positions at latest successful snapshot
+SELECT symbol, volume, profit FROM grafana_position_snapshots
+WHERE run_id = (SELECT MAX(run_id) FROM snapshot_runs WHERE status = 'ok');
+
+-- Realized PnL by symbol
+SELECT symbol, total_profit FROM grafana_trade_stats ORDER BY total_profit DESC;
+```
+
+> **Note**: OpenTelemetry integration is intentionally not part of this release and is tracked separately.
+
 ### Incremental history SDK
 
 For automated pipelines, use the importable incremental API instead of re-fetching fixed date ranges:

{mt5cli-1.0.3 → mt5cli-1.1.1}/docs/api/public-contract.md

@@ -45,7 +45,7 @@ These names are exported from `mt5cli` and enumerated in
 | `MT5Client`                                     | Read-only data client with optional `order_check` / `order_send`                                                                                                                                                                                                                  |
 | `build_config`                                  | Build `pdmt5.Mt5Config` from connection fields; `login` accepts `int \| str \| None` — numeric strings are coerced to `int`, blank strings are treated as unset, and `${ENV_VAR}` / `$ENV_NAME` placeholders in string parameters are expanded when `allow_whole_dollar_env=True` |
 | `mt5_session`                                   | Context manager: initialize, login, yield client, shutdown                                                                                                                                                                                                                        |
-| `create_trading_client`, `mt5_trading_session`  | Trading-capable MT5 client lifecycle; returns a client supporting order execution and account management                                                                                                                                                                          |
+| `create_trading_client`, `mt5_trading_session`  | Trading-capable MT5 client lifecycle; returns a raw `pdmt5.Mt5DataClient` (not `MT5Client`) supporting order execution, account management, and history deal retrieval                                                                                                            |
 | `AccountSpec`                                   | Generic account group: symbols plus optional credentials                                                                                                                                                                                                                          |
 | `resolve_account_spec`, `resolve_account_specs` | Merge overrides and expand `${ENV_VAR}` placeholders; opt-in `allow_whole_dollar_env` for bare `$NAME`                                                                                                                                                                            |
 
@@ -99,6 +99,7 @@ strategy entries, exits, Kelly sizing, or signal logic.
 | `determine_order_limits`                                                                                                       | SL/TP price levels from ratios                                    |
 | `calculate_trailing_stop_updates`                                                                                              | Per-ticket generic trailing stop-loss update plan                 |
 | `ensure_symbol_selected`                                                                                                       | Select/verify Market Watch visibility                             |
+| `fetch_recent_history_deals_for_trading_client`                                                                                | Recent deal history from a connected trading client               |
 | `place_market_order`, `close_open_positions`, `update_sltp_for_open_positions`, `update_trailing_stop_loss_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                                     |
@@ -124,6 +125,63 @@ 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()`.
 
+### Grafana observability (SQLite read model)
+
+These helpers prepare a SQLite database as a Grafana datasource. All DDL is
+idempotent (`CREATE TABLE IF NOT EXISTS`, `DROP VIEW IF EXISTS` + `CREATE
+VIEW`, `CREATE INDEX IF NOT EXISTS`). Missing source tables are skipped with a
+warning rather than raising an error.
+
+| Symbol                             | Role                                                                                            |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `update_observability`             | Append one timestamped snapshot row per data type; accepts an already-connected `Mt5DataClient` |
+| `update_observability_with_config` | Standalone wrapper: opens/closes MT5 connection automatically around `update_observability`     |
+
+Both functions write to the SQLite path given by `output=`. The optional
+`symbols` parameter filters `positions_get` / `orders_get` by symbol.
+`with_grafana_schema=False` (default) skips Grafana view/index setup; run
+`grafana-schema` once to set up the schema, then call `snapshot` repeatedly
+without this flag.
+
+**Snapshot tables** (created by `create_snapshot_tables` in `mt5cli.grafana`):
+
+| Table                | Content                                   |
+| -------------------- | ----------------------------------------- |
+| `account_snapshots`  | Balance, equity, margin, free-margin, P&L |
+| `position_snapshots` | Open positions: symbol, volume, profit, … |
+| `order_snapshots`    | Active orders: symbol, type, price, …     |
+| `terminal_snapshots` | Terminal connectivity and build info      |
+| `snapshot_runs`      | Per-run status (`ok` / `error`) timestamp |
+
+**Grafana time-series views** (integer epoch-second `time` column; snapshot views also expose `run_id`):
+
+| View                         | Source                           |
+| ---------------------------- | -------------------------------- |
+| `grafana_rates`              | `rates` table                    |
+| `grafana_ticks`              | `ticks` table                    |
+| `grafana_history_deals`      | `history_deals`                  |
+| `grafana_history_orders`     | `history_orders`                 |
+| `grafana_trade_deals`        | `history_deals` trade types only |
+| `grafana_cash_events`        | `history_deals` non-trade events |
+| `grafana_symbol_pnl`         | Per-close-deal P&L per symbol    |
+| `grafana_account_snapshots`  | `account_snapshots`              |
+| `grafana_position_snapshots` | `position_snapshots`             |
+| `grafana_order_snapshots`    | `order_snapshots`                |
+| `grafana_terminal_snapshots` | `terminal_snapshots`             |
+
+**Grafana static summary views** (no `time` column; use for table/stat panels, not time-series):
+
+| View                   | Source                                |
+| ---------------------- | ------------------------------------- |
+| `grafana_realized_pnl` | Cumulative realized PnL per symbol    |
+| `grafana_trade_stats`  | Win/loss counts and profit per symbol |
+
+Lower-level helpers (`ensure_grafana_schema`, `create_grafana_views`,
+`create_grafana_indexes`, `create_snapshot_tables`, `start_snapshot_run`,
+`insert_account_snapshot`, `insert_position_snapshots`, `insert_order_snapshots`,
+`insert_terminal_snapshot`, `record_snapshot_run`) are available directly from
+`mt5cli.grafana` and are not part of the package-root stable surface.
+
 ### Errors
 
 | Symbol                                                                     | Role                          |
@@ -135,14 +193,15 @@ and returned as `status="failed"` with normalized `request` / `response` details
 Lower-level helpers are available from their owning modules and are not part
 of the package-root stable surface. Import them directly when needed:
 
-| Module              | Examples                                                                                       |
-| ------------------- | ---------------------------------------------------------------------------------------------- |
-| `mt5cli.history`    | `resolve_rate_view_name`, `resolve_rate_tables`, `load_rate_data`, `build_rate_view_name`      |
-| `mt5cli.sdk`        | `copy_rates_from`, `copy_ticks_from`, `account_info`, `symbols`, `mt5_summary`, `latest_rates` |
-| `mt5cli.schemas`    | `DataKind`, `normalize_dataframe`, `validate_schema`, `DEDUP_KEYS`                             |
-| `mt5cli.utils`      | `Dataset`, `IfExists`, `detect_format`, `export_dataframe`, `export_dataframe_to_sqlite`       |
-| `mt5cli.converters` | `normalize_symbol`, `ensure_utc`, `parse_date_range`, `granularity_name`                       |
-| `mt5cli.exceptions` | `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error`           |
+| Module              | Examples                                                                                                                                                                    |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mt5cli.grafana`    | `ensure_grafana_schema`, `create_grafana_views`, `create_grafana_indexes`, `create_snapshot_tables`, `start_snapshot_run`, `insert_account_snapshot`, `record_snapshot_run` |
+| `mt5cli.history`    | `resolve_rate_view_name`, `resolve_rate_tables`, `load_rate_data`, `build_rate_view_name`                                                                                   |
+| `mt5cli.sdk`        | `copy_rates_from`, `copy_ticks_from`, `account_info`, `symbols`, `mt5_summary`, `latest_rates`                                                                              |
+| `mt5cli.schemas`    | `DataKind`, `normalize_dataframe`, `validate_schema`, `DEDUP_KEYS`                                                                                                          |
+| `mt5cli.utils`      | `Dataset`, `IfExists`, `detect_format`, `export_dataframe`, `export_dataframe_to_sqlite`                                                                                    |
+| `mt5cli.converters` | `normalize_symbol`, `ensure_utc`, `parse_date_range`, `granularity_name`                                                                                                    |
+| `mt5cli.exceptions` | `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error`                                                                                        |
 
 ## CLI commands
 
@@ -155,6 +214,15 @@ The Typer application in `mt5cli.cli` exposes file-export commands documented in
 - Delegate to the same Python APIs described here; they are not duplicated
   business logic.
 
+`grafana-schema` initializes Grafana views, indexes, and snapshot tables in the
+target SQLite database without connecting to MT5. It is idempotent and safe to
+run repeatedly.
+
+`snapshot` appends one timestamped row per enabled data type
+(`--with-account`, `--with-positions`, `--with-orders`, `--with-terminal`) and
+never places orders or modifies trading state. Both commands require
+`-o/--output` to point at a `.db` / SQLite file.
+
 `order-send` is the expert raw-request path; it requires `--yes` and a fully
 constructed request payload. `close-positions` is the safer high-level helper
 that closes open positions by `--symbol` or `--ticket` using
@@ -187,6 +255,9 @@ The following belong in consuming applications, not in mt5cli:
 - 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
+- Entry-deal classification, Kelly fractions, or betting-specific deal transformations
+  (use `fetch_recent_history_deals_for_trading_client` to retrieve raw deal data, then
+  apply downstream transformations in your own adapter layer)
 - Application-specific credential schema keys wired into mt5cli internals
 
 mt5cli provides connection lifecycle, normalized data access, SQLite history

{mt5cli-1.0.3 → mt5cli-1.1.1}/docs/api/trading.md

@@ -10,6 +10,11 @@ client supporting order execution and account management, use `Mt5Config.path`
 to launch the terminal when configured, and `mt5_trading_session()` always
 calls `shutdown()` on exit.
 
+`create_trading_client()` returns a raw `pdmt5.Mt5DataClient` instance, not the
+higher-level `MT5Client` wrapper. Use `mt5_session()` / `MT5Client` for
+read-only data collection; use `mt5_trading_session()` only where order
+placement or trading calculations are required.
+
 ```python
 from mt5cli import create_trading_client, mt5_trading_session
 
@@ -182,6 +187,55 @@ updates: list[OrderExecutionResult] = update_sltp_for_open_positions(
 Closes issue #33: strategy-neutral order planning and execution helpers exposed
 through the stable package root without embedding entry/exit policy.
 
+## Retrieving recent history deals
+
+`fetch_recent_history_deals_for_trading_client()` fetches history deals from an
+already-connected trading client over a trailing time window. It works directly
+with the object returned by `create_trading_client()` (a raw
+`pdmt5.Mt5DataClient`) without requiring any additional wrapping.
+
+The helper returns a chronologically sorted DataFrame with a `RangeIndex` and
+all columns from the underlying client (`time`, `symbol`, `type`, `entry`,
+`volume`, `profit`, `position_id`, etc.). It does **not** apply any
+strategy-specific transformations — entry/exit classification, Kelly fractions,
+and betting semantics belong in downstream applications.
+
+```python
+from mt5cli import (
+    create_trading_client,
+    fetch_recent_history_deals_for_trading_client,
+)
+
+client = create_trading_client(login=12345, server="Broker-Demo")
+try:
+    deals_df = fetch_recent_history_deals_for_trading_client(
+        client,
+        symbol="JP225",
+        hours=24,
+    )
+finally:
+    client.shutdown()
+```
+
+Or inside a managed session:
+
+```python
+from mt5cli import fetch_recent_history_deals_for_trading_client, mt5_trading_session
+
+with mt5_trading_session(login=12345, server="Broker-Demo") as client:
+    deals_df = fetch_recent_history_deals_for_trading_client(
+        client,
+        symbol="JP225",
+        hours=48,
+    )
+```
+
+`hours` must be positive; `date_to` defaults to `datetime.now(UTC)`. An empty
+or `None` result from the underlying client is normalized to an empty DataFrame.
+
+Downstream packages own all strategy-specific transformations. mt5cli does not
+provide entry-deal classification, Kelly sizing, or any betting-specific helpers.
+
 ## Migration from application-local helpers
 
 | Application-local concern                                | mt5cli replacement                                                                      |
@@ -192,6 +246,7 @@ through the stable package root without embedding entry/exit policy.
 | Local broker volume step normalization                   | `normalize_order_volume()`                                                              |
 | Local order or position margin estimation                | `estimate_order_margin()`, `calculate_positions_margin()`                               |
 | Local closed-bar fetch from a trading session            | `fetch_latest_closed_rates_for_trading_client()`, `fetch_latest_closed_rates_indexed()` |
+| Local recent deal history fetch from a trading session   | `fetch_recent_history_deals_for_trading_client()`                                       |
 | Local SL/TP price derivation                             | `determine_order_limits()`                                                              |
 | Throttled SQLite history loop with ad-hoc error handling | `ThrottledHistoryUpdater(suppress_errors=True)`                                         |
 

mt5cli-1.1.1/examples/grafana/README.md

@@ -0,0 +1,95 @@
+# Grafana Integration for mt5cli
+
+This directory contains example configuration and dashboard files for visualising
+mt5cli SQLite data in [Grafana](https://grafana.com/) using the
+[Grafana SQLite datasource plugin](https://grafana.com/grafana/plugins/frser-sqlite-datasource/).
+
+## Prerequisites
+
+- mt5cli installed and able to connect to MetaTrader 5
+- Grafana 10+ with the `frser-sqlite-datasource` plugin installed
+- (Optional) Docker and Docker Compose for the containerised setup
+
+## Generating the SQLite database
+
+Collect historical data and snapshot current account state:
+
+```sh
+# Collect OHLCV history
+mt5cli -o history.db collect-history --symbol EURUSD --date-from 2024-01-01 --date-to 2024-12-31
+
+# Create Grafana-ready views and indexes
+mt5cli -o history.db grafana-schema
+
+# Snapshot current account, positions, and orders
+mt5cli -o history.db snapshot --with-grafana-schema
+```
+
+## Publishing a Grafana-readable copy
+
+Grafana reads the SQLite file directly. To avoid read/write conflicts, publish
+a consistent copy after each update:
+
+```sh
+mt5cli -o history.db grafana-schema --publish-copy history.mt5cli.db
+mt5cli -o history.db snapshot --publish-copy history.mt5cli.db
+```
+
+The `--publish-copy` option uses the SQLite online backup API, which is safe
+even when the source database uses WAL journal mode.
+
+## Configuring the datasource path
+
+Edit `provisioning/datasources/mt5cli-sqlite.yml` and set the `path` field
+to the absolute path of your published `.db` file:
+
+```yaml
+jsonData:
+  path: /absolute/path/to/history.mt5cli.db
+```
+
+## Running Grafana on Windows (native)
+
+1. Download and install Grafana from <https://grafana.com/grafana/download/>.
+2. Install the SQLite plugin: `grafana-cli plugins install frser-sqlite-datasource`.
+3. Copy `provisioning/datasources/mt5cli-sqlite.yml` into
+   `%ProgramFiles%\GrafanaLabs\grafana\conf\provisioning\datasources\`.
+   Do not copy `provisioning/dashboards/mt5cli.yml` — it contains a
+   Docker-specific dashboard path that is not valid on Windows.
+4. Import the dashboards from `dashboards/` via the Grafana UI
+   (Dashboards → Import → Upload JSON file).
+
+## Running with Docker Compose
+
+Set `MT5CLI_DB_PATH` to the absolute path of your published `.db` file, then
+start the stack:
+
+```sh
+# From the examples/grafana directory
+MT5CLI_DB_PATH=/absolute/path/to/history.mt5cli.db docker compose up -d
+```
+
+Alternatively, create a `.env` file in `examples/grafana/` containing
+`MT5CLI_DB_PATH=/absolute/path/to/history.mt5cli.db` and run
+`docker compose up -d`. Compose refuses to start if the variable is unset or
+empty.
+
+Then open <http://localhost:3000> (default credentials: admin / admin).
+
+## Dashboard overview
+
+| Dashboard              | Description                                             |
+| ---------------------- | ------------------------------------------------------- |
+| `mt5cli-overview.json` | Account balance, equity, margin, and snapshot freshness |
+| `mt5cli-trades.json`   | Trade P/L, win rate, symbol breakdown                   |
+| `mt5cli-market.json`   | OHLCV rates, spreads, and tick volume                   |
+
+All panel queries use the `grafana_*` views; they do not read internal storage
+tables directly.
+
+## Importing dashboards
+
+1. Open Grafana and navigate to **Dashboards → Import**.
+2. Click **Upload JSON file** and select one of the files in `dashboards/`.
+3. Select the `mt5cli-SQLite` datasource when prompted.
+4. Click **Import**.

mt5cli-1.1.1/examples/grafana/compose.yml

@@ -0,0 +1,26 @@
+# Docker Compose for Grafana with mt5cli SQLite datasource.
+#
+# MT5CLI_DB_PATH must be set to the absolute host path of your published .db
+# file before running `docker compose up -d`. Compose will refuse to start if
+# the variable is missing or empty.
+#
+# Example:
+#   MT5CLI_DB_PATH=/home/user/history.mt5cli.db docker compose up -d
+
+services:
+  grafana:
+    image: grafana/grafana:latest
+    ports:
+      - "3000:3000"
+    environment:
+      GF_PATHS_PROVISIONING: /etc/grafana/provisioning
+      GF_INSTALL_PLUGINS: frser-sqlite-datasource
+    volumes:
+      - ./provisioning:/etc/grafana/provisioning:ro
+      - ./dashboards:/var/lib/grafana/dashboards:ro
+      - grafana-storage:/var/lib/grafana
+      - ${MT5CLI_DB_PATH:?Set MT5CLI_DB_PATH to the path of your published mt5cli SQLite DB}:/data/mt5cli.db:ro
+    user: "472"
+
+volumes:
+  grafana-storage: