feat: add reproducibility controls and deterministic search RNG (#179)

* feat: add reproducibility controls and deterministic search RNG

* chore: bump package version to 1.3.2

Author: marcellodebernardi

config.yaml.template

@@ -93,18 +93,18 @@
 
 # LLM for hypothesiser agent
 # Type: string
-# Default: "openai/gpt-5-mini"
-# hypothesiser_llm: "openai/gpt-5-mini"
+# Default: "anthropic/claude-sonnet-4-5-20250929"
+# hypothesiser_llm: "anthropic/claude-sonnet-4-5-20250929"
 
 # LLM for planner agent
 # Type: string
-# Default: "openai/gpt-5-mini"
-# planner_llm: "openai/gpt-5-mini"
+# Default: "anthropic/claude-sonnet-4-5-20250929"
+# planner_llm: "anthropic/claude-sonnet-4-5-20250929"
 
 # LLM for insight extractor agent
 # Type: string
-# Default: "openai/gpt-5-mini"
-# insight_extractor_llm: "openai/gpt-5-mini"
+# Default: "anthropic/claude-sonnet-4-5-20250929"
+# insight_extractor_llm: "anthropic/claude-sonnet-4-5-20250929"
 
 # ------------------------------------------------------------
 # Logging & Agent Settings

plexe/CODE_INDEX.md

@@ -1,6 +1,6 @@
 # Code Index: plexe
 
-> Generated on 2026-02-26 19:02:04
+> Generated on 2026-02-27 14:59:37
 
 Code structure and public interface documentation for the **plexe** package.
 
@@ -149,11 +149,13 @@ Configuration for plexe.
 - `validate_model_providers(cls, v: dict[str, str], info) -> dict[str, str]` - Validate that all model provider references exist.
 
 **`Config`** - Configuration for model building workflow.
+- `get_temperature(self, agent_name: str) -> float` - Resolve temperature for a given agent, falling back to default_temperature.
 - `settings_customise_sources(cls, settings_cls, init_settings, env_settings, dotenv_settings, file_secret_settings)` - Customize settings source priority.
 - `validate_nn_training_settings(self) -> 'Config'` - Ensure neural network defaults do not exceed the configured cap.
 - `parse_otel_headers_from_env(self) -> 'Config'` - Parse OTEL_EXPORTER_OTLP_HEADERS (comma-separated key=value pairs).
 
 **Functions:**
+- `detect_installed_frameworks() -> list[str]` - Detect which ML frameworks are installed and importable.
 - `get_routing_for_model(config: RoutingConfig | None, model_id: str) -> tuple[str | None, dict[str, str]]` - Get routing configuration for a specific model ID.
 - `setup_logging(config: Config) -> logging.Logger` - Configure logging for the plexe package.
 - `setup_litellm(config: Config) -> None` - Configure LiteLLM global settings.
@@ -302,7 +304,7 @@ Amazon S3 storage helper.
 Universal entry point for plexe.
 
 **Functions:**
-- `main(intent: str, data_refs: list[str], integration: WorkflowIntegration | None, spark_mode: str, user_id: str, experiment_id: str, max_iterations: int, work_dir: Path, test_dataset_uri: str | None, enable_final_evaluation: bool, max_epochs: int | None, allowed_model_types: list[str] | None, is_retrain: bool, original_model_uri: str | None, original_experiment_id: str | None, auto_mode: bool, user_feedback: dict | None, enable_otel: bool, otel_endpoint: str | None, otel_headers: dict[str, str] | None, external_storage_uri: str | None, csv_delimiter: str, csv_header: bool)` - Main model building function.
+- `main(intent: str, data_refs: list[str], integration: WorkflowIntegration | None, spark_mode: str, user_id: str, experiment_id: str, max_iterations: int, global_seed: int | None, work_dir: Path, test_dataset_uri: str | None, enable_final_evaluation: bool, max_epochs: int | None, allowed_model_types: list[str] | None, is_retrain: bool, original_model_uri: str | None, original_experiment_id: str | None, auto_mode: bool, user_feedback: dict | None, enable_otel: bool, otel_endpoint: str | None, otel_headers: dict[str, str] | None, external_storage_uri: str | None, csv_delimiter: str, csv_header: bool)` - Main model building function.
 
 ---
 ## `models.py`
@@ -367,7 +369,7 @@ Model retraining functionality.
 PiEvolve-inspired evolutionary search policy with adaptive state analysis.
 
 **`EvolutionarySearchPolicy`** - PiEvolve-inspired probabilistic action selection with adaptive search state analysis.
-- `__init__(self, num_drafts: int, debug_prob: float, max_debug_depth: int)`
+- `__init__(self, num_drafts: int, debug_prob: float, max_debug_depth: int, seed: int | None)`
 - `decide_next_solution(self, journal: SearchJournal, context: BuildContext, iteration: int, max_iterations: int) -> Solution | None` - PiEvolve-style probabilistic action selection based on search state.
 - `should_stop(self, journal: SearchJournal, iteration: int, max_iterations: int) -> bool` - Enhanced stopping criteria with intelligent early stopping.
 
@@ -417,7 +419,7 @@ Search policy abstract base class.
 Tree-search policy inspired by AIDE.
 
 **`TreeSearchPolicy`** - AIDE-inspired tree-search with draft/debug/improve stages.
-- `__init__(self, num_drafts: int, debug_prob: float, max_debug_depth: int)`
+- `__init__(self, num_drafts: int, debug_prob: float, max_debug_depth: int, seed: int | None)`
 - `decide_next_solution(self, journal: SearchJournal, context: BuildContext, iteration: int, max_iterations: int) -> Solution | None` - Decide which solution node to expand next.
 - `should_stop(self, journal: SearchJournal, iteration: int, max_iterations: int) -> bool` - Decide if search should terminate early.
 

plexe/agents/baseline_builder.py

@@ -131,6 +131,7 @@ def _build_agent(self, val_sample_df) -> CodeAgent:
             ),
             model=PlexeLiteLLMModel(
                 model_id=self.llm_model,
+                temperature=self.config.get_temperature("baseline_builder"),
                 api_base=api_base,
                 extra_headers=headers,
             ),

plexe/agents/dataset_splitter.py

@@ -137,6 +137,7 @@ def _build_agent(self) -> CodeAgent:
             ),
             model=PlexeLiteLLMModel(
                 model_id=self.llm_model,
+                temperature=self.config.get_temperature("dataset_splitter"),
                 api_base=api_base,
                 extra_headers=headers,
             ),

plexe/agents/feature_processor.py

@@ -72,6 +72,7 @@ def _build_agent(self, train_sample_df, val_sample_df) -> CodeAgent:
             instructions=instructions,
             model=PlexeLiteLLMModel(
                 model_id=self.llm_model,
+                temperature=self.config.get_temperature("feature_processor"),
                 api_base=api_base,
                 extra_headers=headers,
             ),

plexe/agents/hypothesiser.py

@@ -127,9 +127,9 @@ def _build_agent(self) -> CodeAgent:
             instructions=instructions,
             model=PlexeLiteLLMModel(
                 model_id=self.llm_model,
+                temperature=self.config.get_temperature("hypothesiser"),
                 api_base=api_base,
                 extra_headers=headers,
-                reasoning_effort="minimal",
             ),
             verbosity_level=self.config.agent_verbosity_level,
             tools=[get_save_hypothesis_tool(self.context, self.expand_solution_id)],

plexe/agents/insight_extractor.py

@@ -127,9 +127,9 @@ def _build_agent(self) -> CodeAgent:
             instructions=instructions,
             model=PlexeLiteLLMModel(
                 model_id=self.llm_model,
+                temperature=self.config.get_temperature("insight_extractor"),
                 api_base=api_base,
                 extra_headers=headers,
-                reasoning_effort="minimal",
             ),
             verbosity_level=self.config.agent_verbosity_level,
             tools=[get_save_insight_tool(self.insight_store)],

plexe/agents/layout_detector.py

@@ -123,6 +123,7 @@ def _build_agent(self) -> CodeAgent:
             ),
             model=PlexeLiteLLMModel(
                 model_id=self.llm_model,
+                temperature=self.config.get_temperature("layout_detector"),
                 api_base=api_base,
                 extra_headers=headers,
             ),

plexe/agents/metric_implementer.py

@@ -90,6 +90,7 @@ def _build_agent(self) -> CodeAgent:
             ),
             model=PlexeLiteLLMModel(
                 model_id=self.llm_model,
+                temperature=self.config.get_temperature("metric_implementer"),
                 api_base=api_base,
                 extra_headers=headers,
             ),

plexe/agents/metric_selector.py

@@ -74,6 +74,7 @@ def _build_agent(self) -> CodeAgent:
             ),
             model=PlexeLiteLLMModel(
                 model_id=self.llm_model,
+                temperature=self.config.get_temperature("metric_selector"),
                 api_base=api_base,
                 extra_headers=headers,
             ),