nexusquant-cli 0.5.0__tar.gz → 0.6.1__tar.gz

{nexusquant_cli-0.5.0 → nexusquant_cli-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexusquant-cli
-Version: 0.5.0
+Version: 0.6.1
 Summary: NexusQuant CLI for users, strategy providers and admins
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27

nexusquant_cli-0.6.1/nexusquant_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.6.1"

{nexusquant_cli-0.5.0 → nexusquant_cli-0.6.1}/nexusquant_cli/api_client.py

@@ -232,9 +232,11 @@ def list_signal_logs(
     status: str | None = None,
     limit: int = 50,
     offset: int = 0,
+    signal_id: str | None = None,
 ) -> Any:
     """GET /strategy-signal/logs/ — signals that arrived while the caller was
-    listening, with the caller's own broker result per signal."""
+    listening, with the caller's own broker result per signal. `signal_id` = just that one
+    (still only if the caller can see it)."""
     params = _drop_none(
         {
             "strategy_id": strategy_id,
@@ -242,6 +244,7 @@ def list_signal_logs(
             "status": status,
             "limit": limit,
             "offset": offset,
+            "id": signal_id,
         }
     )
     return get_json("/strategy-signal/logs/", params=params)
@@ -397,6 +400,17 @@ def admin_get_agent_session(session: str, *, after_seq: int | None = None, limit
     return get_json(f"/admin/nexus-ai/sessions/{session}/", params=_drop_none({"after_seq": after_seq, "limit": limit}))
 
 
+def admin_list_signal_logs(**filters: Any) -> Any:
+    """GET /admin/strategy-signal/logs/ — every user's signal rows (strategy_id, user_id, direction, status,
+    limit ≤ 200, offset). `status` is the shared row's status."""
+    return get_json("/admin/strategy-signal/logs/", params=_drop_none(filters))
+
+
+def admin_list_containers(*, active_only: bool = False) -> Any:
+    """GET /admin/users/containers/ — every trading environment with its broker connection status."""
+    return get_json("/admin/users/containers/", params={"active_only": "true"} if active_only else None)
+
+
 def admin_list_flags() -> Any:
     """GET /admin/feature-flags/ — every flag/switch with its user list."""
     return get_json("/admin/feature-flags/")

nexusquant_cli-0.6.1/nexusquant_cli/data/signal_codes.json

