mt5cli 1.6.0__tar.gz → 1.7.0__tar.gz

{mt5cli-1.6.0 → mt5cli-1.7.0}/.github/workflows/claude.yml

@@ -34,7 +34,7 @@ jobs:
       issues: write
       id-token: write
       actions: read
-    uses: dceoy/gha-for-devops/.github/workflows/claude-code-review.yml@main  # zizmor: ignore[unpinned-uses]
+    uses: dceoy/pr-loop/.github/workflows/claude-code-review.yml@main  # zizmor: ignore[unpinned-uses]
     secrets:
       CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}  # zizmor: ignore[secrets-outside-env]
       GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{mt5cli-1.6.0 → mt5cli-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mt5cli
-Version: 1.6.0
+Version: 1.7.0
 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>
@@ -212,8 +212,8 @@ python -m mt5cli -o account.csv account-info
 | `close-positions`      | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` available; optional `--filling-mode` / `--deviation` / `--comment` / `--magic`) |
 | `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`)                              |
 | `history-gaps`         | Export a SQLite-only one-row-per-gap report from managed rate compatibility views without connecting to MT5                                                              |
-| `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                                                                    |
+| `publish-dashboard`    | Publish Parquet analytics datasets and a manifest from a SQLite history database for static dashboards (`--sqlite3`; `-o` is the manifest path; no MT5)                  |
+| `snapshot`             | Snapshot current account, position, order, and terminal state into SQLite                                                                                                |
 
 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
@@ -246,25 +246,20 @@ 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
+### Static dashboard publication
 
-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.
+`mt5cli -o dist/data/manifest.json publish-dashboard --sqlite3 history.db` (or `mt5cli.publish_dashboard("history.db", "dist/data")`) writes `trades`, `daily_pnl`, `strategy_stats`, `equity`, and `account_snapshots` Parquet files plus a `manifest.json` from canonical `analytics_*` views, ready for static hosting and DuckDB-Wasm. It never connects to MT5 and requires the `parquet` extra. See `docs/api/analytics.md`.
 
-#### Prepare the schema (idempotent, no MT5 connection needed)
+### Account snapshots (SQLite)
 
-```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.
+mt5cli can append timestamped account, position, order, and terminal snapshots to a SQLite database. Snapshot tables (`account_snapshots`, `position_snapshots`, `order_snapshots`, `terminal_snapshots`, `snapshot_runs`) are created automatically and idempotently.
 
 #### 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
+  --with-account --with-positions --with-orders --with-terminal
 ```
 
 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.
@@ -284,56 +279,10 @@ update_observability_with_config(
     include_positions=True,
     include_orders=True,
     include_terminal=True,
-    with_grafana_schema=True,
 )
 ```
 
-#### 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;
-```
-
-#### Grafana and telemetry API docs
-
-The shipped Grafana helpers are documented in [`docs/api/grafana.md`](docs/api/grafana.md), including `publish_grafana_copy()` for creating a WAL-safe published SQLite copy for Grafana.
+#### Telemetry API docs
 
 OpenTelemetry metrics are documented in [`docs/api/telemetry.md`](docs/api/telemetry.md), including `enable_otel_metrics()`, `configure_metrics()`, the `mt5cli[otel]` extra, and `OTEL_EXPORTER_OTLP_ENDPOINT`.
 

{mt5cli-1.6.0 → mt5cli-1.7.0}/README.md

@@ -183,8 +183,8 @@ python -m mt5cli -o account.csv account-info
 | `close-positions`      | Close open positions by `--symbol` or `--ticket` (`--yes` required for live; `--dry-run` available; optional `--filling-mode` / `--deviation` / `--comment` / `--magic`) |
 | `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`)                              |
 | `history-gaps`         | Export a SQLite-only one-row-per-gap report from managed rate compatibility views without connecting to MT5                                                              |
