corethink 1.0.0__py3-none-any.whl

corethink/commands/api.py

@@ -0,0 +1,59 @@
+"""`corethink api`: any Workbench API call, signed in. Everything the console can do is reachable through it."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import typer
+
+from corethink import output as ui
+from corethink.context import client
+
+METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE"}
+
+
+def api(
+    method: str = typer.Argument(..., help="GET, POST, PUT, PATCH or DELETE."),
+    path: str = typer.Argument(..., help="The API path, e.g. /api/v1/harnesses/usecases"),
+    data: str = typer.Option(None, "--data", "-d", help="JSON body; @file reads it from a file, @- from stdin."),
+    param: list[str] = typer.Option(None, "--param", "-p", help="Query parameter key=value (repeatable)."),
+) -> None:
+    """Call any Workbench API route directly and print its JSON answer.
+
+    Example: corethink api GET /api/v1/harnesses/training-jobs -p qa=1
+    """
+    verb = method.upper()
+    if verb not in METHODS:
+        ui.error(f"Use one of {', '.join(sorted(METHODS))}.")
+        raise typer.Exit(2)
+    if not path.startswith("/api/"):
+        path = "/api/v1/" + path.lstrip("/")
+    body = None
+    if data is not None:
+        text = (
+            sys.stdin.read()
+            if data == "@-"
+            else Path(data[1:]).read_text(encoding="utf-8")
+            if data.startswith("@")
+            else data
+        )
+        try:
+            body = json.loads(text) if text.strip() else None
+        except ValueError as error:
+            ui.error(f"--data is not JSON: {error}")
+            raise typer.Exit(2) from None
+    params = {}
+    for item in param or []:
+        key, sep, value = item.partition("=")
+        if not sep:
+            ui.error(f"--param {item}: use key=value.")
+            raise typer.Exit(2)
+        params[key] = value
+    answer = client().request(verb, path, json=body, params=params or None)
+    ui.print_json(answer)
+
+
+def register(root: typer.Typer) -> None:
+    root.command(rich_help_panel="Advanced")(api)

corethink/commands/archive.py

@@ -0,0 +1,433 @@
+"""`corethink archive`: archived runs, tests and environments; restore them, or (admins) delete them for good.
+
+As the console's Archive page: restoring a run or test is for members, an environment for admins; deleting is for admins,
+after the server's own preview of what would go. "Delete all" deletes a few at a time and says what did not go, and why.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import typer
+
+from corethink import output as ui
+from corethink.client import ApiError
+from corethink.commands.train import (
+    ARCHIVE,
+    JOBS,
+    USECASES,
+    _test_result,
+    base_vs_trained,
+    fail,
+    pick_run,
+    plural,
+    run_environment,
+    run_name,
+)
+from corethink.context import client
+
+app = typer.Typer(
+    help="Archived runs, tests and environments: restore them, or delete them for good.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+
+# how many ids one bulk delete request carries (the console's BULK_CHUNK; the server takes at most 25)
+BULK_CHUNK = 10
+DELETE_ALL_WORD = "delete all"
+
+
+def load_archive() -> dict[str, Any]:
+    answer = client().get(ARCHIVE) or {}
+    return {
+        "runs": list(answer.get("runs") or []),
+        "environments": list(answer.get("environments") or []),
+    }
+
+
+def runs_and_tests(runs: int, tests: int) -> str:
+    return " and ".join(p for p in (plural(runs, "run") if runs else "", plural(tests, "test") if tests else "") if p)
+
+
+def _result(run: dict[str, Any]) -> str | None:
+    if run.get("kind") == "test":
+        return _test_result(run)
+    if run.get("state") != "SUCCEEDED":
+        return str(run.get("state") or "").lower() or None
+    scores = base_vs_trained(run.get("gate"))
+    if scores["base"] is None or scores["trained"] is None:
+        return None
+    return f"{ui.score(scores['base'])} → {ui.score(scores['trained'])}"
+
+
+def _archived(at: Any, by: Any) -> str:
+    who = f" by {by}" if by and not str(by).startswith("local:") else ""
+    return f"{ui.when(at)}{who}" if at else (f"archived{who}" if who else "—")
+
+
+@app.command("list")
+def list_archive() -> None:
+    """Archived environments, runs and tests in this workspace.
+
+    Example: corethink archive list
+    """
+    archive = load_archive()
+
+    def human() -> None:
+        environments, runs = archive["environments"], archive["runs"]
+        if not environments and not runs:
+            ui.info(
+                "Nothing is archived. Archive a run with `corethink train archive RUN`: it waits here, with everything "
+                "it had, until it is restored or deleted for good."
+            )
+            return
+        if environments:
+            ui.table(
+                environments,
+                [
+                    ("ID", "id"),
+                    ("Name", "name"),
+                    ("Runs", lambda e: str(e.get("runs", 0))),
+                    ("Tests", lambda e: str(e.get("tests", 0))),
+                    ("Archived", lambda e: _archived(e.get("archived_at"), e.get("archived_by"))),
+                ],
+                title=f"Environments · {len(environments)}",
+            )
+            ui.out.print()
+        if runs:
+            archived_envs = {e.get("id") for e in environments}
+            names = {e.get("id"): e.get("name") for e in environments}
+            ui.table(
+                runs,
+                [
+                    ("ID", lambda r: ui.short_id(r.get("job_id"))),
+                    ("Name", run_name),
+                    (
+                        "Kind",
+                        lambda r: "Base-model test" if r.get("kind") == "test" else "Training run",
+                    ),
+                    ("Environment", lambda r: run_environment(r, names)),
+                    ("Result", _result),
+                    (
+                        "Archived",
+                        lambda r: (
+                            _archived(r.get("archived_at"), r.get("archived_by"))
+                            + (" with its environment" if r.get("archived_with") else "")
+                            + (
+                                " (environment archived)"
+                                if r.get("usecase") in archived_envs and not r.get("archived_with")
+                                else ""
+                            )
+                        ),
+                    ),
+                ],
+                title=f"Runs and tests · {len(runs)}",
+            )
+        ui.info("An archived run's or environment's endpoint keeps serving what it served when it was archived.")
+
+    ui.emit(archive, human)
+
+
+def _which(ref: str, archive: dict[str, Any], kind: str | None) -> tuple[str, dict[str, Any]]:
+    """("environment" | "run", the archived thing) that `ref` names."""
+    wanted = ref.strip()
+    if kind != "run":
+        envs = archive["environments"]
+        exact = [e for e in envs if e.get("id") == wanted]
+        found = (
+            exact
+            or [e for e in envs if str(e.get("id", "")).startswith(wanted)]
+            or [e for e in envs if str(e.get("name", "")).lower() == wanted.lower()]
+        )
+        if len(found) == 1:
+            return "environment", found[0]
+        if len(found) > 1:
+            raise fail(
+                f"{wanted!r} matches {len(found)} archived environments: {', '.join(e['id'] for e in found[:6])}."
+            )
+        if kind == "environment":
+            raise fail(f"No archived environment matches {wanted!r}. See `corethink archive list`.", 5)
+    return "run", pick_run(wanted, archive["runs"], where=" in the Archive")
+
+
+def restore_run(ref: str) -> None:
+    """Restore an archived run or test (members): `corethink train restore` and `corethink archive restore`."""
+    archive = load_archive()
+    _restore("run", pick_run(ref, archive["runs"], where=" in the Archive"), archive)
+
+
+def _restore(kind: str, thing: dict[str, Any], archive: dict[str, Any]) -> None:
+    if kind == "environment":
+        summary = client().post(f"{USECASES}/{thing['id']}:restore")
+        moved = (summary or {}).get("moved") or {}
+
+        def human() -> None:
+            ui.success(
+                f"Restored {thing.get('name') or thing['id']}, with {plural(moved.get('runs', 0), 'run')} and "
+                f"{plural(moved.get('tests', 0), 'test')}."
+            )
+
+        ui.emit(summary, human)
+        return
+    name = run_name(thing)
+    noun = "test" if thing.get("kind") == "test" else "run"
+    if thing.get("usecase") in {e.get("id") for e in archive["environments"]}:
+        if thing.get("archived_with"):
+            raise fail(
+                f"{noun.capitalize()} {name} was archived with its environment: restoring the environment brings it "
+                f"back (`corethink archive restore {thing['usecase']}`).",
+                6,
+            )
+        raise fail(
+            f"Its environment is archived: restore the environment first (`corethink archive restore {thing['usecase']}`).",
+            6,
+        )
+    summary = client().post(f"{JOBS}/{thing['job_id']}:restore")
+    ui.emit(
+        summary,
+        lambda: ui.success(f"Restored {noun} {name}. See it with `corethink train show {str(thing['job_id'])[:8]}`."),
+    )
+
+
+@app.command("restore")
+def restore(
+    ref: str = typer.Argument(
+        ..., help="An archived run's id (or the start of it, or its name), or an environment's id."
+    ),
+    environment: bool = typer.Option(False, "--env", help="It is an environment."),
+    run: bool = typer.Option(False, "--run", help="It is a run or test."),
+) -> None:
+    """Bring an archived run, test or environment back (an environment comes back with the runs archived with it).
+
+    Examples:
+      corethink archive restore 3f2a
+      corethink archive restore payroll-0ecb50 --env
+    """
+    if environment and run:
+        raise fail("Choose --env or --run, not both.")
+    archive = load_archive()
+    kind, thing = _which(ref, archive, "environment" if environment else "run" if run else None)
+    _restore(kind, thing, archive)
+
+
+def deletion_lines(summary: dict[str, Any]) -> list[str]:
+    """What a delete removes, line by line, from the server's own count (DeleteDialog.tsx deletionLines)."""
+    d = summary.get("deleted") or {}
+    target = (summary.get("target") or {}).get("kind")
+    lines: list[str] = []
+    if target == "environment":
+        if d.get("runs") or d.get("tests"):
+            what = " and ".join(
+                p
+                for p in (
+                    plural(d.get("runs", 0), "training run") if d.get("runs") else "",
+                    plural(d.get("tests", 0), "base-model test") if d.get("tests") else "",
+                )
+                if p
+            )
+            lines.append(
+                f"{what}, with their logs, charts, final checks and files ({plural(d.get('run_files', 0), 'file')})"
+            )
+        else:
+            lines.append("No runs or tests")
+    else:
+        lines.append(
+            f"The {'test' if target == 'test' else 'run'} and its record: logs, charts, final check and files "
+            f"({plural(d.get('run_files', 0), 'file')})"
+        )
+    if d.get("packages"):
+        lines.append(
+            ("The learned program's package" if d["packages"] == 1 else f"{d['packages']} learned-program packages")
+            + f" and {'its' if d.get('gate_results') == 1 else 'their'} final-check result"
+        )
+    aliases = summary.get("cleared_aliases") or []
+    for alias in aliases:
+        if alias.endswith(" canary"):
+            lines.append(f"The canary on {alias[: -len(' canary')]}")
+        else:
+            lines.append(
+                f"What {alias} serves: the endpoint has nothing on {alias.split('@')[1] if '@' in alias else 'it'} afterwards"
+            )
+    if d.get("canary_plans") and not any(a.endswith(" canary") for a in aliases):
+        lines.append(f"Its endpoint's canary records ({d['canary_plans']})")
+    if d.get("endpoint_keys"):
+        lines.append(
+            f"{plural(d['endpoint_keys'], 'endpoint key')}: callers using {'it' if d['endpoint_keys'] == 1 else 'them'} stop working"
+        )
+    if target == "environment":
+        lines.append(
+            "The environment's own files: tasks, tools, traces, captured conversations and labels "
+            f"({plural(d.get('environment_files', 0), 'file')})"
+        )
+    for kept in summary.get("kept") or []:
+        lines.append(f"Kept: {kept}")
+    return lines
+
+
+def _typed(expected: str, yes: bool, question: str) -> None:
+    """Ask for `expected` to be typed (skipped with --yes; refused without a terminal)."""
+    if yes:
+        return
+    if not sys.stdin.isatty():
+        ui.error(f"{question} Re-run with --yes to confirm without a prompt.")
+        raise typer.Exit(2)
+    typed = typer.prompt(f"Type {expected} to confirm", default="", show_default=False)
+    if typed.strip().lower() != expected.lower():
+        ui.error("That does not match; nothing was deleted.")
+        raise typer.Exit(1)
+
+
+@app.command("delete")
+def delete(
+    ref: str = typer.Argument(
+        ..., help="An archived run's id (or the start of it, or its name), or an environment's id."
+    ),
+    environment: bool = typer.Option(False, "--env", help="It is an environment."),
+    run: bool = typer.Option(False, "--run", help="It is a run or test."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Delete without asking."),
+) -> None:
+    """Delete an archived run, test or environment for good (admins). Shows what would go first.
+
+    An environment takes its archived runs and tests, its endpoint (staging, keys) and its files with it.
+    This cannot be undone.
+
+    Example: corethink archive delete 3f2a
+    """
+    if environment and run:
+        raise fail("Choose --env or --run, not both.")
+    archive = load_archive()
+    kind, thing = _which(ref, archive, "environment" if environment else "run" if run else None)
+    if kind == "environment":
+        path, name, typed = (
+            f"{ARCHIVE}/usecases/{thing['id']}",
+            thing.get("name") or thing["id"],
+            thing["id"],
+        )
+        noun = "environment"
+    else:
+        path, name, typed = (
+            f"{ARCHIVE}/training-jobs/{thing['job_id']}",
+            run_name(thing),
+            str(thing["job_id"])[:8],
+        )
+        noun = "test" if thing.get("kind") == "test" else "run"
+    preview = client().get(f"{path}/deletion") or {}
+    if not preview.get("deletable", False):
+        raise fail(
+            f"{noun.capitalize()} {name} cannot be deleted now: {preview.get('reason') or 'the Workbench refused'}.",
+            6,
+        )
+    summary = preview.get("summary") or {}
+    ui.err.print(f"Deleting {noun} {name} for good removes:")
+    for line in deletion_lines(summary):
+        ui.err.print(f"  • {line}")
+    ui.err.print("This cannot be undone.", style="bold red")
+    _typed(typed, yes, f"Delete {noun} {name} for good?")
+    done = client().delete(path)
+
+    def human() -> None:
+        deleted = (done or {}).get("deleted") or {}
+        if kind == "environment":
+            ui.success(
+                f"Deleted {name}, with {plural(deleted.get('runs', 0), 'run')} and {plural(deleted.get('tests', 0), 'test')}."
+            )
+        else:
+            cleared = (done or {}).get("cleared_aliases") or []
+            ui.success(f"Deleted {noun} {name}" + (f"; {', '.join(cleared)} is empty now" if cleared else "") + ".")
+
+    ui.emit(done, human)
+
+
+def delete_in_chunks(ids: list[str], path: str) -> dict[str, Any]:
+    """Delete `ids` for good, BULK_CHUNK at a time; a request that fails as a whole stops the rest."""
+    result: dict[str, Any] = {"asked": len(ids), "deleted": [], "failed": [], "stopped": None}
+    for at in range(0, len(ids), BULK_CHUNK):
+        chunk = ids[at : at + BULK_CHUNK]
+        try:
+            answer = client().post(path, {"ids": chunk}) or {}
+        except ApiError as problem:
+            result["stopped"] = problem.message
+            break
+        result["deleted"].extend(answer.get("deleted") or [])
+        result["failed"].extend(answer.get("failed") or [])
+        ui.info(f"Deleting… {min(len(ids), at + len(chunk))} of {len(ids)}")
+    return result
+
+
+@app.command("delete-all")
+def delete_all(
+    what: str = typer.Argument(..., help="runs (archived runs and tests) or environments."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Delete without asking."),
+) -> None:
+    """Delete every archived run and test, or every archived environment, for good (admins).
+
+    Any that cannot be deleted are skipped and listed. Spent credit stays in the ledger. This cannot be undone.
+
+    Example: corethink archive delete-all runs
+    """
+    if what not in ("runs", "environments"):
+        raise fail("Say what to delete: runs or environments.")
+    archive = load_archive()
+    if what == "runs":
+        items = archive["runs"]
+        ids = [str(r["job_id"]) for r in items]
+        label = runs_and_tests(sum(r.get("kind") != "test" for r in items), sum(r.get("kind") == "test" for r in items))
+        lines = [
+            "Each one's record, logs, charts, final check and files",
+            "Its learned program's package, unless another run or endpoint still uses it",
+            "What its endpoint's staging serves, when that is its package",
+        ]
+        unit, path = "runs and tests", f"{ARCHIVE}/training-jobs:delete"
+        name_of = {str(r["job_id"]): run_name(r) for r in items}
+    else:
+        items = archive["environments"]
+        ids = [str(e["id"]) for e in items]
+        label = plural(len(items), "environment")
+        runs = sum(int(e.get("runs") or 0) for e in items)
+        tests = sum(int(e.get("tests") or 0) for e in items)
+        lines = [
+            f"Their archived runs and tests{f' ({runs_and_tests(runs, tests)})' if runs or tests else ''}, with their logs, charts and files",
+            "Their endpoints: staging, canaries and keys. Callers using those keys stop working",
+            "Their files: tasks, tools, traces, captured conversations and labels",
+        ]
+        unit, path = "environments", f"{ARCHIVE}/usecases:delete"
+        name_of = {str(e["id"]): e.get("name") or e["id"] for e in items}
+    if not ids:
+        ui.info(f"No archived {what}.")
+        ui.emit({"asked": 0, "deleted": [], "failed": [], "stopped": None}, lambda: None)
+        return
+    ui.err.print(f"Delete {label} for good? This removes:")
+    for line in lines:
+        ui.err.print(f"  • {line}")
+    ui.err.print(
+        "Any that cannot be deleted are skipped and listed. Spent credit stays in the ledger.",
+        style="dim",
+    )
+    ui.err.print("This cannot be undone.", style="bold red")
+    if what == "environments":
+        _typed(DELETE_ALL_WORD, yes, f"Delete {label} for good?")
+    else:
+        ui.confirm(f"Delete {label} for good?", yes=yes)
+    result = delete_in_chunks(ids, path)
+
+    def human() -> None:
+        deleted = len(result["deleted"])
+        part = f"{deleted} of {result['asked']} {unit}"
+        if result["stopped"]:
+            ui.error(f"Deleted {part}, then stopped: {result['stopped']}")
+        elif deleted == result["asked"]:
+            ui.success(f"Deleted {label}.")
+        else:
+            failed = len(result["failed"])
+            ui.warn(f"Deleted {part}. {failed} {'was' if failed == 1 else 'were'} not deleted:")
+        for failure in result["failed"]:
+            ui.err.print(f"  • {name_of.get(str(failure.get('id')), failure.get('id'))}: {failure.get('reason')}")
+
+    ui.emit(result, human)
+    if result["stopped"] or result["failed"]:
+        raise typer.Exit(1)
+
+
+def register(root: typer.Typer) -> None:
+    root.add_typer(app, name="archive", rich_help_panel="Manage")