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

package/dist/composer/cli.py

@@ -0,0 +1,355 @@
+"""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 status <target> [-o <dir>] — derived lifecycle position + the next verb.
+    composer catalog / describe <node>  — the registry-generated progressive-disclosure surface.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+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_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 _cmd_status(args: argparse.Namespace) -> int:
+    result = run_status(args.target, out_dir=args.out)
+    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 | 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_status = sub.add_parser(
+        "status",
+        help="Derived lifecycle position + the next verb to run (no journals; state is the file).",
+    )
+    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("--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"]