-| `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                                                                    |
+| `publish-dashboard`    | Publish Parquet analytics datasets and a manifest from a SQLite history database for static dashboards (`--sqlite3`; `-o` is the manifest path; no MT5)                  |
+| `snapshot`             | Snapshot current account, position, order, and terminal state into SQLite                                                                                                |
 
 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
@@ -217,25 +217,20 @@ 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
+### Static dashboard publication
 
-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.
+`mt5cli -o dist/data/manifest.json publish-dashboard --sqlite3 history.db` (or `mt5cli.publish_dashboard("history.db", "dist/data")`) writes `trades`, `daily_pnl`, `strategy_stats`, `equity`, and `account_snapshots` Parquet files plus a `manifest.json` from canonical `analytics_*` views, ready for static hosting and DuckDB-Wasm. It never connects to MT5 and requires the `parquet` extra. See `docs/api/analytics.md`.
 
-#### Prepare the schema (idempotent, no MT5 connection needed)
+### Account snapshots (SQLite)
 
-```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.
+mt5cli can append timestamped account, position, order, and terminal snapshots to a SQLite database. Snapshot tables (`account_snapshots`, `position_snapshots`, `order_snapshots`, `terminal_snapshots`, `snapshot_runs`) are created automatically and idempotently.
 
 #### 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
+  --with-account --with-positions --with-orders --with-terminal
 ```
 
 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.
@@ -255,56 +250,10 @@ update_observability_with_config(
     include_positions=True,
     include_orders=True,
     include_terminal=True,
-    with_grafana_schema=True,
 )
 ```
 