@@ -0,0 +1,233 @@
+{
+  "_source": "nexus-frontend-platform (generated by nexusquant-cli/scripts/gen_signal_codes.cjs)",
+  "RISK_CODE_LABELS": {
+    "POSITION_OVER_ALLOCATION": {
+      "zh": "超出分配额度",
+      "en": "Over allocation"
+    },
+    "INSUFFICIENT_CASH": {
+      "zh": "现金不足",
+      "en": "Insufficient cash"
+    },
+    "BELOW_MIN_CASH_RESERVE": {
+      "zh": "低于最低现金保有量",
+      "en": "Below minimum cash reserve"
+    },
+    "INSUFFICIENT_BUYING_POWER": {
+      "zh": "购买力不足",
+      "en": "Insufficient buying power"
+    },
+    "CASH_QUERY_FAILED": {
+      "zh": "资金查询失败",
+      "en": "Cash query failed"
+    },
+    "BUYING_POWER_QUERY_FAILED": {
+      "zh": "购买力查询失败",
+      "en": "Buying power query failed"
+    },
+    "INSUFFICIENT_POSITION": {
+      "zh": "持仓不足",
+      "en": "Insufficient position"
+    },
+    "POSITION_QUERY_FAILED": {
+      "zh": "持仓查询失败",
+      "en": "Position query failed"
+    },
+    "RESULT_UNKNOWN": {
+      "zh": "结果未知 · 请到券商核对",
+      "en": "Result unknown · Please check with your broker"
+    },
+    "GATEWAY_UNREACHABLE": {
+      "zh": "券商未连接",
+      "en": "Broker not connected"
+    },
+    "BROKER_RECONNECT_FAILED": {
+      "zh": "券商连接异常",
+      "en": "Broker connection error"
+    },
+    "BROKER_AUTH_EXPIRED": {
+      "zh": "券商授权已失效",
+      "en": "Broker authorization invalid"
+    },
+    "BROKER_NOT_CONNECTED": {
+      "zh": "券商未连接",
+      "en": "Broker not connected"
+    },
+    "SYMBOLS_ALLOWLIST": {
+      "zh": "不在允许交易列表",
+      "en": "Not in allowed symbols"
+    },
+    "UNLOCK_REQUIRED": {
+      "zh": "交易未解锁",
+      "en": "Trading not unlocked"
+    },
+    "MAX_ORDER_CASH_USD": {
+      "zh": "单笔金额上限过低",
+      "en": "Max order amount too low"
+    }
+  },
+  "RISK_CODE_DETAILS": {
+    "CASH_QUERY_FAILED": {
+      "zh": "下单前未能查询到账户可用美元现金，为避免误单，已跳过本次买入。通常是券商连接中断，请在「我的策略」中检查券商连接。",
+      "en": "Couldn't check your account's available USD cash before ordering, so this buy was skipped to avoid a wrong order. This is usually a dropped broker connection. Please check the broker connection in My strategies."
+    },
+    "POSITION_QUERY_FAILED": {
+      "zh": "下单前未能查询到该品种的持仓市值，为避免超出分配额度，已跳过本次买入。通常是券商连接中断，请在「我的策略」中检查券商连接。",
+      "en": "Couldn't check this symbol's position value before ordering, so this buy was skipped to avoid exceeding your allocation. This is usually a dropped broker connection. Please check the broker connection in My strategies."
+    },
+    "BUYING_POWER_QUERY_FAILED": {
+      "zh": "下单前未能查询到账户购买力，为避免误单，已跳过本次买入。通常是券商连接中断，请在「我的策略」中检查券商连接。",
+      "en": "Couldn't check your account's buying power before ordering, so this buy was skipped to avoid a wrong order. This is usually a dropped broker connection. Please check the broker connection in My strategies."
+    },
+    "BROKER_AUTH_EXPIRED": {
+      "zh": "券商授权已失效，订单未提交。请在「我的策略」中点击「重新授权」。",
+      "en": "Your broker authorization is no longer valid, so the order wasn't submitted. Please click \"Re-authorize\" in My strategies."
+    }
+  },
+  "CONFIG_SKIP_COPY": {
+    "config_below_one_share": {
+      "zh": "按当前配置，本次交易不足 1 股，已跳过。如需参与，请调整策略配置。",
+      "en": "Under your current settings, this order is less than 1 share, so it was skipped. To take part, please adjust the strategy settings."
+    },
+    "config_not_dispatched": {
+      "zh": "本次信号已按当前配置跳过。如需参与，请调整策略配置。",
+      "en": "This signal was skipped under your current settings. To take part, please adjust the strategy settings."
+    },
+    "config_zero_quantity": {
+      "zh": "本次信号已按当前配置跳过。如需参与，请调整策略配置。",
+      "en": "This signal was skipped under your current settings. To take part, please adjust the strategy settings."
+    }
+  },
+  "UNCONFIRMED_COPY": {
+    "label": {
+      "zh": "未确认 · 请到券商 App 核对",
+      "en": "Unconfirmed · Please check your broker app"
+    },
+    "detail": {
+      "zh": "该订单的最终结果未能确认，请在券商 App 中核对。",
+      "en": "The final result of this order couldn't be confirmed. Please check it in your broker app."
+    }
+  },
+  "FAILURE_KIND_COPY": {
+    "opposite_pending_order": {
+      "label": {
+        "zh": "未执行 · 有反向挂单",
+        "en": "Not executed · Opposite pending order"
+      },
+      "detail": {
+        "zh": "该品种有相反方向的未成交挂单，您的券商不支持交叉交易。请先撤销反向挂单后重试。",
+        "en": "This symbol has an unfilled order in the opposite direction, and your broker doesn't support cross trading. Please cancel the opposite order first, then try again."
+      }
+    },
+    "insufficient_buying_power": {
+      "label": {
+        "zh": "购买力不足",
+        "en": "Insufficient buying power"
+      },
+      "detail": {
+        "zh": "下单时券商提示购买力不足，订单被拒绝（未成交）。请在券商 App 存入资金或换汇后重试。",
+        "en": "Your broker rejected the order for insufficient buying power (not filled). Please deposit funds or exchange currency in your broker app, then try again."
+      }
+    },
+    "timeout_not_sent": {
+      "label": {
+        "zh": "未执行 · 券商未响应",
+        "en": "Not executed · No response from broker"
+      },
+      "detail": {
+        "zh": "等待券商响应超时，订单没有发出（未成交）。如持续出现，请在「我的策略」中检查券商连接。",
+        "en": "The broker didn't respond in time, so the order was not sent (not filled). If this keeps happening, please check the broker connection in My strategies."
+      }
+    },
+    "in_doubt_absent": {
+      "label": {
+        "zh": "未执行 · 券商查无此单",
+        "en": "Not executed · Broker has no such order"
+      },
+      "detail": {
+        "zh": "下单结果当时未能确认，之后向券商核实，券商没有这笔订单（未成交）。本次信号不会补下。",
+        "en": "The result of this order couldn't be confirmed at the time. The broker later confirmed it has no such order (not filled). This signal will not be placed again."
+      }
+    },
+    "broker_not_connected": {
+      "label": {
+        "zh": "未执行 · 券商未连接",
+        "en": "Not executed · Broker not connected"
+      },
+      "detail": {
+        "zh": "下单时无法连接券商。请在「我的策略」中检查券商连接并完成验证。",
+        "en": "Couldn't reach your broker when placing the order. Please check the broker connection in My strategies and complete verification."
+      }
+    },
+    "broker_gateway_down": {
+      "label": {
+        "zh": "未执行 · 券商未连接",
+        "en": "Not executed · Broker not connected"
+      },
+      "detail": {
+        "zh": "下单时无法连接券商。请在「我的策略」中检查券商连接并完成验证。",
+        "en": "Couldn't reach your broker when placing the order. Please check the broker connection in My strategies and complete verification."
+      }
+    },
+    "broker_auth_expired": {
+      "label": {
+        "zh": "未执行 · 券商授权已失效",
+        "en": "Not executed · Broker authorization invalid"
+      },
+      "detail": {
+        "zh": "券商授权已失效，订单未提交。请在「我的策略」中点击「重新授权」。",
+        "en": "Your broker authorization is no longer valid, so the order wasn't submitted. Please click \"Re-authorize\" in My strategies."
+      }
+    },
+    "pdt_restriction": {
+      "label": {
+        "zh": "未执行 · 触发日内交易限制",
+        "en": "Not executed · Pattern day trader limit"
+      },
+      "detail": {
+        "zh": "该订单将使您的账户被认定为日内交易者（Pattern Day Trader）。按 NYSE / FINRA 规则，此类账户需维持不低于 $25,000 的账户权益，券商因此拒绝了该订单。请在券商 App 查看账户权益，或减少日内往返交易后重试。",
+        "en": "This order would classify your account as a pattern day trader. Under NYSE/FINRA rules, such accounts must keep at least $25,000 in equity, so your broker rejected the order. Please check your account equity in the broker app, or make fewer day trades, then try again."
+      }
+    },
+    "account_action_required": {
+      "label": {
+        "zh": "被券商拒绝 · 账户待处理",
+        "en": "Rejected by broker · Account needs attention"
+      },
+      "detail": {
+        "zh": "券商账户有待处理事项，订单被拒绝。请在券商 App 查看拒单原因。",
+        "en": "Your broker account has an item that needs attention, so the order was rejected. Please check the reason in your broker app."
+      }
+    },
+    "unlock_required": {
+      "label": {
+        "zh": "交易未解锁",
+        "en": "Trading not unlocked"
+      },
+      "detail": {
+        "zh": "券商要求先解锁交易才能下单。请在券商 App 完成交易解锁后重试。",
+        "en": "Your broker requires trading to be unlocked before placing orders. Please unlock trading in the broker app, then try again."
+      }
+    },
+    "non_trading_hours": {
+      "label": {
+        "zh": "未执行 · 非交易时段",
+        "en": "Not executed · Outside trading hours"
+      },
+      "detail": {
+        "zh": "下单时不在该品种的可交易时段，券商未受理。请在交易时段内重试。",
+        "en": "The order was placed outside this symbol's trading hours, so the broker didn't accept it. Please try again during trading hours."
+      }
+    },
+    "not_supported": {
+      "label": {
+        "zh": "未执行 · 券商不支持该操作",
+        "en": "Not executed · Not supported by your broker"
+      },
+      "detail": {
+        "zh": "您的券商不支持该下单方式。",
+        "en": "Your broker doesn't support this type of order."
+      }
+    }
+  }
+}

