arctx-cli 0.2.0b2__py3-none-any.whl

arctx_cli/commands/sync.py

@@ -0,0 +1,244 @@
+"""arctx CLI sync command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+from arctx_cli.context import resolve_run_id_from_args, resolve_store, resolve_user_id_from_args
+
+
+def _sync_local():
+    from arctx.core.sync import local
+
+    return local
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser(
+        "sync",
+        help="Synchronize a local run with a file-backed shared DAG",
+    )
+    commands = parser.add_subparsers(dest="sync_command", required=True)
+
+    init = commands.add_parser("init", help="Initialize sync for a local run")
+    _add_common_args(init)
+    init.add_argument("--shared-run", required=True, dest="shared_run_id")
+    init.add_argument("--workspace", default=None, dest="workspace_id")
+    init.add_argument("--user", default=None)
+
+    status = commands.add_parser("status", help="Show local/shared sync status")
+    _add_common_args(status)
+    status.add_argument("--shared-run", default=None, dest="shared_run_id")
+
+    push = commands.add_parser("push", help="Push local records to the shared DAG")
+    _add_common_args(push)
+    push.add_argument("--shared-run", default=None, dest="shared_run_id")
+    push.add_argument("--workspace", default=None, dest="workspace_id")
+    push.add_argument("--user", default=None)
+
+    pull = commands.add_parser("pull", help="Pull shared DAG records into the local run")
+    _add_common_args(pull)
+    pull.add_argument("--shared-run", default=None, dest="shared_run_id")
+
+    return parser
+
+
+def _add_common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--run", default=None)
+    parser.add_argument("--store-dir", default=None)
+    parser.add_argument("--remote", default=None)
+    parser.add_argument("--remote-dir", default=None)
+
+
+def run_sync_init_command(
+    *,
+    run_id: str,
+    shared_run_id: str,
+    store_dir: str,
+    remote: str = "local-shared",
+    remote_dir: str | None = None,
+    workspace_id: str | None = None,
+    actor_id: str = "user",
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    sync = _sync_local()
+    return sync.sync_init(
+        handle=handle,
+        run_path=store.run_path(run_id),
+        remote=remote,
+        shared_run_id=shared_run_id,
+        remote_dir=remote_dir or str(sync.default_remote_dir(store_dir)),
+        workspace_id=workspace_id or _default_workspace_id(),
+        actor_id=actor_id,
+    )
+
+
+def run_sync_status_command(
+    *,
+    run_id: str,
+    store_dir: str,
+    shared_run_id: str | None = None,
+    remote: str | None = None,
+    remote_dir: str | None = None,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    cfg = _resolve_sync_config(
+        run_path=store.run_path(run_id),
+        shared_run_id=shared_run_id,
+        remote=remote,
+        remote_dir=remote_dir,
+        store_dir=store_dir,
+    )
+    sync = _sync_local()
+    return sync.sync_status(
+        handle=handle,
+        remote=cfg["remote"],
+        shared_run_id=cfg["shared_run_id"],
+        remote_dir=cfg["remote_dir"],
+    )
+
+
+def run_sync_push_command(
+    *,
+    run_id: str,
+    store_dir: str,
+    shared_run_id: str | None = None,
+    remote: str | None = None,
+    remote_dir: str | None = None,
+    workspace_id: str | None = None,
+    actor_id: str = "user",
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    cfg = _resolve_sync_config(
+        run_path=store.run_path(run_id),
+        shared_run_id=shared_run_id,
+        remote=remote,
+        remote_dir=remote_dir,
+        store_dir=store_dir,
+    )
+    sync = _sync_local()
+    return sync.sync_push(
+        handle=handle,
+        remote=cfg["remote"],
+        shared_run_id=cfg["shared_run_id"],
+        remote_dir=cfg["remote_dir"],
+        workspace_id=workspace_id or cfg.get("workspace_id") or _default_workspace_id(),
+        actor_id=actor_id,
+    )
+
+
+def run_sync_pull_command(
+    *,
+    run_id: str,
+    store_dir: str,
+    shared_run_id: str | None = None,
+    remote: str | None = None,
+    remote_dir: str | None = None,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    cfg = _resolve_sync_config(
+        run_path=store.run_path(run_id),
+        shared_run_id=shared_run_id,
+        remote=remote,
+        remote_dir=remote_dir,
+        store_dir=store_dir,
+    )
+    sync = _sync_local()
+    result = sync.sync_pull(
+        handle=handle,
+        remote=cfg["remote"],
+        shared_run_id=cfg["shared_run_id"],
+        remote_dir=cfg["remote_dir"],
+    )
+    store.save_run(handle)
+    return result
+
+
+def cli_sync(args) -> int:
+    if args.sync_command == "init":
+        result = run_sync_init_command(
+            run_id=resolve_run_id_from_args(args),
+            shared_run_id=args.shared_run_id,
+            store_dir=args.store_dir,
+            remote=args.remote or "local-shared",
+            remote_dir=args.remote_dir,
+            workspace_id=args.workspace_id,
+            actor_id=resolve_user_id_from_args(args),
+        )
+    elif args.sync_command == "status":
+        result = run_sync_status_command(
+            run_id=resolve_run_id_from_args(args),
+            store_dir=args.store_dir,
+            shared_run_id=args.shared_run_id,
+            remote=args.remote,
+            remote_dir=args.remote_dir,
+        )
+    elif args.sync_command == "push":
+        result = run_sync_push_command(
+            run_id=resolve_run_id_from_args(args),
+            store_dir=args.store_dir,
+            shared_run_id=args.shared_run_id,
+            remote=args.remote,
+            remote_dir=args.remote_dir,
+            workspace_id=args.workspace_id,
+            actor_id=resolve_user_id_from_args(args),
+        )
+    elif args.sync_command == "pull":
+        result = run_sync_pull_command(
+            run_id=resolve_run_id_from_args(args),
+            store_dir=args.store_dir,
+            shared_run_id=args.shared_run_id,
+            remote=args.remote,
+            remote_dir=args.remote_dir,
+        )
+    else:
+        return 1
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+def _resolve_sync_config(
+    *,
+    run_path: Path,
+    shared_run_id: str | None,
+    remote: str | None,
+    remote_dir: str | None,
+    store_dir: str,
+) -> dict[str, str]:
+    if shared_run_id is None or remote is None or remote_dir is None:
+        try:
+            cfg = _sync_local().load_sync_config(run_path)
+        except RuntimeError:
+            if shared_run_id is None:
+                raise
+            cfg = {}
+    else:
+        cfg = {}
+    return {
+        "shared_run_id": shared_run_id or cfg["shared_run_id"],
+        "remote": remote or cfg.get("remote", "local-shared"),
+        "remote_dir": remote_dir
+        or cfg.get("remote_dir", str(_sync_local().default_remote_dir(store_dir))),
+        "workspace_id": cfg.get("workspace_id", _default_workspace_id()),
+        "actor_id": cfg.get("actor_id", "user"),
+    }
+
+
+def _default_workspace_id() -> str:
+    return os.environ.get("ARCTX_WORKSPACE_ID") or "local"

arctx_cli/commands/trace.py

@@ -0,0 +1,46 @@
+"""arctx CLI trace command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from arctx_cli.context import resolve_store, resolve_run_id_from_args
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("trace", help="Trace observed history from a node")
+    parser.add_argument("--run", default=None)
+    parser.add_argument("--from-node", required=True)
+    parser.add_argument("--depth", type=int, default=None)
+    parser.add_argument("--store-dir", default=None)
+    return parser
+
+
+def run_trace_command(
+    *,
+    run_id: str,
+    from_node_id: str,
+    depth: int | None,
+    store_dir: str,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    history = handle.trace(
+        from_node_id,
+        depth=depth,
+    )
+    return {"history": history.to_dict()}
+
+
+def cli_trace(args) -> int:
+    result = run_trace_command(
+        run_id=resolve_run_id_from_args(args),
+        from_node_id=args.from_node,
+        depth=args.depth,
+        store_dir=args.store_dir,
+    )
+    print(json.dumps(result["history"], ensure_ascii=False, indent=2))
+    return 0

arctx_cli/commands/transition.py

@@ -0,0 +1,212 @@
+"""arctx CLI transition command."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from arctx_cli.commands.outcomes import run_outcomes_command
+from arctx_cli.commands.show import run_show_command
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+    resolve_work_session_id_from_args,
+)
+from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.payload_builder import build_payload, parse_field_args, parse_json_object
+from arctx.core.schema.payloads import TransitionPayload
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser(
+        "transition",
+        help="Create and inspect transitions",
+    )
+    transition_sub = parser.add_subparsers(dest="transition_command", required=True)
+
+    sp_create = transition_sub.add_parser(
+        "create",
+        help="Create one Transition and one output Node from input nodes",
+    )
+    sp_create.add_argument("--run", default=None)
+    sp_create.add_argument(
+        "--from",
+        action="append",
+        required=True,
+        dest="input_nodes",
+        metavar="NODE_ID",
+        help="Input node (repeatable for multi-node transitions)",
+    )
+    sp_create.add_argument("--payload-type", default="transition_payload")
+    sp_create.add_argument("--field", action="append", default=None, help="Payload field as key=value")
+    sp_create.add_argument("--json", default=None, help="Payload fields as a JSON object")
+    sp_create.add_argument("--store-dir", default=None)
+    sp_create.add_argument("--user", default=None)
+    sp_create.add_argument("--work-session", default=None)
+
+    sp_show = transition_sub.add_parser("show", help="Show one transition")
+    sp_show.add_argument("transition_id")
+    sp_show.add_argument("--with-payloads", action="store_true")
+    sp_show.add_argument("--run", default=None)
+    sp_show.add_argument("--store-dir", default=None)
+
+    sp_output = transition_sub.add_parser("output", help="Show a transition output node")
+    sp_output.add_argument("transition_id")
+    sp_output.add_argument("--run", default=None)
+    sp_output.add_argument("--store-dir", default=None)
+
+    sp_inputs = transition_sub.add_parser("inputs", help="Show transition input nodes")
+    sp_inputs.add_argument("transition_id")
+    sp_inputs.add_argument("--run", default=None)
+    sp_inputs.add_argument("--store-dir", default=None)
+
+    sp_payloads = transition_sub.add_parser("payloads", help="Show transition payloads")
+    sp_payloads.add_argument("transition_id")
+    sp_payloads.add_argument("--run", default=None)
+    sp_payloads.add_argument("--store-dir", default=None)
+    return parser
+
+
+def run_transition_command(
+    *,
+    run_id: str,
+    input_node_ids: list[str],
+    payload_type: str,
+    content: dict,
+    store_dir: str,
+    user_id: str | None = None,
+    work_session_id: str | None = None,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    payload = TransitionPayload(
+        payload_id="pending",
+        target_id="pending",
+        type=payload_type,
+        content=content,
+    )
+    before = graph_counts(handle)
+    transition = handle.transition(
+        input_node_ids,
+        payload,
+        user_id=user_id,
+        work_session_id=work_session_id,
+    )
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        before=before,
+    )
+    return {"transition": transition.to_dict()}
+
+
+def run_transition_create_command(
+    *,
+    run_id: str,
+    input_node_ids: list[str],
+    payload_type: str,
+    field_data: dict,
+    json_data: dict,
+    store_dir: str,
+    user_id: str | None = None,
+    work_session_id: str | None = None,
+) -> dict:
+    store = resolve_store(store_dir)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+    payload = build_payload(
+        payload_type=payload_type,
+        target_kind="transition",
+        target_id="pending",
+        payload_id="pending",
+        json_data=json_data,
+        field_data=field_data,
+    )
+    before = graph_counts(handle)
+    transition = handle.transition(
+        input_node_ids,
+        payload,
+        user_id=user_id,
+        work_session_id=work_session_id,
+    )
+    maybe_append_or_save(
+        store=store,
+        handle=handle,
+        user_id=user_id,
+        work_session_id=work_session_id,
+        before=before,
+    )
+    return {"transition": transition.to_dict()}
+
+
+def cli_transition(args) -> int:
+    try:
+        if args.transition_command == "create":
+            result = run_transition_create_command(
+                run_id=resolve_run_id_from_args(args),
+                input_node_ids=args.input_nodes,
+                payload_type=args.payload_type,
+                field_data=parse_field_args(args.field),
+                json_data=parse_json_object(args.json),
+                store_dir=args.store_dir,
+                user_id=resolve_user_id_from_args(args),
+                work_session_id=resolve_work_session_id_from_args(args),
+            )
+            print(json.dumps(result["transition"], ensure_ascii=False, indent=2))
+            return 0
+        if args.transition_command == "show":
+            result = run_show_command(
+                run_id=resolve_run_id_from_args(args),
+                node_id=None,
+                transition_id=args.transition_id,
+                payload_id=None,
+                with_payloads=args.with_payloads,
+                outputs=True,
+                store_dir=args.store_dir,
+            )
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+            return 0
+        if args.transition_command == "output":
+            result = run_outcomes_command(
+                run_id=resolve_run_id_from_args(args),
+                transition_id=args.transition_id,
+                include_payloads=False,
+                store_dir=args.store_dir,
+            )
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+            return 0
+        if args.transition_command == "inputs":
+            result = run_show_command(
+                run_id=resolve_run_id_from_args(args),
+                node_id=None,
+                transition_id=args.transition_id,
+                payload_id=None,
+                with_payloads=False,
+                outputs=False,
+                store_dir=args.store_dir,
+            )
+            print(json.dumps({"input_node_ids": result["input_node_ids"]}, ensure_ascii=False, indent=2))
+            return 0
+        if args.transition_command == "payloads":
+            result = run_show_command(
+                run_id=resolve_run_id_from_args(args),
+                node_id=None,
+                transition_id=args.transition_id,
+                payload_id=None,
+                with_payloads=True,
+                outputs=False,
+                store_dir=args.store_dir,
+            )
+            print(json.dumps(result["payloads"], ensure_ascii=False, indent=2))
+            return 0
+    except (KeyError, ValueError, json.JSONDecodeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0

arctx_cli/commands/use.py

@@ -0,0 +1,67 @@
+"""arctx CLI use command."""
+
+from __future__ import annotations
+
+import argparse
+
+from arctx_cli.context import resolve_store
+from arctx_cli.paths import find_repo_root, resolve_store_dir, arctx_id_path, write_arctx_id
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    """Register the ``use`` subcommand parser."""
+    parser = subparsers.add_parser(
+        "use", help="Set the current run (writes <gitdir>/arctx-id)"
+    )
+    parser.add_argument("run_id", help="Run identifier")
+    parser.add_argument(
+        "--store-dir",
+        default=None,
+        help="Directory where runs are stored (default: <ARCTX_HOME>/runs)",
+    )
+    return parser
+
+
+def run_use_command(
+    *,
+    run_id: str,
+    store_dir: str | None,
+) -> dict:
+    """Set the current run by writing its id to ``<gitdir>/arctx-id``.
+
+    Parameters
+    ----------
+    run_id:
+        Identifier of the run.
+    store_dir:
+        Directory where runs are stored.
+
+    Returns
+    -------
+    dict with ``run_id`` and ``arctx_id_path`` keys.
+
+    Raises
+    ------
+    KeyError
+        If the run_id does not exist in the store.
+    RuntimeError
+        If not inside a git repository.
+    """
+    resolved_store_dir = store_dir if store_dir is not None else resolve_store_dir()
+    store = resolve_store(resolved_store_dir)
+    run_path = store.run_path(run_id)
+    if not run_path.exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    repo_root = find_repo_root()
+    write_arctx_id(repo_root, run_id)
+    return {"run_id": run_id, "arctx_id_path": str(arctx_id_path(repo_root))}
+
+
+def cli_use(args) -> int:
+    """Entry point for ``arctx use`` subcommand."""
+    result = run_use_command(
+        run_id=args.run_id,
+        store_dir=args.store_dir,
+    )
+    print(result["run_id"])
+    return 0

arctx_cli/commands/view.py

@@ -0,0 +1,82 @@
+"""arctx CLI view subcommands."""
+
+from __future__ import annotations
+
+import argparse
+import json
+
+from arctx_cli.append_batch import graph_counts, maybe_append_or_save
+from arctx_cli.context import (
+    resolve_run_id_from_args,
+    resolve_store,
+    resolve_user_id_from_args,
+    resolve_work_session_id_from_args,
+)
+
+
+def add_parser(subparsers) -> argparse.ArgumentParser:
+    parser = subparsers.add_parser("view", help="Manage GraphViews")
+    view_sub = parser.add_subparsers(dest="view_command", required=True)
+
+    # view create
+    create = view_sub.add_parser("create", help="Create a new GraphView")
+    create.add_argument("--name", required=True)
+    create.add_argument("--root-node", required=True, dest="root_node")
+    create.add_argument("--run", default=None)
+    create.add_argument("--store-dir", default=None)
+    create.add_argument("--user", default=None)
+    create.add_argument("--work-session", default=None)
+
+    # view list
+    lst = view_sub.add_parser("list", help="List all GraphViews")
+    lst.add_argument("--run", default=None)
+    lst.add_argument("--store-dir", default=None)
+
+    # view show
+    show = view_sub.add_parser("show", help="Show a GraphView")
+    show.add_argument("view_name")
+    show.add_argument("--run", default=None)
+    show.add_argument("--store-dir", default=None)
+
+    return parser
+
+
+def cli_view(args) -> int:
+    store = resolve_store(args.store_dir)
+    run_id = resolve_run_id_from_args(args)
+    if not store.run_path(run_id).exists():
+        raise KeyError(f"unknown run_id: {run_id}")
+    handle = store.load_run(run_id)
+
+    if args.view_command == "create":
+        user_id = resolve_user_id_from_args(args)
+        work_session_id = resolve_work_session_id_from_args(args)
+        before = graph_counts(handle)
+        view = handle.view_create(args.name, root_node_id=args.root_node)
+        handle.record_work_event(
+            user_id=user_id,
+            work_session_id=work_session_id,
+            event_type="view_created",
+            target_kind="view",
+            target_id=view.view_id,
+            created_records=(view.view_id,),
+            summary=view.name,
+        )
+        maybe_append_or_save(
+            store=store,
+            handle=handle,
+            user_id=user_id,
+            work_session_id=work_session_id,
+            before=before,
+        )
+        print(json.dumps(view.to_dict(), ensure_ascii=False, indent=2))
+
+    elif args.view_command == "list":
+        views = handle.view_list()
+        print(json.dumps([v.to_dict() for v in views], ensure_ascii=False, indent=2))
+
+    elif args.view_command == "show":
+        view = handle.view_show(args.view_name)
+        print(json.dumps(view.to_dict(), ensure_ascii=False, indent=2))
+
+    return 0