nexusquant-cli 0.1.2__tar.gz → 0.2.0__tar.gz

{nexusquant_cli-0.1.2 → nexusquant_cli-0.2.0}/PKG-INFO

@@ -1,9 +1,10 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: nexusquant-cli
-Version: 0.1.2
+Version: 0.2.0
 Summary: NexusQuant strategy provider CLI
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.27
+Requires-Dist: nexusquant-sdk>=0.2
 Requires-Dist: platformdirs>=4.2
 Requires-Dist: rich>=13.7
 Requires-Dist: typer>=0.12

nexusquant_cli-0.2.0/nexusquant_cli/__init__.py

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

{nexusquant_cli-0.1.2 → nexusquant_cli-0.2.0}/nexusquant_cli/commands/__init__.py

@@ -3,9 +3,11 @@ from __future__ import annotations
 import typer
 
 from nexusquant_cli.commands.auth.cmd import register as register_auth
+from nexusquant_cli.commands.policy.cmd import register as register_policy
 from nexusquant_cli.commands.strategy.cmd import register as register_strategy
 
 
 def register_all(app: typer.Typer) -> None:
     register_auth(app)
+    register_policy(app)
     register_strategy(app)

nexusquant_cli-0.2.0/nexusquant_cli/commands/policy/cmd.py

