Merge branch 'v1.16' into fix/4687-clean

Signed-off-by: Marc Duiker <[email protected]>

Author: marcduiker

daprdocs/content/en/developing-applications/building-blocks/conversation/conversation-overview.md

@@ -31,7 +31,7 @@ The following features are out-of-the-box for [all the supported conversation co
 
 ### Prompt caching
 
-Prompt caching improves performance by storing and reusing prompts repeated across API calls. Dapr keeps frequent prompts in a local cache for reuse with your app, reducing latency and cost by avoiding reprocessing for every request.
+The Conversation API includes a built-in caching mechanism (enabled by the cacheTTL parameter) that optimizes both performance and cost by storing previous model responses for faster delivery to repetitive requests. This is particularly valuable in scenarios where similar prompt patterns occur frequently. When caching is enabled, Dapr creates a deterministic hash of the prompt text and all configuration parameters, checks if a valid cached response exists for this hash within the time period (for example, 10 minutes), and returns the cached response immediately if found. If no match exists, Dapr makes the API call and stores the result. This eliminates external API calls, lowers latency, and avoids provider charges for repeated requests. The cache exists entirely within your runtime environment, with each Dapr sidecar maintaining its own local cache.
 
 ### Personally identifiable information (PII) obfuscation
 

daprdocs/content/en/developing-applications/building-blocks/conversation/howto-conversation-layer.md

@@ -56,7 +56,7 @@ spec:
 
 ## Connect the conversation client
 
-The following examples use an HTTP client to send a POST request to Dapr's sidecar HTTP endpoint. You can also use [the Dapr SDK client instead]({{% ref "#related-links" %}}).
+The following examples use the Dapr SDK client to interact with LLMs.
 
 {{< tabpane text=true >}}
 
@@ -83,7 +83,7 @@ var response = await conversationClient.ConverseAsync("conversation",
             DaprConversationRole.Generic)
     });
 
