honegumi_rag_assistant package

Subpackages

honegumi_rag_assistant.nodes package

Submodules

honegumi_rag_assistant.app_config module

Configuration management for the Honegumi RAG Assistant.

This module defines a simple dataclass, Settings, that holds configuration values for the pipeline. These values can be overridden via environment variables or programmatically at runtime. A global instance, settings, is created on import for convenience.

The following configuration options are supported:

model_name: The name of the language model to use when invoking the OpenAI API. Defaults to "gpt-5". Override via the OPENAI_MODEL_NAME environment variable.
openai_api_key: Your OpenAI API key. The assistant will raise an exception if attempting to call the API when this value is empty. Override via the LLM_API_KEY environment variable.
retrieval_vectorstore_path: Path to a serialized vector store (e.g. FAISS index) containing the Ax documentation. When supplied, the retriever will attempt to load this index and perform semantic searches. Override via the AX_DOCS_VECTORSTORE_PATH environment variable.
retrieval_top_k: The number of documents to return from the retriever. Defaults to 5. Override via the RETRIEVAL_TOP_K environment variable.
output_dir: Directory where the generated scripts and artefacts will be saved. Defaults to "./honegumi_rag_output". Override via the OUTPUT_DIR environment variable.

class honegumi_rag_assistant.app_config.Settings(model_name: str = 'gpt-5', code_writer_model: str = 'gpt-5', reviewer_model: str = 'gpt-4o', retrieval_planner_model: str = 'gpt-5', openai_api_key: str = '', retrieval_vectorstore_path: str = '', retrieval_top_k: int = 5, output_dir: str = './honegumi_rag_output', debug: bool = False, stream_code: bool = False)[source]

Bases: object

Container for configuration values.

Attributes

model_namestr: Identifier of the OpenAI model to use for all LLM calls. A sensible default of "gpt-5" is provided but can be overridden via the OPENAI_MODEL_NAME environment variable.
code_writer_modelstr: Model to use specifically for the Code Writer agent. Defaults to model_name if not specified. Override via CODE_WRITER_MODEL environment variable.
reviewer_modelstr: Model to use specifically for the Reviewer agent. Defaults to model_name if not specified. Override via REVIEWER_MODEL environment variable.
retrieval_planner_modelstr: Model to use specifically for the Retrieval Planner agent. Defaults to model_name if not specified. Override via RETRIEVAL_PLANNER_MODEL environment variable.
openai_api_keystr: Secret API key used to authenticate with the OpenAI API. You must set this in your environment or the pipeline will raise an exception when attempting to call the LLM.
retrieval_vectorstore_pathstr: Optional path to a vector store used by the retriever to fetch Ax documentation. If empty, no retrieval will be performed and the contexts field of the state will remain an empty list.
retrieval_top_kint: Number of context snippets to return from the vector store. A small number (5–10) keeps the LLM context manageable.
output_dirstr: Directory where the generated code and artefacts should be written by the run() function. The directory will be created if it does not exist.
debugbool: Whether to enable debug mode with verbose output showing all decisions, parameters, and intermediate steps. Set at runtime via CLI flag. Defaults to False.

code_writer_model: str = 'gpt-5'

debug: bool = False

model_name: str = 'gpt-5'

openai_api_key: str = ''

output_dir: str = './honegumi_rag_output'

reload_from_env()[source]

Reload settings from environment variables.

Useful when environment variables are set after the module is imported, such as in Jupyter/Colab notebooks.

retrieval_planner_model: str = 'gpt-5'

retrieval_top_k: int = 5

retrieval_vectorstore_path: str = ''

reviewer_model: str = 'gpt-4o'

stream_code: bool = False

honegumi_rag_assistant.build_vector_store module

Build a FAISS vector store from Ax documentation.

This script automates the process of: 1. Cloning Ax repository from GitHub 2. Extracting documentation from markdown files 3. Generating OpenAI embeddings 4. Building and saving a FAISS vector database

Usage:: python scripts/build_vector_store.py python scripts/build_vector_store.py –output custom/path python scripts/build_vector_store.py –update # Refresh existing store

honegumi_rag_assistant.build_vector_store.build_faiss_index(documents: List[Document], openai_api_key: str, embedding_model: str = 'text-embedding-3-large') → FAISS[source]

Build a FAISS vector store from documents.

Uses text-embedding-3-large for better retrieval quality. This model has 3072 dimensions vs 1536 for the small model, providing more nuanced semantic understanding.

Parameters:

documents – List of LangChain Document objects
openai_api_key – OpenAI API key for embeddings
embedding_model – OpenAI embedding model (default: text-embedding-3-large)