-#### 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;
-```
-
-#### Grafana and telemetry API docs
-
-The shipped Grafana helpers are documented in [`docs/api/grafana.md`](docs/api/grafana.md), including `publish_grafana_copy()` for creating a WAL-safe published SQLite copy for Grafana.
+#### Telemetry API docs
 
 OpenTelemetry metrics are documented in [`docs/api/telemetry.md`](docs/api/telemetry.md), including `enable_otel_metrics()`, `configure_metrics()`, the `mt5cli[otel]` extra, and `OTEL_EXPORTER_OTLP_ENDPOINT`.
 

mt5cli-1.7.0/docs/api/analytics.md

@@ -0,0 +1,99 @@
+# Analytics
+
+::: mt5cli.analytics
+
+## Static dashboard workflow
+
+mt5cli keeps SQLite as the canonical local store and publishes browser-facing
+Parquet datasets from it, so a static site (for example DuckDB-Wasm) can query
+the data without a live API or direct SQLite access. Visualization stays
+outside mt5cli.
+
+```bash
+mt5cli -o dist/data/manifest.json publish-dashboard --sqlite3 history.db
+```
+
+```python
+from mt5cli import publish_dashboard
+
+manifest = publish_dashboard("history.db", "dist/data")
+```
+
+Publication never connects to MetaTrader 5 and never modifies the source
+database (analytics views are created as connection-local TEMP views). It
+requires the `parquet` extra (`pip install "mt5cli[parquet]"`).
+
+| File                        | Source view                                                                                           |
+| --------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `trades.parquet`            | `analytics_trades`                                                                                    |
+| `daily_pnl.parquet`         | `analytics_daily_pnl`                                                                                 |
+| `strategy_stats.parquet`    | `analytics_strategy_stats`                                                                            |
+| `equity.parquet`            | `analytics_equity`                                                                                    |
+| `account_snapshots.parquet` | `account_snapshots` joined to successful runs                                                         |
+| `manifest.json`             | `schema_version`, `generated_at`, `mt5cli_version`, and per dataset `name`, `file`, `rows`, `columns` |
+
+Datasets whose source tables are missing are skipped and omitted from the
+manifest. The manifest is written last. `manifest_name` must be a plain file name (no `/`, `\\`, drive prefix or `..`) that is not the name of a dataset file; otherwise `ValueError` is raised before anything is written (the CLI reports it as a usage error).
+
+## Analytics views
+
+`create_analytics_views(conn)` creates the views idempotently in an existing
+history database (`temporary=True` creates TEMP views for read-only databases).
+
+- `analytics_trades`: one row per completed trade leg (built on the history layer's `deal_portions` view, the same source as `positions_reconstructed`). A leg is the stretch of
+  a `position_id` between reversals: a `DEAL_ENTRY_INOUT` deal closes the
+  current leg and opens the next one (`leg_index`). Its volume, commission and
+  fee are split pro rata between the two legs; its swap goes wholly to the
+  closing leg (MT5 reports `DEAL_SWAP` for the position being closed), and
+  profit is realized on the closed part only. A leg is complete once its closing volume covers its opening
+  volume (1e-9 lot tolerance), so partially closed legs and the still-open
+  leg after a reversal are excluded. For positions without reversals, leg 0
+  matches `positions_reconstructed`. Columns: `position_id`, `symbol`,
+  `leg_index`, `magic`, `magic_count`, `side`, `open_time`, `close_time`, `close_date`,
+  `holding_seconds`, `volume`, `entry_price`, `exit_price` (volume-weighted),
+  `reversal_count`, `deals_count`, `profit`, `commission`, `swap`, `fee`,
+  `net_profit`. Numeric timestamps stay numeric epoch values; textual
+  timestamps remain timezone-naive MT5 trade-server wall-clock values. No
+  implicit UTC conversion is performed.
+- `analytics_realized_events`: every deal portion, each at its own timestamp
+  (cash basis: an entry's commission lands on the entry date and a partial
+  close's profit on the day it is realized), including partially closed and
+  still-open legs. Events of a completed leg sum to that leg's `net_profit`,
+  so cumulative equity also reflects entry costs and partial-close profit of
+  legs that have not completed yet.
+  Each event carries its own deal's `magic`. A leg needs a visible opening
+  volume to count as a trade, and its position must start inside the captured
+  history (its first visible deal is an entry-in, since the reversal split cannot
+  be reconstructed otherwise), so positions opened before the captured history
+  appear only in the events, daily P/L and equity. This check is best-effort: a
+  scale-in cut by the capture window looks like a position start and cannot be told
+  apart from one using the deals alone, so collect history from before the oldest
+  open position when exact trade legs matter.
+- `analytics_daily_pnl`: per `date`, `symbol`, `magic` (the deal-level magic)
+  from the realized events: `event_count`, `profit`, `commission`, `swap`, `fee`, `net_profit`.
+- `analytics_strategy_stats`: per `symbol`, `magic` from the trade legs (trade
+  count, wins, losses, win rate, gross profit/loss, profit factor), plus
+  `avg_holding_seconds`, `first_open_time`, `last_close_time`. A leg's `magic` is
+  its entry magic; legs whose entry deals mix magics have a NULL `magic` with
+  `magic_count > 1`, so for such legs daily P/L by magic and the strategy stats
+  by magic can differ.
+- `analytics_equity`: one row per realized event in time order with
+  `cumulative_net_profit` (realized P&L only).
+
+Net P/L is:
+
+```text
+net_profit = COALESCE(profit, 0) + COALESCE(commission, 0)
+           + COALESCE(swap, 0) + COALESCE(fee, 0)
+```
+
+Missing optional deal columns are treated as zero (or NULL for `magic`). A trade
+is a win when `net_profit > 0` and a loss when `net_profit < 0`; break-even
+trades count as neither. `gross_profit` and `gross_loss` sum positive and
+negative trade `net_profit`, and `profit_factor = gross_profit / ABS(gross_loss)`
+is NULL without losses. Metrics needing unavailable state (such as MAE/MFE) are
+out of scope.
+
+Parquet columns with a fixed meaning are written with stable types (`Int64`,
+`float64`, `string`) even for empty tables; time columns keep the stored
+representation.

{mt5cli-1.6.0 → mt5cli-1.7.0}/docs/api/history.md

@@ -123,6 +123,20 @@ erDiagram
         REAL profit
     }
 
+    deal_portions {
+        INTEGER ticket
+        INTEGER position_id
+        TEXT symbol
+        INTEGER leg
+        TEXT role
+        INTEGER position_start_known
+        REAL volume
+        REAL profit
+        REAL commission
+        REAL swap
+        REAL fee
+    }
+
     positions_reconstructed {
         INTEGER position_id
         TEXT symbol
@@ -144,20 +158,32 @@ erDiagram
     history_orders ||--o{ history_deals : "order ~ ticket (logical)"
     symbols ||--o{ rates : "symbol (logical)"
     history_deals ||--|| cash_events : "VIEW: type NOT IN (0,1)"
-    history_deals ||--o{ positions_reconstructed : "VIEW: GROUP BY position_id"
+    history_deals ||--o{ deal_portions : "VIEW: deals split at reversals"
+    deal_portions ||--o{ positions_reconstructed : "VIEW: GROUP BY position_id"
 ```
 
 ### Tables and views
 