{nexusquant_cli-0.5.0 → nexusquant_cli-0.6.1}/nexusquant_cli/embedded.py

@@ -15,7 +15,9 @@ as the user who is chatting, without any credentials on disk:
 
 The token never appears in argv, the environment, or a file.
 
-Read commands (`investor list|read …`, plus `ping broker`) always run. Commands that change state run only when the
+Read commands (`investor list|read …`, plus `ping broker`) always run. `admin list|read …` also runs —
+the bridge offers it only in admin (operator) sessions, and the backend checks the token is an admin's;
+admin commands that change anything are never available here. Commands that change state run only when the
 caller sets NEXUS_CLI_WRITE_CONFIRMED=1 — the bridge does so only after the user clicked "allow"
 for that exact call — and only from the WRITE_COMMANDS allowlist; they get --yes because the
 confirmation already happened. Everything else is refused before a token is read.
@@ -68,6 +70,8 @@ def is_write(argv: list[str]) -> bool:
 
 def validate(argv: list[str], *, write_confirmed: bool = False) -> str | None:
     """None if argv may run; otherwise why not."""
+    if len(argv) >= 3 and argv[0] == "admin":
+        return None if argv[1] in READ_VERBS else "only `admin list|read …` is available here"
     if len(argv) < 3 or argv[0] != "investor":
         return "only `investor <verb> <resource> …` is available"
     if argv[1] in READ_VERBS or argv[2] in UNCONFIRMED_ACTIONS.get(argv[1], set()):
