honegumi_rag_assistant.nodes package

Submodules

honegumi_rag_assistant.nodes.code_writer module

Node: Code writer agent.

This node generates Python code from the Honegumi skeleton and any retrieved documentation contexts. In the new architecture, retrieval is performed upfront by the Retrieval Planner, so the Code Writer focuses solely on code generation.

The agent receives the problem description, optimization parameters, skeleton code, and pre-retrieved documentation contexts, then generates the final Python script.

class honegumi_rag_assistant.nodes.code_writer.CodeWriterAgent

Bases: object

Code writer that generates Ax Platform code from skeleton and contexts.

In the new architecture, retrieval is handled upfront by the Retrieval Planner agent with parallel execution. The Code Writer receives all necessary contexts and focuses on generating high-quality code.

static write_code(state: HonegumiRAGState) → Dict[str, Any]

Generate executable Python code from skeleton and contexts.

Parameters

stateHonegumiRAGState

The current pipeline state with keys problem, bo_params, skeleton_code, and contexts.

Returns

Dict[str, Any]

Dictionary with either: - “final_code” if streaming is enabled (no review) - “candidate_code” if review is enabled

honegumi_rag_assistant.nodes.parameter_selector module

Node: Parameter selection agent.

This node is responsible for translating the user’s natural language problem description into a structured set of Bayesian optimisation parameters.

This node implements a two-stage extraction process: 1. Extract problem structure (parameters, objectives, constraints) 2. Select grid parameters based on the extracted structure

The heavy lifting is delegated to ProblemStructureExtractor and ParameterExtractor, which invoke language models via the OpenAI function calling interface.

The output of this node is merged into the global state under the bo_params key. If an error occurs during extraction, the error message is added to the error field of the state.

class honegumi_rag_assistant.nodes.parameter_selector.ParameterSelector

Bases: object

A LangGraph node that selects optimisation parameters via LLM.

This node accepts the current pipeline state and extracts the problem field to construct a prompt. It uses a two-stage process:

1. Extract problem structure (parameters, objectives, constraints)

2. Select grid parameters based on extracted structure

This approach improves accuracy by forcing explicit reasoning about problem elements before making grid selections.

Any returned errors are propagated into the error field of the state.

static select_parameters(state: HonegumiRAGState) → Dict[str, Any]

Select optimisation parameters for the given problem.

Parameters

stateHonegumiRAGState

The current pipeline state containing at least a problem key.

Returns

Dict[str, Any]

A dictionary with updated keys for the pipeline state. At minimum this will include a bo_params entry and may contain an error entry if something goes wrong.

honegumi_rag_assistant.nodes.retrieval_planner module

Node: Retrieval Planner Agent.

This agent analyzes the problem description and Honegumi skeleton to determine what additional information is needed from the Ax documentation. It can generate up to 7 specific queries that will be executed in parallel via fan-out subgraphs.

The planner acts as an intelligent information needs analyzer that decides: 1. Does the skeleton provide enough structure, or do we need more details? 2. What specific aspects of Ax Platform need clarification? 3. How to formulate focused queries for maximum relevance?

class honegumi_rag_assistant.nodes.retrieval_planner.RetrievalPlan(*, action: ~typing.Literal['skip_retrieval', 'retrieve'], queries: ~typing.Annotated[~typing.List[~honegumi_rag_assistant.nodes.retrieval_planner.RetrievalQuery], ~annotated_types.MaxLen(max_length=7)] = <factory>)

Bases: BaseModel

Decision about what to retrieve from Ax documentation.

action: Literal['skip_retrieval', 'retrieve']

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

queries: List[RetrievalQuery]

class honegumi_rag_assistant.nodes.retrieval_planner.RetrievalPlannerAgent

Bases: object

Plan retrieval strategy by analyzing information needs.

static plan_retrieval(state: HonegumiRAGState) → Dict[str, Any]

Analyze problem and skeleton to determine retrieval needs.

Parameters

stateHonegumiRAGState

The current pipeline state containing problem, bo_params, and skeleton_code.

Returns

Dict[str, Any]

Dictionary with: - retrieval_queries: List[str] of queries to execute in parallel - Empty list if no retrieval needed