Returns:

FAISS vector store

honegumi_rag_assistant.build_vector_store.chunk_documents(documents: List[Dict[str, str]], chunk_size: int = 2000, chunk_overlap: int = 400) → List[Document][source]

Split documents into chunks for retrieval.

Uses larger chunks (2000 chars) to keep code examples and explanations together. Larger overlap (400 chars) ensures context continuity across chunks.

Parameters:

documents – List of dicts with ‘content’, ‘title’, ‘url’
chunk_size – Target size for each chunk in characters (default: 2000)
chunk_overlap – Overlap between chunks to preserve context (default: 400)

Returns:

List of LangChain Document objects

honegumi_rag_assistant.build_vector_store.clone_ax_repo(temp_dir: Path, ax_version: str = '0.4.3') → Path[source]

Clone the Ax repository from GitHub at a specific version.

Parameters:

temp_dir – Temporary directory for cloning
ax_version – Git tag/branch to clone (default: “0.4.3” to match honegumi)

Returns:

Path to cloned repository

honegumi_rag_assistant.build_vector_store.extract_docs_from_repo(repo_path: Path) → List[Dict[str, str]][source]

Extract documentation from cloned Ax repository. Includes both /docs markdown files and /tutorials notebooks.

Parameters:: repo_path – Path to cloned Ax repository
Returns:: List of dictionaries with ‘url’, ‘title’, and ‘content’

honegumi_rag_assistant.build_vector_store.main()[source]

honegumi_rag_assistant.extractors module

Lightweight wrappers around the OpenAI function calling API used by the Honegumi RAG Assistant.

This module defines extractor classes that use structured output via Pydantic models and LangChain’s function calling with validation for robust parameter extraction. The ParameterExtractor exposes an invoke() method that accepts a problem description and returns a validated dictionary containing the selected Bayesian optimisation parameters.

The structured output approach uses LangChain’s with_structured_output() which provides automatic validation, retry on validation failures, and type coercion through Pydantic schemas.

class honegumi_rag_assistant.extractors.ConstraintSpec(*, type: Literal['sum', 'order', 'linear', 'composition'], parameters: List[str], description: str, total: float | None = None)[source]

Bases: BaseModel

Represents an optimization constraint.

description: str

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

parameters: List[str]

total: float | None

type: Literal['sum', 'order', 'linear', 'composition']

class honegumi_rag_assistant.extractors.ObjectiveSpec(*, name: str, goal: Literal['maximize', 'minimize'], threshold: float | None = None, units: str | None = None)[source]

Bases: BaseModel

Represents an optimization objective.

goal: Literal['maximize', 'minimize']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

threshold: float | None

units: str | None

class honegumi_rag_assistant.extractors.OptimizationParameters(*, objective: Literal['Single', 'Multi'], model: Literal['Default', 'Custom', 'Fully Bayesian'], task: Literal['Single', 'Multi'], existing_data: bool, sum_constraint: bool, order_constraint: bool, linear_constraint: bool, composition_constraint: bool, categorical: bool, custom_threshold: bool, synchrony: Literal['Batch', 'Single'], visualize: bool)[source]

Bases: BaseModel

Pydantic model for Bayesian optimization parameters.

This model defines the schema for optimization parameters that will be extracted from the user’s problem description using structured output. All fields are required and will be validated automatically.

categorical: bool

composition_constraint: bool

custom_threshold: bool

existing_data: bool

linear_constraint: bool

model: Literal['Default', 'Custom', 'Fully Bayesian']

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

objective: Literal['Single', 'Multi']

order_constraint: bool

sum_constraint: bool

synchrony: Literal['Batch', 'Single']

task: Literal['Single', 'Multi']

validate_parameter_combinations() → OptimizationParameters[source]

Validate that parameter combinations are compatible.

Based on Honegumi’s is_incompatible function, certain parameter combinations are invalid:

custom_threshold=True requires objective=”Multi” (Custom thresholds only apply to multi-objective optimization)
model=”Fully Bayesian” requires custom_gen (not exposed in this model, so we document this limitation)

Raises

ValueError: If an incompatible parameter combination is detected.

visualize: bool

class honegumi_rag_assistant.extractors.ParameterExtractor[source]

Bases: object

Extract optimisation parameters using structured output.

This class uses LangChain’s ChatOpenAI with structured output to reliably extract Bayesian optimization parameters from a natural language problem description.

This is the second stage of a two-stage extraction process. It can optionally accept a ProblemStructure from the first stage to improve grid selection accuracy by reasoning over explicit problem elements.