-Console.WriteLine("Received the following from the LLM:");
+Console.WriteLine("conversation output: ");
 foreach (var resp in response.Outputs)
 {
     Console.WriteLine($"\t{resp.Result}");
@@ -92,6 +92,77 @@ foreach (var resp in response.Outputs)
 
 {{% /tab %}}
 
+<!-- Java -->
+{{% tab "Java" %}}
+
+```java
+//dependencies
+import io.dapr.client.DaprClientBuilder;
+import io.dapr.client.DaprPreviewClient;
+import io.dapr.client.domain.ConversationInput;
+import io.dapr.client.domain.ConversationRequest;
+import io.dapr.client.domain.ConversationResponse;
+import reactor.core.publisher.Mono;
+
+import java.util.List;
+
+public class Conversation {
+
+    public static void main(String[] args) {
+        String prompt = "Please write a witty haiku about the Dapr distributed programming framework at dapr.io";
+
+        try (DaprPreviewClient client = new DaprClientBuilder().buildPreviewClient()) {
+            System.out.println("Input: " + prompt);
+
+            ConversationInput daprConversationInput = new ConversationInput(prompt);
+
+            // Component name is the name provided in the metadata block of the conversation.yaml file.
+            Mono<ConversationResponse> responseMono = client.converse(new ConversationRequest("echo",
+                    List.of(daprConversationInput))
+                    .setContextId("contextId")
+                    .setScrubPii(true).setTemperature(1.1d));
+            ConversationResponse response = responseMono.block();
+            System.out.printf("conversation output: %s", response.getConversationOutputs().get(0).getResult());
+        } catch (Exception e) {
+            throw new RuntimeException(e);
+        }
+    }
+}
+```
+
+{{% /tab %}}
+
+<!-- Python -->
+{{% tab "Python" %}}
+
+```python
+#dependencies
+from dapr.clients import DaprClient
+from dapr.clients.grpc._request import ConversationInput
+
+#code
+with DaprClient() as d:
+    inputs = [
+        ConversationInput(content="Please write a witty haiku about the Dapr distributed programming framework at dapr.io", role='user', scrub_pii=True),
+    ]
+
+    metadata = {
+        'model': 'modelname',
+        'key': 'authKey',
+        'cacheTTL': '10m',
+    }
+
+    response = d.converse_alpha1(
+        name='echo', inputs=inputs, temperature=0.7, context_id='chat-123', metadata=metadata
+    )
+
+    for output in response.outputs:
+        print(f'conversation output: {output.result}')
+```
+
+{{% /tab %}}
+
+
  <!-- Go -->
 {{% tab "Go" %}}
 
@@ -189,39 +260,58 @@ dapr run --app-id conversation --dapr-grpc-port 50001 --log-level debug --resour
 
 {{% /tab %}}
 
- <!-- Go -->
-{{% tab "Go" %}}
+
+{{% tab "Java" %}}
 
 ```bash
-dapr run --app-id conversation --dapr-grpc-port 50001 --log-level debug --resources-path ./config -- go run ./main.go
+
+dapr run --app-id conversation --dapr-grpc-port 50001 --log-level debug --resources-path ./config -- mvn spring-boot:run
 ```
 
-**Expected output**
+{{% /tab %}}
+
+
 
+{{% tab "Python" %}}
+
+```bash
+
+dapr run --app-id conversation --dapr-grpc-port 50001 --log-level debug --resources-path ./config -- python3 app.py
 ```
-  - '== APP == conversation output: Please write a witty haiku about the Dapr distributed programming framework at dapr.io'
+
+{{% /tab %}}
+
+
+ <!-- Go -->
+{{% tab "Go" %}}
+
+```bash
+dapr run --app-id conversation --dapr-grpc-port 50001 --log-level debug --resources-path ./config -- go run ./main.go
 ```
 
+
 {{% /tab %}}
 
+
+
  <!-- Rust -->
 {{% tab "Rust" %}}
 
 ```bash
 dapr run --app-id=conversation --resources-path ./config --dapr-grpc-port 3500 -- cargo run --example conversation
 ```
 
+{{% /tab %}}
+
+{{< /tabpane >}}
+
+
 **Expected output**
 
 ```
-  - 'conversation input: hello world'
-  - 'conversation output: hello world'
+  - '== APP == conversation output: Please write a witty haiku about the Dapr distributed programming framework at dapr.io'
 ```
 
-{{% /tab %}}
-
-{{< /tabpane >}}
-
 ## Advanced features
 
 The conversation API supports the following features:
@@ -230,9 +320,11 @@ The conversation API supports the following features:
 
 1. **PII scrubbing:** Allows for the obfuscation of data going in and out of the LLM.
 
+1. **Tool calling:** Allows LLMs to interact with external functions and APIs.
+
 To learn how to enable these features, see the [conversation API reference guide]({{% ref conversation_api %}}).
 
-## Related links
+## Conversation API examples in Dapr SDK repositories
 
 Try out the conversation API using the full examples provided in the supported SDK repos.
 
@@ -246,7 +338,23 @@ Try out the conversation API using the full examples provided in the supported S
 
 {{% /tab %}}
 
- <!-- Go -->
+
+<!-- Java -->
+{{% tab "Java" %}}
+
+[Dapr conversation example with the Java SDK](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/conversation)
+
+{{% /tab %}}
+
+
+<!-- Python -->
+{{% tab "Python" %}}
+
+[Dapr conversation example with the Python SDK](https://github.com/dapr/python-sdk/tree/main/examples/conversation)
+
+{{% /tab %}}
+
+<!-- Go -->
 {{% tab "Go" %}}
 
 [Dapr conversation example with the Go SDK](https://github.com/dapr/go-sdk/tree/main/examples/conversation)
@@ -264,6 +372,6 @@ Try out the conversation API using the full examples provided in the supported S
 
 
 ## Next steps
-
+- [Conversation quickstart]({{% ref conversation-quickstart %}})
 - [Conversation API reference guide]({{% ref conversation_api %}})
 - [Available conversation components]({{% ref supported-conversation %}})

daprdocs/content/en/developing-applications/building-blocks/state-management/howto-outbox.md

@@ -16,23 +16,72 @@ For example, you can use the outbox pattern to:
 
 With Dapr's outbox support, you can notify subscribers when an application's state is created or updated when calling Dapr's [transactions API]({{% ref "state_api.md#state-transactions" %}}).
 
-The diagram below is an overview of how the outbox feature works:
+The diagram below is an overview of how the outbox feature works at a high level:
 
 1) Service A saves/updates state to the state store using a transaction.
 2) A message is written to the broker under the same transaction. When the message is successfully delivered to the message broker, the transaction completes, ensuring the state and message are transacted together.
 3) The message broker delivers the message topic to any subscribers - in this case, Service B.
 
