Post-review modifications to Planner agent docs

docs/docs/planner-agents.md

@@ -1,17 +1,36 @@
 # Planner agents
 
-Planner agents are AI agents that can plan and execute multi-step tasks through iterative planning cycles. 
-They continuously build or update plans, execute steps, and check if goals have been achieved.
+Planner agents are AI agents that can plan and execute multistep tasks through iterative planning cycles. 
+They continuously build or update plans, execute steps, and check completion criteria against the current state.
 
-Planner agents are suitable for complex tasks that require breaking down a high-level goal into smaller, actionable steps, and adapting the plan based on the results of each step.
+Planner agents are suitable for complex tasks
+that require breaking down a high-level goal into smaller, actionable steps
+and adapting the plan based on the results of each step.
+
+Planner agents operate through an iterative planning cycle:
+
+1. The planner creates or updates a plan based on the current state.
+2. The planner executes a single step from the plan, updating the state.
+3. The planner determines whether the plan is completed according to the current state.
+    - If the plan is completed, the cycle ends.
+    - If the plan is not completed, the cycle repeats from the first step.
+
+```mermaid
+graph LR
+  A[Create or update plan] --> B["Execute step and update state"]
+  B --> C["Check completion"]
+  C -->|Completed| D[[Done]]
+  C -->|"Not completed"| A
+```
 
 ## Prerequisites
 
 Before you start, make sure that you have the following:
 
 - A working Kotlin/JVM project.
 - Java 17+ installed.
-- A valid API key from the LLM provider used to implement an AI agent. For a list of all available providers, refer to [LLM providers](llm-providers.md).
+- A valid API key from the LLM provider that you use to implement an AI agent. For a list of all available providers, 
+see [LLM providers](llm-providers.md).
 
 !!! tip
     Use environment variables or a secure configuration management system to store your API keys.