The structured output approach provides automatic validation via Pydantic, retry logic on validation failures, and type coercion, making it more robust than manual JSON parsing.

Note: LangChain’s with_structured_output() internally uses validation and retry mechanisms similar to TrustCall when method=’function_calling’ is used (the default).

classmethod invoke(prompt: str, problem_structure: Dict[str, Any] | None = None) → Dict[str, Any][source]

Invoke the LLM with a problem description and parse the result.

Parameters

promptstr: The user’s problem description. This text should explain the optimisation task in natural language.
problem_structureOptional[Dict[str, Any]], optional: The extracted problem structure from ProblemStructureExtractor. If provided, this will be included in the prompt to improve grid selection accuracy.

Returns

Dict[str, Any]: A dictionary with a single key, bo_params, containing the parsed and validated optimisation parameters as a dict. If the call fails, bo_params will be None and an error key will contain the error message.

class honegumi_rag_assistant.extractors.ProblemStructure(*, search_space: ~typing.List[~honegumi_rag_assistant.extractors.SearchSpaceParameter], objective: ~typing.List[~honegumi_rag_assistant.extractors.ObjectiveSpec], budget: int | None = None, batch_size: int | None = None, noise_model: bool = True, constraints: ~typing.List[~honegumi_rag_assistant.extractors.ConstraintSpec] = <factory>, historical_data_points: int | None = None, model_preference: ~typing.Literal['Default', 'Fully Bayesian', 'Custom'] | None = None)[source]

Bases: BaseModel

Structured representation of the optimization problem following the solution format.

This intermediate representation extracts the key elements of the optimization problem in the same structure as the ‘solution’ field in test problems. This ensures consistency and makes validation straightforward.

Structure matches:

solution:: search_space: […] objective: {…} or [{…}, …] budget: int batch_size: int (optional) noise_model: bool constraints: […]

batch_size: int | None

budget: int | None

constraints: List[ConstraintSpec]

historical_data_points: int | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_preference: Literal['Default', 'Fully Bayesian', 'Custom'] | None

noise_model: bool

objective: List[ObjectiveSpec]

search_space: List[SearchSpaceParameter]

validate_minimum_structure() → ProblemStructure[source]

Validate that the problem structure has minimum required elements.

A valid optimization problem must have: - At least 1 objective (what are we optimizing?) - Ideally at least 1 parameter (what are we optimizing over?)

This validator ensures the LLM extracted meaningful structure and fails fast if extraction was incomplete.

Raises

ValueError: If the structure is missing critical elements.

class honegumi_rag_assistant.extractors.ProblemStructureExtractor[source]

Bases: object

Extract structured problem representation from natural language.

This is the first stage of a two-stage extraction process. It extracts the explicit problem structure (parameters, objectives, constraints) before making grid selections. This intermediate representation helps improve accuracy by forcing explicit reasoning about problem elements.

classmethod invoke(prompt: str) → Dict[str, Any][source]

Extract problem structure from natural language description.

Parameters

promptstr: The user’s problem description in natural language.

Returns

Dict[str, Any]: A dictionary with a ‘problem_structure’ key containing the extracted structure, or an ‘error’ key if extraction failed.

class honegumi_rag_assistant.extractors.SearchSpaceParameter(*, name: str, type: Literal['continuous', 'categorical'], bounds: List[float] | None = None, categories: List[str] | None = None, units: str | None = None)[source]

Bases: BaseModel

Represents a single parameter in the search space.

bounds: List[float] | None

categories: List[str] | None

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

type: Literal['continuous', 'categorical']

units: str | None

honegumi_rag_assistant.orchestrator module

Orchestrate the Honegumi RAG Assistant workflow.

This module assembles the various nodes defined in honegumi_rag_assistant.nodes into a LangGraph state machine. The build_graph() function constructs the graph and returns a compiled version ready for execution. The run() convenience function reads a problem description from disk, runs the graph and writes the resulting Python script to the configured output directory.

You can customise the workflow by modifying the nodes or adding new conditional branches. See the LangGraph documentation for further details on graph construction.

honegumi_rag_assistant.orchestrator.build_graph(skip_review: bool = False, enable_review: bool = False) → Any[source]

Construct and return the compiled LangGraph for the agentic pipeline.

Parameters

skip_reviewbool, optional: DEPRECATED: Use enable_review instead. If True, skip the review step. Defaults to False.
enable_reviewbool, optional: If True, include the reviewer step. Defaults to False (reviewer disabled by default).

Returns

