feat(python): parallelize checks across packages

Run (package × task) cross-product in parallel using ThreadPoolExecutor
and subprocesses. Key changes:

- Add scripts/task_runner.py with shared parallel execution engine
- Update run_tasks_in_packages_if_exists.py to accept multiple tasks
- Update run_tasks_in_changed_packages.py with --files flag and parallel support
- Add check-packages poe task (fmt+lint+pyright+mypy in parallel)
- Add prek-markdown-code-lint and prek-samples-check with change detection
- Split CI code quality workflow into parallel prek and mypy jobs
- Update DEV_SETUP.md to document new parallel behavior

Core package changes still trigger checks on all packages.

Author: eavanvalkenburg

.github/workflows/python-code-quality.yml

@@ -13,7 +13,7 @@ env:
 
 jobs:
   prek:
-    name: Checks
+    name: Prek Checks
     if: "!cancelled()"
     strategy:
       fail-fast: false
@@ -47,6 +47,33 @@ jobs:
         name: Run Prek Hooks
         with:
           extra-args: --cd python --all-files
+
+  mypy:
+    name: Mypy Checks
+    if: "!cancelled()"
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.14"]
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    defaults:
+      run:
+        working-directory: ./python
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Set up python and install the project
+        id: python-setup
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ matrix.python-version }}
+          os: ${{ runner.os }}
+        env:
+          UV_CACHE_DIR: /tmp/.uv-cache
       - name: Run Mypy
         env:
           GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref || github.base_ref || 'main' }}

python/DEV_SETUP.md

@@ -228,28 +228,28 @@ uv run poe prek-install
 
 ### Code Quality and Formatting
 
-Each of the following tasks are designed to run against both the main `agent-framework` package and the extension packages, ensuring consistent code quality across the project.
+Each of the following tasks run against both the main `agent-framework` package and the extension packages in parallel, ensuring consistent code quality across the project.
 
 #### `fmt` (format)
-Format code using ruff:
+Format code using ruff (runs in parallel across all packages):
 ```bash
 uv run poe fmt
 ```
 
 #### `lint`
-Run linting checks and fix issues:
+Run linting checks and fix issues (runs in parallel across all packages):
 ```bash
 uv run poe lint
 ```
 
 #### `pyright`
-Run Pyright type checking:
+Run Pyright type checking (runs in parallel across all packages):
 ```bash
 uv run poe pyright
 ```
 
 #### `mypy`
-Run MyPy type checking:
+Run MyPy type checking (runs in parallel across all packages):
 ```bash
 uv run poe mypy
 ```
@@ -270,16 +270,22 @@ uv run poe markdown-code-lint
 
 ### Comprehensive Checks
 
+#### `check-packages`
+Run all package-level quality checks (format, lint, pyright, mypy) in parallel across all packages. This runs the full cross-product of (package × check) concurrently:
+```bash
+uv run poe check-packages
+```
+
 #### `check`
-Run all quality checks (format, lint, pyright, mypy, test, markdown lint):
+Run all quality checks including package checks, samples, tests and markdown lint:
 ```bash
 uv run poe check
 ```
 
 ### Testing
 
 #### `test`
-Run unit tests with coverage by invoking the `test` task in each package sequentially:
+Run unit tests with coverage by invoking the `test` task in each package in parallel:
 ```bash
 uv run poe test
 ```
@@ -327,7 +333,7 @@ uv run poe publish
 
 ## Prek Hooks
 
