feat(api): POST /agent/run endpoint (orchestrator + RAG, stub-injectable)

src/api/main.py

@@ -11,6 +11,7 @@ from src.api.routes import (
     predict_router,
     explain_router,
     experiments_router,
+    agent_router,
 )
 from src.api.schemas import HealthResponse
 
@@ -24,6 +25,7 @@ app.include_router(pipeline_router)
 app.include_router(predict_router)
 app.include_router(explain_router)
 app.include_router(experiments_router)
+app.include_router(agent_router)
 
 
 @app.get("/health", response_model=HealthResponse)

src/api/routes.py

@@ -18,6 +18,9 @@ import pandas as pd
 from fastapi import APIRouter, HTTPException
 
 from src.api.schemas import (
+    AgentRunRequest,
+    AgentRunResponse,
+    AgentToolTraceItem,
     BBBExplainRequest,
     BBBExplainResponse,
     BBBPredictRequest,
@@ -500,3 +503,63 @@ def diff_runs(req: RunDiffRequest) -> RunDiffResponse:
             )
         )
     return RunDiffResponse(rows=rows)
+
+
+# --- Agent router ----------------------------------------------------------
+
+agent_router = APIRouter(prefix="/agent")
+
+
+_DEFAULT_RAG_INDEX_DIR = Path("data/processed/faiss_index")
+_AGENT_MODEL_ENV = "NEUROBRIDGE_AGENT_MODEL"
+_AGENT_DEFAULT_MODEL = "google/gemini-2.0-flash-exp:free"
+
+
+def _build_orchestrator():
+    """Construct the default orchestrator. Patchable in tests."""
+    from openai import OpenAI
+
+    from src.agents.orchestrator import Orchestrator
+    from src.agents.prompts import ORCHESTRATOR_SYSTEM_PROMPT
+    from src.agents.tools import build_default_tools
+
+    api_key = os.environ.get("OPENROUTER_API_KEY")
+    if not api_key:
+        raise HTTPException(
+            status_code=503,
+            detail="OPENROUTER_API_KEY not set; agent surface unavailable.",
+        )
+    client = OpenAI(
+        base_url="https://openrouter.ai/api/v1",
+        api_key=api_key,
+        timeout=30.0,
+    )
+    rag_dir = _DEFAULT_RAG_INDEX_DIR if _DEFAULT_RAG_INDEX_DIR.exists() else None
+    tools = build_default_tools(rag_index_dir=rag_dir)
+    model = os.environ.get(_AGENT_MODEL_ENV, _AGENT_DEFAULT_MODEL)
+    return Orchestrator(
+        llm_client=client,
+        tools=tools,
+        system_prompt=ORCHESTRATOR_SYSTEM_PROMPT,
+        model=model,
+        max_steps=5,
+    )
+
+
+@agent_router.post("/run", response_model=AgentRunResponse)
+def run_agent(req: AgentRunRequest) -> AgentRunResponse:
+    """Run the orchestrator on `user_input`. Picks a pipeline + grounds via RAG."""
+    orch = _build_orchestrator()
+    user_text = req.user_input
+    if req.user_question:
+        user_text = f"{req.user_input}\n\nUser question: {req.user_question}"
+    result = orch.run(user_text)
+    return AgentRunResponse(
+        text=result.text,
+        trace=[
+            AgentToolTraceItem(name=t.name, args=t.args, result=t.result, error=t.error)
+            for t in result.trace
+        ],
+        model=result.model,
+        finish_reason=result.finish_reason,
+    )

src/api/schemas.py

@@ -228,3 +228,27 @@ class RunDiffRow(BaseModel):
 class RunDiffResponse(BaseModel):
     """Response for POST /experiments/diff: side-by-side metric/param diff."""
     rows: list[RunDiffRow]
+
+
+# --- Agent surface (orchestrator + RAG) ------------------------------------
+
+class AgentRunRequest(BaseModel):
+    """User input to the orchestrator."""
+    user_input: str = Field(..., min_length=1, description="SMILES, file path, or directory path")
+    user_question: str | None = Field(
+        None, description="Optional natural-language question to language-match the response"
+    )
+
+
+class AgentToolTraceItem(BaseModel):
+    name: str
+    args: dict = Field(default_factory=dict)
+    result: dict | None = None
+    error: str | None = None
+
+
+class AgentRunResponse(BaseModel):
+    text: str
+    trace: list[AgentToolTraceItem] = Field(default_factory=list)
+    model: str | None = None
+    finish_reason: str = "complete"

tests/agents/test_agent_route.py

@@ -0,0 +1,54 @@
+"""Tests for POST /agent/run — uses a stub orchestrator factory."""
+from __future__ import annotations
+
+from typing import Any
+from unittest.mock import patch
+
+import pytest
+from fastapi.testclient import TestClient
+
+from src.agents.schemas import AgentResult, ToolTraceItem
+from src.api.main import app
+
+
+client = TestClient(app)
+
+
+class _FakeOrchestrator:
+    """Returns a canned AgentResult; ignores input."""
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        pass
+
+    def run(self, user_input: str) -> AgentResult:
+        return AgentResult(
+            text=f"Synthesized answer for: {user_input}",
+            trace=[
+                ToolTraceItem(name="run_bbb_pipeline", args={"smiles": user_input},
+                              result={"label": 1, "label_text": "permeable"}),
+                ToolTraceItem(name="retrieve_context", args={"query": "BBB"},
+                              result={"chunks": []}),
+            ],
+            model="stub-model",
+            finish_reason="complete",
+        )
+
+
+class TestAgentRoute:
+    def test_post_returns_synthesized_text_and_trace(self) -> None:
+        with patch("src.api.routes._build_orchestrator", return_value=_FakeOrchestrator()):
+            r = client.post("/agent/run", json={"user_input": "CCO"})
+        assert r.status_code == 200
+        body = r.json()
+        assert "Synthesized answer for: CCO" in body["text"]
+        assert len(body["trace"]) == 2
+        assert body["trace"][0]["name"] == "run_bbb_pipeline"
+        assert body["model"] == "stub-model"
+        assert body["finish_reason"] == "complete"
+
+    def test_empty_user_input_422(self) -> None:
+        r = client.post("/agent/run", json={"user_input": ""})
+        assert r.status_code == 422
+
+    def test_missing_user_input_422(self) -> None:
+        r = client.post("/agent/run", json={})
+        assert r.status_code == 422