Added annotations for retry for qos provider, and also properties, with nested for action names gh-1221

Signed-off-by: hayden.rear <hayden.rear@gmail.com>

Author: haydenrear

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/annotation/annotations.kt

@@ -17,6 +17,7 @@ package com.embabel.agent.api.annotation
 
 import com.embabel.agent.api.common.PlannerType
 import com.embabel.agent.core.IoBinding
+import com.embabel.agent.core.ActionRetryPolicy
 import com.embabel.common.core.types.Semver.Companion.DEFAULT_VERSION
 import com.embabel.common.core.types.ZeroToOne
 import org.springframework.core.annotation.AliasFor
@@ -57,6 +58,17 @@ annotation class EmbabelComponent(
  * to be turned into a Spring bean in case of an autodetected component. Use only if there's the likelihood of
  * conflict with the default bean name.
  * @param opaque Whether to hide the agent's actions and conditions
+ * @param actionRetryPolicy {@link com.embabel.agent.core.ActionRetryPolicy} for how to manage retries per action.
+ * Use actionRetryPolicyExpression to specify specific properties. You can override this per action in the {@link Action} annotation.
+ * @param actionRetryPolicyExpression An expression pointing to a set of properties for how to manage retries per action
+ * overriding these (these are the defaults if you do not specify):
+ *   max-attempts: int = 5
+ *   backoff-millis: long = 10000
+ *   backoff-multiplier: double = 5.0
+ *   backoff-maxInterval: long = 60000
+ *   idempotent: boolean = false
+ * example: ${agent.action-retry.default}
+ * You can override this per action in the {@link Action} annotation.
  */
 @Retention(AnnotationRetention.RUNTIME)
 @Target(
@@ -73,6 +85,8 @@ annotation class Agent(
     @get:AliasFor(annotation = Component::class, attribute = "value")
     val beanName: String = "",
     val opaque: Boolean = false,
+    val actionRetryPolicy: ActionRetryPolicy = ActionRetryPolicy.DEFAULT,
+    val actionRetryPolicyExpression: String = "",
 )
 
 /**
@@ -163,6 +177,18 @@ annotation class ToolGroup(
  * is freshly added, even when multiple parameters of various types are available.
  * Defaults to Unit::class (no trigger). A trigger is an **additional** precondition: it
  * must be satisfied in addition to any preconditions listed in [pre] and the action method's input parameters.
+ * @param actionRetryPolicy {@link com.embabel.agent.core.ActionRetryPolicy} for how to manage retries for this action.
+ * Use actionRetryPolicyExpression
+ * to specify specific properties.
+ * @param actionRetryPolicyExpression An expression pointing to a set of properties for how to manage retries for this
+ * action overriding these (these are the defaults if you do not specify):
+ *   max-attempts: int = 5
+ *   backoff-millis: long = 10000
+ *   backoff-multiplier: double = 5.0
+ *   backoff-maxInterval: long = 60000
+ *   idempotent: boolean = false
+ * example: ${agent.action-retry.default}
+ * These take precedence over specifying the default in the Agent annotation.
  */
 @Target(AnnotationTarget.FUNCTION)
 @Retention(AnnotationRetention.RUNTIME)
@@ -181,6 +207,8 @@ annotation class Action(
     val toolGroups: Array<String> = [],
     val toolGroupRequirements: Array<ToolGroup> = [],
     val trigger: KClass<*> = Unit::class,
+    val actionRetryPolicy: ActionRetryPolicy = ActionRetryPolicy.DEFAULT,
+    val actionRetryPolicyExpression: String = "",
 )
 
 /**

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/annotation/support/ActionMethodManager.kt

@@ -44,6 +44,8 @@ interface ActionMethodManager {
      */
     val argumentResolvers: List<ActionMethodArgumentResolver>
 
+    val actionQosProvider: ActionQosProvider
+
     /**
      * Create an Action from a method
      * @param method the method to create an action from

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/annotation/support/ActionQosPropertyProvider.kt

@@ -0,0 +1,63 @@
+/*
+ * Copyright 2024-2026 Embabel Pty Ltd.
+ *
+ * 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.
+ */
+package com.embabel.agent.api.annotation.support
+
+import com.embabel.agent.spi.config.spring.AgentPlatformProperties
+import org.slf4j.LoggerFactory
+import org.springframework.boot.context.properties.bind.Binder
+import org.springframework.core.env.Environment
+import org.springframework.stereotype.Component
+
+@Component
+class ActionQosPropertyProvider(val env: Environment? = null) {
+
+    private val logger = LoggerFactory.getLogger(ActionQosPropertyProvider::class.java)
+
+    private val propertiesBinder: Binder? by lazy(LazyThreadSafetyMode.PUBLICATION) {
+        env?.let (Binder::get)
+    }
+
+    fun getBound(expr: String): AgentPlatformProperties.ActionQosProperties.ActionProperties? {
+        if (expr.isBlank()) return null
+        val propertiesBinder = propertiesBinder ?: return null
+
+        val prefix = if (expr.startsWith("\${") && expr.endsWith("}")) {
+            expr.substring(2, expr.length - 1).trim()
+        } else {
+            expr
+        }
+
+        val prefixResolved = env.let {
+            if (it == null)
+                expr
+            else
+                resolvePrefix(it, prefix) ?: prefix
+        }
+
+        return propertiesBinder.bind(prefixResolved, AgentPlatformProperties.ActionQosProperties.ActionProperties::class.java)
+            ?.orElse(null)
+    }
+
+    private fun resolvePrefix(env: Environment, s: String): String? {
+        if (env.containsProperty(s)) {
+            return s
+        }
+
+        logger.info("Did not find prefix $s when resolving action properties.")
+        return null
+    }
+
+}

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/annotation/support/ActionQosProvider.kt

@@ -18,10 +18,16 @@ package com.embabel.agent.api.annotation.support
 import com.embabel.agent.core.ActionQos
 import java.lang.reflect.Method
 
+/**
+ * Provides {@link com.embabel.agent.core.ActionQos} for a method, typically derived from
+ * {@link com.embabel.agent.api.annotation.Action} and {@link com.embabel.agent.api.annotation.Agent} metadata.
+ */
 interface ActionQosProvider {
 
-    fun provideActionQos(method: Method,
-                         instance: Any): ActionQos {
+    fun provideActionQos(
+        method: Method,
+        instance: Any
+    ): ActionQos {
         return ActionQos()
     }
 

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/annotation/support/DefaultActionMethodManager.kt

@@ -48,7 +48,7 @@ import kotlin.reflect.jvm.kotlinFunction
 @Component
 internal class DefaultActionMethodManager(
     val nameGenerator: MethodDefinedOperationNameGenerator = MethodDefinedOperationNameGenerator(),
-    val actionQosProvider: ActionQosProvider = DefaultActionQosProvider(),
+    override val actionQosProvider: ActionQosProvider = DefaultActionQosProvider(),
     override val argumentResolvers: List<ActionMethodArgumentResolver> = listOf(
         ProcessContextArgumentResolver(),
         OperationContextArgumentResolver(),

embabel-agent-api/src/main/kotlin/com/embabel/agent/api/annotation/support/DefaultActionQosProvider.kt

@@ -15,14 +15,63 @@
  */
 package com.embabel.agent.api.annotation.support
 
+import com.embabel.agent.api.annotation.Action
+import com.embabel.agent.api.annotation.Agent
 import com.embabel.agent.core.ActionQos
+import com.embabel.agent.core.ActionRetryPolicy
+import com.embabel.agent.spi.config.spring.AgentPlatformProperties
+import org.springframework.stereotype.Component
 import java.lang.reflect.Method
 
-class DefaultActionQosProvider : ActionQosProvider {
+/**
+ * Default {@link com.embabel.agent.api.annotation.support.ActionQosProvider} implementation that resolves
+ * retry overrides from {@link com.embabel.agent.api.annotation.Agent} and {@link com.embabel.agent.api.annotation.Action},
+ * then maps them to {@link com.embabel.agent.core.ActionQos}.
+ */
+@Component
+class DefaultActionQosProvider(
+    val actionQosProperties: AgentPlatformProperties.ActionQosProperties = AgentPlatformProperties.ActionQosProperties(),
+    val propertyProvider: ActionQosPropertyProvider = ActionQosPropertyProvider(),
+) : ActionQosProvider {
+
     override fun provideActionQos(
         method: Method,
         instance: Any
     ): ActionQos {
-        return ActionQos()
+
+        var defaultActionQos = actionQosProperties.default
+
+        var props = instance.javaClass.getAnnotation(Agent::class.java)?.let {
+            if (hasRetryExpression(it.actionRetryPolicyExpression)) {
+                defaultActionQos = defaultActionQos
+                    .overridingNotNull(getBound(it.actionRetryPolicyExpression))
+            }
+
+            if (it.actionRetryPolicy == ActionRetryPolicy.FIRE_ONCE) {
+                defaultActionQos = defaultActionQos.copy(maxAttempts = 1)
+            }
+
+            defaultActionQos
+
+        } ?: defaultActionQos
+
+        method.getAnnotation(Action::class.java)?.let {
+            if (hasRetryExpression(it.actionRetryPolicyExpression)) {
+                props = props.overridingNotNull(getBound(it.actionRetryPolicyExpression))
+            }
+            if (it.actionRetryPolicy == ActionRetryPolicy.FIRE_ONCE) {
+                props = props.copy(maxAttempts = 1)
+            }
+        }
+
+
+        return props.toActionQos()
     }
+
+
+    fun getBound(expr: String): AgentPlatformProperties.ActionQosProperties.ActionProperties? {
+        return propertyProvider.getBound(expr)
+    }
+
+    private fun hasRetryExpression(expr: String): Boolean = expr.isNotBlank()
 }

embabel-agent-api/src/main/kotlin/com/embabel/agent/core/ActionRetryPolicy.kt

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2024-2026 Embabel Pty Ltd.
+ *
+ * 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.
+ */
+package com.embabel.agent.core
+
+/**
+ * Retry policy selector for an action.
+ *
+ * This is the first-priority override for retry behavior on an {@link com.embabel.agent.api.annotation.Action}
+ * or {@link com.embabel.agent.api.annotation.Agent}. The underlying policy maps to {@link ActionQos} with the
+ * following default properties:
+ * max-attempts: int = 5
+ * backoff-millis: long = 10000
+ * backoff-multiplier: double = 5.0
+ * backoff-maxInterval: long = 60000
+ * idempotent: boolean = false
+ * To override with a custom policy, see actionRetryPolicyExpression on {@link com.embabel.agent.api.annotation.Action}
+ * or {@link com.embabel.agent.api.annotation.Agent}.
+ */
+enum class ActionRetryPolicy {
+
+    /**
+     * Fire only once: maps to {@link ActionQos} with maxAttempts = 1.
+     */
+    FIRE_ONCE,
+
+    /**
+     * Default retry policy: uses the default {@link ActionQos}. Note that using this retry policy explicitly will not
+     * override any custom retry policy provided at any level, even if that custom retry policy is at a lower
+     * precedence than the one annotated with this retry policy.
+     */
+    DEFAULT
+
+}

embabel-agent-api/src/main/kotlin/com/embabel/agent/spi/config/spring/AgentPlatformProperties.kt

@@ -15,6 +15,7 @@
  */
 package com.embabel.agent.spi.config.spring
 
+import com.embabel.agent.core.ActionQos
 import org.springframework.boot.context.properties.ConfigurationProperties
 import org.springframework.boot.context.properties.NestedConfigurationProperty
 
@@ -67,6 +68,9 @@ class AgentPlatformProperties {
     @field:NestedConfigurationProperty
     var test: TestConfig = TestConfig()
 
+    @field:NestedConfigurationProperty
+    var actionQos: ActionQosProperties = ActionQosProperties()
+
     /**
      * Agent Process Type
      */
@@ -282,4 +286,58 @@ class AgentPlatformProperties {
          */
         var mockMode: Boolean = true
     }
+
+    /**
+     * Configuration of retry policy overrides for actions on agents.
+     *
+     * This allows configuring default and per-action overrides that map to {@link com.embabel.agent.core.ActionQos}.
+     */
+    @ConfigurationProperties(prefix = "embabel.agent.platform.action-qos")
+    class ActionQosProperties {
+
+        /**
+         * Overrides for a single action's QoS settings.
+         *
+         * Null values mean "use defaults" (either the configured defaults or {@link com.embabel.agent.core.ActionQos}).
+         */
+        data class ActionProperties(
+            var maxAttempts: Int? = null,
+            var backoffMillis: Long? = null,
+            var backoffMultiplier: Double? = null,
+            var backoffMaxInterval: Long? = null,
+            var idempotent: Boolean? = null,
+        ) {
+            fun overridingNotNull(overridingAction: ActionProperties?): ActionProperties {
+                if (overridingAction == null) {
+                    return this
+                }
+
+                return ActionProperties(
+                    maxAttempts = overridingAction.maxAttempts ?: this.maxAttempts,
+                    backoffMillis = overridingAction.backoffMillis ?: this.backoffMillis,
+                    backoffMultiplier = overridingAction.backoffMultiplier ?: backoffMultiplier,
+                    backoffMaxInterval = overridingAction.backoffMaxInterval ?: backoffMaxInterval,
+                    idempotent = overridingAction.idempotent ?: idempotent
+                )
+            }
+
+            fun toActionQos(defaultAction: ActionQos = ActionQos()): ActionQos {
+                return ActionQos(
+                    maxAttempts = maxAttempts ?: defaultAction.maxAttempts,
+                    backoffMillis = backoffMillis ?: defaultAction.backoffMillis,
+                    backoffMultiplier = backoffMultiplier ?: defaultAction.backoffMultiplier,
+                    backoffMaxInterval = backoffMaxInterval ?: defaultAction.backoffMaxInterval,
+                    idempotent = idempotent ?: defaultAction.idempotent
+                )
+            }
+        }
+
+        /**
+         * Fallback retry properties for {@code @Action} and {@code @Agent} overrides.
+         *
+         * These values are merged with {@link com.embabel.agent.core.ActionQos} defaults.
+         */
+        var default: ActionProperties = ActionProperties()
+
+    }
 }