@senpi/runtime 3.0.9-dev.20260710204324 → 3.0.9-dev.feat-strategy-compos.20260716233548

package/dist/composer/cli.py

@@ -0,0 +1,487 @@
+"""cli — the ``composer`` verbs; the Python core's command surface (D7, D8).
+
+The composer is driven through a small set of verbs, all deriving their behaviour from the
+registry so the agent never reasons from stale docs:
+
+    composer new <id> --archetype X ...  — interview answers in, a COMPLETE, VALID graph
+        out, with mechanically bindable values bound and bespoke slots TODO-marked; a
+        feasibility gap report when answers reference unavailable registry names; refuses
+        to overwrite an edited graph without ``--force``.
+    composer check     — validate + port typecheck + fn-node unit tests + compile +
+        fixture smoke, collapsed into ONE verdict.
+    composer deploy    — idempotent, hard-gated on ``check``, targets the existing
+        external_scanner deploy path.
+    composer status    — position DERIVED from artifact + validation + platform state
+        (the spec file IS the state; no journals), naming the next verb.
+    composer catalog / composer describe <node>  — the registry-generated progressive
+        disclosure surface (index on demand, full ports/params/example per node).
+
+This module is the Python entry point; TypeScript appears only as a thin CLI/verdict
+wrapper (``--json``, deploy gate) in the existing ``@senpi-ai/runtime`` plugin
+(``src/cli/composer-commands.ts``, D8). All verbs are wired as of slice 7: ``new`` and
+``validate`` (slices 2/6), ``compile`` (slice 3), and the slice-7 lifecycle verbs
+``check`` / ``deploy`` / ``status`` plus the ``catalog`` / ``describe`` disclosure surface
+(implemented in ``composer.verbs``). Every verb takes ``--json`` for the TS rim.
+
+    composer validate <file> [--json]  — teaching-error report; exit 0 when clean.
+    composer check <file> [--json]      — ONE verdict (validate+tests+compile+smoke); 0 iff GREEN.
+    composer deploy <file> -o <dir>     — stage the deployable artifact set; gated on check.
+    composer fund <target> --budget N   — create + fund the strategy's wallet via MCP
+        strategy_create_custom_strategy (preflight balance → create → poll ACTIVE); idempotent,
+        writes <state>/strategies/<strategy>/wallet.json (slice B3).
+    composer install <target> [--wallet 0x…] — copy a staged unit to a canonical hash dir, bind the
+        wallet (explicit --wallet, or auto-bound from a funded wallet.json), and hand it to the
+        frozen `openclaw senpi runtime create` consumer (slice A2/B3).
+    composer close <target> [--state-dir <dir>] — safe teardown: stop the runtime, confirm gone,
+        then trigger MCP strategy_close (flattens positions + returns funds); idempotent (B1).
+    composer status <target> [-o <dir>] [--state-dir <dir>] — derived lifecycle position + the next
+        verb, extended down the on-box install chain (landed → registered → running) when a box is named.
+    composer catalog / describe <node>  — the registry-generated progressive-disclosure surface.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from composer.authoring import compose_new, load_answers, load_answers_file
+from composer.compiler import CompileError, compile_file
+from composer.validator import validate_file
+from composer.verbs import (
+    catalog_text,
+    check_file,
+    deploy_file,
+    describe_text,
+    run_close,
+    run_fund,
+    run_install,
+    run_status,
+)
+
+
+def _split_csv(value: str) -> list[str]:
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+def _new_overrides(args: argparse.Namespace) -> dict:
+    """Assemble the CLI-flag override dict (only flags the user actually passed).
+
+    Flags override the answers-file field-by-field (D7 "individual flag overrides"). Nested
+    fields (universe.*, risk.*) are placed under their sub-mapping so the deep-merge in
+    ``load_answers`` composes them with the file rather than replacing whole sub-objects.
+    """
+    over: dict = {"archetype": args.archetype, "strategy": args.id}
+    universe: dict = {}
+    risk: dict = {}
+    if args.whitelist is not None:
+        universe["whitelist"] = _split_csv(args.whitelist)
+    if args.long_basket is not None:
+        universe["long_basket"] = _split_csv(args.long_basket)
+    if args.short_basket is not None:
+        universe["short_basket"] = _split_csv(args.short_basket)
+    if args.discover:
+        universe["discover"] = True
+    if args.dex is not None:
+        universe["dex"] = args.dex
+    if args.name_prefix is not None:
+        universe["name_prefix"] = args.name_prefix
+    if args.max_leverage_cap is not None:
+        universe["max_leverage_cap"] = args.max_leverage_cap
+    if args.min_day_volume is not None:
+        universe["min_day_volume"] = args.min_day_volume
+    if universe:
+        over["universe"] = universe
+    if args.intervals is not None:
+        over["intervals"] = _split_csv(args.intervals)
+    if args.max_positions is not None:
+        over["max_positions"] = args.max_positions
+    if args.ttl_seconds is not None:
+        over["ttl_seconds"] = args.ttl_seconds
+    if args.exit_preset is not None:
+        over["exit_preset"] = args.exit_preset
+    if args.unmanaged:
+        over["unmanaged"] = True
+    if args.margin_pct is not None:
+        risk["margin_pct"] = args.margin_pct
+    if args.leverage is not None:
+        risk["leverage"] = args.leverage
+    if args.drawdown_halt_pct is not None:
+        risk["drawdown_halt_pct"] = args.drawdown_halt_pct
+    if args.max_consecutive_losses is not None:
+        risk["max_consecutive_losses"] = args.max_consecutive_losses
+    if args.cooldown_seconds is not None:
+        risk["cooldown_seconds"] = args.cooldown_seconds
+    if args.max_entries_per_day is not None:
+        risk["max_entries_per_day"] = args.max_entries_per_day
+    if risk:
+        over["risk"] = risk
+    if args.edge is not None:
+        over["edge"] = args.edge
+    return over
+
+
+def _cmd_new(args: argparse.Namespace) -> int:
+    file_data = load_answers_file(args.answers) if args.answers else None
+    try:
+        answers = load_answers(file_data, _new_overrides(args))
+    except Exception as exc:  # pydantic ValidationError etc. — a bad answer, not a crash
+        if args.json:
+            print(json.dumps({"ok": False, "error": str(exc)}, indent=2))
+        else:
+            print(f"invalid answers: {exc}", file=sys.stderr)
+        return 1
+
+    out_dir = Path(args.output) if args.output else Path.cwd()
+    out_path = out_dir / f"{args.id}.graph.yaml"
+    result = compose_new(answers, out_path, force=args.force)
+
+    if args.json:
+        print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+
+    if result.gap_report is not None:
+        if not args.json:
+            print(result.gap_report.render(), end="")
+        return 2
+    if result.clobber_refused:
+        if not args.json:
+            print(result.message, file=sys.stderr)
+        return 3
+    if not result.ok:
+        if not args.json:
+            print(result.message, file=sys.stderr)
+        return 1
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(result.yaml_text, encoding="utf-8")
+    if not args.json:
+        print(f"wrote {out_path}  ({result.message})")
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    result = validate_file(args.file)
+    if args.json:
+        print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+    else:
+        print(result.render(), end="")
+    return 0 if result.ok else 1
+
+
+def _cmd_compile(args: argparse.Namespace) -> int:
+    try:
+        source = compile_file(args.file)
+    except CompileError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(source)
+        print(f"wrote {args.output}")
+    else:
+        print(source, end="")
+    return 0
+
+
+def _cmd_check(args: argparse.Namespace) -> int:
+    result = check_file(args.file)
+    if args.json:
+        print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+    else:
+        print(result.render(), end="")
+    return 0 if result.ok else 1
+
+
+def _cmd_deploy(args: argparse.Namespace) -> int:
+    result = deploy_file(args.file, args.out)
+    if args.json:
+        print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+    else:
+        print(result.render(), end="")
+    return 0 if result.ok else 1
+
+
+def _resolve_state_dir(explicit: str | None) -> str:
+    """Base senpi-state dir for the on-box canonical layout: explicit ``--state-dir`` (the rim
+    passes the authoritative resolveSenpiBaseStateDir value) → ``SENPI_STATE_DIR`` env →
+    ``~/.openclaw/senpi-state`` default. Mirrors the env+default tail of
+    src/cli/senpi-cli-config.ts::resolveSenpiBaseStateDir (the store/plugin-stateDir precedence
+    lives in the rim; this Python fallback covers a direct-CLI invocation)."""
+    if explicit and explicit.strip():
+        return str(Path(explicit).expanduser())
+    env = os.environ.get("SENPI_STATE_DIR", "").strip()
+    if env:
+        return str(Path(env).expanduser())
+    return str(Path.home() / ".openclaw" / "senpi-state")
+
+
+def _cmd_install(args: argparse.Namespace) -> int:
+    result = run_install(
+        args.target,
+        args.wallet,
+        _resolve_state_dir(args.state_dir),
+        out_dir=args.out,
+        runtime_id=args.runtime_id,
+        bound_at=args.bound_at,
+    )
+    if args.json:
+        print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+    else:
+        print(result.render(), end="")
+    return 0 if result.ok else 1
+
+
+def _cmd_fund(args: argparse.Namespace) -> int:
+    result = run_fund(
+        args.target,
+        args.budget,
+        _resolve_state_dir(args.state_dir),
+        out_dir=args.out,
+        created_at=args.created_at,
+    )
+    if args.json:
+        print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+    else:
+        print(result.render(), end="")
+    return 0 if result.ok else 1
+
+
+def _cmd_close(args: argparse.Namespace) -> int:
+    result = run_close(
+        args.target,
+        _resolve_state_dir(args.state_dir),
+        wallet=args.wallet,
+        strategy_id=args.strategy_id,
+    )
+    if args.json:
+        print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+    else:
+        print(result.render(), end="")
+    return 0 if result.ok else 1
+
+
+def _cmd_status(args: argparse.Namespace) -> int:
+    # --state-dir opts INTO the on-box install-chain derivation; without it status stops at the
+    # deploy layer (the file-only lifecycle), exactly as before.
+    state_dir = _resolve_state_dir(args.state_dir) if args.state_dir is not None else None
+    result = run_status(args.target, out_dir=args.out, state_dir=state_dir)
+    if args.json:
+        print(json.dumps(result.to_json(), indent=2, sort_keys=True))
+    else:
+        print(result.render(), end="")
+    return 0
+
+
+def _cmd_catalog(args: argparse.Namespace) -> int:
+    if args.json:
+        print(json.dumps({"catalog": catalog_text()}, indent=2, sort_keys=True))
+    else:
+        print(catalog_text(), end="")
+    return 0
+
+
+def _cmd_describe(args: argparse.Namespace) -> int:
+    try:
+        text = describe_text(args.node)
+    except KeyError as exc:
+        msg = str(exc).strip('"')
+        if args.json:
+            print(json.dumps({"ok": False, "error": msg}, indent=2))
+        else:
+            print(msg, file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps({"ok": True, "node": args.node, "describe": text}, indent=2, sort_keys=True))
+    else:
+        print(text, end="")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="composer",
+        description="Strategy Composer — build, validate, and deploy trading strategy graphs.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_new = sub.add_parser(
+        "new",
+        help="Generate a COMPLETE, VALID strategy graph from interview answers (D7).",
+    )
+    p_new.add_argument("id", help="Strategy id; the graph is written to <id>.graph.yaml.")
+    p_new.add_argument("--archetype", required=True,
+                       help="Archetype template (trend_momentum | breakout | classifier | "
+                            "thesis_fund); an unknown one falls back to a minimal valid skeleton.")
+    p_new.add_argument("--answers", help="Path to a YAML/JSON answers-file (flags override it).")
+    p_new.add_argument("-o", "--output", help="Output directory (default: cwd).")
+    p_new.add_argument("--force", action="store_true",
+                       help="Overwrite an edited graph (default: refuse to clobber edits).")
+    p_new.add_argument("--json", action="store_true",
+                       help="Emit the structured result (path / gap report) as JSON.")
+    # individual flag overrides (D7): each overrides the answers-file field-by-field.
+    p_new.add_argument("--whitelist", help="Comma-separated fixed universe (trend_momentum).")
+    p_new.add_argument("--long-basket", dest="long_basket", help="Comma-separated LONG leg (thesis_fund).")
+    p_new.add_argument("--short-basket", dest="short_basket", help="Comma-separated SHORT leg (thesis_fund).")
+    p_new.add_argument("--discover", action="store_true", help="Derive the universe from the live board (classifier).")
+    p_new.add_argument("--dex", help="Venue filter for discovery (classifier).")
+    p_new.add_argument("--name-prefix", dest="name_prefix", help="Instrument name prefix for discovery (classifier).")
+    p_new.add_argument("--max-leverage-cap", dest="max_leverage_cap", type=float, help="Discovery leverage cap (classifier).")
+    p_new.add_argument("--min-day-volume", dest="min_day_volume", type=float, help="Discovery daily-volume floor (classifier).")
+    p_new.add_argument("--intervals", help="Comma-separated candle intervals (e.g. 1h,4h).")
+    p_new.add_argument("--max-positions", dest="max_positions", type=int, help="Cardinality: 1 = single best, >1 = pool-cap.")
+    p_new.add_argument("--ttl-seconds", dest="ttl_seconds", type=int, help="Signal-dedup TTL window (memory).")
+    p_new.add_argument("--exit-preset", dest="exit_preset",
+                       help="Exit protection preset (protected_standard | protected_tight | protected_wide); "
+                            "default protected_standard is bound if unset (protection-by-default).")
+    p_new.add_argument("--unmanaged", action="store_true",
+                       help="Deliberately opt OUT of exit protection (no exit section, loud warning). "
+                            "Without this, an exit-less unit is RED at check (CMP120).")
+    p_new.add_argument("--margin-pct", dest="margin_pct", type=float, help="Percent of withdrawable to allocate, (0,100].")
+    p_new.add_argument("--leverage", type=float, help="Requested leverage.")
+    p_new.add_argument("--drawdown-halt-pct", dest="drawdown_halt_pct", type=float,
+                       help="Guard rail: halt the whole strategy at this equity drawdown %% (0-100).")
+    p_new.add_argument("--max-consecutive-losses", dest="max_consecutive_losses", type=int,
+                       help="Guard rail: pause after N consecutive losses.")
+    p_new.add_argument("--cooldown-seconds", dest="cooldown_seconds", type=int,
+                       help="Guard rail: post-loss cooldown seconds (>= 60).")
+    p_new.add_argument("--max-entries-per-day", dest="max_entries_per_day", type=int,
+                       help="Guard rail: cap entries per day (>= 1).")
+    p_new.add_argument("--edge", help="The strategy's EDGE, carried verbatim into the graph (never interpreted).")
+    p_new.set_defaults(func=_cmd_new)
+
+    p_validate = sub.add_parser(
+        "validate",
+        help="Validate a strategy graph (schema + graph checks) with teaching errors.",
+    )
+    p_validate.add_argument("file", help="Path to the YAML strategy graph.")
+    p_validate.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit the structured result as JSON instead of the plain-text report.",
+    )
+    p_validate.set_defaults(func=_cmd_validate)
+
+    p_compile = sub.add_parser(
+        "compile",
+        help="Compile a validated strategy graph into a scan.py on the external_scanner contract.",
+    )
+    p_compile.add_argument("file", help="Path to the YAML strategy graph.")
+    p_compile.add_argument(
+        "-o",
+        "--output",
+        help="Write the emitted scan.py here (default: stdout).",
+    )
+    p_compile.set_defaults(func=_cmd_compile)
+
+    p_check = sub.add_parser(
+        "check",
+        help="ONE verdict: validate + pure_fn tests + compile + fixture smoke (exit 0 iff GREEN).",
+    )
+    p_check.add_argument("file", help="Path to the YAML strategy graph.")
+    p_check.add_argument("--json", action="store_true", help="Emit the verdict as JSON.")
+    p_check.set_defaults(func=_cmd_check)
+
+    p_deploy = sub.add_parser(
+        "deploy",
+        help="Stage the deployable artifact set (idempotent); HARD-gated on a GREEN check.",
+    )
+    p_deploy.add_argument("file", help="Path to the YAML strategy graph.")
+    p_deploy.add_argument("-o", "--out", default="dist", help="Staging directory (default: dist).")
+    p_deploy.add_argument("--json", action="store_true", help="Emit the deploy verdict as JSON.")
+    p_deploy.set_defaults(func=_cmd_deploy)
+
+    p_install = sub.add_parser(
+        "install",
+        help="Bind a staged unit onto THIS box (copy to a hash dir, bind --wallet, run "
+             "`openclaw senpi runtime create`).",
+    )
+    p_install.add_argument("target", help="A `composer deploy` staging dir, or a graph file (with -o).")
+    p_install.add_argument("--wallet",
+                           help="The strategy's ACTIVE 0x… wallet to bind. Omit to auto-bind the "
+                                "funded wallet from `composer fund` (its wallet.json), if ACTIVE.")
+    p_install.add_argument("-o", "--out", help="Staging dir (when target is a graph file, not a staged dir).")
+    p_install.add_argument("--state-dir", dest="state_dir",
+                           help="Base senpi-state dir (default: $SENPI_STATE_DIR or ~/.openclaw/senpi-state).")
+    p_install.add_argument("--runtime-id", dest="runtime_id",
+                           help="Override the derived runtime id (default: <strategy>-<hash8>).")
+    p_install.add_argument("--bound-at", dest="bound_at",
+                           help="Timestamp recorded in install.json (injected; no wall-clock default).")
+    p_install.add_argument("--json", action="store_true", help="Emit the install verdict as JSON.")
+    p_install.set_defaults(func=_cmd_install)
+
+    p_fund = sub.add_parser(
+        "fund",
+        help="Create + fund the strategy's wallet (MCP strategy_create_custom_strategy): preflights "
+             "the balance, waits for ACTIVE, safe to re-run while funding settles.",
+    )
+    p_fund.add_argument("target", help="A `composer deploy` staging dir, or a graph file (with -o).")
+    p_fund.add_argument("--budget", type=float, required=True,
+                        help="Explicit USD to fund THIS strategy's wallet with (≥ $100). Never "
+                             "derived or split — agree it with the user first.")
+    p_fund.add_argument("-o", "--out", help="Staging dir (when target is a graph file, not a staged dir).")
+    p_fund.add_argument("--state-dir", dest="state_dir",
+                        help="Base senpi-state dir (default: $SENPI_STATE_DIR or ~/.openclaw/senpi-state).")
+    p_fund.add_argument("--created-at", dest="created_at",
+                        help="Timestamp recorded in wallet.json (injected; no wall-clock default).")
+    p_fund.add_argument("--json", action="store_true", help="Emit the fund verdict as JSON.")
+    p_fund.set_defaults(func=_cmd_fund)
+
+    p_close = sub.add_parser(
+        "close",
+        help="Safe teardown: stop the runtime, confirm gone, then trigger MCP strategy_close "
+             "(flattens positions + returns funds). Idempotent — re-run to poll.",
+    )
+    p_close.add_argument("target", help="Strategy name / canonical hash dir / runtime id / 0x… "
+                                        "wallet / strategyId to close.")
+    p_close.add_argument("--wallet", help="Close the strategy on this 0x… wallet directly "
+                                          "(overrides target-based wallet resolution).")
+    p_close.add_argument("--strategy-id", dest="strategy_id",
+                         help="Close this strategyId directly (legacy/ops-deployed strategies).")
+    p_close.add_argument("--state-dir", dest="state_dir",
+                         help="Base senpi-state dir (default: $SENPI_STATE_DIR or ~/.openclaw/senpi-state).")
+    p_close.add_argument("--json", action="store_true", help="Emit the close verdict as JSON.")
+    p_close.set_defaults(func=_cmd_close)
+
+    p_status = sub.add_parser(
+        "status",
+        help="Derived lifecycle position + the next verb to run (no journals; state is the file). "
+             "Pass --state-dir to extend down the on-box install chain.",
+    )
+    p_status.add_argument("target", help="A graph YAML file, or a staging directory.")
+    p_status.add_argument("-o", "--out", help="Staging directory to check for a deployed artifact.")
+    p_status.add_argument("--state-dir", dest="state_dir",
+                          help="Base senpi-state dir — opts into the on-box install chain "
+                               "(landed → registered → running). Default when set empty: "
+                               "$SENPI_STATE_DIR or ~/.openclaw/senpi-state.")
+    p_status.add_argument("--json", action="store_true", help="Emit the status as JSON.")
+    p_status.set_defaults(func=_cmd_status)
+
+    p_catalog = sub.add_parser(
+        "catalog",
+        help="Print the registry-generated catalog index (node names + one-liners + params).",
+    )
+    p_catalog.add_argument("--json", action="store_true", help="Wrap the catalog text in JSON.")
+    p_catalog.set_defaults(func=_cmd_catalog)
+
+    p_describe = sub.add_parser(
+        "describe",
+        help="Print one node's full ports/params/example from the registry.",
+    )
+    p_describe.add_argument("node", help="Node name (see `composer catalog`).")
+    p_describe.add_argument("--json", action="store_true", help="Wrap the describe text in JSON.")
+    p_describe.set_defaults(func=_cmd_describe)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/composer/compiler/__init__.py

@@ -0,0 +1,22 @@
+"""compiler — the deterministic materializer: strategy graph -> runtime-owned scan.py.
+
+Compilation over interpretation (D5): the compiler validates the graph, topo-sorts it,
+walks per-node Jinja2 emission templates in that order, and produces straight-line Python
+targeting the existing ``external_scanner`` contract — no IR (the graph is the IR), no
+optimizer, no off-the-shelf codegen framework (D8). Semantics are compile-on-deploy with
+freeze-on-deploy (works-forever); a consent-based upgrade recompiles. Determinism is a
+hard property: the same graph must emit byte-identical ``scan.py``. Correctness is tested
+against our declared semantics via self-authored golden vectors (per-primitive known
+series -> known values, plus small composed synthetic cases with hand-computed expected
+signals), NOT by bit-diffing the hand-written corpus originals — corpus fidelity is a
+separate judged, recorded-replay oracle deferred to slice 8. (Implemented in slice 3.)
+
+Public API:
+    compile_text / compile_file — validate then materialize graph YAML into scan.py source.
+    CompileError                — invalid graph (surfaces the teaching-error report) or a
+                                  structural gap the slice-3 compiler cannot emit.
+"""
+
+from .compile import CompileError, compile_file, compile_text
+
+__all__ = ["compile_text", "compile_file", "CompileError"]