@@ -0,0 +1,327 @@
+"""`nexusquant policy …` —— SizingPolicy: publish a formula instead of a number.
+
+All validation lives in ``nexusquant_sdk._policy`` and is called from here, never
+re-implemented. A second copy of the rules would eventually drift from the server,
+and a client check that disagrees with the server is worse than no check at all —
+it hands you false confidence. (The backend is always the authority; these commands
+only move the obvious mistakes onto your machine.)
+
+What you submit is two things::
+
+    {"expr": {"buy.quantity": "...", "buy.price": "..."}, "params": ["a", "b"]}
+
+``expr`` is the formula, ``params`` are the names it needs you to send with every
+signal. Run ``nexusquant policy features`` first — that endpoint is the authority on
+which names exist.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from nexusquant_cli.commands._util import load_json_file
+from nexusquant_sdk import (
+    SignalValidationError,
+    parse_param_args,
+    policy_features,
+    policy_list,
+    policy_publish,
+    policy_send_signal,
+    policy_set_mode,
+    policy_spec_for,
+)
+
+console = Console()
+
+policy_app = typer.Typer(
+    help=(
+        "SizingPolicy: submit a formula that decides order quantity (and optionally "
+        "limit price) instead of sending a fixed number. Requires "
+        "custom:userType=strategyProvider or admin."
+    ),
+    no_args_is_help=True,
+)
+
+
+def _err(e: Exception) -> None:
+    console.print(f"[red]{e}[/red]")
+    raise typer.Exit(1) from e
+
+
+def _print_gate(gate: dict[str, Any]) -> None:
+    """Print every gate step. When a publish is rejected, which step and why is the
+    only useful information, so it is never collapsed into a single line."""
+    table = Table(show_header=True, header_style="dim")
+    table.add_column("gate", style="bold")
+    table.add_column("")
+    table.add_column("detail", overflow="fold")
+    for step in gate.get("steps") or []:
+        table.add_row(
+            str(step.get("name")),
+            "[green]pass[/green]" if step.get("ok") else "[red]fail[/red]",
+            str(step.get("detail") or ""),
+        )
+    console.print(table)
+    for warning in gate.get("warnings") or []:
+        console.print(f"[yellow]⚠ {warning}[/yellow]")
+
+
+@policy_app.command(
+    "features",
+    help=(
+        "List the names a formula may use. Run this before writing one — the server "
+        "registry is the authority, and names outside it cannot be published."
+    ),
+)
+def features_cmd(
+    scope: Annotated[
+        str | None,
+        typer.Option("--scope", help="Filter: 'shared' (you send them) or 'account' (bound in the user's container)"),
+    ] = None,
+    as_json: Annotated[bool, typer.Option("--json", help="Raw output for scripting")] = False,
+) -> None:
+    try:
+        resp = policy_features()
+    except Exception as e:  # noqa: BLE001
+        _err(e)
+    data = (resp or {}).get("data") or {}
+    rows = data.get("features") or []
+    if not rows:
+        console.print("[dim]Server returned no features.[/dim]")
+        return
+    if as_json:
+        console.print_json(data=data)
+        return
+
+    want = (scope or "").strip().lower()
+    if want in ("account", "per_user"):
+        rows = [r for r in rows if r.get("scope") == "per_user"]
+    elif want == "shared":
+        rows = [r for r in rows if r.get("scope") == "shared"]
+    elif want:
+        _err(RuntimeError("--scope must be 'shared' or 'account'"))
+
+    table = Table(show_header=True, header_style="dim")
+    table.add_column("name", style="bold", overflow="fold")
+    table.add_column("label", overflow="fold")
+    table.add_column("supplied by")
+    table.add_column("what it is", overflow="fold")
+    for r in sorted(rows, key=lambda x: (x.get("scope") != "shared", x.get("name") or "")):
+        per_user = r.get("scope") == "per_user"
+        # A registered-but-unsuppliable name is flagged in red here: it can be written
+        # into a formula, but publishing will reject it — and that rejection lands
+        # after you have already written the whole thing.
+        if per_user and not r.get("suppliable", True):
+            who = "[red]unavailable[/red]"
+        elif per_user:
+            who = "[cyan]user's container[/cyan]"
+        else:
+            who = "you, per signal"
+        table.add_row(
+            str(r.get("name")), str(r.get("label") or ""), who,
+            str(r.get("definition") or ""),
+        )
+    console.print(table)
+    if data.get("guidance"):
+        console.print(f"\n[yellow]{data['guidance']}[/yellow]")
+    console.print(
+        "\n[dim]Names marked 'you, per signal' go into your artifact's params. "
+        "Names bound in the user's container must NOT — reference them directly.[/dim]"
+    )
+
+
+@policy_app.command(
+    "publish",
+    help=(
+        "Publish a policy. This call IS the go-live action — there is no shadow or "
+        "canary step, and the previous version on the same slot is deactivated."
+    ),
+)
+def publish_cmd(
+    strategy_id: Annotated[str, typer.Option("--strategy-id", help="A strategy you own")],
+    ticker: Annotated[str, typer.Option("--ticker", help="Which symbol this formula is for")],
+    file: Annotated[Path, typer.Option("--file", help='JSON: {"expr": {...}, "params": [...]}')],
+    profile: Annotated[str | None, typer.Option("--profile", help="Tier; defaults to 'normal'")] = None,
+    skip_name_check: Annotated[
+        bool,
+        typer.Option("--skip-name-check", help="Do not fetch the registry before validating locally"),
+    ] = False,
+) -> None:
+    raw = load_json_file(file, label="--file")
+    if not isinstance(raw, dict):
+        _err(RuntimeError("--file must contain a JSON object"))
+    try:
+        resp = policy_publish(
+            strategy_id,
+            ticker=ticker,
+            expr=raw.get("expr") or {},
+            params=raw.get("params") or [],
+            profile=profile,
+            check_names=not skip_name_check,
+        )
+    except SignalValidationError as e:
+        _err(e)
+    except Exception as e:  # noqa: BLE001
+        _err(e)
+    data = (resp or {}).get("data") or {}
+    if data.get("gate"):
+        _print_gate(data["gate"])
+    console.print(f"[green]Published and live[/green] {data.get('policy_id')}")
+    if data.get("slots"):
+        console.print(f"Output slots: {', '.join(data['slots'])}")
+    if data.get("params"):
+        console.print(
+            f"Send with every signal: {', '.join(data['params'])}"
+            "  [dim]miss one and the signal is rejected[/dim]"
+        )
+    if data.get("account_features"):
+        console.print(
+            f"[cyan]Reads user holdings: {', '.join(data['account_features'])}[/cyan]"
+            "  [dim]values are bound in the user's container; you never see them[/dim]"
+        )
+    if data.get("superseded"):
+        console.print(f"Deactivated on the same slot: {', '.join(data['superseded'])}")
+
+
+@policy_app.command("list", help="List published policies for one strategy.")
+def list_cmd(
+    strategy_id: Annotated[str, typer.Argument(help="Strategy ID")],
+    ticker: Annotated[str | None, typer.Option("--ticker")] = None,
+    mode: Annotated[str | None, typer.Option("--mode", help="active / off")] = None,
+) -> None:
+    try:
+        resp = policy_list(strategy_id, ticker=ticker, mode=mode)
+    except Exception as e:  # noqa: BLE001
+        _err(e)
+    rows = ((resp or {}).get("data") or {}).get("policies") or []
+    if not rows:
+        console.print("[dim]No published policies.[/dim]")
+        return
+    table = Table(show_header=True, header_style="dim")
+    for col in ("policy_id", "ticker", "mode", "output slots", "params", "reads holdings"):
+        table.add_column(col, overflow="fold")
+    for r in rows:
+        art = r.get("artifact") or {}
+        slots = r.get("slots") or [k for k in (art.get("expr") or {}) if "." in k]
+        params = r.get("params") or art.get("params") or []
+        acct = r.get("account_features") or []
+        table.add_row(
+            str(r.get("policy_id")), str(r.get("ticker")),
+            ("[green]active[/green]" if r.get("mode") == "active" else str(r.get("mode"))),
+            ", ".join(sorted(slots)), ", ".join(sorted(params)),
+            ("[cyan]" + ", ".join(sorted(acct)) + "[/cyan]") if acct else "",
+        )
+    console.print(table)
+
+
+@policy_app.command(
+    "set-mode",
+    help="Deactivate or restore a policy (active ↔ off). Publishing already goes live, so this is the emergency stop, not a promotion step.",
+)
+def set_mode_cmd(
+    policy_id: Annotated[str, typer.Option("--policy-id")],
+    mode: Annotated[str, typer.Option("--mode", help="active or off")],
+) -> None:
+    try:
+        resp = policy_set_mode(policy_id, mode)
+    except ValueError as e:
+        _err(e)
+    except Exception as e:  # noqa: BLE001
+        _err(e)
+    data = (resp or {}).get("data") or {}
+    console.print(f"[green]{data.get('previous_mode')} → {data.get('mode')}[/green] {policy_id}")
+
+
+@policy_app.command(
+    "send-signal",
+    help=(
+        "Send a signal carrying the policy's parameter values (--param name=value, "
+        "repeatable). Every declared parameter must be present or the signal is rejected."
+    ),
+)
+def send_signal_cmd(
+    strategy_id: Annotated[str, typer.Option("--strategy-id")],
+    ticker: Annotated[str, typer.Option("--ticker")],
+    price: Annotated[float, typer.Option("--price")],
+    direction: Annotated[str, typer.Option("--direction", help="buy or sell")],
+    strategy_name: Annotated[str | None, typer.Option("--strategy-name")] = None,
+    param: Annotated[
+        list[str] | None,
+        typer.Option("--param", "-p", help="Parameter value, e.g. depth=3; repeat per declared name"),
+    ] = None,
+    params_file: Annotated[
+        Path | None, typer.Option("--params-file", help="Or a JSON object with all parameter values")
+    ] = None,
+    quantity: Annotated[
+        int | None,
+        typer.Option("--quantity", help="Used when the formula has no slot for this direction"),
+    ] = None,
+    order_type: Annotated[str | None, typer.Option("--order-type", help="MARKET / LIMIT")] = None,
+    policy_id: Annotated[
+        str | None, typer.Option("--policy-id", help="Defaults to the active policy on this (strategy, ticker)")
+    ] = None,
+    no_fetch: Annotated[
+        bool,
+        typer.Option("--no-fetch", help="Skip fetching the policy; only the 'no account state' rule is then checked"),
+    ] = False,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Validate and print the payload without sending")] = False,
+) -> None:
+    supplied: dict[str, Any] = {}
+    if params_file:
+        loaded = load_json_file(params_file, label="--params-file")
+        if not isinstance(loaded, dict):
+            _err(RuntimeError("--params-file must contain a JSON object"))
+        supplied.update(loaded)
+    try:
+        supplied.update(parse_param_args(param or []))
+    except SignalValidationError as e:
+        _err(e)
+
+    spec = None
+    if not no_fetch:
+        try:
+            spec = policy_spec_for(strategy_id, ticker=ticker, policy_id=policy_id)
+        except SignalValidationError as e:
+            _err(e)
+        except Exception as e:  # noqa: BLE001
+            _err(e)
+
+    if dry_run:
+        # Build without sending, so the same validation runs and you see the exact body.
+        from nexusquant_sdk import _policy
+
+        try:
+            body = _policy.build_signal_payload(
+                strategy_id=strategy_id,
+                strategy_name=strategy_name or strategy_id,
+                ticker=ticker, price=price, direction=direction,
+                params=supplied, spec=spec, quantity=quantity, order_type=order_type,
+            )
+        except SignalValidationError as e:
+            _err(e)
+        console.print("[dim]--dry-run: validated, not sent[/dim]")
+        console.print_json(data=body)
+        return
+
+    try:
+        resp = policy_send_signal(
+            strategy_id, strategy_name=strategy_name, ticker=ticker, price=price,
+            direction=direction, params=supplied, quantity=quantity,
+            order_type=order_type, spec=spec, fetch_spec=False,
+        )
+    except SignalValidationError as e:
+        _err(e)
+    except Exception as e:  # noqa: BLE001
+        _err(e)
+    console.print("[green]Sent[/green]")
+    console.print_json(data=resp)
+
+
+def register(app: typer.Typer) -> None:
+    app.add_typer(policy_app, name="policy")

{nexusquant_cli-0.1.2 → nexusquant_cli-0.2.0}/pyproject.toml

@@ -4,12 +4,15 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nexusquant-cli"
-version = "0.1.2"
+version = "0.2.0"
 description = "NexusQuant strategy provider CLI"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
   "httpx>=0.27",
+  # policy 命令的全部校验都在 SDK 里，这里只调不抄 —— 抄一份就会与服务端分叉，
+  # 而分叉的客户端校验比没有更糟（它给的是假信心）。
+  "nexusquant-sdk>=0.2",
   "platformdirs>=4.2",
   "rich>=13.7",
   "typer>=0.12",

nexusquant_cli-0.1.2/nexusquant_cli/__init__.py

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