@@ -97,15 +101,18 @@ def main(argv: list[str] | None = None) -> int:
     from nexusquant_cli.config import set_token_override
 
     set_token_override(token)
-    # Import only the investor commands: the full app also loads provider/policy, which needs the SDK.
-    from nexusquant_cli.roles.investor import investor_app
+    # Import only the role that runs: the full app also loads provider/policy, which needs the SDK.
+    if argv[0] == "admin":
+        from nexusquant_cli.roles.admin import admin_app as app
+    else:
+        from nexusquant_cli.roles.investor import investor_app as app
 
     if "--json" not in argv:
         argv.append("--json")
-    if write and "--yes" not in argv and "--yes" in _options(investor_app, argv[1], argv[2]):
+    if write and "--yes" not in argv and "--yes" in _options(app, argv[1], argv[2]):
         argv.append("--yes")   # confirmed in the web UI already; a prompt here would block on stdin
     try:
-        investor_app(argv[1:], prog_name="nexus-cli investor", standalone_mode=False)
+        app(argv[1:], prog_name=f"nexus-cli {argv[0]}", standalone_mode=False)
     except SystemExit as e:  # typer.Exit / click exceptions
         return int(e.code or 0) if isinstance(e.code, int) else 1
     except Exception as e:  # noqa: BLE001 — usage errors etc.; message only, never the token

{nexusquant_cli-0.5.0 → nexusquant_cli-0.6.1}/nexusquant_cli/roles/admin.py

