Merge branch 'main' into remove-deprecated-workflow-operations

Signed-off-by: Albert Callarisa <albert@diagrid.io>

Author: acroca

AGENTS.md

@@ -0,0 +1,233 @@
+# AGENTS.md — Dapr Python SDK
+
+This file provides context for AI agents working on the Dapr Python SDK.
+The project is the official Python SDK for [Dapr](https://dapr.io/) (Distributed Application Runtime),
+enabling Python developers to build distributed applications using Dapr building blocks.
+
+Repository: https://github.com/dapr/python-sdk
+License: Apache 2.0
+
+> **Deeper documentation lives alongside the code.** This root file gives you the big picture and
+> tells you where to look. Each extension and the examples directory has its own `AGENTS.md` with
+> detailed architecture, APIs, and patterns.
+
+## Project structure
+
+```
+dapr/                        # Core SDK package
+├── actor/                   # Actor framework (virtual actor model)
+├── aio/                     # Async I/O modules
+├── clients/                 # Dapr clients (gRPC and HTTP)
+├── common/                  # Shared utilities
+├── conf/                    # Configuration (settings, environment)
+├── proto/                   # Auto-generated gRPC protobuf stubs (DO NOT EDIT)
+├── serializers/             # JSON and pluggable serializers
+└── version/                 # Version metadata
+
+ext/                         # Extension packages (each is a separate PyPI package)
+├── dapr-ext-workflow/       # Workflow authoring  ← see ext/dapr-ext-workflow/AGENTS.md
+├── dapr-ext-grpc/           # gRPC App extension  ← see ext/dapr-ext-grpc/AGENTS.md
+├── dapr-ext-fastapi/        # FastAPI integration  ← see ext/dapr-ext-fastapi/AGENTS.md
+├── dapr-ext-langgraph/      # LangGraph checkpointer  ← see ext/dapr-ext-langgraph/AGENTS.md
+├── dapr-ext-strands/        # Strands agent sessions  ← see ext/dapr-ext-strands/AGENTS.md
+└── flask_dapr/              # Flask integration  ← see ext/flask_dapr/AGENTS.md
+
+tests/                       # Unit tests (mirrors dapr/ package structure)
+examples/                    # Integration test suite  ← see examples/AGENTS.md
+docs/                        # Sphinx documentation source
+tools/                       # Build and release scripts
+```
+
+## Key architectural patterns
+
+- **Namespace packages**: The `dapr` namespace is shared across the core SDK and extensions via `find_namespace_packages`. Extensions live in `ext/` but install into the `dapr.ext.*` namespace. Do not add `__init__.py` to namespace package roots in extensions.
+- **Client architecture**: `DaprGrpcClient` (primary, high-performance) and HTTP-based clients. Both implement shared interfaces.
+- **Actor model**: `Actor` base class, `ActorInterface` with `@actormethod` decorator, `ActorProxy`/`ActorProxyFactory` for client-side references, `ActorRuntime` for server-side hosting.
+- **Serialization**: Pluggable via `Serializer` base class. `DefaultJSONSerializer` is the default.
+- **Proto files**: Auto-generated from Dapr proto definitions. Never edit files under `dapr/proto/` directly.
+
+## Extension overview
+
+Each extension is a **separate PyPI package** with its own `setup.cfg`, `setup.py`, `tests/`, and `AGENTS.md`.
+
+| Extension | Package | Purpose | Active development |
+|-----------|---------|---------|-------------------|
+| `dapr-ext-workflow` | `dapr.ext.workflow` | Durable workflow orchestration via durabletask-dapr | **High** — major focus area |
+| `dapr-ext-grpc` | `dapr.ext.grpc` | gRPC server for Dapr callbacks (methods, pub/sub, bindings, jobs) | Moderate |
+| `dapr-ext-fastapi` | `dapr.ext.fastapi` | FastAPI integration for pub/sub and actors | Moderate |
+| `flask_dapr` | `flask_dapr` | Flask integration for pub/sub and actors | Low |
+| `dapr-ext-langgraph` | `dapr.ext.langgraph` | LangGraph checkpoint persistence to Dapr state store | Moderate |
+| `dapr-ext-strands` | `dapr.ext.strands` | Strands agent session management via Dapr state store | New |
+
+## Examples (integration test suite)
+
+The `examples/` directory serves as both user-facing documentation and the project's integration test suite. Examples are validated in CI using [mechanical-markdown](https://pypi.org/project/mechanical-markdown/), which executes bash code blocks from README files and asserts expected output.
+
+**See `examples/AGENTS.md`** for the full guide on example structure, validation, mechanical-markdown STEP blocks, and how to add new examples.
+
+Quick reference:
+```bash
+tox -e examples                          # Run all examples (needs Dapr runtime)
+tox -e example-component -- state_store  # Run a single example
+cd examples && ./validate.sh state_store # Run directly
+```
+
+## Python version support
+
+- **Minimum**: Python 3.10
+- **Tested**: 3.10, 3.11, 3.12, 3.13, 3.14
+- **Target version for tooling**: `py310` (ruff, mypy)
+
+## Development setup
+
+Install all packages in editable mode with dev dependencies:
+
+```bash
+pip install -r dev-requirements.txt \
+    -e . \
+    -e ext/dapr-ext-workflow/ \
+    -e ext/dapr-ext-grpc/ \
+    -e ext/dapr-ext-fastapi/ \
+    -e ext/dapr-ext-langgraph/ \
+    -e ext/dapr-ext-strands/ \
+    -e ext/flask_dapr/
+```
+
+## Running tests
+
+Tests use Python's built-in `unittest` framework with `coverage`. Run via tox:
+
+```bash
+# Run all unit tests (replace 311 with your Python version)
+tox -e py311
+
+# Run linting and formatting
+tox -e ruff
+
+# Run type checking
+tox -e type
+
+# Validate examples (requires Dapr runtime)
+tox -e examples
+```
+
+To run tests directly without tox:
+
+```bash
+# Core SDK tests
+python -m unittest discover -v ./tests
+
+# Extension tests (run each separately)
+python -m unittest discover -v ./ext/dapr-ext-workflow/tests
+python -m unittest discover -v ./ext/dapr-ext-grpc/tests
+python -m unittest discover -v ./ext/dapr-ext-fastapi/tests
+python -m unittest discover -v ./ext/dapr-ext-langgraph/tests
+python -m unittest discover -v ./ext/dapr-ext-strands/tests
+python -m unittest discover -v ./ext/flask_dapr/tests
+```
+
+## Code style and linting
+
+**Formatter/Linter**: Ruff (v0.14.1)
+
+Key rules:
+- **Line length**: 100 characters (E501 is currently ignored, but respect the 100-char target)
+- **Quote style**: Single quotes
+- **Import sorting**: isort-compatible (ruff `I` rules)
+- **Target**: Python 3.10
+- **Excluded from linting**: `.github/`, `dapr/proto/`
+
+Run formatting and lint fixes:
+
+```bash
+ruff check --fix
+ruff format
+```
+
+**Type checking**: MyPy
+
+```bash
+mypy --config-file mypy.ini
+```
+
+MyPy is configured to check: `dapr/actor/`, `dapr/clients/`, `dapr/conf/`, `dapr/serializers/`, `ext/dapr-ext-grpc/`, `ext/dapr-ext-fastapi/`, `ext/flask_dapr/`, and `examples/demo_actor/`. Proto stubs (`dapr.proto.*`) have errors ignored.
+
+## Commit and PR conventions
+
+- **DCO required**: Every commit must include a `Signed-off-by` line. Use `git commit -s` to add it automatically.
+- **CI checks**: Linting (ruff), unit tests (Python 3.10-3.14), type checking (mypy), and DCO verification run on all PRs.
+- **Branch targets**: PRs go to `main` or `release-*` branches.
+- **Tag-based releases**: Tags like `v*`, `workflow-v*`, `grpc-v*`, `fastapi-v*`, `flask-v*`, `langgraph-v*`, `strands-v*` trigger PyPI publishing for the corresponding package.
+
+## Agent task checklist
+
+When completing any task on this project, work through this checklist. Not every item applies to every change — use judgment — but always consider each one.
+
+### Before writing code
+
+- [ ] Read the relevant existing source files before making changes
+- [ ] Understand the existing patterns in the area you're modifying (naming, error handling, async vs sync)
+- [ ] Check if there's both a sync and async variant that needs updating (see `dapr/aio/` and extension `aio/` subdirectories)
+- [ ] Read the relevant extension's `AGENTS.md` for architecture and gotchas specific to that area
+
+### Implementation
+
+- [ ] Follow existing code style: single quotes, 100-char lines, Python 3.10+ syntax
+- [ ] Do not edit files under `dapr/proto/` — these are auto-generated
+- [ ] Do not add `__init__.py` files to namespace package roots in extensions
+
+### Unit tests
+
+- [ ] Add or update unit tests under `tests/` (core SDK) or `ext/*/tests/` (extensions)
+- [ ] Tests use `unittest` — follow the existing test patterns in the relevant directory
+- [ ] Verify tests pass: `python -m unittest discover -v ./tests` (or the relevant test directory)
+
+### Linting and type checking
+
+- [ ] Run `ruff check --fix && ruff format` and fix any remaining issues
+- [ ] Run `mypy --config-file mypy.ini` if you changed files covered by mypy (actor, clients, conf, serializers, ext-grpc, ext-fastapi, flask_dapr)
+
+### Examples (integration tests)
+
+- [ ] If you added a new user-facing feature or building block, add or update an example in `examples/`
+- [ ] Ensure the example README has `<!-- STEP -->` blocks with `expected_stdout_lines` so it is validated in CI
+- [ ] If you added a new example, register it in `tox.ini` under `[testenv:examples]`
+- [ ] If you changed output format of existing functionality, update `expected_stdout_lines` in affected example READMEs
+- [ ] See `examples/AGENTS.md` for full details on writing examples
+
+### Documentation
+
+- [ ] Update docstrings if you changed a public API's signature or behavior
+- [ ] Update the relevant example README if the usage pattern changed
+
+### Final verification
+
+- [ ] Run `tox -e ruff` — linting must be clean
+- [ ] Run `tox -e py311` (or your Python version) — all unit tests must pass
+- [ ] If you touched examples: `tox -e example-component -- <example-name>` to validate locally
+- [ ] Commits must be signed off for DCO: `git commit -s`
+
+## Important files
+
+| File | Purpose |
+|------|---------|
+| `setup.cfg` | Core package metadata and dependencies |
+| `setup.py` | Package build script (handles dev version suffixing) |
+| `pyproject.toml` | Ruff configuration |
+| `tox.ini` | Test environments and CI commands |
+| `mypy.ini` | Type checking configuration |
+| `dev-requirements.txt` | Development/test dependencies |
+| `dapr/version/__init__.py` | SDK version string |
+| `ext/*/setup.cfg` | Extension package metadata and dependencies |
+| `examples/validate.sh` | Entry point for mechanical-markdown example validation |
+
+## Gotchas
+
+- **Namespace packages**: Do not add `__init__.py` to the top-level `dapr/` directory in extensions — it will break namespace package resolution.
+- **Proto files**: Never manually edit anything under `dapr/proto/`. These are generated.
+- **Extension independence**: Each extension is a separate PyPI package. Core SDK changes should not break extensions; extension changes should not require core SDK changes unless intentional.
+- **DCO signoff**: PRs will be blocked by the DCO bot if commits lack `Signed-off-by`. Always use `git commit -s`.
+- **Ruff version pinned**: Dev requirements pin `ruff === 0.14.1`. Use this exact version to match CI.
+- **Examples are integration tests**: Changing output format (log messages, print statements) can break example validation. Always check `expected_stdout_lines` in example READMEs when modifying user-visible output.
+- **Background processes in examples**: Examples that start background services (servers, subscribers) must include a cleanup step to stop them, or CI will hang.
+- **Workflow is the most active area**: See `ext/dapr-ext-workflow/AGENTS.md` for workflow-specific architecture and constraints.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

dapr/aio/__init__.py

@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+
+"""
+Copyright 2026 The Dapr Authors
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""

dapr/aio/clients/__init__.py

@@ -103,7 +103,7 @@ async def invoke_method(
         self,
         app_id: str,
         method_name: str,
-        data: Union[bytes, str, GrpcMessage],
+        data: Union[bytes, str, GrpcMessage] = b'',
         content_type: Optional[str] = None,
         metadata: Optional[MetadataTuple] = None,
         http_verb: Optional[str] = None,

dapr/aio/clients/grpc/client.py

@@ -17,7 +17,7 @@
 import socket
 import time
 import uuid
-from typing import Any, Awaitable, Callable, Dict, List, Optional, Sequence, Text, Union
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Sequence, Text, Tuple, Union
 from urllib.parse import urlencode
 from warnings import warn
 
@@ -149,7 +149,7 @@ def __init__(
 
         useragent = f'dapr-sdk-python/{__version__}'
         if not max_grpc_message_length:
-            options = [
+            options: List[Tuple[str, Any]] = [
                 ('grpc.primary_user_agent', useragent),
             ]
         else:
@@ -200,7 +200,7 @@ def __init__(
 
     @staticmethod
     def get_credentials():
-        return grpc.ssl_channel_credentials()
+        return grpc.ssl_channel_credentials()  # type: ignore[attr-defined]
 
     async def close(self):
         """Closes Dapr runtime gRPC channel."""
@@ -599,7 +599,7 @@ async def subscribe_with_handler(
         self,
         pubsub_name: str,
         topic: str,
-        handler_fn: Callable[..., TopicEventResponse],
+        handler_fn: Callable[..., Awaitable[TopicEventResponse]],
         metadata: Optional[dict] = None,
         dead_letter_topic: Optional[str] = None,
     ) -> Callable[[], Awaitable[None]]:
@@ -1015,7 +1015,7 @@ async def execute_state_transaction(
                 operationType=o.operation_type.value,
                 request=common_v1.StateItem(
                     key=o.key,
-                    value=to_bytes(o.data),
+                    value=to_bytes(o.data) if o.data is not None else to_bytes(''),
                     etag=common_v1.Etag(value=o.etag) if o.etag is not None else None,
                 ),
             )
@@ -1355,7 +1355,7 @@ async def try_lock(
         response = await call
         return TryLockResponse(
             success=response.success,
-            client=self,
+            client=self,  # type: ignore[arg-type]
             store_name=store_name,
             resource_id=resource_id,
             lock_owner=lock_owner,

dapr/aio/clients/grpc/interceptors.py

@@ -92,9 +92,9 @@ async def _intercept_call(self, client_call_details: ClientCallDetails) -> Clien
             :class: `ClientCallDetails` modified call details
         """
 
-        metadata = []
+        metadata: List[Tuple[str, str]] = []
         if client_call_details.metadata is not None:
-            metadata = list(client_call_details.metadata)
+            metadata = list(client_call_details.metadata)  # type: ignore[arg-type]
         metadata.extend(self._metadata)
 
         new_call_details = _ClientCallDetailsAsync(

dapr/aio/clients/grpc/subscription.py

@@ -1,6 +1,6 @@
 import asyncio
 
-from grpc import StatusCode
+from grpc import StatusCode  # type: ignore[attr-defined]
 from grpc.aio import AioRpcError
 
 from dapr.aio.clients.health import DaprHealth
@@ -21,7 +21,7 @@ def __init__(self, stub, pubsub_name, topic, metadata=None, dead_letter_topic=No
         self._metadata = metadata or {}
         self._dead_letter_topic = dead_letter_topic or ''
         self._stream = None
-        self._send_queue = asyncio.Queue()
+        self._send_queue: asyncio.Queue[api_v1.SubscribeTopicEventsRequestAlpha1] = asyncio.Queue()
         self._stream_active = asyncio.Event()
 
     async def start(self):