fix(agents/tools): parameterize processed_dir + translate HTTPException → ValueError

Replace top-level _execute_bbb/eeg/mri functions with closure factories
(_make_bbb/eeg/mri_executor) that (a) accept processed_dir so output paths
are no longer hard-coded relative strings, and (b) catch HTTPException from
route calls and re-raise as ValueError with a clean message.

Add build_default_tools(processed_dir=Path("data/processed")) keyword arg
for backwards-compatible parameterization.

Add 4 new tests: processed_dir threading, retrieve short-circuit with no
index, backwards-compat default, and HTTPException → ValueError translation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/agents/tools.py

@@ -73,66 +73,81 @@ class Tool:
 # ---------------------------------------------------------------------------
 
 
-def _execute_bbb(inp: BBBPipelineInput) -> BBBPipelineOutput:
-    """Predict + SHAP for a single SMILES, reusing the existing model surface."""
-    from src.api import routes as api_routes
-    from src.api.schemas import BBBPredictRequest
-
-    response = api_routes.predict_bbb(
-        BBBPredictRequest(smiles=inp.smiles, top_k=inp.top_k)
-    )
-    return BBBPipelineOutput(
-        smiles=inp.smiles,
-        label=response.label,
-        label_text=response.label_text,
-        confidence=response.confidence,
-        top_features=[f.model_dump() for f in response.top_features],
-        drift_z=response.drift_z,
-    )
-
-
-def _execute_eeg(inp: EEGPipelineInput) -> EEGPipelineOutput:
-    """Run the EEG pipeline via the existing route function (run_eeg)."""
-    from src.api.schemas import EEGRequest
-    from src.api import routes as api_routes
-
-    out_path = Path("data/processed/eeg_features.parquet")
-    response = api_routes.run_eeg(
-        EEGRequest(
+def _make_bbb_executor() -> Callable[[BBBPipelineInput], BBBPipelineOutput]:
+    """Closure factory: BBB permeability prediction + SHAP, translates HTTPException."""
+    def execute(inp: BBBPipelineInput) -> BBBPipelineOutput:
+        from src.api import routes as api_routes
+        from src.api.schemas import BBBPredictRequest
+        from fastapi import HTTPException
+        try:
+            response = api_routes.predict_bbb(
+                BBBPredictRequest(smiles=inp.smiles, top_k=inp.top_k)
+            )
+        except HTTPException as e:
+            raise ValueError(f"bbb tool failed: {e.detail}") from e
+        return BBBPipelineOutput(
+            smiles=inp.smiles,
+            label=response.label,
+            label_text=response.label_text,
+            confidence=response.confidence,
+            top_features=[f.model_dump() for f in response.top_features],
+            drift_z=response.drift_z,
+        )
+    return execute
+
+
+def _make_eeg_executor(processed_dir: Path) -> Callable[[EEGPipelineInput], EEGPipelineOutput]:
+    """Closure factory: EEG pipeline, writes output under processed_dir."""
+    def execute(inp: EEGPipelineInput) -> EEGPipelineOutput:
+        from src.api.schemas import EEGRequest
+        from src.api import routes as api_routes
+        from fastapi import HTTPException
+        out_path = processed_dir / "eeg_features.parquet"
+        try:
+            response = api_routes.run_eeg(
+                EEGRequest(
+                    input_path=inp.input_path,
+                    output_path=str(out_path),
+                    epoch_duration_s=inp.epoch_duration_s,
+                )
+            )
+        except HTTPException as e:
+            raise ValueError(f"eeg tool failed: {e.detail}") from e
+        return EEGPipelineOutput(
             input_path=inp.input_path,
-            output_path=str(out_path),
-            epoch_duration_s=inp.epoch_duration_s,
+            output_path=response.output_path,
+            rows=response.rows,
+            columns=response.columns,
+            duration_sec=response.duration_sec,
         )
-    )
-    return EEGPipelineOutput(
-        input_path=inp.input_path,
-        output_path=response.output_path,
-        rows=response.rows,
-        columns=response.columns,
-        duration_sec=response.duration_sec,
-    )
-
-
-def _execute_mri(inp: MRIPipelineInput) -> MRIPipelineOutput:
-    """Run the MRI pipeline via the existing route function (run_mri)."""
-    from src.api.schemas import MRIRequest
-    from src.api import routes as api_routes
-
-    out_path = Path("data/processed/mri_features.parquet")
-    response = api_routes.run_mri(
-        MRIRequest(
+    return execute
+
+
+def _make_mri_executor(processed_dir: Path) -> Callable[[MRIPipelineInput], MRIPipelineOutput]:
+    """Closure factory: MRI pipeline, writes output under processed_dir."""
+    def execute(inp: MRIPipelineInput) -> MRIPipelineOutput:
+        from src.api.schemas import MRIRequest
+        from src.api import routes as api_routes
+        from fastapi import HTTPException
+        out_path = processed_dir / "mri_features.parquet"
+        try:
+            response = api_routes.run_mri(
+                MRIRequest(
+                    input_dir=inp.input_dir,
+                    sites_csv=inp.sites_csv,
+                    output_path=str(out_path),
+                )
+            )
+        except HTTPException as e:
+            raise ValueError(f"mri tool failed: {e.detail}") from e
+        return MRIPipelineOutput(
             input_dir=inp.input_dir,
-            sites_csv=inp.sites_csv,
-            output_path=str(out_path),
+            output_path=response.output_path,
+            rows=response.rows,
+            columns=response.columns,
+            duration_sec=response.duration_sec,
         )
-    )
-    return MRIPipelineOutput(
-        input_dir=inp.input_dir,
-        output_path=response.output_path,
-        rows=response.rows,
-        columns=response.columns,
-        duration_sec=response.duration_sec,
-    )
+    return execute
 
 
 def _make_retrieve_executor(rag_index_dir: Path | None) -> Callable[[RetrieveContextInput], RetrieveContextOutput]:
@@ -151,7 +166,10 @@ def _make_retrieve_executor(rag_index_dir: Path | None) -> Callable[[RetrieveCon
     return execute
 
 
-def build_default_tools(rag_index_dir: Path | None) -> list[Tool]:
+def build_default_tools(
+    rag_index_dir: Path | None,
+    processed_dir: Path = Path("data/processed"),
+) -> list[Tool]:
     """Return the 4 tools the orchestrator gets by default."""
     return [
         Tool(
@@ -164,7 +182,7 @@ def build_default_tools(rag_index_dir: Path | None) -> list[Tool]:
             ),
             input_model=BBBPipelineInput,
             output_model=BBBPipelineOutput,
-            execute=_execute_bbb,
+            execute=_make_bbb_executor(),
         ),
         Tool(
             name="run_eeg_pipeline",
@@ -176,7 +194,7 @@ def build_default_tools(rag_index_dir: Path | None) -> list[Tool]:
             ),
             input_model=EEGPipelineInput,
             output_model=EEGPipelineOutput,
-            execute=_execute_eeg,
+            execute=_make_eeg_executor(processed_dir),
         ),
         Tool(
             name="run_mri_pipeline",
@@ -187,7 +205,7 @@ def build_default_tools(rag_index_dir: Path | None) -> list[Tool]:
             ),
             input_model=MRIPipelineInput,
             output_model=MRIPipelineOutput,
-            execute=_execute_mri,
+            execute=_make_mri_executor(processed_dir),
         ),
         Tool(
             name="retrieve_context",

tests/agents/test_tools.py

@@ -93,3 +93,36 @@ class TestBuildDefaultTools:
         assert "sites_csv" in MRIPipelineInput.model_fields
         assert "query" in RetrieveContextInput.model_fields
         assert "k" in RetrieveContextInput.model_fields
+
+    def test_retrieve_context_short_circuits_when_no_index(self) -> None:
+        tools = build_default_tools(rag_index_dir=None)
+        retrieve = next(t for t in tools if t.name == "retrieve_context")
+        out = retrieve.invoke({"query": "anything", "k": 3})
+        assert out == {"query": "anything", "chunks": []}
+
+    def test_processed_dir_parameter_threads_to_executors(self, tmp_path: Path) -> None:
+        # build_default_tools should accept processed_dir; executors should
+        # eventually write under it (we don't invoke the pipelines here, just
+        # verify the parameter is accepted and tools are built).
+        tools = build_default_tools(rag_index_dir=None, processed_dir=tmp_path)
+        names = {t.name for t in tools}
+        assert "run_eeg_pipeline" in names
+        assert "run_mri_pipeline" in names
+
+    def test_default_processed_dir_when_omitted(self) -> None:
+        # backwards-compat: omitting processed_dir keeps existing behavior
+        tools = build_default_tools(rag_index_dir=None)
+        # just ensure no exception and 4 tools returned
+        assert len(tools) == 4
+
+    def test_bbb_executor_translates_httpexception_to_valueerror(self) -> None:
+        from unittest.mock import patch
+        from fastapi import HTTPException
+
+        tools = build_default_tools(rag_index_dir=None)
+        bbb = next(t for t in tools if t.name == "run_bbb_pipeline")
+
+        with patch("src.api.routes.predict_bbb",
+                   side_effect=HTTPException(status_code=503, detail="model missing")):
+            with pytest.raises(ValueError, match="bbb tool failed"):
+                bbb.invoke({"smiles": "CCO"})