wiki/implementation/README-react-mode.md

React Mode (Plan–Act–Observe–Refine)

This introduces a compact iterative workflow that replaces bulk action plans with a tight loop:

• Plan (select): Model selects exactly one action
• Act (execute): Host requests only parameters for that action and executes
• Observe (summarize): Host returns a compact observation object
• Refine (decide): Model decides whether to continue or stop

How to enable it

Set the mode on ChatWorkflow (persisted in DB / passed through the API):

• workflowMode: string – "Actionplan" (legacy) or "React" (iterative)
• maxSteps: number – maximum iterations per task in React mode (default 5)

When workflowMode="Actionplan", the legacy batch action planning path is used.

Data models

Defined in gateway/modules/interfaces/interfaceChatModel.py:

• ActionSelection: { method: str, name: str }
• ActionParameters: { parameters: dict }
• Observation: { success: bool, resultLabel: str, documentsCount: int, previews: [{name,mime,snippet}], notes: [str] }
• TaskContext additions: reactMode: bool, maxSteps: int
• ChatWorkflow additions: workflowMode: str, maxSteps: int

Prompts

Defined in gateway/modules/chat/handling/promptFactory.py:

• createActionSelectionPrompt(context) → returns one action
• createActionParameterPrompt(context, selected_action) → returns parameters only
• createRefinementPrompt(context, observation) → returns { decision: continue|stop, reason }

Execution flow

Implemented in gateway/modules/chat/handling/handlingTasks.py:

• plan_select(context) → { action: { method, name } }
• act_execute(context, selection, task_step, workflow, step) → executes one action and returns ActionResult
• observe_build(action_result) → builds Observation
• refine_decide(context, observation) → { decision, reason }
• Integrated loop lives inside executeTask(...) when context.reactMode is true

Iteration control helper in gateway/modules/chat/handling/executionState.py:

• should_continue(observation, review_dict, current_step, max_steps)

Observation format

Compact, machine-friendly, with small previews only:

{
  success: boolean,
  resultLabel: string,
  documentsCount: number,
  previews: [ { name, mime, snippet } ],
  notes: [ string ]
}

Telemetry

Each iteration logs duration (seconds) to workflow logs. No specific token metrics required.

Backward compatibility

• Legacy planning/execution remains the default when workflowMode="Actionplan".
• No breaking changes to action or document structures.

Notes

• Document routing uses deterministic resultLabel: round{r}_task{t}_action{a}_...
• Previews are capped to ≤5 items and keep name, mime, and a short snippet.