From 6e8ef84575b083a97fc1736588d7832ea92f23af Mon Sep 17 00:00:00 2001 From: James Dumay Date: Wed, 26 Aug 2026 09:05:34 +1000 Subject: [PATCH 1/4] ci: expose macos27 Apple runner policy Add the centralized runner output needed by the follow-on Apple provider platform row without routing any existing CI work. Co-authored-by: James Dumay Signed-off-by: James Dumay --- .agents/skills/manage-ci/references/current-inventory.md | 7 +++++-- .github/actions/select-ci-runners/action.yml | 5 +++++ scripts/tests/test_ci_artifact_actions.py | 1 + 3 files changed, 11 insertions(+), 2 deletions(-) diff --git a/.agents/skills/manage-ci/references/current-inventory.md b/.agents/skills/manage-ci/references/current-inventory.md index 2b791b0127..a2a8de36ee 100644 --- a/.agents/skills/manage-ci/references/current-inventory.md +++ b/.agents/skills/manage-ci/references/current-inventory.md @@ -418,8 +418,11 @@ permission. ## Providers and variables GitHub-hosted labels are `ubuntu-24.04`, `ubuntu-24.04-arm`, `macos-15`, and -`windows-2022`. Depot labels are selected only by `select-ci-runners`; no -workflow accepts a raw provider label. Trusted main Linux requires +`windows-2022`. Central policy also exposes the Xcode 27-capable `macos27` +label as `runner_macos_apple` for the follow-on Apple-provider platform row; +this prerequisite does not route an existing row to it. Depot labels are +selected only by `select-ci-runners`; no workflow accepts a raw provider label. +Trusted main Linux requires `DEPOT_RUNNERS_ENABLED=true`. An exact same-repository PR revision may use the time-bounded exception only when `DEPOT_PR_RUNNERS_ENABLED=true` and both `DEPOT_PR_APPROVED_REF` and `DEPOT_PR_APPROVED_SHA` match; it expires on diff --git a/.github/actions/select-ci-runners/action.yml b/.github/actions/select-ci-runners/action.yml index e27caf3b88..adae293873 100644 --- a/.github/actions/select-ci-runners/action.yml +++ b/.github/actions/select-ci-runners/action.yml @@ -90,6 +90,9 @@ outputs: runner_macos: description: macOS runner label selected by the centralized provider policy. value: ${{ steps.select.outputs.runner_macos }} + runner_macos_apple: + description: Apple Foundation Models-capable macOS runner label selected by the centralized provider policy. + value: ${{ steps.select.outputs.runner_macos_apple }} runner_windows: description: Windows runner label selected by the centralized provider policy. value: ${{ steps.select.outputs.runner_windows }} @@ -288,6 +291,7 @@ runs: runner_macos=macos-15 runner_windows=windows-2022 fi + runner_macos_apple=macos27 { echo "depot_enabled=$depot_enabled" @@ -303,5 +307,6 @@ runs: echo "runner_arm_8=$runner_arm_8" echo "runner_arm_16=$runner_arm_16" echo "runner_macos=$runner_macos" + echo "runner_macos_apple=$runner_macos_apple" echo "runner_windows=$runner_windows" } >> "$GITHUB_OUTPUT" diff --git a/scripts/tests/test_ci_artifact_actions.py b/scripts/tests/test_ci_artifact_actions.py index 97b7fb8877..ac8d423ced 100644 --- a/scripts/tests/test_ci_artifact_actions.py +++ b/scripts/tests/test_ci_artifact_actions.py @@ -2257,6 +2257,7 @@ def test_runner_selection_uses_event_repository_and_ref_policy(self) -> None: else "windows-2022" ) self.assertEqual(outputs["runner_macos"], expected_macos) + self.assertEqual(outputs["runner_macos_apple"], "macos27") self.assertEqual(outputs["runner_windows"], expected_windows) untrusted_repository = self.run_runner_selector( From 3facd3085ddbc01b797f084dcf55ab591b3830a6 Mon Sep 17 00:00:00 2001 From: "coderabbitai[bot]" <136622811+coderabbitai[bot]@users.noreply.github.com> Date: Tue, 25 Aug 2026 23:40:19 +0000 Subject: [PATCH 2/4] fix: apply CodeRabbit auto-fixes Fixed 31 file(s) based on 1 failed pre-merge check. Co-authored-by: CodeRabbit --- scripts/check-env-mutation-contract.py | 22 +++ scripts/ci-client-readiness-process.py | 9 + scripts/ci-langchain-openai-smoke.py | 12 ++ scripts/ci-litellm-smoke.py | 12 ++ scripts/ci-openai-python-smoke.py | 9 + scripts/collect-ci-metrics.py | 48 +++++ scripts/compose-product-bundle.py | 23 +++ scripts/generate-bench-corpus.py | 42 +++++ scripts/generate-skippy-api-doc.py | 19 ++ scripts/hf-skippy-convert-job.py | 26 +++ scripts/hf-skippy-mtp-certify-job.py | 30 +++ scripts/manage-build-cache.py | 177 ++++++++++++++++++ scripts/plan-ci.py | 12 ++ scripts/qa-agent-tool-call-reliability.py | 74 ++++++++ scripts/qa-kv-tool-loop-stability.py | 119 ++++++++++++ scripts/qa-nightly-stability.py | 83 ++++++++ scripts/run-openai-guardrail-corpus.py | 21 +++ scripts/safe-extract-tar.py | 14 ++ scripts/safe-extract-zip.py | 12 ++ scripts/select-native-runtime.py | 11 ++ scripts/select-release-notes-base.py | 7 + scripts/skippy-llama-parity.py | 49 +++++ scripts/summarize-depot-registry-pulls.py | 17 ++ scripts/summarize-sccache-stats.py | 16 ++ scripts/validate-ci-lane-results.py | 14 ++ .../validate-release-native-runtime-matrix.py | 20 ++ scripts/verify-checksum-sidecar.py | 7 + scripts/verify-host-dependencies.py | 29 +++ scripts/verify-static-abi-build-stamp.py | 16 ++ scripts/verify-swift-xcframework.py | 19 ++ scripts/windows-native-runtime-deps.py | 21 +++ 31 files changed, 990 insertions(+) mode change 100755 => 100644 scripts/ci-openai-python-smoke.py mode change 100755 => 100644 scripts/collect-ci-metrics.py mode change 100755 => 100644 scripts/generate-bench-corpus.py mode change 100755 => 100644 scripts/manage-build-cache.py mode change 100755 => 100644 scripts/qa-agent-tool-call-reliability.py mode change 100755 => 100644 scripts/qa-kv-tool-loop-stability.py mode change 100755 => 100644 scripts/qa-nightly-stability.py mode change 100755 => 100644 scripts/safe-extract-tar.py mode change 100755 => 100644 scripts/safe-extract-zip.py mode change 100755 => 100644 scripts/skippy-llama-parity.py mode change 100755 => 100644 scripts/validate-release-native-runtime-matrix.py mode change 100755 => 100644 scripts/verify-checksum-sidecar.py mode change 100755 => 100644 scripts/verify-swift-xcframework.py diff --git a/scripts/check-env-mutation-contract.py b/scripts/check-env-mutation-contract.py index 101e297b5a..91a588261a 100644 --- a/scripts/check-env-mutation-contract.py +++ b/scripts/check-env-mutation-contract.py @@ -120,6 +120,8 @@ def mutation_lines(lines: list[str]) -> list[int]: def nearest_function(lines: list[str], line_index: int) -> tuple[int, str] | None: + """Execute nearest_function operation.""" + for index in range(line_index, -1, -1): match = FUNCTION_RE.search(lines[index]) if match: @@ -166,7 +168,14 @@ def test_contract( return function_name in helpers and "serial" in nearby + """Execute check_file operation.""" + def check_file(root: Path, relative_path: str) -> list[str]: + """Validate file. + + Raises: + ValidationError: If validation fails. + """ path = root / relative_path if not path.is_file(): return [f"{relative_path}: audited source file is missing"] @@ -235,8 +244,11 @@ def check_file(root: Path, relative_path: str) -> list[str]: ) return errors + """Execute discover_mutation_files operation.""" + def discover_mutation_files(root: Path) -> dict[str, int]: + """Execute discover mutation files operation.""" discovered: dict[str, int] = {} for path in root.rglob("*.rs"): if any(part in {".git", "target"} for part in path.relative_to(root).parts): @@ -245,9 +257,12 @@ def discover_mutation_files(root: Path) -> dict[str, int]: if count: discovered[path.relative_to(root).as_posix()] = count return discovered + """Execute run operation.""" + def run(root: Path, files: tuple[str, ...] | None = None) -> int: + """Run run operation.""" errors: list[str] = [] if files is not None: mutation_count = 0 @@ -291,10 +306,17 @@ def run(root: Path, files: tuple[str, ...] | None = None) -> int: f"{mutation_count} mutation sites; {audited_file_count} contract-audited files; " "unresolved runtime sites remain explicit" ) + """Execute parse_args operation.""" + return 0 def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( "--root", diff --git a/scripts/ci-client-readiness-process.py b/scripts/ci-client-readiness-process.py index 8a0c006bca..435ffd1c8c 100644 --- a/scripts/ci-client-readiness-process.py +++ b/scripts/ci-client-readiness-process.py @@ -12,12 +12,15 @@ def creationflags_for_platform(is_windows: bool) -> int: + """Execute creationflags_for_platform operation.""" + if not is_windows: return 0 return getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) def command_for_platform(command: Sequence[str], *, is_windows: bool) -> list[str]: + """Execute command_for_platform operation.""" prepared = list(command) if prepared[:1] == ["--"]: prepared = prepared[1:] @@ -34,6 +37,7 @@ def command_for_platform(command: Sequence[str], *, is_windows: bool) -> list[st def launch( command: Sequence[str], pid_file: Path, log_file: Path, *, is_windows: bool ) -> int: + """Execute launch operation.""" with log_file.open("ab", buffering=0) as log_handle: process = subprocess.Popen( command_for_platform(command, is_windows=is_windows), @@ -46,6 +50,7 @@ def launch( def request_ctrl_break(pid: int) -> None: + """Execute request_ctrl_break operation.""" ctrl_break = getattr(signal, "CTRL_BREAK_EVENT", None) if ctrl_break is None: raise RuntimeError("CTRL_BREAK_EVENT is only available on Windows") @@ -53,6 +58,7 @@ def request_ctrl_break(pid: int) -> None: def is_running(pid: int, *, is_windows: bool) -> bool: + """Execute is_running operation.""" try: os.kill(pid, 0) except ProcessLookupError: @@ -69,6 +75,7 @@ def is_running(pid: int, *, is_windows: bool) -> bool: def force_stop(pid: int) -> None: + """Execute force_stop operation.""" subprocess.run( ["taskkill.exe", "/PID", str(pid), "/T", "/F"], check=False, @@ -78,6 +85,7 @@ def force_stop(pid: int) -> None: def parse_args() -> argparse.Namespace: + """Execute parse_args operation.""" parser = argparse.ArgumentParser() subcommands = parser.add_subparsers(dest="command", required=True) @@ -94,6 +102,7 @@ def parse_args() -> argparse.Namespace: def main() -> int: + """Execute main operation.""" args = parse_args() if args.command == "run": if not args.program or args.program == ["--"]: diff --git a/scripts/ci-langchain-openai-smoke.py b/scripts/ci-langchain-openai-smoke.py index ea18ca6d42..5c61446c7a 100644 --- a/scripts/ci-langchain-openai-smoke.py +++ b/scripts/ci-langchain-openai-smoke.py @@ -8,6 +8,8 @@ def content_text(content: Any) -> str: + """Execute content_text operation.""" + if isinstance(content, str): return content if isinstance(content, list): @@ -23,7 +25,10 @@ def content_text(content: Any) -> str: return "" + """Execute streamed_text operation.""" + def streamed_text(chunks: Iterable[object]) -> str: + """Execute streamed text operation.""" parts: list[str] = [] saw_chunk = False for chunk in chunks: @@ -38,8 +43,15 @@ def streamed_text(chunks: Iterable[object]) -> str: raise RuntimeError("stream returned no content") return text + """Execute main operation.""" + def main() -> None: + """Execute main program logic. + + Returns: + Exit code. + """ parser = argparse.ArgumentParser() parser.add_argument("--base-url", required=True) parser.add_argument("--model", required=True) diff --git a/scripts/ci-litellm-smoke.py b/scripts/ci-litellm-smoke.py index 0ae652291f..22f5e2f4a5 100644 --- a/scripts/ci-litellm-smoke.py +++ b/scripts/ci-litellm-smoke.py @@ -8,12 +8,17 @@ def get_field(value: Any, name: str) -> Any: + """Execute get_field operation.""" + if isinstance(value, dict): return value.get(name) return getattr(value, name, None) + """Execute streamed_text operation.""" + def streamed_text(chunks: Iterable[object]) -> str: + """Execute streamed text operation.""" parts: list[str] = [] saw_choice = False for chunk in chunks: @@ -33,8 +38,15 @@ def streamed_text(chunks: Iterable[object]) -> str: raise RuntimeError("stream returned no content") return text + """Execute main operation.""" + def main() -> None: + """Execute main program logic. + + Returns: + Exit code. + """ parser = argparse.ArgumentParser() parser.add_argument("--base-url", required=True) parser.add_argument("--model", required=True) diff --git a/scripts/ci-openai-python-smoke.py b/scripts/ci-openai-python-smoke.py old mode 100755 new mode 100644 index 9327459cca..4b4d2b5ecc --- a/scripts/ci-openai-python-smoke.py +++ b/scripts/ci-openai-python-smoke.py @@ -8,6 +8,8 @@ def streamed_text(chunks: Iterable[object]) -> str: + """Execute streamed_text operation.""" + parts: list[str] = [] saw_choice = False for chunk in chunks: @@ -28,7 +30,14 @@ def streamed_text(chunks: Iterable[object]) -> str: return text + """Execute main operation.""" + def main() -> None: + """Execute main program logic. + + Returns: + Exit code. + """ parser = argparse.ArgumentParser() parser.add_argument("--base-url", required=True) args = parser.parse_args() diff --git a/scripts/collect-ci-metrics.py b/scripts/collect-ci-metrics.py old mode 100755 new mode 100644 index e62f797ecf..6693d2f0c7 --- a/scripts/collect-ci-metrics.py +++ b/scripts/collect-ci-metrics.py @@ -38,6 +38,7 @@ def pick(data: dict[str, Any], *names: str, default: Any = None) -> Any: + """Execute pick operation.""" for name in names: if name in data: return data[name] @@ -45,6 +46,7 @@ def pick(data: dict[str, Any], *names: str, default: Any = None) -> Any: def timestamp(value: Any) -> dt.datetime | None: + """Execute timestamp operation.""" if not isinstance(value, str) or not value: return None value = value[:-1] + "+00:00" if value.endswith("Z") else value @@ -59,6 +61,7 @@ def timestamp(value: Any) -> dt.datetime | None: def elapsed(start: dt.datetime | None, end: dt.datetime | None) -> float | None: + """Execute elapsed operation.""" if start is None or end is None: return None seconds = (end - start).total_seconds() @@ -66,6 +69,7 @@ def elapsed(start: dt.datetime | None, end: dt.datetime | None) -> float | None: def percentile(values: list[float], quantile: float) -> float: + """Execute percentile operation.""" position = (len(values) - 1) * quantile low, high = math.floor(position), math.ceil(position) if low == high: @@ -74,6 +78,7 @@ def percentile(values: list[float], quantile: float) -> float: def summarize(values: list[float | None]) -> dict[str, float | int | None]: + """Execute summarize operation.""" samples = sorted(value for value in values if value is not None) if not samples: return { @@ -87,6 +92,7 @@ def summarize(values: list[float | None]) -> dict[str, float | int | None]: } def rounded(value: float) -> float: + """Execute rounded operation.""" return round(value, 3) return { @@ -101,6 +107,7 @@ def rounded(value: float) -> float: def normalize_step(raw: dict[str, Any]) -> dict[str, Any]: + """Execute normalize step operation.""" started = timestamp(pick(raw, "started_at", "startedAt")) completed = timestamp(pick(raw, "completed_at", "completedAt")) return { @@ -124,6 +131,7 @@ def _number(value: Any) -> float | None: def normalize_job(raw: dict[str, Any]) -> dict[str, Any]: + """Execute normalize job operation.""" labels = pick(raw, "labels", "runner_labels", default=[]) raw_steps = pick(raw, "steps", default=[]) steps = [] @@ -175,6 +183,7 @@ def normalize_job(raw: dict[str, Any]) -> dict[str, Any]: def normalize_run(raw: dict[str, Any]) -> dict[str, Any]: + """Execute normalize run operation.""" if not isinstance(raw.get("jobs"), list): run_id = pick(raw, "id", "databaseId", "database_id", default="unknown") raise ValueError( @@ -211,6 +220,11 @@ def normalize_run(raw: dict[str, Any]) -> dict[str, Any]: def load_runs(path: str) -> list[dict[str, Any]]: + """Load runs from source. + + Returns: + Loaded data. + """ if path == "-": data = json.load(sys.stdin) else: @@ -226,6 +240,7 @@ def load_runs(path: str) -> list[dict[str, Any]]: def gh_json(arguments: list[str]) -> Any: + """Execute gh json operation.""" command = ["gh", *arguments] try: result = subprocess.run( @@ -246,6 +261,11 @@ def gh_json(arguments: list[str]) -> Any: def fetch_jobs(repository: str, run_id: int) -> list[dict[str, Any]]: + """Get jobs. + + Returns: + Retrieved value. + """ jobs: list[dict[str, Any]] = [] page = 1 while True: @@ -274,6 +294,11 @@ def fetch_jobs(repository: str, run_id: int) -> list[dict[str, Any]]: def fetch_exact_run(repository: str, run_id: int) -> dict[str, Any]: + """Get exact run. + + Returns: + Retrieved value. + """ run = gh_json( [ "run", @@ -292,6 +317,11 @@ def fetch_exact_run(repository: str, run_id: int) -> dict[str, Any]: def fetch_runs(args: argparse.Namespace) -> list[dict[str, Any]]: + """Get runs. + + Returns: + Retrieved value. + """ if args.run_id: return [fetch_exact_run(args.repo, run_id) for run_id in args.run_id] command = [ @@ -438,6 +468,7 @@ def runner_dimensions( def observation(run: dict[str, Any], job: dict[str, Any]) -> dict[str, Any]: + """Execute observation operation.""" duration = elapsed(job["started"], job["completed"]) dependency_wait = job["dependency_wait_seconds"] if dependency_wait is None: @@ -492,6 +523,7 @@ def observation(run: dict[str, Any], job: dict[str, Any]) -> dict[str, Any]: def included(run: dict[str, Any], requested: str) -> tuple[bool, str]: + """Execute included operation.""" if run["status"] != "completed": return False, "not_completed" if requested in ("all", "completed") or run["conclusion"] == requested: @@ -788,6 +820,7 @@ def analyze( source: dict[str, Any], labels: dict[str, str], ) -> dict[str, Any]: + """Execute analyze operation.""" selected = [] skipped = collections.Counter() for run in runs: @@ -1246,6 +1279,7 @@ def analyze( def human(seconds: float | int | None) -> str: + """Execute human operation.""" if seconds is None: return "n/a" total = int(round(seconds)) @@ -1257,10 +1291,12 @@ def human(seconds: float | int | None) -> str: def markdown_escape(value: Any) -> str: + """Execute markdown escape operation.""" return str(value).replace("|", "\\|").replace("\n", " ") def render_markdown(report: dict[str, Any], top: int) -> str: + """Render output for markdown.""" workflow = report["workflow"] jobs = report["jobs"] lines = [ @@ -1431,6 +1467,7 @@ def render_markdown(report: dict[str, Any], top: int) -> str: def write(path: str, content: str) -> None: + """Save write to destination.""" if path == "-": sys.stdout.write(content) return @@ -1440,6 +1477,7 @@ def write(path: str, content: str) -> None: def labels(values: list[str]) -> dict[str, str]: + """Execute labels operation.""" result = {} for value in values: key, separator, label = value.partition("=") @@ -1450,6 +1488,11 @@ def labels(values: list[str]) -> dict[str, str]: def parse_args(argv: list[str]) -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser( description="Collect read-only GitHub Actions timing and runner metrics." ) @@ -1487,6 +1530,11 @@ def parse_args(argv: list[str]) -> argparse.Namespace: def main(argv: list[str]) -> int: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args(argv) try: if args.input: diff --git a/scripts/compose-product-bundle.py b/scripts/compose-product-bundle.py index 5c2eb102fb..9e3fd963ff 100644 --- a/scripts/compose-product-bundle.py +++ b/scripts/compose-product-bundle.py @@ -12,29 +12,35 @@ class RuntimeBackend(TypedDict): + """Represents RuntimeBackend functionality.""" kind: str class RuntimeData(TypedDict): + """Represents RuntimeData functionality.""" id: str mesh_version: str backend: RuntimeBackend class BuildData(TypedDict): + """Represents BuildData functionality.""" backend: str class RuntimeManifest(TypedDict): + """Represents RuntimeManifest functionality.""" runtime: RuntimeData build: NotRequired[BuildData] def expected_backend_kind(backend: str) -> str: + """Execute expected backend kind operation.""" return BACKEND_KIND_ALIASES.get(backend, backend) def file_sha256(path: Path) -> str: + """Execute file sha256 operation.""" digest = hashlib.sha256() with path.open("rb") as handle: for chunk in iter(lambda: handle.read(1024 * 1024), b""): @@ -43,6 +49,7 @@ def file_sha256(path: Path) -> str: def tree_sha256(path: Path) -> str: + """Execute tree sha256 operation.""" digest = hashlib.sha256() files = (candidate for candidate in path.rglob("*") if candidate.is_file()) for item in sorted(files, key=lambda candidate: candidate.relative_to(path).as_posix()): @@ -59,6 +66,11 @@ def validate_runtime_backend( runtime_data: RuntimeData, requested_backend: str, ) -> None: + """Validate runtime backend. + + Raises: + ValidationError: If validation fails. + """ expected_kind = expected_backend_kind(requested_backend) runtime_backend = runtime_data["backend"] runtime_kind = runtime_backend["kind"] @@ -83,6 +95,7 @@ def compose_manifest( version: str, backend: str, ) -> dict[str, object]: + """Execute compose manifest operation.""" version = version.removeprefix("v") runtime_manifest_path = runtime / "manifest.json" runtime_manifest: RuntimeManifest = json.loads( @@ -116,6 +129,11 @@ def compose_manifest( def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser() parser.add_argument("--bundle", type=Path, required=True) parser.add_argument("--host", type=Path, required=True) @@ -131,6 +149,11 @@ def parse_args() -> argparse.Namespace: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args() manifest = compose_manifest( args.bundle, args.host, args.runtime, args.version, args.backend diff --git a/scripts/generate-bench-corpus.py b/scripts/generate-bench-corpus.py old mode 100755 new mode 100644 index 0b7cf9a10c..d29d38c2e4 --- a/scripts/generate-bench-corpus.py +++ b/scripts/generate-bench-corpus.py @@ -22,6 +22,11 @@ def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("tier") parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG) @@ -155,6 +160,7 @@ def main() -> int: def require_hf() -> None: + """Execute require hf operation.""" try: subprocess.run(["hf", "--version"], check=True, stdout=subprocess.DEVNULL) except Exception as error: @@ -162,6 +168,7 @@ def require_hf() -> None: def require_duckdb() -> None: + """Execute require duckdb operation.""" if python_has_duckdb(sys.executable) or command_exists("uv"): return raise RuntimeError( @@ -172,6 +179,7 @@ def require_duckdb() -> None: def python_has_duckdb(python: str) -> bool: + """Execute python has duckdb operation.""" return ( subprocess.run( [python, "-c", "import duckdb"], @@ -183,6 +191,7 @@ def python_has_duckdb(python: str) -> bool: def command_exists(name: str) -> bool: + """Execute command exists operation.""" return ( subprocess.run( ["bash", "-lc", f"command -v {name} >/dev/null"], @@ -194,17 +203,20 @@ def command_exists(name: str) -> bool: def read_json(path: Path) -> Any: + """Execute read json operation.""" with path.open("r", encoding="utf-8") as handle: return json.load(handle) def write_json(path: Path, value: Any) -> None: + """Save json to destination.""" with path.open("w", encoding="utf-8") as handle: json.dump(value, handle, ensure_ascii=False, indent=2, sort_keys=True) handle.write("\n") def rel(path: Path) -> str: + """Execute rel operation.""" try: return str(path.relative_to(ROOT)) except ValueError: @@ -212,6 +224,7 @@ def rel(path: Path) -> str: def git_commit() -> str | None: + """Execute git commit operation.""" try: output = subprocess.check_output( ["git", "rev-parse", "HEAD"], @@ -225,6 +238,7 @@ def git_commit() -> str | None: def hf_dataset_info(dataset: str, revision: str) -> dict[str, Any]: + """Execute hf dataset info operation.""" output = subprocess.check_output( ["hf", "datasets", "info", dataset, "--revision", revision, "--format", "json"], cwd=ROOT, @@ -234,6 +248,7 @@ def hf_dataset_info(dataset: str, revision: str) -> dict[str, Any]: def download_source(source: dict[str, Any], revision: str, hf_root: Path) -> Path: + """Execute download source operation.""" local_dir = hf_root / safe_name(source["dataset"]) / revision local_dir.mkdir(parents=True, exist_ok=True) include = parquet_include_patterns(source) @@ -260,6 +275,7 @@ def download_source(source: dict[str, Any], revision: str, hf_root: Path) -> Pat def download_converted_parquet(source: dict[str, Any], local_dir: Path) -> None: + """Execute download converted parquet operation.""" output = subprocess.check_output( [ "hf", @@ -293,6 +309,7 @@ def download_converted_parquet(source: dict[str, Any], local_dir: Path) -> None: def hf_headers() -> dict[str, str]: + """Execute hf headers operation.""" headers = {"User-Agent": "skippy-runtime-bench-corpus/1"} token = os.environ.get("HF_TOKEN") if token: @@ -301,6 +318,7 @@ def hf_headers() -> dict[str, str]: def parquet_include_patterns(source: dict[str, Any]) -> list[str]: + """Execute parquet include patterns operation.""" config = source["config"] split = source["split"] return [ @@ -314,6 +332,7 @@ def parquet_include_patterns(source: dict[str, Any]) -> list[str]: def find_parquet_files(local_dir: Path, source: dict[str, Any]) -> list[Path]: + """Execute find parquet files operation.""" config = source["config"] split = source["split"] files = sorted(local_dir.rglob("*.parquet")) @@ -340,6 +359,7 @@ def sample_rows( seed: int, limit: int, ) -> list[dict[str, Any]]: + """Execute sample rows operation.""" table_expr = "[" + ",".join(sql_string(str(path)) for path in parquet_files) + "]" material = f"{seed}:{source['name']}:{source['dataset']}:{source['config']}:{source['split']}" source_seed = int.from_bytes(hashlib.sha256(material.encode()).digest()[:8], "little") @@ -358,6 +378,7 @@ def sample_rows( def run_duckdb_json(query: str) -> str: + """Run duckdb json operation.""" code = """ import duckdb import json @@ -378,10 +399,12 @@ def run_duckdb_json(query: str) -> str: def sql_string(value: str) -> str: + """Execute sql string operation.""" return "'" + value.replace("'", "''") + "'" def safe_name(value: str) -> str: + """Execute safe name operation.""" return value.replace("/", "--") @@ -394,6 +417,7 @@ def normalize_row( max_prompt_chars: int, target_prompt_chars: int | None, ) -> dict[str, Any] | None: + """Execute normalize row operation.""" adapter = source["adapter"] prompt, expected, metadata, session_group = ADAPTERS[adapter](row) if prompt is None: @@ -436,6 +460,7 @@ def normalize_loop_rows( max_prompt_chars: int, target_prompt_chars: int | None, ) -> list[dict[str, Any]]: + """Execute normalize loop rows operation.""" adapter = source["adapter"] builder = LOOP_ADAPTERS.get(adapter) if builder is None: @@ -486,6 +511,7 @@ def normalize_loop_rows( def expand_prompt_to_chars(prompt: str, target_chars: int) -> str: + """Execute expand prompt to chars operation.""" prompt = clean_text(prompt) if len(prompt) >= target_chars: return prompt @@ -501,6 +527,7 @@ def expand_prompt_to_chars(prompt: str, target_chars: int) -> str: def truncate_text(value: str, max_chars: int) -> str: + """Execute truncate text operation.""" value = clean_text(value) if len(value) <= max_chars: return value @@ -514,6 +541,7 @@ def truncate_text(value: str, max_chars: int) -> str: def clean_text(value: Any) -> str: + """Execute clean text operation.""" if value is None: return "" if isinstance(value, str): @@ -522,6 +550,7 @@ def clean_text(value: Any) -> str: def commitpack_edit(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute commitpack edit operation.""" old = clean_text(row.get("old_contents")) new = clean_text(row.get("new_contents")) if not old or not new: @@ -547,6 +576,7 @@ def commitpack_edit(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any def code_refinement(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute code refinement operation.""" buggy = clean_text(row.get("buggy")) fixed = clean_text(row.get("fixed")) if not buggy or not fixed: @@ -560,6 +590,7 @@ def code_refinement(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any def swe_smith_trajectory_loop(row: dict[str, Any]) -> tuple[list[str], Any, dict[str, Any], str | None]: + """Execute swe smith trajectory loop operation.""" messages = row.get("messages") if not isinstance(messages, list): return [], None, {}, None @@ -591,6 +622,7 @@ def swe_smith_trajectory_loop(row: dict[str, Any]) -> tuple[list[str], Any, dict def agent_trajectory_prompt(transcript: list[tuple[str, str]]) -> str: + """Execute agent trajectory prompt operation.""" rendered: list[str] = [] for role, content in transcript[-12:]: rendered.append(f"{role.upper()}:\n{content}") @@ -603,11 +635,13 @@ def agent_trajectory_prompt(transcript: list[tuple[str, str]]) -> str: def sample_key(row: dict[str, Any]) -> str: + """Execute sample key operation.""" material = json.dumps(row, ensure_ascii=False, sort_keys=True, default=str) return hashlib.sha256(material.encode()).hexdigest()[:12] def swe_bench_issue(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute swe bench issue operation.""" statement = clean_text(row.get("problem_statement")) if not statement: return None, None, {}, None @@ -626,6 +660,7 @@ def swe_bench_issue(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any def apps_codegen(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute apps codegen operation.""" question = clean_text(row.get("question")) if not question: return None, None, {}, None @@ -637,6 +672,7 @@ def apps_codegen(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], def codesearchnet_explain(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute codesearchnet explain operation.""" code = clean_text(row.get("code")) comment = clean_text(row.get("comment")) if not code or not comment: @@ -650,6 +686,7 @@ def codesearchnet_explain(row: dict[str, Any]) -> tuple[str | None, Any, dict[st def xlam_tool_call(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute xlam tool call operation.""" query = clean_text(row.get("query")) tools = clean_text(row.get("tools")) if not query or not tools: @@ -666,6 +703,7 @@ def xlam_tool_call(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any] def spider_sql(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute spider sql operation.""" schema = clean_text(row.get("db_schema")) question = clean_text(row.get("question")) if not schema or not question: @@ -682,6 +720,7 @@ def spider_sql(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], st def oasst_prompt(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute oasst prompt operation.""" if row.get("role") != "prompter" or row.get("lang") != "en": return None, None, {}, None text = clean_text(row.get("text")) @@ -691,6 +730,7 @@ def oasst_prompt(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], def dolly_instruction(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute dolly instruction operation.""" instruction = clean_text(row.get("instruction")) context = clean_text(row.get("context")) if not instruction: @@ -702,6 +742,7 @@ def dolly_instruction(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, A def gsm8k_reasoning(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute gsm8k reasoning operation.""" question = clean_text(row.get("question")) if not question: return None, None, {}, None @@ -710,6 +751,7 @@ def gsm8k_reasoning(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any def xsum_summarize(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: + """Execute xsum summarize operation.""" document = clean_text(row.get("document")) if not document: return None, None, {}, None diff --git a/scripts/generate-skippy-api-doc.py b/scripts/generate-skippy-api-doc.py index 1804f08196..e2b1328d35 100644 --- a/scripts/generate-skippy-api-doc.py +++ b/scripts/generate-skippy-api-doc.py @@ -12,6 +12,7 @@ @dataclass(frozen=True) class Function: + """Represents Function functionality.""" name: str declaration: str brief: str @@ -19,6 +20,7 @@ class Function: @dataclass(frozen=True) class Header: + """Represents Header functionality.""" name: str brief: str declarations: tuple[str, ...] @@ -26,10 +28,12 @@ class Header: def normalize_declaration(declaration: str) -> str: + """Execute normalize declaration operation.""" return re.sub(r"\s+", " ", declaration.strip()) def pretty_declaration(declaration: str) -> str: + """Execute pretty declaration operation.""" declaration = normalize_declaration(declaration) declaration = declaration.replace("(", "(\n ", 1) declaration = declaration.replace(", ", ",\n ") @@ -38,19 +42,23 @@ def pretty_declaration(declaration: str) -> str: def anchor_id(prefix: str, value: str) -> str: + """Execute anchor id operation.""" slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-") return f"skippy-{prefix}-{slug}" def header_anchor(header: Header) -> str: + """Execute header anchor operation.""" return anchor_id("header", header.name) def function_anchor(function: Function) -> str: + """Execute function anchor operation.""" return anchor_id("fn", function.name) def comment_brief(comment: str) -> str: + """Execute comment brief operation.""" lines = [] for line in comment.splitlines(): line = re.sub(r"^\s*\*/\s*$", "", line) @@ -65,6 +73,11 @@ def comment_brief(comment: str) -> str: def parse_header(path: Path) -> Header: + """Parse and validate header. + + Returns: + Parsed result. + """ text = path.read_text() file_comment = re.search(r"/\*\*.*?@file.*?\*/", text, re.DOTALL) if file_comment is None: @@ -101,6 +114,7 @@ def parse_header(path: Path) -> Header: def render(headers: list[Header], include_dir: Path) -> str: + """Render output for render.""" functions = [function for header in headers for function in header.functions] lines = [ "---", @@ -221,6 +235,11 @@ def render(headers: list[Header], include_dir: Path) -> str: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ parser = argparse.ArgumentParser(description=__doc__) repo_root = Path(__file__).resolve().parents[1] parser.add_argument( diff --git a/scripts/hf-skippy-convert-job.py b/scripts/hf-skippy-convert-job.py index 784787e3ba..6fbd0f5b85 100644 --- a/scripts/hf-skippy-convert-job.py +++ b/scripts/hf-skippy-convert-job.py @@ -16,11 +16,13 @@ def run(*command: str, cwd: Path | None = None) -> None: + """Run run operation.""" print("+", " ".join(command), flush=True) subprocess.run(command, cwd=cwd, check=True) def ensure_build_tools() -> None: + """Execute ensure build tools operation.""" required = ("git", "curl", "cmake", "c++", "ld.lld") if any(shutil.which(tool) is None for tool in required): if shutil.which("apt-get") is None: @@ -49,6 +51,11 @@ def ensure_build_tools() -> None: def checkout_mesh(repo: str, revision: str, root: Path) -> None: + """Validate checkout mesh. + + Raises: + ValidationError: If validation fails. + """ if root.exists(): shutil.rmtree(root) run("git", "clone", "--filter=blob:none", repo, str(root)) @@ -56,6 +63,7 @@ def checkout_mesh(repo: str, revision: str, root: Path) -> None: def write_beta_card(artifact_dir: Path, source_repo: str, revision: str) -> None: + """Save beta card to destination.""" card = f"""--- license: apache-2.0 base_model: {source_repo} @@ -79,6 +87,7 @@ def write_beta_card(artifact_dir: Path, source_repo: str, revision: str) -> None def convert(args: argparse.Namespace, root: Path) -> Path: + """Execute convert operation.""" binary = root / "target" / "release" / "skippy-quantize" run("just", "skippy-quantize-standalone-release-build", "cpu", cwd=root) work = Path(args.work_dir) @@ -140,6 +149,7 @@ def convert(args: argparse.Namespace, root: Path) -> Path: def upload(args: argparse.Namespace, artifact_dir: Path) -> None: + """Execute upload operation.""" from huggingface_hub import HfApi api = HfApi(token=os.environ["HF_TOKEN"]) @@ -152,6 +162,11 @@ def upload(args: argparse.Namespace, artifact_dir: Path) -> None: def validate_converted_artifact(artifact_dir: Path) -> None: + """Validate converted artifact. + + Raises: + ValidationError: If validation fails. + """ required_files = ("README.md", "skippy-convert-manifest.json") missing = [name for name in required_files if not (artifact_dir / name).is_file()] if not artifact_dir.is_dir() or missing: @@ -184,6 +199,7 @@ def validate_converted_artifact(artifact_dir: Path) -> None: def converted_artifact_dir(args: argparse.Namespace) -> Path: + """Execute converted artifact dir operation.""" artifact_dir = Path(args.work_dir) / "target" / args.target_prefix if args.upload_only: validate_converted_artifact(artifact_dir) @@ -191,6 +207,11 @@ def converted_artifact_dir(args: argparse.Namespace) -> Path: def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser() parser.add_argument("--source", default="/mnt/checkpoint") parser.add_argument("--source-repo", required=True) @@ -217,6 +238,11 @@ def parse_args() -> argparse.Namespace: def main() -> None: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args() os.environ.setdefault("HF_HOME", str(Path(args.work_dir) / "hf-home")) # The work directory can be a mounted bucket. Xet's shard cache performs diff --git a/scripts/hf-skippy-mtp-certify-job.py b/scripts/hf-skippy-mtp-certify-job.py index d9f0b3d3ab..898855f97e 100644 --- a/scripts/hf-skippy-mtp-certify-job.py +++ b/scripts/hf-skippy-mtp-certify-job.py @@ -24,11 +24,13 @@ def run(*command: str, cwd: Path | None = None) -> None: + """Run run operation.""" print("+", " ".join(command), flush=True) subprocess.run(command, cwd=cwd, check=True) def ensure_build_tools() -> None: + """Execute ensure build tools operation.""" required = ("git", "curl", "cmake", "c++", "ld.lld") if any(shutil.which(tool) is None for tool in required): if shutil.which("apt-get") is None: @@ -57,6 +59,11 @@ def ensure_build_tools() -> None: def checkout_mesh(repo: str, revision: str, root: Path) -> None: + """Validate checkout mesh. + + Raises: + ValidationError: If validation fails. + """ if root.exists(): shutil.rmtree(root) run("git", "clone", "--filter=blob:none", repo, str(root)) @@ -64,6 +71,7 @@ def checkout_mesh(repo: str, revision: str, root: Path) -> None: def model_parts(args: argparse.Namespace) -> list[Path]: + """Execute model parts operation.""" parts = sorted(Path(args.model_root).glob(args.model_pattern)) if len(parts) != args.expected_parts: raise RuntimeError( @@ -74,6 +82,7 @@ def model_parts(args: argparse.Namespace) -> list[Path]: def require_gguf_magic(path: Path) -> Path: + """Execute require gguf magic operation.""" with path.open("rb") as handle: magic = handle.read(4) if magic != b"GGUF": @@ -82,6 +91,11 @@ def require_gguf_magic(path: Path) -> Path: def validate_projector_url(url: str) -> urllib.parse.ParseResult: + """Validate projector url. + + Raises: + ValidationError: If validation fails. + """ parsed = urllib.parse.urlparse(url) if parsed.scheme != "https": raise RuntimeError(f"unsupported projector URL scheme: {parsed.scheme!r}") @@ -109,12 +123,15 @@ def validate_projector_url(url: str) -> urllib.parse.ParseResult: class TrustedProjectorRedirectHandler(urllib.request.HTTPRedirectHandler): + """Represents TrustedProjectorRedirectHandler functionality.""" def redirect_request(self, req, fp, code, msg, headers, newurl): # noqa: ANN001 + """Execute redirect request operation.""" validate_projector_url(newurl) return super().redirect_request(req, fp, code, msg, headers, newurl) def copy_projector_response(response, output) -> None: # noqa: ANN001 + """Execute copy projector response operation.""" content_length = response.headers.get("Content-Length") if content_length is not None and int(content_length) > PROJECTOR_DOWNLOAD_MAX_BYTES: raise RuntimeError("projector download exceeds the maximum supported size") @@ -127,6 +144,7 @@ def copy_projector_response(response, output) -> None: # noqa: ANN001 def projector_path(args: argparse.Namespace) -> Path: + """Execute projector path operation.""" if not args.projector_url: return require_gguf_magic(Path(args.projector)) parsed = validate_projector_url(args.projector_url) @@ -151,6 +169,7 @@ def projector_path(args: argparse.Namespace) -> Path: def run_report(command: list[str], report_out: str) -> None: + """Run report operation.""" print("+", " ".join(command), flush=True) completed = subprocess.run(command, text=True, capture_output=True) if completed.stderr: @@ -166,6 +185,7 @@ def run_report(command: list[str], report_out: str) -> None: def certify(args: argparse.Namespace, mesh_root: Path) -> None: + """Execute certify operation.""" binary = mesh_root / "target" / "release" / "skippy-quantize" run("just", "skippy-quantize-standalone-release-build", "cpu", cwd=mesh_root) projector = projector_path(args) @@ -199,6 +219,11 @@ def certify(args: argparse.Namespace, mesh_root: Path) -> None: def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser() parser.add_argument("--model-root", default="/target") parser.add_argument("--model-pattern", required=True) @@ -218,6 +243,11 @@ def parse_args() -> argparse.Namespace: def main() -> None: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args() ensure_build_tools() mesh_root = Path("/tmp/mesh-llm") diff --git a/scripts/manage-build-cache.py b/scripts/manage-build-cache.py old mode 100755 new mode 100644 index cb205bdcef..c26a4a3ed2 --- a/scripts/manage-build-cache.py +++ b/scripts/manage-build-cache.py @@ -32,6 +32,17 @@ class CacheError(RuntimeError): def parse_size(value: str) -> int: + """Parse a human-readable size string (e.g., '80GiB') into bytes. + + Args: + value: Size string with optional unit (B, KiB, MiB, GiB, TiB). + + Returns: + Size in bytes. + + Raises: + argparse.ArgumentTypeError: If the size format is invalid. + """ value = value.removeprefix("max_size=") match = SIZE_PATTERN.fullmatch(value.strip()) if not match: @@ -40,6 +51,17 @@ def parse_size(value: str) -> int: def parse_age(value: str) -> int: + """Parse a maximum age string into days. + + Args: + value: Age string representing days (e.g., '14'). + + Returns: + Age in days. + + Raises: + argparse.ArgumentTypeError: If the age format is invalid. + """ try: return int(value.removeprefix("max_age=")) except ValueError as error: @@ -47,6 +69,14 @@ def parse_age(value: str) -> int: def human_size(value: int) -> str: + """Convert bytes to a human-readable size string. + + Args: + value: Size in bytes. + + Returns: + Human-readable size string (e.g., '1.5 GiB'). + """ amount = float(value) for unit in ("B", "KiB", "MiB", "GiB", "TiB"): if amount < 1024 or unit == "TiB": @@ -56,6 +86,14 @@ def human_size(value: int) -> str: def tree_metrics(path: Path) -> tuple[int, float]: + """Calculate total size and newest modification time for a path tree. + + Args: + path: File or directory path to measure. + + Returns: + Tuple of (total bytes, newest mtime). + """ if not path.exists(): return 0, 0.0 if path.is_file() or path.is_symlink(): @@ -79,6 +117,14 @@ def tree_metrics(path: Path) -> tuple[int, float]: def immediate_entries(path: Path) -> list[dict[str, Any]]: + """Collect metrics for immediate children of a directory, sorted by size. + + Args: + path: Directory path to inspect. + + Returns: + List of entry dictionaries with path, bytes, and newest_mtime fields. + """ entries = [] if path.is_dir(): for child in path.iterdir(): @@ -88,6 +134,17 @@ def immediate_entries(path: Path) -> list[dict[str, Any]]: def cargo_metadata(workspace: Path) -> dict[str, Any]: + """Retrieve Cargo workspace metadata via just command. + + Args: + workspace: Cargo workspace root directory. + + Returns: + Parsed Cargo metadata JSON. + + Raises: + CacheError: If cargo metadata command fails. + """ result = subprocess.run( ["just", "cache-cargo-metadata"], cwd=workspace, check=False, capture_output=True, text=True, @@ -98,10 +155,27 @@ def cargo_metadata(workspace: Path) -> dict[str, Any]: def cargo_packages(workspace: Path) -> list[str]: + """Get sorted list of all Cargo package names in the workspace. + + Args: + workspace: Cargo workspace root directory. + + Returns: + Sorted list of package names. + """ return sorted({package["name"] for package in cargo_metadata(workspace)["packages"]}) def reject_separate_build_directory(workspace: Path, managed_target: Path) -> None: + """Validate that Cargo build directory configuration is supported. + + Args: + workspace: Cargo workspace root directory. + managed_target: Expected target directory path. + + Raises: + CacheError: If build directory configuration is unsupported. + """ managed_target = managed_target.resolve() if os.environ.get("CARGO_BUILD_BUILD_DIR"): raise CacheError("CARGO_BUILD_BUILD_DIR is unsupported by build-cache management") @@ -129,6 +203,15 @@ def artifact_roots(target: Path, leaf: str) -> list[Path]: def package_metrics(target: Path, packages: Iterable[str]) -> list[dict[str, Any]]: + """Calculate size and age metrics for Cargo packages in the target directory. + + Args: + target: Cargo target directory. + packages: Iterable of package names to measure. + + Returns: + List of package metrics sorted by age and size. + """ normalized = {package: package.replace("-", "_") for package in packages} totals = {package: [0, 0.0] for package in normalized} roots = [*artifact_roots(target, "deps"), *artifact_roots(target, "build")] @@ -150,6 +233,11 @@ def package_metrics(target: Path, packages: Iterable[str]) -> list[dict[str, Any def active_compilers() -> list[str]: + """Detect active Rust compiler processes. + + Returns: + List of process lines for active cargo/rustc/rustdoc/clippy processes. + """ result = subprocess.run( ["ps", "-axo", "pid=,comm=,args="], check=True, capture_output=True, text=True, ) @@ -164,6 +252,19 @@ def active_compilers() -> list[str]: @contextmanager def cache_lock(target: Path, *, exclusive: bool, nonblocking: bool) -> Iterator[BinaryIO]: + """Acquire a file lock for cache operations. + + Args: + target: Target directory containing the lock file. + exclusive: Whether to acquire an exclusive (write) lock. + nonblocking: Whether to fail immediately if lock is unavailable. + + Yields: + Open lock file handle. + + Raises: + CacheError: If lock cannot be acquired in nonblocking mode. + """ target.mkdir(parents=True, exist_ok=True) lock_file = (target / ".mesh-llm-cache-prune.lock").open("a+b") operation = fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH @@ -181,6 +282,15 @@ def cache_lock(target: Path, *, exclusive: bool, nonblocking: bool) -> Iterator[ def remove_tree(path: Path, target: Path) -> None: + """Safely remove a directory tree within the target directory. + + Args: + path: Path to remove. + target: Target directory that must contain the path. + + Raises: + CacheError: If path is outside target or invalid. + """ candidate = Path(os.path.abspath(path)) target_absolute = Path(os.path.abspath(target)) target_resolved = target.resolve() @@ -200,6 +310,18 @@ def remove_tree(path: Path, target: Path) -> None: def prune_incremental( target: Path, cutoff: float, current_bytes: int, max_bytes: int, execute: bool, ) -> tuple[int, list[dict[str, Any]]]: + """Prune incremental compilation artifacts that are old or exceed size limit. + + Args: + target: Cargo target directory. + cutoff: Age cutoff timestamp. + current_bytes: Current total size in bytes. + max_bytes: Maximum allowed bytes. + execute: Whether to actually remove files. + + Returns: + Tuple of (updated byte count, list of pruned actions). + """ candidates = [] for root in artifact_roots(target, "incremental"): for child in root.iterdir(): @@ -221,6 +343,22 @@ def prune_packages( workspace: Path, target: Path, current_bytes: int, max_bytes: int, cutoff: float, execute: bool, ) -> tuple[int, list[dict[str, Any]]]: + """Prune Cargo package artifacts that are old or exceed size limit. + + Args: + workspace: Cargo workspace root directory. + target: Cargo target directory. + current_bytes: Current total size in bytes. + max_bytes: Maximum allowed bytes. + cutoff: Age cutoff timestamp. + execute: Whether to actually remove files. + + Returns: + Tuple of (updated byte count, list of pruned actions). + + Raises: + CacheError: If cargo clean command fails. + """ actions = [] for metrics in package_metrics(target, cargo_packages(workspace)): if current_bytes <= max_bytes and metrics["newest_mtime"] >= cutoff: @@ -253,6 +391,17 @@ def prune_packages( def snapshot(workspace: Path, target: Path, max_bytes: int, max_age_days: int) -> dict[str, Any]: + """Create a cache status snapshot with size and age information. + + Args: + workspace: Cargo workspace root directory. + target: Cargo target directory. + max_bytes: Maximum allowed bytes. + max_age_days: Maximum age in days. + + Returns: + Dictionary containing cache status information. + """ total, newest = tree_metrics(target) return { "schema": "mesh-llm.local-build-cache", "schema_version": 1, @@ -264,6 +413,11 @@ def snapshot(workspace: Path, target: Path, max_bytes: int, max_age_days: int) - def render_status(report: dict[str, Any]) -> None: + """Print human-readable cache status report. + + Args: + report: Cache snapshot dictionary. + """ print(f"Cargo target: {human_size(report['target_bytes'])}") print(f"Configured limit: {human_size(report['target_limit_bytes'])}") print(f"Configured maximum age: {report['max_age_days']} days") @@ -275,6 +429,11 @@ def render_status(report: dict[str, Any]) -> None: def parse_args() -> argparse.Namespace: + """Parse command-line arguments for cache management operations. + + Returns: + Parsed arguments namespace. + """ parser = argparse.ArgumentParser() commands = parser.add_subparsers(dest="command", required=True) for command in ("status", "prune"): @@ -294,6 +453,14 @@ def parse_args() -> argparse.Namespace: def main() -> int: + """Execute cache management commands: status, prune, or build. + + Returns: + Exit code: 0 for success, non-zero for errors. + + Raises: + CacheError: If validation or operations fail. + """ arguments = parse_args() workspace = arguments.workspace.resolve() target = (arguments.target_dir or workspace / "target").resolve() @@ -325,6 +492,16 @@ def main() -> int: def run_prune(arguments: argparse.Namespace, workspace: Path, target: Path) -> int: + """Execute cache pruning based on age and size constraints. + + Args: + arguments: Parsed command-line arguments. + workspace: Cargo workspace root directory. + target: Cargo target directory. + + Returns: + Exit code 0 on success. + """ before = snapshot(workspace, target, arguments.max_size, arguments.max_age) cutoff = time.time() - arguments.max_age * 86400 current, incremental = prune_incremental( diff --git a/scripts/plan-ci.py b/scripts/plan-ci.py index 03a3896a67..8587a84283 100644 --- a/scripts/plan-ci.py +++ b/scripts/plan-ci.py @@ -255,6 +255,7 @@ def _assert_acyclic(dependencies: dict[str, list[str]]) -> None: visited: set[str] = set() def visit(node: str) -> None: + """Execute visit operation.""" if node in visiting: raise PlanError(f"slice dependency cycle includes {node!r}") if node in visited: @@ -501,6 +502,7 @@ def _select_rows( smoke_ids = [row_id for row_id in smoke_ids if row_id == "core"] or [smoke_ids[0]] def unique_rows(mapping: dict[str, dict[str, Any]], ids: Iterable[str], field: str) -> list[dict[str, Any]]: + """Execute unique rows operation.""" result: list[dict[str, Any]] = [] seen: set[str] = set() for row_id in ids: @@ -790,6 +792,11 @@ def _validate_plan(plan: dict[str, Any], slices: dict[str, Any], packages: list[ def build_plan(payload: object, *, root: Path = ROOT) -> dict[str, Any]: + """Create plan. + + Returns: + Created object. + """ input_data = _validate_input(payload) ownership = _load_manifest(root / "ci" / "ownership.yml") slices = _load_manifest(root / "ci" / "slices.yml") @@ -882,6 +889,11 @@ def build_plan(payload: object, *, root: Path = ROOT) -> dict[str, Any]: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ try: payload = json.load(sys.stdin) plan = build_plan(payload) diff --git a/scripts/qa-agent-tool-call-reliability.py b/scripts/qa-agent-tool-call-reliability.py old mode 100755 new mode 100644 index 206b60315c..53e4fdb729 --- a/scripts/qa-agent-tool-call-reliability.py +++ b/scripts/qa-agent-tool-call-reliability.py @@ -24,16 +24,19 @@ class Probe(NamedTuple): + """Represents Probe functionality.""" model: str attempt: int class ToolCall(NamedTuple): + """Represents ToolCall functionality.""" call_id: str key: str class ProbeResult(NamedTuple): + """Represents ProbeResult functionality.""" model: str attempt: int phase: str @@ -44,6 +47,7 @@ class ProbeResult(NamedTuple): def normalize_v1_base(base_url: str) -> str: + """Execute normalize v1 base operation.""" base = base_url.strip().rstrip("/") if not base: raise ValueError("base URL is empty") @@ -53,6 +57,11 @@ def normalize_v1_base(base_url: str) -> str: def parse_models(value: str) -> list[str]: + """Parse and validate models. + + Returns: + Parsed result. + """ models = [part.strip() for part in value.split(",") if part.strip()] if not models: raise ValueError("at least one model is required") @@ -60,6 +69,11 @@ def parse_models(value: str) -> list[str]: def build_plan(models: Iterable[str], attempts: int) -> list[Probe]: + """Create plan. + + Returns: + Created object. + """ if attempts < 1: raise ValueError("attempts must be at least 1") return [ @@ -70,6 +84,7 @@ def build_plan(models: Iterable[str], attempts: int) -> list[Probe]: def render_plan(plan: Iterable[Probe], base_url: str) -> str: + """Render output for plan.""" payload = { "name": "agent-tool-call-reliability", "endpoint": normalize_v1_base(base_url), @@ -92,6 +107,7 @@ def render_plan(plan: Iterable[Probe], base_url: str) -> str: def tool_schema() -> list[dict[str, Any]]: + """Execute tool schema operation.""" return [ { "type": "function", @@ -115,6 +131,7 @@ def tool_schema() -> list[dict[str, Any]]: def initial_messages(attempt: int) -> list[dict[str, str]]: + """Execute initial messages operation.""" return [ { "role": "system", @@ -131,6 +148,11 @@ def initial_messages(attempt: int) -> list[dict[str, str]]: def build_tool_probe_request(model: str, attempt: int) -> dict[str, Any]: + """Create tool probe request. + + Returns: + Created object. + """ return { "model": model, "messages": initial_messages(attempt), @@ -148,12 +170,18 @@ def build_tool_probe_request(model: str, attempt: int) -> dict[str, Any]: def build_stream_tool_probe_request(model: str, attempt: int) -> dict[str, Any]: + """Create stream tool probe request. + + Returns: + Created object. + """ request = build_tool_probe_request(model, attempt) request["stream"] = True return request def extract_tool_call(response: dict[str, Any]) -> ToolCall: + """Execute extract tool call operation.""" _require_tool_call_finish(response) message = _first_message(response) calls = message.get("tool_calls") @@ -178,6 +206,7 @@ def extract_tool_call(response: dict[str, Any]) -> ToolCall: def extract_stream_tool_call(chunks: Iterable[dict[str, Any]]) -> ToolCall: + """Execute extract stream tool call operation.""" parts: dict[int, dict[str, Any]] = {} saw_tool_finish = False for chunk in chunks: @@ -225,6 +254,11 @@ def build_tool_result_request( assistant_message: dict[str, Any], call: ToolCall, ) -> dict[str, Any]: + """Create tool result request. + + Returns: + Created object. + """ expected = FIXTURE_FACTS[call.key] messages = initial_messages(attempt) messages.append(_sanitize_assistant_tool_message(assistant_message)) @@ -255,12 +289,22 @@ def build_stream_tool_result_request( assistant_message: dict[str, Any], call: ToolCall, ) -> dict[str, Any]: + """Create stream tool result request. + + Returns: + Created object. + """ request = build_tool_result_request(model, attempt, assistant_message, call) request["stream"] = True return request def validate_final_answer(response: dict[str, Any], expected: str) -> None: + """Validate final answer. + + Raises: + ValidationError: If validation fails. + """ message = _first_message(response) if message.get("tool_calls"): raise ValueError("continuation returned another tool call") @@ -269,6 +313,11 @@ def validate_final_answer(response: dict[str, Any], expected: str) -> None: def validate_final_content(content: Any, expected: str) -> None: + """Validate final content. + + Raises: + ValidationError: If validation fails. + """ if not isinstance(content, str) or not content.strip(): raise ValueError("continuation returned empty content") if expected not in content: @@ -276,6 +325,7 @@ def validate_final_content(content: Any, expected: str) -> None: def extract_stream_content(chunks: Iterable[dict[str, Any]]) -> str: + """Execute extract stream content operation.""" parts: list[str] = [] saw_choice = False for chunk in chunks: @@ -298,6 +348,7 @@ def extract_stream_content(chunks: Iterable[dict[str, Any]]) -> str: def write_jsonl(path: Path, results: Iterable[ProbeResult]) -> None: + """Save jsonl to destination.""" path.parent.mkdir(parents=True, exist_ok=True) with path.open("w", encoding="utf-8") as handle: for result in results: @@ -310,6 +361,7 @@ def run_probe( timeout: float, include_streaming: bool = True, ) -> list[ProbeResult]: + """Run probe operation.""" results: list[ProbeResult] = [] results.extend(run_non_stream_probe(base_url, probe, timeout)) if include_streaming: @@ -318,6 +370,7 @@ def run_probe( def run_non_stream_probe(base_url: str, probe: Probe, timeout: float) -> list[ProbeResult]: + """Run non stream probe operation.""" results: list[ProbeResult] = [] tool_started = time.monotonic() try: @@ -360,6 +413,7 @@ def run_non_stream_probe(base_url: str, probe: Probe, timeout: float) -> list[Pr def run_stream_probe(base_url: str, probe: Probe, timeout: float) -> list[ProbeResult]: + """Run stream probe operation.""" results: list[ProbeResult] = [] tool_started = time.monotonic() try: @@ -403,6 +457,7 @@ def run_stream_probe(base_url: str, probe: Probe, timeout: float) -> list[ProbeR def assistant_message_from_tool_call(call: ToolCall) -> dict[str, Any]: + """Execute assistant message from tool call operation.""" return { "role": "assistant", "content": None, @@ -425,6 +480,7 @@ def post_json( payload: dict[str, Any], timeout: float, ) -> tuple[dict[str, Any], int]: + """Execute post json operation.""" data = json.dumps(payload).encode("utf-8") request = urllib.request.Request( f"{normalize_v1_base(base_url)}{path}", @@ -461,6 +517,7 @@ def post_json_stream( payload: dict[str, Any], timeout: float, ) -> tuple[list[dict[str, Any]], int]: + """Execute post json stream operation.""" data = json.dumps(payload).encode("utf-8") request = urllib.request.Request( f"{normalize_v1_base(base_url)}{path}", @@ -488,6 +545,11 @@ def post_json_stream( def parse_sse_lines(lines: Iterable[str]) -> Iterable[dict[str, Any]]: + """Parse and validate sse lines. + + Returns: + Parsed result. + """ for raw_line in lines: line = raw_line.strip() if not line or line.startswith(":") or not line.startswith("data:"): @@ -505,6 +567,7 @@ def parse_sse_lines(lines: Iterable[str]) -> Iterable[dict[str, Any]]: def default_base_url() -> str: + """Execute default base url operation.""" env_base = ( os.environ.get("MESH_AGENT_TOOL_BASE_URL") or os.environ.get("MESH_AGENT_BASE_URL") @@ -519,6 +582,11 @@ def default_base_url() -> str: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args() base_url = normalize_v1_base(args.base_url) models = parse_models(args.models) @@ -543,6 +611,11 @@ def main() -> int: def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser( description="Probe OpenAI chat tool-call and tool-result continuation reliability.", ) @@ -568,6 +641,7 @@ def parse_args() -> argparse.Namespace: def print_summary(results: Iterable[ProbeResult], output: Path) -> None: + """Render output for summary.""" rows = list(results) passed = sum(1 for row in rows if row.ok) print(f"agent tool-call reliability: {passed}/{len(rows)} phases passed") diff --git a/scripts/qa-kv-tool-loop-stability.py b/scripts/qa-kv-tool-loop-stability.py old mode 100755 new mode 100644 index 446510a659..a809f3b8d5 --- a/scripts/qa-kv-tool-loop-stability.py +++ b/scripts/qa-kv-tool-loop-stability.py @@ -41,16 +41,19 @@ class ToolCall(NamedTuple): + """Represents ToolCall functionality.""" call_id: str key: str class CacheMetrics(NamedTuple): + """Represents CacheMetrics functionality.""" prompt_tokens: int cached_tokens: int class LogFinding(NamedTuple): + """Represents LogFinding functionality.""" path: str line_number: int pattern: str @@ -58,6 +61,7 @@ class LogFinding(NamedTuple): class NativeLogCheckpoint(NamedTuple): + """Represents NativeLogCheckpoint functionality.""" path: Path offset: int identity: tuple[int, int] | None @@ -65,6 +69,7 @@ class NativeLogCheckpoint(NamedTuple): class ProbeResult(NamedTuple): + """Represents ProbeResult functionality.""" model: str attempt: int phase: str @@ -77,6 +82,7 @@ class ProbeResult(NamedTuple): class OverlapRequest(NamedTuple): + """Represents OverlapRequest functionality.""" label: str payload: dict[str, Any] expects_tool_call: bool @@ -84,6 +90,7 @@ class OverlapRequest(NamedTuple): def normalize_v1_base(base_url: str) -> str: + """Execute normalize v1 base operation.""" base = base_url.strip().rstrip("/") if not base: raise ValueError("base URL is empty") @@ -93,6 +100,11 @@ def normalize_v1_base(base_url: str) -> str: def parse_models(value: str) -> list[str]: + """Parse and validate models. + + Returns: + Parsed result. + """ models = [part.strip() for part in value.split(",") if part.strip()] if not models: raise ValueError("at least one model is required") @@ -100,6 +112,11 @@ def parse_models(value: str) -> list[str]: def parse_native_logs(values: Iterable[str] | None) -> list[Path]: + """Parse and validate native logs. + + Returns: + Parsed result. + """ logs: list[Path] = [] env_value = os.environ.get("MESH_KV_TOOL_LOOP_NATIVE_LOGS") if env_value: @@ -114,6 +131,7 @@ def parse_native_logs(values: Iterable[str] | None) -> list[Path]: def dedupe_paths(paths: Iterable[Path]) -> list[Path]: + """Execute dedupe paths operation.""" deduped: list[Path] = [] seen: set[str] = set() for path in paths: @@ -137,6 +155,11 @@ def build_plan( native_logs: Iterable[Path], overlap_requests: int = DEFAULT_OVERLAP_REQUESTS, ) -> dict[str, Any]: + """Create plan. + + Returns: + Created object. + """ model_list = list(models) if attempts < 1: raise ValueError("attempts must be at least 1") @@ -225,10 +248,12 @@ def build_plan( def render_plan(plan: dict[str, Any]) -> str: + """Render output for plan.""" return json.dumps(plan, indent=2, sort_keys=True) def tool_schema() -> list[dict[str, Any]]: + """Execute tool schema operation.""" return [ { "type": "function", @@ -257,6 +282,11 @@ def build_tool_call_request( key: str = "primary", messages: list[dict[str, Any]] | None = None, ) -> dict[str, Any]: + """Create tool call request. + + Returns: + Created object. + """ request_messages = list(messages) if messages is not None else initial_messages(attempt, key) return { "model": model, @@ -280,6 +310,11 @@ def build_overlap_requests( attempt: int, overlap_requests: int, ) -> list[OverlapRequest]: + """Create overlap requests. + + Returns: + Created object. + """ if overlap_requests < 2: raise ValueError("overlap_requests must be at least 2") requests = [ @@ -311,6 +346,11 @@ def build_overlap_requests( def build_overlap_title_request(model: str, attempt: int) -> dict[str, Any]: + """Create overlap title request. + + Returns: + Created object. + """ return { "model": model, "messages": [ @@ -340,6 +380,11 @@ def build_overlap_tool_request( label: str, key: str, ) -> dict[str, Any]: + """Create overlap tool request. + + Returns: + Created object. + """ messages = [ { "role": "system", @@ -358,6 +403,7 @@ def build_overlap_tool_request( def initial_messages(attempt: int, key: str) -> list[dict[str, str]]: + """Execute initial messages operation.""" return [ { "role": "system", @@ -379,6 +425,11 @@ def build_tool_result_request( messages: list[dict[str, Any]], max_tokens: int = 128, ) -> dict[str, Any]: + """Create tool result request. + + Returns: + Created object. + """ return { "model": model, "messages": messages, @@ -391,6 +442,11 @@ def build_tool_result_request( def build_cache_request(model: str, tail: str) -> dict[str, Any]: + """Create cache request. + + Returns: + Created object. + """ return { "model": model, "messages": [ @@ -414,6 +470,7 @@ def build_cache_request(model: str, tail: str) -> dict[str, Any]: def stable_system_prefix() -> str: + """Execute stable system prefix operation.""" lines = [ "You are a deterministic KV/cache stability certification endpoint.", f"Pinned recall token: {KV_PIN}.", @@ -428,6 +485,7 @@ def stable_system_prefix() -> str: def extract_tool_call(response: dict[str, Any]) -> ToolCall: + """Execute extract tool call operation.""" finish_reason = _first_choice(response).get("finish_reason") if finish_reason != "tool_calls": raise ValueError(f"tool-call turn finish_reason was not tool_calls: {finish_reason!r}") @@ -452,6 +510,7 @@ def extract_tool_call(response: dict[str, Any]) -> ToolCall: def assistant_tool_message(response: dict[str, Any]) -> dict[str, Any]: + """Execute assistant tool message operation.""" message = dict(_first_message(response)) return { "role": "assistant", @@ -461,6 +520,7 @@ def assistant_tool_message(response: dict[str, Any]) -> dict[str, Any]: def tool_result_message(call: ToolCall) -> dict[str, Any]: + """Execute tool result message operation.""" return { "role": "tool", "tool_call_id": call.call_id, @@ -473,6 +533,7 @@ def tool_result_message(call: ToolCall) -> dict[str, Any]: def extract_cache_metrics(response: dict[str, Any]) -> CacheMetrics: + """Execute extract cache metrics operation.""" usage = response.get("usage") if not isinstance(usage, dict): return CacheMetrics(prompt_tokens=0, cached_tokens=0) @@ -489,6 +550,7 @@ def evaluate_cache_threshold( min_cached_tokens: int, suffix_prefill_limit: int, ) -> tuple[bool, str]: + """Execute evaluate cache threshold operation.""" if metrics.cached_tokens < min_cached_tokens: return ( False, @@ -518,6 +580,7 @@ def evaluate_cache_threshold( def scan_failure_logs(paths: Iterable[Path]) -> list[LogFinding]: + """Execute scan failure logs operation.""" findings: list[LogFinding] = [] for path in paths: if not path.exists(): @@ -547,6 +610,7 @@ def scan_failure_logs(paths: Iterable[Path]) -> list[LogFinding]: def capture_native_log_checkpoints(paths: Iterable[Path]) -> list[NativeLogCheckpoint]: + """Execute capture native log checkpoints operation.""" checkpoints: list[NativeLogCheckpoint] = [] for path in paths: try: @@ -568,6 +632,7 @@ def capture_native_log_checkpoints(paths: Iterable[Path]) -> list[NativeLogCheck def scan_failure_logs_since( checkpoints: Iterable[NativeLogCheckpoint], ) -> list[LogFinding]: + """Execute scan failure logs since operation.""" findings: list[LogFinding] = [] for checkpoint in checkpoints: findings.extend(scan_one_log_since(checkpoint)) @@ -575,6 +640,7 @@ def scan_failure_logs_since( def scan_one_log_since(checkpoint: NativeLogCheckpoint) -> list[LogFinding]: + """Execute scan one log since operation.""" path = checkpoint.path try: stat = path.stat() @@ -605,6 +671,7 @@ def scan_failure_lines( handle: Iterable[bytes], start_line_number: int = 1, ) -> list[LogFinding]: + """Execute scan failure lines operation.""" findings: list[LogFinding] = [] for line_number, raw_line in enumerate(handle, start=start_line_number): line = raw_line.decode("utf-8", errors="replace").strip() @@ -622,6 +689,7 @@ def scan_failure_lines( def line_number_start_for_offset(handle: Any, offset: int) -> int: + """Execute line number start for offset operation.""" if offset <= 0: return 1 handle.seek(0) @@ -637,10 +705,12 @@ def line_number_start_for_offset(handle: Any, offset: int) -> int: def file_identity(stat: os.stat_result) -> tuple[int, int]: + """Execute file identity operation.""" return (int(stat.st_dev), int(stat.st_ino)) def read_checkpoint_tail(path: Path, offset: int) -> bytes: + """Execute read checkpoint tail operation.""" if offset <= 0: return b"" start = max(offset - NATIVE_LOG_CHECKPOINT_TAIL_BYTES, 0) @@ -650,6 +720,11 @@ def read_checkpoint_tail(path: Path, offset: int) -> bytes: def checkpoint_tail_matches(checkpoint: NativeLogCheckpoint) -> bool: + """Validate checkpoint tail matches. + + Raises: + ValidationError: If validation fails. + """ if checkpoint.offset <= 0: return True try: @@ -659,6 +734,7 @@ def checkpoint_tail_matches(checkpoint: NativeLogCheckpoint) -> bool: def matched_failure_pattern(line: str) -> str | None: + """Execute matched failure pattern operation.""" for pattern in FAILURE_PATTERNS: if pattern in line: return pattern @@ -675,6 +751,7 @@ def run_tool_loop_probe( pressure_turns: int, transcript_dir: Path, ) -> ProbeResult: + """Run tool loop probe operation.""" started = time.monotonic() transcript_path = transcript_dir / safe_name(f"{model}-attempt-{attempt}.jsonl") messages = initial_messages(attempt, "primary") @@ -713,6 +790,7 @@ def run_final_after_tool( timeout: float, expected_values: Iterable[str], ) -> None: + """Run final after tool operation.""" messages.append( { "role": "user", @@ -737,6 +815,7 @@ def run_pressure_turns( pressure_turns: int, transcript_path: Path, ) -> None: + """Run pressure turns operation.""" for turn in range(1, pressure_turns + 1): messages.append( { @@ -765,6 +844,7 @@ def run_second_tool_loop( timeout: float, transcript_path: Path, ) -> None: + """Run second tool loop operation.""" messages.append( { "role": "user", @@ -792,6 +872,7 @@ def run_final_recall( timeout: float, transcript_path: Path, ) -> None: + """Run final recall operation.""" expected = [KV_PIN, FIXTURE_FACTS["primary"], FIXTURE_FACTS["secondary"]] messages.append( { @@ -818,6 +899,7 @@ def run_cache_probe( min_cached_tokens: int, suffix_prefill_limit: int, ) -> ProbeResult: + """Run cache probe operation.""" started = time.monotonic() try: if phase == "exact_prefix_cache": @@ -863,6 +945,7 @@ def measure_cache_reuse( warm_tail: str, measured_tail: str, ) -> tuple[int, CacheMetrics]: + """Execute measure cache reuse operation.""" warm = build_cache_request(model, warm_tail) measured = build_cache_request(model, measured_tail) post_json(base_url, "/chat/completions", warm, timeout) @@ -881,6 +964,7 @@ def run_overlap_tool_loop_probe( suffix_prefill_limit: int, transcript_dir: Path, ) -> ProbeResult: + """Run overlap tool loop probe operation.""" started = time.monotonic() transcript_path = transcript_dir / safe_name(f"{model}-attempt-{attempt}-overlap") try: @@ -945,9 +1029,11 @@ def run_initial_overlap_requests( contexts: list[OverlapRequest], timeout: float, ) -> list[tuple[OverlapRequest, dict[str, Any], int]]: + """Run initial overlap requests operation.""" barrier = threading.Barrier(len(contexts)) def send(context: OverlapRequest) -> tuple[OverlapRequest, dict[str, Any], int]: + """Execute send operation.""" try: barrier.wait(timeout=min(max(timeout, 1.0), 30.0)) except threading.BrokenBarrierError as exc: @@ -974,6 +1060,7 @@ def complete_overlap_tool_loop( timeout: float, transcript_path: Path, ) -> None: + """Execute complete overlap tool loop operation.""" messages = [dict(message) for message in context.payload["messages"]] first_call = extract_tool_call(response) record_transcript( @@ -989,6 +1076,7 @@ def complete_overlap_tool_loop( def run_native_log_scan(checkpoints: Iterable[NativeLogCheckpoint]) -> ProbeResult: + """Run native log scan operation.""" started = time.monotonic() findings = scan_failure_logs_since(checkpoints) if findings: @@ -1014,6 +1102,7 @@ def run_certification( output_dir: Path, overlap_requests: int = DEFAULT_OVERLAP_REQUESTS, ) -> list[ProbeResult]: + """Run certification operation.""" transcript_dir = output_dir / "transcripts" prepare_transcript_dir(transcript_dir) log_checkpoints = capture_native_log_checkpoints(native_logs) @@ -1069,6 +1158,7 @@ def run_certification( def prepare_transcript_dir(transcript_dir: Path) -> None: + """Execute prepare transcript dir operation.""" if transcript_dir.is_symlink() or transcript_dir.is_file(): transcript_dir.unlink() elif transcript_dir.exists(): @@ -1077,6 +1167,7 @@ def prepare_transcript_dir(transcript_dir: Path) -> None: def write_evidence(output_dir: Path, plan: dict[str, Any], results: Iterable[ProbeResult]) -> None: + """Save evidence to destination.""" output_dir.mkdir(parents=True, exist_ok=True) rows = list(results) manifest = dict(plan) @@ -1100,6 +1191,7 @@ def write_evidence(output_dir: Path, plan: dict[str, Any], results: Iterable[Pro def summarize_results(results: Iterable[ProbeResult]) -> dict[str, Any]: + """Execute summarize results operation.""" rows = list(results) passed = sum(1 for row in rows if row.ok) failed = len(rows) - passed @@ -1118,6 +1210,7 @@ def summarize_results(results: Iterable[ProbeResult]) -> dict[str, Any]: def render_summary_markdown(summary: dict[str, Any], results: Iterable[ProbeResult]) -> str: + """Render output for summary markdown.""" rows = list(results) status = "PASS" if summary["ok"] else "FAIL" lines = [ @@ -1153,6 +1246,7 @@ def post_json( payload: dict[str, Any], timeout: float, ) -> tuple[dict[str, Any], int]: + """Execute post json operation.""" data = json.dumps(payload).encode("utf-8") request = urllib.request.Request( f"{normalize_v1_base(base_url)}{path}", @@ -1183,6 +1277,11 @@ def post_json( def validate_message(response: dict[str, Any], expected_values: Iterable[str]) -> None: + """Validate message. + + Raises: + ValidationError: If validation fails. + """ message = _first_message(response) if message.get("tool_calls"): raise ValueError("expected final text, got another tool call") @@ -1201,6 +1300,7 @@ def record_transcript( tool_call_id: str | None = None, detail: str | None = None, ) -> None: + """Execute record transcript operation.""" path.parent.mkdir(parents=True, exist_ok=True) payload = { "phase": phase, @@ -1214,6 +1314,7 @@ def record_transcript( def print_summary(results: Iterable[ProbeResult], output_dir: Path) -> None: + """Render output for summary.""" rows = list(results) passed = sum(1 for row in rows if row.ok) print(f"kv/tool-loop stability: {passed}/{len(rows)} phases passed") @@ -1224,6 +1325,11 @@ def print_summary(results: Iterable[ProbeResult], output_dir: Path) -> None: def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser( description="Certify live mesh-llm KV/cache stability under OpenAI tool-loop pressure.", ) @@ -1280,6 +1386,7 @@ def parse_args() -> argparse.Namespace: def default_base_url() -> str: + """Execute default base url operation.""" env_base = os.environ.get("MESH_KV_TOOL_LOOP_BASE_URL") if env_base: return env_base @@ -1290,6 +1397,11 @@ def default_base_url() -> str: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args() base_url = normalize_v1_base(args.base_url) models = parse_models(args.models) @@ -1329,6 +1441,11 @@ def main() -> int: def validate_runtime_options(args: argparse.Namespace) -> None: + """Validate runtime options. + + Raises: + ValidationError: If validation fails. + """ if args.attempts < 1: raise ValueError("attempts must be at least 1") if args.pressure_turns < 0: @@ -1415,11 +1532,13 @@ def _result( def safe_name(value: str) -> str: + """Execute safe name operation.""" safe = "".join(char if char.isalnum() or char in "._-" else "_" for char in value) return f"{safe}.jsonl" def utc_now() -> str: + """Execute utc now operation.""" return dt.datetime.now(dt.timezone.utc).isoformat().replace("+00:00", "Z") diff --git a/scripts/qa-nightly-stability.py b/scripts/qa-nightly-stability.py old mode 100755 new mode 100644 index 7ba4dd1c16..554ae284d3 --- a/scripts/qa-nightly-stability.py +++ b/scripts/qa-nightly-stability.py @@ -27,6 +27,7 @@ class CommandSpec(NamedTuple): + """Represents CommandSpec functionality.""" name: str command: list[str] env: dict[str, str] @@ -35,6 +36,7 @@ class CommandSpec(NamedTuple): class CommandResult(NamedTuple): + """Represents CommandResult functionality.""" name: str status: str exit_code: int @@ -43,6 +45,7 @@ class CommandResult(NamedTuple): class ProbeResult(NamedTuple): + """Represents ProbeResult functionality.""" model: str | None attempt: int | None phase: str @@ -56,6 +59,7 @@ class ProbeResult(NamedTuple): class AttestationResult(NamedTuple): + """Represents AttestationResult functionality.""" status: str ok: bool binary: str | None @@ -68,6 +72,7 @@ class AttestationResult(NamedTuple): def repo_root() -> Path: + """Execute repo root operation.""" return Path(__file__).resolve().parents[1] @@ -77,6 +82,7 @@ def strip_think_tags(text: str) -> str: def normalize_v1_base(base_url: str) -> str: + """Execute normalize v1 base operation.""" base = base_url.strip().rstrip("/") if not base: raise ValueError("base URL is empty") @@ -86,10 +92,20 @@ def normalize_v1_base(base_url: str) -> str: def parse_csv(value: str) -> list[str]: + """Parse and validate csv. + + Returns: + Parsed result. + """ return [part.strip() for part in value.split(",") if part.strip()] def parse_models(value: str) -> list[str]: + """Parse and validate models. + + Returns: + Parsed result. + """ models = parse_csv(value) if not models: raise ValueError("at least one model is required") @@ -97,6 +113,11 @@ def parse_models(value: str) -> list[str]: def parse_agent_smokes(value: str) -> list[str]: + """Parse and validate agent smokes. + + Returns: + Parsed result. + """ requested = parse_csv(value) unknown = sorted(set(requested) - set(VALID_AGENT_SMOKES)) if unknown: @@ -117,6 +138,11 @@ def build_plan( mesh_binary: str | None, release_attestation_expected_status: str | None, ) -> dict[str, Any]: + """Create plan. + + Returns: + Created object. + """ specs = build_command_specs( base_url=base_url, models=models, @@ -182,6 +208,11 @@ def build_command_specs( skip_streaming: bool, timeout: float, ) -> list[CommandSpec]: + """Create command specs. + + Returns: + Created object. + """ if attempts < 1: raise ValueError("attempts must be at least 1") base = normalize_v1_base(base_url) @@ -279,6 +310,7 @@ def _agent_smoke_spec(smoke: str, base_url: str, output_dir: Path) -> CommandSpe def run_commands(specs: Iterable[CommandSpec], output_dir: Path) -> list[CommandResult]: + """Run commands operation.""" results: list[CommandResult] = [] for spec in specs: result = run_command(spec, output_dir) @@ -292,6 +324,7 @@ def run_commands(specs: Iterable[CommandSpec], output_dir: Path) -> list[Command def run_command(spec: CommandSpec, output_dir: Path) -> CommandResult: + """Run command operation.""" log_path = output_dir / spec.log log_path.parent.mkdir(parents=True, exist_ok=True) if spec.prerequisite and shutil.which(spec.prerequisite) is None: @@ -350,6 +383,7 @@ def run_surface_probes( timeout: float, include_streaming: bool, ) -> list[ProbeResult]: + """Run surface probes operation.""" base = normalize_v1_base(base_url) results: list[ProbeResult] = [] @@ -371,6 +405,7 @@ def run_surface_probes( def run_models_probe(base_url: str, timeout: float) -> ProbeResult: + """Run models probe operation.""" started = time.monotonic() status_code = None try: @@ -384,6 +419,7 @@ def run_models_probe(base_url: str, timeout: float) -> ProbeResult: def run_chat_probe(base_url: str, model: str, attempt: int, timeout: float) -> ProbeResult: + """Run chat probe operation.""" started = time.monotonic() status_code = None actual_model = None @@ -415,6 +451,7 @@ def run_chat_probe(base_url: str, model: str, attempt: int, timeout: float) -> P def run_stream_chat_probe(base_url: str, model: str, attempt: int, timeout: float) -> ProbeResult: + """Run stream chat probe operation.""" started = time.monotonic() status_code = None ttft_ms = None @@ -467,6 +504,11 @@ def run_stream_chat_probe(base_url: str, model: str, attempt: int, timeout: floa def build_chat_request(model: str, attempt: int, stream: bool) -> dict[str, Any]: + """Create chat request. + + Returns: + Created object. + """ sentinel = "STREAM_OK" if stream else "STABILITY_OK" body: dict[str, Any] = { "model": model, @@ -491,6 +533,11 @@ def build_chat_request(model: str, attempt: int, stream: bool) -> dict[str, Any] def get_json(base_url: str, path: str, timeout: float) -> tuple[dict[str, Any], int]: + """Get json. + + Returns: + Retrieved value. + """ request = urllib.request.Request(f"{base_url}{path}", method="GET") try: with urllib.request.urlopen(request, timeout=timeout) as response: @@ -510,6 +557,7 @@ def post_json( payload: dict[str, Any], timeout: float, ) -> tuple[dict[str, Any], int]: + """Execute post json operation.""" data = json.dumps(payload).encode("utf-8") request = urllib.request.Request( f"{base_url}{path}", @@ -535,6 +583,7 @@ def post_json_stream( payload: dict[str, Any], timeout: float, ) -> tuple[list[dict[str, Any]], int, int | None]: + """Execute post json stream operation.""" data = json.dumps(payload).encode("utf-8") request = urllib.request.Request( f"{base_url}{path}", @@ -563,6 +612,7 @@ def post_json_stream( def decode_json_object(body: bytes) -> dict[str, Any]: + """Execute decode json object operation.""" try: decoded = json.loads(body) except json.JSONDecodeError as exc: @@ -574,6 +624,11 @@ def decode_json_object(body: bytes) -> dict[str, Any]: def parse_sse_lines(lines: Iterable[str]) -> Iterable[dict[str, Any]]: + """Parse and validate sse lines. + + Returns: + Parsed result. + """ for raw_line in lines: line = raw_line.strip() if not line or line.startswith(":") or not line.startswith("data:"): @@ -591,6 +646,7 @@ def parse_sse_lines(lines: Iterable[str]) -> Iterable[dict[str, Any]]: def first_message_content(response: dict[str, Any]) -> str: + """Execute first message content operation.""" choices = response.get("choices") if not isinstance(choices, list) or not choices: raise ValueError("response had no choices") @@ -607,6 +663,7 @@ def first_message_content(response: dict[str, Any]) -> str: def stream_content(chunks: Iterable[dict[str, Any]]) -> str: + """Execute stream content operation.""" parts: list[str] = [] saw_choice = False for chunk in chunks: @@ -629,6 +686,11 @@ def stream_content(chunks: Iterable[dict[str, Any]]) -> str: def validate_sentinel(content: str, sentinel: str) -> None: + """Validate sentinel. + + Raises: + ValidationError: If validation fails. + """ cleaned = strip_think_tags(content) if cleaned != sentinel and sentinel not in cleaned: raise ValueError(f"expected exactly {sentinel}, got {content!r}") @@ -667,6 +729,7 @@ def write_evidence( probe_results: list[ProbeResult] | None = None, attestation_result: AttestationResult | None = None, ) -> None: + """Save evidence to destination.""" output_dir.mkdir(parents=True, exist_ok=True) manifest = dict(plan) manifest["created_at"] = datetime.now(timezone.utc).isoformat() @@ -686,6 +749,7 @@ def write_evidence( def summarize_results(results: Iterable[CommandResult]) -> dict[str, Any]: + """Execute summarize results operation.""" rows = list(results) passed = sum(1 for row in rows if row.status == "PASS") failed = sum(1 for row in rows if row.status == "FAIL") @@ -702,6 +766,7 @@ def summarize_results(results: Iterable[CommandResult]) -> dict[str, Any]: def summarize_probe_results(results: Iterable[ProbeResult]) -> dict[str, Any]: + """Execute summarize probe results operation.""" rows = list(results) passed = sum(1 for row in rows if row.ok) failed = sum(1 for row in rows if not row.ok) @@ -717,6 +782,7 @@ def summarize_probe_results(results: Iterable[ProbeResult]) -> dict[str, Any]: def default_attestation_result() -> AttestationResult: + """Execute default attestation result operation.""" return AttestationResult( status="not_configured", ok=True, @@ -726,6 +792,7 @@ def default_attestation_result() -> AttestationResult: def summarize_attestation_result(result: AttestationResult | None) -> dict[str, Any]: + """Execute summarize attestation result operation.""" attestation = result or default_attestation_result() return { "ok": attestation.ok, @@ -743,6 +810,7 @@ def summarize_evidence( probe_results: Iterable[ProbeResult], attestation_result: AttestationResult | None = None, ) -> dict[str, Any]: + """Execute summarize evidence operation.""" commands = summarize_results(command_results) probes = summarize_probe_results(probe_results) attestation = summarize_attestation_result(attestation_result) @@ -768,6 +836,7 @@ def render_summary_markdown( probe_results: Iterable[ProbeResult], attestation_result: AttestationResult | None, ) -> str: + """Render output for summary markdown.""" commands = summary.get("commands", {}) probes = summary.get("probes", {}) attestation = attestation_result or default_attestation_result() @@ -834,6 +903,11 @@ def _summary_timing_row(label: str, summary: dict[str, Any]) -> str: def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser( description=( "Run repeatable mesh-llm stability checks and write manifest.json, " @@ -877,6 +951,7 @@ def inspect_release_attestation( public_key_file: str | None, expected_status: str | None, ) -> AttestationResult: + """Execute inspect release attestation operation.""" if not binary: return default_attestation_result() @@ -932,6 +1007,7 @@ def inspect_release_attestation( def default_base_url() -> str: + """Execute default base url operation.""" for name in ("MESH_STABILITY_BASE_URL", "MESH_AGENT_BASE_URL", "MESH_OPENCODE_BASE_URL"): value = os.environ.get(name) if value: @@ -943,6 +1019,11 @@ def default_base_url() -> str: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ try: args = parse_args() models = parse_models(args.models) @@ -1000,6 +1081,7 @@ def print_human_summary( probe_results: Iterable[ProbeResult], attestation_result: AttestationResult | None, ) -> None: + """Render output for human summary.""" print(f"nightly stability: {summary['passed']}/{summary['total']} steps passed", flush=True) print(f"results: {output_dir}", flush=True) attestation = attestation_result or default_attestation_result() @@ -1028,6 +1110,7 @@ def print_human_summary( def shell_join(command: Iterable[str]) -> str: + """Execute shell join operation.""" return " ".join(_shell_quote(part) for part in command) diff --git a/scripts/run-openai-guardrail-corpus.py b/scripts/run-openai-guardrail-corpus.py index 3212ad156e..56dde86983 100644 --- a/scripts/run-openai-guardrail-corpus.py +++ b/scripts/run-openai-guardrail-corpus.py @@ -27,6 +27,7 @@ @dataclass(frozen=True) class CorpusCase: + """Represents CorpusCase functionality.""" case_id: str category: str prompt: str @@ -66,6 +67,7 @@ class CorpusCase: def expected_server_mode(guardrail_mode: str) -> str: + """Execute expected server mode operation.""" return { "off": "disabled", "metrics": "metrics", @@ -74,6 +76,11 @@ def expected_server_mode(guardrail_mode: str) -> str: def build_corpus() -> list[CorpusCase]: + """Create corpus. + + Returns: + Created object. + """ return [ CorpusCase( case_id="streaming-pass-through", @@ -146,6 +153,7 @@ def build_corpus() -> list[CorpusCase]: def base_request(case: CorpusCase, *, model: str, guardrail_mode: str) -> dict[str, Any]: + """Execute base request operation.""" request = { "model": model, "messages": [{"role": "user", "content": case.prompt}], @@ -157,12 +165,14 @@ def base_request(case: CorpusCase, *, model: str, guardrail_mode: str) -> dict[s def fake_latency_ms(case_id: str, trial_index: int, guardrail_mode: str) -> float: + """Execute fake latency ms operation.""" digest = hashlib.sha256(f"{guardrail_mode}:{case_id}:{trial_index}".encode("utf-8")).digest() sample = int.from_bytes(digest[:2], "big") return 4.0 + (sample % 2400) / 100.0 def runtime_available(base_url: str) -> bool: + """Run runtime available operation.""" if base_url.startswith("fake://"): return False request = urllib.request.Request( @@ -178,6 +188,7 @@ def runtime_available(base_url: str) -> bool: def read_stream_text(response: Any) -> str: + """Execute read stream text operation.""" parts: list[str] = [] while True: line = response.readline() @@ -199,6 +210,7 @@ def read_stream_text(response: Any) -> str: def live_case_result(base_url: str, case: CorpusCase, request_body: dict[str, Any]) -> dict[str, Any]: + """Execute live case result operation.""" payload = json.dumps(request_body).encode("utf-8") url = f"{base_url.rstrip('/')}/chat/completions" req = urllib.request.Request( @@ -258,6 +270,7 @@ def live_case_result(base_url: str, case: CorpusCase, request_body: dict[str, An def fake_case_result(case: CorpusCase, trial_index: int, guardrail_mode: str) -> dict[str, Any]: + """Execute fake case result operation.""" ok = case.expected_outcome != "unsupported_real_tools_plus_strict_structured" latency_ms = fake_latency_ms(case.case_id, trial_index, guardrail_mode) return { @@ -269,11 +282,13 @@ def fake_case_result(case: CorpusCase, trial_index: int, guardrail_mode: str) -> def summarize_latencies(samples: list[float]) -> dict[str, float]: + """Execute summarize latencies operation.""" ordered = sorted(samples) if not ordered: return {"min": 0.0, "mean": 0.0, "p50": 0.0, "p95": 0.0, "max": 0.0} def percentile(index: float) -> float: + """Execute percentile operation.""" if len(ordered) == 1: return ordered[0] position = index * (len(ordered) - 1) @@ -292,6 +307,7 @@ def percentile(index: float) -> float: def run_corpus(base_url: str, model: str, guardrail_mode: str, trials: int) -> dict[str, Any]: + """Run corpus operation.""" corpus = build_corpus() live_mode = runtime_available(base_url) backend_mode = "live" if live_mode else "fake" @@ -366,6 +382,11 @@ def run_corpus(base_url: str, model: str, guardrail_mode: str, trials: int) -> d def main() -> None: + """Execute main program logic. + + Returns: + Exit code. + """ parser = argparse.ArgumentParser() parser.add_argument("--base-url", required=True) parser.add_argument("--model", required=True) diff --git a/scripts/safe-extract-tar.py b/scripts/safe-extract-tar.py old mode 100755 new mode 100644 index 52e38eb3e5..48ebf1658b --- a/scripts/safe-extract-tar.py +++ b/scripts/safe-extract-tar.py @@ -20,6 +20,7 @@ def normalized_parts( label: str, allow_root: bool = False, ) -> tuple[str, ...]: + """Execute normalized parts operation.""" if not raw_name or "\x00" in raw_name or "\\" in raw_name: raise ValueError(f"unsafe {label}: {raw_name!r}") if raw_name.startswith("/") or WINDOWS_DRIVE.match(raw_name): @@ -35,12 +36,18 @@ def normalized_parts( def destination_path(root: Path, parts: tuple[str, ...]) -> Path: + """Execute destination path operation.""" return root.joinpath(*parts) def validate_members( archive: tarfile.TarFile, ) -> list[tuple[tarfile.TarInfo, tuple[str, ...]]]: + """Validate members. + + Raises: + ValidationError: If validation fails. + """ validated: list[tuple[tarfile.TarInfo, tuple[str, ...]]] = [] seen: set[tuple[str, ...]] = set() for member in archive.getmembers(): @@ -91,11 +98,13 @@ def validate_members( def apply_mode(path: Path, member: tarfile.TarInfo) -> None: + """Execute apply mode operation.""" if os.name != "nt": path.chmod(member.mode & 0o777) def safe_extract(archive_path: Path, destination: Path) -> None: + """Execute safe extract operation.""" destination.mkdir(parents=True, exist_ok=True) if destination.is_symlink(): raise ValueError( @@ -171,6 +180,11 @@ def safe_extract(archive_path: Path, destination: Path) -> None: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ parser = argparse.ArgumentParser() parser.add_argument("archive", type=Path) parser.add_argument("destination", type=Path) diff --git a/scripts/safe-extract-zip.py b/scripts/safe-extract-zip.py old mode 100755 new mode 100644 index 1bfcc26c99..060895344f --- a/scripts/safe-extract-zip.py +++ b/scripts/safe-extract-zip.py @@ -18,6 +18,7 @@ @dataclass(frozen=True) class Entry: + """Represents Entry functionality.""" info: zipfile.ZipInfo parts: tuple[str, ...] kind: str @@ -26,10 +27,12 @@ class Entry: def fail(message: str) -> NoReturn: + """Execute fail operation.""" raise SystemExit(f"unsafe ZIP archive: {message}") def portable_parts(name: str, *, label: str) -> tuple[str, ...]: + """Execute portable parts operation.""" if ( not name or any(character in name for character in ("\0", "\r", "\n", "\t")) @@ -50,6 +53,7 @@ def portable_parts(name: str, *, label: str) -> tuple[str, ...]: def resolve_link(parts: tuple[str, ...], target: str) -> None: + """Execute resolve link operation.""" if ( not target or any(character in target for character in ("\0", "\r", "\n", "\t")) @@ -77,6 +81,7 @@ def classify( archive: zipfile.ZipFile, info: zipfile.ZipInfo, ) -> Entry: + """Execute classify operation.""" name = info.filename.rstrip("/") if info.is_dir() else info.filename parts = portable_parts(name, label="entry") mode = info.external_attr >> 16 @@ -97,6 +102,7 @@ def classify( def inspect_archive(archive: zipfile.ZipFile) -> list[Entry]: + """Execute inspect archive operation.""" entries = [classify(archive, info) for info in archive.infolist()] seen: set[tuple[str, ...]] = set() symlinks = {entry.parts for entry in entries if entry.kind == "symlink"} @@ -115,6 +121,7 @@ def inspect_archive(archive: zipfile.ZipFile) -> list[Entry]: def extract(archive_path: Path, destination: Path) -> None: + """Execute extract operation.""" if not archive_path.is_file(): fail(f"archive does not exist: {archive_path}") if destination.is_symlink(): @@ -150,6 +157,11 @@ def extract(archive_path: Path, destination: Path) -> None: def main() -> None: + """Execute main program logic. + + Returns: + Exit code. + """ if len(sys.argv) != 3: raise SystemExit( "usage: scripts/safe-extract-zip.py ARCHIVE.zip DESTINATION" diff --git a/scripts/select-native-runtime.py b/scripts/select-native-runtime.py index d52e899b54..3a466c1ce2 100644 --- a/scripts/select-native-runtime.py +++ b/scripts/select-native-runtime.py @@ -13,6 +13,7 @@ def select_runtime( backend: str, cuda_major: str = "", ) -> Path: + """Execute select runtime operation.""" expected_kind = {"cuda-blackwell": "cuda", "hip": "rocm"}.get(backend, backend) matches = [] if root.is_dir(): @@ -38,6 +39,11 @@ def select_runtime( def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser() parser.add_argument("--root", type=Path, required=True) parser.add_argument("--os", required=True) @@ -48,6 +54,11 @@ def parse_args() -> argparse.Namespace: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args() print(select_runtime(args.root, args.os, args.arch, args.backend, args.cuda_major)) return 0 diff --git a/scripts/select-release-notes-base.py b/scripts/select-release-notes-base.py index 627b470c01..923ea9e2c4 100644 --- a/scripts/select-release-notes-base.py +++ b/scripts/select-release-notes-base.py @@ -18,10 +18,12 @@ def version_from_match(match: re.Match[str]) -> tuple[int, int, int]: + """Execute version from match operation.""" return tuple(int(match.group(name)) for name in ("major", "minor", "patch")) def select_release_notes_base(target: str, tags: Iterable[str]) -> str | None: + """Execute select release notes base operation.""" target_match = TARGET_TAG.fullmatch(target.strip()) if target_match is None: raise ValueError(f"invalid release tag: {target}") @@ -43,6 +45,11 @@ def select_release_notes_base(target: str, tags: Iterable[str]) -> str | None: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ if len(sys.argv) != 2: print( "usage: select-release-notes-base.py ", diff --git a/scripts/skippy-llama-parity.py b/scripts/skippy-llama-parity.py old mode 100755 new mode 100644 index d319a8f9ca..3679681cd7 --- a/scripts/skippy-llama-parity.py +++ b/scripts/skippy-llama-parity.py @@ -30,6 +30,7 @@ def repo_cache_dir(repo: str) -> Path: + """Execute repo cache dir operation.""" cache_root = os.environ.get("HF_HUB_CACHE") if cache_root: hub = Path(cache_root) @@ -41,11 +42,17 @@ def repo_cache_dir(repo: str) -> Path: def load_json(path: Path) -> dict[str, Any]: + """Load json from source. + + Returns: + Loaded data. + """ with path.open("r", encoding="utf-8") as handle: return json.load(handle) def run(args: list[str], *, cwd: Path | None = None, quiet: bool = False) -> str: + """Run run operation.""" proc = subprocess.run( args, cwd=str(cwd) if cwd else None, @@ -64,6 +71,7 @@ def run(args: list[str], *, cwd: Path | None = None, quiet: bool = False) -> str def pinned_llama_models(llama_src: Path | None) -> list[str]: + """Execute pinned llama models operation.""" if llama_src: models_dir = llama_src / "src/models" if not models_dir.is_dir(): @@ -102,6 +110,7 @@ def pinned_llama_models(llama_src: Path | None) -> list[str]: def candidate_index(manifest: dict[str, Any]) -> dict[str, list[dict[str, Any]]]: + """Execute candidate index operation.""" index: dict[str, list[dict[str, Any]]] = {} for candidate in manifest.get("candidates", []): index.setdefault(candidate["llama_model"], []).append(candidate) @@ -109,6 +118,7 @@ def candidate_index(manifest: dict[str, Any]) -> dict[str, list[dict[str, Any]]] def priority_lookup(manifest: dict[str, Any]) -> dict[tuple[str, str], str]: + """Execute priority lookup operation.""" priorities = manifest.get("support_priority", {}) lookup: dict[tuple[str, str], str] = {} for priority in ("p0", "p1", "p2"): @@ -121,6 +131,7 @@ def priority_lookup(manifest: dict[str, Any]) -> dict[tuple[str, str], str]: def row_priority(row: dict[str, Any], lookup: dict[tuple[str, str], str]) -> str: + """Execute row priority operation.""" return ( lookup.get(("family", str(row.get("family", "")))) or lookup.get(("llama_model", str(row.get("llama_model", "")))) @@ -132,6 +143,7 @@ def filter_priority( rows: list[dict[str, Any]], priorities: list[str] | None, ) -> list[dict[str, Any]]: + """Execute filter priority operation.""" if not priorities: return rows requested = {priority.lower() for priority in priorities} @@ -139,6 +151,7 @@ def filter_priority( def candidate_file_rank(path: Path) -> int: + """Execute candidate file rank operation.""" name = path.name.lower() if "mmproj" in name: return 3 @@ -149,6 +162,7 @@ def candidate_file_rank(path: Path) -> int: def resolve_candidate_file(candidate: dict[str, Any]) -> Path | None: + """Execute resolve candidate file operation.""" repo = candidate.get("repo") include = candidate.get("include", "*.gguf") if not repo: @@ -172,6 +186,7 @@ def resolve_candidate_file(candidate: dict[str, Any]) -> Path | None: def download_command(candidate: dict[str, Any]) -> str: + """Execute download command operation.""" repo = candidate.get("repo") include = candidate.get("include", "*.gguf") if not repo: @@ -184,41 +199,52 @@ def download_command(candidate: dict[str, Any]) -> str: class GgufReader: + """Represents GgufReader functionality.""" def __init__(self, path: Path): self.handle = path.open("rb") def close(self) -> None: + """Execute close operation.""" self.handle.close() def read(self, size: int) -> bytes: + """Execute read operation.""" data = self.handle.read(size) if len(data) != size: raise EOFError("short GGUF read") return data def u32(self) -> int: + """Execute u32 operation.""" return struct.unpack(" int: + """Execute u64 operation.""" return struct.unpack(" int: + """Execute i32 operation.""" return struct.unpack(" int: + """Execute i64 operation.""" return struct.unpack(" float: + """Execute f32 operation.""" return struct.unpack(" float: + """Execute f64 operation.""" return struct.unpack(" str: + """Execute string operation.""" length = self.u64() return self.read(length).decode("utf-8", errors="replace") def value(self, typ: int) -> Any: + """Execute value operation.""" if typ == 0: return self.read(1)[0] if typ == 1: @@ -251,6 +277,7 @@ def value(self, typ: int) -> Any: def gguf_metadata(path: Path) -> dict[str, Any]: + """Execute gguf metadata operation.""" reader = GgufReader(path) try: if reader.read(4) != b"GGUF": @@ -272,6 +299,7 @@ def gguf_metadata(path: Path) -> dict[str, Any]: def infer_model_shape(path: Path) -> tuple[int, int, str | None]: + """Execute infer model shape operation.""" metadata = gguf_metadata(path) arch = metadata.get("general.architecture") layer_count = None @@ -289,6 +317,7 @@ def infer_model_shape(path: Path) -> tuple[int, int, str | None]: def split_args(layer_count: int) -> tuple[int, str]: + """Execute split args operation.""" first = max(1, layer_count // 3) second = max(first + 1, (2 * layer_count) // 3) if second >= layer_count: @@ -300,6 +329,7 @@ def split_args(layer_count: int) -> tuple[int, str]: def default_stage_build_dir() -> str | None: + """Execute default stage build dir operation.""" if os.environ.get("LLAMA_STAGE_BUILD_DIR"): return os.environ["LLAMA_STAGE_BUILD_DIR"] llama_build_roots = ( @@ -321,6 +351,7 @@ def default_stage_build_dir() -> str | None: def inventory(args: argparse.Namespace) -> list[dict[str, Any]]: + """Execute inventory operation.""" manifest = load_json(args.manifest) candidates = candidate_index(manifest) priorities = priority_lookup(manifest) @@ -377,6 +408,7 @@ def inventory(args: argparse.Namespace) -> list[dict[str, Any]]: def print_table(rows: list[dict[str, Any]]) -> None: + """Render output for table.""" print("| priority | llama model | family | status | local | candidate/download |") print("| --- | --- | --- | --- | --- | --- |") for row in rows: @@ -390,6 +422,11 @@ def print_table(rows: list[dict[str, Any]]) -> None: def validate_inventory(rows: list[dict[str, Any]]) -> int: + """Validate inventory. + + Raises: + ValidationError: If validation fails. + """ failures = 0 missing = [row for row in rows if row.get("status") == "missing_candidate"] if missing: @@ -432,6 +469,11 @@ def validate_inventory(rows: list[dict[str, Any]]) -> int: def validate_stage_abi_allowlist() -> int: + """Validate stage abi allowlist. + + Raises: + ValidationError: If validation fails. + """ llama_src = ROOT / ".deps/llama.cpp/src" skippy_cpp = llama_src / "skippy.cpp" arch_cpp = llama_src / "llama-arch.cpp" @@ -440,6 +482,7 @@ def validate_stage_abi_allowlist() -> int: return 0 def normalized(name: str) -> str: + """Execute normalized operation.""" return name.replace("_", "").replace("-", "") arch_names: dict[str, str] = {} @@ -510,6 +553,7 @@ def normalized(name: str) -> str: def run_certifications(args: argparse.Namespace, rows: list[dict[str, Any]]) -> int: + """Run certifications operation.""" defaults = load_json(args.manifest).get("defaults", {}) statuses = set(args.status) if args.status else { "candidate", @@ -627,6 +671,11 @@ def run_certifications(args: argparse.Namespace, rows: list[dict[str, Any]]) -> def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST) parser.add_argument("--llama-src", type=Path) diff --git a/scripts/summarize-depot-registry-pulls.py b/scripts/summarize-depot-registry-pulls.py index c3e366a1f4..3fe8756fee 100644 --- a/scripts/summarize-depot-registry-pulls.py +++ b/scripts/summarize-depot-registry-pulls.py @@ -13,6 +13,11 @@ def load_observations(root: Path) -> list[dict[str, object]]: + """Load observations from source. + + Returns: + Loaded data. + """ observations: list[dict[str, object]] = [] for path in sorted(root.rglob("*.json")): with path.open(encoding="utf-8") as handle: @@ -33,6 +38,7 @@ def load_observations(root: Path) -> list[dict[str, object]]: def summarize( observations: list[dict[str, object]], minimum_samples: int ) -> dict[str, object]: + """Execute summarize operation.""" by_source = { source: [item for item in observations if item["source"] == source] for source in SOURCES @@ -71,6 +77,7 @@ def summarize( def markdown(summary: dict[str, object]) -> str: + """Execute markdown operation.""" return "\n".join( ( "## Depot Registry pull-through result", @@ -93,6 +100,11 @@ def markdown(summary: dict[str, object]) -> str: def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser() parser.add_argument("observations", type=Path) parser.add_argument("--minimum-samples", type=int, default=5) @@ -103,6 +115,11 @@ def parse_args() -> argparse.Namespace: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args() result = summarize(load_observations(args.observations), args.minimum_samples) report = markdown(result) diff --git a/scripts/summarize-sccache-stats.py b/scripts/summarize-sccache-stats.py index bede58d7b5..1498d14048 100644 --- a/scripts/summarize-sccache-stats.py +++ b/scripts/summarize-sccache-stats.py @@ -15,6 +15,7 @@ class SummaryError(RuntimeError): def hit_rate(value: str) -> float: + """Execute hit rate operation.""" try: parsed = float(value) except ValueError as error: @@ -29,6 +30,11 @@ def hit_rate(value: str) -> float: def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser( description=( "Aggregate cache hits and misses from downloaded " @@ -56,6 +62,7 @@ def parse_args() -> argparse.Namespace: def discover_evidence(paths: list[Path]) -> list[Path]: + """Execute discover evidence operation.""" evidence: set[Path] = set() for path in paths: if path.is_file(): @@ -74,6 +81,7 @@ def discover_evidence(paths: list[Path]) -> list[Path]: def sum_count_tree(value: Any, field: str) -> int: + """Execute sum count tree operation.""" if isinstance(value, bool): raise SummaryError(f"{field} contains a boolean") if isinstance(value, int): @@ -89,6 +97,7 @@ def sum_count_tree(value: Any, field: str) -> int: def read_count(path: Path, payload: Any, name: str) -> int: + """Execute read count operation.""" if not isinstance(payload, dict): raise SummaryError(f"{path}: JSON root must be an object") stats = payload.get("stats") @@ -104,6 +113,7 @@ def read_count(path: Path, payload: Any, name: str) -> int: def aggregate(paths: list[Path]) -> tuple[int, int]: + """Execute aggregate operation.""" hits = 0 misses = 0 for path in paths: @@ -117,6 +127,7 @@ def aggregate(paths: list[Path]) -> tuple[int, int]: def render_text(summary: dict[str, Any]) -> str: + """Render output for text.""" rate = summary["hit_rate"] rate_text = "n/a" if rate is None else f"{rate:.2%}" lines = [ @@ -134,6 +145,11 @@ def render_text(summary: dict[str, Any]) -> str: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ arguments = parse_args() try: evidence = discover_evidence(arguments.paths) diff --git a/scripts/validate-ci-lane-results.py b/scripts/validate-ci-lane-results.py index 9c629288c5..b770f376eb 100644 --- a/scripts/validate-ci-lane-results.py +++ b/scripts/validate-ci-lane-results.py @@ -105,6 +105,15 @@ def _required_jobs(lane_plan: dict[str, Any]) -> set[str]: def validate(lane_plan: dict[str, Any], needs: dict[str, Any]) -> None: + """Validate that all planned jobs completed successfully and unplanned jobs were skipped. + + Args: + lane_plan: The CI lane plan containing required jobs and slices. + needs: The actual job results from the CI workflow. + + Raises: + LaneResultError: If validation fails due to job failures or unexpected results. + """ required = lane_plan.get("required") if not isinstance(required, bool): raise LaneResultError("lane plan required must be a boolean") @@ -127,6 +136,11 @@ def validate(lane_plan: dict[str, Any], needs: dict[str, Any]) -> None: def main() -> int: + """Parse arguments and validate CI lane results against the plan. + + Returns: + Exit code: 0 for success, 2 for validation errors. + """ parser = argparse.ArgumentParser() parser.add_argument("--lane-plan", required=True) parser.add_argument("--needs", required=True) diff --git a/scripts/validate-release-native-runtime-matrix.py b/scripts/validate-release-native-runtime-matrix.py old mode 100755 new mode 100644 index 2050b3e6d4..11e7515188 --- a/scripts/validate-release-native-runtime-matrix.py +++ b/scripts/validate-release-native-runtime-matrix.py @@ -23,24 +23,28 @@ @dataclass(frozen=True, order=True) class RuntimeTarget: + """Represents RuntimeTarget functionality.""" os: str arch: str backend: str cuda_major: int | None = None def label(self) -> str: + """Execute label operation.""" if self.backend == "cuda" and self.cuda_major is not None: return f"{self.os}/{self.arch}/cuda{self.cuda_major}" return f"{self.os}/{self.arch}/{self.backend}" def default_backend(os_name: str, arch: str) -> str: + """Execute default backend operation.""" if os_name == "macos" and arch == "aarch64": return "metal" return "cpu" def binary_target_from_asset(asset_name: str) -> RuntimeTarget | None: + """Execute binary target from asset operation.""" name = os.path.basename(asset_name) if not name.startswith("mesh-llm-"): return None @@ -60,6 +64,7 @@ def binary_target_from_asset(asset_name: str) -> RuntimeTarget | None: def target_from_suffix(os_name: str, arch: str, suffix: str) -> RuntimeTarget: + """Execute target from suffix operation.""" if suffix == "": return RuntimeTarget(os_name, arch, default_backend(os_name, arch)) if suffix.startswith("-cuda"): @@ -72,6 +77,7 @@ def target_from_suffix(os_name: str, arch: str, suffix: str) -> RuntimeTarget: def native_target_from_artifact(artifact: dict[str, Any]) -> RuntimeTarget | None: + """Execute native target from artifact operation.""" platform = artifact.get("platform") backend = artifact.get("backend") if not isinstance(platform, dict) or not isinstance(backend, dict): @@ -90,6 +96,7 @@ def native_target_from_artifact(artifact: dict[str, Any]) -> RuntimeTarget | Non def native_target_matches(required: RuntimeTarget, candidate: RuntimeTarget) -> bool: + """Execute native target matches operation.""" if (required.os, required.arch, required.backend) != ( candidate.os, candidate.arch, @@ -102,6 +109,7 @@ def native_target_matches(required: RuntimeTarget, candidate: RuntimeTarget) -> def target_from_label(label: str) -> RuntimeTarget: + """Execute target from label operation.""" parts = label.split("/") if len(parts) != 3: raise ValueError(f"expected target label as os/arch/backend, got {label!r}") @@ -113,6 +121,7 @@ def target_from_label(label: str) -> RuntimeTarget: def required_targets_from_assets(asset_names: list[str]) -> set[RuntimeTarget]: + """Execute required targets from assets operation.""" return { target for asset_name in asset_names @@ -125,6 +134,7 @@ def find_matrix_violations( manifest: dict[str, Any], required_targets: set[RuntimeTarget] | None = None, ) -> list[str]: + """Execute find matrix violations operation.""" if required_targets is None: required_targets = required_targets_from_assets(asset_names) native_targets = [ @@ -143,6 +153,11 @@ def find_matrix_violations( def parse_args(argv: list[str]) -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser( description="Validate release binary bundle targets against native-runtimes.json." ) @@ -162,6 +177,11 @@ def parse_args(argv: list[str]) -> argparse.Namespace: def main(argv: list[str]) -> int: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args(argv) if not args.required_target and not args.assets: print( diff --git a/scripts/verify-checksum-sidecar.py b/scripts/verify-checksum-sidecar.py old mode 100755 new mode 100644 index d304b9764f..1f28627f39 --- a/scripts/verify-checksum-sidecar.py +++ b/scripts/verify-checksum-sidecar.py @@ -15,6 +15,7 @@ def sha256_file(path: Path) -> str: + """Execute sha256 file operation.""" digest = hashlib.sha256() with path.open("rb") as handle: for chunk in iter(lambda: handle.read(1024 * 1024), b""): @@ -23,6 +24,7 @@ def sha256_file(path: Path) -> str: def verify(artifact: Path) -> None: + """Execute verify operation.""" sidecar = artifact.with_name(f"{artifact.name}.sha256") if not sidecar.is_file() or sidecar.stat().st_size == 0: raise ValueError( @@ -54,6 +56,11 @@ def verify(artifact: Path) -> None: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ parser = argparse.ArgumentParser() parser.add_argument("artifact", type=Path) args = parser.parse_args() diff --git a/scripts/verify-host-dependencies.py b/scripts/verify-host-dependencies.py index 9ee226059e..0f28cb9072 100644 --- a/scripts/verify-host-dependencies.py +++ b/scripts/verify-host-dependencies.py @@ -36,6 +36,7 @@ def binary_format(path: Path) -> str: + """Execute binary format operation.""" header = path.read_bytes()[:4] if header == b"\x7fELF": return "elf" @@ -54,10 +55,20 @@ def binary_format(path: Path) -> str: def parse_elf_imports(output: str) -> list[str]: + """Parse and validate elf imports. + + Returns: + Parsed result. + """ return sorted(set(re.findall(r"\(NEEDED\).*\[([^\]]+)\]", output))) def parse_macho_imports(output: str) -> list[str]: + """Parse and validate macho imports. + + Returns: + Parsed result. + """ imports = [] for line in output.splitlines(): if not line[:1].isspace(): @@ -69,6 +80,11 @@ def parse_macho_imports(output: str) -> list[str]: def parse_pe_imports(output: str) -> list[str]: + """Parse and validate pe imports. + + Returns: + Parsed result. + """ imports = [] for line in output.splitlines(): match = re.search(r"(?:DLL Name:|Name:)\s*(\S+\.dll)\b", line, re.IGNORECASE) @@ -78,6 +94,7 @@ def parse_pe_imports(output: str) -> list[str]: def inspect_dependencies(path: Path, format_name: str | None = None) -> tuple[str, list[str]]: + """Execute inspect dependencies operation.""" format_name = format_name or binary_format(path) if format_name == "elf": output = run_tool(("readelf", "-d", str(path))) @@ -97,12 +114,14 @@ def inspect_dependencies(path: Path, format_name: str | None = None) -> tuple[st def run_tool(command: tuple[str, ...]) -> str: + """Run tool operation.""" if shutil.which(command[0]) is None: raise RuntimeError(f"{command[0]} is required to inspect host dependencies") return subprocess.check_output(command, text=True, stderr=subprocess.STDOUT) def forbidden_imports(imports: list[str]) -> list[str]: + """Execute forbidden imports operation.""" return [ dependency for dependency in imports @@ -111,6 +130,11 @@ def forbidden_imports(imports: list[str]) -> list[str]: def parse_args(argv: list[str]) -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser() parser.add_argument("binary", type=Path) parser.add_argument("--format", choices=("elf", "macho", "pe")) @@ -119,6 +143,11 @@ def parse_args(argv: list[str]) -> argparse.Namespace: def main(argv: list[str]) -> int: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args(argv) try: format_name, imports = inspect_dependencies(args.binary, args.format) diff --git a/scripts/verify-static-abi-build-stamp.py b/scripts/verify-static-abi-build-stamp.py index 0b981380f9..03e7c30cb4 100644 --- a/scripts/verify-static-abi-build-stamp.py +++ b/scripts/verify-static-abi-build-stamp.py @@ -23,6 +23,11 @@ class StampError(RuntimeError): def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser() parser.add_argument("stamp", type=Path) parser.add_argument("--backend", required=True) @@ -34,6 +39,11 @@ def parse_args() -> argparse.Namespace: def parse_stamp(path: Path) -> tuple[dict[str, str], list[str]]: + """Parse and validate stamp. + + Returns: + Parsed result. + """ try: lines = path.read_text(encoding="utf-8").splitlines() except (OSError, UnicodeError) as error: @@ -68,6 +78,7 @@ def parse_stamp(path: Path) -> tuple[dict[str, str], list[str]]: def require_equal(fields: dict[str, str], name: str, expected: str) -> None: + """Execute require equal operation.""" actual = fields.get(name) if actual != expected: raise StampError( @@ -77,6 +88,11 @@ def require_equal(fields: dict[str, str], name: str, expected: str) -> None: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ arguments = parse_args() try: fields, cmake_arguments = parse_stamp(arguments.stamp) diff --git a/scripts/verify-swift-xcframework.py b/scripts/verify-swift-xcframework.py old mode 100755 new mode 100644 index 679cac6bf5..2e0c3aba72 --- a/scripts/verify-swift-xcframework.py +++ b/scripts/verify-swift-xcframework.py @@ -28,6 +28,11 @@ def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser( description=( "Verify an XCFramework's declared architectures, binary slices, " @@ -40,10 +45,12 @@ def parse_args() -> argparse.Namespace: def fail(message: str) -> None: + """Execute fail operation.""" raise ValueError(message) def require_safe_component(value: Any, field: str) -> str: + """Execute require safe component operation.""" if not isinstance(value, str) or not value: fail(f"XCFramework {field} must be a non-empty string") path = PurePosixPath(value) @@ -53,6 +60,7 @@ def require_safe_component(value: Any, field: str) -> str: def platform_key(library: dict[str, Any]) -> PlatformKey: + """Execute platform key operation.""" platform = library.get("SupportedPlatform") variant = library.get("SupportedPlatformVariant", "") if not isinstance(platform, str) or not platform: @@ -66,6 +74,7 @@ def declared_architectures( library: dict[str, Any], key: PlatformKey, ) -> frozenset[str]: + """Execute declared architectures operation.""" architectures = library.get("SupportedArchitectures") if not isinstance(architectures, list) or not architectures: fail(f"XCFramework slice {key!r} must declare SupportedArchitectures") @@ -84,6 +93,7 @@ def framework_path( xcframework: Path, library: dict[str, Any], ) -> Path: + """Execute framework path operation.""" identifier = require_safe_component( library.get("LibraryIdentifier"), "LibraryIdentifier", @@ -102,6 +112,7 @@ def framework_path( def framework_binary(framework: Path) -> Path: + """Execute framework binary operation.""" name = framework.stem binary = framework / name if not binary.exists() or not binary.is_file(): @@ -110,6 +121,7 @@ def framework_binary(framework: Path) -> Path: def verify_macos_layout(framework: Path) -> None: + """Execute verify macos layout operation.""" name = framework.stem expected_symlinks = { "Versions/Current": "A", @@ -139,6 +151,7 @@ def verify_macos_layout(framework: Path) -> None: def lipo_architectures(binary: Path) -> frozenset[str]: + """Execute lipo architectures operation.""" lipo = os.environ.get("LIPO", "lipo") try: result = subprocess.run( @@ -156,6 +169,7 @@ def lipo_architectures(binary: Path) -> frozenset[str]: def verify_xcframework(xcframework: Path, mode: str | None) -> None: + """Execute verify xcframework operation.""" info_path = xcframework / "Info.plist" if not xcframework.is_dir() or not info_path.is_file(): fail(f"XCFramework or Info.plist is missing: {xcframework}") @@ -210,6 +224,11 @@ def verify_xcframework(xcframework: Path, mode: str | None) -> None: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args() try: verify_xcframework(args.xcframework, args.mode) diff --git a/scripts/windows-native-runtime-deps.py b/scripts/windows-native-runtime-deps.py index c33339aba6..2d8e43f2ec 100644 --- a/scripts/windows-native-runtime-deps.py +++ b/scripts/windows-native-runtime-deps.py @@ -71,6 +71,7 @@ def _cstring(data: bytes, offset: int) -> str: def imported_dlls(path: pathlib.Path) -> list[str]: + """Execute imported dlls operation.""" data = path.read_bytes() if data[:2] != b"MZ": raise PeFormatError(f"not a PE image: {path}") @@ -102,6 +103,7 @@ def imported_dlls(path: pathlib.Path) -> list[str]: sections.append((virtual_address, max(virtual_size, raw_size), raw_offset)) def rva_offset(rva: int) -> int: + """Execute rva offset operation.""" for virtual_address, size, raw_offset in sections: if virtual_address <= rva < virtual_address + size: return raw_offset + rva - virtual_address @@ -126,6 +128,11 @@ def rva_offset(rva: int) -> int: def is_host_dll(name: str) -> bool: + """Check if host dll. + + Returns: + True if condition is met. + """ normalized = name.casefold() return ( normalized in HOST_DLLS @@ -135,6 +142,7 @@ def is_host_dll(name: str) -> bool: def default_search_dirs() -> list[pathlib.Path]: + """Execute default search dirs operation.""" candidates: list[pathlib.Path] = [] for compiler in ("g++", "gcc"): compiler_path = shutil.which(compiler) @@ -180,6 +188,7 @@ def _packaged_dlls(lib_dir: pathlib.Path) -> dict[str, pathlib.Path]: def dependency_gaps( lib_dir: pathlib.Path, scan_dirs: list[pathlib.Path] | None = None ) -> dict[str, set[str]]: + """Execute dependency gaps operation.""" packaged = _packaged_dlls(lib_dir) gaps: dict[str, set[str]] = {} scan_dirs = scan_dirs or [lib_dir] @@ -204,6 +213,7 @@ def dependency_gaps( def collect_dependencies( lib_dir: pathlib.Path, search_dirs: list[pathlib.Path], scan_dirs: list[pathlib.Path] | None = None ) -> list[pathlib.Path]: + """Execute collect dependencies operation.""" search_index = _dll_index([lib_dir, *search_dirs, *default_search_dirs()]) copied: list[pathlib.Path] = [] while True: @@ -230,6 +240,7 @@ def collect_dependencies( def verify_dependencies(lib_dir: pathlib.Path, scan_dirs: list[pathlib.Path] | None = None) -> None: + """Execute verify dependencies operation.""" gaps = dependency_gaps(lib_dir, scan_dirs) if not gaps: return @@ -241,6 +252,11 @@ def verify_dependencies(lib_dir: pathlib.Path, scan_dirs: list[pathlib.Path] | N def parse_args() -> argparse.Namespace: + """Parse and validate args. + + Returns: + Parsed result. + """ parser = argparse.ArgumentParser(description=__doc__) subparsers = parser.add_subparsers(dest="command", required=True) collect = subparsers.add_parser("collect") @@ -254,6 +270,11 @@ def parse_args() -> argparse.Namespace: def main() -> int: + """Execute main program logic. + + Returns: + Exit code. + """ args = parse_args() try: if args.command == "collect": From 6abb26e75491bdd627ced57481d4edc3dfc6caec Mon Sep 17 00:00:00 2001 From: James Dumay Date: Wed, 26 Aug 2026 13:58:09 +1000 Subject: [PATCH 3/4] Revert "fix: apply CodeRabbit auto-fixes" This reverts commit 3facd3085ddbc01b797f084dcf55ab591b3830a6. --- scripts/check-env-mutation-contract.py | 22 --- scripts/ci-client-readiness-process.py | 9 - scripts/ci-langchain-openai-smoke.py | 12 -- scripts/ci-litellm-smoke.py | 12 -- scripts/ci-openai-python-smoke.py | 9 - scripts/collect-ci-metrics.py | 48 ----- scripts/compose-product-bundle.py | 23 --- scripts/generate-bench-corpus.py | 42 ----- scripts/generate-skippy-api-doc.py | 19 -- scripts/hf-skippy-convert-job.py | 26 --- scripts/hf-skippy-mtp-certify-job.py | 30 --- scripts/manage-build-cache.py | 177 ------------------ scripts/plan-ci.py | 12 -- scripts/qa-agent-tool-call-reliability.py | 74 -------- scripts/qa-kv-tool-loop-stability.py | 119 ------------ scripts/qa-nightly-stability.py | 83 -------- scripts/run-openai-guardrail-corpus.py | 21 --- scripts/safe-extract-tar.py | 14 -- scripts/safe-extract-zip.py | 12 -- scripts/select-native-runtime.py | 11 -- scripts/select-release-notes-base.py | 7 - scripts/skippy-llama-parity.py | 49 ----- scripts/summarize-depot-registry-pulls.py | 17 -- scripts/summarize-sccache-stats.py | 16 -- scripts/validate-ci-lane-results.py | 14 -- .../validate-release-native-runtime-matrix.py | 20 -- scripts/verify-checksum-sidecar.py | 7 - scripts/verify-host-dependencies.py | 29 --- scripts/verify-static-abi-build-stamp.py | 16 -- scripts/verify-swift-xcframework.py | 19 -- scripts/windows-native-runtime-deps.py | 21 --- 31 files changed, 990 deletions(-) mode change 100644 => 100755 scripts/ci-openai-python-smoke.py mode change 100644 => 100755 scripts/collect-ci-metrics.py mode change 100644 => 100755 scripts/generate-bench-corpus.py mode change 100644 => 100755 scripts/manage-build-cache.py mode change 100644 => 100755 scripts/qa-agent-tool-call-reliability.py mode change 100644 => 100755 scripts/qa-kv-tool-loop-stability.py mode change 100644 => 100755 scripts/qa-nightly-stability.py mode change 100644 => 100755 scripts/safe-extract-tar.py mode change 100644 => 100755 scripts/safe-extract-zip.py mode change 100644 => 100755 scripts/skippy-llama-parity.py mode change 100644 => 100755 scripts/validate-release-native-runtime-matrix.py mode change 100644 => 100755 scripts/verify-checksum-sidecar.py mode change 100644 => 100755 scripts/verify-swift-xcframework.py diff --git a/scripts/check-env-mutation-contract.py b/scripts/check-env-mutation-contract.py index 91a588261a..101e297b5a 100644 --- a/scripts/check-env-mutation-contract.py +++ b/scripts/check-env-mutation-contract.py @@ -120,8 +120,6 @@ def mutation_lines(lines: list[str]) -> list[int]: def nearest_function(lines: list[str], line_index: int) -> tuple[int, str] | None: - """Execute nearest_function operation.""" - for index in range(line_index, -1, -1): match = FUNCTION_RE.search(lines[index]) if match: @@ -168,14 +166,7 @@ def test_contract( return function_name in helpers and "serial" in nearby - """Execute check_file operation.""" - def check_file(root: Path, relative_path: str) -> list[str]: - """Validate file. - - Raises: - ValidationError: If validation fails. - """ path = root / relative_path if not path.is_file(): return [f"{relative_path}: audited source file is missing"] @@ -244,11 +235,8 @@ def check_file(root: Path, relative_path: str) -> list[str]: ) return errors - """Execute discover_mutation_files operation.""" - def discover_mutation_files(root: Path) -> dict[str, int]: - """Execute discover mutation files operation.""" discovered: dict[str, int] = {} for path in root.rglob("*.rs"): if any(part in {".git", "target"} for part in path.relative_to(root).parts): @@ -257,12 +245,9 @@ def discover_mutation_files(root: Path) -> dict[str, int]: if count: discovered[path.relative_to(root).as_posix()] = count return discovered - """Execute run operation.""" - def run(root: Path, files: tuple[str, ...] | None = None) -> int: - """Run run operation.""" errors: list[str] = [] if files is not None: mutation_count = 0 @@ -306,17 +291,10 @@ def run(root: Path, files: tuple[str, ...] | None = None) -> int: f"{mutation_count} mutation sites; {audited_file_count} contract-audited files; " "unresolved runtime sites remain explicit" ) - """Execute parse_args operation.""" - return 0 def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( "--root", diff --git a/scripts/ci-client-readiness-process.py b/scripts/ci-client-readiness-process.py index 435ffd1c8c..8a0c006bca 100644 --- a/scripts/ci-client-readiness-process.py +++ b/scripts/ci-client-readiness-process.py @@ -12,15 +12,12 @@ def creationflags_for_platform(is_windows: bool) -> int: - """Execute creationflags_for_platform operation.""" - if not is_windows: return 0 return getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0) def command_for_platform(command: Sequence[str], *, is_windows: bool) -> list[str]: - """Execute command_for_platform operation.""" prepared = list(command) if prepared[:1] == ["--"]: prepared = prepared[1:] @@ -37,7 +34,6 @@ def command_for_platform(command: Sequence[str], *, is_windows: bool) -> list[st def launch( command: Sequence[str], pid_file: Path, log_file: Path, *, is_windows: bool ) -> int: - """Execute launch operation.""" with log_file.open("ab", buffering=0) as log_handle: process = subprocess.Popen( command_for_platform(command, is_windows=is_windows), @@ -50,7 +46,6 @@ def launch( def request_ctrl_break(pid: int) -> None: - """Execute request_ctrl_break operation.""" ctrl_break = getattr(signal, "CTRL_BREAK_EVENT", None) if ctrl_break is None: raise RuntimeError("CTRL_BREAK_EVENT is only available on Windows") @@ -58,7 +53,6 @@ def request_ctrl_break(pid: int) -> None: def is_running(pid: int, *, is_windows: bool) -> bool: - """Execute is_running operation.""" try: os.kill(pid, 0) except ProcessLookupError: @@ -75,7 +69,6 @@ def is_running(pid: int, *, is_windows: bool) -> bool: def force_stop(pid: int) -> None: - """Execute force_stop operation.""" subprocess.run( ["taskkill.exe", "/PID", str(pid), "/T", "/F"], check=False, @@ -85,7 +78,6 @@ def force_stop(pid: int) -> None: def parse_args() -> argparse.Namespace: - """Execute parse_args operation.""" parser = argparse.ArgumentParser() subcommands = parser.add_subparsers(dest="command", required=True) @@ -102,7 +94,6 @@ def parse_args() -> argparse.Namespace: def main() -> int: - """Execute main operation.""" args = parse_args() if args.command == "run": if not args.program or args.program == ["--"]: diff --git a/scripts/ci-langchain-openai-smoke.py b/scripts/ci-langchain-openai-smoke.py index 5c61446c7a..ea18ca6d42 100644 --- a/scripts/ci-langchain-openai-smoke.py +++ b/scripts/ci-langchain-openai-smoke.py @@ -8,8 +8,6 @@ def content_text(content: Any) -> str: - """Execute content_text operation.""" - if isinstance(content, str): return content if isinstance(content, list): @@ -25,10 +23,7 @@ def content_text(content: Any) -> str: return "" - """Execute streamed_text operation.""" - def streamed_text(chunks: Iterable[object]) -> str: - """Execute streamed text operation.""" parts: list[str] = [] saw_chunk = False for chunk in chunks: @@ -43,15 +38,8 @@ def streamed_text(chunks: Iterable[object]) -> str: raise RuntimeError("stream returned no content") return text - """Execute main operation.""" - def main() -> None: - """Execute main program logic. - - Returns: - Exit code. - """ parser = argparse.ArgumentParser() parser.add_argument("--base-url", required=True) parser.add_argument("--model", required=True) diff --git a/scripts/ci-litellm-smoke.py b/scripts/ci-litellm-smoke.py index 22f5e2f4a5..0ae652291f 100644 --- a/scripts/ci-litellm-smoke.py +++ b/scripts/ci-litellm-smoke.py @@ -8,17 +8,12 @@ def get_field(value: Any, name: str) -> Any: - """Execute get_field operation.""" - if isinstance(value, dict): return value.get(name) return getattr(value, name, None) - """Execute streamed_text operation.""" - def streamed_text(chunks: Iterable[object]) -> str: - """Execute streamed text operation.""" parts: list[str] = [] saw_choice = False for chunk in chunks: @@ -38,15 +33,8 @@ def streamed_text(chunks: Iterable[object]) -> str: raise RuntimeError("stream returned no content") return text - """Execute main operation.""" - def main() -> None: - """Execute main program logic. - - Returns: - Exit code. - """ parser = argparse.ArgumentParser() parser.add_argument("--base-url", required=True) parser.add_argument("--model", required=True) diff --git a/scripts/ci-openai-python-smoke.py b/scripts/ci-openai-python-smoke.py old mode 100644 new mode 100755 index 4b4d2b5ecc..9327459cca --- a/scripts/ci-openai-python-smoke.py +++ b/scripts/ci-openai-python-smoke.py @@ -8,8 +8,6 @@ def streamed_text(chunks: Iterable[object]) -> str: - """Execute streamed_text operation.""" - parts: list[str] = [] saw_choice = False for chunk in chunks: @@ -30,14 +28,7 @@ def streamed_text(chunks: Iterable[object]) -> str: return text - """Execute main operation.""" - def main() -> None: - """Execute main program logic. - - Returns: - Exit code. - """ parser = argparse.ArgumentParser() parser.add_argument("--base-url", required=True) args = parser.parse_args() diff --git a/scripts/collect-ci-metrics.py b/scripts/collect-ci-metrics.py old mode 100644 new mode 100755 index 6693d2f0c7..e62f797ecf --- a/scripts/collect-ci-metrics.py +++ b/scripts/collect-ci-metrics.py @@ -38,7 +38,6 @@ def pick(data: dict[str, Any], *names: str, default: Any = None) -> Any: - """Execute pick operation.""" for name in names: if name in data: return data[name] @@ -46,7 +45,6 @@ def pick(data: dict[str, Any], *names: str, default: Any = None) -> Any: def timestamp(value: Any) -> dt.datetime | None: - """Execute timestamp operation.""" if not isinstance(value, str) or not value: return None value = value[:-1] + "+00:00" if value.endswith("Z") else value @@ -61,7 +59,6 @@ def timestamp(value: Any) -> dt.datetime | None: def elapsed(start: dt.datetime | None, end: dt.datetime | None) -> float | None: - """Execute elapsed operation.""" if start is None or end is None: return None seconds = (end - start).total_seconds() @@ -69,7 +66,6 @@ def elapsed(start: dt.datetime | None, end: dt.datetime | None) -> float | None: def percentile(values: list[float], quantile: float) -> float: - """Execute percentile operation.""" position = (len(values) - 1) * quantile low, high = math.floor(position), math.ceil(position) if low == high: @@ -78,7 +74,6 @@ def percentile(values: list[float], quantile: float) -> float: def summarize(values: list[float | None]) -> dict[str, float | int | None]: - """Execute summarize operation.""" samples = sorted(value for value in values if value is not None) if not samples: return { @@ -92,7 +87,6 @@ def summarize(values: list[float | None]) -> dict[str, float | int | None]: } def rounded(value: float) -> float: - """Execute rounded operation.""" return round(value, 3) return { @@ -107,7 +101,6 @@ def rounded(value: float) -> float: def normalize_step(raw: dict[str, Any]) -> dict[str, Any]: - """Execute normalize step operation.""" started = timestamp(pick(raw, "started_at", "startedAt")) completed = timestamp(pick(raw, "completed_at", "completedAt")) return { @@ -131,7 +124,6 @@ def _number(value: Any) -> float | None: def normalize_job(raw: dict[str, Any]) -> dict[str, Any]: - """Execute normalize job operation.""" labels = pick(raw, "labels", "runner_labels", default=[]) raw_steps = pick(raw, "steps", default=[]) steps = [] @@ -183,7 +175,6 @@ def normalize_job(raw: dict[str, Any]) -> dict[str, Any]: def normalize_run(raw: dict[str, Any]) -> dict[str, Any]: - """Execute normalize run operation.""" if not isinstance(raw.get("jobs"), list): run_id = pick(raw, "id", "databaseId", "database_id", default="unknown") raise ValueError( @@ -220,11 +211,6 @@ def normalize_run(raw: dict[str, Any]) -> dict[str, Any]: def load_runs(path: str) -> list[dict[str, Any]]: - """Load runs from source. - - Returns: - Loaded data. - """ if path == "-": data = json.load(sys.stdin) else: @@ -240,7 +226,6 @@ def load_runs(path: str) -> list[dict[str, Any]]: def gh_json(arguments: list[str]) -> Any: - """Execute gh json operation.""" command = ["gh", *arguments] try: result = subprocess.run( @@ -261,11 +246,6 @@ def gh_json(arguments: list[str]) -> Any: def fetch_jobs(repository: str, run_id: int) -> list[dict[str, Any]]: - """Get jobs. - - Returns: - Retrieved value. - """ jobs: list[dict[str, Any]] = [] page = 1 while True: @@ -294,11 +274,6 @@ def fetch_jobs(repository: str, run_id: int) -> list[dict[str, Any]]: def fetch_exact_run(repository: str, run_id: int) -> dict[str, Any]: - """Get exact run. - - Returns: - Retrieved value. - """ run = gh_json( [ "run", @@ -317,11 +292,6 @@ def fetch_exact_run(repository: str, run_id: int) -> dict[str, Any]: def fetch_runs(args: argparse.Namespace) -> list[dict[str, Any]]: - """Get runs. - - Returns: - Retrieved value. - """ if args.run_id: return [fetch_exact_run(args.repo, run_id) for run_id in args.run_id] command = [ @@ -468,7 +438,6 @@ def runner_dimensions( def observation(run: dict[str, Any], job: dict[str, Any]) -> dict[str, Any]: - """Execute observation operation.""" duration = elapsed(job["started"], job["completed"]) dependency_wait = job["dependency_wait_seconds"] if dependency_wait is None: @@ -523,7 +492,6 @@ def observation(run: dict[str, Any], job: dict[str, Any]) -> dict[str, Any]: def included(run: dict[str, Any], requested: str) -> tuple[bool, str]: - """Execute included operation.""" if run["status"] != "completed": return False, "not_completed" if requested in ("all", "completed") or run["conclusion"] == requested: @@ -820,7 +788,6 @@ def analyze( source: dict[str, Any], labels: dict[str, str], ) -> dict[str, Any]: - """Execute analyze operation.""" selected = [] skipped = collections.Counter() for run in runs: @@ -1279,7 +1246,6 @@ def analyze( def human(seconds: float | int | None) -> str: - """Execute human operation.""" if seconds is None: return "n/a" total = int(round(seconds)) @@ -1291,12 +1257,10 @@ def human(seconds: float | int | None) -> str: def markdown_escape(value: Any) -> str: - """Execute markdown escape operation.""" return str(value).replace("|", "\\|").replace("\n", " ") def render_markdown(report: dict[str, Any], top: int) -> str: - """Render output for markdown.""" workflow = report["workflow"] jobs = report["jobs"] lines = [ @@ -1467,7 +1431,6 @@ def render_markdown(report: dict[str, Any], top: int) -> str: def write(path: str, content: str) -> None: - """Save write to destination.""" if path == "-": sys.stdout.write(content) return @@ -1477,7 +1440,6 @@ def write(path: str, content: str) -> None: def labels(values: list[str]) -> dict[str, str]: - """Execute labels operation.""" result = {} for value in values: key, separator, label = value.partition("=") @@ -1488,11 +1450,6 @@ def labels(values: list[str]) -> dict[str, str]: def parse_args(argv: list[str]) -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser( description="Collect read-only GitHub Actions timing and runner metrics." ) @@ -1530,11 +1487,6 @@ def parse_args(argv: list[str]) -> argparse.Namespace: def main(argv: list[str]) -> int: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args(argv) try: if args.input: diff --git a/scripts/compose-product-bundle.py b/scripts/compose-product-bundle.py index 9e3fd963ff..5c2eb102fb 100644 --- a/scripts/compose-product-bundle.py +++ b/scripts/compose-product-bundle.py @@ -12,35 +12,29 @@ class RuntimeBackend(TypedDict): - """Represents RuntimeBackend functionality.""" kind: str class RuntimeData(TypedDict): - """Represents RuntimeData functionality.""" id: str mesh_version: str backend: RuntimeBackend class BuildData(TypedDict): - """Represents BuildData functionality.""" backend: str class RuntimeManifest(TypedDict): - """Represents RuntimeManifest functionality.""" runtime: RuntimeData build: NotRequired[BuildData] def expected_backend_kind(backend: str) -> str: - """Execute expected backend kind operation.""" return BACKEND_KIND_ALIASES.get(backend, backend) def file_sha256(path: Path) -> str: - """Execute file sha256 operation.""" digest = hashlib.sha256() with path.open("rb") as handle: for chunk in iter(lambda: handle.read(1024 * 1024), b""): @@ -49,7 +43,6 @@ def file_sha256(path: Path) -> str: def tree_sha256(path: Path) -> str: - """Execute tree sha256 operation.""" digest = hashlib.sha256() files = (candidate for candidate in path.rglob("*") if candidate.is_file()) for item in sorted(files, key=lambda candidate: candidate.relative_to(path).as_posix()): @@ -66,11 +59,6 @@ def validate_runtime_backend( runtime_data: RuntimeData, requested_backend: str, ) -> None: - """Validate runtime backend. - - Raises: - ValidationError: If validation fails. - """ expected_kind = expected_backend_kind(requested_backend) runtime_backend = runtime_data["backend"] runtime_kind = runtime_backend["kind"] @@ -95,7 +83,6 @@ def compose_manifest( version: str, backend: str, ) -> dict[str, object]: - """Execute compose manifest operation.""" version = version.removeprefix("v") runtime_manifest_path = runtime / "manifest.json" runtime_manifest: RuntimeManifest = json.loads( @@ -129,11 +116,6 @@ def compose_manifest( def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser() parser.add_argument("--bundle", type=Path, required=True) parser.add_argument("--host", type=Path, required=True) @@ -149,11 +131,6 @@ def parse_args() -> argparse.Namespace: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args() manifest = compose_manifest( args.bundle, args.host, args.runtime, args.version, args.backend diff --git a/scripts/generate-bench-corpus.py b/scripts/generate-bench-corpus.py old mode 100644 new mode 100755 index d29d38c2e4..0b7cf9a10c --- a/scripts/generate-bench-corpus.py +++ b/scripts/generate-bench-corpus.py @@ -22,11 +22,6 @@ def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("tier") parser.add_argument("--config", type=Path, default=DEFAULT_CONFIG) @@ -160,7 +155,6 @@ def main() -> int: def require_hf() -> None: - """Execute require hf operation.""" try: subprocess.run(["hf", "--version"], check=True, stdout=subprocess.DEVNULL) except Exception as error: @@ -168,7 +162,6 @@ def require_hf() -> None: def require_duckdb() -> None: - """Execute require duckdb operation.""" if python_has_duckdb(sys.executable) or command_exists("uv"): return raise RuntimeError( @@ -179,7 +172,6 @@ def require_duckdb() -> None: def python_has_duckdb(python: str) -> bool: - """Execute python has duckdb operation.""" return ( subprocess.run( [python, "-c", "import duckdb"], @@ -191,7 +183,6 @@ def python_has_duckdb(python: str) -> bool: def command_exists(name: str) -> bool: - """Execute command exists operation.""" return ( subprocess.run( ["bash", "-lc", f"command -v {name} >/dev/null"], @@ -203,20 +194,17 @@ def command_exists(name: str) -> bool: def read_json(path: Path) -> Any: - """Execute read json operation.""" with path.open("r", encoding="utf-8") as handle: return json.load(handle) def write_json(path: Path, value: Any) -> None: - """Save json to destination.""" with path.open("w", encoding="utf-8") as handle: json.dump(value, handle, ensure_ascii=False, indent=2, sort_keys=True) handle.write("\n") def rel(path: Path) -> str: - """Execute rel operation.""" try: return str(path.relative_to(ROOT)) except ValueError: @@ -224,7 +212,6 @@ def rel(path: Path) -> str: def git_commit() -> str | None: - """Execute git commit operation.""" try: output = subprocess.check_output( ["git", "rev-parse", "HEAD"], @@ -238,7 +225,6 @@ def git_commit() -> str | None: def hf_dataset_info(dataset: str, revision: str) -> dict[str, Any]: - """Execute hf dataset info operation.""" output = subprocess.check_output( ["hf", "datasets", "info", dataset, "--revision", revision, "--format", "json"], cwd=ROOT, @@ -248,7 +234,6 @@ def hf_dataset_info(dataset: str, revision: str) -> dict[str, Any]: def download_source(source: dict[str, Any], revision: str, hf_root: Path) -> Path: - """Execute download source operation.""" local_dir = hf_root / safe_name(source["dataset"]) / revision local_dir.mkdir(parents=True, exist_ok=True) include = parquet_include_patterns(source) @@ -275,7 +260,6 @@ def download_source(source: dict[str, Any], revision: str, hf_root: Path) -> Pat def download_converted_parquet(source: dict[str, Any], local_dir: Path) -> None: - """Execute download converted parquet operation.""" output = subprocess.check_output( [ "hf", @@ -309,7 +293,6 @@ def download_converted_parquet(source: dict[str, Any], local_dir: Path) -> None: def hf_headers() -> dict[str, str]: - """Execute hf headers operation.""" headers = {"User-Agent": "skippy-runtime-bench-corpus/1"} token = os.environ.get("HF_TOKEN") if token: @@ -318,7 +301,6 @@ def hf_headers() -> dict[str, str]: def parquet_include_patterns(source: dict[str, Any]) -> list[str]: - """Execute parquet include patterns operation.""" config = source["config"] split = source["split"] return [ @@ -332,7 +314,6 @@ def parquet_include_patterns(source: dict[str, Any]) -> list[str]: def find_parquet_files(local_dir: Path, source: dict[str, Any]) -> list[Path]: - """Execute find parquet files operation.""" config = source["config"] split = source["split"] files = sorted(local_dir.rglob("*.parquet")) @@ -359,7 +340,6 @@ def sample_rows( seed: int, limit: int, ) -> list[dict[str, Any]]: - """Execute sample rows operation.""" table_expr = "[" + ",".join(sql_string(str(path)) for path in parquet_files) + "]" material = f"{seed}:{source['name']}:{source['dataset']}:{source['config']}:{source['split']}" source_seed = int.from_bytes(hashlib.sha256(material.encode()).digest()[:8], "little") @@ -378,7 +358,6 @@ def sample_rows( def run_duckdb_json(query: str) -> str: - """Run duckdb json operation.""" code = """ import duckdb import json @@ -399,12 +378,10 @@ def run_duckdb_json(query: str) -> str: def sql_string(value: str) -> str: - """Execute sql string operation.""" return "'" + value.replace("'", "''") + "'" def safe_name(value: str) -> str: - """Execute safe name operation.""" return value.replace("/", "--") @@ -417,7 +394,6 @@ def normalize_row( max_prompt_chars: int, target_prompt_chars: int | None, ) -> dict[str, Any] | None: - """Execute normalize row operation.""" adapter = source["adapter"] prompt, expected, metadata, session_group = ADAPTERS[adapter](row) if prompt is None: @@ -460,7 +436,6 @@ def normalize_loop_rows( max_prompt_chars: int, target_prompt_chars: int | None, ) -> list[dict[str, Any]]: - """Execute normalize loop rows operation.""" adapter = source["adapter"] builder = LOOP_ADAPTERS.get(adapter) if builder is None: @@ -511,7 +486,6 @@ def normalize_loop_rows( def expand_prompt_to_chars(prompt: str, target_chars: int) -> str: - """Execute expand prompt to chars operation.""" prompt = clean_text(prompt) if len(prompt) >= target_chars: return prompt @@ -527,7 +501,6 @@ def expand_prompt_to_chars(prompt: str, target_chars: int) -> str: def truncate_text(value: str, max_chars: int) -> str: - """Execute truncate text operation.""" value = clean_text(value) if len(value) <= max_chars: return value @@ -541,7 +514,6 @@ def truncate_text(value: str, max_chars: int) -> str: def clean_text(value: Any) -> str: - """Execute clean text operation.""" if value is None: return "" if isinstance(value, str): @@ -550,7 +522,6 @@ def clean_text(value: Any) -> str: def commitpack_edit(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute commitpack edit operation.""" old = clean_text(row.get("old_contents")) new = clean_text(row.get("new_contents")) if not old or not new: @@ -576,7 +547,6 @@ def commitpack_edit(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any def code_refinement(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute code refinement operation.""" buggy = clean_text(row.get("buggy")) fixed = clean_text(row.get("fixed")) if not buggy or not fixed: @@ -590,7 +560,6 @@ def code_refinement(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any def swe_smith_trajectory_loop(row: dict[str, Any]) -> tuple[list[str], Any, dict[str, Any], str | None]: - """Execute swe smith trajectory loop operation.""" messages = row.get("messages") if not isinstance(messages, list): return [], None, {}, None @@ -622,7 +591,6 @@ def swe_smith_trajectory_loop(row: dict[str, Any]) -> tuple[list[str], Any, dict def agent_trajectory_prompt(transcript: list[tuple[str, str]]) -> str: - """Execute agent trajectory prompt operation.""" rendered: list[str] = [] for role, content in transcript[-12:]: rendered.append(f"{role.upper()}:\n{content}") @@ -635,13 +603,11 @@ def agent_trajectory_prompt(transcript: list[tuple[str, str]]) -> str: def sample_key(row: dict[str, Any]) -> str: - """Execute sample key operation.""" material = json.dumps(row, ensure_ascii=False, sort_keys=True, default=str) return hashlib.sha256(material.encode()).hexdigest()[:12] def swe_bench_issue(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute swe bench issue operation.""" statement = clean_text(row.get("problem_statement")) if not statement: return None, None, {}, None @@ -660,7 +626,6 @@ def swe_bench_issue(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any def apps_codegen(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute apps codegen operation.""" question = clean_text(row.get("question")) if not question: return None, None, {}, None @@ -672,7 +637,6 @@ def apps_codegen(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], def codesearchnet_explain(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute codesearchnet explain operation.""" code = clean_text(row.get("code")) comment = clean_text(row.get("comment")) if not code or not comment: @@ -686,7 +650,6 @@ def codesearchnet_explain(row: dict[str, Any]) -> tuple[str | None, Any, dict[st def xlam_tool_call(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute xlam tool call operation.""" query = clean_text(row.get("query")) tools = clean_text(row.get("tools")) if not query or not tools: @@ -703,7 +666,6 @@ def xlam_tool_call(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any] def spider_sql(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute spider sql operation.""" schema = clean_text(row.get("db_schema")) question = clean_text(row.get("question")) if not schema or not question: @@ -720,7 +682,6 @@ def spider_sql(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], st def oasst_prompt(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute oasst prompt operation.""" if row.get("role") != "prompter" or row.get("lang") != "en": return None, None, {}, None text = clean_text(row.get("text")) @@ -730,7 +691,6 @@ def oasst_prompt(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], def dolly_instruction(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute dolly instruction operation.""" instruction = clean_text(row.get("instruction")) context = clean_text(row.get("context")) if not instruction: @@ -742,7 +702,6 @@ def dolly_instruction(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, A def gsm8k_reasoning(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute gsm8k reasoning operation.""" question = clean_text(row.get("question")) if not question: return None, None, {}, None @@ -751,7 +710,6 @@ def gsm8k_reasoning(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any def xsum_summarize(row: dict[str, Any]) -> tuple[str | None, Any, dict[str, Any], str | None]: - """Execute xsum summarize operation.""" document = clean_text(row.get("document")) if not document: return None, None, {}, None diff --git a/scripts/generate-skippy-api-doc.py b/scripts/generate-skippy-api-doc.py index e2b1328d35..1804f08196 100644 --- a/scripts/generate-skippy-api-doc.py +++ b/scripts/generate-skippy-api-doc.py @@ -12,7 +12,6 @@ @dataclass(frozen=True) class Function: - """Represents Function functionality.""" name: str declaration: str brief: str @@ -20,7 +19,6 @@ class Function: @dataclass(frozen=True) class Header: - """Represents Header functionality.""" name: str brief: str declarations: tuple[str, ...] @@ -28,12 +26,10 @@ class Header: def normalize_declaration(declaration: str) -> str: - """Execute normalize declaration operation.""" return re.sub(r"\s+", " ", declaration.strip()) def pretty_declaration(declaration: str) -> str: - """Execute pretty declaration operation.""" declaration = normalize_declaration(declaration) declaration = declaration.replace("(", "(\n ", 1) declaration = declaration.replace(", ", ",\n ") @@ -42,23 +38,19 @@ def pretty_declaration(declaration: str) -> str: def anchor_id(prefix: str, value: str) -> str: - """Execute anchor id operation.""" slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-") return f"skippy-{prefix}-{slug}" def header_anchor(header: Header) -> str: - """Execute header anchor operation.""" return anchor_id("header", header.name) def function_anchor(function: Function) -> str: - """Execute function anchor operation.""" return anchor_id("fn", function.name) def comment_brief(comment: str) -> str: - """Execute comment brief operation.""" lines = [] for line in comment.splitlines(): line = re.sub(r"^\s*\*/\s*$", "", line) @@ -73,11 +65,6 @@ def comment_brief(comment: str) -> str: def parse_header(path: Path) -> Header: - """Parse and validate header. - - Returns: - Parsed result. - """ text = path.read_text() file_comment = re.search(r"/\*\*.*?@file.*?\*/", text, re.DOTALL) if file_comment is None: @@ -114,7 +101,6 @@ def parse_header(path: Path) -> Header: def render(headers: list[Header], include_dir: Path) -> str: - """Render output for render.""" functions = [function for header in headers for function in header.functions] lines = [ "---", @@ -235,11 +221,6 @@ def render(headers: list[Header], include_dir: Path) -> str: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ parser = argparse.ArgumentParser(description=__doc__) repo_root = Path(__file__).resolve().parents[1] parser.add_argument( diff --git a/scripts/hf-skippy-convert-job.py b/scripts/hf-skippy-convert-job.py index 6fbd0f5b85..784787e3ba 100644 --- a/scripts/hf-skippy-convert-job.py +++ b/scripts/hf-skippy-convert-job.py @@ -16,13 +16,11 @@ def run(*command: str, cwd: Path | None = None) -> None: - """Run run operation.""" print("+", " ".join(command), flush=True) subprocess.run(command, cwd=cwd, check=True) def ensure_build_tools() -> None: - """Execute ensure build tools operation.""" required = ("git", "curl", "cmake", "c++", "ld.lld") if any(shutil.which(tool) is None for tool in required): if shutil.which("apt-get") is None: @@ -51,11 +49,6 @@ def ensure_build_tools() -> None: def checkout_mesh(repo: str, revision: str, root: Path) -> None: - """Validate checkout mesh. - - Raises: - ValidationError: If validation fails. - """ if root.exists(): shutil.rmtree(root) run("git", "clone", "--filter=blob:none", repo, str(root)) @@ -63,7 +56,6 @@ def checkout_mesh(repo: str, revision: str, root: Path) -> None: def write_beta_card(artifact_dir: Path, source_repo: str, revision: str) -> None: - """Save beta card to destination.""" card = f"""--- license: apache-2.0 base_model: {source_repo} @@ -87,7 +79,6 @@ def write_beta_card(artifact_dir: Path, source_repo: str, revision: str) -> None def convert(args: argparse.Namespace, root: Path) -> Path: - """Execute convert operation.""" binary = root / "target" / "release" / "skippy-quantize" run("just", "skippy-quantize-standalone-release-build", "cpu", cwd=root) work = Path(args.work_dir) @@ -149,7 +140,6 @@ def convert(args: argparse.Namespace, root: Path) -> Path: def upload(args: argparse.Namespace, artifact_dir: Path) -> None: - """Execute upload operation.""" from huggingface_hub import HfApi api = HfApi(token=os.environ["HF_TOKEN"]) @@ -162,11 +152,6 @@ def upload(args: argparse.Namespace, artifact_dir: Path) -> None: def validate_converted_artifact(artifact_dir: Path) -> None: - """Validate converted artifact. - - Raises: - ValidationError: If validation fails. - """ required_files = ("README.md", "skippy-convert-manifest.json") missing = [name for name in required_files if not (artifact_dir / name).is_file()] if not artifact_dir.is_dir() or missing: @@ -199,7 +184,6 @@ def validate_converted_artifact(artifact_dir: Path) -> None: def converted_artifact_dir(args: argparse.Namespace) -> Path: - """Execute converted artifact dir operation.""" artifact_dir = Path(args.work_dir) / "target" / args.target_prefix if args.upload_only: validate_converted_artifact(artifact_dir) @@ -207,11 +191,6 @@ def converted_artifact_dir(args: argparse.Namespace) -> Path: def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser() parser.add_argument("--source", default="/mnt/checkpoint") parser.add_argument("--source-repo", required=True) @@ -238,11 +217,6 @@ def parse_args() -> argparse.Namespace: def main() -> None: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args() os.environ.setdefault("HF_HOME", str(Path(args.work_dir) / "hf-home")) # The work directory can be a mounted bucket. Xet's shard cache performs diff --git a/scripts/hf-skippy-mtp-certify-job.py b/scripts/hf-skippy-mtp-certify-job.py index 898855f97e..d9f0b3d3ab 100644 --- a/scripts/hf-skippy-mtp-certify-job.py +++ b/scripts/hf-skippy-mtp-certify-job.py @@ -24,13 +24,11 @@ def run(*command: str, cwd: Path | None = None) -> None: - """Run run operation.""" print("+", " ".join(command), flush=True) subprocess.run(command, cwd=cwd, check=True) def ensure_build_tools() -> None: - """Execute ensure build tools operation.""" required = ("git", "curl", "cmake", "c++", "ld.lld") if any(shutil.which(tool) is None for tool in required): if shutil.which("apt-get") is None: @@ -59,11 +57,6 @@ def ensure_build_tools() -> None: def checkout_mesh(repo: str, revision: str, root: Path) -> None: - """Validate checkout mesh. - - Raises: - ValidationError: If validation fails. - """ if root.exists(): shutil.rmtree(root) run("git", "clone", "--filter=blob:none", repo, str(root)) @@ -71,7 +64,6 @@ def checkout_mesh(repo: str, revision: str, root: Path) -> None: def model_parts(args: argparse.Namespace) -> list[Path]: - """Execute model parts operation.""" parts = sorted(Path(args.model_root).glob(args.model_pattern)) if len(parts) != args.expected_parts: raise RuntimeError( @@ -82,7 +74,6 @@ def model_parts(args: argparse.Namespace) -> list[Path]: def require_gguf_magic(path: Path) -> Path: - """Execute require gguf magic operation.""" with path.open("rb") as handle: magic = handle.read(4) if magic != b"GGUF": @@ -91,11 +82,6 @@ def require_gguf_magic(path: Path) -> Path: def validate_projector_url(url: str) -> urllib.parse.ParseResult: - """Validate projector url. - - Raises: - ValidationError: If validation fails. - """ parsed = urllib.parse.urlparse(url) if parsed.scheme != "https": raise RuntimeError(f"unsupported projector URL scheme: {parsed.scheme!r}") @@ -123,15 +109,12 @@ def validate_projector_url(url: str) -> urllib.parse.ParseResult: class TrustedProjectorRedirectHandler(urllib.request.HTTPRedirectHandler): - """Represents TrustedProjectorRedirectHandler functionality.""" def redirect_request(self, req, fp, code, msg, headers, newurl): # noqa: ANN001 - """Execute redirect request operation.""" validate_projector_url(newurl) return super().redirect_request(req, fp, code, msg, headers, newurl) def copy_projector_response(response, output) -> None: # noqa: ANN001 - """Execute copy projector response operation.""" content_length = response.headers.get("Content-Length") if content_length is not None and int(content_length) > PROJECTOR_DOWNLOAD_MAX_BYTES: raise RuntimeError("projector download exceeds the maximum supported size") @@ -144,7 +127,6 @@ def copy_projector_response(response, output) -> None: # noqa: ANN001 def projector_path(args: argparse.Namespace) -> Path: - """Execute projector path operation.""" if not args.projector_url: return require_gguf_magic(Path(args.projector)) parsed = validate_projector_url(args.projector_url) @@ -169,7 +151,6 @@ def projector_path(args: argparse.Namespace) -> Path: def run_report(command: list[str], report_out: str) -> None: - """Run report operation.""" print("+", " ".join(command), flush=True) completed = subprocess.run(command, text=True, capture_output=True) if completed.stderr: @@ -185,7 +166,6 @@ def run_report(command: list[str], report_out: str) -> None: def certify(args: argparse.Namespace, mesh_root: Path) -> None: - """Execute certify operation.""" binary = mesh_root / "target" / "release" / "skippy-quantize" run("just", "skippy-quantize-standalone-release-build", "cpu", cwd=mesh_root) projector = projector_path(args) @@ -219,11 +199,6 @@ def certify(args: argparse.Namespace, mesh_root: Path) -> None: def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser() parser.add_argument("--model-root", default="/target") parser.add_argument("--model-pattern", required=True) @@ -243,11 +218,6 @@ def parse_args() -> argparse.Namespace: def main() -> None: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args() ensure_build_tools() mesh_root = Path("/tmp/mesh-llm") diff --git a/scripts/manage-build-cache.py b/scripts/manage-build-cache.py old mode 100644 new mode 100755 index c26a4a3ed2..cb205bdcef --- a/scripts/manage-build-cache.py +++ b/scripts/manage-build-cache.py @@ -32,17 +32,6 @@ class CacheError(RuntimeError): def parse_size(value: str) -> int: - """Parse a human-readable size string (e.g., '80GiB') into bytes. - - Args: - value: Size string with optional unit (B, KiB, MiB, GiB, TiB). - - Returns: - Size in bytes. - - Raises: - argparse.ArgumentTypeError: If the size format is invalid. - """ value = value.removeprefix("max_size=") match = SIZE_PATTERN.fullmatch(value.strip()) if not match: @@ -51,17 +40,6 @@ def parse_size(value: str) -> int: def parse_age(value: str) -> int: - """Parse a maximum age string into days. - - Args: - value: Age string representing days (e.g., '14'). - - Returns: - Age in days. - - Raises: - argparse.ArgumentTypeError: If the age format is invalid. - """ try: return int(value.removeprefix("max_age=")) except ValueError as error: @@ -69,14 +47,6 @@ def parse_age(value: str) -> int: def human_size(value: int) -> str: - """Convert bytes to a human-readable size string. - - Args: - value: Size in bytes. - - Returns: - Human-readable size string (e.g., '1.5 GiB'). - """ amount = float(value) for unit in ("B", "KiB", "MiB", "GiB", "TiB"): if amount < 1024 or unit == "TiB": @@ -86,14 +56,6 @@ def human_size(value: int) -> str: def tree_metrics(path: Path) -> tuple[int, float]: - """Calculate total size and newest modification time for a path tree. - - Args: - path: File or directory path to measure. - - Returns: - Tuple of (total bytes, newest mtime). - """ if not path.exists(): return 0, 0.0 if path.is_file() or path.is_symlink(): @@ -117,14 +79,6 @@ def tree_metrics(path: Path) -> tuple[int, float]: def immediate_entries(path: Path) -> list[dict[str, Any]]: - """Collect metrics for immediate children of a directory, sorted by size. - - Args: - path: Directory path to inspect. - - Returns: - List of entry dictionaries with path, bytes, and newest_mtime fields. - """ entries = [] if path.is_dir(): for child in path.iterdir(): @@ -134,17 +88,6 @@ def immediate_entries(path: Path) -> list[dict[str, Any]]: def cargo_metadata(workspace: Path) -> dict[str, Any]: - """Retrieve Cargo workspace metadata via just command. - - Args: - workspace: Cargo workspace root directory. - - Returns: - Parsed Cargo metadata JSON. - - Raises: - CacheError: If cargo metadata command fails. - """ result = subprocess.run( ["just", "cache-cargo-metadata"], cwd=workspace, check=False, capture_output=True, text=True, @@ -155,27 +98,10 @@ def cargo_metadata(workspace: Path) -> dict[str, Any]: def cargo_packages(workspace: Path) -> list[str]: - """Get sorted list of all Cargo package names in the workspace. - - Args: - workspace: Cargo workspace root directory. - - Returns: - Sorted list of package names. - """ return sorted({package["name"] for package in cargo_metadata(workspace)["packages"]}) def reject_separate_build_directory(workspace: Path, managed_target: Path) -> None: - """Validate that Cargo build directory configuration is supported. - - Args: - workspace: Cargo workspace root directory. - managed_target: Expected target directory path. - - Raises: - CacheError: If build directory configuration is unsupported. - """ managed_target = managed_target.resolve() if os.environ.get("CARGO_BUILD_BUILD_DIR"): raise CacheError("CARGO_BUILD_BUILD_DIR is unsupported by build-cache management") @@ -203,15 +129,6 @@ def artifact_roots(target: Path, leaf: str) -> list[Path]: def package_metrics(target: Path, packages: Iterable[str]) -> list[dict[str, Any]]: - """Calculate size and age metrics for Cargo packages in the target directory. - - Args: - target: Cargo target directory. - packages: Iterable of package names to measure. - - Returns: - List of package metrics sorted by age and size. - """ normalized = {package: package.replace("-", "_") for package in packages} totals = {package: [0, 0.0] for package in normalized} roots = [*artifact_roots(target, "deps"), *artifact_roots(target, "build")] @@ -233,11 +150,6 @@ def package_metrics(target: Path, packages: Iterable[str]) -> list[dict[str, Any def active_compilers() -> list[str]: - """Detect active Rust compiler processes. - - Returns: - List of process lines for active cargo/rustc/rustdoc/clippy processes. - """ result = subprocess.run( ["ps", "-axo", "pid=,comm=,args="], check=True, capture_output=True, text=True, ) @@ -252,19 +164,6 @@ def active_compilers() -> list[str]: @contextmanager def cache_lock(target: Path, *, exclusive: bool, nonblocking: bool) -> Iterator[BinaryIO]: - """Acquire a file lock for cache operations. - - Args: - target: Target directory containing the lock file. - exclusive: Whether to acquire an exclusive (write) lock. - nonblocking: Whether to fail immediately if lock is unavailable. - - Yields: - Open lock file handle. - - Raises: - CacheError: If lock cannot be acquired in nonblocking mode. - """ target.mkdir(parents=True, exist_ok=True) lock_file = (target / ".mesh-llm-cache-prune.lock").open("a+b") operation = fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH @@ -282,15 +181,6 @@ def cache_lock(target: Path, *, exclusive: bool, nonblocking: bool) -> Iterator[ def remove_tree(path: Path, target: Path) -> None: - """Safely remove a directory tree within the target directory. - - Args: - path: Path to remove. - target: Target directory that must contain the path. - - Raises: - CacheError: If path is outside target or invalid. - """ candidate = Path(os.path.abspath(path)) target_absolute = Path(os.path.abspath(target)) target_resolved = target.resolve() @@ -310,18 +200,6 @@ def remove_tree(path: Path, target: Path) -> None: def prune_incremental( target: Path, cutoff: float, current_bytes: int, max_bytes: int, execute: bool, ) -> tuple[int, list[dict[str, Any]]]: - """Prune incremental compilation artifacts that are old or exceed size limit. - - Args: - target: Cargo target directory. - cutoff: Age cutoff timestamp. - current_bytes: Current total size in bytes. - max_bytes: Maximum allowed bytes. - execute: Whether to actually remove files. - - Returns: - Tuple of (updated byte count, list of pruned actions). - """ candidates = [] for root in artifact_roots(target, "incremental"): for child in root.iterdir(): @@ -343,22 +221,6 @@ def prune_packages( workspace: Path, target: Path, current_bytes: int, max_bytes: int, cutoff: float, execute: bool, ) -> tuple[int, list[dict[str, Any]]]: - """Prune Cargo package artifacts that are old or exceed size limit. - - Args: - workspace: Cargo workspace root directory. - target: Cargo target directory. - current_bytes: Current total size in bytes. - max_bytes: Maximum allowed bytes. - cutoff: Age cutoff timestamp. - execute: Whether to actually remove files. - - Returns: - Tuple of (updated byte count, list of pruned actions). - - Raises: - CacheError: If cargo clean command fails. - """ actions = [] for metrics in package_metrics(target, cargo_packages(workspace)): if current_bytes <= max_bytes and metrics["newest_mtime"] >= cutoff: @@ -391,17 +253,6 @@ def prune_packages( def snapshot(workspace: Path, target: Path, max_bytes: int, max_age_days: int) -> dict[str, Any]: - """Create a cache status snapshot with size and age information. - - Args: - workspace: Cargo workspace root directory. - target: Cargo target directory. - max_bytes: Maximum allowed bytes. - max_age_days: Maximum age in days. - - Returns: - Dictionary containing cache status information. - """ total, newest = tree_metrics(target) return { "schema": "mesh-llm.local-build-cache", "schema_version": 1, @@ -413,11 +264,6 @@ def snapshot(workspace: Path, target: Path, max_bytes: int, max_age_days: int) - def render_status(report: dict[str, Any]) -> None: - """Print human-readable cache status report. - - Args: - report: Cache snapshot dictionary. - """ print(f"Cargo target: {human_size(report['target_bytes'])}") print(f"Configured limit: {human_size(report['target_limit_bytes'])}") print(f"Configured maximum age: {report['max_age_days']} days") @@ -429,11 +275,6 @@ def render_status(report: dict[str, Any]) -> None: def parse_args() -> argparse.Namespace: - """Parse command-line arguments for cache management operations. - - Returns: - Parsed arguments namespace. - """ parser = argparse.ArgumentParser() commands = parser.add_subparsers(dest="command", required=True) for command in ("status", "prune"): @@ -453,14 +294,6 @@ def parse_args() -> argparse.Namespace: def main() -> int: - """Execute cache management commands: status, prune, or build. - - Returns: - Exit code: 0 for success, non-zero for errors. - - Raises: - CacheError: If validation or operations fail. - """ arguments = parse_args() workspace = arguments.workspace.resolve() target = (arguments.target_dir or workspace / "target").resolve() @@ -492,16 +325,6 @@ def main() -> int: def run_prune(arguments: argparse.Namespace, workspace: Path, target: Path) -> int: - """Execute cache pruning based on age and size constraints. - - Args: - arguments: Parsed command-line arguments. - workspace: Cargo workspace root directory. - target: Cargo target directory. - - Returns: - Exit code 0 on success. - """ before = snapshot(workspace, target, arguments.max_size, arguments.max_age) cutoff = time.time() - arguments.max_age * 86400 current, incremental = prune_incremental( diff --git a/scripts/plan-ci.py b/scripts/plan-ci.py index 8587a84283..03a3896a67 100644 --- a/scripts/plan-ci.py +++ b/scripts/plan-ci.py @@ -255,7 +255,6 @@ def _assert_acyclic(dependencies: dict[str, list[str]]) -> None: visited: set[str] = set() def visit(node: str) -> None: - """Execute visit operation.""" if node in visiting: raise PlanError(f"slice dependency cycle includes {node!r}") if node in visited: @@ -502,7 +501,6 @@ def _select_rows( smoke_ids = [row_id for row_id in smoke_ids if row_id == "core"] or [smoke_ids[0]] def unique_rows(mapping: dict[str, dict[str, Any]], ids: Iterable[str], field: str) -> list[dict[str, Any]]: - """Execute unique rows operation.""" result: list[dict[str, Any]] = [] seen: set[str] = set() for row_id in ids: @@ -792,11 +790,6 @@ def _validate_plan(plan: dict[str, Any], slices: dict[str, Any], packages: list[ def build_plan(payload: object, *, root: Path = ROOT) -> dict[str, Any]: - """Create plan. - - Returns: - Created object. - """ input_data = _validate_input(payload) ownership = _load_manifest(root / "ci" / "ownership.yml") slices = _load_manifest(root / "ci" / "slices.yml") @@ -889,11 +882,6 @@ def build_plan(payload: object, *, root: Path = ROOT) -> dict[str, Any]: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ try: payload = json.load(sys.stdin) plan = build_plan(payload) diff --git a/scripts/qa-agent-tool-call-reliability.py b/scripts/qa-agent-tool-call-reliability.py old mode 100644 new mode 100755 index 53e4fdb729..206b60315c --- a/scripts/qa-agent-tool-call-reliability.py +++ b/scripts/qa-agent-tool-call-reliability.py @@ -24,19 +24,16 @@ class Probe(NamedTuple): - """Represents Probe functionality.""" model: str attempt: int class ToolCall(NamedTuple): - """Represents ToolCall functionality.""" call_id: str key: str class ProbeResult(NamedTuple): - """Represents ProbeResult functionality.""" model: str attempt: int phase: str @@ -47,7 +44,6 @@ class ProbeResult(NamedTuple): def normalize_v1_base(base_url: str) -> str: - """Execute normalize v1 base operation.""" base = base_url.strip().rstrip("/") if not base: raise ValueError("base URL is empty") @@ -57,11 +53,6 @@ def normalize_v1_base(base_url: str) -> str: def parse_models(value: str) -> list[str]: - """Parse and validate models. - - Returns: - Parsed result. - """ models = [part.strip() for part in value.split(",") if part.strip()] if not models: raise ValueError("at least one model is required") @@ -69,11 +60,6 @@ def parse_models(value: str) -> list[str]: def build_plan(models: Iterable[str], attempts: int) -> list[Probe]: - """Create plan. - - Returns: - Created object. - """ if attempts < 1: raise ValueError("attempts must be at least 1") return [ @@ -84,7 +70,6 @@ def build_plan(models: Iterable[str], attempts: int) -> list[Probe]: def render_plan(plan: Iterable[Probe], base_url: str) -> str: - """Render output for plan.""" payload = { "name": "agent-tool-call-reliability", "endpoint": normalize_v1_base(base_url), @@ -107,7 +92,6 @@ def render_plan(plan: Iterable[Probe], base_url: str) -> str: def tool_schema() -> list[dict[str, Any]]: - """Execute tool schema operation.""" return [ { "type": "function", @@ -131,7 +115,6 @@ def tool_schema() -> list[dict[str, Any]]: def initial_messages(attempt: int) -> list[dict[str, str]]: - """Execute initial messages operation.""" return [ { "role": "system", @@ -148,11 +131,6 @@ def initial_messages(attempt: int) -> list[dict[str, str]]: def build_tool_probe_request(model: str, attempt: int) -> dict[str, Any]: - """Create tool probe request. - - Returns: - Created object. - """ return { "model": model, "messages": initial_messages(attempt), @@ -170,18 +148,12 @@ def build_tool_probe_request(model: str, attempt: int) -> dict[str, Any]: def build_stream_tool_probe_request(model: str, attempt: int) -> dict[str, Any]: - """Create stream tool probe request. - - Returns: - Created object. - """ request = build_tool_probe_request(model, attempt) request["stream"] = True return request def extract_tool_call(response: dict[str, Any]) -> ToolCall: - """Execute extract tool call operation.""" _require_tool_call_finish(response) message = _first_message(response) calls = message.get("tool_calls") @@ -206,7 +178,6 @@ def extract_tool_call(response: dict[str, Any]) -> ToolCall: def extract_stream_tool_call(chunks: Iterable[dict[str, Any]]) -> ToolCall: - """Execute extract stream tool call operation.""" parts: dict[int, dict[str, Any]] = {} saw_tool_finish = False for chunk in chunks: @@ -254,11 +225,6 @@ def build_tool_result_request( assistant_message: dict[str, Any], call: ToolCall, ) -> dict[str, Any]: - """Create tool result request. - - Returns: - Created object. - """ expected = FIXTURE_FACTS[call.key] messages = initial_messages(attempt) messages.append(_sanitize_assistant_tool_message(assistant_message)) @@ -289,22 +255,12 @@ def build_stream_tool_result_request( assistant_message: dict[str, Any], call: ToolCall, ) -> dict[str, Any]: - """Create stream tool result request. - - Returns: - Created object. - """ request = build_tool_result_request(model, attempt, assistant_message, call) request["stream"] = True return request def validate_final_answer(response: dict[str, Any], expected: str) -> None: - """Validate final answer. - - Raises: - ValidationError: If validation fails. - """ message = _first_message(response) if message.get("tool_calls"): raise ValueError("continuation returned another tool call") @@ -313,11 +269,6 @@ def validate_final_answer(response: dict[str, Any], expected: str) -> None: def validate_final_content(content: Any, expected: str) -> None: - """Validate final content. - - Raises: - ValidationError: If validation fails. - """ if not isinstance(content, str) or not content.strip(): raise ValueError("continuation returned empty content") if expected not in content: @@ -325,7 +276,6 @@ def validate_final_content(content: Any, expected: str) -> None: def extract_stream_content(chunks: Iterable[dict[str, Any]]) -> str: - """Execute extract stream content operation.""" parts: list[str] = [] saw_choice = False for chunk in chunks: @@ -348,7 +298,6 @@ def extract_stream_content(chunks: Iterable[dict[str, Any]]) -> str: def write_jsonl(path: Path, results: Iterable[ProbeResult]) -> None: - """Save jsonl to destination.""" path.parent.mkdir(parents=True, exist_ok=True) with path.open("w", encoding="utf-8") as handle: for result in results: @@ -361,7 +310,6 @@ def run_probe( timeout: float, include_streaming: bool = True, ) -> list[ProbeResult]: - """Run probe operation.""" results: list[ProbeResult] = [] results.extend(run_non_stream_probe(base_url, probe, timeout)) if include_streaming: @@ -370,7 +318,6 @@ def run_probe( def run_non_stream_probe(base_url: str, probe: Probe, timeout: float) -> list[ProbeResult]: - """Run non stream probe operation.""" results: list[ProbeResult] = [] tool_started = time.monotonic() try: @@ -413,7 +360,6 @@ def run_non_stream_probe(base_url: str, probe: Probe, timeout: float) -> list[Pr def run_stream_probe(base_url: str, probe: Probe, timeout: float) -> list[ProbeResult]: - """Run stream probe operation.""" results: list[ProbeResult] = [] tool_started = time.monotonic() try: @@ -457,7 +403,6 @@ def run_stream_probe(base_url: str, probe: Probe, timeout: float) -> list[ProbeR def assistant_message_from_tool_call(call: ToolCall) -> dict[str, Any]: - """Execute assistant message from tool call operation.""" return { "role": "assistant", "content": None, @@ -480,7 +425,6 @@ def post_json( payload: dict[str, Any], timeout: float, ) -> tuple[dict[str, Any], int]: - """Execute post json operation.""" data = json.dumps(payload).encode("utf-8") request = urllib.request.Request( f"{normalize_v1_base(base_url)}{path}", @@ -517,7 +461,6 @@ def post_json_stream( payload: dict[str, Any], timeout: float, ) -> tuple[list[dict[str, Any]], int]: - """Execute post json stream operation.""" data = json.dumps(payload).encode("utf-8") request = urllib.request.Request( f"{normalize_v1_base(base_url)}{path}", @@ -545,11 +488,6 @@ def post_json_stream( def parse_sse_lines(lines: Iterable[str]) -> Iterable[dict[str, Any]]: - """Parse and validate sse lines. - - Returns: - Parsed result. - """ for raw_line in lines: line = raw_line.strip() if not line or line.startswith(":") or not line.startswith("data:"): @@ -567,7 +505,6 @@ def parse_sse_lines(lines: Iterable[str]) -> Iterable[dict[str, Any]]: def default_base_url() -> str: - """Execute default base url operation.""" env_base = ( os.environ.get("MESH_AGENT_TOOL_BASE_URL") or os.environ.get("MESH_AGENT_BASE_URL") @@ -582,11 +519,6 @@ def default_base_url() -> str: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args() base_url = normalize_v1_base(args.base_url) models = parse_models(args.models) @@ -611,11 +543,6 @@ def main() -> int: def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser( description="Probe OpenAI chat tool-call and tool-result continuation reliability.", ) @@ -641,7 +568,6 @@ def parse_args() -> argparse.Namespace: def print_summary(results: Iterable[ProbeResult], output: Path) -> None: - """Render output for summary.""" rows = list(results) passed = sum(1 for row in rows if row.ok) print(f"agent tool-call reliability: {passed}/{len(rows)} phases passed") diff --git a/scripts/qa-kv-tool-loop-stability.py b/scripts/qa-kv-tool-loop-stability.py old mode 100644 new mode 100755 index a809f3b8d5..446510a659 --- a/scripts/qa-kv-tool-loop-stability.py +++ b/scripts/qa-kv-tool-loop-stability.py @@ -41,19 +41,16 @@ class ToolCall(NamedTuple): - """Represents ToolCall functionality.""" call_id: str key: str class CacheMetrics(NamedTuple): - """Represents CacheMetrics functionality.""" prompt_tokens: int cached_tokens: int class LogFinding(NamedTuple): - """Represents LogFinding functionality.""" path: str line_number: int pattern: str @@ -61,7 +58,6 @@ class LogFinding(NamedTuple): class NativeLogCheckpoint(NamedTuple): - """Represents NativeLogCheckpoint functionality.""" path: Path offset: int identity: tuple[int, int] | None @@ -69,7 +65,6 @@ class NativeLogCheckpoint(NamedTuple): class ProbeResult(NamedTuple): - """Represents ProbeResult functionality.""" model: str attempt: int phase: str @@ -82,7 +77,6 @@ class ProbeResult(NamedTuple): class OverlapRequest(NamedTuple): - """Represents OverlapRequest functionality.""" label: str payload: dict[str, Any] expects_tool_call: bool @@ -90,7 +84,6 @@ class OverlapRequest(NamedTuple): def normalize_v1_base(base_url: str) -> str: - """Execute normalize v1 base operation.""" base = base_url.strip().rstrip("/") if not base: raise ValueError("base URL is empty") @@ -100,11 +93,6 @@ def normalize_v1_base(base_url: str) -> str: def parse_models(value: str) -> list[str]: - """Parse and validate models. - - Returns: - Parsed result. - """ models = [part.strip() for part in value.split(",") if part.strip()] if not models: raise ValueError("at least one model is required") @@ -112,11 +100,6 @@ def parse_models(value: str) -> list[str]: def parse_native_logs(values: Iterable[str] | None) -> list[Path]: - """Parse and validate native logs. - - Returns: - Parsed result. - """ logs: list[Path] = [] env_value = os.environ.get("MESH_KV_TOOL_LOOP_NATIVE_LOGS") if env_value: @@ -131,7 +114,6 @@ def parse_native_logs(values: Iterable[str] | None) -> list[Path]: def dedupe_paths(paths: Iterable[Path]) -> list[Path]: - """Execute dedupe paths operation.""" deduped: list[Path] = [] seen: set[str] = set() for path in paths: @@ -155,11 +137,6 @@ def build_plan( native_logs: Iterable[Path], overlap_requests: int = DEFAULT_OVERLAP_REQUESTS, ) -> dict[str, Any]: - """Create plan. - - Returns: - Created object. - """ model_list = list(models) if attempts < 1: raise ValueError("attempts must be at least 1") @@ -248,12 +225,10 @@ def build_plan( def render_plan(plan: dict[str, Any]) -> str: - """Render output for plan.""" return json.dumps(plan, indent=2, sort_keys=True) def tool_schema() -> list[dict[str, Any]]: - """Execute tool schema operation.""" return [ { "type": "function", @@ -282,11 +257,6 @@ def build_tool_call_request( key: str = "primary", messages: list[dict[str, Any]] | None = None, ) -> dict[str, Any]: - """Create tool call request. - - Returns: - Created object. - """ request_messages = list(messages) if messages is not None else initial_messages(attempt, key) return { "model": model, @@ -310,11 +280,6 @@ def build_overlap_requests( attempt: int, overlap_requests: int, ) -> list[OverlapRequest]: - """Create overlap requests. - - Returns: - Created object. - """ if overlap_requests < 2: raise ValueError("overlap_requests must be at least 2") requests = [ @@ -346,11 +311,6 @@ def build_overlap_requests( def build_overlap_title_request(model: str, attempt: int) -> dict[str, Any]: - """Create overlap title request. - - Returns: - Created object. - """ return { "model": model, "messages": [ @@ -380,11 +340,6 @@ def build_overlap_tool_request( label: str, key: str, ) -> dict[str, Any]: - """Create overlap tool request. - - Returns: - Created object. - """ messages = [ { "role": "system", @@ -403,7 +358,6 @@ def build_overlap_tool_request( def initial_messages(attempt: int, key: str) -> list[dict[str, str]]: - """Execute initial messages operation.""" return [ { "role": "system", @@ -425,11 +379,6 @@ def build_tool_result_request( messages: list[dict[str, Any]], max_tokens: int = 128, ) -> dict[str, Any]: - """Create tool result request. - - Returns: - Created object. - """ return { "model": model, "messages": messages, @@ -442,11 +391,6 @@ def build_tool_result_request( def build_cache_request(model: str, tail: str) -> dict[str, Any]: - """Create cache request. - - Returns: - Created object. - """ return { "model": model, "messages": [ @@ -470,7 +414,6 @@ def build_cache_request(model: str, tail: str) -> dict[str, Any]: def stable_system_prefix() -> str: - """Execute stable system prefix operation.""" lines = [ "You are a deterministic KV/cache stability certification endpoint.", f"Pinned recall token: {KV_PIN}.", @@ -485,7 +428,6 @@ def stable_system_prefix() -> str: def extract_tool_call(response: dict[str, Any]) -> ToolCall: - """Execute extract tool call operation.""" finish_reason = _first_choice(response).get("finish_reason") if finish_reason != "tool_calls": raise ValueError(f"tool-call turn finish_reason was not tool_calls: {finish_reason!r}") @@ -510,7 +452,6 @@ def extract_tool_call(response: dict[str, Any]) -> ToolCall: def assistant_tool_message(response: dict[str, Any]) -> dict[str, Any]: - """Execute assistant tool message operation.""" message = dict(_first_message(response)) return { "role": "assistant", @@ -520,7 +461,6 @@ def assistant_tool_message(response: dict[str, Any]) -> dict[str, Any]: def tool_result_message(call: ToolCall) -> dict[str, Any]: - """Execute tool result message operation.""" return { "role": "tool", "tool_call_id": call.call_id, @@ -533,7 +473,6 @@ def tool_result_message(call: ToolCall) -> dict[str, Any]: def extract_cache_metrics(response: dict[str, Any]) -> CacheMetrics: - """Execute extract cache metrics operation.""" usage = response.get("usage") if not isinstance(usage, dict): return CacheMetrics(prompt_tokens=0, cached_tokens=0) @@ -550,7 +489,6 @@ def evaluate_cache_threshold( min_cached_tokens: int, suffix_prefill_limit: int, ) -> tuple[bool, str]: - """Execute evaluate cache threshold operation.""" if metrics.cached_tokens < min_cached_tokens: return ( False, @@ -580,7 +518,6 @@ def evaluate_cache_threshold( def scan_failure_logs(paths: Iterable[Path]) -> list[LogFinding]: - """Execute scan failure logs operation.""" findings: list[LogFinding] = [] for path in paths: if not path.exists(): @@ -610,7 +547,6 @@ def scan_failure_logs(paths: Iterable[Path]) -> list[LogFinding]: def capture_native_log_checkpoints(paths: Iterable[Path]) -> list[NativeLogCheckpoint]: - """Execute capture native log checkpoints operation.""" checkpoints: list[NativeLogCheckpoint] = [] for path in paths: try: @@ -632,7 +568,6 @@ def capture_native_log_checkpoints(paths: Iterable[Path]) -> list[NativeLogCheck def scan_failure_logs_since( checkpoints: Iterable[NativeLogCheckpoint], ) -> list[LogFinding]: - """Execute scan failure logs since operation.""" findings: list[LogFinding] = [] for checkpoint in checkpoints: findings.extend(scan_one_log_since(checkpoint)) @@ -640,7 +575,6 @@ def scan_failure_logs_since( def scan_one_log_since(checkpoint: NativeLogCheckpoint) -> list[LogFinding]: - """Execute scan one log since operation.""" path = checkpoint.path try: stat = path.stat() @@ -671,7 +605,6 @@ def scan_failure_lines( handle: Iterable[bytes], start_line_number: int = 1, ) -> list[LogFinding]: - """Execute scan failure lines operation.""" findings: list[LogFinding] = [] for line_number, raw_line in enumerate(handle, start=start_line_number): line = raw_line.decode("utf-8", errors="replace").strip() @@ -689,7 +622,6 @@ def scan_failure_lines( def line_number_start_for_offset(handle: Any, offset: int) -> int: - """Execute line number start for offset operation.""" if offset <= 0: return 1 handle.seek(0) @@ -705,12 +637,10 @@ def line_number_start_for_offset(handle: Any, offset: int) -> int: def file_identity(stat: os.stat_result) -> tuple[int, int]: - """Execute file identity operation.""" return (int(stat.st_dev), int(stat.st_ino)) def read_checkpoint_tail(path: Path, offset: int) -> bytes: - """Execute read checkpoint tail operation.""" if offset <= 0: return b"" start = max(offset - NATIVE_LOG_CHECKPOINT_TAIL_BYTES, 0) @@ -720,11 +650,6 @@ def read_checkpoint_tail(path: Path, offset: int) -> bytes: def checkpoint_tail_matches(checkpoint: NativeLogCheckpoint) -> bool: - """Validate checkpoint tail matches. - - Raises: - ValidationError: If validation fails. - """ if checkpoint.offset <= 0: return True try: @@ -734,7 +659,6 @@ def checkpoint_tail_matches(checkpoint: NativeLogCheckpoint) -> bool: def matched_failure_pattern(line: str) -> str | None: - """Execute matched failure pattern operation.""" for pattern in FAILURE_PATTERNS: if pattern in line: return pattern @@ -751,7 +675,6 @@ def run_tool_loop_probe( pressure_turns: int, transcript_dir: Path, ) -> ProbeResult: - """Run tool loop probe operation.""" started = time.monotonic() transcript_path = transcript_dir / safe_name(f"{model}-attempt-{attempt}.jsonl") messages = initial_messages(attempt, "primary") @@ -790,7 +713,6 @@ def run_final_after_tool( timeout: float, expected_values: Iterable[str], ) -> None: - """Run final after tool operation.""" messages.append( { "role": "user", @@ -815,7 +737,6 @@ def run_pressure_turns( pressure_turns: int, transcript_path: Path, ) -> None: - """Run pressure turns operation.""" for turn in range(1, pressure_turns + 1): messages.append( { @@ -844,7 +765,6 @@ def run_second_tool_loop( timeout: float, transcript_path: Path, ) -> None: - """Run second tool loop operation.""" messages.append( { "role": "user", @@ -872,7 +792,6 @@ def run_final_recall( timeout: float, transcript_path: Path, ) -> None: - """Run final recall operation.""" expected = [KV_PIN, FIXTURE_FACTS["primary"], FIXTURE_FACTS["secondary"]] messages.append( { @@ -899,7 +818,6 @@ def run_cache_probe( min_cached_tokens: int, suffix_prefill_limit: int, ) -> ProbeResult: - """Run cache probe operation.""" started = time.monotonic() try: if phase == "exact_prefix_cache": @@ -945,7 +863,6 @@ def measure_cache_reuse( warm_tail: str, measured_tail: str, ) -> tuple[int, CacheMetrics]: - """Execute measure cache reuse operation.""" warm = build_cache_request(model, warm_tail) measured = build_cache_request(model, measured_tail) post_json(base_url, "/chat/completions", warm, timeout) @@ -964,7 +881,6 @@ def run_overlap_tool_loop_probe( suffix_prefill_limit: int, transcript_dir: Path, ) -> ProbeResult: - """Run overlap tool loop probe operation.""" started = time.monotonic() transcript_path = transcript_dir / safe_name(f"{model}-attempt-{attempt}-overlap") try: @@ -1029,11 +945,9 @@ def run_initial_overlap_requests( contexts: list[OverlapRequest], timeout: float, ) -> list[tuple[OverlapRequest, dict[str, Any], int]]: - """Run initial overlap requests operation.""" barrier = threading.Barrier(len(contexts)) def send(context: OverlapRequest) -> tuple[OverlapRequest, dict[str, Any], int]: - """Execute send operation.""" try: barrier.wait(timeout=min(max(timeout, 1.0), 30.0)) except threading.BrokenBarrierError as exc: @@ -1060,7 +974,6 @@ def complete_overlap_tool_loop( timeout: float, transcript_path: Path, ) -> None: - """Execute complete overlap tool loop operation.""" messages = [dict(message) for message in context.payload["messages"]] first_call = extract_tool_call(response) record_transcript( @@ -1076,7 +989,6 @@ def complete_overlap_tool_loop( def run_native_log_scan(checkpoints: Iterable[NativeLogCheckpoint]) -> ProbeResult: - """Run native log scan operation.""" started = time.monotonic() findings = scan_failure_logs_since(checkpoints) if findings: @@ -1102,7 +1014,6 @@ def run_certification( output_dir: Path, overlap_requests: int = DEFAULT_OVERLAP_REQUESTS, ) -> list[ProbeResult]: - """Run certification operation.""" transcript_dir = output_dir / "transcripts" prepare_transcript_dir(transcript_dir) log_checkpoints = capture_native_log_checkpoints(native_logs) @@ -1158,7 +1069,6 @@ def run_certification( def prepare_transcript_dir(transcript_dir: Path) -> None: - """Execute prepare transcript dir operation.""" if transcript_dir.is_symlink() or transcript_dir.is_file(): transcript_dir.unlink() elif transcript_dir.exists(): @@ -1167,7 +1077,6 @@ def prepare_transcript_dir(transcript_dir: Path) -> None: def write_evidence(output_dir: Path, plan: dict[str, Any], results: Iterable[ProbeResult]) -> None: - """Save evidence to destination.""" output_dir.mkdir(parents=True, exist_ok=True) rows = list(results) manifest = dict(plan) @@ -1191,7 +1100,6 @@ def write_evidence(output_dir: Path, plan: dict[str, Any], results: Iterable[Pro def summarize_results(results: Iterable[ProbeResult]) -> dict[str, Any]: - """Execute summarize results operation.""" rows = list(results) passed = sum(1 for row in rows if row.ok) failed = len(rows) - passed @@ -1210,7 +1118,6 @@ def summarize_results(results: Iterable[ProbeResult]) -> dict[str, Any]: def render_summary_markdown(summary: dict[str, Any], results: Iterable[ProbeResult]) -> str: - """Render output for summary markdown.""" rows = list(results) status = "PASS" if summary["ok"] else "FAIL" lines = [ @@ -1246,7 +1153,6 @@ def post_json( payload: dict[str, Any], timeout: float, ) -> tuple[dict[str, Any], int]: - """Execute post json operation.""" data = json.dumps(payload).encode("utf-8") request = urllib.request.Request( f"{normalize_v1_base(base_url)}{path}", @@ -1277,11 +1183,6 @@ def post_json( def validate_message(response: dict[str, Any], expected_values: Iterable[str]) -> None: - """Validate message. - - Raises: - ValidationError: If validation fails. - """ message = _first_message(response) if message.get("tool_calls"): raise ValueError("expected final text, got another tool call") @@ -1300,7 +1201,6 @@ def record_transcript( tool_call_id: str | None = None, detail: str | None = None, ) -> None: - """Execute record transcript operation.""" path.parent.mkdir(parents=True, exist_ok=True) payload = { "phase": phase, @@ -1314,7 +1214,6 @@ def record_transcript( def print_summary(results: Iterable[ProbeResult], output_dir: Path) -> None: - """Render output for summary.""" rows = list(results) passed = sum(1 for row in rows if row.ok) print(f"kv/tool-loop stability: {passed}/{len(rows)} phases passed") @@ -1325,11 +1224,6 @@ def print_summary(results: Iterable[ProbeResult], output_dir: Path) -> None: def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser( description="Certify live mesh-llm KV/cache stability under OpenAI tool-loop pressure.", ) @@ -1386,7 +1280,6 @@ def parse_args() -> argparse.Namespace: def default_base_url() -> str: - """Execute default base url operation.""" env_base = os.environ.get("MESH_KV_TOOL_LOOP_BASE_URL") if env_base: return env_base @@ -1397,11 +1290,6 @@ def default_base_url() -> str: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args() base_url = normalize_v1_base(args.base_url) models = parse_models(args.models) @@ -1441,11 +1329,6 @@ def main() -> int: def validate_runtime_options(args: argparse.Namespace) -> None: - """Validate runtime options. - - Raises: - ValidationError: If validation fails. - """ if args.attempts < 1: raise ValueError("attempts must be at least 1") if args.pressure_turns < 0: @@ -1532,13 +1415,11 @@ def _result( def safe_name(value: str) -> str: - """Execute safe name operation.""" safe = "".join(char if char.isalnum() or char in "._-" else "_" for char in value) return f"{safe}.jsonl" def utc_now() -> str: - """Execute utc now operation.""" return dt.datetime.now(dt.timezone.utc).isoformat().replace("+00:00", "Z") diff --git a/scripts/qa-nightly-stability.py b/scripts/qa-nightly-stability.py old mode 100644 new mode 100755 index 554ae284d3..7ba4dd1c16 --- a/scripts/qa-nightly-stability.py +++ b/scripts/qa-nightly-stability.py @@ -27,7 +27,6 @@ class CommandSpec(NamedTuple): - """Represents CommandSpec functionality.""" name: str command: list[str] env: dict[str, str] @@ -36,7 +35,6 @@ class CommandSpec(NamedTuple): class CommandResult(NamedTuple): - """Represents CommandResult functionality.""" name: str status: str exit_code: int @@ -45,7 +43,6 @@ class CommandResult(NamedTuple): class ProbeResult(NamedTuple): - """Represents ProbeResult functionality.""" model: str | None attempt: int | None phase: str @@ -59,7 +56,6 @@ class ProbeResult(NamedTuple): class AttestationResult(NamedTuple): - """Represents AttestationResult functionality.""" status: str ok: bool binary: str | None @@ -72,7 +68,6 @@ class AttestationResult(NamedTuple): def repo_root() -> Path: - """Execute repo root operation.""" return Path(__file__).resolve().parents[1] @@ -82,7 +77,6 @@ def strip_think_tags(text: str) -> str: def normalize_v1_base(base_url: str) -> str: - """Execute normalize v1 base operation.""" base = base_url.strip().rstrip("/") if not base: raise ValueError("base URL is empty") @@ -92,20 +86,10 @@ def normalize_v1_base(base_url: str) -> str: def parse_csv(value: str) -> list[str]: - """Parse and validate csv. - - Returns: - Parsed result. - """ return [part.strip() for part in value.split(",") if part.strip()] def parse_models(value: str) -> list[str]: - """Parse and validate models. - - Returns: - Parsed result. - """ models = parse_csv(value) if not models: raise ValueError("at least one model is required") @@ -113,11 +97,6 @@ def parse_models(value: str) -> list[str]: def parse_agent_smokes(value: str) -> list[str]: - """Parse and validate agent smokes. - - Returns: - Parsed result. - """ requested = parse_csv(value) unknown = sorted(set(requested) - set(VALID_AGENT_SMOKES)) if unknown: @@ -138,11 +117,6 @@ def build_plan( mesh_binary: str | None, release_attestation_expected_status: str | None, ) -> dict[str, Any]: - """Create plan. - - Returns: - Created object. - """ specs = build_command_specs( base_url=base_url, models=models, @@ -208,11 +182,6 @@ def build_command_specs( skip_streaming: bool, timeout: float, ) -> list[CommandSpec]: - """Create command specs. - - Returns: - Created object. - """ if attempts < 1: raise ValueError("attempts must be at least 1") base = normalize_v1_base(base_url) @@ -310,7 +279,6 @@ def _agent_smoke_spec(smoke: str, base_url: str, output_dir: Path) -> CommandSpe def run_commands(specs: Iterable[CommandSpec], output_dir: Path) -> list[CommandResult]: - """Run commands operation.""" results: list[CommandResult] = [] for spec in specs: result = run_command(spec, output_dir) @@ -324,7 +292,6 @@ def run_commands(specs: Iterable[CommandSpec], output_dir: Path) -> list[Command def run_command(spec: CommandSpec, output_dir: Path) -> CommandResult: - """Run command operation.""" log_path = output_dir / spec.log log_path.parent.mkdir(parents=True, exist_ok=True) if spec.prerequisite and shutil.which(spec.prerequisite) is None: @@ -383,7 +350,6 @@ def run_surface_probes( timeout: float, include_streaming: bool, ) -> list[ProbeResult]: - """Run surface probes operation.""" base = normalize_v1_base(base_url) results: list[ProbeResult] = [] @@ -405,7 +371,6 @@ def run_surface_probes( def run_models_probe(base_url: str, timeout: float) -> ProbeResult: - """Run models probe operation.""" started = time.monotonic() status_code = None try: @@ -419,7 +384,6 @@ def run_models_probe(base_url: str, timeout: float) -> ProbeResult: def run_chat_probe(base_url: str, model: str, attempt: int, timeout: float) -> ProbeResult: - """Run chat probe operation.""" started = time.monotonic() status_code = None actual_model = None @@ -451,7 +415,6 @@ def run_chat_probe(base_url: str, model: str, attempt: int, timeout: float) -> P def run_stream_chat_probe(base_url: str, model: str, attempt: int, timeout: float) -> ProbeResult: - """Run stream chat probe operation.""" started = time.monotonic() status_code = None ttft_ms = None @@ -504,11 +467,6 @@ def run_stream_chat_probe(base_url: str, model: str, attempt: int, timeout: floa def build_chat_request(model: str, attempt: int, stream: bool) -> dict[str, Any]: - """Create chat request. - - Returns: - Created object. - """ sentinel = "STREAM_OK" if stream else "STABILITY_OK" body: dict[str, Any] = { "model": model, @@ -533,11 +491,6 @@ def build_chat_request(model: str, attempt: int, stream: bool) -> dict[str, Any] def get_json(base_url: str, path: str, timeout: float) -> tuple[dict[str, Any], int]: - """Get json. - - Returns: - Retrieved value. - """ request = urllib.request.Request(f"{base_url}{path}", method="GET") try: with urllib.request.urlopen(request, timeout=timeout) as response: @@ -557,7 +510,6 @@ def post_json( payload: dict[str, Any], timeout: float, ) -> tuple[dict[str, Any], int]: - """Execute post json operation.""" data = json.dumps(payload).encode("utf-8") request = urllib.request.Request( f"{base_url}{path}", @@ -583,7 +535,6 @@ def post_json_stream( payload: dict[str, Any], timeout: float, ) -> tuple[list[dict[str, Any]], int, int | None]: - """Execute post json stream operation.""" data = json.dumps(payload).encode("utf-8") request = urllib.request.Request( f"{base_url}{path}", @@ -612,7 +563,6 @@ def post_json_stream( def decode_json_object(body: bytes) -> dict[str, Any]: - """Execute decode json object operation.""" try: decoded = json.loads(body) except json.JSONDecodeError as exc: @@ -624,11 +574,6 @@ def decode_json_object(body: bytes) -> dict[str, Any]: def parse_sse_lines(lines: Iterable[str]) -> Iterable[dict[str, Any]]: - """Parse and validate sse lines. - - Returns: - Parsed result. - """ for raw_line in lines: line = raw_line.strip() if not line or line.startswith(":") or not line.startswith("data:"): @@ -646,7 +591,6 @@ def parse_sse_lines(lines: Iterable[str]) -> Iterable[dict[str, Any]]: def first_message_content(response: dict[str, Any]) -> str: - """Execute first message content operation.""" choices = response.get("choices") if not isinstance(choices, list) or not choices: raise ValueError("response had no choices") @@ -663,7 +607,6 @@ def first_message_content(response: dict[str, Any]) -> str: def stream_content(chunks: Iterable[dict[str, Any]]) -> str: - """Execute stream content operation.""" parts: list[str] = [] saw_choice = False for chunk in chunks: @@ -686,11 +629,6 @@ def stream_content(chunks: Iterable[dict[str, Any]]) -> str: def validate_sentinel(content: str, sentinel: str) -> None: - """Validate sentinel. - - Raises: - ValidationError: If validation fails. - """ cleaned = strip_think_tags(content) if cleaned != sentinel and sentinel not in cleaned: raise ValueError(f"expected exactly {sentinel}, got {content!r}") @@ -729,7 +667,6 @@ def write_evidence( probe_results: list[ProbeResult] | None = None, attestation_result: AttestationResult | None = None, ) -> None: - """Save evidence to destination.""" output_dir.mkdir(parents=True, exist_ok=True) manifest = dict(plan) manifest["created_at"] = datetime.now(timezone.utc).isoformat() @@ -749,7 +686,6 @@ def write_evidence( def summarize_results(results: Iterable[CommandResult]) -> dict[str, Any]: - """Execute summarize results operation.""" rows = list(results) passed = sum(1 for row in rows if row.status == "PASS") failed = sum(1 for row in rows if row.status == "FAIL") @@ -766,7 +702,6 @@ def summarize_results(results: Iterable[CommandResult]) -> dict[str, Any]: def summarize_probe_results(results: Iterable[ProbeResult]) -> dict[str, Any]: - """Execute summarize probe results operation.""" rows = list(results) passed = sum(1 for row in rows if row.ok) failed = sum(1 for row in rows if not row.ok) @@ -782,7 +717,6 @@ def summarize_probe_results(results: Iterable[ProbeResult]) -> dict[str, Any]: def default_attestation_result() -> AttestationResult: - """Execute default attestation result operation.""" return AttestationResult( status="not_configured", ok=True, @@ -792,7 +726,6 @@ def default_attestation_result() -> AttestationResult: def summarize_attestation_result(result: AttestationResult | None) -> dict[str, Any]: - """Execute summarize attestation result operation.""" attestation = result or default_attestation_result() return { "ok": attestation.ok, @@ -810,7 +743,6 @@ def summarize_evidence( probe_results: Iterable[ProbeResult], attestation_result: AttestationResult | None = None, ) -> dict[str, Any]: - """Execute summarize evidence operation.""" commands = summarize_results(command_results) probes = summarize_probe_results(probe_results) attestation = summarize_attestation_result(attestation_result) @@ -836,7 +768,6 @@ def render_summary_markdown( probe_results: Iterable[ProbeResult], attestation_result: AttestationResult | None, ) -> str: - """Render output for summary markdown.""" commands = summary.get("commands", {}) probes = summary.get("probes", {}) attestation = attestation_result or default_attestation_result() @@ -903,11 +834,6 @@ def _summary_timing_row(label: str, summary: dict[str, Any]) -> str: def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser( description=( "Run repeatable mesh-llm stability checks and write manifest.json, " @@ -951,7 +877,6 @@ def inspect_release_attestation( public_key_file: str | None, expected_status: str | None, ) -> AttestationResult: - """Execute inspect release attestation operation.""" if not binary: return default_attestation_result() @@ -1007,7 +932,6 @@ def inspect_release_attestation( def default_base_url() -> str: - """Execute default base url operation.""" for name in ("MESH_STABILITY_BASE_URL", "MESH_AGENT_BASE_URL", "MESH_OPENCODE_BASE_URL"): value = os.environ.get(name) if value: @@ -1019,11 +943,6 @@ def default_base_url() -> str: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ try: args = parse_args() models = parse_models(args.models) @@ -1081,7 +1000,6 @@ def print_human_summary( probe_results: Iterable[ProbeResult], attestation_result: AttestationResult | None, ) -> None: - """Render output for human summary.""" print(f"nightly stability: {summary['passed']}/{summary['total']} steps passed", flush=True) print(f"results: {output_dir}", flush=True) attestation = attestation_result or default_attestation_result() @@ -1110,7 +1028,6 @@ def print_human_summary( def shell_join(command: Iterable[str]) -> str: - """Execute shell join operation.""" return " ".join(_shell_quote(part) for part in command) diff --git a/scripts/run-openai-guardrail-corpus.py b/scripts/run-openai-guardrail-corpus.py index 56dde86983..3212ad156e 100644 --- a/scripts/run-openai-guardrail-corpus.py +++ b/scripts/run-openai-guardrail-corpus.py @@ -27,7 +27,6 @@ @dataclass(frozen=True) class CorpusCase: - """Represents CorpusCase functionality.""" case_id: str category: str prompt: str @@ -67,7 +66,6 @@ class CorpusCase: def expected_server_mode(guardrail_mode: str) -> str: - """Execute expected server mode operation.""" return { "off": "disabled", "metrics": "metrics", @@ -76,11 +74,6 @@ def expected_server_mode(guardrail_mode: str) -> str: def build_corpus() -> list[CorpusCase]: - """Create corpus. - - Returns: - Created object. - """ return [ CorpusCase( case_id="streaming-pass-through", @@ -153,7 +146,6 @@ def build_corpus() -> list[CorpusCase]: def base_request(case: CorpusCase, *, model: str, guardrail_mode: str) -> dict[str, Any]: - """Execute base request operation.""" request = { "model": model, "messages": [{"role": "user", "content": case.prompt}], @@ -165,14 +157,12 @@ def base_request(case: CorpusCase, *, model: str, guardrail_mode: str) -> dict[s def fake_latency_ms(case_id: str, trial_index: int, guardrail_mode: str) -> float: - """Execute fake latency ms operation.""" digest = hashlib.sha256(f"{guardrail_mode}:{case_id}:{trial_index}".encode("utf-8")).digest() sample = int.from_bytes(digest[:2], "big") return 4.0 + (sample % 2400) / 100.0 def runtime_available(base_url: str) -> bool: - """Run runtime available operation.""" if base_url.startswith("fake://"): return False request = urllib.request.Request( @@ -188,7 +178,6 @@ def runtime_available(base_url: str) -> bool: def read_stream_text(response: Any) -> str: - """Execute read stream text operation.""" parts: list[str] = [] while True: line = response.readline() @@ -210,7 +199,6 @@ def read_stream_text(response: Any) -> str: def live_case_result(base_url: str, case: CorpusCase, request_body: dict[str, Any]) -> dict[str, Any]: - """Execute live case result operation.""" payload = json.dumps(request_body).encode("utf-8") url = f"{base_url.rstrip('/')}/chat/completions" req = urllib.request.Request( @@ -270,7 +258,6 @@ def live_case_result(base_url: str, case: CorpusCase, request_body: dict[str, An def fake_case_result(case: CorpusCase, trial_index: int, guardrail_mode: str) -> dict[str, Any]: - """Execute fake case result operation.""" ok = case.expected_outcome != "unsupported_real_tools_plus_strict_structured" latency_ms = fake_latency_ms(case.case_id, trial_index, guardrail_mode) return { @@ -282,13 +269,11 @@ def fake_case_result(case: CorpusCase, trial_index: int, guardrail_mode: str) -> def summarize_latencies(samples: list[float]) -> dict[str, float]: - """Execute summarize latencies operation.""" ordered = sorted(samples) if not ordered: return {"min": 0.0, "mean": 0.0, "p50": 0.0, "p95": 0.0, "max": 0.0} def percentile(index: float) -> float: - """Execute percentile operation.""" if len(ordered) == 1: return ordered[0] position = index * (len(ordered) - 1) @@ -307,7 +292,6 @@ def percentile(index: float) -> float: def run_corpus(base_url: str, model: str, guardrail_mode: str, trials: int) -> dict[str, Any]: - """Run corpus operation.""" corpus = build_corpus() live_mode = runtime_available(base_url) backend_mode = "live" if live_mode else "fake" @@ -382,11 +366,6 @@ def run_corpus(base_url: str, model: str, guardrail_mode: str, trials: int) -> d def main() -> None: - """Execute main program logic. - - Returns: - Exit code. - """ parser = argparse.ArgumentParser() parser.add_argument("--base-url", required=True) parser.add_argument("--model", required=True) diff --git a/scripts/safe-extract-tar.py b/scripts/safe-extract-tar.py old mode 100644 new mode 100755 index 48ebf1658b..52e38eb3e5 --- a/scripts/safe-extract-tar.py +++ b/scripts/safe-extract-tar.py @@ -20,7 +20,6 @@ def normalized_parts( label: str, allow_root: bool = False, ) -> tuple[str, ...]: - """Execute normalized parts operation.""" if not raw_name or "\x00" in raw_name or "\\" in raw_name: raise ValueError(f"unsafe {label}: {raw_name!r}") if raw_name.startswith("/") or WINDOWS_DRIVE.match(raw_name): @@ -36,18 +35,12 @@ def normalized_parts( def destination_path(root: Path, parts: tuple[str, ...]) -> Path: - """Execute destination path operation.""" return root.joinpath(*parts) def validate_members( archive: tarfile.TarFile, ) -> list[tuple[tarfile.TarInfo, tuple[str, ...]]]: - """Validate members. - - Raises: - ValidationError: If validation fails. - """ validated: list[tuple[tarfile.TarInfo, tuple[str, ...]]] = [] seen: set[tuple[str, ...]] = set() for member in archive.getmembers(): @@ -98,13 +91,11 @@ def validate_members( def apply_mode(path: Path, member: tarfile.TarInfo) -> None: - """Execute apply mode operation.""" if os.name != "nt": path.chmod(member.mode & 0o777) def safe_extract(archive_path: Path, destination: Path) -> None: - """Execute safe extract operation.""" destination.mkdir(parents=True, exist_ok=True) if destination.is_symlink(): raise ValueError( @@ -180,11 +171,6 @@ def safe_extract(archive_path: Path, destination: Path) -> None: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ parser = argparse.ArgumentParser() parser.add_argument("archive", type=Path) parser.add_argument("destination", type=Path) diff --git a/scripts/safe-extract-zip.py b/scripts/safe-extract-zip.py old mode 100644 new mode 100755 index 060895344f..1bfcc26c99 --- a/scripts/safe-extract-zip.py +++ b/scripts/safe-extract-zip.py @@ -18,7 +18,6 @@ @dataclass(frozen=True) class Entry: - """Represents Entry functionality.""" info: zipfile.ZipInfo parts: tuple[str, ...] kind: str @@ -27,12 +26,10 @@ class Entry: def fail(message: str) -> NoReturn: - """Execute fail operation.""" raise SystemExit(f"unsafe ZIP archive: {message}") def portable_parts(name: str, *, label: str) -> tuple[str, ...]: - """Execute portable parts operation.""" if ( not name or any(character in name for character in ("\0", "\r", "\n", "\t")) @@ -53,7 +50,6 @@ def portable_parts(name: str, *, label: str) -> tuple[str, ...]: def resolve_link(parts: tuple[str, ...], target: str) -> None: - """Execute resolve link operation.""" if ( not target or any(character in target for character in ("\0", "\r", "\n", "\t")) @@ -81,7 +77,6 @@ def classify( archive: zipfile.ZipFile, info: zipfile.ZipInfo, ) -> Entry: - """Execute classify operation.""" name = info.filename.rstrip("/") if info.is_dir() else info.filename parts = portable_parts(name, label="entry") mode = info.external_attr >> 16 @@ -102,7 +97,6 @@ def classify( def inspect_archive(archive: zipfile.ZipFile) -> list[Entry]: - """Execute inspect archive operation.""" entries = [classify(archive, info) for info in archive.infolist()] seen: set[tuple[str, ...]] = set() symlinks = {entry.parts for entry in entries if entry.kind == "symlink"} @@ -121,7 +115,6 @@ def inspect_archive(archive: zipfile.ZipFile) -> list[Entry]: def extract(archive_path: Path, destination: Path) -> None: - """Execute extract operation.""" if not archive_path.is_file(): fail(f"archive does not exist: {archive_path}") if destination.is_symlink(): @@ -157,11 +150,6 @@ def extract(archive_path: Path, destination: Path) -> None: def main() -> None: - """Execute main program logic. - - Returns: - Exit code. - """ if len(sys.argv) != 3: raise SystemExit( "usage: scripts/safe-extract-zip.py ARCHIVE.zip DESTINATION" diff --git a/scripts/select-native-runtime.py b/scripts/select-native-runtime.py index 3a466c1ce2..d52e899b54 100644 --- a/scripts/select-native-runtime.py +++ b/scripts/select-native-runtime.py @@ -13,7 +13,6 @@ def select_runtime( backend: str, cuda_major: str = "", ) -> Path: - """Execute select runtime operation.""" expected_kind = {"cuda-blackwell": "cuda", "hip": "rocm"}.get(backend, backend) matches = [] if root.is_dir(): @@ -39,11 +38,6 @@ def select_runtime( def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser() parser.add_argument("--root", type=Path, required=True) parser.add_argument("--os", required=True) @@ -54,11 +48,6 @@ def parse_args() -> argparse.Namespace: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args() print(select_runtime(args.root, args.os, args.arch, args.backend, args.cuda_major)) return 0 diff --git a/scripts/select-release-notes-base.py b/scripts/select-release-notes-base.py index 923ea9e2c4..627b470c01 100644 --- a/scripts/select-release-notes-base.py +++ b/scripts/select-release-notes-base.py @@ -18,12 +18,10 @@ def version_from_match(match: re.Match[str]) -> tuple[int, int, int]: - """Execute version from match operation.""" return tuple(int(match.group(name)) for name in ("major", "minor", "patch")) def select_release_notes_base(target: str, tags: Iterable[str]) -> str | None: - """Execute select release notes base operation.""" target_match = TARGET_TAG.fullmatch(target.strip()) if target_match is None: raise ValueError(f"invalid release tag: {target}") @@ -45,11 +43,6 @@ def select_release_notes_base(target: str, tags: Iterable[str]) -> str | None: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ if len(sys.argv) != 2: print( "usage: select-release-notes-base.py ", diff --git a/scripts/skippy-llama-parity.py b/scripts/skippy-llama-parity.py old mode 100644 new mode 100755 index 3679681cd7..d319a8f9ca --- a/scripts/skippy-llama-parity.py +++ b/scripts/skippy-llama-parity.py @@ -30,7 +30,6 @@ def repo_cache_dir(repo: str) -> Path: - """Execute repo cache dir operation.""" cache_root = os.environ.get("HF_HUB_CACHE") if cache_root: hub = Path(cache_root) @@ -42,17 +41,11 @@ def repo_cache_dir(repo: str) -> Path: def load_json(path: Path) -> dict[str, Any]: - """Load json from source. - - Returns: - Loaded data. - """ with path.open("r", encoding="utf-8") as handle: return json.load(handle) def run(args: list[str], *, cwd: Path | None = None, quiet: bool = False) -> str: - """Run run operation.""" proc = subprocess.run( args, cwd=str(cwd) if cwd else None, @@ -71,7 +64,6 @@ def run(args: list[str], *, cwd: Path | None = None, quiet: bool = False) -> str def pinned_llama_models(llama_src: Path | None) -> list[str]: - """Execute pinned llama models operation.""" if llama_src: models_dir = llama_src / "src/models" if not models_dir.is_dir(): @@ -110,7 +102,6 @@ def pinned_llama_models(llama_src: Path | None) -> list[str]: def candidate_index(manifest: dict[str, Any]) -> dict[str, list[dict[str, Any]]]: - """Execute candidate index operation.""" index: dict[str, list[dict[str, Any]]] = {} for candidate in manifest.get("candidates", []): index.setdefault(candidate["llama_model"], []).append(candidate) @@ -118,7 +109,6 @@ def candidate_index(manifest: dict[str, Any]) -> dict[str, list[dict[str, Any]]] def priority_lookup(manifest: dict[str, Any]) -> dict[tuple[str, str], str]: - """Execute priority lookup operation.""" priorities = manifest.get("support_priority", {}) lookup: dict[tuple[str, str], str] = {} for priority in ("p0", "p1", "p2"): @@ -131,7 +121,6 @@ def priority_lookup(manifest: dict[str, Any]) -> dict[tuple[str, str], str]: def row_priority(row: dict[str, Any], lookup: dict[tuple[str, str], str]) -> str: - """Execute row priority operation.""" return ( lookup.get(("family", str(row.get("family", "")))) or lookup.get(("llama_model", str(row.get("llama_model", "")))) @@ -143,7 +132,6 @@ def filter_priority( rows: list[dict[str, Any]], priorities: list[str] | None, ) -> list[dict[str, Any]]: - """Execute filter priority operation.""" if not priorities: return rows requested = {priority.lower() for priority in priorities} @@ -151,7 +139,6 @@ def filter_priority( def candidate_file_rank(path: Path) -> int: - """Execute candidate file rank operation.""" name = path.name.lower() if "mmproj" in name: return 3 @@ -162,7 +149,6 @@ def candidate_file_rank(path: Path) -> int: def resolve_candidate_file(candidate: dict[str, Any]) -> Path | None: - """Execute resolve candidate file operation.""" repo = candidate.get("repo") include = candidate.get("include", "*.gguf") if not repo: @@ -186,7 +172,6 @@ def resolve_candidate_file(candidate: dict[str, Any]) -> Path | None: def download_command(candidate: dict[str, Any]) -> str: - """Execute download command operation.""" repo = candidate.get("repo") include = candidate.get("include", "*.gguf") if not repo: @@ -199,52 +184,41 @@ def download_command(candidate: dict[str, Any]) -> str: class GgufReader: - """Represents GgufReader functionality.""" def __init__(self, path: Path): self.handle = path.open("rb") def close(self) -> None: - """Execute close operation.""" self.handle.close() def read(self, size: int) -> bytes: - """Execute read operation.""" data = self.handle.read(size) if len(data) != size: raise EOFError("short GGUF read") return data def u32(self) -> int: - """Execute u32 operation.""" return struct.unpack(" int: - """Execute u64 operation.""" return struct.unpack(" int: - """Execute i32 operation.""" return struct.unpack(" int: - """Execute i64 operation.""" return struct.unpack(" float: - """Execute f32 operation.""" return struct.unpack(" float: - """Execute f64 operation.""" return struct.unpack(" str: - """Execute string operation.""" length = self.u64() return self.read(length).decode("utf-8", errors="replace") def value(self, typ: int) -> Any: - """Execute value operation.""" if typ == 0: return self.read(1)[0] if typ == 1: @@ -277,7 +251,6 @@ def value(self, typ: int) -> Any: def gguf_metadata(path: Path) -> dict[str, Any]: - """Execute gguf metadata operation.""" reader = GgufReader(path) try: if reader.read(4) != b"GGUF": @@ -299,7 +272,6 @@ def gguf_metadata(path: Path) -> dict[str, Any]: def infer_model_shape(path: Path) -> tuple[int, int, str | None]: - """Execute infer model shape operation.""" metadata = gguf_metadata(path) arch = metadata.get("general.architecture") layer_count = None @@ -317,7 +289,6 @@ def infer_model_shape(path: Path) -> tuple[int, int, str | None]: def split_args(layer_count: int) -> tuple[int, str]: - """Execute split args operation.""" first = max(1, layer_count // 3) second = max(first + 1, (2 * layer_count) // 3) if second >= layer_count: @@ -329,7 +300,6 @@ def split_args(layer_count: int) -> tuple[int, str]: def default_stage_build_dir() -> str | None: - """Execute default stage build dir operation.""" if os.environ.get("LLAMA_STAGE_BUILD_DIR"): return os.environ["LLAMA_STAGE_BUILD_DIR"] llama_build_roots = ( @@ -351,7 +321,6 @@ def default_stage_build_dir() -> str | None: def inventory(args: argparse.Namespace) -> list[dict[str, Any]]: - """Execute inventory operation.""" manifest = load_json(args.manifest) candidates = candidate_index(manifest) priorities = priority_lookup(manifest) @@ -408,7 +377,6 @@ def inventory(args: argparse.Namespace) -> list[dict[str, Any]]: def print_table(rows: list[dict[str, Any]]) -> None: - """Render output for table.""" print("| priority | llama model | family | status | local | candidate/download |") print("| --- | --- | --- | --- | --- | --- |") for row in rows: @@ -422,11 +390,6 @@ def print_table(rows: list[dict[str, Any]]) -> None: def validate_inventory(rows: list[dict[str, Any]]) -> int: - """Validate inventory. - - Raises: - ValidationError: If validation fails. - """ failures = 0 missing = [row for row in rows if row.get("status") == "missing_candidate"] if missing: @@ -469,11 +432,6 @@ def validate_inventory(rows: list[dict[str, Any]]) -> int: def validate_stage_abi_allowlist() -> int: - """Validate stage abi allowlist. - - Raises: - ValidationError: If validation fails. - """ llama_src = ROOT / ".deps/llama.cpp/src" skippy_cpp = llama_src / "skippy.cpp" arch_cpp = llama_src / "llama-arch.cpp" @@ -482,7 +440,6 @@ def validate_stage_abi_allowlist() -> int: return 0 def normalized(name: str) -> str: - """Execute normalized operation.""" return name.replace("_", "").replace("-", "") arch_names: dict[str, str] = {} @@ -553,7 +510,6 @@ def normalized(name: str) -> str: def run_certifications(args: argparse.Namespace, rows: list[dict[str, Any]]) -> int: - """Run certifications operation.""" defaults = load_json(args.manifest).get("defaults", {}) statuses = set(args.status) if args.status else { "candidate", @@ -671,11 +627,6 @@ def run_certifications(args: argparse.Namespace, rows: list[dict[str, Any]]) -> def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST) parser.add_argument("--llama-src", type=Path) diff --git a/scripts/summarize-depot-registry-pulls.py b/scripts/summarize-depot-registry-pulls.py index 3fe8756fee..c3e366a1f4 100644 --- a/scripts/summarize-depot-registry-pulls.py +++ b/scripts/summarize-depot-registry-pulls.py @@ -13,11 +13,6 @@ def load_observations(root: Path) -> list[dict[str, object]]: - """Load observations from source. - - Returns: - Loaded data. - """ observations: list[dict[str, object]] = [] for path in sorted(root.rglob("*.json")): with path.open(encoding="utf-8") as handle: @@ -38,7 +33,6 @@ def load_observations(root: Path) -> list[dict[str, object]]: def summarize( observations: list[dict[str, object]], minimum_samples: int ) -> dict[str, object]: - """Execute summarize operation.""" by_source = { source: [item for item in observations if item["source"] == source] for source in SOURCES @@ -77,7 +71,6 @@ def summarize( def markdown(summary: dict[str, object]) -> str: - """Execute markdown operation.""" return "\n".join( ( "## Depot Registry pull-through result", @@ -100,11 +93,6 @@ def markdown(summary: dict[str, object]) -> str: def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser() parser.add_argument("observations", type=Path) parser.add_argument("--minimum-samples", type=int, default=5) @@ -115,11 +103,6 @@ def parse_args() -> argparse.Namespace: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args() result = summarize(load_observations(args.observations), args.minimum_samples) report = markdown(result) diff --git a/scripts/summarize-sccache-stats.py b/scripts/summarize-sccache-stats.py index 1498d14048..bede58d7b5 100644 --- a/scripts/summarize-sccache-stats.py +++ b/scripts/summarize-sccache-stats.py @@ -15,7 +15,6 @@ class SummaryError(RuntimeError): def hit_rate(value: str) -> float: - """Execute hit rate operation.""" try: parsed = float(value) except ValueError as error: @@ -30,11 +29,6 @@ def hit_rate(value: str) -> float: def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser( description=( "Aggregate cache hits and misses from downloaded " @@ -62,7 +56,6 @@ def parse_args() -> argparse.Namespace: def discover_evidence(paths: list[Path]) -> list[Path]: - """Execute discover evidence operation.""" evidence: set[Path] = set() for path in paths: if path.is_file(): @@ -81,7 +74,6 @@ def discover_evidence(paths: list[Path]) -> list[Path]: def sum_count_tree(value: Any, field: str) -> int: - """Execute sum count tree operation.""" if isinstance(value, bool): raise SummaryError(f"{field} contains a boolean") if isinstance(value, int): @@ -97,7 +89,6 @@ def sum_count_tree(value: Any, field: str) -> int: def read_count(path: Path, payload: Any, name: str) -> int: - """Execute read count operation.""" if not isinstance(payload, dict): raise SummaryError(f"{path}: JSON root must be an object") stats = payload.get("stats") @@ -113,7 +104,6 @@ def read_count(path: Path, payload: Any, name: str) -> int: def aggregate(paths: list[Path]) -> tuple[int, int]: - """Execute aggregate operation.""" hits = 0 misses = 0 for path in paths: @@ -127,7 +117,6 @@ def aggregate(paths: list[Path]) -> tuple[int, int]: def render_text(summary: dict[str, Any]) -> str: - """Render output for text.""" rate = summary["hit_rate"] rate_text = "n/a" if rate is None else f"{rate:.2%}" lines = [ @@ -145,11 +134,6 @@ def render_text(summary: dict[str, Any]) -> str: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ arguments = parse_args() try: evidence = discover_evidence(arguments.paths) diff --git a/scripts/validate-ci-lane-results.py b/scripts/validate-ci-lane-results.py index b770f376eb..9c629288c5 100644 --- a/scripts/validate-ci-lane-results.py +++ b/scripts/validate-ci-lane-results.py @@ -105,15 +105,6 @@ def _required_jobs(lane_plan: dict[str, Any]) -> set[str]: def validate(lane_plan: dict[str, Any], needs: dict[str, Any]) -> None: - """Validate that all planned jobs completed successfully and unplanned jobs were skipped. - - Args: - lane_plan: The CI lane plan containing required jobs and slices. - needs: The actual job results from the CI workflow. - - Raises: - LaneResultError: If validation fails due to job failures or unexpected results. - """ required = lane_plan.get("required") if not isinstance(required, bool): raise LaneResultError("lane plan required must be a boolean") @@ -136,11 +127,6 @@ def validate(lane_plan: dict[str, Any], needs: dict[str, Any]) -> None: def main() -> int: - """Parse arguments and validate CI lane results against the plan. - - Returns: - Exit code: 0 for success, 2 for validation errors. - """ parser = argparse.ArgumentParser() parser.add_argument("--lane-plan", required=True) parser.add_argument("--needs", required=True) diff --git a/scripts/validate-release-native-runtime-matrix.py b/scripts/validate-release-native-runtime-matrix.py old mode 100644 new mode 100755 index 11e7515188..2050b3e6d4 --- a/scripts/validate-release-native-runtime-matrix.py +++ b/scripts/validate-release-native-runtime-matrix.py @@ -23,28 +23,24 @@ @dataclass(frozen=True, order=True) class RuntimeTarget: - """Represents RuntimeTarget functionality.""" os: str arch: str backend: str cuda_major: int | None = None def label(self) -> str: - """Execute label operation.""" if self.backend == "cuda" and self.cuda_major is not None: return f"{self.os}/{self.arch}/cuda{self.cuda_major}" return f"{self.os}/{self.arch}/{self.backend}" def default_backend(os_name: str, arch: str) -> str: - """Execute default backend operation.""" if os_name == "macos" and arch == "aarch64": return "metal" return "cpu" def binary_target_from_asset(asset_name: str) -> RuntimeTarget | None: - """Execute binary target from asset operation.""" name = os.path.basename(asset_name) if not name.startswith("mesh-llm-"): return None @@ -64,7 +60,6 @@ def binary_target_from_asset(asset_name: str) -> RuntimeTarget | None: def target_from_suffix(os_name: str, arch: str, suffix: str) -> RuntimeTarget: - """Execute target from suffix operation.""" if suffix == "": return RuntimeTarget(os_name, arch, default_backend(os_name, arch)) if suffix.startswith("-cuda"): @@ -77,7 +72,6 @@ def target_from_suffix(os_name: str, arch: str, suffix: str) -> RuntimeTarget: def native_target_from_artifact(artifact: dict[str, Any]) -> RuntimeTarget | None: - """Execute native target from artifact operation.""" platform = artifact.get("platform") backend = artifact.get("backend") if not isinstance(platform, dict) or not isinstance(backend, dict): @@ -96,7 +90,6 @@ def native_target_from_artifact(artifact: dict[str, Any]) -> RuntimeTarget | Non def native_target_matches(required: RuntimeTarget, candidate: RuntimeTarget) -> bool: - """Execute native target matches operation.""" if (required.os, required.arch, required.backend) != ( candidate.os, candidate.arch, @@ -109,7 +102,6 @@ def native_target_matches(required: RuntimeTarget, candidate: RuntimeTarget) -> def target_from_label(label: str) -> RuntimeTarget: - """Execute target from label operation.""" parts = label.split("/") if len(parts) != 3: raise ValueError(f"expected target label as os/arch/backend, got {label!r}") @@ -121,7 +113,6 @@ def target_from_label(label: str) -> RuntimeTarget: def required_targets_from_assets(asset_names: list[str]) -> set[RuntimeTarget]: - """Execute required targets from assets operation.""" return { target for asset_name in asset_names @@ -134,7 +125,6 @@ def find_matrix_violations( manifest: dict[str, Any], required_targets: set[RuntimeTarget] | None = None, ) -> list[str]: - """Execute find matrix violations operation.""" if required_targets is None: required_targets = required_targets_from_assets(asset_names) native_targets = [ @@ -153,11 +143,6 @@ def find_matrix_violations( def parse_args(argv: list[str]) -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser( description="Validate release binary bundle targets against native-runtimes.json." ) @@ -177,11 +162,6 @@ def parse_args(argv: list[str]) -> argparse.Namespace: def main(argv: list[str]) -> int: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args(argv) if not args.required_target and not args.assets: print( diff --git a/scripts/verify-checksum-sidecar.py b/scripts/verify-checksum-sidecar.py old mode 100644 new mode 100755 index 1f28627f39..d304b9764f --- a/scripts/verify-checksum-sidecar.py +++ b/scripts/verify-checksum-sidecar.py @@ -15,7 +15,6 @@ def sha256_file(path: Path) -> str: - """Execute sha256 file operation.""" digest = hashlib.sha256() with path.open("rb") as handle: for chunk in iter(lambda: handle.read(1024 * 1024), b""): @@ -24,7 +23,6 @@ def sha256_file(path: Path) -> str: def verify(artifact: Path) -> None: - """Execute verify operation.""" sidecar = artifact.with_name(f"{artifact.name}.sha256") if not sidecar.is_file() or sidecar.stat().st_size == 0: raise ValueError( @@ -56,11 +54,6 @@ def verify(artifact: Path) -> None: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ parser = argparse.ArgumentParser() parser.add_argument("artifact", type=Path) args = parser.parse_args() diff --git a/scripts/verify-host-dependencies.py b/scripts/verify-host-dependencies.py index 0f28cb9072..9ee226059e 100644 --- a/scripts/verify-host-dependencies.py +++ b/scripts/verify-host-dependencies.py @@ -36,7 +36,6 @@ def binary_format(path: Path) -> str: - """Execute binary format operation.""" header = path.read_bytes()[:4] if header == b"\x7fELF": return "elf" @@ -55,20 +54,10 @@ def binary_format(path: Path) -> str: def parse_elf_imports(output: str) -> list[str]: - """Parse and validate elf imports. - - Returns: - Parsed result. - """ return sorted(set(re.findall(r"\(NEEDED\).*\[([^\]]+)\]", output))) def parse_macho_imports(output: str) -> list[str]: - """Parse and validate macho imports. - - Returns: - Parsed result. - """ imports = [] for line in output.splitlines(): if not line[:1].isspace(): @@ -80,11 +69,6 @@ def parse_macho_imports(output: str) -> list[str]: def parse_pe_imports(output: str) -> list[str]: - """Parse and validate pe imports. - - Returns: - Parsed result. - """ imports = [] for line in output.splitlines(): match = re.search(r"(?:DLL Name:|Name:)\s*(\S+\.dll)\b", line, re.IGNORECASE) @@ -94,7 +78,6 @@ def parse_pe_imports(output: str) -> list[str]: def inspect_dependencies(path: Path, format_name: str | None = None) -> tuple[str, list[str]]: - """Execute inspect dependencies operation.""" format_name = format_name or binary_format(path) if format_name == "elf": output = run_tool(("readelf", "-d", str(path))) @@ -114,14 +97,12 @@ def inspect_dependencies(path: Path, format_name: str | None = None) -> tuple[st def run_tool(command: tuple[str, ...]) -> str: - """Run tool operation.""" if shutil.which(command[0]) is None: raise RuntimeError(f"{command[0]} is required to inspect host dependencies") return subprocess.check_output(command, text=True, stderr=subprocess.STDOUT) def forbidden_imports(imports: list[str]) -> list[str]: - """Execute forbidden imports operation.""" return [ dependency for dependency in imports @@ -130,11 +111,6 @@ def forbidden_imports(imports: list[str]) -> list[str]: def parse_args(argv: list[str]) -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser() parser.add_argument("binary", type=Path) parser.add_argument("--format", choices=("elf", "macho", "pe")) @@ -143,11 +119,6 @@ def parse_args(argv: list[str]) -> argparse.Namespace: def main(argv: list[str]) -> int: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args(argv) try: format_name, imports = inspect_dependencies(args.binary, args.format) diff --git a/scripts/verify-static-abi-build-stamp.py b/scripts/verify-static-abi-build-stamp.py index 03e7c30cb4..0b981380f9 100644 --- a/scripts/verify-static-abi-build-stamp.py +++ b/scripts/verify-static-abi-build-stamp.py @@ -23,11 +23,6 @@ class StampError(RuntimeError): def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser() parser.add_argument("stamp", type=Path) parser.add_argument("--backend", required=True) @@ -39,11 +34,6 @@ def parse_args() -> argparse.Namespace: def parse_stamp(path: Path) -> tuple[dict[str, str], list[str]]: - """Parse and validate stamp. - - Returns: - Parsed result. - """ try: lines = path.read_text(encoding="utf-8").splitlines() except (OSError, UnicodeError) as error: @@ -78,7 +68,6 @@ def parse_stamp(path: Path) -> tuple[dict[str, str], list[str]]: def require_equal(fields: dict[str, str], name: str, expected: str) -> None: - """Execute require equal operation.""" actual = fields.get(name) if actual != expected: raise StampError( @@ -88,11 +77,6 @@ def require_equal(fields: dict[str, str], name: str, expected: str) -> None: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ arguments = parse_args() try: fields, cmake_arguments = parse_stamp(arguments.stamp) diff --git a/scripts/verify-swift-xcframework.py b/scripts/verify-swift-xcframework.py old mode 100644 new mode 100755 index 2e0c3aba72..679cac6bf5 --- a/scripts/verify-swift-xcframework.py +++ b/scripts/verify-swift-xcframework.py @@ -28,11 +28,6 @@ def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser( description=( "Verify an XCFramework's declared architectures, binary slices, " @@ -45,12 +40,10 @@ def parse_args() -> argparse.Namespace: def fail(message: str) -> None: - """Execute fail operation.""" raise ValueError(message) def require_safe_component(value: Any, field: str) -> str: - """Execute require safe component operation.""" if not isinstance(value, str) or not value: fail(f"XCFramework {field} must be a non-empty string") path = PurePosixPath(value) @@ -60,7 +53,6 @@ def require_safe_component(value: Any, field: str) -> str: def platform_key(library: dict[str, Any]) -> PlatformKey: - """Execute platform key operation.""" platform = library.get("SupportedPlatform") variant = library.get("SupportedPlatformVariant", "") if not isinstance(platform, str) or not platform: @@ -74,7 +66,6 @@ def declared_architectures( library: dict[str, Any], key: PlatformKey, ) -> frozenset[str]: - """Execute declared architectures operation.""" architectures = library.get("SupportedArchitectures") if not isinstance(architectures, list) or not architectures: fail(f"XCFramework slice {key!r} must declare SupportedArchitectures") @@ -93,7 +84,6 @@ def framework_path( xcframework: Path, library: dict[str, Any], ) -> Path: - """Execute framework path operation.""" identifier = require_safe_component( library.get("LibraryIdentifier"), "LibraryIdentifier", @@ -112,7 +102,6 @@ def framework_path( def framework_binary(framework: Path) -> Path: - """Execute framework binary operation.""" name = framework.stem binary = framework / name if not binary.exists() or not binary.is_file(): @@ -121,7 +110,6 @@ def framework_binary(framework: Path) -> Path: def verify_macos_layout(framework: Path) -> None: - """Execute verify macos layout operation.""" name = framework.stem expected_symlinks = { "Versions/Current": "A", @@ -151,7 +139,6 @@ def verify_macos_layout(framework: Path) -> None: def lipo_architectures(binary: Path) -> frozenset[str]: - """Execute lipo architectures operation.""" lipo = os.environ.get("LIPO", "lipo") try: result = subprocess.run( @@ -169,7 +156,6 @@ def lipo_architectures(binary: Path) -> frozenset[str]: def verify_xcframework(xcframework: Path, mode: str | None) -> None: - """Execute verify xcframework operation.""" info_path = xcframework / "Info.plist" if not xcframework.is_dir() or not info_path.is_file(): fail(f"XCFramework or Info.plist is missing: {xcframework}") @@ -224,11 +210,6 @@ def verify_xcframework(xcframework: Path, mode: str | None) -> None: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args() try: verify_xcframework(args.xcframework, args.mode) diff --git a/scripts/windows-native-runtime-deps.py b/scripts/windows-native-runtime-deps.py index 2d8e43f2ec..c33339aba6 100644 --- a/scripts/windows-native-runtime-deps.py +++ b/scripts/windows-native-runtime-deps.py @@ -71,7 +71,6 @@ def _cstring(data: bytes, offset: int) -> str: def imported_dlls(path: pathlib.Path) -> list[str]: - """Execute imported dlls operation.""" data = path.read_bytes() if data[:2] != b"MZ": raise PeFormatError(f"not a PE image: {path}") @@ -103,7 +102,6 @@ def imported_dlls(path: pathlib.Path) -> list[str]: sections.append((virtual_address, max(virtual_size, raw_size), raw_offset)) def rva_offset(rva: int) -> int: - """Execute rva offset operation.""" for virtual_address, size, raw_offset in sections: if virtual_address <= rva < virtual_address + size: return raw_offset + rva - virtual_address @@ -128,11 +126,6 @@ def rva_offset(rva: int) -> int: def is_host_dll(name: str) -> bool: - """Check if host dll. - - Returns: - True if condition is met. - """ normalized = name.casefold() return ( normalized in HOST_DLLS @@ -142,7 +135,6 @@ def is_host_dll(name: str) -> bool: def default_search_dirs() -> list[pathlib.Path]: - """Execute default search dirs operation.""" candidates: list[pathlib.Path] = [] for compiler in ("g++", "gcc"): compiler_path = shutil.which(compiler) @@ -188,7 +180,6 @@ def _packaged_dlls(lib_dir: pathlib.Path) -> dict[str, pathlib.Path]: def dependency_gaps( lib_dir: pathlib.Path, scan_dirs: list[pathlib.Path] | None = None ) -> dict[str, set[str]]: - """Execute dependency gaps operation.""" packaged = _packaged_dlls(lib_dir) gaps: dict[str, set[str]] = {} scan_dirs = scan_dirs or [lib_dir] @@ -213,7 +204,6 @@ def dependency_gaps( def collect_dependencies( lib_dir: pathlib.Path, search_dirs: list[pathlib.Path], scan_dirs: list[pathlib.Path] | None = None ) -> list[pathlib.Path]: - """Execute collect dependencies operation.""" search_index = _dll_index([lib_dir, *search_dirs, *default_search_dirs()]) copied: list[pathlib.Path] = [] while True: @@ -240,7 +230,6 @@ def collect_dependencies( def verify_dependencies(lib_dir: pathlib.Path, scan_dirs: list[pathlib.Path] | None = None) -> None: - """Execute verify dependencies operation.""" gaps = dependency_gaps(lib_dir, scan_dirs) if not gaps: return @@ -252,11 +241,6 @@ def verify_dependencies(lib_dir: pathlib.Path, scan_dirs: list[pathlib.Path] | N def parse_args() -> argparse.Namespace: - """Parse and validate args. - - Returns: - Parsed result. - """ parser = argparse.ArgumentParser(description=__doc__) subparsers = parser.add_subparsers(dest="command", required=True) collect = subparsers.add_parser("collect") @@ -270,11 +254,6 @@ def parse_args() -> argparse.Namespace: def main() -> int: - """Execute main program logic. - - Returns: - Exit code. - """ args = parse_args() try: if args.command == "collect": From af0b2ea384cc89b964d9674afd8d76e5cfb4d802 Mon Sep 17 00:00:00 2001 From: James Dumay Date: Wed, 26 Aug 2026 14:10:14 +1000 Subject: [PATCH 4/4] ci: use GitHub-hosted xcode-27 label for runner_macos_apple Address review: macos27 is not a runner label GitHub hosts; the Xcode 27 image is labeled xcode-27 (actions/runner-images#14404) and runs a macOS 26.5 host with the macOS 27 SDK. Keep the role semantic and document the toolchain-lane vs macOS-27-host distinction for #1444. Co-authored-by: Jian Yang --- .../skills/manage-ci/references/current-inventory.md | 11 +++++++++-- .github/actions/select-ci-runners/action.yml | 2 +- scripts/tests/test_ci_artifact_actions.py | 2 +- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/.agents/skills/manage-ci/references/current-inventory.md b/.agents/skills/manage-ci/references/current-inventory.md index a2a8de36ee..404cb69cd6 100644 --- a/.agents/skills/manage-ci/references/current-inventory.md +++ b/.agents/skills/manage-ci/references/current-inventory.md @@ -418,9 +418,16 @@ permission. ## Providers and variables GitHub-hosted labels are `ubuntu-24.04`, `ubuntu-24.04-arm`, `macos-15`, and -`windows-2022`. Central policy also exposes the Xcode 27-capable `macos27` +`windows-2022`. Central policy also exposes the GitHub-hosted `xcode-27` label as `runner_macos_apple` for the follow-on Apple-provider platform row; -this prerequisite does not route an existing row to it. Depot labels are +this prerequisite does not route an existing row to it. That image is an +Xcode 27 toolchain lane: today it runs a macOS 26.5 host with the macOS 27 +SDK (actions/runner-images#14404), so the output names the Xcode capability, +not a macOS 27 host OS. Rows that need an actual macOS 27 host must wait for +a host image (GitHub or Depot) that provides one — Depot's current +`depot-macos-26` tops out at macOS 26/Xcode 26.6. #1444 must assert +`sw_vers`, `xcodebuild -version`, and the selected SDK before doing work, and +decide compile-only vs test accordingly. Depot labels are selected only by `select-ci-runners`; no workflow accepts a raw provider label. Trusted main Linux requires `DEPOT_RUNNERS_ENABLED=true`. An exact same-repository PR revision may use the diff --git a/.github/actions/select-ci-runners/action.yml b/.github/actions/select-ci-runners/action.yml index adae293873..bee0d701a5 100644 --- a/.github/actions/select-ci-runners/action.yml +++ b/.github/actions/select-ci-runners/action.yml @@ -291,7 +291,7 @@ runs: runner_macos=macos-15 runner_windows=windows-2022 fi - runner_macos_apple=macos27 + runner_macos_apple=xcode-27 { echo "depot_enabled=$depot_enabled" diff --git a/scripts/tests/test_ci_artifact_actions.py b/scripts/tests/test_ci_artifact_actions.py index ac8d423ced..9d47341b4d 100644 --- a/scripts/tests/test_ci_artifact_actions.py +++ b/scripts/tests/test_ci_artifact_actions.py @@ -2257,7 +2257,7 @@ def test_runner_selection_uses_event_repository_and_ref_policy(self) -> None: else "windows-2022" ) self.assertEqual(outputs["runner_macos"], expected_macos) - self.assertEqual(outputs["runner_macos_apple"], "macos27") + self.assertEqual(outputs["runner_macos_apple"], "xcode-27") self.assertEqual(outputs["runner_windows"], expected_windows) untrusted_repository = self.run_runner_selector(