-<img src="/images/state-management-outbox.png" width=800 alt="Diagram showing the steps of the outbox pattern">
+<img src="/images/state-management-outbox.png" width=800 alt="Diagram showing the overview of outbox pattern">
 
+## How outbox works under the hood
+
+Dapr outbox processes requests in two flows: the user request flow and the background message flow. Together, they guarantee that state and events stay consistent.
+
+<img src="/images/state-management-outbox-steps.png" width=800 alt="Diagram showing the steps of the outbox pattern">
+
+This is the sequence of interactions:
+
+1. An application calls the Dapr State Management API to write state transactionally using the transactional methods.  
+   This is the entry point where business data, such as an order or profile update, is submitted for persistence.
+
+2. Dapr publishes an intent message with a unique transaction ID to an internal outbox topic.  
+   This durable record ensures the event intent exists before any database commit happens.
+
+3. The state and a transaction marker are written atomically in the same state store.  
+   Both the business data and the marker are committed in the same transaction, preventing partial writes.
+
+4. The application receives a success response after the transaction commits.  
+   At this point, the application can continue, knowing state is saved and the event intent is guaranteed.
+
+5. A background subscriber reads the intent message.  
+   When outbox is enabled, Dapr starts consumers that process the internal outbox topic.
+
+6. The subscriber verifies the transaction marker in the state store.  
+   This check confirms that the database commit was successful before publishing externally.
+
+7. Verified business event is published to the external pub/sub topic.  
+   The event is sent to the configured broker (Kafka, RabbitMQ, etc.) where other services can consume it.
+
+8. The marker is cleaned up (deleted) from the state store.  
+   This prevents unbounded growth in the database once the event has been successfully delivered.
+
+9. Message is acknowledged and removed from internal topic  
+   If publishing or cleanup fails, Dapr retries, ensuring reliable at-least-once delivery.
+  
 ## Requirements
 
-The outbox feature can be used with using any [transactional state store]({{% ref supported-state-stores %}}) supported by Dapr. All [pub/sub brokers]({{% ref supported-pubsub %}}) are supported with the outbox feature.
+1. The outbox feature requires a [transactional state store]({{% ref supported-state-stores %}}) supported by Dapr.  
+   [Learn more about the transactional methods you can use.]({{% ref "howto-get-save-state.md#perform-state-transactions" %}})
 
-[Learn more about the transactional methods you can use.]({{% ref "howto-get-save-state.md#perform-state-transactions" %}})
+2. Any [pub/sub broker]({{% ref supported-pubsub %}}) supported by Dapr can be used with the outbox feature.
 
-{{% alert title="Note" color="primary" %}} 
-Message brokers that work with the competing consumer pattern (for example, [Apache Kafka]({{% ref setup-apache-kafka%}})) are encouraged to reduce the chances of duplicate events.
-{{% /alert %}}
+   {{% alert title="Note" color="primary" %}}
+   Message brokers that support the competing consumer pattern (for example, [Apache Kafka]({{% ref setup-apache-kafka%}})) are recommended to reduce the chance of duplicate events.
+   {{% /alert %}}
+
+3. Internal outbox topic  
+   When outbox is enabled, Dapr creates an internal topic using the following naming convention: `{namespace}{appID}{topic}outbox`, where:
+
+   - `namespace`: the Dapr application namespace (if configured)
+   - `appID`: the Dapr application identifier
+   - `topic`: the value specified in the `outboxPublishTopic` metadata
+
+   This way each outbox topic is uniquely identified per application and external topic, preventing routing conflicts in multi-tenant environments.
+
+   {{% alert title="Note" color="primary" %}}
+   Ensure that the topic is created in advance, or Dapr has sufficient permissions to create the topic at startup time.
+   {{% /alert %}}
 
 ## Enable the outbox pattern
 
@@ -682,3 +731,7 @@ The `data` CloudEvent field is reserved for Dapr's use only, and is non-customiz
 Watch [this video for an overview of the outbox pattern](https://youtu.be/rTovKpG0rhY?t=1338):
 
 {{< youtube id=rTovKpG0rhY start=1338 >}}
+
+## Next Steps
+
+[How Dapr Outbox Eliminates Dual Writes in Distributed Applications](https://www.diagrid.io/blog/how-dapr-outbox-eliminates-dual-writes-in-distributed-applications)

daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-architecture.md

@@ -175,6 +175,20 @@ Similarly, if a state store imposes restrictions on the size of a batch transact
 Workflow state can be purged from a state store, including all its history.
 Each Dapr SDK exposes APIs for purging all metadata related to specific workflow instances.
 
+#### State store record count
+
+The number of records which are saved as history in the state store per workflow run is determined by its complexity or "shape". In other words, the number of activities, timers, sub-workflows etc.
+The following table shows a general guide to the number of records that are saved by different workflow tasks.
+This number may be larger or smaller depending on retries or concurrency.
+
+| Task type | Number of records saved |
+| ----------|-------------------------|
+| Start workflow | 5 records |
+| Call activity | 3 records |
+| Timer | 3 records |
+| Raise event | 3 records |
+| Start child workflow | 8 records |
+
 ## Workflow scalability
 
 Because Dapr Workflows are internally implemented using actors, Dapr Workflows have the same scalability characteristics as actors.

daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-overview.md

@@ -116,7 +116,9 @@ Want to skip the quickstarts? Not a problem. You can try out the workflow buildi
 
 ## Limitations
 
-- **State stores:** Due to underlying limitations in some database choices, more commonly NoSQL databases, you might run into limitations around storing internal states. For example, CosmosDB has a maximum single operation item limit of only 100 states in a single request.
+- **State stores:** You can only use state stores which support workflows, as [described here]({{% ref supported-state-stores %}}).
+- Azure Cosmos DB has [payload and workflow complexity limitations]({{% ref "setup-azure-cosmosdb.md#workflow-limitations" %}}).
+- AWS DynamoDB has [workflow complexity limitations]({{% ref "setup-azure-cosmosdb.md#workflow-limitations" %}}).
 
 ## Watch the demo
 

daprdocs/content/en/operations/configuration/increase-request-size.md

@@ -1,27 +1,29 @@
 ---
 type: docs
-title: "How-To: Handle large http body requests"
-linkTitle: "HTTP request body size"
+title: "How-To: Handle larger body requests"
+linkTitle: "Request body size"
 weight: 6000
 description: "Configure http requests that are bigger than 4 MB"
 ---
 
-By default, Dapr has a limit for the request body size, set to 4MB. You can change this by defining:
-- The `dapr.io/http-max-request-size` annotation, or
-- The `--dapr-http-max-request-size` flag.
+{{% alert title="Note" color="primary" %}}
+The existing flag/annotation`dapr-http-max-request-size` has been deprecated and updated to `max-body-size`.
+{{% /alert %}}
+
+By default, Dapr has a limit for the request body size, set to 4MB. You can change this for both HTTP and gRPC requests by defining:
+- The `dapr.io/max-body-size` annotation, or
+- The `--max-body-size` flag.
 
 {{< tabpane text=true >}}
 
 <!--self hosted-->
 {{% tab "Self-hosted" %}}
 
-When running in self-hosted mode, use the `--dapr-http-max-request-size` flag to configure Dapr to use non-default request body size:
+When running in self-hosted mode, use the `--max-body-size` flag to configure Dapr to use non-default request body size:
 
 ```bash
-dapr run --dapr-http-max-request-size 16 node app.js
+dapr run --max-body-size 16 node app.js
 ```
-This tells Dapr to set maximum request body size to `16` MB.
-
 {{% /tab %}}
 
 <!--kubernetes-->
@@ -50,14 +52,16 @@ spec:
         dapr.io/enabled: "true"
         dapr.io/app-id: "myapp"
         dapr.io/app-port: "8000"
-        dapr.io/http-max-request-size: "16"
+        dapr.io/max-body-size: "16"
 #...
 ```
 
 {{% /tab %}}
 
 {{< /tabpane >}}
 
+This tells Dapr to set the maximum request body size to `16` MB for both HTTP and gRPC requests.
+
 ## Related links
 
 [Dapr Kubernetes pod annotations spec]({{% ref arguments-annotations-overview.md %}})