StateGraph

A compiled LangGraph instance with: - Retrieval Planner → Parallel Retrieval (fan-out/fan-in) - Optional Reviewer (if enable_review=True)

If LangGraph is unavailable, a RuntimeError will be raised.

honegumi_rag_assistant.orchestrator.run(problem_txt_path: str, output_dir: str | None = None, debug: bool = False) → str[source]

Run the full pipeline on the given problem file and write the code to disk.

Parameters

problem_txt_pathstr: Path to a UTF‑8 encoded text file containing the natural language problem description.
output_dirstr or None, optional: Directory where the generated script should be saved. If None, the value from settings.output_dir is used.
debugbool, optional: Whether to enable debug mode with verbose output. Defaults to False.

Returns

str: The generated Python script. Raises if the pipeline fails.

honegumi_rag_assistant.orchestrator.run_from_text(problem: str, output_dir: str | None = None, debug: bool = False, run_id: str | None = None, skip_review: bool = False, enable_review: bool = False) → str[source]

Run the full pipeline on a problem description string and optionally write the code to disk.

Parameters

problemstr: Natural language problem description.
output_dirstr or None, optional: Directory where the generated script should be saved. If None, the code is NOT saved to disk (only returned).
debugbool, optional: Whether to enable debug mode with verbose output. Defaults to False.
run_idstr or None, optional: Unique identifier for this run (used for thread ID and output filename). If None, a hash of the problem text will be used.
skip_reviewbool, optional: DEPRECATED: Use enable_review instead. If True, skip the review step. Defaults to False.
enable_reviewbool, optional: If True, enable the reviewer step. Defaults to False (reviewer disabled by default).

Returns

str: The generated Python script. Raises if the pipeline fails.

honegumi_rag_assistant.orchestrator.run_from_text_with_state(problem: str, output_dir: str | None = None, run_id: str | None = None) → Dict[str, Any][source]

Run the pipeline and return the full state (for batch processing).

Parameters

problemstr: Natural language problem description.
output_dirstr or None, optional: Directory where the generated script should be saved. If None, the value from settings.output_dir is used.
run_idstr or None, optional: Unique identifier for this run. If None, a hash will be used.

Returns

Dict[str, Any]: Dictionary containing: - problem: Original problem text - bo_params: Extracted parameters (dict) - problem_structure: Stage 1 extracted structure (search space, objectives, constraints) - skeleton_code: Generated skeleton - retrieval_count: Number of retrievals performed - retrieval_queries: List of questions asked - review_count: Number of reviews performed - critique_reports: List of review feedback - contexts: Retrieved documentation snippets - final_code: Generated Python code - error: Error message if failed (or None)

honegumi_rag_assistant.states module

Shared pipeline state definitions for the Honegumi RAG Assistant.

This module defines a single TypedDict describing the state passed between nodes in the LangGraph. Using a strongly typed state helps catch errors at wiring time and makes it explicit which keys are available to each node. Whenever a node returns a dictionary, the returned keys must correspond to entries on this type.

Fields marked with typing_extensions.Annotated and operator.add will be automatically concatenated across multiple calls to the same node. This mechanism is used to aggregate document contexts, critique reports and issue evidence as the agent loops through retries.

class honegumi_rag_assistant.states.HonegumiRAGState[source]

Bases: TypedDict

State dictionary propagated through the LangGraph pipeline.

The keys in this dictionary mirror the high‑level stages of the agentic workflow. Nodes mutate the state by returning a subset of these keys in their output dictionaries; the LangGraph runtime then merges the outputs back into the global state. Keys annotated with operator.add are concatenated across iterations allowing the pipeline to accumulate evidence and critiques.

Attributes

