Refactor: unify PTO-ISA resolve + auto-clone; add shared --log-level helper (#555)

PTO-ISA unification
-------------------

Before this change there were two parallel implementations of
"ensure PTO-ISA is available":

  simpler_setup/pto_isa.py::ensure_pto_isa_root()
    - Only looked up (env var -> default path), raised OSError if missing.
    - Called by scene_test.py, so `pytest` and standalone `python test_*.py`
      hit OSError on a fresh checkout, with an error message that literally
      told the user to go run ci.py or run_example.py first. A real
      onboarding papercut.

  simpler_setup/code_runner.py::_ensure_pto_isa_root()
    - Full clone + commit pin + lock + fetch-latest logic (~280 lines).
    - Called by ci.py and run_example.py (via CodeRunner).

Unify both behind a single API in simpler_setup/pto_isa.py. All four user
entry points (pytest, standalone test_*.py, ci.py, run_example.py) now
auto-clone on first use.

Move default clone target
  examples/scripts/_deps/pto-isa  ->  PROJECT_ROOT/build/pto-isa

  - `build/` is the repo's canonical artifact directory (already gitignored,
    already hosts `build/lib/` and `build/cache/`).
  - Per-repo/worktree/venv isolation via PROJECT_ROOT means concurrent
    worktrees each get their own clone and don't race on commit pins.
  - One-time re-clone for existing dev machines; acceptable.

New signature:

  ensure_pto_isa_root(
      commit: Optional[str] = None,
      clone_protocol: str = "ssh",
      update_if_exists: bool = False,   # fetch origin/HEAD when True + no commit
      verbose: bool = False,
  ) -> str

- scene_test calls with defaults  -> auto-clone on first run, never touch
  an existing clone (no network on every pytest run).
- ci.py / CodeRunner pass update_if_exists=True + verbose=True to preserve
  "always ensure latest" behaviour; commit pin still wins when provided.

code_runner.py loses ~280 lines of PTO-ISA code and the fcntl import;
ci.py updates its two import sites to reach pto_isa directly
(ensure_pto_isa_root, checkout_pto_isa_commit, get_pto_isa_clone_path).

The "Cloning pto-isa to X ..." heads-up is emitted at WARNING level so it
surfaces even in pytest / standalone paths that have no basicConfig —
otherwise users would see a 30-60s silent hang on first run.

Shared --log-level helper
-------------------------

Add simpler_setup/log_config.py exposing LOG_LEVEL_CHOICES,
DEFAULT_LOG_LEVEL ("info"), and configure_logging(log_level).

All three CLI entry points now share one spelling of the flag, all default
to INFO:

  ci.py                           --log-level error|warn|info|debug
  examples/scripts/run_example.py --log-level ...  (plus -v / --silent shortcuts)
  python test_*.py (run_module)   --log-level ...

The helper also propagates PTO_LOG_LEVEL env so ci.py's runtime-isolation
subprocesses inherit the level.

pytest is untouched — it has its own --log-cli-level / pyproject log_cli_level
and doesn't need a layered flag.

Verification
------------

- pytest tests/ut/py: 121 passed, 5 skipped (unchanged from main)
- tools/verify_packaging.sh: all 5 install modes × 4 entry points green
- All 3 CLI entry points expose --log-level choices with default info

Author: ChaoWao

ci.py

@@ -60,9 +60,7 @@
 from threading import Lock, Thread
 from typing import Any, Callable, Protocol, cast
 
