chore: import upstream snapshot with attribution

2026-07-13 13:39:25 +08:00
commit db620d33df
5151 changed files with 925932 additions and 0 deletions
@@ -0,0 +1,135 @@
+---
+name: python-code-quality
+description: >
+  Code quality checks, linting, formatting, and type checking commands for the
+  Agent Framework Python codebase. Use this when running checks, fixing lint
+  errors, or troubleshooting CI failures.
+---
+
+# Python Code Quality
+
+## Quick Commands
+
+All commands run from the `python/` directory:
+
+```bash
+# Syntax formatting + checks (parallel across packages by default)
+uv run poe syntax
+uv run poe syntax -P core
+uv run poe syntax -F    # Format only
+uv run poe syntax -C    # Check only
+uv run poe syntax -S    # Samples only
+
+# Type checking
+#
+# Division of labor (see "Type checking architecture" below):
+#   - Pyright (strict) is the source-code type checker.
+#   - Pyright (relaxed `basic`), mypy, pyrefly, ty, zuban all check the TESTS;
+#     pyright/pyrefly/ty also check the SAMPLES (mypy/zuban skip script-style samples).
+uv run poe pyright       # Pyright (strict) over SOURCE, fan-out across packages
+uv run poe pyright -P core
+uv run poe pyright -A
+uv run poe test-typing   # mypy + pyrefly + ty + zuban + pyright over each package's TESTS
+uv run poe test-typing -P core
+uv run poe test-typing -S                       # samples (pyrefly + ty + pyright)
+uv run poe test-typing -P core --checker mypy   # narrow to one checker (repeatable)
+uv run poe test-typing -P core --checker pyright # relaxed pyright over the tests
+uv run poe mypy          # alias: MyPy over the tests only
+uv run poe mypy -P core
+uv run poe typing        # Pyright (source) + the tests checkers
+uv run poe typing -P core
+uv run poe typing -A
+
+# All package-level checks in parallel (syntax + pyright)
+uv run poe check-packages
+
+# Full check (packages + samples + tests + markdown)
+uv run poe check
+uv run poe check -P core
+
+# Samples only
+uv run poe check -S
+uv run poe pyright -S
+
+# Markdown code blocks
+uv run poe markdown-code-lint
+```
+
+## Pre-commit Hooks (prek)
+
+Prek hooks run automatically on commit. They stay lightweight and only check
+changed files.
+
+```bash
+# Install hooks
+uv run poe prek-install
+
+# Run all hooks manually
+uv run prek run -a
+
+# Run on last commit
+uv run prek run --last-commit
+```
+
+They run changed-package syntax formatting/checking, markdown code lint only
+when markdown files change, and sample syntax lint/pyright only when files
+under `samples/` change.
+They intentionally do not run workspace `pyright` or `mypy` by default.
+
+## Type checking architecture
+
+Following the "too many type checkers" approach, type checkers are split by target:
+
+| Target | Checker(s) | Mode | Config |
+|--------|-----------|------|--------|
+| Source (`agent_framework*`) | **pyright** | strict | `[tool.pyright]` in `pyproject.toml` |
+| Tests | pyright, mypy, pyrefly, ty, zuban | relaxed/basic | `pyrightconfig.tests.json`, `[tool.mypy]`, `pyrefly.toml`, `ty` rules |
+| Samples | pyright, pyrefly, ty | basic | `pyrightconfig.samples.json`, `pyrefly.samples.toml`, `ty.samples.toml` |
+
+- **Pyright is the only *strict* source-code checker**, and it ALSO runs in a relaxed
+  `basic` profile over the tests and samples (so the surfaces customers copy from are
+  validated by every checker, including pyright). MyPy was removed from source; its
+  `[tool.mypy]` block is now a *relaxed* profile used only for tests/samples.
+- The extra checkers run over tests/samples because those exercise the public API the way
+  users do. The profile is intentionally relaxed (private access allowed, untyped test
+  bodies allowed) so authors aren't forced into ugly over-annotation.
+- **Gating checkers** are `pyright`, `mypy`, `pyrefly`, `ty`, and `zuban` — all five run by
+  default and gate CI. `zuban` is the strictest of the mypy-compatible pair, so the same
+  `[tool.mypy]` config yields more findings; suppress zuban-only friction with shared
+  `# type: ignore[code]`. Suppress relaxed-pyright friction with `# pyright: ignore[rule]`.
+- **Samples** add `pyright` to `pyrefly` + `ty` — mypy/zuban can't resolve script-style
+  sample layouts (numeric-prefixed dirs, duplicate `main.py`), but pyright handles them.
+- The strict source-pyright (`[tool.pyright]`) enforces `reportUnnecessaryTypeIgnoreComment`
+  and excludes tests/samples; the relaxed test/sample pyright configs do not flag unnecessary
+  ignores.
+
+## Ruff Configuration
+
+- Line length: 120
+- Target: Python 3.10+
+- Auto-fix enabled
+- Rules: ASYNC, B, CPY, D, E, ERA, F, FIX, I, INP, ISC, Q, RET, RSE, RUF, SIM, T20, TD, W, T100, S
+- Scripts directory is excluded from checks
+
+## Pyright Configuration
+
+- **Source**: strict mode (`[tool.pyright]`), `reportUnnecessaryTypeIgnoreComment = "error"`,
+  excludes tests, samples, .venv, packages/devui/frontend.
+- **Tests**: relaxed `basic` profile (`pyrightconfig.tests.json`) — private import/usage and
+  not-required TypedDict access allowed; runs as the `pyright` checker in `test-typing`.
+- **Samples**: relaxed `basic` profile (`pyrightconfig.samples.json`, with a py310 variant) —
+  runs as the `pyright` checker in `test-typing -S`.
+
+## Parallel Execution
+
+The task runner (`scripts/task_runner.py`) executes the cross-product of
+(package × task) in parallel using ThreadPoolExecutor. Single items run
+in-process with streaming output.
+
+## CI Workflow
+
+CI splits into 4 parallel jobs:
+1. **Pre-commit hooks** — lightweight hooks (SKIP=poe-check)
+2. **Package checks** — syntax/pyright (source) via check-packages
+3. **Samples & markdown** — `check -S` plus `markdown-code-lint`
+4. **Test Typing** — change-detected mypy/pyrefly/ty over tests (`ci-test-typing`)