lagora-cli 1.1.0

package/dist/scripts/legato-fsim-runner.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+import traceback
+from pathlib import Path
+
+from agora_playground_harness import has_playground_contract, run_playground_kernel
+from legato_runner_launchers import LauncherError, LauncherScriptError, launcher_runs_in_subprocess, run_launcher
+
+
+class FsimPreflightError(RuntimeError):
+    pass
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run a Legato BINARY launcher on HART fsim")
+    parser.add_argument("--kernel", required=True, help="Path to uploaded Python launcher/kernel file")
+    parser.add_argument("--output-root", required=True, help="Directory for generated fsim outputs")
+    return parser.parse_args()
+
+
+def export_fsim_child_config(output_root: Path) -> None:
+    """Hand the fsim configuration to the process that actually runs the kernel.
+
+    Script-style launchers execute in a child process, and hart's device state
+    lives in the C++ runtime of whichever process called set_fsim_env. Opening
+    the device here would leave the child without one.
+    """
+    os.environ.setdefault("HA_TOOLCHAIN", "1")
+    os.environ.setdefault("HA_MOCK_DEVICE_COUNT", "2")
+
+    try:
+        import hart  # noqa: F401  fail fast if the SDK cannot provide fsim at all
+    except ImportError as exc:
+        raise FsimPreflightError(f"hart not available: {exc}") from exc
+
+    os.environ["AGORA_FSIM_DEVICE_VERSION"] = os.environ.get("AGORA_FSIM_DEVICE_VERSION", "BERTHA_CLOUD_EVT0")
+    os.environ["AGORA_FSIM_COMPUTE_MODE"] = os.environ.get("AGORA_FSIM_COMPUTE_MODE", "TORCH")
+    os.environ["AGORA_FSIM_LOG_LEVEL"] = os.environ.get("AGORA_FSIM_LOG_LEVEL", "trace")
+    os.environ["AGORA_FSIM_LOG_PATH"] = str(output_root / "fsim.log")
+    os.environ["AGORA_FSIM_CONFIGURE_IN_CHILD"] = "1"
+    print("[LEGATO_FSIM] configure=child", flush=True)
+    print(f"[LEGATO_FSIM] device_version={os.environ['AGORA_FSIM_DEVICE_VERSION']}", flush=True)
+    print(f"[LEGATO_FSIM] compute_mode={os.environ['AGORA_FSIM_COMPUTE_MODE']}", flush=True)
+    print(f"[LEGATO_FSIM] log_path={os.environ['AGORA_FSIM_LOG_PATH']}", flush=True)
+
+
+def configure_fsim(output_root: Path) -> None:
+    os.environ.setdefault("HA_TOOLCHAIN", "1")
+    os.environ.setdefault("HA_MOCK_DEVICE_COUNT", "2")
+
+    try:
+        import hart
+    except ImportError as exc:
+        raise FsimPreflightError(f"hart not available: {exc}") from exc
+
+    device_version_name = os.environ.get("AGORA_FSIM_DEVICE_VERSION", "BERTHA_CLOUD_EVT0")
+    compute_mode_name = os.environ.get("AGORA_FSIM_COMPUTE_MODE", "TORCH")
+    log_level = os.environ.get("AGORA_FSIM_LOG_LEVEL", "trace")
+    log_path = output_root / "fsim.log"
+
+    try:
+        device_version = getattr(hart.HaDeviceVersion, device_version_name)
+        compute_mode = getattr(hart.HaFSimComputeMode, compute_mode_name)
+    except AttributeError as exc:
+        raise FsimPreflightError(
+            f"unsupported fsim config: AGORA_FSIM_DEVICE_VERSION={device_version_name}, "
+            f"AGORA_FSIM_COMPUTE_MODE={compute_mode_name}",
+        ) from exc
+
+    try:
+        hart.set_fsim_env(device_version, compute_mode, str(log_path), log_level)
+    except RuntimeError as exc:
+        raise FsimPreflightError(f"set_fsim_env failed: {exc}") from exc
+    if hart.get_device_count() == 0:
+        raise FsimPreflightError("no fsim devices available")
+    hart.set_device(0)
+    print(f"[LEGATO_FSIM] device_version={device_version_name}", flush=True)
+    print(f"[LEGATO_FSIM] compute_mode={compute_mode_name}", flush=True)
+    print(f"[LEGATO_FSIM] log_path={log_path}", flush=True)
+
+
+def main() -> int:
+    args = parse_args()
+    kernel_path = Path(args.kernel).resolve()
+    output_root = Path(args.output_root).resolve()
+    output_root.mkdir(parents=True, exist_ok=True)
+
+    # A kernel that brings no launcher of its own is driven here rather than by
+    # itself, so the device has to be opened in this process -- not handed to a
+    # child that is never spawned.
+    harness_driven = has_playground_contract(kernel_path)
+    try:
+        if harness_driven or not launcher_runs_in_subprocess(kernel_path):
+            configure_fsim(output_root)
+        else:
+            export_fsim_child_config(output_root)
+        os.environ["AGORA_LEGATO_SESSION_LAUNCH"] = "1"
+        print("[LEGATO_WORKER] stage=FSIM status=running", flush=True)
+        if harness_driven:
+            print("[LEGATO_WORKER] launcher_mode=harness", flush=True)
+            run_playground_kernel(kernel_path, output_root)
+        else:
+            run_launcher(kernel_path, ["BINARY"], output_root)
+    except LauncherScriptError as exc:
+        print("[LEGATO_WORKER] stage=FSIM status=failed", flush=True)
+        print(f"[LEGATO_WORKER] reason={exc}", flush=True)
+        return 1
+    except (FsimPreflightError, LauncherError) as exc:
+        print("[LEGATO_WORKER] preflight=failed", flush=True)
+        print(f"[LEGATO_WORKER] reason={exc}", flush=True)
+        return 2
+    except Exception:  # noqa: BROAD_EXCEPT_OK
+        print("[LEGATO_WORKER] stage=FSIM status=failed", flush=True)
+        traceback.print_exc()
+        return 1
+
+    print("[LEGATO_WORKER] stage=FSIM status=success", flush=True)
+    print("[LEGATO_WORKER] fsim=success", flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/scripts/legato-lowering-runner.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""Run staged Legato lowering for an uploaded kernel module.
+
+The runner imports a user kernel file, finds a @legato.compile or
+@legato.primitive JitFunction, synthesizes dummy arguments from Legato type
+annotations, and runs the same function through each requested OutputType. It
+prints stable worker markers so the Agora TypeScript worker can summarize the
+failed stage.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import importlib.util
+import inspect
+import os
+import re
+import sys
+import traceback
+from pathlib import Path
+from typing import Any
+
+from legato_runner_annotations import (
+    PreflightError,
+    load_module,
+    place_arguments,
+    select_kernel,
+    synthesize_args,
+    top_level_function_names,
+)
+from legato_runner_launchers import (
+    LauncherError,
+    LauncherScriptError,
+    kernel_has_launcher,
+    run_launcher,
+    statically_decorated_kernel_names,
+)
+
+
+DEFAULT_STAGES = ["MLIR", "CORE_IR", "BACKEND_IR", "ASM", "BINARY"]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run staged Legato lowering")
+    parser.add_argument("--kernel", required=True, help="Path to uploaded kernel.py")
+    parser.add_argument("--function", help="@legato.compile/@legato.primitive function name. Auto-detects if omitted.")
+    parser.add_argument("--output-root", required=True, help="Directory for stage outputs")
+    parser.add_argument("--stages", default=",".join(DEFAULT_STAGES), help="Comma-separated OutputType stages")
+    return parser.parse_args()
+
+
+
+
+def run_stage(legato_module: Any, kernel: Any, kernel_args: list[Any], stage: str, output_root: Path) -> None:
+    output_type = getattr(legato_module.OutputType, stage)
+    output_path = output_root / stage.lower()
+    output_path.mkdir(parents=True, exist_ok=True)
+    print(f"[LEGATO_WORKER] stage={stage} status=running", flush=True)
+    print(f"[LEGATO_WORKER] output_path={output_path}", flush=True)
+    with legato_module.session(**session_kwargs(legato_module.session, output_type, output_path, launch=False)):
+        kernel(*kernel_args)
+    print(f"[LEGATO_WORKER] stage={stage} status=success", flush=True)
+
+
+def session_kwargs(session_factory: Any, output_type: Any, output_path: Path, launch: bool) -> dict[str, Any]:
+    kwargs: dict[str, Any] = {"output_type": output_type, "output_path": str(output_path)}
+    if session_accepts_launch(session_factory):
+        kwargs["launch"] = launch
+    return kwargs
+
+
+def session_accepts_launch(session_factory: Any) -> bool:
+    try:
+        signature = inspect.signature(session_factory)
+    except (TypeError, ValueError):
+        return False
+    return "launch" in signature.parameters or any(
+        parameter.kind is inspect.Parameter.VAR_KEYWORD
+        for parameter in signature.parameters.values()
+    )
+
+
+def validate_stages(legato_module: Any, stages: list[str]) -> None:
+    if not stages:
+        raise PreflightError("no lowering stages requested")
+    for stage in stages:
+        if not hasattr(legato_module.OutputType, stage):
+            raise PreflightError(f"unsupported lowering stage: {stage}")
+
+
+def run_compiled_kernel(legato_module: Any, kernel_path: Path, function_name: str | None, stages: list[str], output_root: Path) -> None:
+    local_function_names = top_level_function_names(kernel_path)
+    selected_name: str | None = None
+    for index, stage in enumerate(stages):
+        module = load_module(kernel_path)
+        stage_selected_name, kernel = select_kernel(module, function_name, local_function_names)
+        if selected_name is None:
+            selected_name = stage_selected_name
+            print(f"[LEGATO_WORKER] kernel_function={selected_name}")
+        elif stage_selected_name != selected_name:
+            raise PreflightError(f"selected kernel changed between stages: {selected_name} != {stage_selected_name}")
+        # A kernel that declares param_kinds must be called with its arguments
+        # bound to those targets, or lowering refuses them as bare values.
+        kernel_args = place_arguments(kernel, synthesize_args(kernel))
+        if index == 0:
+            print(f"[LEGATO_WORKER] synthesized_args={len(kernel_args)}")
+        run_stage(legato_module, kernel, kernel_args, stage, output_root)
+
+
+def main() -> int:
+    args = parse_args()
+    kernel_path = Path(args.kernel).resolve()
+    output_root = Path(args.output_root).resolve()
+    stages = [stage.strip() for stage in args.stages.split(",") if stage.strip()]
+    function_name = args.function or os.environ.get("LEGATO_KERNEL_FUNCTION")
+    os.environ.setdefault("AGORA_LEGATO_SESSION_LAUNCH", "0")
+
+    try:
+        import legato
+    except Exception:  # noqa: BLE001
+        print("[LEGATO_WORKER] preflight=failed")
+        print("[LEGATO_WORKER] reason=failed to import legato")
+        traceback.print_exc()
+        return 2
+
+    try:
+        validate_stages(legato, stages)
+        decorated_names = statically_decorated_kernel_names(kernel_path)
+        if function_name:
+            run_compiled_kernel(legato, kernel_path, function_name, stages, output_root)
+        elif kernel_has_launcher(kernel_path):
+            run_launcher(kernel_path, stages, output_root)
+        elif decorated_names:
+            run_compiled_kernel(legato, kernel_path, None, stages, output_root)
+        else:
+            run_launcher(kernel_path, stages, output_root)
+    except LauncherScriptError as exc:
+        print("[LEGATO_WORKER] lowering_pipeline=failed")
+        print(f"[LEGATO_WORKER] reason={exc}")
+        return 1
+    except (PreflightError, LauncherError) as exc:
+        print("[LEGATO_WORKER] preflight=failed")
+        print(f"[LEGATO_WORKER] reason={exc}")
+        return 2
+    except Exception:  # noqa: BLE001
+        print("[LEGATO_WORKER] lowering_pipeline=failed")
+        traceback.print_exc()
+        return 1
+
+    print("[LEGATO_WORKER] lowering_pipeline=success")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/dist/scripts/legato_runner_annotations.py

@@ -0,0 +1,235 @@
+"""Reading a Legato kernel's shape from its annotations.
+
+Extracted so more than one runner can use it: lowering synthesizes arguments to
+compile with, and the Playground harness needs the same shapes to allocate device
+tensors. The file name matters -- the runners are hyphenated scripts and cannot
+be imported, which is why this had to move before it could be shared.
+"""
+from __future__ import annotations
+
+import ast
+import importlib.util
+import inspect
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+TORCH_DTYPE_BY_LEGATO = {
+    "bfloat16": "bfloat16",
+    "bf16": "bfloat16",
+    "float16": "float16",
+    "fp16": "float16",
+    "float32": "float32",
+    "f32": "float32",
+    "float64": "float64",
+    "f64": "float64",
+    "int32": "int32",
+    "i32": "int32",
+    "int64": "int64",
+    "i64": "int64",
+    "bool": "bool",
+}
+
+
+class PreflightError(RuntimeError):
+    pass
+
+
+def load_module(kernel_path: Path) -> Any:
+    spec = importlib.util.spec_from_file_location("agora_uploaded_kernel", kernel_path)
+    if spec is None or spec.loader is None:
+        raise PreflightError(f"cannot import kernel module: {kernel_path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.path.insert(0, str(kernel_path.parent))
+    try:
+        spec.loader.exec_module(module)
+    finally:
+        if sys.path and sys.path[0] == str(kernel_path.parent):
+            sys.path.pop(0)
+    return module
+
+
+def is_legato_jit_function(value: Any) -> bool:
+    return callable(value) and hasattr(value, "_node") and hasattr(value, "_globals") and hasattr(value, "verify_types")
+
+
+def top_level_function_names(kernel_path: Path) -> set[str]:
+    with kernel_path.open("r", encoding="utf-8") as source:
+        tree = ast.parse(source.read(), filename=str(kernel_path))
+    return {node.name for node in tree.body if isinstance(node, ast.FunctionDef)}
+
+
+def select_kernel(module: Any, function_name: str | None, local_function_names: set[str]) -> tuple[str, Any]:
+    if function_name:
+        value = getattr(module, function_name, None)
+        if not is_legato_jit_function(value):
+            raise PreflightError(f"{function_name} is not a @legato.compile/@legato.primitive function")
+        return function_name, value
+
+    candidates = [
+        (name, value)
+        for name, value in vars(module).items()
+        if name in local_function_names and is_legato_jit_function(value)
+    ]
+    if not candidates:
+        raise PreflightError("no @legato.compile/@legato.primitive function found in uploaded module")
+    if len(candidates) > 1:
+        names = ", ".join(name for name, _ in candidates)
+        raise PreflightError(f"multiple @legato.compile/@legato.primitive functions found; set LEGATO_KERNEL_FUNCTION. candidates={names}")
+    return candidates[0]
+
+
+def get_function_def(jit_function: Any) -> ast.FunctionDef:
+    node = getattr(jit_function, "_node", None)
+    for item in ast.walk(node):
+        if isinstance(item, ast.FunctionDef):
+            return item
+    raise PreflightError("cannot locate function AST for Legato kernel target")
+
+
+def annotation_source(annotation: ast.expr | None) -> str:
+    if annotation is None:
+        return ""
+    return ast.unparse(annotation)
+
+
+def eval_annotation(source: str, jit_function: Any) -> Any:
+    if not source:
+        raise PreflightError("missing required Legato argument annotation")
+    namespace = dict(getattr(jit_function, "_globals", {}))
+    return eval(source, namespace)  # noqa: S307 - trusted internal worker environment for uploaded repros.
+
+
+def dtype_name(type_value: Any, source: str) -> str:
+    quoted = re.search(r"['\"]([A-Za-z0-9_]+)['\"]", source)
+    if quoted and quoted.group(1).lower() in TORCH_DTYPE_BY_LEGATO:
+        return TORCH_DTYPE_BY_LEGATO[quoted.group(1).lower()]
+    text = str(type_value).lower()
+    for legato_name, torch_name in TORCH_DTYPE_BY_LEGATO.items():
+        if legato_name in text:
+            return torch_name
+    return "float32"
+
+
+def dimension_value(dim: Any) -> int:
+    if isinstance(dim, int):
+        return 8 if dim == -1 else max(dim, 1)
+    if isinstance(dim, tuple):
+        if len(dim) == 2 and dim[0] == -1 and isinstance(dim[1], int):
+            return max(dim[1], 1)
+        raise PreflightError(f"unsupported dynamic dimension tuple: {dim!r}")
+    raise PreflightError(f"unsupported tensor dimension: {dim!r}")
+
+
+def tensor_shape_from_annotation_source(source: str, jit_function: Any) -> list[int]:
+    parsed = ast.parse(source, mode="eval")
+    call = parsed.body
+    if not isinstance(call, ast.Call):
+        raise PreflightError(f"unsupported tensor annotation expression: {source}")
+    if len(call.args) < 2:
+        raise PreflightError(f"tensor annotation is missing shape argument: {source}")
+    shape_node = call.args[1]
+    try:
+        raw_shape = ast.literal_eval(shape_node)
+    except Exception as exc:  # noqa: BLE001
+        namespace = dict(getattr(jit_function, "_globals", {}))
+        try:
+            raw_shape = eval(ast.unparse(shape_node), namespace)  # noqa: S307 - internal repro runner.
+        except Exception as eval_exc:  # noqa: BLE001
+            raise PreflightError(f"tensor shape must be literal/evaluable: {source}") from eval_exc
+    if isinstance(raw_shape, int):
+        return [dimension_value(raw_shape)]
+    if not isinstance(raw_shape, (list, tuple)):
+        raise PreflightError(f"tensor shape must be a list/tuple literal: {source}")
+    return [dimension_value(dim) for dim in raw_shape]
+
+
+def is_tensor_annotation(value: Any, source: str) -> bool:
+    if "tensor_type" in source or ".tensor(" in source:
+        return True
+    return hasattr(value, "is_tensor") and bool(value.is_tensor())
+
+
+def scalar_arg(type_value: Any) -> Any:
+    text = str(type_value).lower()
+    if "bool" in text:
+        return True
+    if "float" in text or "f32" in text or "f64" in text:
+        return 1.0
+    if "list" in text:
+        return [0]
+    if "tuple" in text:
+        return (0, 0)
+    return 1
+
+
+def make_tensor_arg(torch_module: Any, type_value: Any, source: str, name: str, jit_function: Any) -> Any:
+    shape = tensor_shape_from_annotation_source(source, jit_function)
+    dtype = getattr(torch_module, dtype_name(type_value, source))
+    if name.lower() in {"out", "output", "result"} or name.lower().endswith(("_out", "_output")):
+        return torch_module.zeros(*shape, dtype=dtype)
+    if dtype is torch_module.bool:
+        return torch_module.zeros(*shape, dtype=dtype)
+    if dtype in {torch_module.int32, torch_module.int64}:
+        return torch_module.ones(*shape, dtype=dtype)
+    return torch_module.randn(*shape, dtype=dtype)
+
+
+def synthesize_args(jit_function: Any) -> list[Any]:
+    function_def = get_function_def(jit_function)
+    if not function_def.args.args:
+        return []
+
+    import torch
+
+    args: list[Any] = []
+    for arg in function_def.args.args:
+        source = annotation_source(arg.annotation)
+        type_value = eval_annotation(source, jit_function)
+        if is_tensor_annotation(type_value, source):
+            args.append(make_tensor_arg(torch, type_value, source, arg.arg, jit_function))
+        else:
+            args.append(scalar_arg(type_value))
+    return args
+
+
+def placement_for(jit_function: Any, name: str) -> Any:
+    """Where a parameter has to be bound, from the decorator's param_kinds.
+
+    None means pass the tensor as it is; anything else has to be wrapped in
+    legato.Arg. A kernel that declares a placement and is called without one
+    fails at lowering with "declared as 'top_param' but passed as a bare value",
+    so both the lowering path and the Playground harness ask this.
+    """
+    import legato.model.bertha as bertha
+
+    # The compiled function keeps these as _param_kinds; reading the public
+    # spelling silently found nothing and left every argument unbound.
+    kinds = getattr(jit_function, "_param_kinds", None)
+    if kinds is None:
+        kinds = getattr(jit_function, "param_kinds", None) or {}
+    # Stored normalised as "<kind>_param"; the decorator is written with the bare
+    # word. Accept either rather than depending on which spelling survives.
+    kind = kinds.get(name)
+    if isinstance(kind, str) and kind.endswith("_param"):
+        kind = kind[: -len("_param")]
+    if kind in (None, "universal"):
+        return None
+    if kind == "top":
+        return bertha.top
+    if kind == "core":
+        return bertha.core(0)
+    raise PreflightError(f"parameter '{name}' has param_kind '{kind}', which is not placed automatically")
+
+
+def place_arguments(jit_function: Any, values: list[Any]) -> list[Any]:
+    """Bind each argument to the device target its parameter declares."""
+    import legato
+
+    names = [arg.arg for arg in get_function_def(jit_function).args.args]
+    placed: list[Any] = []
+    for name, value in zip(names, values):
+        target = placement_for(jit_function, name)
+        placed.append(value if target is None else legato.Arg(value, target))
+    return placed

package/dist/scripts/legato_runner_env.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def launcher_working_directory() -> Path:
+    return Path(os.environ.get("AGORA_SDK_ROOT", Path.cwd())).resolve()
+
+
+def compiler_root() -> Path | None:
+    """Root of a separate SDK supplying legato, when one was selected."""
+    configured = os.environ.get("AGORA_LEGATO_COMPILER_ROOT", "").strip()
+    return Path(configured).resolve() if configured else None
+
+
+def legato_source_path(root: Path) -> Path | None:
+    """The checkout's legato package, but only when it was built in place.
+
+    A prepared runtime is a git checkout whichever way its packages arrived, so
+    `legato/src` exists even when legato came from a published wheel. Putting it
+    on the path then shadows the installed package with pure Python that has no
+    compiled `_legato`, and every kernel dies on `cannot import name
+    'get_builder' from 'legato._legato' (unknown location)`.
+
+    Presence of the built extension is what distinguishes the two layouts, so
+    that is what this asks -- no configuration to keep in sync.
+    """
+    source = root / "legato" / "src"
+    return source if any((source / "legato").glob("_legato*.so")) else None
+
+
+def launcher_import_paths(kernel_path: Path) -> list[Path]:
+    sdk_root = launcher_working_directory()
+    compiler = compiler_root()
+    candidates = [
+        kernel_path.parent,
+        # These land ahead of the runtime SDK so its legato is shadowed. They are
+        # inserted into sys.path directly, which outranks PYTHONPATH, so setting
+        # PYTHONPATH alone would not be enough.
+        *([path for path in (legato_source_path(compiler), compiler / "legato_aten_lib") if path] if compiler else []),
+        sdk_root,
+        *([source] if (source := legato_source_path(sdk_root)) else []),
+    ]
+    paths: list[Path] = []
+    seen: set[str] = set()
+    for candidate in candidates:
+        text = str(candidate.resolve())
+        if text in seen:
+            continue
+        seen.add(text)
+        paths.append(candidate)
+    return paths
+
+
+def script_command(kernel_path: Path) -> list[str]:
+    return [sys.executable, str(Path(__file__).with_name("legato_runner_script_wrapper.py")), str(kernel_path)]
+
+
+def launcher_env(kernel_path: Path, output_root: Path, stages: list[str]) -> dict[str, str]:
+    import_paths = launcher_import_paths(kernel_path)
+    env = {
+        **os.environ,
+        "AGORA_LEGATO_OUTPUT_ROOT": str(output_root),
+        "AGORA_LEGATO_STAGES": ",".join(stages),
+        "LEGATO_OUTPUT_PATH": str(output_root),
+        "AGORA_SDK_ROOT": str(launcher_working_directory()),
+        "AGORA_LEGATO_IMPORT_PATHS": os.pathsep.join(str(path) for path in import_paths),
+        "AGORA_LEGATO_SESSION_LAUNCH": os.environ.get("AGORA_LEGATO_SESSION_LAUNCH", "0"),
+    }
+    return prepend_pythonpath(env, import_paths)
+
+
+def prepend_pythonpath(env: dict[str, str], paths: list[Path]) -> dict[str, str]:
+    existing = env.get("PYTHONPATH", "")
+    values = [str(path) for path in paths]
+    values.extend(item for item in existing.split(os.pathsep) if item)
+    env["PYTHONPATH"] = os.pathsep.join(dedupe(values))
+    return env
+
+
+def dedupe(values: list[str]) -> list[str]:
+    result: list[str] = []
+    seen: set[str] = set()
+    for value in values:
+        if value in seen:
+            continue
+        seen.add(value)
+        result.append(value)
+    return result