Pattern Modules

This page documents the stable public pattern facades.

Stable public exports for reusable orchestration patterns.

class design_research_agents.patterns.BeamSearchPattern(*, generator_delegate, evaluator_delegate, max_depth=3, branch_factor=3, beam_width=2, tracer=None)

Beam-style tree search over generated candidate states.

Initialize tree-search reasoning pattern.

Parameters:

• generator_delegate – Delegate that expands one candidate into children.

• evaluator_delegate – Delegate that assigns a score to one candidate.

• max_depth – Maximum expansion depth.

• branch_factor – Max children retained per expanded node.

• beam_width – Max frontier width kept after each depth.

• tracer – Optional tracer dependency.

Raises:

ValueError – Raised when depth/branch/beam settings are invalid.

compile(prompt, *, request_id=None, dependencies=None)

Compile one tree-search workflow.

run(prompt, *, request_id=None, dependencies=None)

Execute tree search and return the highest-scoring candidate.

class design_research_agents.patterns.BlackboardPattern(*, peers, max_rounds=6, stability_rounds=2, initial_state=None, peer_prompt_builder=None, tracer=None)

Networked pattern with explicit blackboard reducer semantics.

Initialize blackboard specialization with convergence controls.

Parameters:

• peers – Peer delegates participating in rounds.

• max_rounds – Maximum rounds before termination.

• stability_rounds – Number of unchanged state hashes required to declare convergence.

• initial_state – Optional initial blackboard override mapping.

• peer_prompt_builder – Optional peer prompt builder callback.

• tracer – Optional tracer dependency.

Raises:

ValueError – Raised when stability_rounds is less than one.

class design_research_agents.patterns.DebatePattern(*, llm_client, tool_runtime, affirmative_delegate=None, negative_delegate=None, judge_delegate=None, max_rounds=3, affirmative_system_prompt=None, affirmative_user_prompt_template=None, negative_system_prompt=None, negative_user_prompt_template=None, judge_system_prompt=None, judge_user_prompt_template=None, default_request_id_prefix='debate', default_dependencies=None, tracer=None)

Configured reusable debate pattern with affirmative, negative, and judge phases.

Store dependencies and initialize prompt defaults.

compile(prompt, *, request_id=None, dependencies=None)

Compile one debate workflow.

run(prompt, *, request_id=None, dependencies=None)

The debate pattern and return one final judged result.

class design_research_agents.patterns.PlanExecutePattern(*, llm_client, tool_runtime, planner_delegate=None, executor_delegate=None, max_iterations=3, max_tool_calls_per_step=5, planner_system_prompt=None, planner_user_prompt_template=None, executor_step_prompt_template=None, default_request_id_prefix=None, default_dependencies=None, tracer=None)

Planner/executor orchestration pattern built on workflow primitives.

Store dependencies and initialize workflow-native orchestration settings.

Parameters:

• llm_client – LLM client used for planner and executor model calls.

• tool_runtime – Tool runtime used by executor agent steps.

• planner_delegate – Optional planner delegate override.

• executor_delegate – Optional executor delegate override.

• max_iterations – Maximum number of plan steps executed in one run.

• max_tool_calls_per_step – Maximum tool calls allowed per executor step.

• planner_system_prompt – Optional override for planner system prompt.

• planner_user_prompt_template – Optional override for planner user prompt.

• executor_step_prompt_template – Optional override for executor step prompt.

• default_request_id_prefix – Optional prefix used to derive request ids.

• default_dependencies – Dependency defaults merged into each run.

• tracer – Optional tracer used for run-level instrumentation.

Raises:

ValueError – If max_iterations or max_tool_calls_per_step is invalid.

compile(prompt, *, request_id=None, dependencies=None)

Compile one bound plan-execute orchestration.

run(prompt, *, request_id=None, dependencies=None)

Execute one plan-execute orchestration run.

class design_research_agents.patterns.ProposeCriticPattern(*, llm_client, tool_runtime, proposer_delegate=None, critic_delegate=None, max_iterations=3, proposer_system_prompt=None, proposer_user_prompt_template=None, critic_system_prompt=None, critic_user_prompt_template=None, default_request_id_prefix=None, default_dependencies=None, tracer=None)

Propose/critique revision pattern built on workflow primitives.

Store dependencies and initialize workflow-native orchestration settings.

Parameters:

• llm_client – LLM client used by proposer and critic calls.

• tool_runtime – Tool runtime used by loop execution runtime.

• proposer_delegate – Optional proposer delegate override.

• critic_delegate – Optional critic delegate override.

• max_iterations – Maximum propose/critic iterations per run.

• proposer_system_prompt – Optional override for proposer system prompt.

• proposer_user_prompt_template – Optional proposer user prompt template.

• critic_system_prompt – Optional override for critic system prompt.

• critic_user_prompt_template – Optional critic user prompt template.

• default_request_id_prefix – Optional prefix used to derive request ids.

• default_dependencies – Dependency defaults merged into each run.

• tracer – Optional tracer used for run-level instrumentation.

Raises:

