feat: generate TypedDict types for input-side models (#738)

## Summary

Adds `TypedDict` counterparts for input-side models so users passing
plain dicts to resource-client methods get full type-checker support
without importing Pydantic models.

- Generate TypedDicts alongside Pydantic models via a second
`datamodel-code-generator` pass (`--output-model-type typing.TypedDict`)
in `poe generate-models`.
- Split generated content into `_models_generated.py` /
`_typeddicts_generated.py`. Hand-written `_models.py` / `_typeddicts.py`
now only hold shapes not exposed by the OpenAPI spec (e.g.
`RequestInput`, `RequestInputDict`).
- Extend `scripts/postprocess_generated_models.py` to trim the TypedDict
file to input-relevant classes (plus transitive deps), rename them with
a `Dict` suffix, and add `@docs_group('Typed dicts')`.
- Widen resource-client input parameters (`actor`, `task`,
`task_collection`, `request_queue`) to accept `TypedDict |
PydanticModel` unions.
- Update `.rules.md` and `manual_regenerate_models.yaml` to reflect the
new layout.

Closes #666.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vdusek

.github/workflows/manual_regenerate_models.yaml

@@ -1,4 +1,4 @@
-# This workflow regenerates Pydantic models (src/apify_client/_models.py) from the OpenAPI spec.
+# This workflow regenerates Pydantic models and TypedDicts (src/apify_client/_{models,typeddicts}_generated.py) from the OpenAPI spec.
 #
 # It can be triggered in two ways:
 #   1. Automatically via workflow_dispatch from the apify-docs CI pipeline.
@@ -108,7 +108,7 @@ jobs:
         id: commit
         uses: EndBug/add-and-commit@v10
         with:
-          add: src/apify_client/_models.py
+          add: 'src/apify_client/_*_generated.py'
           author_name: apify-service-account
           author_email: apify-service-account@users.noreply.github.com
           message: ${{ env.TITLE }}
@@ -130,9 +130,9 @@ jobs:
           else
             if [[ -n "$DOCS_PR_NUMBER" ]]; then
               DOCS_PR_URL="https://github.com/apify/apify-docs/pull/${DOCS_PR_NUMBER}"
-              BODY="This PR updates the auto-generated Pydantic models based on OpenAPI specification changes in [apify-docs PR #${DOCS_PR_NUMBER}](${DOCS_PR_URL})."
+              BODY="This PR updates the auto-generated Pydantic models and TypedDicts based on OpenAPI specification changes in [apify-docs PR #${DOCS_PR_NUMBER}](${DOCS_PR_URL})."
             else
-              BODY="This PR updates the auto-generated Pydantic models from the [published OpenAPI specification](https://docs.apify.com/api/openapi.json)."
+              BODY="This PR updates the auto-generated Pydantic models and TypedDicts from the [published OpenAPI specification](https://docs.apify.com/api/openapi.json)."
             fi
 
             PR_URL=$(gh pr create \

.rules.md

@@ -19,7 +19,7 @@ uv run poe type-check               # Run ty type checker
 uv run poe unit-tests               # Run unit tests
 uv run poe check-docstrings         # Verify async docstrings match sync
 uv run poe fix-docstrings           # Auto-fix async docstrings
-uv run poe generate-models          # Regenerate _models.py from live OpenAPI spec
+uv run poe generate-models          # Regenerate _models_generated.py and _typeddicts_generated.py from live OpenAPI spec
 uv run poe generate-models-from-file <path>  # Regenerate from a local OpenAPI spec file
 
 # Run a single test
@@ -73,7 +73,7 @@ Docstrings are written on sync clients and **automatically copied** to async cli
 
 ### Data Models
 
-`src/apify_client/_models.py` is **auto-generated** — do not edit it manually.
+`src/apify_client/_models_generated.py` and `src/apify_client/_typeddicts_generated.py` are **auto-generated** — do not edit them manually. The hand-maintained `src/apify_client/_models.py` and `src/apify_client/_typeddicts.py` hold only shapes that are not exposed by the OpenAPI spec (or that need local logic); import generated types directly from the `_*_generated` modules.
 
 - Generated by `datamodel-code-generator` from the OpenAPI spec at `https://docs.apify.com/api/openapi.json` (config in `pyproject.toml` under `[tool.datamodel-codegen]`, aliases in `datamodel_codegen_aliases.json`)
 - After generation, `scripts/postprocess_generated_models.py` is run to apply additional fixes

docs/02_concepts/code/03_nested_async.py

@@ -1,5 +1,5 @@
 from apify_client import ApifyClientAsync
-from apify_client._models import ActorJobStatus
+from apify_client._models_generated import ActorJobStatus
 
 TOKEN = 'MY-APIFY-TOKEN'
 

docs/02_concepts/code/03_nested_sync.py

@@ -1,5 +1,5 @@
 from apify_client import ApifyClient
-from apify_client._models import ActorJobStatus
+from apify_client._models_generated import ActorJobStatus
 
 TOKEN = 'MY-APIFY-TOKEN'
 

docs/04_upgrading/upgrading_to_v3.mdx

@@ -55,7 +55,7 @@ run.status
 Models also use `populate_by_name=True`, which means you can use either the Python field name or the camelCase alias when **constructing** a model:
 
 ```python
-from apify_client._models import Run
+from apify_client._models_generated import Run
 
 # Both work when constructing models
 Run(default_dataset_id='abc')   # Python field name
@@ -86,7 +86,7 @@ rq_client.add_request({
 After (v3) — both forms are accepted:
 
 ```python
-from apify_client._types import RequestInput
+from apify_client._models import RequestInput
 
 # Option 1: dict (still works)
 rq_client.add_request({

pyproject.toml

@@ -152,7 +152,7 @@ indent-style = "space"
 "**/docs/03_guides/code/05_custom_http_client_{async,sync}.py" = [
     "ARG002", # Unused method argument
 ]
-"src/apify_client/_models.py" = [
+"src/apify_client/_*_generated.py" = [
     "D",      # Everything from the pydocstyle
     "E501",   # Line too long
     "ERA001", # Commented-out code
@@ -210,7 +210,7 @@ context = 7
 # https://koxudaxi.github.io/datamodel-code-generator/
 [tool.datamodel-codegen]
 input_file_type = "openapi"
-output = "src/apify_client/_models.py"
+output = "src/apify_client/_models_generated.py"
 target_python_version = "3.11"
 output_model_type = "pydantic_v2.BaseModel"
 use_schema_description = true
@@ -272,8 +272,22 @@ shell = "./build_api_reference.sh && corepack enable && yarn && uv run yarn star
 cwd = "website"
 
 [tool.poe.tasks.generate-models]
-shell = "uv run datamodel-codegen --url https://docs.apify.com/api/openapi.json && python scripts/postprocess_generated_models.py"
+shell = """
+uv run datamodel-codegen --url https://docs.apify.com/api/openapi.json \
+    && uv run datamodel-codegen --url https://docs.apify.com/api/openapi.json \
+        --output src/apify_client/_typeddicts_generated.py \
+        --output-model-type typing.TypedDict \
+        --no-use-closed-typed-dict \
+    && python scripts/postprocess_generated_models.py
+"""
 
 [tool.poe.tasks.generate-models-from-file]
-shell = "uv run datamodel-codegen --input $input_file && python scripts/postprocess_generated_models.py"
+shell = """
+uv run datamodel-codegen --input $input_file \
+    && uv run datamodel-codegen --input $input_file \
+        --output src/apify_client/_typeddicts_generated.py \
+        --output-model-type typing.TypedDict \
+        --no-use-closed-typed-dict \
+    && python scripts/postprocess_generated_models.py
+"""
 args = [{ name = "input-file", positional = true, required = true }]