@@ -204,6 +204,59 @@ def list_agent_logs(
         console.print(f"[dim]More: --before {d.get('next_before')} --before-id {d.get('next_before_id')}[/dim]")
 
 
+@list_app.command("signals", help="Signal rows of every user (ops: find failures). --status filters the shared row status.")
+def list_signals(
+    user_id: UserIdOpt = None,
+    strategy_id: Annotated[str | None, typer.Option("--strategy-id")] = None,
+    direction: Annotated[str | None, typer.Option("--direction", help="buy / sell")] = None,
+    status: Annotated[str | None, typer.Option("--status", help="completed / failed / skipped / sent_to_broker")] = None,
+    limit: Annotated[int, typer.Option("--limit", min=1, max=200)] = 50,
+    offset: Annotated[int, typer.Option("--offset", min=0)] = 0,
+    as_json: Annotated[bool, typer.Option("--json", help="Print raw JSON.")] = False,
+) -> None:
+    try:
+        resp = api_client.admin_list_signal_logs(user_id=user_id, strategy_id=strategy_id, direction=direction,
+                                                 status=status, limit=limit, offset=offset)
+    except Exception as e:  # noqa: BLE001
+        fail(console, e)
+    d = (resp or {}).get("data") or {}
+    if as_json:
+        console.print_json(data=d)
+        return
+    table = Table(show_header=True, header_style="dim")
+    for col in ("time", "user", "strategy", "ticker", "side", "price", "status", "error"):
+        table.add_column(col, overflow="fold")
+    for r in d.get("logs") or []:
+        table.add_row(str(r.get("received_at"))[:19], str(r.get("user_email") or r.get("user_id") or ""),
+                      str(r.get("strategy_id")), str(r.get("ticker")), str(r.get("direction")), str(r.get("price")),
+                      str(r.get("status")), str(r.get("error_message") or "")[:80])
+    console.print(table)
+
+
+@list_app.command("containers", help="Every trading environment with broker and connection status (ops).")
+def list_containers(
+    active_only: Annotated[bool, typer.Option("--active-only", help="Only running / active ones.")] = False,
+    as_json: Annotated[bool, typer.Option("--json", help="Print raw JSON.")] = False,
+) -> None:
+    try:
+        resp = api_client.admin_list_containers(active_only=active_only)
+    except Exception as e:  # noqa: BLE001
+        fail(console, e)
+    d = (resp or {}).get("data", resp) if isinstance(resp, dict) else {}
+    rows = (d or {}).get("containers") or []
+    if as_json:
+        console.print_json(data=d)
+        return
+    table = Table(show_header=True, header_style="dim")
+    for col in ("user", "broker", "status", "connection", "login", "version", "strategies"):
+        table.add_column(col, overflow="fold")
+    for r in rows:
+        table.add_row(str(r.get("user_email") or r.get("username") or ""), str(r.get("broker_id")),
+                      str(r.get("status")), str(r.get("connection_status")), str(r.get("opend_login_status") or ""),
+                      str(r.get("vm_version") or ""), str(r.get("strategy_name") or ""))
+    console.print(table)
+
+
 @list_app.command("agent-access", help="Which non-admin users may use Nexus AI (flag NEXUS_AI_USERS).")
 def list_agent_access(as_json: Annotated[bool, typer.Option("--json", help="Print raw JSON.")] = False) -> None:
     try:

{nexusquant_cli-0.5.0 → nexusquant_cli-0.6.1}/nexusquant_cli/roles/investor.py

@@ -344,15 +344,11 @@ def list_signals(
     for col in ("time", "strategy", "ticker", "side", "price", "status", "your result"):
         table.add_column(col, overflow="fold")
     for s in logs:
-        res = s.get("viewer_broker_result") or {}
-        if res.get("error"):
-            detail = f"[red]{res.get('error')}[/red]"
-        elif res.get("skipped"):
-            detail = f"[yellow]skipped[/yellow] {res.get('risk_code') or ''}"
-        elif res.get("is_filled"):
-            detail = "[green]filled[/green]"
+        results = s.get("viewer_broker_results") or []
+        if len({r.get("account_tail") or "" for r in results}) > 1:
+            detail = "\n".join(f"{r.get('account_tail')} {_result_detail(s, r)}" for r in results)
         else:
-            detail = str(s.get("viewer_no_result_reason") or "")
+            detail = _result_detail(s, s.get("viewer_broker_result") or {})
         table.add_row(
             str(s.get("signal_time") or s.get("received_at"))[:19],
             str(s.get("strategy_id")), str(s.get("ticker")), str(s.get("direction")),
@@ -366,6 +362,51 @@ def list_signals(
         )
 
 
+def _result_detail(signal: dict, res: dict) -> str:
+    if res.get("error"):
+        return f"[red]{res.get('error')}[/red]"
+    if res.get("skipped"):
+        return f"[yellow]skipped[/yellow] {res.get('risk_code') or ''}"
+    if res.get("is_filled"):
+        return "[green]filled[/green]"
+    return str(signal.get("viewer_no_result_reason") or "")
+
+
+@read_app.command("signal", help="One signal you received, and why it did or didn't place an order.")
+def read_signal(
+    signal_id: Annotated[str, typer.Argument(help="Signal id (from `list signals`).")],
+    as_json: JsonOpt = False,
+) -> None:
+    from nexusquant_cli.signal_explain import explain
+
+    resp = _call(lambda: api_client.list_signal_logs(signal_id=signal_id, limit=1)) or {}
+    logs = (resp.get("data") or {}).get("logs") or []
+    if not logs:
+        console.print(f"[red]No signal {signal_id} in your signal history.[/red]")
+        raise typer.Exit(1)
+    row = logs[0]
+    out = {"signal": row, "explain": explain(row)}
+    if as_json:
+        console.print_json(data=out)
+        return
+    ex = out["explain"]
+    console.print(f"[bold]{row.get('ticker')} {row.get('direction')} @ {row.get('price')}[/bold]  "
+                  f"{row.get('strategy_name')} · {str(row.get('signal_time'))[:19]}")
+    console.print(f"outcome  {ex['outcome']}   (listening at signal time: {ex.get('listening_at_signal_time')})")
+    for key, val in ex.get("codes", {}).items():
+        console.print(f"{key:<14}{val}")
+    for key, val in ex.get("copy", {}).items():
+        if isinstance(val, dict) and "zh" in val:
+            console.print(f"[dim]{key}[/dim]  {val['zh']}")
+        elif isinstance(val, dict):
+            for sub, txt in val.items():
+                console.print(f"[dim]{key}.{sub}[/dim]  {txt.get('zh') if isinstance(txt, dict) else txt}")
+    if ex.get("broker_message"):
+        console.print(f"[dim]broker[/dim]  {ex['broker_message']}")
+    for acct in ex.get("accounts", []):
+        console.print(f"account  {acct['account']}  {acct['outcome']}")
+
+
 @read_app.command("stats", help="Your signal counts and broker success rate.")
 def read_stats(as_json: JsonOpt = False) -> None:
     resp = _call(api_client.get_signal_statistics) or {}

nexusquant_cli-0.6.1/nexusquant_cli/signal_explain.py

@@ -0,0 +1,119 @@
+"""Why a signal did or didn't trade — facts + the web app's own wording.
+
+Used by `nexus-cli investor read signal <id>` (and so by Nexus AI when a user asks
+"why didn't this signal place an order?").
+
+The CLI does NOT re-derive the order status: the web app's deriveOrderStatus has dozens
+of branches and a second copy would drift. Instead it returns
+  * `outcome`: one coarse bucket computed from the viewer fields the backend already sends,
+  * `codes`:   the raw error_code / risk_code / failure_kind / submit_class,
+  * `copy`:    the exact zh/en strings the web app shows for those codes, looked up in
+               data/signal_codes.json, which is generated from the frontend source by
+               scripts/gen_signal_codes.cjs (tests/test_signal_codes.py keeps them in sync).
+"""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from importlib import resources
+from typing import Any
+
+
+@lru_cache(maxsize=1)
+def glossary() -> dict[str, Any]:
+    text = resources.files("nexusquant_cli").joinpath("data/signal_codes.json").read_text(encoding="utf-8")
+    return json.loads(text)
+
+
+# Plain facts for the branches that have no code to look up (mirrors the first branches of the
+# web app's deriveOrderStatus: not listening / no broker report / still waiting).
+_NO_RESULT = {
+    "not_listening": {
+        "zh": "信号到达时，你没有开启这个策略的监听（自动交易），所以不会下单。",
+        "en": "Listening (auto-trading) for this strategy was off when the signal arrived, so no order was placed.",
+    },
+    "no_broker_report": {
+        "zh": "监听是开着的，但超过一小时没有收到券商的执行回报，可能当时券商未连接或执行超时。",
+        "en": "Listening was on, but no execution report came back from the broker for over an hour. "
+              "The broker may have been disconnected, or execution timed out.",
+    },
+    "awaiting": {
+        "zh": "还在等券商的下单回报。",
+        "en": "Still waiting for the broker's order report.",
+    },
+}
+
+
+def _upper_lookup(table: dict[str, Any], code: str | None) -> Any:
+    if not code:
+        return None
+    return table.get(code) or table.get(code.upper())
+
+
+def explain(row: dict[str, Any]) -> dict[str, Any]:
+    """The account the backend picked (a failed one, if any failed), plus every account when there are several."""
+    out = _explain_one(row)
+    results = row.get("viewer_broker_results") or []
+    if len({r.get("account_tail") or "" for r in results}) > 1:
+        out["accounts"] = [
+            {"account": r.get("account_tail"), **_explain_one({**row, "viewer_broker_result": r})} for r in results
+        ]
+    return out
+
+
+def _explain_one(row: dict[str, Any]) -> dict[str, Any]:
+    g = glossary()
+    vbr = row.get("viewer_broker_result") or None
+    listening = row.get("viewer_was_listening_at_signal_time")
+    out: dict[str, Any] = {"listening_at_signal_time": listening, "codes": {}, "copy": {}}
+
+    if not vbr:
+        if listening is False:
+            out["outcome"] = "not_listening"
+        elif row.get("viewer_no_result_reason") == "no_broker_stale":
+            out["outcome"] = "no_broker_report"
+        else:
+            out["outcome"] = "awaiting"
+        out["copy"]["summary"] = _NO_RESULT[out["outcome"]]
+        return out
+
+    order_info = vbr.get("order_info") if isinstance(vbr.get("order_info"), dict) else {}
+    if vbr.get("success") is True:
+        if vbr.get("is_filled"):
+            outcome = "filled"
+        elif vbr.get("is_cancelled"):
+            outcome = "rejected_by_broker" if order_info.get("reject_reason") else "cancelled_unfilled"
+        else:
+            outcome = "submitted"
+    elif vbr.get("skipped") is True:
+        outcome = "skipped"
+    else:
+        outcome = "unconfirmed" if vbr.get("submit_class") == "in_doubt" else "failed"
+    out["outcome"] = outcome
+
+    codes = {k: vbr.get(k) for k in ("error_code", "risk_code", "failure_kind", "submit_class") if vbr.get(k)}
+    if order_info.get("reject_reason"):
+        codes["reject_reason"] = str(order_info["reject_reason"])[:300]
+    out["codes"] = codes
+
+    copy = out["copy"]
+    if codes.get("error_code") in g["CONFIG_SKIP_COPY"]:
+        copy["config_skip"] = g["CONFIG_SKIP_COPY"][codes["error_code"]]
+    for key in ("risk_code", "error_code"):
+        label = _upper_lookup(g["RISK_CODE_LABELS"], codes.get(key))
+        if label and "label" not in copy:
+            copy["label"] = label
+            detail = _upper_lookup(g["RISK_CODE_DETAILS"], codes.get(key))
+            if detail:
+                copy["detail"] = detail
+    kind = codes.get("failure_kind")
+    if kind and kind in g["FAILURE_KIND_COPY"]:
+        copy["failure_kind"] = g["FAILURE_KIND_COPY"][kind]
+    if outcome == "unconfirmed":
+        copy["unconfirmed"] = g["UNCONFIRMED_COPY"]
+    # The broker / VM's own text: the web app falls back to it when no copy matches.
+    raw = vbr.get("error_zh") or vbr.get("error")
+    if raw and not copy:
+        out["broker_message"] = str(raw)[:500]
+    return out

{nexusquant_cli-0.5.0 → nexusquant_cli-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nexusquant-cli"
-version = "0.5.0"
+version = "0.6.1"
 description = "NexusQuant CLI for users, strategy providers and admins"
 readme = "README.md"
 requires-python = ">=3.10"