From 6bc2092d784997be12eeaf311470735ab4562f1b Mon Sep 17 00:00:00 2001 From: ValueOn AG Date: Tue, 7 Oct 2025 00:17:30 +0200 Subject: [PATCH] revised react planning 2 stages --- ...entation_react_two_stage_prompting_spec.md | 137 ++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 poweron/implementation/implementation_react_two_stage_prompting_spec.md diff --git a/poweron/implementation/implementation_react_two_stage_prompting_spec.md b/poweron/implementation/implementation_react_two_stage_prompting_spec.md new file mode 100644 index 0000000..1d0d95d --- /dev/null +++ b/poweron/implementation/implementation_react_two_stage_prompting_spec.md @@ -0,0 +1,137 @@ +## React Mode: Two-Stage Prompting Adaptation (Spec) + +### Goals +- Stage 1 selects the next action and declares objective, learnings, and concrete document/connection references. +- Stage 1 explicitly must NOT produce any parameters. +- Stage 2 collects only business parameters, with minimal context: action objective and selected action. Stage 2 does not implicitly inherit Stage 1 state and therefore receives these two fields explicitly. +- Keep current server-side handling of document/connection references unchanged (do not central-resolve differently), to preserve Actionplan mode compatibility. +- Persist a short `summary` for each action message upon completion to support contextual history. + +--- + +### Stage 1: Action Selection (no parameters) + +• Input context +- User prompt +- Available methods +- Available documents summary +- Reverse-chronological workflow history (current round first, then older rounds), each message enriched with: document index references, findings, summary (if present), learnings (if available). + +• Output JSON (only): +```json +{ + "action": "method.action_name", + "actionObjective": "string", + "learnings": ["string"], + "requiredInputDocuments": ["docList:..." | "docItem:..."], + "requiredConnection": "connectionLabel" | null, + "parametersContext": "string (concise context text for Stage 2 parameter setting)", + "parametersSchema": { + "fields": [ + { "name": "string", "type": "string|number|boolean|enum|object", "required": true, "description": "string" } + ] + } +} +``` + +• Constraints +- Do NOT include a `parameters` object in Stage 1. +- `parametersSchema` must NOT contain keys for `documentList`, `connectionReference`, `history`, `documents`, `connections`. +- Document and connection references are selected already in Stage 1 (labels/refs), but parameter values are not. +- The `parametersContext` is a compact natural-language text that Stage 2 will consume directly in its prompt; no host-side passing of broader context is required beyond including this text in the Stage 2 prompt. + +• Prompt changes (code) +- File: `gateway/modules/workflows/processing/shared/promptGenerationActionsReact.py` + - Function: `generateReactPlanSelectionPrompt` + - Extend template to request the above JSON schema (no `parameters`). + - Add placeholders for `WORKFLOW_HISTORY` (see history section) and, if needed, `extractAvailableConnectionsIndex` and `extractAvailableDocumentsIndex` to support deterministic labels. + - Instruct the model to produce a concise `parametersContext` suitable to be embedded in the Stage 2 prompt to set business parameters. + +• Parser changes (code) +- File: `gateway/modules/workflows/processing/modes/modeReact.py` + - Function: `_planSelect` + - Update validation to accept the extended Stage‑1 JSON (ensure `'action'` is a string; ignore/transport other keys; explicitly reject if a `parameters` key is present). + +--- + +### Stage 2: Parameter Collection (business parameters only) + +• Input context +- Minimal: `selectedAction` (compound name `method.action`) and `actionObjective` (string), plus the textual `parametersContext` produced by Stage 1. Stage 2 does not require any other implicit state. + +• Output JSON (only): +```json +{ + "schema": "parameters_v1", + "parameters": { + "paramName": "value" + } +} +``` + +• Constraints +- Do NOT ask for or include: `documentList`, `connectionReference`, `history`, `documents`, `connections`. +- Collect only fields specified by `parametersSchema.fields` from Stage 1 (business parameters). + +• Prompt changes (code) +- File: `gateway/modules/workflows/processing/shared/promptGenerationActionsReact.py` + - Function: `generateReactParametersPrompt` (Option B: conditional behavior) + - If `parametersSchema` is available in context (as part of Stage 1 output), build a minimal prompt that includes only: + - `ACTION_OBJECTIVE` + - `SELECTED_ACTION` + - `PARAMETERS_CONTEXT` (the concise text from Stage 1) + - A rendered `PARAMETERS_SCHEMA` section (from Stage 1) for the user/LLM to fill + - Exclude placeholders/sections for documents index, connections index, previous results, learnings, refinement feedback, workflow history. + +• Execution flow changes (code) +- File: `gateway/modules/workflows/processing/modes/modeReact.py` + - Function: `_actExecute` + - Remove allowance for Stage‑1 to pre-supply `parameters` (enforce that Stage‑2 is always used for parameter collection when none are present). + - Continue to rely on existing downstream logic that accepts the document/connection references from Stage 1; do NOT add new server-side resolution behavior. + - Ensure the Stage 2 prompt is constructed with `selectedAction`, `actionObjective`, and `parametersContext` directly from Stage 1 output; no other history/documents/connections should be injected. + +--- + +### History: Reverse-Chronological With Context + +• Requirements +- Present history reverse-chronologically: first all messages of the current round (newest → oldest), then previous rounds. +- Per message, include: `documentsLabel` and document references (index), findings/notes (if present), `summary` (persisted on action completion), and learnings if available (e.g., from refinement/validation). + +• Implementation (code) +- File: `gateway/modules/workflows/processing/shared/placeholderFactory.py` + - Functions: `extractWorkflowHistory`, helpers (e.g., `getPreviousRoundContext` or new dedicated routine) + - Build a compact textual history that embeds the above fields per message. + - Use existing document index builders from WorkflowService to get stable `docList`/`docItem` references; do not alter their behavior. + - Mapping table comment: allow `{{KEY:WORKFLOW_HISTORY}}` also for React Stage‑1 prompt. + +--- + +### Persisting `summary` on Action Completion + +• Requirement +- After each action, store a short `summary` in `ChatMessage.summary` for better history context. + +• Implementation (code) +- File: `gateway/modules/workflows/processing/core/messageCreator.py` + - Function: `createActionMessage` + - Derive a concise summary from the available observation/validation/notes and set `summary` when creating/updating the message record. + +--- + +### Non-Goals / Compatibility +- Do not change server-side resolution for document or connection references. Use the existing flow; this preserves Actionplan mode. +- Stage 1 must never emit `parameters`. +- Stage 2 must not request or include document/connection fields or history/documents content. + +--- + +### Test Checklist +- Stage‑1 responses include action + objective + learnings + required docs + required connection + parametersSchema; no `parameters`. +- Stage‑2 prompts show only objective + selected action + parametersSchema; no references to documents/connections/history. +- `_planSelect` rejects Stage‑1 responses containing `parameters`. +- `_actExecute` always triggers Stage‑2 parameter collection when needed, and uses existing logic for doc/connection references. +- History placeholder renders reverse‑chronological with enriched message context. +- Action completion writes `ChatMessage.summary`. + +