The plan repair loop: ask for a step plan, check it, feed the violations back, ask again. More...

#include <neograph/api.h>
#include <neograph/program/registry.h>
#include <neograph/program/step_plan.h>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <string>
#include <string_view>
#include <vector>

Include dependency graph for step_plan_repair.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	neograph::program::PlannerMessage
	One message of the planner's conversation. More...

struct	neograph::program::PlannerReply
	What a planner call returns; usage is the host's own accounting. More...

Enumerations
enum class	neograph::program::StepPlanFeedback : std::uint8_t { Replace , Append }
	How the next prompt is built after a rejected plan. More...

Functions
NEOGRAPH_PROGRAM_API void	neograph::program::add_step_plan_repair (RegistrySnapshotBuilder &builder, const StepPlanRepairNodeOptions &options)
	Register the intake node (`neograph.step_plan_intake/v1`; configuration `max_attempts`, 1 to the host ceiling, default 3, and `feedback`, "replace" (default) or "append"), the route condition (`neograph.step_plan_route/v1`: `ok`, `retry`, `give_up`) and the report node (`neograph.step_plan_report/v1`: a final, idempotent write of the exhausted report, for a graph that ends the loop in a failure exit).

NEOGRAPH_PROGRAM_API StepPlanRepairResult	neograph::program::repair_step_plan (const PlanRepairOptions &options, std::string_view request, const std::function< PlannerReply(const std::vector< PlannerMessage > &)> &planner)
	Run the loop around a planner callback, for hosts that plan before they start a run.

Detailed Description

The plan repair loop: ask for a step plan, check it, feed the violations back, ask again.

The loop is a documented pattern over mechanisms that already exist, not a new plan operation. In a Program it is a Core graph plan -> intake -> (plan again): a registered pure node checks the planner's last answer with intake_step_plan and rebuilds the prompt, a registered condition routes on the result, and the graph's own bounds (the attempt count, max_visits, the run budget) end it. add_step_plan_repair registers the node, the condition and a report node. A host that plans before it starts a run uses repair_step_plan, the same loop around a callback.

Channels the intake node reads and writes (names are fixed):

messages read and rewritten: the conversation, as {role, content} messages. The last assistant message is the planner's answer.
proposal written: the lowered TaskGraphProposal JSON when the plan is accepted, else null.
repair read and written: the report below.

The repair report is {status, attempts, max_attempts, last_violations, violation_code_histogram, plan_digests, envelope}; status is ok, retry or exhausted.

Definition in file step_plan_repair.h.

Enumeration Type Documentation

◆ StepPlanFeedback

enum class neograph::program::StepPlanFeedback : std::uint8_t

strong

How the next prompt is built after a rejected plan.

Enumerator

Replace

Rebuild the conversation as [system messages, first user message, the rejected plan, the violations].

The context does not grow and an earlier mistake is not re-read.

Append

Keep the whole conversation and add the violations to it.

Definition at line 42 of file step_plan_repair.h.

Function Documentation

◆ add_step_plan_repair()

NEOGRAPH_PROGRAM_API void neograph::program::add_step_plan_repair	(	RegistrySnapshotBuilder &	builder,
		const StepPlanRepairNodeOptions &	options
	)

Register the intake node (neograph.step_plan_intake/v1; configuration max_attempts, 1 to the host ceiling, default 3, and feedback, "replace" (default) or "append"), the route condition (neograph.step_plan_route/v1: ok, retry, give_up) and the report node (neograph.step_plan_report/v1: a final, idempotent write of the exhausted report, for a graph that ends the loop in a failure exit).

The implementation identities cover the host options, so a Program admitted with one allow-list does not run with another.

References neograph::program::add_step_plan_repair().

Referenced by neograph::program::add_step_plan_repair().

◆ repair_step_plan()

NEOGRAPH_PROGRAM_API StepPlanRepairResult neograph::program::repair_step_plan	(	const PlanRepairOptions &	options,
		std::string_view	request,
		const std::function< PlannerReply(const std::vector< PlannerMessage > &)> &	planner
	)

Run the loop around a planner callback, for hosts that plan before they start a run.

The accepted proposal then becomes the run's input, which the run record persists, so a resume never plans again. Accounting is the host's own: the run's budgets do not include planning. request is the first user message and should carry the catalog the planner may use.

References neograph::program::repair_step_plan().

Referenced by neograph::program::repair_step_plan().

Classes