-| Object                    | Kind  | Source               | Notes                                                                                       |
-| ------------------------- | ----- | -------------------- | ------------------------------------------------------------------------------------------- |
-| `rates`                   | table | `copy_rates_range`   | Indexed on `(symbol, timeframe, time)` when columns exist.                                  |
-| `ticks`                   | table | `copy_ticks_range`   | Indexed on `(symbol, time)` when columns exist.                                             |
-| `history_orders`          | table | `history_orders_get` | Fetched per `--symbol`, then concatenated.                                                  |
-| `history_deals`           | table | `history_deals_get`  | Fetched per `--symbol`, then concatenated. Indexed on `(position_id, symbol)` when present. |
-| `symbols`                 | table | `symbol_info`        | Opt-in. One row per symbol per collection/update, snapshotted at `date_to` / update end.    |
-| `cash_events`             | view  | `history_deals`      | Non-trade deal types (deposits, balance ops, etc.). Requires `type` column.                 |
-| `positions_reconstructed` | view  | `history_deals`      | One row per closed `position_id`; volume-weighted prices and reversal stats.                |
+| Object                    | Kind  | Source               | Notes                                                                                                                                        |
+| ------------------------- | ----- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rates`                   | table | `copy_rates_range`   | Indexed on `(symbol, timeframe, time)` when columns exist.                                                                                   |
+| `ticks`                   | table | `copy_ticks_range`   | Indexed on `(symbol, time)` when columns exist.                                                                                              |
+| `history_orders`          | table | `history_orders_get` | Fetched per `--symbol`, then concatenated.                                                                                                   |
+| `history_deals`           | table | `history_deals_get`  | Fetched per `--symbol`, then concatenated. Indexed on `(position_id, symbol)` when present.                                                  |
+| `symbols`                 | table | `symbol_info`        | Opt-in. One row per symbol per collection/update, snapshotted at `date_to` / update end.                                                     |
+| `cash_events`             | view  | `history_deals`      | Non-trade deal types (deposits, balance ops, etc.). Requires `type` column.                                                                  |
+| `deal_portions`           | view  | `history_deals`      | Canonical leg-aware layer: trade deals, with each reversal (`DEAL_ENTRY_INOUT`) split into a closing and an opening portion (`leg`, `role`). |
+| `positions_reconstructed` | view  | `deal_portions`      | One row per closed `position_id`; volume-weighted prices and reversal stats (reversal volume counted whole).                                 |
+
+The reversal split in `deal_portions` uses the balance of the visible deals, so it
+is reliable only for positions whose first visible deal is an entry-in
+(`position_start_known = 1`). When the captured history starts mid-position
+(`position_start_known = 0`), the `leg` numbering and the closing/opening split of a
+reversal are approximate, though every deal's cash totals are preserved and
+`positions_reconstructed` is unaffected. The flag is best-effort: a scale-in is also
+an entry-in deal, so if the capture window cuts a position and a later scale-in is
+the first visible deal, the missing earlier exposure cannot be detected from the
+deals alone.
 
 Column sets can vary with terminal and pdmt5 version. Views are skipped with a warning
 when required columns are missing.

{mt5cli-1.6.0 → mt5cli-1.7.0}/docs/api/index.md

@@ -18,9 +18,8 @@ responsibilities.
 | [Exceptions](exceptions.md)               | Stable mt5cli exception types and MT5 error normalization                            |
 | [Trading](trading.md)                     | Trading-capable sessions and operational helpers                                     |
 | [History Collection (SQLite)](history.md) | SQLite schema, incremental writes, dedup, and rate views                             |
-| [Observability](observability.md)         | Account/position/order/terminal snapshot orchestration                               |
+| [Observability](observability.md)         | Account/position/order/terminal snapshot orchestration and SQLite snapshot tables    |
 | [Telemetry](telemetry.md)                 | OpenTelemetry metrics setup, meters, and emitted metric names                        |
-| [Grafana](grafana.md)                     | Grafana-ready SQLite schema, views, snapshots, and published copies                  |
 | [CLI](cli.md)                             | Typer commands that delegate to the Python API                                       |
 | [Utils](utils.md)                         | Generic parsing, conversion, and export helpers                                      |
 
@@ -34,7 +33,6 @@ flowchart TD
     MarketData["marketdata"] --> Client
     History["history"] --> Client
     Observability["observability"] --> Client
-    Observability --> Grafana["grafana"]
     History --> Utils["utils export"]
 ```
 

