Update docs to Plano (#639)

docs/source/concepts/prompt_target.rst

@@ -1,15 +1,17 @@
 .. _prompt_target:
 
 Prompt Target
-==============
+=============
+A Prompt Target is a deterministic, task-specific backend function or API endpoint that your application calls via Plano.
+Unlike agents (which handle wide-ranging, open-ended tasks), prompt targets are designed for focused, specific workloads where Plano can add value through input clarification and validation.
 
-**Prompt Targets** are a core concept in Arch, empowering developers to clearly define how user prompts are interpreted, processed, and routed within their generative AI applications. Prompts can seamlessly be routed either to specialized AI agents capable of handling sophisticated, context-driven tasks or to targeted tools provided by your application, offering users a fast, precise, and personalized experience.
+Plano helps by:
 
-This section covers the essentials of prompt targets—what they are, how to configure them, their practical uses, and recommended best practices—to help you fully utilize this feature in your applications.
+* **Clarifying and validating input**: Plano enriches incoming prompts with metadata (e.g., detecting follow-ups or clarifying requests) and can extract structured parameters from natural language before passing them to your backend.
+* **Enabling high determinism**: Since the task is specific and well-defined, Plano can reliably extract the information your backend needs without ambiguity.
+* **Reducing backend work**: Your backend receives clean, validated, structured inputs—so you can focus on business logic instead of parsing and validation.
 
-What Are Prompt Targets?
-------------------------
-Prompt targets are endpoints within Arch that handle specific types of user prompts. They act as the bridge between user inputs and your backend agents or tools (APIs), enabling Arch to route, process, and manage prompts efficiently. Defining prompt targets helps you decouple your application's core logic from processing and handling complexities, leading to clearer code organization, better scalability, and easier maintenance.
+For example, a prompt target might be "schedule a meeting" (specific task, deterministic inputs like date, time, attendees) or "retrieve documents" (well-defined RAG query with clear intent). Prompt targets are typically called from your application code via Plano's internal listener.
 
 
 .. table::
@@ -33,16 +35,11 @@ Below are the key features of prompt targets that empower developers to build ef
 - **Input Management**: Specify required and optional parameters for each target.
 - **Tools Integration**: Seamlessly connect prompts to backend APIs or functions.
 - **Error Handling**: Direct errors to designated handlers for streamlined troubleshooting.
-- **Metadata Enrichment**: Attach additional context to prompts for enhanced processing.
-
-Configuring Prompt Targets
---------------------------
-Configuring prompt targets involves defining them in Arch's configuration file. Each Prompt target specifies how a particular type of prompt should be handled, including the endpoint to invoke and any parameters required.
+- **Multi-Turn Support**: Manage follow-up prompts and clarifications in conversational flows.
 
 Basic Configuration
 ~~~~~~~~~~~~~~~~~~~
-
-A prompt target configuration includes the following elements:
+Configuring prompt targets involves defining them in Plano's configuration file. Each Prompt target specifies how a particular type of prompt should be handled, including the endpoint to invoke and any parameters required. A prompt target configuration includes the following elements:
 
 .. vale Vale.Spelling = NO
 
@@ -55,8 +52,8 @@ A prompt target configuration includes the following elements:
 
 Defining Parameters
 ~~~~~~~~~~~~~~~~~~~
-Parameters are the pieces of information that Arch needs to extract from the user's prompt to perform the desired action.
-Each parameter can be marked as required or optional. Here is a full list of parameter attributes that Arch can support:
+Parameters are the pieces of information that Plano needs to extract from the user's prompt to perform the desired action.
+Each parameter can be marked as required or optional. Here is a full list of parameter attributes that Plano can support:
 
 .. table::
     :width: 100%
@@ -98,50 +95,92 @@ Example Configuration For Tools
           name: api_server
           path: /weather
 
-Example Configuration For Agents
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _plano_multi_turn_guide:
 
-.. code-block:: yaml
-    :caption: Agent Orchestration Configuration Example
+Multi-Turn
+~~~~~~~~~~
+Developers often `struggle <https://www.reddit.com/r/LocalLLaMA/comments/18mqwg6/best_practice_for_rag_with_followup_chat/>`_ to efficiently handle
+``follow-up`` or ``clarification`` questions. Specifically, when users ask for changes or additions to previous responses, it requires developers to
+re-write prompts using LLMs with precise prompt engineering techniques. This process is slow, manual, error prone and adds latency and token cost for
+common scenarios that can be managed more efficiently.
 
-    overrides:
-      use_agent_orchestrator: true
+Plano is highly capable of accurately detecting and processing prompts in multi-turn scenarios so that you can buil fast and accurate agents in minutes.
+Below are some cnversational examples that you can build via Plano. Each example is enriched with annotations (via ** [Plano] ** ) that illustrates how Plano
+processess conversational messages on your behalf.
 
-    prompt_targets:
-      - name: sales_agent
-        description: handles queries related to sales and purchases
+Example 1: Adjusting Retrieval
 
-      - name: issues_and_repairs
-        description: handles issues, repairs, or refunds
+.. code-block:: text
 
-      - name: escalate_to_human
-        description: escalates to human agent
+    User: What are the benefits of renewable energy?
+    **[Plano]**: Check if there is an available <prompt_target> that can handle this user query.
+    **[Plano]**: Found "get_info_for_energy_source" prompt_target in arch_config.yaml. Forward prompt to the endpoint configured in "get_info_for_energy_source"
+    ...
+    Assistant: Renewable energy reduces greenhouse gas emissions, lowers air pollution, and provides sustainable power sources like solar and wind.
 
-.. note::
-    Today, you can use Arch to coordinate more specific agentic scenarios via tools and function calling, or use it for high-level agent routing and hand off scenarios. In the future, we plan to offer you the ability to combine these two approaches for more complex scenarios. Please see `github issues <https://github.com/katanemo/archgw/issues/442>`_ for more details.
+    User: Include cost considerations in the response.
+    **[Plano]**: Follow-up detected. Forward prompt history to the "get_info_for_energy_source" prompt_target and post the following parameters consideration="cost"
+    ...
+    Assistant: Renewable energy reduces greenhouse gas emissions, lowers air pollution, and provides sustainable power sources like solar and wind. While the initial setup costs can be high, long-term savings from reduced fuel expenses and government incentives make it cost-effective.
 
-Routing Logic
--------------
-Prompt targets determine where and how user prompts are processed. Arch uses intelligent routing logic to ensure that prompts are directed to the appropriate targets based on their intent and context.
 
-Default Targets
-~~~~~~~~~~~~~~~
-For general-purpose prompts that do not match any specific prompt target, Arch routes them to a designated default target. This is useful for handling open-ended queries like document summarization or information extraction.
+Example 2: Switching Intent
+---------------------------
+.. code-block:: text
 
-Intent Matching
-~~~~~~~~~~~~~~~
-Arch analyzes the user's prompt to determine its intent and matches it with the most suitable prompt target based on the name and description defined in the configuration.
+    User: What are the symptoms of diabetes?
+    **[Plano]**: Check if there is an available <prompt_target> that can handle this user query.
+    **[Plano]**: Found "diseases_symptoms" prompt_target in arch_config.yaml. Forward disease=diabeteres to "diseases_symptoms" prompt target
+    ...
+    Assistant: Common symptoms include frequent urination, excessive thirst, fatigue, and blurry vision.
 
-For example:
+    User: How is it diagnosed?
+    **[Plano]**: New intent detected.
+    **[Plano]**: Found "disease_diagnoses" prompt_target in arch_config.yaml. Forward disease=diabeteres to "disease_diagnoses" prompt target
+    ...
+    Assistant: Diabetes is diagnosed through blood tests like fasting blood sugar, A1C, or an oral glucose tolerance test.
 
-.. code-block:: bash
 
-  Prompt: "Can you reboot the router?"
-  Matching Target: reboot_device (based on description matching "reboot devices")
+Build Multi-Turn RAG Apps
+-------------------------
+The following section describes how you can easilly add support for multi-turn scenarios via Plano. You process and manage multi-turn prompts
+just like you manage single-turn ones. Plano handles the conpleixity of detecting the correct intent based on the last user prompt and
+the covnersational history, extracts relevant parameters needed by downstream APIs, and dipatches calls to any upstream LLMs to summarize the
+response from your APIs.
 
 
+.. _multi_turn_subsection_prompt_target:
+
+Step 1: Define Plano Config
+---------------------------
+
+.. literalinclude:: ../build_with_plano/includes/multi_turn/prompt_targets_multi_turn.yaml
+    :language: yaml
+    :caption: Plano Config
+    :linenos:
+
+Step 2: Process Request in Flask
+--------------------------------
+
+Once the prompt targets are configured as above, handle parameters across multi-turn as if its a single-turn request
+
+.. literalinclude:: ../build_with_plano/includes/multi_turn/multi_turn_rag.py
+    :language: python
+    :caption: Parameter handling with Flask
+    :linenos:
+
+Demo App
+--------
+
+For your convenience, we've built a `demo app <https://github.com/katanemo/archgw/tree/main/demos/samples_python/multi_turn_rag_agent>`_
+that you can test and modify locally for multi-turn RAG scenarios.
+
+.. figure:: ../build_with_plano/includes/multi_turn/mutli-turn-example.png
+   :width: 100%
+   :align: center
+
+   Example multi-turn user conversation showing adjusting retrieval
+
 Summary
---------
-Prompt targets are essential for defining how user prompts are handled within your generative AI applications using Arch.
-
-By carefully configuring prompt targets, you can ensure that prompts are accurately routed, necessary parameters are extracted, and backend services are invoked seamlessly. This modular approach not only simplifies your application's architecture but also enhances scalability, maintainability, and overall user experience.
+~~~~~~~
+By carefully designing prompt targets as deterministic, task-specific entry points, you ensure that prompts are routed to the right workload, necessary parameters are cleanly extracted and validated, and backend services are invoked with structured inputs. This clear separation between prompt handling and business logic simplifies your architecture, makes behavior more predictable and testable, and improves the scalability and maintainability of your agentic applications.