Add inspection for missing KDocs in public API (#270)

Author: Ololoshechkin

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/AIAgent.kt

@@ -134,6 +134,12 @@ public open class AIAgent(
      *       This makes the API a bit stricter and clear.
      */
     public class FeatureContext internal constructor(private val agent: AIAgent) {
+        /**
+         * Installs and configures a feature into the current AI agent context.
+         *
+         * @param feature the feature to be added, defined by an implementation of [AIAgentFeature], which provides specific functionality
+         * @param configure an optional lambda to customize the configuration of the feature, where the provided [Config] can be modified
+         */
         public fun <Config : FeatureConfig, Feature : Any> install(
             feature: AIAgentFeature<Config, Feature>,
             configure: Config.() -> Unit = {}
@@ -209,6 +215,15 @@ public open class AIAgent(
         }
     }
 
+    /**
+     * Executes the AI agent using a builder to construct the textual input.
+     *
+     * This method allows for constructing a complex input by utilizing the functionalities
+     * of [TextContentBuilder]. The builder is applied to create the structured input which
+     * is then used to initiate the agent's execution.
+     *
+     * @param builder a lambda function applied to a [TextContentBuilder] instance to build the input text for the agent
+     */
     public suspend fun run(builder: suspend TextContentBuilder.() -> Unit) {
         run(agentInput = TextContentBuilder().apply { this.builder() }.build())
     }

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/AIAgentTool.kt

@@ -47,9 +47,21 @@ public class AIAgentTool(
     agentDescription: String,
     requestDescription: String = "Input for the task"
 ) : Tool<AgentToolArgs, AgentToolResult>() {
+    /**
+     * Represents the arguments required for the execution of an agent tool.
+     *
+     * @property request The input data or parameters needed for the agent tool to perform its operation.
+     */
     @Serializable
     public data class AgentToolArgs(val request: String) : Args
 
+    /**
+     * Represents the result of executing an agent tool operation.
+     *
+     * @property successful Indicates whether the operation was successful.
+     * @property errorMessage An optional error message describing the failure, if any.
+     * @property result An optional string representing the result produced by the tool operation.
+     */
     @Serializable
     public data class AgentToolResult(
         val successful: Boolean,
@@ -74,13 +86,13 @@ public class AIAgentTool(
     )
 
     override suspend fun execute(args: AgentToolArgs): AgentToolResult {
-        try {
-            return AgentToolResult(
+        return try {
+            AgentToolResult(
                 successful = true,
                 result = agent.runAndGetResult(args.request)
             )
         } catch (e: Throwable) {
-            return AgentToolResult(
+            AgentToolResult(
                 successful = false,
                 errorMessage = "Error happened: ${e::class.simpleName}(${e.message})\n" +
                         e.stackTraceToString().take(100)

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/config/AIAgentConfig.kt

@@ -26,8 +26,23 @@ public class AIAgentConfig(
     )
 ): AIAgentConfigBase {
 
+    /**
+     * Companion object for providing utility methods related to `AIAgentConfig`.
+     */
     public companion object {
 
+        /**
+         * Creates an AI agent configuration with a specified system prompt.
+         *
+         * This function initializes an instance of `AIAgentConfig` using the provided system-level prompt
+         * and other optional parameters, such as the language model, configuration ID, and maximum agent iterations.
+         *
+         * @param prompt The content of the system prompt to define the context and instructions for the AI agent.
+         * @param llm The Large Language Model (LLM) to be used for the AI agent. Defaults to OpenAIModels.Chat.GPT4o.
+         * @param id The identifier for the agent configuration. Defaults to "code-engine-agents".
+         * @param maxAgentIterations The maximum number of iterations the agent can perform to avoid infinite loops. Defaults to 3.
+         * @return An instance of `AIAgentConfigBase` representing the AI agent configuration with the specified parameters.
+         */
         public fun withSystemPrompt(
             prompt: String,
             llm: LLModel = OpenAIModels.Chat.GPT4o,

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/config/AIAgentConfigBase.kt

@@ -8,11 +8,44 @@ import ai.koog.prompt.llm.LLModel
  */
 public interface AIAgentConfigBase {
 
+    /**
+     * Defines the `Prompt` to be utilized in the AI agent's configuration.
+     *
+     * The `prompt` serves as the input structure for generating outputs from the language model and consists
+     * of a list of messages, a unique identifier, and optional parameters. This property plays a role
+     * in managing conversational state, input prompts, and configurations for the language model.
+     */
     public val prompt: Prompt
 
+    /**
+     * Specifies the Large Language Model (LLM) used by the AI agent for generating responses.
+     *
+     * The model defines configurations such as the specific LLM provider, its identifier,
+     * and supported capabilities (e.g., temperature control, tool usage). It plays a
+     * vital role in determining how the AI agent processes and generates outputs
+     * in response to user prompts and tasks.
+     */
     public val model: LLModel
 
+    /**
+     * Specifies the maximum number of iterations an AI agent is allowed to perform during its operation.
+     *
+     * This value acts as a safeguard to prevent infinite loops in scenarios where the agent's logic
+     * might otherwise continue indefinitely. It determines the number of steps the agent can take
+     * while executing its task, and exceeding this limit will halt the agent's processing.
+     */
     public val maxAgentIterations: Int
 
+    /**
+     * Strategy used to determine how tool calls, present in the prompt but lacking definitions,
+     * are handled during agent execution.
+     *
+     * This property provides a mechanism to convert or format missing tool call and result messages when they occur,
+     * typically due to differences in tool sets between steps or subgraphs while the same history is reused. This ensures
+     * the prompt remains consistent and readable for the model, even with undefined tools.
+     *
+     * The specific behavior is determined by the selected `MissingToolsConversionStrategy`, which may either replace
+     * all tool-related messages or only those corresponding to missing tool definitions.
+     */
     public val missingToolsConversionStrategy: MissingToolsConversionStrategy
 }

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/config/MissingToolsConversionStrategy.kt

@@ -14,8 +14,23 @@ import ai.koog.prompt.message.Message
  * @property format Formatter used to convert tool calls
  */
 public abstract class MissingToolsConversionStrategy(private val format: ToolCallDescriber) {
+    /**
+     * Converts a given [Prompt] by applying modifications based on the provided list of [ToolDescriptor].
+     *
+     * @param prompt The original [Prompt] to be converted.
+     * @param tools The list of [ToolDescriptor] used to modify or adapt the [Prompt].
+     * @return A new [Prompt] instance with applied changes based on the provided tools.
+     */
     public abstract fun convertPrompt(prompt: Prompt, tools: List<ToolDescriptor>): Prompt
 
+    /**
+     * Converts the given message by formatting specific types of tool-related messages
+     * (e.g., `Message.Tool.Call` and `Message.Tool.Result`) into descriptive messages.
+     * If the message is not a tool-related message, it remains unchanged.
+     *
+     * @param message The input message to be converted.
+     * @return The converted message, either modified if it's a tool-related message, or unchanged otherwise.
+     */
     public fun convertMessage(message: Message): Message {
         return when (message) {
             is Message.Tool.Call -> format.describeToolCall(message)

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/entity/AIAgentNode.kt

@@ -11,6 +11,11 @@ import ai.koog.agents.core.annotation.InternalAgentsApi
  * @param Output The type of output data this node produces.
  */
 public abstract class AIAgentNodeBase<Input, Output> internal constructor() {
+    /**
+     * The name of the AI agent node.
+     * This property serves as a unique identifier for the node within the strategy graph
+     * and is used to distinguish and reference nodes in the graph structure.
+     */
     public abstract val name: String
 
     /**
@@ -122,7 +127,24 @@ internal class AIAgentNode<Input, Output> internal constructor(
     override suspend fun execute(context: AIAgentContextBase, input: Input): Output = context.execute(input)
 }
 
+/**
+ * Represents the base node for starting a subgraph in an AI agent strategy graph.
+ * Derived from [AIAgentNodeBase], this node acts as an entry point for executing subgraphs
+ * identified by a unique name.
+ *
+ * @param Input The type of input data this node processes and produces as output.
+ */
 public open class StartAIAgentNodeBase<Input>() : AIAgentNodeBase<Input, Input>() {
+    /**
+     * The name of the subgraph associated with the AI agent's starting node.
+     *
+     * This property serves as an identifier or label for the subgraph, helping to distinguish
+     * and reference specific AI workflows or strategies. It can be null if no subgraph
+     * name has been assigned.
+     *
+     * Internal changes to this property are restricted to ensure controlled modification, as the setter
+     * is marked internal. Its value may influence how the AI agent node generates its unique name.
+     */
     public var subgraphName: String? = null
         internal set
 
@@ -131,7 +153,23 @@ public open class StartAIAgentNodeBase<Input>() : AIAgentNodeBase<Input, Input>(
     override suspend fun execute(context: AIAgentContextBase, input: Input): Input = input
 }
 
+/**
+ * Represents a specialized node within an AI agent strategy graph that marks the endpoint
+ * of a subgraph. This node serves as a "finish" node and directly passes its input
+ * to its output without modification, acting as an identity operation.
+ *
+ * @param Output The type of data this node processes and produces.
+ */
 public open class FinishAIAgentNodeBase<Output>() : AIAgentNodeBase<Output, Output>() {
+    /**
+     * Stores the name of the subgraph associated with the node.
+     *
+     * This variable is used to identify or tag subgraphs in AI agent strategies.
+     * If `subgraphName` is set, it will be integrated into the node's identity or behavior,
+     * such as forming a unique name for the node.
+     *
+     * This property is mutable within the internal scope, but read-only from external scopes.
+     */
     public var subgraphName: String? = null
         internal set
 

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/entity/AIAgentState.kt

@@ -17,6 +17,16 @@ internal class AIAgentState internal constructor(
     }
 }
 
+/**
+ * Manages the state of an AI agent by providing thread-safe access and mechanisms
+ * to update the internal state using a locking mechanism.
+ *
+ * This class ensures consistency across state modifications by using a mutual exclusion
+ * lock, allowing only one coroutine to access or modify the state at a time.
+ *
+ * @constructor Creates a new instance of AIAgentStateManager with the initial state,
+ * defaulting to a new `AIAgentState` if not provided.
+ */
 public class AIAgentStateManager internal constructor(
     private var state: AIAgentState = AIAgentState()
 ) {

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/entity/AIAgentStorage.kt

@@ -3,8 +3,22 @@ package ai.koog.agents.core.agent.entity
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 
+/**
+ * Represents a storage key used for identifying and accessing data associated with an AI agent.
+ *
+ * The generic type parameter [T] specifies the type of data associated with this key, ensuring
+ * type safety when storing and retrieving data in the context of an AI agent.
+ *
+ * @param name The string identifier that uniquely represents the storage key.
+ */
 public data class AIAgentStorageKey<T : Any>(val name: String)
 
+/**
+ * Creates a storage key for a specific type, allowing identification and retrieval of values associated with it.
+ *
+ * @param name The name of the storage key, used to uniquely identify it.
+ * @return A new instance of [AIAgentStorageKey] for the specified type.
+ */
 public inline fun <reified T : Any> createStorageKey(name: String): AIAgentStorageKey<T> = AIAgentStorageKey<T>(name)
 
 /**

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/agent/session/AIAgentLLMSession.kt

@@ -115,6 +115,17 @@ public sealed class AIAgentLLMSession(
         executeMultiple(prompt, tools).first()
 
 
+    /**
+     * Sends a request to the language model without utilizing any tools and returns the response.
+     *
+     * This method validates the session state before proceeding with the operation. If tool usage
+     * is disabled (i.e., the tools list is empty), the tool choice parameter will be set to null
+     * to ensure compatibility with the underlying LLM client's behavior. It then executes the request
+     * and retrieves the response from the LLM.
+     *
+     * @return The response message from the language model after executing the request, represented
+     *         as a [Message.Response] instance.
+     */
     public open suspend fun requestLLMWithoutTools(): Message.Response {
         validateSession()
         /*
@@ -128,6 +139,14 @@ public sealed class AIAgentLLMSession(
         return executeSingle(promptWithDisabledTools, tools)
     }
 
+    /**
+     * Sends a request to the language model that enforces the usage of tools and retrieves the response.
+     *
+     * This method updates the session's prompt configuration to mark tool usage as required before
+     * executing the request. Additionally, it ensures the session is active before proceeding.
+     *
+     * @return The response from the language model after executing the request with enforced tool usage.
+     */
     public open suspend fun requestLLMOnlyCallingTools(): Message.Response {
         validateSession()
         val promptWithOnlyCallingTools = prompt.withUpdatedParams {
@@ -136,6 +155,20 @@ public sealed class AIAgentLLMSession(
         return executeSingle(promptWithOnlyCallingTools, tools)
     }
 
+    /**
+     * Sends a request to the language model while enforcing the use of a specific tool,
+     * and returns the response.
+     *
+     * This method validates that the session is active and checks if the specified tool
+     * exists within the session's set of available tools. It updates the prompt configuration
+     * to enforce the selection of the specified tool before executing the request.
+     *
+     * @param tool The tool to be used for the request, represented by a [ToolDescriptor] instance.
+     *             This parameter ensures that the language model utilizes the specified tool
+     *             during the interaction.
+     * @return The response from the language model as a [Message.Response] instance after
+     *         processing the request with the enforced tool.
+     */
     public open suspend fun requestLLMForceOneTool(tool: ToolDescriptor): Message.Response {
         validateSession()
         check(tools.contains(tool)) { "Unable to force call to tool `${tool.name}` because it is not defined" }
@@ -145,6 +178,18 @@ public sealed class AIAgentLLMSession(
         return executeSingle(promptWithForcingOneTool, tools)
     }
 
+    /**
+     * Sends a request to the language model while enforcing the use of a specific tool, and returns the response.
+     *
+     * This method ensures the session is active and updates the prompt configuration to enforce the selection of the
+     * specified tool before executing the request. It uses the provided tool as a focus for the language model to process
+     * the interaction.
+     *
+     * @param tool The tool to be used for the request, represented as an instance of [Tool]. This parameter ensures
+     *             the specified tool is utilized during the LLM interaction.
+     * @return The response from the language model as a [Message.Response] instance after processing the request with the
+     *         enforced tool.
+     */
     public open suspend fun requestLLMForceOneTool(tool: Tool<*, *>): Message.Response {
         return requestLLMForceOneTool(tool.descriptor)
     }

agents/agents-core/src/commonMain/kotlin/ai/koog/agents/core/annotation/InternalAgentsApi.kt

@@ -1,4 +1,13 @@
 package ai.koog.agents.core.annotation
 
+/**
+ * Indicates that the annotated API is internal to agent-related implementations and not intended for public use.
+ *
+ * Classes, functions, or members marked with this annotation are part of the internal functionality of the AI agents infrastructure
+ * and are not guaranteed to maintain backwards compatibility. They are subject to change, removal, or modification without notice.
+ *
+ * This annotation is primarily used to signal to developers that the API is not designed for general application development
+ * and should only be used with caution in specialized scenarios, such as extending or modifying internal agent behavior.
+ */
 @RequiresOptIn
 public annotation class InternalAgentsApi