-Prek hooks run automatically on commit and execute a subset of the checks on changed files only. You can also run all checks using prek directly:
+Prek hooks run automatically on commit and execute a subset of the checks on changed files only. Package-level checks (fmt, lint, pyright) run in parallel but only for packages with changed files. Markdown and sample checks are skipped when no relevant files were changed. If the `core` package is changed, all packages are checked. You can also run all checks using prek directly:
 
 ```bash
 uv run prek run -a

python/pyproject.toml

@@ -229,7 +229,8 @@ build-meta = "python -m flit build"
 build = ["build-packages", "build-meta"]
 publish = "uv publish"
 # combined checks
-check = ["fmt", "lint", "pyright", "mypy", "samples-lint", "samples-syntax", "test", "markdown-code-lint"]
+check-packages = "python scripts/run_tasks_in_packages_if_exists.py fmt lint pyright mypy"
+check = ["check-packages", "samples-lint", "samples-syntax", "test", "markdown-code-lint"]
 
 [tool.poe.tasks.all-tests-cov]
 cmd = """
@@ -279,7 +280,36 @@ sequence = [
 args = [{ name = "python", default = "3.13", options = ['-p', '--python'] }]
 
 [tool.poe.tasks.prek-pyright]
-cmd = "uv run python scripts/run_tasks_in_changed_packages.py pyright ${files}"
+cmd = "uv run python scripts/run_tasks_in_changed_packages.py pyright --files ${files}"
+args = [{ name = "files", default = ".", positional = true, multiple = true }]
+
+[tool.poe.tasks.prek-check-packages]
+cmd = "uv run python scripts/run_tasks_in_changed_packages.py fmt lint pyright --files ${files}"
+args = [{ name = "files", default = ".", positional = true, multiple = true }]
+
+[tool.poe.tasks.prek-markdown-code-lint]
+cmd = """uv run python scripts/check_md_code_blocks.py ${files} --no-glob
+    --exclude cookiecutter-agent-framework-lab --exclude tau2
+    --exclude packages/devui/frontend --exclude context_providers/azure_ai_search"""
+args = [{ name = "files", default = ".", positional = true, multiple = true }]
+
+[tool.poe.tasks.prek-samples-check]
+shell = """
+HAS_SAMPLES=false
+for f in ${files}; do
+    case "$f" in
+        samples/*) HAS_SAMPLES=true; break ;;
+    esac
+done
+if [ "$HAS_SAMPLES" = true ]; then
+    echo "Sample files changed, running samples checks..."
+    uv run ruff check samples --fix --exclude samples/autogen-migration,samples/semantic-kernel-migration --ignore E501,ASYNC,B901,TD002
+    uv run pyright -p pyrightconfig.samples.json --warnings
+else
+    echo "No sample files changed, skipping samples checks"
+fi
+"""
+interpreter = "bash"
 args = [{ name = "files", default = ".", positional = true, multiple = true }]
 
 
@@ -301,18 +331,15 @@ else
                     echo ".")
 fi
 echo "Changed files: $CHANGED_FILES"
-uv run python scripts/run_tasks_in_changed_packages.py mypy $CHANGED_FILES
+uv run python scripts/run_tasks_in_changed_packages.py mypy --files $CHANGED_FILES
 """
 interpreter = "bash"
 
 [tool.poe.tasks.prek-check]
 sequence = [
-    { ref = "fmt" },
-    { ref = "lint" },
-    { ref = "prek-pyright ${files}" },
-    { ref = "markdown-code-lint" },
-    { ref = "samples-lint" },
-    { ref = "samples-syntax" }
+    { ref = "prek-check-packages ${files}" },
+    { ref = "prek-markdown-code-lint ${files}" },
+    { ref = "prek-samples-check ${files}" }
 ]
 args = [{ name = "files", default = ".", positional = true, multiple = true }]
 

python/scripts/run_tasks_in_changed_packages.py

@@ -1,58 +1,12 @@
 # Copyright (c) Microsoft. All rights reserved.
 
-"""Run a task only in packages that have changed files."""
+"""Run task(s) only in packages that have changed files, in parallel by default."""
 
 import argparse
-import glob
-import sys
 from pathlib import Path
 
-import tomli
-from poethepoet.app import PoeThePoet
 from rich import print
-
-
-def discover_projects(workspace_pyproject_file: Path) -> list[Path]:
-    with workspace_pyproject_file.open("rb") as f:
-        data = tomli.load(f)
-
-    projects = data["tool"]["uv"]["workspace"]["members"]
-    exclude = data["tool"]["uv"]["workspace"].get("exclude", [])
-
-    all_projects: list[Path] = []
-    for project in projects:
-        if "*" in project:
-            globbed = glob.glob(str(project), root_dir=workspace_pyproject_file.parent)
-            globbed_paths = [Path(p) for p in globbed]
-            all_projects.extend(globbed_paths)
-        else:
-            all_projects.append(Path(project))
-
-    for project in exclude:
-        if "*" in project:
-            globbed = glob.glob(str(project), root_dir=workspace_pyproject_file.parent)
-            globbed_paths = [Path(p) for p in globbed]
-            all_projects = [p for p in all_projects if p not in globbed_paths]
-        else:
-            all_projects = [p for p in all_projects if p != Path(project)]
-
-    return all_projects
-
-
-def extract_poe_tasks(file: Path) -> set[str]:
-    with file.open("rb") as f:
-        data = tomli.load(f)
-
-    tasks = set(data.get("tool", {}).get("poe", {}).get("tasks", {}).keys())
-
-    # Check if there is an include too
-    include: str | None = data.get("tool", {}).get("poe", {}).get("include", None)
-    if include:
-        include_file = file.parent / include
-        if include_file.exists():
-            tasks = tasks.union(extract_poe_tasks(include_file))
-
-    return tasks
+from task_runner import build_work_items, discover_projects, run_tasks
 
 
 def get_changed_packages(projects: list[Path], changed_files: list[str], workspace_root: Path) -> set[Path]:
@@ -95,38 +49,32 @@ def get_changed_packages(projects: list[Path], changed_files: list[str], workspa
 
 
 def main() -> None:
-    parser = argparse.ArgumentParser(description="Run a task only in packages with changed files.")
-    parser.add_argument("task", help="The task name to run")
-    parser.add_argument("files", nargs="*", help="Changed files to determine which packages to run")
+    parser = argparse.ArgumentParser(description="Run task(s) in changed packages, in parallel by default.")
+    parser.add_argument("tasks", nargs="+", help="Task name(s) to run")
+    parser.add_argument("--files", nargs="*", default=None, help="Changed files to determine which packages to run")
+    parser.add_argument("--seq", action="store_true", help="Run sequentially instead of in parallel")
     args = parser.parse_args()
 
     pyproject_file = Path(__file__).parent.parent / "pyproject.toml"
     workspace_root = pyproject_file.parent
     projects = discover_projects(pyproject_file)
 
-    # If no files specified, run in all packages (default behavior)
+    # Determine which packages to check
     if not args.files or args.files == ["."]:
-        print(f"[yellow]No specific files provided, running {args.task} in all packages[/yellow]")
-        changed_packages = set(projects)
+        task_list = ", ".join(args.tasks)
+        print(f"[yellow]No specific files provided, running {task_list} in all packages[/yellow]")
+        target_packages = sorted(set(projects))
     else:
         changed_packages = get_changed_packages(projects, args.files, workspace_root)
         if changed_packages:
             print(f"[cyan]Detected changes in packages: {', '.join(str(p) for p in sorted(changed_packages))}[/cyan]")
         else:
-            print(f"[yellow]No changes detected in any package, skipping {args.task}[/yellow]")
+            print(f"[yellow]No changes detected in any package, skipping[/yellow]")
             return
+        target_packages = sorted(changed_packages)
 
-    # Run the task in changed packages
-    for project in sorted(changed_packages):
-        tasks = extract_poe_tasks(project / "pyproject.toml")
-        if args.task in tasks:
-            print(f"Running task {args.task} in {project}")
-            app = PoeThePoet(cwd=project)
-            result = app(cli_args=[args.task])
-            if result:
-                sys.exit(result)
-        else:
-            print(f"Task {args.task} not found in {project}")
+    work_items = build_work_items(target_packages, args.tasks)
+    run_tasks(work_items, workspace_root, sequential=args.seq)
 
 
 if __name__ == "__main__":

python/scripts/run_tasks_in_packages_if_exists.py

@@ -1,76 +1,28 @@
 # Copyright (c) Microsoft. All rights reserved.
 
-import glob
+"""Run poe task(s) across all workspace packages, in parallel by default."""
+
+import argparse
 import sys
 from pathlib import Path
 
-import tomli
-from poethepoet.app import PoeThePoet
-from rich import print
-
-
-def discover_projects(workspace_pyproject_file: Path) -> list[Path]:
-    with workspace_pyproject_file.open("rb") as f:
-        data = tomli.load(f)
-
-    projects = data["tool"]["uv"]["workspace"]["members"]
-    exclude = data["tool"]["uv"]["workspace"].get("exclude", [])
-
-    all_projects: list[Path] = []
-    for project in projects:
-        if "*" in project:
-            globbed = glob.glob(str(project), root_dir=workspace_pyproject_file.parent)
-            globbed_paths = [Path(p) for p in globbed]
-            all_projects.extend(globbed_paths)
-        else:
-            all_projects.append(Path(project))
-
-    for project in exclude:
-        if "*" in project:
-            globbed = glob.glob(str(project), root_dir=workspace_pyproject_file.parent)
-            globbed_paths = [Path(p) for p in globbed]
-            all_projects = [p for p in all_projects if p not in globbed_paths]
-        else:
-            all_projects = [p for p in all_projects if p != Path(project)]
-
-    return all_projects
-
-
-def extract_poe_tasks(file: Path) -> set[str]:
-    with file.open("rb") as f:
-        data = tomli.load(f)
-
-    tasks = set(data.get("tool", {}).get("poe", {}).get("tasks", {}).keys())
-
-    # Check if there is an include too
-    include: str | None = data.get("tool", {}).get("poe", {}).get("include", None)
-    if include:
-        include_file = file.parent / include
-        if include_file.exists():
-            tasks = tasks.union(extract_poe_tasks(include_file))
-
-    return tasks
+from task_runner import build_work_items, discover_projects, run_tasks
 
 
 def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Run poe task(s) across all workspace packages, in parallel by default."
+    )
+    parser.add_argument("tasks", nargs="+", help="Task name(s) to run across packages")
+    parser.add_argument("--seq", action="store_true", help="Run sequentially instead of in parallel")
+    args = parser.parse_args()
+
     pyproject_file = Path(__file__).parent.parent / "pyproject.toml"
+    workspace_root = pyproject_file.parent
     projects = discover_projects(pyproject_file)
 
-    if len(sys.argv) < 2:
-        print("Please provide a task name")
-        sys.exit(1)
-
-    task_name = sys.argv[1]
-    for project in projects:
-        tasks = extract_poe_tasks(project / "pyproject.toml")
-        if task_name in tasks:
-            print(f"Running task {task_name} in {project}")
-            app = PoeThePoet(cwd=project)
-            result = app(cli_args=sys.argv[1:])
-            if result:
-                sys.exit(result)
-        else:
-            print(f"Task {task_name} not found in {project}")
+    work_items = build_work_items(projects, args.tasks)
+    run_tasks(work_items, workspace_root, sequential=args.seq)
 
 
 if __name__ == "__main__":