-PROJECT_ROOT = Path(__file__).resolve().parent
-
-from simpler.task_interface import (  # noqa: E402  # type: ignore[import-not-found]
+from simpler.task_interface import (  # type: ignore[import-not-found]
     ChipCallable,  # pyright: ignore[reportAttributeAccessIssue]
     ChipCallConfig,  # pyright: ignore[reportAttributeAccessIssue]
     ChipStorageTaskArgs,  # pyright: ignore[reportAttributeAccessIssue]
@@ -72,6 +70,10 @@
     scalar_to_uint64,
 )
 
+from simpler_setup.log_config import DEFAULT_LOG_LEVEL, LOG_LEVEL_CHOICES, configure_logging
+
+PROJECT_ROOT = Path(__file__).resolve().parent
+
 logger = logging.getLogger("ci")
 
 # ---------------------------------------------------------------------------
@@ -264,16 +266,17 @@ def discover_tasks(platform: str, runtime_filter: str | None = None) -> list[Tas
 
 
 def ensure_pto_isa(commit: str | None, clone_protocol: str) -> str:
-    from simpler_setup.code_runner import _ensure_pto_isa_root  # noqa: PLC0415
-
-    root = _ensure_pto_isa_root(verbose=True, commit=commit, clone_protocol=clone_protocol)
-    if root is None:
-        raise OSError(
-            "PTO_ISA_ROOT could not be resolved.\n"
-            "Set it manually or let auto-clone run:\n"
-            "  export PTO_ISA_ROOT=$(pwd)/examples/scripts/_deps/pto-isa"
-        )
-    return root
+    from simpler_setup.pto_isa import ensure_pto_isa_root  # noqa: PLC0415
+
+    # update_if_exists=True: when no commit is pinned, fetch latest origin/HEAD
+    # so CI runs reproducibly track main rather than whatever local checkout
+    # happens to be on disk.
+    return ensure_pto_isa_root(
+        commit=commit,
+        clone_protocol=clone_protocol,
+        update_if_exists=True,
+        verbose=True,
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -952,11 +955,11 @@ def print_summary(results: list[TaskResult]) -> int:
 
 def reset_pto_isa(commit: str, clone_protocol: str) -> str:
     """Checkout PTO-ISA at the pinned commit (or re-clone if needed)."""
-    from simpler_setup.code_runner import _checkout_pto_isa_commit, _get_pto_isa_clone_path  # noqa: PLC0415
+    from simpler_setup.pto_isa import checkout_pto_isa_commit, get_pto_isa_clone_path  # noqa: PLC0415
 
-    clone_path = _get_pto_isa_clone_path()
+    clone_path = get_pto_isa_clone_path()
     if clone_path.exists():
-        _checkout_pto_isa_commit(clone_path, commit, verbose=True)
+        checkout_pto_isa_commit(clone_path, commit, verbose=True)
         return str(clone_path.resolve())
     return ensure_pto_isa(commit, clone_protocol)
 
@@ -1177,6 +1180,9 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("-t", "--timeout", type=int, default=600)
     parser.add_argument("--clone-protocol", choices=["ssh", "https"], default="ssh")
     parser.add_argument("--all", dest="run_all_cases", action="store_true", help="Run all cases, not just DEFAULT_CASE")
+    parser.add_argument(
+        "--log-level", choices=LOG_LEVEL_CHOICES, default=DEFAULT_LOG_LEVEL, help="Root logger level (default: info)"
+    )
     parser.add_argument("--device-worker", action="store_true", help=argparse.SUPPRESS)
     parser.add_argument("--result-json", default=None, help=argparse.SUPPRESS)
     parser.add_argument("--task-list-json", default=None, help=argparse.SUPPRESS)
@@ -1276,9 +1282,8 @@ def _run_single_platform(platform: str, args: argparse.Namespace) -> list[TaskRe
 
 
 def main() -> int:
-    logging.basicConfig(level=logging.INFO, format="[%(levelname)s] %(message)s", force=True)
-
     args = parse_args()
+    configure_logging(args.log_level)
     args.devices = parse_device_range(args.device_range)
 
     valid_platforms = _discover_valid_platforms()

examples/scripts/run_example.py

@@ -40,6 +40,9 @@
 import time
 from pathlib import Path
 
+from simpler_setup.code_runner import create_code_runner
+from simpler_setup.log_config import DEFAULT_LOG_LEVEL, LOG_LEVEL_CHOICES, configure_logging
+
 project_root = Path(__file__).parent.parent.parent
 
 logger = logging.getLogger(__name__)
@@ -127,23 +130,11 @@ def compute_golden(tensors: dict, params: dict) -> None:
         help="Platform name: 'a2a3'/'a5' for hardware, 'a2a3sim'/'a5sim' for simulation (default: a2a3)",
     )
 
-    parser.add_argument(
-        "-v",
-        "--verbose",
-        action="store_true",
-        help="Enable verbose output (equivalent to --log-level debug)",
-    )
-
-    parser.add_argument(
-        "--silent",
-        action="store_true",
-        help="Silent mode - only show errors (equivalent to --log-level error)",
-    )
-
     parser.add_argument(
         "--log-level",
-        choices=["error", "warn", "info", "debug"],
-        help="Set log level explicitly (overrides --verbose and --silent)",
+        choices=LOG_LEVEL_CHOICES,
+        default=DEFAULT_LOG_LEVEL,
+        help=f"Root logger level (default: {DEFAULT_LOG_LEVEL})",
     )
 
     parser.add_argument(
@@ -206,31 +197,7 @@ def compute_golden(tensors: dict, params: dict) -> None:
     if args.all and args.case:
         parser.error("--all and --case are mutually exclusive")
 
-    # Determine log level from arguments
-    log_level_str = None
-    if args.log_level:
-        log_level_str = args.log_level
-    elif args.verbose:
-        log_level_str = "debug"
-    elif args.silent:
-        log_level_str = "error"
-    else:
-        log_level_str = "info"
-
-    # Setup logging before any other operations
-    level_map = {
-        "error": logging.ERROR,
-        "warn": logging.WARNING,
-        "info": logging.INFO,
-        "debug": logging.DEBUG,
-    }
-    log_level = level_map.get(log_level_str.lower(), logging.INFO)
-
-    # Configure Python logging
-    logging.basicConfig(level=log_level, format="[%(levelname)s] %(message)s", force=True)
-
-    # Set environment variable for C++ side
-    os.environ["PTO_LOG_LEVEL"] = log_level_str
+    configure_logging(args.log_level)
 
     # Validate paths
     kernels_path = Path(args.kernels)
@@ -249,10 +216,7 @@ def compute_golden(tensors: dict, params: dict) -> None:
         logger.error(f"kernel_config.py not found in {kernels_path}")
         return 1
 
-    # Import and run
     try:
-        from simpler_setup.code_runner import create_code_runner  # noqa: PLC0415
-
         runner = create_code_runner(
             kernels_dir=str(args.kernels),
             golden_path=str(args.golden),
@@ -310,16 +274,15 @@ def compute_golden(tensors: dict, params: dict) -> None:
                     else:
                         cmd += ["-d", str(args.device)]
 
-                    if log_level_str == "debug":
+                    if logger.isEnabledFor(logging.DEBUG):
                         cmd.append("-v")
 
                     result = subprocess.run(cmd, check=True, capture_output=True, text=True)
                     logger.info(result.stdout)
                     logger.info("Swimlane JSON generation completed")
                 except subprocess.CalledProcessError as e:
                     logger.warning(f"Failed to generate swimlane JSON: {e}")
-                    if log_level_str == "debug":
-                        logger.debug(f"stderr: {e.stderr}")
+                    logger.debug(f"stderr: {e.stderr}")
             else:
                 logger.warning(f"Swimlane converter script not found: {swimlane_script}")
 
@@ -332,7 +295,7 @@ def compute_golden(tensors: dict, params: dict) -> None:
 
     except Exception as e:
         logger.error(f"TEST FAILED: {e}")
-        if log_level_str == "debug":
+        if logger.isEnabledFor(logging.DEBUG):
             import traceback  # noqa: PLC0415
 
             traceback.print_exc()