{mt5cli-1.6.0 → mt5cli-1.7.0}/docs/api/observability.md

@@ -2,13 +2,11 @@
 
 ::: mt5cli.observability
 
-## Grafana observability (SQLite read model)
+## Snapshot persistence (SQLite)
 
 These helpers append timestamped account/position/order/terminal snapshot
-rows into a SQLite database, preparing it 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.
+rows into a SQLite database. The snapshot tables are created on demand with
+idempotent DDL (`CREATE TABLE IF NOT EXISTS`).
 
 | Symbol                             | Role                                                                                        |
 | ---------------------------------- | ------------------------------------------------------------------------------------------- |
@@ -17,9 +15,6 @@ warning rather than raising an error.
 
 Both functions write to the SQLite path given by `output=`. The optional
 `symbols` parameter filters `positions` / `orders` 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.
 
 Pass the `MT5Client` yielded by `mt5_session()` directly to
 `update_observability(client=...)`. This workflow calls the facade's canonical
@@ -34,5 +29,7 @@ with mt5_session() as client:
     update_observability(client=client, output="observability.db")
 ```
 
-Schema and persistence (table DDL, Grafana views, and row inserts) belong to
-[Grafana](grafana.md); this module owns _when_ and _what_ to snapshot.
+The snapshot table DDL and row inserts (`create_snapshot_tables`,
+`start_snapshot_run`, `insert_*_snapshot(s)`, `record_snapshot_run`) live in
+this module alongside the orchestration that decides _when_ and _what_ to
+snapshot.

{mt5cli-1.6.0 → mt5cli-1.7.0}/docs/api/public-contract.md

@@ -25,7 +25,7 @@ in pdmt5 — the name changed, it was not simply moved.
 Downstream packages should import from the package root (`from mt5cli import
 ...`). The authoritative SDK declaration in `mt5cli.sdk` enumerates
 every package-root symbol. Helpers promoted for downstream use, including selected configuration and
-parsing utilities, history timeframe resolution, and Grafana schema setup, are
+parsing utilities, history timeframe resolution, and dashboard publication, are
 part of that root contract. Other low-level
 schema, export, conversion, and implementation helpers remain available only
 from their owning modules.
@@ -43,8 +43,8 @@ operational capability still has exactly one owning module:
 | `mt5cli.marketdata`    | Stateless one-off market-data reads and multi-account rate collection (`AccountSpec`, `collect_latest_rates_for_accounts`, etc.)            |
 | `mt5cli.history`       | Legacy history collection, incremental updates, and SQLite storage (`collect_history`, `update_history`, `write_*_dataset`)                 |
 | `mt5cli.rates`         | Canonical rate persistence/loading and stable update wrappers (`load_rate_series_from_sqlite`, `update_history`, `ThrottledHistoryUpdater`) |
-| `mt5cli.observability` | Observability snapshot orchestration (`update_observability`, `update_observability_with_config`)                                           |
-| `mt5cli.grafana`       | Grafana schema, views, and snapshot persistence                                                                                             |
+| `mt5cli.observability` | Observability snapshot orchestration and SQLite snapshot tables (`update_observability`, `update_observability_with_config`)                |
+| `mt5cli.analytics`     | Canonical `analytics_*` views and static-dashboard Parquet publication (`publish_dashboard`)                                                |
 | `mt5cli.trading`       | Order preparation, broker-facing calculations, and normalized execution receipts                                                            |
 | `mt5cli.contract`      | The internal `HistoryClient` / `ObservabilityClient` protocols                                                                              |
 | `mt5cli.sdk`           | Authoritative stable package-root export declaration; no separate connection lifecycle                                                      |
@@ -196,12 +196,11 @@ client type; `from mt5cli import MT5Client, mt5_session` remains the supported
 way to obtain a connected client. Downstream code should import stable names
 from the package root and capability-specific helpers from their owning modules.
 
-### Grafana observability (SQLite read model)
+### Observability snapshots (SQLite)
 
-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.
+These helpers append timestamped account/position/order/terminal snapshot
+rows to a SQLite database. The snapshot tables are created on demand with
+idempotent DDL (`CREATE TABLE IF NOT EXISTS`).
 
 | Symbol                             | Role                                                                                                                                      |
 | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
@@ -213,9 +212,7 @@ warning rather than raising an error.
 
 `update_observability` and `persist_observability_snapshot` 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.
+`positions_get` / `orders_get` by symbol.
 
 `update_observability(client=...)` is exactly
 `capture_observability_snapshot(client=...)` followed by
@@ -232,7 +229,7 @@ workflows call the facade's canonical data methods (`account_info`, `positions`,
 `orders`, `terminal_info`, `copy_rates_range`, `copy_ticks_range`,
 `history_orders`, and `history_deals`); callers never need a pdmt5 client.
 
-**Snapshot tables** (created by `create_snapshot_tables` in `mt5cli.grafana`):
+**Snapshot tables** (created by `create_snapshot_tables` in `mt5cli.observability`):
 
 | Table                | Content                                   |
 | -------------------- | ----------------------------------------- |
@@ -242,35 +239,15 @@ workflows call the facade's canonical data methods (`account_info`, `positions`,
 | `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 |
