ci: review pull requests against the API client, Crawlee and the JS SDK

.github/review-references.yaml

@@ -0,0 +1,26 @@
+# Cross-repository references for the apify-factory review (apify/ai-developer, `review-references`).
+version: 1
+
+instructions: |
+  This repository is the Apify SDK for Python, the library for building Actors in Python. It is built
+  on the Python API client and on Crawlee for Python, and it mirrors the Apify SDK for JavaScript. For
+  every behaviour the pull request adds or changes, check three things: that it uses the API client's
+  methods, models and exceptions as they are (the SDK defines none of its own), that it fits the
+  Crawlee interface it builds on, and that it matches what the JS SDK does for the same operation
+  (ignore differences caused by different language idioms and style). Back every finding with the
+  reference file and line; the review links them to the commit it read.
+
+references:
+  - repository: apify/apify-client-python
+    instructions: |
+      The API client this SDK calls. Compare every client call the pull request makes or changes with
+      the method it calls: parameters, defaults, return shape, exceptions.
+  - repository: apify/crawlee-python
+    instructions: |
+      The framework this SDK extends: configuration, storage clients and their models, storages, events,
+      request loaders, the service locator. Compare what the pull request implements or overrides with
+      the interface or base class it builds on.
+  - repository: apify/apify-sdk-js
+    instructions: |
+      The JS SDK this one mirrors. Compare the changed Python behaviour with its JS counterpart:
+      parameters and defaults, what it returns, and how it handles errors.

.github/workflows/factory_review.yaml

@@ -3,6 +3,9 @@ name: apify-factory review (AI review, and auto-approval)
 # Calls the apify-factory review and auto-approval pipeline (apify/ai-developer, wired up in
 # apify/workflows). Approvals additionally need the repository's `factory_auto_approve` custom
 # property set to true.
+#
+# `.github/review-references.yaml` names the repositories the reviewer compares a pull request with
+# (the Python API client, Crawlee for Python, the JS SDK); the pipeline reads it from the base branch.
 on:
   # Taken from the default branch, never from the pull request, so a pull request cannot rewrite
   # its own review pipeline. Pull request code is never checked out or executed.
@@ -25,6 +28,8 @@ jobs:
     # Paths never auto-approved here, on top of the pipeline's defaults. Proposed from the
     # repository's layout when this workflow was added; edit them like any other code.
     with:
+      # The draft of the cross-repository references, under evaluation. Back to `main` once it lands.
+      ai-developer-ref: claude/review-references
       policy: |
         {
           "denyGlobs": [

.rules.md

@@ -27,3 +27,7 @@ Don't introduce a shared Pydantic base model to centralize `model_config`. Each
 - **Events** — `ApifyEventManager` receives platform events over a WebSocket.
 - **Errors** — `apify.errors` only re-exports the exceptions from `apify_client.errors`; the SDK defines no error classes of its own, and API calls raise the client exceptions unchanged.
 - Response and data models (`Run`, pricing info, webhook representations) come from `apify-client`; the SDK doesn't define its own. The platform env-var enums (`ApifyEnvVars`, `ActorEnvVars`) live in `apify._consts`.
+
+### Additional context
+
+The code in this repository is based on and integrated with code from other repositories. The most important references are defined in [review references](./.github/review-references.yaml).