problemstr: The original natural language description of the user’s optimisation problem. This value is set at the beginning of the pipeline and never modified.
bo_paramsOptional[Dict[str, Any]]: A dictionary of optimisation parameters returned by the ParameterSelector node. It contains choices such as objective, model, and constraint flags. If the parameter selection fails this field may remain None.
problem_structureOptional[Dict[str, Any]]: The extracted problem structure from Stage 1 of parameter selection. Contains search_space, objectives, constraints, and experimental setup details. This is used as input for Stage 2 grid parameter selection.
skeleton_codeOptional[str]: The raw Python code skeleton generated by Honegumi. This skeleton contains the structure of the Ax optimisation workflow but lacks problem‑specific logic.
template_metadataOptional[Dict[str, Any]]: Additional metadata about the generated skeleton, such as template names, version information or hashes. Not used by downstream nodes but exposed for observability.
contextsList[Dict[str, Any]]: A list of context snippets retrieved from the Ax documentation. Each entry in the list should contain at least a text field with the content and may include source, url or other metadata. The retriever manually accumulates contexts across multiple retrievals within a single code generation cycle.
candidate_codeOptional[str]: A provisional version of the final Python script produced by the CodeWriterAgent. This field is overwritten on each iteration of code writing.
critique_reportAnnotated[List[str], operator.add]: A list of critiques or observations produced by the code writer or reviewer. The list is extended on each pass allowing successive agents to append feedback for debugging.
confidenceOptional[float]: A numeric confidence score (0.0–1.0) associated with the generated code. Downstream nodes may use this value to decide whether to trigger a fallback or attempt a repair.
final_codeOptional[str]: The final, approved Python script ready to be delivered to the user. This value is set by the ReviewerAgent.
errorOptional[str]: An error message set by any node if unrecoverable problems are encountered. The presence of an error should cause the pipeline to abort early in production deployments.
retrieval_countint: Counter tracking how many times the retrieval agent has been invoked during the current code writing iteration. Limited to a maximum of 3 to prevent infinite loops.
review_countint: Counter tracking how many times the code has been sent back for revision by the reviewer. Limited to a maximum of 2 to prevent infinite revision loops.
retrieval_queryOptional[str]: The specific question generated by the CodeWriterAgent to query the Ax documentation. This is used by the RetrieverAgent to perform targeted searches.

bo_params: Dict[str, Any] | None

candidate_code: str | None

confidence: float | None

contexts: Any]], <function merge_contexts at 0x7f57fff35940>]

critique_report: List[str], <built-in function add>]

error: str | None

final_code: str | None

problem: str

problem_structure: Dict[str, Any] | None

retrieval_count: int

retrieval_queries: List[str]

retrieval_query: str | None

review_count: int

skeleton_code: str | None

template_metadata: Dict[str, Any] | None

vectorstore_missing: Annotated[bool | None, <function merge_vectorstore_flag at 0x7f57fff359e0>]

honegumi_rag_assistant.states.merge_contexts(left: List[Dict[str, Any]] | None, right: List[Dict[str, Any]] | None) → List[Dict[str, Any]][source]

Custom reducer for contexts that accumulates contexts from parallel retrievers.

For parallel retrieval with Send API, we need to ACCUMULATE contexts from all parallel branches. This reducer concatenates left and right lists.

This differs from operator.add in that it handles None values gracefully.

honegumi_rag_assistant.states.merge_vectorstore_flag(left: bool | None, right: bool | None) → bool[source]

Custom reducer for vectorstore_missing flag.

If ANY parallel retriever reports missing vector store, the flag should be True. This is an OR operation: True if either left or right is True.

honegumi_rag_assistant.timing_utils module

Timing utilities for measuring node execution time.

This module provides a simple decorator to time node execution and print the results in a user-friendly format.

honegumi_rag_assistant.timing_utils.time_node(node_name: str) → Callable[source]

Decorator to time a node’s execution and print the result.

Only prints timing information when debug mode is enabled.

Parameters

node_namestr: Human-readable name of the node (e.g., “Parameter Selector”)

Returns

Callable: Decorated function that prints timing information

Module contents

The honegumi_rag_assistant package exposes a simple API for building and executing an agentic workflow that generates Bayesian optimisation code from a natural language problem description. This package uses a LangGraph state machine under the hood to orchestrate a collection of autonomous nodes that each perform a single function in the overall pipeline:

The ParameterSelector node parses the free‑form problem text and selects an appropriate set of optimisation parameters via a large language model using the OpenAI function calling interface.
The SkeletonGenerator node calls into the Honegumi template engine to produce a deterministic code skeleton for the Ax platform, based on the selected parameters.
The RetrieverAgent queries a vector store of the Ax documentation to fetch relevant context snippets that can be passed to the code writing model. If no vector store is configured the retriever gracefully returns an empty list.
The CodeWriterAgent writes the final Python script by editing the skeleton in the context of the user’s problem and any retrieved documentation. A simple self‑check is performed to ensure the skeleton’s structure is preserved.
The ReviewerAgent performs a final sanity check on the generated code and either approves it or flags an error.

The root of this package exposes two helper functions:

build_graph(): Construct the LangGraph state machine for the workflow. You can customise or extend this graph by importing and wiring additional nodes.
run(): Execute the pipeline on a given problem statement and write the generated code to disk. This function is suitable for use in command‑line interfaces or notebooks.

See the module docstrings and individual classes for more details.