ValueError – If max_iterations is invalid.

compile(prompt, *, request_id=None, dependencies=None)

Compile one propose/critic workflow.

run(prompt, *, request_id=None, dependencies=None)

Execute one propose-and-critique orchestration run.

class design_research_agents.patterns.RAGPattern(*, reasoning_delegate, memory_store, memory_namespace='default', memory_top_k=5, memory_min_score=None, write_back=True, tracer=None)

Reasoning pattern orchestrated as memory read -> reason -> memory write.

Initialize RAG reasoning pattern.

Parameters:

• reasoning_delegate – Delegate object that performs reasoning with retrieved context.

• memory_store – Memory store used for retrieval and optional write-back.

• memory_namespace – Namespace partition for reads/writes.

• memory_top_k – Number of retrieved matches for reasoning context.

• memory_min_score – Optional minimum retrieval score threshold.

• write_back – Whether to persist one summary record after reasoning.

• tracer – Optional tracer dependency.

Raises:

ValueError – Raised when memory_top_k is less than one.

compile(prompt, *, request_id=None, dependencies=None)

Compile the read/reason/write workflow.

run(prompt, *, request_id=None, dependencies=None)

Execute memory retrieval, delegated reasoning, and optional write-back.

class design_research_agents.patterns.RoundBasedCoordinationPattern(*, peers, max_rounds=4, initial_state=None, peer_prompt_builder=None, tracer=None)

Round-based peer coordination pattern with deterministic peer ordering.

Initialize peer-only networked orchestration.

Parameters:

• peers – Mapping of peer ids to delegate objects.

• max_rounds – Maximum number of coordination rounds.

• initial_state – Optional initial shared state payload.

• peer_prompt_builder – Optional prompt builder per peer and round.

• tracer – Optional tracer dependency.

Raises:

ValueError – Raised when peers is empty or max_rounds is invalid.

compile(prompt, *, request_id=None, dependencies=None)

Compile peer-only networked coordination rounds.

run(prompt, *, request_id=None, dependencies=None)

Execute peer-only networked coordination rounds.

class design_research_agents.patterns.RouterDelegatePattern(*, llm_client, tool_runtime, alternatives, alternative_descriptions=None, router_system_prompt=None, router_user_prompt_template=None, default_request_id_prefix=None, default_dependencies=None, tracer=None)

Routing/delegation pattern built on workflow primitives.

Store dependencies and initialize workflow-native routing settings.

Parameters:

• llm_client – LLM client used by the router agent.

• tool_runtime – Tool runtime used to cost/metadata-account delegated calls.

• alternatives – Mapping of route keys to delegate objects.

• alternative_descriptions – Optional descriptions used to guide routing.

• router_system_prompt – Optional override for router system prompt.

• router_user_prompt_template – Optional override for router user prompt.

• default_request_id_prefix – Optional prefix used to derive request ids.

• default_dependencies – Dependency defaults merged into each run.

• tracer – Optional tracer used for run-level instrumentation.

Raises:

ValueError – If no valid route alternatives are supplied.

compile(prompt, *, request_id=None, dependencies=None)

Compile one intent-routing orchestration run.

run(prompt, *, request_id=None, dependencies=None)

Execute one intent-routing orchestration run.

class design_research_agents.patterns.TwoSpeakerConversationPattern(*, llm_client_a, llm_client_b=None, speaker_a_delegate=None, speaker_b_delegate=None, max_turns=3, speaker_a_name='speaker_a', speaker_b_name='speaker_b', speaker_a_system_prompt=None, speaker_a_user_prompt_template=None, speaker_b_system_prompt=None, speaker_b_user_prompt_template=None, default_request_id_prefix=None, default_dependencies=None, tracer=None)

Two-speaker LLM conversation pattern with per-speaker prompts and clients.

Store dependencies and prompt defaults for conversation orchestration.

Parameters:

• llm_client_a – LLM client used by speaker A.

• llm_client_b – Optional LLM client used by speaker B. Defaults to llm_client_a when omitted.

• speaker_a_delegate – Optional explicit delegate for speaker A.

• speaker_b_delegate – Optional explicit delegate for speaker B.

• max_turns – Maximum conversation turns where each turn is A->B.

• speaker_a_name – Display name for speaker A in transcript and prompts.

• speaker_b_name – Display name for speaker B in transcript and prompts.

• speaker_a_system_prompt – Optional override for speaker A system prompt.

• speaker_a_user_prompt_template – Optional speaker A user template override.

• speaker_b_system_prompt – Optional override for speaker B system prompt.

• speaker_b_user_prompt_template – Optional speaker B user template override.

• default_request_id_prefix – Optional request-id prefix used for auto-generated ids.

• default_dependencies – Default dependency mapping merged into each run.

• tracer – Optional tracer used for pattern and nested agent traces.

Raises:

ValueError – Raised when constructor configuration is invalid.

compile(prompt, *, request_id=None, dependencies=None)

Compile one two-speaker conversation workflow.

run(prompt, *, request_id=None, dependencies=None)

Execute one two-speaker conversation run.