class honegumi_rag_assistant.nodes.retrieval_planner.RetrievalQuery(*, query: str)

Bases: BaseModel

A single focused query for the vector database.

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

query: str

honegumi_rag_assistant.nodes.retriever module

Node: Retrieve relevant documentation contexts.

This node provides the code writer with additional grounding by extracting snippets from the Ax documentation. When configured with settings.retrieval_vectorstore_path, it attempts to load a vector store (for example a FAISS index) created from the documentation and performs a similarity search using a query derived from the problem description and optimisation parameters. If the vector store or dependencies are unavailable, it returns an empty list of contexts.

Each returned context should be a dictionary containing at least a text key with the content. Additional metadata such as source and score may be included depending on the vector store implementation.

class honegumi_rag_assistant.nodes.retriever.RetrieverAgent

Bases: object

Retrieve relevant documentation snippets for the current problem.

The retriever constructs a query by concatenating the natural language problem description with a JSON representation of the optimisation parameters. It then executes a similarity search against the configured vector store to return the top k most relevant chunks. If no vector store is configured or the required dependencies are missing the retriever returns an empty list.

static retrieve_context(state: HonegumiRAGState) → Dict[str, Any]

Retrieve documentation contexts based on a specific question.

Parameters

stateHonegumiRAGState

The current pipeline state containing retrieval_query with a specific question from the Code Writer agent.

Returns

Dict[str, Any]

A dictionary with keys: - contexts: list of context snippets (empty if retrieval fails) - retrieval_count: incremented counter - retrieval_query: cleared (set to None)

honegumi_rag_assistant.nodes.retriever.retrieve_single_query(query: str, query_index: int) → Dict[str, Any]

Retrieve contexts for a single query (used in parallel fan-out).

This is a simpler version designed for parallel execution via Send API. Each parallel retriever handles one query independently.

Parameters

querystr

The retrieval query to execute

query_indexint

Index of this query (for debugging)

Returns

Dict[str, Any]

Dictionary with ‘contexts’ key containing retrieved docs

honegumi_rag_assistant.nodes.reviewer module

Node: Reviewer agent.

The reviewer acts as a quality control gate that can either approve the generated code or send it back for revision. It uses LLM-based code review to check correctness, completeness, and adherence to Ax Platform best practices.

The reviewer can send code back for revision up to 2 times with specific feedback. After the maximum number of revisions, it will approve the code regardless of quality to prevent infinite loops.

class honegumi_rag_assistant.nodes.reviewer.ReviewDecision(*, action: Literal['approve', 'revise'], feedback: str | None = None)

Bases: BaseModel

Decision made by the Reviewer Agent.

action: Literal['approve', 'revise']

feedback: str | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class honegumi_rag_assistant.nodes.reviewer.ReviewerAgent

Bases: object

Perform LLM-based review and decide whether to approve or request revision.

static review_code(state: HonegumiRAGState) → Dict[str, Any]

Review the candidate code and decide to approve or revise.

Parameters

stateHonegumiRAGState

The current pipeline state containing candidate_code, review_count, and other context.

Returns

Dict[str, Any]

Either: - {“final_code”: str} if approved - {“critique_report”: List[str], “review_count”: int} if revision needed

honegumi_rag_assistant.nodes.skeleton_generator module

Node: Generate a deterministic code skeleton using Honegumi.

This node converts the optimisation parameters selected by the ParameterSelector into a baseline Python script using the Honegumi template engine. The skeleton contains the correct Ax API calls and experiment loop structure but does not implement any problem‑specific logic. Once generated, the skeleton and any associated metadata are inserted into the pipeline state.

class honegumi_rag_assistant.nodes.skeleton_generator.SkeletonGenerator

Bases: object

Generate the Honegumi skeleton code for the selected parameters.

Given a set of optimisation parameters (bo_params), this node instantiates the Honegumi template engine and renders the corresponding Ax script.

static generate_skeleton(state: HonegumiRAGState) → Dict[str, Any]

Generate a skeleton code file from the provided parameters.

Parameters

stateHonegumiRAGState

The current pipeline state containing at least a bo_params key.

Returns

Dict[str, Any]

A dictionary with keys skeleton_code and template_metadata. If an error occurs, an error key will also be set.

Module contents

Import convenience for node classes.

This module exposes the key nodes used in the Honegumi RAG Assistant workflow so that they can be imported from a single place. When modifying or extending the pipeline you should add your new nodes here.

class honegumi_rag_assistant.nodes.CodeWriterAgent

Bases: object

Code writer that generates Ax Platform code from skeleton and contexts.

In the new architecture, retrieval is handled upfront by the Retrieval Planner agent with parallel execution. The Code Writer receives all necessary contexts and focuses on generating high-quality code.

static write_code(state: HonegumiRAGState) → Dict[str, Any]

Generate executable Python code from skeleton and contexts.

Parameters

stateHonegumiRAGState

The current pipeline state with keys problem, bo_params, skeleton_code, and contexts.

Returns

Dict[str, Any]

Dictionary with either: - “final_code” if streaming is enabled (no review) - “candidate_code” if review is enabled

class honegumi_rag_assistant.nodes.ParameterSelector

Bases: object

A LangGraph node that selects optimisation parameters via LLM.

This node accepts the current pipeline state and extracts the problem field to construct a prompt. It uses a two-stage process:

1. Extract problem structure (parameters, objectives, constraints)

2. Select grid parameters based on extracted structure

This approach improves accuracy by forcing explicit reasoning about problem elements before making grid selections.

Any returned errors are propagated into the error field of the state.

static select_parameters(state: HonegumiRAGState) → Dict[str, Any]

Select optimisation parameters for the given problem.

Parameters

stateHonegumiRAGState

The current pipeline state containing at least a problem key.

Returns

Dict[str, Any]

A dictionary with updated keys for the pipeline state. At minimum this will include a bo_params entry and may contain an error entry if something goes wrong.

class honegumi_rag_assistant.nodes.RetrievalPlannerAgent

Bases: object

Plan retrieval strategy by analyzing information needs.

static plan_retrieval(state: HonegumiRAGState) → Dict[str, Any]

Analyze problem and skeleton to determine retrieval needs.

Parameters

stateHonegumiRAGState

The current pipeline state containing problem, bo_params, and skeleton_code.

Returns

Dict[str, Any]

Dictionary with: - retrieval_queries: List[str] of queries to execute in parallel - Empty list if no retrieval needed

class honegumi_rag_assistant.nodes.RetrieverAgent

Bases: object

Retrieve relevant documentation snippets for the current problem.

The retriever constructs a query by concatenating the natural language problem description with a JSON representation of the optimisation parameters. It then executes a similarity search against the configured vector store to return the top k most relevant chunks. If no vector store is configured or the required dependencies are missing the retriever returns an empty list.

static retrieve_context(state: HonegumiRAGState) → Dict[str, Any]

Retrieve documentation contexts based on a specific question.

Parameters

stateHonegumiRAGState

The current pipeline state containing retrieval_query with a specific question from the Code Writer agent.

Returns

Dict[str, Any]

A dictionary with keys: - contexts: list of context snippets (empty if retrieval fails) - retrieval_count: incremented counter - retrieval_query: cleared (set to None)

class honegumi_rag_assistant.nodes.ReviewerAgent

Bases: object

Perform LLM-based review and decide whether to approve or request revision.

static review_code(state: HonegumiRAGState) → Dict[str, Any]

Review the candidate code and decide to approve or revise.

Parameters

stateHonegumiRAGState

The current pipeline state containing candidate_code, review_count, and other context.

Returns

Dict[str, Any]

Either: - {“final_code”: str} if approved - {“critique_report”: List[str], “review_count”: int} if revision needed

class honegumi_rag_assistant.nodes.SkeletonGenerator

Bases: object

Generate the Honegumi skeleton code for the selected parameters.

Given a set of optimisation parameters (bo_params), this node instantiates the Honegumi template engine and renders the corresponding Ax script.

static generate_skeleton(state: HonegumiRAGState) → Dict[str, Any]

Generate a skeleton code file from the provided parameters.

Parameters

stateHonegumiRAGState

The current pipeline state containing at least a bo_params key.

Returns

Dict[str, Any]

A dictionary with keys skeleton_code and template_metadata. If an error occurs, an error key will also be set.