-
-`ensure_grafana_schema` is a stable package-root helper for downstream setup.
-Other lower-level helpers (`create_grafana_views`, `create_grafana_indexes`,
-`create_snapshot_tables`, `start_snapshot_run`,
+`publish_dashboard(source, output_dir)` is a stable package-root helper that
+publishes Parquet analytics datasets and `manifest.json` from an offline
+SQLite history database without connecting to MT5 or modifying the source; see
+[Analytics](analytics.md).
+
+Lower-level snapshot helpers (`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.
+`mt5cli.observability` and are not part of the package-root stable surface.
 
 ### Errors
 
@@ -314,14 +291,14 @@ names.
 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.grafana`    | `ensure_grafana_schema`, `create_grafana_views`, `create_grafana_indexes`, `create_snapshot_tables`, `start_snapshot_run`, `insert_account_snapshot`, `record_snapshot_run` |
-| `mt5cli.marketdata` | `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`, `ensure_trade_server_time`, `parse_date_range`, `granularity_name`                                                                        |
-| `mt5cli.exceptions` | `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error`                                                                                        |
+| Module              | Examples                                                                                             |
+| ------------------- | ---------------------------------------------------------------------------------------------------- |
+| `mt5cli.analytics`  | `create_analytics_views`                                                                             |
+| `mt5cli.marketdata` | `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`, `ensure_trade_server_time`, `parse_date_range`, `granularity_name` |
+| `mt5cli.exceptions` | `normalize_mt5_exception`, `call_with_normalized_errors`, `is_recoverable_mt5_error`                 |
 
 ## CLI commands
 
@@ -337,14 +314,10 @@ 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.
+never places orders or modifies trading state. It requires `-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
@@ -402,7 +375,8 @@ their own adapter layer.
 
 ## Contract verification
 
-`tests/unit/test_contracts.py` asserts that every name in `STABLE_SDK_EXPORTS` is
+`tests/contracts/test_public_api.py` asserts that every name in `STABLE_SDK_EXPORTS` is
 importable from `mt5cli`, that all package-root exports are covered by the
-stable set, and documents key closed-bar, SQLite loading, account-resolution,
-and trading-session behaviors.
+stable set, and that the package-root API exposes only the canonical public
+surface. Module-specific unit tests cover closed-bar, SQLite loading,
+account-resolution, and trading-session behaviors.

{mt5cli-1.6.0 → mt5cli-1.7.0}/mkdocs.yml

@@ -67,7 +67,7 @@ nav:
       - History Collection (SQLite): api/history.md
       - Observability: api/observability.md
       - Telemetry: api/telemetry.md
-      - Grafana: api/grafana.md
+      - Analytics: api/analytics.md
       - Utils: api/utils.md
 
 markdown_extensions: