loopx 0.4.8__py3-none-any.whl

loopx/cli_commands/ml_experiment.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable
+
+from ..domain_packs.ml_experiment import (
+    GUARDRAIL_STATUSES,
+    HYPOTHESIS_STATUSES,
+    VOLC_MLP_TASK_STATES,
+    build_ml_experiment_advisory_packet,
+    build_volc_mlp_result_ledger,
+    build_volc_mlp_task_packet,
+    default_ml_experiment_domain_state_ledger_path,
+    render_ml_experiment_advisory_markdown,
+    render_volc_mlp_result_ledger_markdown,
+    render_volc_mlp_task_packet_markdown,
+    upsert_ml_experiment_ledger_jsonl,
+)
+
+
+PrintPayload = Callable[
+    [dict[str, object], str, Callable[[dict[str, object]], str]],
+    None,
+]
+FormatSelector = Callable[..., str]
+AddFormat = Callable[[argparse.ArgumentParser], None]
+
+
+def register_ml_experiment_commands(
+    subparsers: argparse._SubParsersAction,
+    add_subcommand_format: AddFormat,
+) -> None:
+    ml_experiment_parser = subparsers.add_parser(
+        "ml-experiment",
+        help="Render default-off ML experiment advisory packets.",
+    )
+    ml_experiment_sub = ml_experiment_parser.add_subparsers(dest="ml_experiment_command", required=True)
+    preview_parser = ml_experiment_sub.add_parser(
+        "preview",
+        help="Preview a public-safe ML experiment result, hypothesis ledger, and replan packet.",
+    )
+    add_subcommand_format(preview_parser)
+    preview_parser.add_argument("--experiment-id", required=True, help="Public experiment id.")
+    preview_parser.add_argument("--primary-metric", required=True, help="Primary metric label.")
+    preview_parser.add_argument("--baseline-value", type=float, required=True)
+    preview_parser.add_argument("--candidate-value", type=float, required=True)
+    metric_direction = preview_parser.add_mutually_exclusive_group()
+    metric_direction.add_argument(
+        "--higher-is-better",
+        dest="higher_is_better",
+        action="store_true",
+        default=True,
+        help="Classify positive metric deltas as improvements. This is the default.",
+    )
+    metric_direction.add_argument(
+        "--lower-is-better",
+        dest="higher_is_better",
+        action="store_false",
+        help="Classify negative metric deltas as improvements.",
+    )
+    preview_parser.add_argument(
+        "--guardrail-status",
+        choices=GUARDRAIL_STATUSES,
+        default="unknown",
+        help="Compact guardrail classification.",
+    )
+    preview_parser.add_argument("--train-window", required=True)
+    preview_parser.add_argument("--eval-window", required=True)
+    preview_parser.add_argument("--granularity", default="daily")
+    preview_parser.add_argument("--hypothesis-id", required=True)
+    preview_parser.add_argument("--mechanism-family", required=True)
+    preview_parser.add_argument("--route", required=True)
+    preview_parser.add_argument(
+        "--hypothesis-status",
+        choices=HYPOTHESIS_STATUSES,
+        default="active",
+    )
+    preview_parser.add_argument(
+        "--positive-evidence",
+        action="append",
+        default=[],
+        help="Compact public-safe evidence label. Repeatable.",
+    )
+    preview_parser.add_argument(
+        "--negative-evidence",
+        action="append",
+        default=[],
+        help="Compact public-safe evidence label. Repeatable.",
+    )
+    preview_parser.add_argument(
+        "--next-candidate",
+        action="append",
+        default=[],
+        help="Compact public-safe follow-up candidate label. Repeatable.",
+    )
+
+    volc_parser = ml_experiment_sub.add_parser(
+        "volc-task-packet",
+        help="Render a public-safe Volc/MLP external task packet.",
+    )
+    add_subcommand_format(volc_parser)
+    volc_parser.add_argument("--task-id", required=True, help="Volc task id, for example t-... .")
+    volc_parser.add_argument("--task-name", required=True, help="Compact public task label.")
+    volc_parser.add_argument("--state", choices=VOLC_MLP_TASK_STATES, default="Unknown")
+    volc_parser.add_argument("--priority", type=int)
+    volc_parser.add_argument("--retried-times", type=int)
+    volc_parser.add_argument("--train-window", required=True)
+    volc_parser.add_argument("--eval-window", required=True)
+    volc_parser.add_argument("--code-ref", required=True, help="Branch, commit, or other public code alias.")
+    volc_parser.add_argument("--model-name", required=True)
+    volc_parser.add_argument("--mechanism-family", default="unknown")
+    volc_parser.add_argument("--source-task-id")
+    volc_parser.add_argument(
+        "--workspace-ref",
+        help="Optional workspace handle. Raw paths or URLs are redacted in output.",
+    )
+    volc_parser.add_argument(
+        "--metric-ref",
+        action="append",
+        default=[],
+        help="Optional metric artifact handle. Raw paths or URLs are redacted in output. Repeatable.",
+    )
+    volc_parser.add_argument(
+        "--ledger-path",
+        help="Optional local JSONL ledger path. Overrides the default project-local domain-state path.",
+    )
+    volc_parser.add_argument(
+        "--goal-id",
+        help="Goal id used for the default .loopx/domain-state/<goal-id>/ml_experiment/ledger.jsonl path.",
+    )
+    volc_parser.add_argument("--project", default=".", help="Project root for the default domain-state ledger path.")
+    volc_parser.add_argument("--primary-metric", default="offline_auc")
+    volc_parser.add_argument(
+        "--guardrail-metric",
+        action="append",
+        default=[],
+        help="Compact guardrail metric label. Repeatable.",
+    )
+    volc_parser.add_argument("--next-action", default="monitor_task_until_terminal_metrics")
+
+    volc_result_parser = ml_experiment_sub.add_parser(
+        "volc-result-ledger",
+        help="Render a public-safe Volc/MLP benchmark result ledger row.",
+    )
+    add_subcommand_format(volc_result_parser)
+    volc_result_parser.add_argument("--experiment-id", required=True)
+    volc_result_parser.add_argument("--task-id", required=True, help="Volc task id, for example t-... .")
+    volc_result_parser.add_argument("--task-name", required=True, help="Compact public task label.")
+    volc_result_parser.add_argument("--state", choices=VOLC_MLP_TASK_STATES, default="Unknown")
+    volc_result_parser.add_argument("--priority", type=int)
+    volc_result_parser.add_argument("--retried-times", type=int)
+    volc_result_parser.add_argument("--train-window", required=True)
+    volc_result_parser.add_argument("--eval-window", required=True)
+    volc_result_parser.add_argument("--code-ref", required=True, help="Branch, commit, or other public code alias.")
+    volc_result_parser.add_argument("--model-name", required=True)
+    volc_result_parser.add_argument("--mechanism-family", default="unknown")
+    volc_result_parser.add_argument("--primary-metric", default="offline_auc")
+    volc_result_parser.add_argument("--baseline-value", type=float)
+    volc_result_parser.add_argument("--candidate-value", type=float)
+    result_metric_direction = volc_result_parser.add_mutually_exclusive_group()
+    result_metric_direction.add_argument(
+        "--higher-is-better",
+        dest="higher_is_better",
+        action="store_true",
+        default=True,
+        help="Classify positive metric deltas as improvements. This is the default.",
+    )
+    result_metric_direction.add_argument(
+        "--lower-is-better",
+        dest="higher_is_better",
+        action="store_false",
+        help="Classify negative metric deltas as improvements.",
+    )
+    volc_result_parser.add_argument(
+        "--guardrail-status",
+        choices=GUARDRAIL_STATUSES,
+        default="unknown",
+    )
+    volc_result_parser.add_argument("--baseline-task-id")
+    volc_result_parser.add_argument("--source-task-id")
+    volc_result_parser.add_argument(
+        "--workspace-ref",
+        help="Optional workspace handle. Raw paths or URLs are redacted in output.",
+    )
+    volc_result_parser.add_argument(
+        "--metric-ref",
+        action="append",
+        default=[],
+        help="Optional metric artifact handle. Raw paths or URLs are redacted in output. Repeatable.",
+    )
+    volc_result_parser.add_argument(
+        "--ledger-path",
+        help="Optional local JSONL ledger path. Overrides the default project-local domain-state path.",
+    )
+    volc_result_parser.add_argument(
+        "--goal-id",
+        help="Goal id used for the default .loopx/domain-state/<goal-id>/ml_experiment/ledger.jsonl path.",
+    )
+    volc_result_parser.add_argument("--project", default=".", help="Project root for the default domain-state ledger path.")
+    volc_result_parser.add_argument(
+        "--guardrail-metric",
+        action="append",
+        default=[],
+        help="Compact guardrail metric label. Repeatable.",
+    )
+    volc_result_parser.add_argument(
+        "--positive-evidence",
+        action="append",
+        default=[],
+        help="Compact public-safe evidence label. Repeatable.",
+    )
+    volc_result_parser.add_argument(
+        "--negative-evidence",
+        action="append",
+        default=[],
+        help="Compact public-safe evidence label. Repeatable.",
+    )
+    volc_result_parser.add_argument(
+        "--failure-label",
+        action="append",
+        default=[],
+        help="Compact public-safe failure attribution label. Repeatable.",
+    )
+    volc_result_parser.add_argument("--next-action")
+
+
+def handle_ml_experiment_command(
+    args: argparse.Namespace,
+    *,
+    output_format: FormatSelector,
+    print_payload: PrintPayload,
+) -> int:
+    try:
+        if args.ml_experiment_command == "preview":
+            payload = build_ml_experiment_advisory_packet(
+                experiment_id=args.experiment_id,
+                primary_metric=args.primary_metric,
+                baseline_value=args.baseline_value,
+                candidate_value=args.candidate_value,
+                higher_is_better=bool(args.higher_is_better),
+                guardrail_status=args.guardrail_status,
+                train_window=args.train_window,
+                eval_window=args.eval_window,
+                granularity=args.granularity,
+                hypothesis_id=args.hypothesis_id,
+                mechanism_family=args.mechanism_family,
+                route=args.route,
+                hypothesis_status=args.hypothesis_status,
+                positive_evidence=args.positive_evidence,
+                negative_evidence=args.negative_evidence,
+                next_candidates=args.next_candidate,
+            )
+            renderer = render_ml_experiment_advisory_markdown
+        elif args.ml_experiment_command == "volc-task-packet":
+            payload = build_volc_mlp_task_packet(
+                task_id=args.task_id,
+                task_name=args.task_name,
+                state=args.state,
+                priority=args.priority,
+                retried_times=args.retried_times,
+                train_window=args.train_window,
+                eval_window=args.eval_window,
+                code_ref=args.code_ref,
+                model_name=args.model_name,
+                mechanism_family=args.mechanism_family,
+                source_task_id=args.source_task_id,
+                workspace_ref=args.workspace_ref,
+                metric_refs=args.metric_ref,
+                primary_metric=args.primary_metric,
+                guardrail_metrics=args.guardrail_metric,
+                next_action=args.next_action,
+            )
+            renderer = render_volc_mlp_task_packet_markdown
+        elif args.ml_experiment_command == "volc-result-ledger":
+            payload = build_volc_mlp_result_ledger(
+                experiment_id=args.experiment_id,
+                task_id=args.task_id,
+                task_name=args.task_name,
+                state=args.state,
+                priority=args.priority,
+                retried_times=args.retried_times,
+                train_window=args.train_window,
+                eval_window=args.eval_window,
+                code_ref=args.code_ref,
+                model_name=args.model_name,
+                mechanism_family=args.mechanism_family,
+                primary_metric=args.primary_metric,
+                baseline_value=args.baseline_value,
+                candidate_value=args.candidate_value,
+                higher_is_better=bool(args.higher_is_better),
+                guardrail_status=args.guardrail_status,
+                baseline_task_id=args.baseline_task_id,
+                source_task_id=args.source_task_id,
+                workspace_ref=args.workspace_ref,
+                metric_refs=args.metric_ref,
+                guardrail_metrics=args.guardrail_metric,
+                positive_evidence=args.positive_evidence,
+                negative_evidence=args.negative_evidence,
+                failure_labels=args.failure_label,
+                next_action=args.next_action,
+            )
+            renderer = render_volc_mlp_result_ledger_markdown
+        else:
+            raise ValueError("ml-experiment requires a supported subcommand")
+        ledger_path = getattr(args, "ledger_path", None)
+        if not ledger_path and getattr(args, "goal_id", None):
+            ledger_path = default_ml_experiment_domain_state_ledger_path(
+                project=getattr(args, "project", "."),
+                goal_id=args.goal_id,
+            )
+        if ledger_path:
+            payload["ledger_write"] = upsert_ml_experiment_ledger_jsonl(ledger_path, payload)
+    except Exception as exc:
+        payload = {
+            "ok": False,
+            "mode": "ml-experiment",
+            "error": str(exc),
+        }
+        renderer = render_ml_experiment_advisory_markdown
+    print_payload(payload, output_format(args), renderer)
+    return 0 if payload.get("ok") else 1

loopx/cli_commands/multi_agent.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Callable
+from pathlib import Path
+
+from ..history import load_registry
+from ..paths import resolve_runtime_root
+from ..visible_multi_agent_launcher import (
+    build_visible_multi_agent_payload_from_spec,
+    execute_visible_multi_agent_launcher,
+    wake_visible_multi_agent_panes,
+)
+
+
+PrintPayload = Callable[
+    [dict[str, object], str, Callable[[dict[str, object]], str]],
+    None,
+]
+FormatSelector = Callable[..., str]
+AddFormat = Callable[[argparse.ArgumentParser], None]
+
+
+def register_multi_agent_commands(
+    subparsers: argparse._SubParsersAction,
+    add_subcommand_format: AddFormat,
+) -> None:
+    parser = subparsers.add_parser(
+        "multi-agent",
+        help="Launch visible Codex TUI agents from a small role spec.",
+    )
+    multi_agent_sub = parser.add_subparsers(dest="multi_agent_command", required=True)
+    launch = multi_agent_sub.add_parser(
+        "launch",
+        help="Preview or launch a tmux session with one interactive Codex TUI per role.",
+    )
+    add_subcommand_format(launch)
+    launch.add_argument("--spec", required=True, help="Path to a generic_multi_agent_launch_spec_v0 JSON file.")
+    launch.add_argument("--execute", action="store_true", help="Start the visible TUI session. Omit for preview.")
+    launch.add_argument("--workspace", help="Workspace root for all lanes. Defaults to the current directory.")
+    launch.add_argument("--create-workspace", action="store_true", help="Create --workspace if it is missing.")
+    launch.add_argument("--session-name", help="Override spec.session_name.")
+    launch.add_argument("--reasoning-effort", help="Override spec.default_reasoning_effort.")
+    launch.add_argument("--launcher", choices=["auto", "tmux"], default="tmux")
+    launch.add_argument("--tmux-bin", default="tmux")
+    launch.add_argument("--cli-bin", default="loopx")
+    launch.add_argument("--codex-bin", default="codex")
+    launch.add_argument("--attach", action="store_true", help="Attach to the session after launch.")
+    launch.add_argument("--replace-existing", action="store_true", help="Replace an existing session of the same name.")
+    launch.add_argument(
+        "--auto-wake",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help=(
+            "Run a session-scoped background wake loop. The loop only broadcasts "
+            "the fixed pane-local A2A prompt; each pane still reads its own state."
+        ),
+    )
+    launch.add_argument(
+        "--auto-wake-interval-seconds",
+        type=float,
+        default=45.0,
+        help=argparse.SUPPRESS,
+    )
+    launch.add_argument(
+        "--codex-trust-workspace",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="Pass a trusted project config to each Codex TUI lane.",
+    )
+    wake = multi_agent_sub.add_parser(
+        "wake",
+        help="Broadcast the fixed pane-local A2A prompt to live visible Codex TUI panes.",
+    )
+    add_subcommand_format(wake)
+    wake.add_argument("--session-name", required=True, help="tmux session to wake.")
+    wake.add_argument(
+        "--lane",
+        action="append",
+        default=[],
+        help="Specific pane/window name to wake. Repeat to target multiple panes. Omit with --execute to list the session windows.",
+    )
+    wake.add_argument("--tmux-bin", default="tmux")
+    wake.add_argument("--execute", action="store_true", help="Send the fixed prompt to tmux panes.")
+
+
+def _load_spec(path: Path) -> dict[str, object]:
+    with path.open(encoding="utf-8") as handle:
+        value = json.load(handle)
+    if not isinstance(value, dict):
+        raise ValueError("multi-agent spec must be a JSON object")
+    return value
+
+
+def _render_multi_agent_launch_markdown(payload: dict[str, object]) -> str:
+    if not payload.get("ok"):
+        return f"LoopX multi-agent launch failed: {payload.get('error')}"
+    lanes = [lane for lane in payload.get("lanes", []) if isinstance(lane, dict)]
+    lines = [
+        "# LoopX Multi-Agent Launch",
+        f"- mode: {payload.get('mode')}",
+        f"- goal: {payload.get('goal_id')}",
+        f"- session: {payload.get('session_name')}",
+        f"- roles: {len(lanes)}",
+    ]
+    for lane in lanes:
+        lines.append(
+            f"- {lane.get('lane_id')}: {lane.get('role_id')} "
+            f"({lane.get('agent_id')})"
+        )
+    commands = payload.get("commands") if isinstance(payload.get("commands"), dict) else {}
+    if commands.get("attach"):
+        lines.append("")
+        lines.append(f"attach: `{commands.get('attach')}`")
+    launch_result = payload.get("launch_result")
+    if isinstance(launch_result, dict):
+        accepted = (
+            launch_result.get("visible_acceptance", {})
+            if isinstance(launch_result.get("visible_acceptance"), dict)
+            else {}
+        )
+        lines.append("")
+        lines.append(f"visible accepted: {accepted.get('accepted')}")
+        lines.append(f"started lanes: {', '.join(str(item) for item in launch_result.get('started_lanes', []))}")
+    return "\n".join(lines)
+
+
+def _render_multi_agent_wake_markdown(payload: dict[str, object]) -> str:
+    if not payload.get("ok"):
+        return f"LoopX multi-agent wake failed: {payload.get('error')}"
+    lines = [
+        "# LoopX Multi-Agent Wake",
+        f"- mode: {payload.get('mode')}",
+        f"- session: {payload.get('session_name')}",
+        f"- wakeup_model: {payload.get('wakeup_model')}",
+        f"- coordination_model: {payload.get('coordination_model')}",
+        f"- workflow_driver: {payload.get('workflow_driver')}",
+        f"- target_lanes: {', '.join(str(item) for item in payload.get('target_lanes') or [])}",
+    ]
+    return "\n".join(lines)
+
+
+def handle_multi_agent_command(
+    args: argparse.Namespace,
+    *,
+    registry_path: Path,
+    runtime_root_arg: str | None,
+    output_format: FormatSelector,
+    print_payload: PrintPayload,
+) -> int | None:
+    if args.command != "multi-agent":
+        return None
+    try:
+        if args.multi_agent_command == "wake":
+            payload = wake_visible_multi_agent_panes(
+                session_name=args.session_name,
+                tmux_bin=args.tmux_bin,
+                lanes=args.lane,
+                execute=bool(args.execute),
+            )
+            print_payload(payload, output_format(args), _render_multi_agent_wake_markdown)
+            return 0
+        if args.multi_agent_command != "launch":
+            raise ValueError("multi-agent requires the `launch` or `wake` subcommand")
+        spec_path = Path(args.spec).expanduser()
+        spec = _load_spec(spec_path)
+        if args.session_name:
+            spec = {**spec, "session_name": args.session_name}
+        if args.reasoning_effort:
+            spec = {**spec, "default_reasoning_effort": args.reasoning_effort}
+        payload = build_visible_multi_agent_payload_from_spec(
+            spec,
+            tmux_bin=args.tmux_bin,
+            cli_bin=args.cli_bin,
+            codex_bin=args.codex_bin,
+        )
+        if args.execute:
+            registry = load_registry(registry_path)
+            runtime_root = resolve_runtime_root(registry, runtime_root_arg)
+            launch_result, chosen, workspace_mode = execute_visible_multi_agent_launcher(
+                payload=payload,
+                registry=registry_path,
+                runtime_root=runtime_root,
+                requested_launcher=args.launcher,
+                tmux_bin=args.tmux_bin,
+                cli_bin=args.cli_bin,
+                codex_bin=args.codex_bin,
+                attach=bool(args.attach),
+                replace_existing=bool(args.replace_existing),
+                workspace=args.workspace,
+                create_workspace=bool(args.create_workspace),
+                cwd=Path.cwd(),
+                codex_trust_workspace=bool(args.codex_trust_workspace),
+                source_root=spec_path.parent,
+                auto_wake=bool(args.auto_wake),
+                auto_wake_interval_seconds=args.auto_wake_interval_seconds,
+            )
+            payload["mode"] = "execute"
+            payload["chosen_launcher"] = chosen
+            payload["workspace_mode"] = workspace_mode
+            payload["launch_result"] = launch_result
+            payload["boundary"] = {
+                **payload["boundary"],
+                "starts_visible_processes": True,
+                "runs_agent_processes": True,
+            }
+    except Exception as exc:
+        payload = {"ok": False, "mode": "multi-agent", "error": str(exc)}
+    print_payload(payload, output_format(args), _render_multi_agent_launch_markdown)
+    return 0 if payload.get("ok") else 1