@@ -23,29 +42,30 @@ To use planner agents, include the following dependencies in your build configur
 
 ```
 dependencies {
-    implementation("ai.koog:koog-agents:$koog_version")
-    implementation("ai.koog.agents:agents-planner:$koog_version")
-    // Include Ktor client dependency explicitly
-    implementation("io.ktor:ktor-client-cio:$ktor_version")
+    implementation("ai.koog:koog-agents:VERSION")
 }
 ```
 
 For all available installation methods, see [Install Koog](getting-started.md#install-koog).
 
-## How planner agents work
+## Simple LLM-based planners
 
-Planner agents operate through an iterative planning cycle:
+Simple LLM-based planners use LLMs to generate and evaluate plans. 
+They operate on a string-based state and execute steps through LLM requests.
+String-based state means that the agent state is noted as a single string,
+where the agent accepts an initial state string and returns the final state string as the result.
 
-1. **Build a plan**: The planner creates or updates a plan based on the current state
-2. **Execute a step**: The planner executes a single step from the plan, updating the state
-3. **Check completion**: The planner determines if the goal has been achieved by checking the state against the goal condition
-4. **Repeat**: If the goal is not achieved, the cycle repeats from step 1
+Koog provides two simple planners: 
 
-## Simple LLM-based planners
+- [SimpleLLMPlanner](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.llm/-simple-l-l-m-planner/index.html)
+    generates a plan only once at the very beginning and then follows the plan until it is completed. 
+    To include replanning, extend `SimpleLLMPlanner` and override the `assessPlan` method,
+    indicating when the agent should replan.
+- [SimpleLLMWithCriticPlanner](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.llm/-simple-l-l-m-with-critic-planner/index.html)
+    implements the `assessPlan` method that uses an LLM.
+    The method checks the validity of the plan via an LLM request and assesses whether the agent should replan.
 
-Simple LLM-based planners use LLMs to generate and evaluate plans. 
-They operate on a string state, i.e., just a single `String`, and execute steps through LLM requests.
-Out-of-the-box, Koog provides two simple planners: `SimpleLLMPlanner` and `SimpleLLMWithCriticPlanner`:
+The following example shows how to create a simple planner agent using `SimpleLLMPlanner`:
 
 <!--- INCLUDE
 import ai.koog.agents.core.agent.config.AIAgentConfig
@@ -56,11 +76,6 @@ import ai.koog.prompt.dsl.prompt
 import ai.koog.prompt.executor.clients.openai.OpenAIModels
 import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
 import kotlinx.coroutines.runBlocking
-
-suspend fun main() {
--->
-<!--- SUFFIX
-}
 -->
 ```kotlin
 // Create the planner
@@ -88,39 +103,46 @@ val agent = PlannerAIAgent(
     agentConfig = agentConfig
 )
 
-// Run the agent with a task
-val result = agent.run("Create a plan to organize a team meeting")
-println(result)
+suspend fun main() {
+    // Run the agent with a task
+    val result = agent.run("Create a plan to organize a team meeting")
+    println(result)
+}
 ```
 <!--- KNIT example-planner-01.kt -->
 
 
 ## GOAP (Goal-Oriented Action Planning)
 
-GOAP is an algorithmic planning approach that uses A* search to find optimal action sequences.
-Instead of using an LLM to generate plans, GOAP automatically discovers action sequences based on predefined goals and actions.
-
-### Key concepts
+GOAP is an algorithmic planning approach that uses [A* search](https://en.wikipedia.org/wiki/A*_search_algorithm) to find optimal action sequences.
+Instead of using an LLM to generate plans,
+a GOAP agent automatically discovers action sequences based on predefined goals and actions.
+In Koog, GOAP is implemented through a DSL that lets you define goals and actions declaratively.
 
 GOAP planners work with three main concepts:
 
-- **State**: Represents the current state of the world
-- **Actions**: Define what can be done, including preconditions, effects (beliefs), costs, and execution logic
-- **Goals**: Define target conditions, heuristic costs, and value functions
+- **State**: Represents the current state of the world.
+- **Actions**: Define what can be done, including preconditions, effects (beliefs), costs, and execution logic.
+- **Goals**: Define target conditions, heuristic costs, and value functions.
 
-The planner uses A* search to find the sequence of actions that satisfies the goal condition while minimizing total cost.
-
-### Creating a GOAP agent
+A GOAP planner uses A* search to find the sequence of actions that satisfies the goal condition while minimizing total cost.
 
 To create a GOAP agent, you need to:
 
-1. Define your state type
-2. Define actions with preconditions and effects
-3. Define goals with completion conditions
-4. Create the GOAP planner using the DSL
-5. Wrap it in a planner strategy and agent
+1. Define the state as a data class with properties representing various aspects specific to your goal.
+2. Create a [GOAPPlanner](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.goap/-g-o-a-p-planner/index.html) instance using the [goap()](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.goap/goap.html) function.
+    1. Define actions with preconditions and beliefs using the [action()](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.goap/-g-o-a-p-planner-builder/action.html) function.
+    2. Define goals with completion conditions using the [goal()](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner.goap/-g-o-a-p-planner-builder/goal.html) function.
+3. Wrap the planner with [AIAgentPlannerStrategy](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner/-a-i-agent-planner-strategy/index.html) and pass it to the [PlannerAIAgent](https://api.koog.ai/agents/agents-planner/ai.koog.agents.planner/-planner-a-i-agent/index.html) constructor.
+
+!!! note
 
-In the following example, GOAP handles the high-level planning (outline → draft → review → publish),
+    The planner selects individual actions and their sequence.
+    Each action includes a precondition that must hold true for the action to be executed
+    and a belief that defines the predicted outcome.
+    For more information about beliefs, see [State beliefs compared to actual execution](#state-beliefs-compared-to-actual-execution).
+
+In the following example, GOAP handles the high-level planning for creating an article (outline → draft → review → publish),
 while the LLM performs the actual content generation within each action.
 
 <!--- INCLUDE
@@ -135,11 +157,6 @@ import ai.koog.prompt.executor.clients.openai.OpenAIModels
 import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
 import kotlinx.coroutines.runBlocking
 import kotlin.reflect.typeOf
-
-suspend fun main() {
--->
-<!--- SUFFIX
-}
 -->
 ```kotlin
 // Define a state for content creation
@@ -155,6 +172,7 @@ data class ContentState(
 
 // Create GOAP planner with LLM-powered actions
 val planner = goap<ContentState>(typeOf<ContentState>()) {
+    // Define actions with preconditions and beliefs
     action(
         name = "Create outline",
         precondition = { state -> !state.hasOutline },
@@ -213,7 +231,8 @@ val planner = goap<ContentState>(typeOf<ContentState>()) {
         println("Publishing article...")
         state.copy(isPublished = true)
     }
-
+
+    // Define the goal with a completion condition
     goal(
         name = "Published article",
         description = "Complete and publish the article",
@@ -222,7 +241,6 @@ val planner = goap<ContentState>(typeOf<ContentState>()) {
 }
 
 // Create and run the agent
-val strategy = AIAgentPlannerStrategy("content-planner", planner)
 val agentConfig = AIAgentConfig(
     prompt = prompt("writer") {
         system("You are a professional content writer.")
@@ -233,12 +251,14 @@ val agentConfig = AIAgentConfig(
 
 val agent = PlannerAIAgent(
     promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
-    strategy = strategy,
+    strategy = AIAgentPlannerStrategy("content-planner", planner),
     agentConfig = agentConfig
 )
 
-val result = agent.run(ContentState(topic = "The Future of AI in Software Development"))
-println("Final state: $result")
+suspend fun main() {
+    val result = agent.run(ContentState(topic = "The Future of AI in Software Development"))
+    println("Final state: $result")
+}
 ```
 <!--- KNIT example-planner-02.kt -->
 
@@ -247,7 +267,8 @@ println("Final state: $result")
 
 ### Custom cost functions
 
-You can define custom cost functions for actions and goals to guide the planner:
+As A* search uses cost as a factor in finding the optimal sequence of actions,
+you can define custom cost functions for actions and goals to guide the planner:
 
 ```kotlin
 action(
@@ -264,12 +285,12 @@ action(
 }
 ```
 
-### State beliefs vs actual execution
+### State beliefs compared to actual execution
 
-GOAP distinguishes between beliefs (optimistic predictions) and actual execution:
+GOAP distinguishes between the concepts of beliefs (optimistic predictions) and actual execution:
 
-- **Belief**: What the planner thinks will happen (used for planning)
-- **Execution**: What actually happens (used for real state updates)
+- **Belief**: What the planner thinks will happen, used for planning.
+- **Execution**: What actually happens, used for real state updates.
 
 This allows the planner to make plans based on expected outcomes while handling actual results properly: