Feat/advisor tools (#38)

* added /scraper directory from Clary branch for inspection.

* Added Gemini function-calling MVP with course search tool.

* Added Rate My Professor tool and multi-tool dispatcher.

* Added tool registry with auto-discovery and tool filtering.

* fixed test warning in RMP tool test.

* added structured tool-call return result and get_tool_response method to orchestrator.

* wired tool calling into orchestrator chat routes.

* cleaned up standalone test routes and did minor refactoring.

* fixed context manager dropping non-allowlist persona and tool responses.

* pinned backend requirements to <pkg>~=M.m from latest container build.

* removed license notices and cu_info_scraper.

* moved the tool-calling loop into LLMClient with provider specific overrides implemented in each respective client class.

* refactored tools config to support per tool settings.

* added rmp school_id lookup script for CLI usage.

* added dark mode awareness to advisor color fallback which is used by the orchestrator when a tool call is made.

* fixed vLLM tool calling to handle multiple tool calls.

* fixed Gemini tool calling to handle multiple tool calls.

* deleted reference /scrapers directory.

* revert Gemini base url to be defined in init.

* refactored Gemini tool calling to use the /openai endpoint format.

multi_llm_chatbot_backend/app/api/routes/chat.py

@@ -115,6 +115,27 @@ async def chat_stream(
                 ).to_ndjson()
                 return
 
+            # If an enabled tool can handle this query, return its response
+            # directly and skip persona generation.
+            tool_result = await chat_orchestrator.get_tool_response(message.user_input)
+            if tool_result.used_tool:
+                session.append_message("orchestrator", tool_result.text)
+                yield ChatStreamLine(
+                    type="advisor",
+                    data={
+                        "persona_id": "orchestrator",
+                        "persona_name": "Orchestrator",
+                        "content": tool_result.text,
+                        "used_documents": False,
+                        "document_chunks_used": 0,
+                    },
+                ).to_ndjson()
+                yield ChatStreamLine(
+                    type="progress",
+                    data={"phase": "complete"},
+                ).to_ndjson()
+                return
+
             # Get personas most relevant to the current session
             top_personas = await chat_orchestrator.get_top_personas(
                 session_id=sid,
@@ -363,7 +384,26 @@ async def chat_sequential_enhanced(
                     "trigger": "vague_input"
                 }
             }
-        
+
+        # If an enabled tool can handle this query, return its response
+        # directly and skip persona generation.
+        tool_result = await chat_orchestrator.get_tool_response(message.user_input)
+        if tool_result.used_tool:
+            session.append_message("orchestrator", tool_result.text)
+            return {
+                "responses": [{
+                    "persona_id": "orchestrator",
+                    "persona_name": "Orchestrator",
+                    "content": tool_result.text,
+                    "used_documents": False,
+                    "document_chunks_used": 0,
+                }],
+                "session_debug": {
+                    "session_id": session_id,
+                    "tool_used": True,
+                }
+            }
+
         # RESTORED: Get intelligently ordered personas based on context
         top_personas = await chat_orchestrator.get_top_personas(
             session_id=session_id, 

multi_llm_chatbot_backend/app/api/routes/provider.py

@@ -69,6 +69,8 @@ async def switch_provider(provider_data: ProviderSwitch):
         new_llm = create_llm_client(current_provider)
         llm = new_llm
 
+        chat_orchestrator.llm_client = new_llm
+
         new_personas = get_default_personas(new_llm)
         chat_orchestrator.personas.clear()
         for persona in new_personas:

multi_llm_chatbot_backend/app/config.py

@@ -11,7 +11,7 @@ import os
 import logging
 import colorsys
 from pathlib import Path
-from typing import List, Optional
+from typing import Any, Dict, List, Optional
 from colorhash import ColorHash
 
 import yaml
@@ -234,6 +234,23 @@ class RAGConfig(BaseModel):
     chroma_collection: str = "phd_advisor_documents"
 
 
+class ToolsConfig(BaseModel):
+    model_config = {"extra": "allow"}
+
+    def get_enabled_names(self) -> List[str]:
+        """Return tool names whose config has ``enabled: true``."""
+        return [
+            name
+            for name, cfg in self.__pydantic_extra__.items()
+            if isinstance(cfg, dict) and cfg.get("enabled", True)
+        ]
+
+    def get_tool_config(self, name: str) -> Dict[str, Any]:
+        """Return the raw config dict for a single tool, or ``{}``."""
+        cfg = self.__pydantic_extra__.get(name, {})
+        return cfg if isinstance(cfg, dict) else {}
+
+
 class AppSettings(BaseModel):
     """Top-level container that mirrors the YAML structure."""
     app: AppConfig = AppConfig()
@@ -246,6 +263,7 @@ class AppSettings(BaseModel):
     mongodb: MongoDBConfig = MongoDBConfig()
     llm: LLMConfig = LLMConfig()
     rag: RAGConfig = RAGConfig()
+    tools: ToolsConfig = ToolsConfig()
 
     # ------------------------------------------------------------------
     # Convenience helpers

multi_llm_chatbot_backend/app/core/bootstrap.py

@@ -30,7 +30,7 @@ def create_llm_client(provider=None):
         )
 
 llm = create_llm_client()
-chat_orchestrator = ImprovedChatOrchestrator()
+chat_orchestrator = ImprovedChatOrchestrator(llm_client=llm)
 
 DEFAULT_PERSONAS = get_default_personas(llm)
 for persona in DEFAULT_PERSONAS:

multi_llm_chatbot_backend/app/core/context_manager.py

@@ -209,17 +209,16 @@ class ContextManager:
                     "role": "user",
                     "parts": [{"text": content}]
                 })
-            elif role in ['assistant', 'methodologist', 'theorist', 'pragmatist']:
-                formatted.append({
-                    "role": "model",
-                    "parts": [{"text": content}]
-                })
             elif role == 'document':
-                # Add document as user context
                 formatted.append({
                     "role": "user",
                     "parts": [{"text": f"[Context Document] {content}"}]
                 })
+            else:
+                formatted.append({
+                    "role": "model",
+                    "parts": [{"text": content}]
+                })
 
         return formatted
     

multi_llm_chatbot_backend/app/core/improved_orchestrator.py

@@ -4,6 +4,8 @@ from app.core.session_manager import ConversationContext, get_session_manager
 from app.core.context_manager import get_context_manager
 from app.core.rag_manager import get_rag_manager
 from app.config import get_settings
+from app.llm.llm_client import LLMClient, ToolCallResult
+from app.tools import get_tool_definitions, get_tool_executor
 
 import json
 import logging
@@ -16,8 +18,9 @@ class ImprovedChatOrchestrator:
     Enhanced orchestrator with document awareness and improved context handling
     """
     
-    def __init__(self):
+    def __init__(self, llm_client: LLMClient = None):
         self.personas: Dict[str, Persona] = {}
+        self.llm_client = llm_client
         self.session_manager = get_session_manager()
         self.context_manager = get_context_manager()
     
@@ -33,7 +36,49 @@ class ImprovedChatOrchestrator:
     def list_personas(self) -> List[str]:
         """List all available persona IDs"""
         return list(self.personas.keys())
-    
+
+    async def get_tool_response(self, user_message: str) -> ToolCallResult:
+        """Check whether a tool can handle *user_message*.
+
+        If tools are disabled in config, no LLM client is available, or the
+        model decides no tool is needed, returns
+        ``ToolCallResult(used_tool=False)``.  Otherwise executes the tool and
+        returns the grounded response with ``used_tool=True``.
+        """
+        if self.llm_client is None:
+            return ToolCallResult(text="", used_tool=False)
+
+        settings = get_settings()
+        tools_enabled = settings.tools.get_enabled_names()
+
+        if not tools_enabled:
+            return ToolCallResult(text="", used_tool=False)
+
+        tool_definitions = get_tool_definitions(enabled=tools_enabled)
+        tool_executor = get_tool_executor(enabled=tools_enabled)
+
+        if not tool_definitions:
+            return ToolCallResult(text="", used_tool=False)
+
+        system_prompt = (
+            "You are a helpful assistant with access to external tools. "
+            "Use the available tools when the user's question can be answered "
+            "by one of them. If no tool is relevant, respond with a brief "
+            "text answer. "
+            "If a tool response includes 'truncated': true, let the user know "
+            "how many total results were found and suggest they narrow their "
+            "search for more specific results. "
+            "Format your responses using markdown. Use bullet points "
+            "to present structured data like course listings or professor ratings."
+        )
+
+        return await self.llm_client.generate_with_tools(
+            system_prompt=system_prompt,
+            user_message=user_message,
+            tool_definitions=tool_definitions,
+            tool_executor=tool_executor,
+        )
+
     async def process_message(self, 
                             user_input: str, 
                             session_id: Optional[str] = None,

multi_llm_chatbot_backend/app/llm/improved_gemini_client.py

@@ -1,10 +1,14 @@
 import httpx
-import os
-from typing import List
-from app.llm.llm_client import LLMClient
+import json
+import logging
+from typing import Any, Callable, Dict, List, Optional
+
+from openai import AsyncOpenAI, APIConnectionError, APIStatusError
+
+from app.llm.llm_client import LLMClient, ToolCallInfo, ToolCallResult
+
 from app.core.context_manager import get_context_manager
 from app.config import get_settings
-import logging
 
 logger = logging.getLogger(__name__)
 
@@ -20,8 +24,16 @@ class ImprovedGeminiClient(LLMClient):
         if not self.api_key:
             raise ValueError("Gemini API key not set. Provide it in config.yaml (llm.gemini.api_key).")
         
+        # Native Gemini REST API
         self.base_url = "https://generativelanguage.googleapis.com/v1beta/models"
         self.context_manager = get_context_manager()
+
+        # OpenAI-compatible endpoint (for tool calling)
+        self.openai_client = AsyncOpenAI(
+            base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
+            api_key=self.api_key,
+            timeout=90.0,
+        )
     
     async def generate(self, system_prompt: str, context: List[dict], temperature: float, max_tokens: int, response_mime_type: str = None) -> str:
         """
@@ -120,3 +132,111 @@ class ImprovedGeminiClient(LLMClient):
         except Exception as e:
             logger.error(f"Unexpected error in Gemini client: {str(e)}")
             return "I encountered an unexpected error. Please try again."
+
+    # ------------------------------------------------------------------
+    # Tool-calling support (via Gemini OpenAI-compatible endpoint)
+    # ------------------------------------------------------------------
+
+    _MAX_TOOL_ROUNDS = 5
+
+    async def generate_with_tools(
+        self,
+        system_prompt: str,
+        user_message: str,
+        tool_definitions: Optional[List[Dict[str, Any]]] = None,
+        tool_executor: Optional[Callable] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 2048,
+    ) -> ToolCallResult:
+        """OpenAI-compatible tool-calling loop via Gemini's /openai/ endpoint.
+
+        Tool definitions are expected in OpenAI format (as returned by the
+        tool registry).  Loops through the standard tool-call protocol
+        until the model produces a plain text response:
+
+            request → detect tool_calls → execute all → feed results
+            back → repeat (up to ``_MAX_TOOL_ROUNDS`` rounds).
+
+        All tool calls in a single response are executed before the next
+        round, so multi-tool queries (e.g. "compare professor A vs B")
+        work correctly.
+        """
+        messages: List[Dict[str, Any]] = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_message},
+        ]
+
+        openai_tools = tool_definitions or []
+        all_tool_calls: List[ToolCallInfo] = []
+
+        try:
+            for _round in range(self._MAX_TOOL_ROUNDS):
+                response = await self.openai_client.chat.completions.create(
+                    model=self.model_name,
+                    messages=messages,
+                    tools=openai_tools or None,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                )
+
+                choice = response.choices[0].message
+
+                if not choice.tool_calls:
+                    return ToolCallResult(
+                        text=choice.content or "",
+                        used_tool=bool(all_tool_calls),
+                        tool_name=all_tool_calls[0].name if all_tool_calls else None,
+                        tool_args=all_tool_calls[0].args if all_tool_calls else {},
+                        tool_calls_made=all_tool_calls,
+                    )
+
+                messages.append(choice.model_dump(exclude_none=True))
+
+                for tc in choice.tool_calls:
+                    fn_name = tc.function.name
+                    fn_args = json.loads(tc.function.arguments)
+                    logger.info("Gemini requested tool call: %s(%s)", fn_name, fn_args)
+                    all_tool_calls.append(ToolCallInfo(name=fn_name, args=fn_args))
+
+                    try:
+                        tool_result = await tool_executor(name=fn_name, **fn_args)
+                    except Exception as exc:
+                        logger.error("Tool %s failed: %s", fn_name, exc)
+                        tool_result = {"error": str(exc)}
+
+                    messages.append({
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": json.dumps(tool_result),
+                    })
+
+            logger.warning(
+                "Tool-calling loop exhausted after %d rounds", self._MAX_TOOL_ROUNDS,
+            )
+            last_content = response.choices[0].message.content or ""
+            return ToolCallResult(
+                text=last_content or "I was unable to finish looking that up. Please try again.",
+                used_tool=bool(all_tool_calls),
+                tool_name=all_tool_calls[0].name if all_tool_calls else None,
+                tool_args=all_tool_calls[0].args if all_tool_calls else {},
+                tool_calls_made=all_tool_calls,
+            )
+
+        except APIConnectionError:
+            logger.error("Unable to connect to Gemini OpenAI-compat endpoint")
+            return ToolCallResult(
+                text="I'm unable to connect to the AI service. Please try again.",
+                used_tool=False,
+            )
+        except APIStatusError as e:
+            logger.error("Gemini tool-call API error: %s - %s", e.status_code, e.message)
+            return ToolCallResult(
+                text="The AI service encountered an error. Please try again.",
+                used_tool=False,
+            )
+        except Exception as e:
+            logger.error("Unexpected error in Gemini tool-calling: %s", e)
+            return ToolCallResult(
+                text="I encountered an unexpected error. Please try again.",
+                used_tool=False,
+            )

multi_llm_chatbot_backend/app/llm/improved_vllm_client.py

@@ -1,8 +1,11 @@
-from typing import List
+import json
+import logging
+from typing import Any, Callable, Dict, List, Optional
+
 from openai import AsyncOpenAI, APIConnectionError, APIStatusError
-from app.llm.llm_client import LLMClient
+
+from app.llm.llm_client import LLMClient, ToolCallInfo, ToolCallResult
 from app.core.context_manager import get_context_manager
-import logging
 
 logger = logging.getLogger(__name__)
 
@@ -15,7 +18,7 @@ class ImprovedVllmClient(LLMClient):
         self.client = AsyncOpenAI(
             base_url=f"{api_url}/v1",
             api_key=api_key,
-            timeout=30.0,
+            timeout=90.0,
         )
         self.context_manager = get_context_manager()
 
@@ -70,3 +73,118 @@ class ImprovedVllmClient(LLMClient):
             logger.error(f"Unexpected error in vLLM client: {str(e)}")
             return "I encountered an unexpected error. Please try again."
 
+    # ------------------------------------------------------------------
+    # Tool-calling support (OpenAI-compatible format)
+    # ------------------------------------------------------------------
+
+    _MAX_TOOL_ROUNDS = 5
+
+    async def generate_with_tools(
+        self,
+        system_prompt: str,
+        user_message: str,
+        tool_definitions: Optional[List[Dict[str, Any]]] = None,
+        tool_executor: Optional[Callable] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 2048,
+    ) -> ToolCallResult:
+        """OpenAI-compatible tool-calling loop for vLLM.
+
+        Tool definitions are expected in OpenAI format (as returned by the
+        tool registry).  Loops through the standard tool-call protocol
+        until the model produces a plain text response:
+
+            request → detect tool_calls → execute all → feed results
+            back → repeat (up to ``_MAX_TOOL_ROUNDS`` rounds).
+
+        All tool calls in a single response are executed before the next
+        round, so multi-tool queries (e.g. "compare professor A vs B")
+        work correctly.
+        """
+        if not self.model_name:
+            await self.refresh_model()
+
+        messages: List[Dict[str, Any]] = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_message},
+        ]
+
+        openai_tools = tool_definitions or []
+
+        all_tool_calls: List[ToolCallInfo] = []
+
+        try:
+            for _round in range(self._MAX_TOOL_ROUNDS):
+                response = await self.client.chat.completions.create(
+                    model=self.model_name,
+                    messages=messages,
+                    tools=openai_tools or None,
+                    temperature=temperature,
+                    max_tokens=max_tokens,
+                )
+
+                choice = response.choices[0].message
+
+                if not choice.tool_calls:
+                    return ToolCallResult(
+                        text=choice.content or "",
+                        used_tool=bool(all_tool_calls),
+                        tool_name=all_tool_calls[0].name if all_tool_calls else None,
+                        tool_args=all_tool_calls[0].args if all_tool_calls else {},
+                        tool_calls_made=all_tool_calls,
+                    )
+
+                messages.append(choice.model_dump())
+
+                for tc in choice.tool_calls:
+                    fn_name = tc.function.name
+                    fn_args = json.loads(tc.function.arguments)
+                    logger.info("vLLM requested tool call: %s(%s)", fn_name, fn_args)
+                    all_tool_calls.append(ToolCallInfo(name=fn_name, args=fn_args))
+
+                    try:
+                        tool_result = await tool_executor(name=fn_name, **fn_args)
+                    except Exception as exc:
+                        logger.error("Tool %s failed: %s", fn_name, exc)
+                        tool_result = {"error": str(exc)}
+
+                    messages.append({
+                        "role": "tool",
+                        "tool_call_id": tc.id,
+                        "content": json.dumps(tool_result),
+                    })
+
+            logger.warning(
+                "Tool-calling loop exhausted after %d rounds", self._MAX_TOOL_ROUNDS,
+            )
+            last_content = response.choices[0].message.content or ""
+            return ToolCallResult(
+                text=last_content or "I was unable to finish looking that up. Please try again.",
+                used_tool=bool(all_tool_calls),
+                tool_name=all_tool_calls[0].name if all_tool_calls else None,
+                tool_args=all_tool_calls[0].args if all_tool_calls else {},
+                tool_calls_made=all_tool_calls,
+            )
+
+        except APIConnectionError:
+            logger.error("Unable to connect to vLLM at %s", self.api_url)
+            return ToolCallResult(
+                text="I'm unable to connect to the AI service. Please ensure the vLLM endpoint is available.",
+                used_tool=False,
+            )
+        except APIStatusError as e:
+            logger.error("vLLM tool-call API error: %s - %s", e.status_code, e.message)
+            if e.status_code == 404:
+                self.model_name = None
+            return ToolCallResult(
+                text="The AI service encountered an error. Please try again.",
+                used_tool=False,
+            )
+        except Exception as e:
+            logger.error("Unexpected error in vLLM tool-calling: %s", e)
+            return ToolCallResult(
+                text="I encountered an unexpected error. Please try again.",
+                used_tool=False,
+            )
+
+

multi_llm_chatbot_backend/app/llm/llm_client.py

@@ -1,27 +1,72 @@
 from abc import ABC, abstractmethod
-from typing import List
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
 import re
 
+
+@dataclass
+class ToolCallInfo:
+    """Record of a single tool invocation."""
+
+    name: str
+    args: dict = field(default_factory=dict)
+
+
+@dataclass
+class ToolCallResult:
+    """Structured return value from ``generate_with_tools``."""
+
+    text: str
+    used_tool: bool
+    tool_name: Optional[str] = None
+    tool_args: dict = field(default_factory=dict)
+    tool_calls_made: List["ToolCallInfo"] = field(default_factory=list)
+
+
 class LLMClient(ABC):
     """Abstract base class for all LLM clients"""
-    
+
     @abstractmethod
     async def generate(self, system_prompt: str, context: List[dict], temperature: float, max_tokens: int, response_mime_type: str = None) -> str:
         """
         Generate a response using the LLM.
-        
+
         Args:
             system_prompt (str): The system prompt defining the persona/role
             context (List[dict]): List of conversation messages with 'role' and 'content' keys
             temperature (float): Sampling temperature for generation
             max_tokens (int): Maximum number of tokens to generate
             response_mime_type (str, optional): MIME type for the response format. Defaults to None.
-            
+
         Returns:
             str: The generated response text
         """
         pass
 
+    async def generate_with_tools(
+        self,
+        system_prompt: str,
+        user_message: str,
+        tool_definitions: Optional[List[Dict[str, Any]]] = None,
+        tool_executor: Optional[Callable] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 2048,
+    ) -> ToolCallResult:
+        """Generate a response, optionally invoking tools.
+
+        Subclasses that support native tool calling should override this
+        method.  The default implementation ignores tools and falls back
+        to a plain ``generate()`` call so that providers without tool
+        support degrade gracefully.
+        """
+        text = await self.generate(
+            system_prompt=system_prompt,
+            context=[{"role": "user", "content": user_message}],
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        return ToolCallResult(text=text, used_tool=False)
+
     def _clean_response(self, response: str) -> str:
         """Clean up response text, preserving Markdown formatting."""
         response = response.replace("\r\n", "\n").replace("\r", "\n")

multi_llm_chatbot_backend/app/main.py

@@ -58,6 +58,7 @@ app.include_router(auth_router, prefix="/auth", tags=["authentication"])
 app.include_router(chat_sessions_router, prefix="/api", tags=["chat-sessions"])
 app.include_router(phd_canvas_router, prefix="/api", tags=["phd-canvas"])
 
+
 # ---------------------------------------------------------------------------
 # Public configuration endpoint — serves the frontend-safe subset
 # ---------------------------------------------------------------------------

multi_llm_chatbot_backend/app/tests/unit/test_course_search_tool.py

@@ -0,0 +1,33 @@
+import asyncio
+import unittest
+
+from app.tools.search_courses import TOOL_DEFINITION, execute
+
+
+class TestSearchCoursesContract(unittest.TestCase):
+    """The search_courses tool module must export a valid OpenAI
+    tool definition and an async executor."""
+
+    def test_tool_definition_has_required_fields(self):
+        self.assertEqual(TOOL_DEFINITION["type"], "function")
+        self.assertIn("function", TOOL_DEFINITION)
+        fn = TOOL_DEFINITION["function"]
+        self.assertIn("name", fn)
+        self.assertIn("description", fn)
+        self.assertIn("parameters", fn)
+
+    def test_tool_definition_name(self):
+        self.assertEqual(TOOL_DEFINITION["function"]["name"], "search_courses")
+
+    def test_tool_definition_has_nonempty_description(self):
+        self.assertIsInstance(TOOL_DEFINITION["function"]["description"], str)
+        self.assertGreater(len(TOOL_DEFINITION["function"]["description"]), 0)
+
+    def test_tool_definition_parameters_is_valid_schema(self):
+        params = TOOL_DEFINITION["function"]["parameters"]
+        self.assertEqual(params["type"], "object")
+        self.assertIn("properties", params)
+        self.assertIn("subject", params["properties"])
+
+    def test_execute_is_async_callable(self):
+        self.assertTrue(asyncio.iscoroutinefunction(execute))

multi_llm_chatbot_backend/app/tests/unit/test_gemini_client.py

@@ -0,0 +1,432 @@
+import asyncio
+import json
+import unittest
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from openai import APIConnectionError, APIStatusError
+
+from app.llm.llm_client import ToolCallResult
+from app.llm.improved_gemini_client import ImprovedGeminiClient
+
+
+FAKE_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "search_courses",
+        "description": "Search courses",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "subject": {"type": "string", "description": "Subject code"},
+            },
+        },
+    },
+}
+
+
+def _make_text_completion_mock(content="Response"):
+    """Build a ChatCompletion mock with no tool calls."""
+    mock_message = MagicMock()
+    mock_message.content = content
+    mock_message.tool_calls = None
+    mock_choice = MagicMock()
+    mock_choice.message = mock_message
+    return MagicMock(choices=[mock_choice])
+
+
+def _make_tool_call_mock(fn_name, fn_args_dict, tool_call_id="call_123"):
+    """Build a ChatCompletion mock where the model requests a tool call."""
+    fn_args_json = json.dumps(fn_args_dict)
+
+    tool_call = MagicMock()
+    tool_call.id = tool_call_id
+    tool_call.function.name = fn_name
+    tool_call.function.arguments = fn_args_json
+
+    mock_message = MagicMock()
+    mock_message.content = None
+    mock_message.tool_calls = [tool_call]
+    mock_message.model_dump.return_value = {
+        "role": "assistant",
+        "content": None,
+        "tool_calls": [{
+            "id": tool_call_id,
+            "type": "function",
+            "function": {"name": fn_name, "arguments": fn_args_json},
+        }],
+    }
+
+    mock_choice = MagicMock()
+    mock_choice.message = mock_message
+    return MagicMock(choices=[mock_choice])
+
+
+def _make_multi_tool_call_mock(calls):
+    """Build a ChatCompletion mock with multiple parallel tool calls.
+
+    *calls* is a list of (fn_name, fn_args_dict, tool_call_id) tuples.
+    """
+    tool_calls = []
+    dump_calls = []
+    for fn_name, fn_args_dict, tool_call_id in calls:
+        fn_args_json = json.dumps(fn_args_dict)
+        tc = MagicMock()
+        tc.id = tool_call_id
+        tc.function.name = fn_name
+        tc.function.arguments = fn_args_json
+        tool_calls.append(tc)
+        dump_calls.append({
+            "id": tool_call_id,
+            "type": "function",
+            "function": {"name": fn_name, "arguments": fn_args_json},
+        })
+
+    mock_message = MagicMock()
+    mock_message.content = None
+    mock_message.tool_calls = tool_calls
+    mock_message.model_dump.return_value = {
+        "role": "assistant",
+        "content": None,
+        "tool_calls": dump_calls,
+    }
+
+    mock_choice = MagicMock()
+    mock_choice.message = mock_message
+    return MagicMock(choices=[mock_choice])
+
+
+def _make_gemini_client(MockSettings, MockCtxMgr):
+    """Instantiate an ImprovedGeminiClient with mocked dependencies."""
+    mock_settings = MagicMock()
+    mock_settings.llm.gemini.api_key = "fake-key"
+    mock_settings.llm.gemini.model = "gemini-2.0-flash"
+    MockSettings.return_value = mock_settings
+    MockCtxMgr.return_value = MagicMock()
+    return ImprovedGeminiClient()
+
+
+@patch("app.llm.improved_gemini_client.get_context_manager")
+@patch("app.llm.improved_gemini_client.get_settings")
+class TestGeminiGenerateWithTools(unittest.TestCase):
+    """Unit tests for ImprovedGeminiClient.generate_with_tools()
+    using the OpenAI-compatible endpoint."""
+
+    # ------------------------------------------------------------------
+    # Happy path — no tool call
+    # ------------------------------------------------------------------
+
+    def test_direct_text_response_returns_text(self, MockSettings, MockCtxMgr):
+        """When the model responds with text (no tool call), return it."""
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        gemini.openai_client.chat.completions.create = AsyncMock(
+            return_value=_make_text_completion_mock("Hello, world!"),
+        )
+        mock_executor = AsyncMock()
+
+        result = asyncio.run(gemini.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Hi there",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        self.assertIsInstance(result, ToolCallResult)
+        self.assertEqual(result.text, "Hello, world!")
+        self.assertFalse(result.used_tool)
+        mock_executor.assert_not_called()
+
+    # ------------------------------------------------------------------
+    # Happy path — tool call
+    # ------------------------------------------------------------------
+
+    def test_function_call_triggers_executor_and_returns_final_text(self, MockSettings, MockCtxMgr):
+        """When the model requests a tool call, execute it and return
+        the text from the follow-up completion."""
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        gemini.openai_client.chat.completions.create = AsyncMock(side_effect=[
+            _make_tool_call_mock("search_courses", {"subject": "CSCI"}),
+            _make_text_completion_mock("CSCI 1300 is available MWF 10-10:50."),
+        ])
+        mock_executor = AsyncMock(
+            return_value={"courses": [{"title": "Intro to CS"}]}
+        )
+
+        result = asyncio.run(gemini.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="What CSCI classes are there?",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        mock_executor.assert_called_once_with(
+            name="search_courses", subject="CSCI",
+        )
+        self.assertIsInstance(result, ToolCallResult)
+        self.assertEqual(result.text, "CSCI 1300 is available MWF 10-10:50.")
+        self.assertTrue(result.used_tool)
+        self.assertEqual(result.tool_name, "search_courses")
+        self.assertEqual(result.tool_args, {"subject": "CSCI"})
+        self.assertEqual(len(result.tool_calls_made), 1)
+        self.assertEqual(result.tool_calls_made[0].name, "search_courses")
+        self.assertEqual(gemini.openai_client.chat.completions.create.call_count, 2)
+
+    # ------------------------------------------------------------------
+    # Payload format
+    # ------------------------------------------------------------------
+
+    def test_tool_definitions_passed_through_in_openai_format(self, MockSettings, MockCtxMgr):
+        """Tool definitions (already in OpenAI format) are passed through
+        directly to the completions API."""
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        gemini.openai_client.chat.completions.create = AsyncMock(
+            return_value=_make_text_completion_mock("Ok"),
+        )
+
+        asyncio.run(gemini.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Hello",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=AsyncMock(),
+        ))
+
+        call_kwargs = gemini.openai_client.chat.completions.create.call_args[1]
+        tools = call_kwargs["tools"]
+        self.assertEqual(len(tools), 1)
+        self.assertEqual(tools[0]["type"], "function")
+        self.assertEqual(tools[0]["function"]["name"], "search_courses")
+        self.assertIn("parameters", tools[0]["function"])
+
+    def test_tool_result_appended_to_followup(self, MockSettings, MockCtxMgr):
+        """After executing a tool, the follow-up call must include
+        the assistant message, a ``role: tool`` message, and ``tools=``."""
+        tool_output = {"courses": [{"title": "Algorithms"}]}
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        gemini.openai_client.chat.completions.create = AsyncMock(side_effect=[
+            _make_tool_call_mock("search_courses", {"subject": "CSCI"}),
+            _make_text_completion_mock("Here are the results."),
+        ])
+        mock_executor = AsyncMock(return_value=tool_output)
+
+        asyncio.run(gemini.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Find CSCI courses",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        second_call_kwargs = gemini.openai_client.chat.completions.create.call_args_list[1][1]
+        messages = second_call_kwargs["messages"]
+
+        assistant_msg = messages[-2]
+        self.assertEqual(assistant_msg["role"], "assistant")
+
+        tool_msg = messages[-1]
+        self.assertEqual(tool_msg["role"], "tool")
+        self.assertEqual(tool_msg["tool_call_id"], "call_123")
+        self.assertEqual(json.loads(tool_msg["content"]), tool_output)
+
+        self.assertIn("tools", second_call_kwargs,
+                       "Follow-up call must include tools= so the model can "
+                       "request additional tool calls if needed")
+
+    # ------------------------------------------------------------------
+    # Error handling
+    # ------------------------------------------------------------------
+
+    def test_tool_executor_failure_serialises_error_and_continues(self, MockSettings, MockCtxMgr):
+        """If the tool executor raises, the error is serialised as the
+        tool result and the loop continues to the follow-up completion."""
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        gemini.openai_client.chat.completions.create = AsyncMock(side_effect=[
+            _make_tool_call_mock("search_courses", {"subject": "CSCI"}),
+            _make_text_completion_mock("Sorry, I couldn't look that up."),
+        ])
+        mock_executor = AsyncMock(side_effect=RuntimeError("network down"))
+
+        result = asyncio.run(gemini.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Find CSCI courses",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        self.assertTrue(result.used_tool)
+        self.assertEqual(result.tool_name, "search_courses")
+        self.assertEqual(len(result.tool_calls_made), 1)
+
+        second_call_msgs = gemini.openai_client.chat.completions.create.call_args_list[1][1]["messages"]
+        tool_msg = [m for m in second_call_msgs if m.get("role") == "tool"][0]
+        self.assertIn("network down", json.loads(tool_msg["content"])["error"])
+
+    def test_connection_error_returns_not_used(self, MockSettings, MockCtxMgr):
+        """APIConnectionError during tool calling returns used_tool=False."""
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        gemini.openai_client.chat.completions.create = AsyncMock(
+            side_effect=APIConnectionError(request=MagicMock()),
+        )
+
+        result = asyncio.run(gemini.generate_with_tools(
+            system_prompt="Test",
+            user_message="Hi",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=AsyncMock(),
+        ))
+
+        self.assertIsInstance(result, ToolCallResult)
+        self.assertFalse(result.used_tool)
+        self.assertIn("unable to connect", result.text.lower())
+
+    def test_status_error_returns_not_used(self, MockSettings, MockCtxMgr):
+        """APIStatusError during tool calling returns used_tool=False."""
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        mock_response = MagicMock()
+        mock_response.status_code = 500
+        gemini.openai_client.chat.completions.create = AsyncMock(
+            side_effect=APIStatusError(
+                message="Server error", response=mock_response, body=None,
+            )
+        )
+
+        result = asyncio.run(gemini.generate_with_tools(
+            system_prompt="Test",
+            user_message="Hi",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=AsyncMock(),
+        ))
+
+        self.assertIsInstance(result, ToolCallResult)
+        self.assertFalse(result.used_tool)
+        self.assertIn("error", result.text.lower())
+
+    # ------------------------------------------------------------------
+    # Multi-tool call in a single response
+    # ------------------------------------------------------------------
+
+    def test_parallel_tool_calls_all_executed(self, MockSettings, MockCtxMgr):
+        """When the model requests multiple tool calls in one response,
+        all of them are executed and their results fed back."""
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        gemini.openai_client.chat.completions.create = AsyncMock(side_effect=[
+            _make_multi_tool_call_mock([
+                ("rate_my_professor", {"professor_name": "Dubson"}, "call_a"),
+                ("rate_my_professor", {"professor_name": "West"}, "call_b"),
+            ]),
+            _make_text_completion_mock("Dubson has a 4.5 rating. West has a 3.8 rating."),
+        ])
+        mock_executor = AsyncMock(side_effect=[
+            {"professors": [{"name": "Dubson", "rating": 4.5}]},
+            {"professors": [{"name": "West", "rating": 3.8}]},
+        ])
+
+        result = asyncio.run(gemini.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Is professor Dubson or West rated better?",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        self.assertEqual(mock_executor.call_count, 2)
+        self.assertTrue(result.used_tool)
+        self.assertIn("Dubson", result.text)
+        self.assertIn("West", result.text)
+        self.assertEqual(len(result.tool_calls_made), 2)
+        self.assertEqual(result.tool_calls_made[0].name, "rate_my_professor")
+        self.assertEqual(result.tool_calls_made[1].args, {"professor_name": "West"})
+        self.assertEqual(gemini.openai_client.chat.completions.create.call_count, 2)
+
+    def test_parallel_tool_results_all_in_followup_messages(self, MockSettings, MockCtxMgr):
+        """All tool results must appear as separate role:tool messages
+        in the follow-up request."""
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        gemini.openai_client.chat.completions.create = AsyncMock(side_effect=[
+            _make_multi_tool_call_mock([
+                ("rate_my_professor", {"professor_name": "Dubson"}, "call_a"),
+                ("rate_my_professor", {"professor_name": "West"}, "call_b"),
+            ]),
+            _make_text_completion_mock("Comparison complete."),
+        ])
+        mock_executor = AsyncMock(side_effect=[
+            {"professors": [{"name": "Dubson"}]},
+            {"professors": [{"name": "West"}]},
+        ])
+
+        asyncio.run(gemini.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Compare",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        second_call_msgs = gemini.openai_client.chat.completions.create.call_args_list[1][1]["messages"]
+        tool_msgs = [m for m in second_call_msgs if m.get("role") == "tool"]
+        self.assertEqual(len(tool_msgs), 2)
+        self.assertEqual(tool_msgs[0]["tool_call_id"], "call_a")
+        self.assertEqual(tool_msgs[1]["tool_call_id"], "call_b")
+
+    # ------------------------------------------------------------------
+    # Multi-round tool calling
+    # ------------------------------------------------------------------
+
+    def test_sequential_tool_rounds(self, MockSettings, MockCtxMgr):
+        """The loop handles a second round of tool calls after the first
+        results are fed back."""
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        gemini.openai_client.chat.completions.create = AsyncMock(side_effect=[
+            _make_tool_call_mock("rate_my_professor", {"professor_name": "Dubson"}, "call_1"),
+            _make_tool_call_mock("rate_my_professor", {"professor_name": "West"}, "call_2"),
+            _make_text_completion_mock("Dubson is rated higher than West."),
+        ])
+        mock_executor = AsyncMock(side_effect=[
+            {"professors": [{"name": "Dubson", "rating": 4.5}]},
+            {"professors": [{"name": "West", "rating": 3.8}]},
+        ])
+
+        result = asyncio.run(gemini.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Compare Dubson and West",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        self.assertEqual(mock_executor.call_count, 2)
+        self.assertTrue(result.used_tool)
+        self.assertEqual(len(result.tool_calls_made), 2)
+        self.assertEqual(result.tool_name, "rate_my_professor")
+        self.assertEqual(gemini.openai_client.chat.completions.create.call_count, 3)
+
+    # ------------------------------------------------------------------
+    # Partial failure in multi-tool context
+    # ------------------------------------------------------------------
+
+    def test_partial_tool_failure_continues(self, MockSettings, MockCtxMgr):
+        """If one tool call in a batch fails, the error is serialised
+        and the loop continues to the follow-up."""
+        gemini = _make_gemini_client(MockSettings, MockCtxMgr)
+        gemini.openai_client.chat.completions.create = AsyncMock(side_effect=[
+            _make_multi_tool_call_mock([
+                ("rate_my_professor", {"professor_name": "Dubson"}, "call_a"),
+                ("rate_my_professor", {"professor_name": "West"}, "call_b"),
+            ]),
+            _make_text_completion_mock("Only Dubson data available."),
+        ])
+        mock_executor = AsyncMock(side_effect=[
+            {"professors": [{"name": "Dubson", "rating": 4.5}]},
+            RuntimeError("network down"),
+        ])
+
+        result = asyncio.run(gemini.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Compare",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        self.assertTrue(result.used_tool)
+        self.assertEqual(len(result.tool_calls_made), 2)
+        self.assertEqual(gemini.openai_client.chat.completions.create.call_count, 2)
+
+        second_call_msgs = gemini.openai_client.chat.completions.create.call_args_list[1][1]["messages"]
+        tool_msgs = [m for m in second_call_msgs if m.get("role") == "tool"]
+        self.assertEqual(len(tool_msgs), 2)
+        error_content = json.loads(tool_msgs[1]["content"])
+        self.assertIn("error", error_content)

multi_llm_chatbot_backend/app/tests/unit/test_rmp_tool.py

@@ -0,0 +1,169 @@
+import asyncio
+import unittest
+from unittest.mock import AsyncMock, MagicMock, patch
+
+from app.tools.rate_my_professor import TOOL_DEFINITION, execute
+
+
+def _graphql_success_response(nodes):
+    """Build a mock RMP GraphQL response containing the given teacher nodes."""
+    edges = [{"cursor": f"c{i}", "node": n} for i, n in enumerate(nodes)]
+    return {
+        "data": {
+            "search": {
+                "teachers": {
+                    "didFallback": False,
+                    "edges": edges,
+                    "pageInfo": {"hasNextPage": False, "endCursor": ""},
+                }
+            }
+        }
+    }
+
+
+SAMPLE_NODE = {
+    "id": "VGVhY2hlci0xMjM0",
+    "legacyId": 1234,
+    "firstName": "Jane",
+    "lastName": "Smith",
+    "department": "Computer Science",
+    "school": {"id": "U2Nob29sLTEwODc=", "name": "University of Colorado Boulder"},
+    "avgRating": 4.2,
+    "avgDifficulty": 3.1,
+    "wouldTakeAgainPercent": 85.0,
+    "numRatings": 42,
+}
+
+
+class TestRMPToolContract(unittest.TestCase):
+    """The rate_my_professor tool module must export a valid OpenAI
+    tool definition and an async executor."""
+
+    def test_tool_definition_has_required_fields(self):
+        self.assertEqual(TOOL_DEFINITION["type"], "function")
+        self.assertIn("function", TOOL_DEFINITION)
+        fn = TOOL_DEFINITION["function"]
+        self.assertIn("name", fn)
+        self.assertIn("description", fn)
+        self.assertIn("parameters", fn)
+
+    def test_tool_definition_name(self):
+        self.assertEqual(TOOL_DEFINITION["function"]["name"], "rate_my_professor")
+
+    def test_tool_definition_has_nonempty_description(self):
+        self.assertIsInstance(TOOL_DEFINITION["function"]["description"], str)
+        self.assertGreater(len(TOOL_DEFINITION["function"]["description"]), 0)
+
+    def test_tool_definition_parameters_schema(self):
+        params = TOOL_DEFINITION["function"]["parameters"]
+        self.assertEqual(params["type"], "object")
+        self.assertIn("properties", params)
+        self.assertIn("professor_name", params["properties"])
+
+    def test_execute_is_async_callable(self):
+        self.assertTrue(asyncio.iscoroutinefunction(execute))
+
+
+def _fake_tool_config(name):
+    """Return a fake tool config dict with school_id set."""
+    if name == "rate_my_professor":
+        return {"enabled": True, "school_id": "U2Nob29sLTEwODc="}
+    return {}
+
+
+@patch("app.tools.rate_my_professor.get_settings")
+class TestRMPToolExecutor(unittest.TestCase):
+    """Unit tests for rate_my_professor.execute() with mocked HTTP."""
+
+    def _mock_client(self, get_response, post_response):
+        """Build a mock httpx.AsyncClient with canned GET and POST responses."""
+        get_resp = MagicMock()
+        get_resp.text = '<script>"Authorization":"Basic dGVzdDp0ZXN0"</script>'
+        get_resp.raise_for_status = MagicMock()
+        if get_response is not None:
+            get_resp.text = get_response
+
+        post_resp = MagicMock()
+        post_resp.status_code = 200
+        post_resp.json.return_value = post_response
+        post_resp.raise_for_status = MagicMock()
+
+        client_instance = AsyncMock()
+        client_instance.get = AsyncMock(return_value=get_resp)
+        client_instance.post = AsyncMock(return_value=post_resp)
+
+        ctx = MagicMock()
+        ctx.__aenter__ = AsyncMock(return_value=client_instance)
+        ctx.__aexit__ = AsyncMock(return_value=False)
+        return ctx, client_instance
+
+    def test_execute_returns_professor_data(self, mock_get_settings):
+        """Successful GraphQL response returns structured professor data."""
+        mock_get_settings.return_value.tools.get_tool_config = _fake_tool_config
+        ctx, client = self._mock_client(
+            get_response=None,
+            post_response=_graphql_success_response([SAMPLE_NODE]),
+        )
+
+        with patch("httpx.AsyncClient", return_value=ctx):
+            result = asyncio.run(execute(professor_name="Smith"))
+
+        self.assertIn("professors", result)
+        self.assertEqual(len(result["professors"]), 1)
+
+        prof = result["professors"][0]
+        self.assertEqual(prof["name"], "Jane Smith")
+        self.assertEqual(prof["department"], "Computer Science")
+        self.assertAlmostEqual(prof["rating"], 4.2)
+        self.assertAlmostEqual(prof["difficulty"], 3.1)
+        self.assertEqual(prof["num_ratings"], 42)
+
+    def test_execute_returns_empty_on_no_results(self, mock_get_settings):
+        """When the GraphQL API returns no matching professors, return
+        an empty list — not an error."""
+        mock_get_settings.return_value.tools.get_tool_config = _fake_tool_config
+        ctx, _ = self._mock_client(
+            get_response=None,
+            post_response=_graphql_success_response([]),
+        )
+
+        with patch("httpx.AsyncClient", return_value=ctx):
+            result = asyncio.run(execute(professor_name="Nonexistent"))
+
+        self.assertIn("professors", result)
+        self.assertEqual(len(result["professors"]), 0)
+
+    def test_execute_returns_error_on_api_failure(self, mock_get_settings):
+        """When the HTTP request fails, return an error payload instead
+        of raising an exception."""
+        mock_get_settings.return_value.tools.get_tool_config = _fake_tool_config
+        ctx = MagicMock()
+        client_instance = AsyncMock()
+        client_instance.get = AsyncMock(side_effect=Exception("connection refused"))
+        client_instance.post = AsyncMock(side_effect=Exception("connection refused"))
+        ctx.__aenter__ = AsyncMock(return_value=client_instance)
+        ctx.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("httpx.AsyncClient", return_value=ctx):
+            result = asyncio.run(execute(professor_name="Smith"))
+
+        self.assertIn("professors", result)
+        self.assertEqual(len(result["professors"]), 0)
+        self.assertIn("error", result)
+
+    def test_execute_accepts_name_kwarg(self, mock_get_settings):
+        """The dispatcher passes name= as a kwarg; execute must accept
+        and ignore it without error."""
+        mock_get_settings.return_value.tools.get_tool_config = _fake_tool_config
+        ctx, _ = self._mock_client(
+            get_response=None,
+            post_response=_graphql_success_response([SAMPLE_NODE]),
+        )
+
+        with patch("httpx.AsyncClient", return_value=ctx):
+            result = asyncio.run(
+                execute(name="rate_my_professor", professor_name="Smith")
+            )
+
+        self.assertIn("professors", result)
+        self.assertEqual(len(result["professors"]), 1)

multi_llm_chatbot_backend/app/tests/unit/test_tool_registry.py

@@ -0,0 +1,123 @@
+import asyncio
+import unittest
+from unittest.mock import AsyncMock
+
+from app.tools import (
+    get_tool_definitions,
+    get_tool_executor,
+    list_registered_tools,
+    _REGISTRY,
+)
+
+
+KNOWN_TOOLS = {"search_courses", "rate_my_professor"}
+
+
+class TestToolDiscovery(unittest.TestCase):
+    """Auto-discovery should find every tool module that exports
+    TOOL_DEFINITION + execute."""
+
+    def test_known_tools_are_discovered(self):
+        registered = set(list_registered_tools())
+        for name in KNOWN_TOOLS:
+            self.assertIn(name, registered, f"Tool '{name}' was not discovered")
+
+    def test_registry_entries_have_definition_and_executor(self):
+        for name, entry in _REGISTRY.items():
+            self.assertIn("definition", entry, f"'{name}' missing definition")
+            self.assertIn("executor", entry, f"'{name}' missing executor")
+
+    def test_definitions_have_required_fields(self):
+        for name, entry in _REGISTRY.items():
+            defn = entry["definition"]
+            self.assertEqual(defn["type"], "function")
+            self.assertIn("function", defn)
+            fn = defn["function"]
+            self.assertIn("name", fn)
+            self.assertIn("description", fn)
+            self.assertIn("parameters", fn)
+            self.assertEqual(fn["name"], name)
+
+    def test_executors_are_async_callables(self):
+        for name, entry in _REGISTRY.items():
+            self.assertTrue(
+                asyncio.iscoroutinefunction(entry["executor"]),
+                f"Executor for '{name}' is not an async function",
+            )
+
+
+class TestGetToolDefinitions(unittest.TestCase):
+    """get_tool_definitions() returns OpenAI-format tool dicts,
+    optionally filtered."""
+
+    def test_returns_all_when_no_filter(self):
+        defs = get_tool_definitions()
+        names = {d["function"]["name"] for d in defs}
+        self.assertTrue(KNOWN_TOOLS.issubset(names))
+
+    def test_filter_to_single_tool(self):
+        defs = get_tool_definitions(enabled=["search_courses"])
+        self.assertEqual(len(defs), 1)
+        self.assertEqual(defs[0]["function"]["name"], "search_courses")
+
+    def test_filter_to_multiple_tools(self):
+        defs = get_tool_definitions(enabled=["search_courses", "rate_my_professor"])
+        names = {d["function"]["name"] for d in defs}
+        self.assertEqual(names, KNOWN_TOOLS)
+
+    def test_filter_with_unknown_name_returns_empty(self):
+        defs = get_tool_definitions(enabled=["nonexistent_tool"])
+        self.assertEqual(defs, [])
+
+    def test_filter_with_empty_list_returns_empty(self):
+        defs = get_tool_definitions(enabled=[])
+        self.assertEqual(defs, [])
+
+    def test_filter_ignores_unknown_names_keeps_valid(self):
+        defs = get_tool_definitions(enabled=["search_courses", "bogus"])
+        self.assertEqual(len(defs), 1)
+        self.assertEqual(defs[0]["function"]["name"], "search_courses")
+
+
+class TestGetToolExecutor(unittest.TestCase):
+    """get_tool_executor() returns a dispatcher that routes to the
+    correct tool executor."""
+
+    def test_dispatch_known_tool(self):
+        mock_exec = AsyncMock(return_value={"courses": []})
+        original = _REGISTRY["search_courses"]["executor"]
+        _REGISTRY["search_courses"]["executor"] = mock_exec
+        try:
+            dispatch = get_tool_executor()
+            result = asyncio.run(dispatch(name="search_courses", subject="CSCI"))
+            mock_exec.assert_called_once_with(name="search_courses", subject="CSCI")
+            self.assertEqual(result, {"courses": []})
+        finally:
+            _REGISTRY["search_courses"]["executor"] = original
+
+    def test_dispatch_unknown_tool_returns_error(self):
+        dispatch = get_tool_executor()
+        result = asyncio.run(dispatch(name="nonexistent"))
+        self.assertIn("error", result)
+
+    def test_filtered_executor_allows_enabled_tool(self):
+        mock_exec = AsyncMock(return_value={"courses": []})
+        original = _REGISTRY["search_courses"]["executor"]
+        _REGISTRY["search_courses"]["executor"] = mock_exec
+        try:
+            dispatch = get_tool_executor(enabled=["search_courses"])
+            result = asyncio.run(dispatch(name="search_courses", subject="CSCI"))
+            self.assertNotIn("error", result)
+        finally:
+            _REGISTRY["search_courses"]["executor"] = original
+
+    def test_filtered_executor_blocks_disabled_tool(self):
+        dispatch = get_tool_executor(enabled=["search_courses"])
+        result = asyncio.run(dispatch(name="rate_my_professor", professor_name="Smith"))
+        self.assertIn("error", result)
+        self.assertIn("not enabled", result["error"])
+
+    def test_filtered_executor_with_empty_list_blocks_all(self):
+        dispatch = get_tool_executor(enabled=[])
+        result = asyncio.run(dispatch(name="search_courses", subject="CSCI"))
+        self.assertIn("error", result)

multi_llm_chatbot_backend/app/tests/unit/test_vllm_client.py

@@ -1,15 +1,31 @@
 import asyncio
+import json
 import unittest
 from unittest.mock import AsyncMock, MagicMock, patch
 
 from openai import APIConnectionError, APIStatusError
 
+from app.llm.llm_client import ToolCallResult
 from app.llm.improved_vllm_client import ImprovedVllmClient
 
 
 FAKE_URL = "https://fake.example.com/vllm0"
 FAKE_KEY = "test-key"
 
+FAKE_TOOL = {
+    "type": "function",
+    "function": {
+        "name": "search_courses",
+        "description": "Search courses",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "subject": {"type": "string", "description": "Subject code"},
+            },
+        },
+    },
+}
+
 
 def _make_completion_mock(content="Response"):
     """Build a mock that looks like an OpenAI ChatCompletion."""
@@ -20,6 +36,77 @@ def _make_completion_mock(content="Response"):
     return MagicMock(choices=[mock_choice])
 
 
+def _make_text_completion_mock(content="Response"):
+    """Build a ChatCompletion mock with no tool calls."""
+    mock_message = MagicMock()
+    mock_message.content = content
+    mock_message.tool_calls = None
+    mock_choice = MagicMock()
+    mock_choice.message = mock_message
+    return MagicMock(choices=[mock_choice])
+
+
+def _make_tool_call_mock(fn_name, fn_args_dict, tool_call_id="call_123"):
+    """Build a ChatCompletion mock where the model requests a tool call."""
+    fn_args_json = json.dumps(fn_args_dict)
+
+    tool_call = MagicMock()
+    tool_call.id = tool_call_id
+    tool_call.function.name = fn_name
+    tool_call.function.arguments = fn_args_json
+
+    mock_message = MagicMock()
+    mock_message.content = None
+    mock_message.tool_calls = [tool_call]
+    mock_message.model_dump.return_value = {
+        "role": "assistant",
+        "content": None,
+        "tool_calls": [{
+            "id": tool_call_id,
+            "type": "function",
+            "function": {"name": fn_name, "arguments": fn_args_json},
+        }],
+    }
+
+    mock_choice = MagicMock()
+    mock_choice.message = mock_message
+    return MagicMock(choices=[mock_choice])
+
+
+def _make_multi_tool_call_mock(calls):
+    """Build a ChatCompletion mock with multiple parallel tool calls.
+
+    *calls* is a list of (fn_name, fn_args_dict, tool_call_id) tuples.
+    """
+    tool_calls = []
+    dump_calls = []
+    for fn_name, fn_args_dict, tool_call_id in calls:
+        fn_args_json = json.dumps(fn_args_dict)
+        tc = MagicMock()
+        tc.id = tool_call_id
+        tc.function.name = fn_name
+        tc.function.arguments = fn_args_json
+        tool_calls.append(tc)
+        dump_calls.append({
+            "id": tool_call_id,
+            "type": "function",
+            "function": {"name": fn_name, "arguments": fn_args_json},
+        })
+
+    mock_message = MagicMock()
+    mock_message.content = None
+    mock_message.tool_calls = tool_calls
+    mock_message.model_dump.return_value = {
+        "role": "assistant",
+        "content": None,
+        "tool_calls": dump_calls,
+    }
+
+    mock_choice = MagicMock()
+    mock_choice.message = mock_message
+    return MagicMock(choices=[mock_choice])
+
+
 @patch("app.llm.improved_vllm_client.get_context_manager")
 @patch("app.llm.improved_vllm_client.AsyncOpenAI")
 class TestImprovedVllmClient(unittest.TestCase):
@@ -214,3 +301,328 @@ class TestImprovedVllmClient(unittest.TestCase):
         self.assertNotIn("\r", cleaned)
         self.assertNotIn("\n\n\n", cleaned)
         self.assertEqual(cleaned, "Line one.\n\nLine two.")
+
+
+@patch("app.llm.improved_vllm_client.get_context_manager")
+@patch("app.llm.improved_vllm_client.AsyncOpenAI")
+class TestVllmGenerateWithTools(unittest.TestCase):
+    """Unit tests for ImprovedVllmClient.generate_with_tools()."""
+
+    # ------------------------------------------------------------------
+    # Happy path — no tool call
+    # ------------------------------------------------------------------
+
+    def test_text_response_returns_not_used(self, MockAsyncOpenAI, mock_get_ctx):
+        """When the model responds with plain text, return used_tool=False."""
+        client = ImprovedVllmClient(
+            api_url=FAKE_URL, api_key=FAKE_KEY, model_name="test-model",
+        )
+        client.client.chat.completions.create = AsyncMock(
+            return_value=_make_text_completion_mock("Hello, world!"),
+        )
+
+        result = asyncio.run(client.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Hi there",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=AsyncMock(),
+        ))
+
+        self.assertIsInstance(result, ToolCallResult)
+        self.assertEqual(result.text, "Hello, world!")
+        self.assertFalse(result.used_tool)
+
+    # ------------------------------------------------------------------
+    # Happy path — tool call
+    # ------------------------------------------------------------------
+
+    def test_tool_call_executes_and_returns_final_text(self, MockAsyncOpenAI, mock_get_ctx):
+        """When the model requests a tool call, execute it and return
+        the text from the follow-up completion."""
+        client = ImprovedVllmClient(
+            api_url=FAKE_URL, api_key=FAKE_KEY, model_name="test-model",
+        )
+        client.client.chat.completions.create = AsyncMock(side_effect=[
+            _make_tool_call_mock("search_courses", {"subject": "CSCI"}),
+            _make_text_completion_mock("CSCI 1300 is available MWF 10-10:50."),
+        ])
+        mock_executor = AsyncMock(
+            return_value={"courses": [{"title": "Intro to CS"}]},
+        )
+
+        result = asyncio.run(client.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="What CSCI classes are there?",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        mock_executor.assert_called_once_with(
+            name="search_courses", subject="CSCI",
+        )
+        self.assertIsInstance(result, ToolCallResult)
+        self.assertEqual(result.text, "CSCI 1300 is available MWF 10-10:50.")
+        self.assertTrue(result.used_tool)
+        self.assertEqual(result.tool_name, "search_courses")
+        self.assertEqual(result.tool_args, {"subject": "CSCI"})
+        self.assertEqual(len(result.tool_calls_made), 1)
+        self.assertEqual(result.tool_calls_made[0].name, "search_courses")
+        self.assertEqual(client.client.chat.completions.create.call_count, 2)
+
+    # ------------------------------------------------------------------
+    # Payload format
+    # ------------------------------------------------------------------
+
+    def test_tool_definitions_passed_through_in_openai_format(self, MockAsyncOpenAI, mock_get_ctx):
+        """Tool definitions (already in OpenAI format) are passed through
+        directly to the completions API."""
+        client = ImprovedVllmClient(
+            api_url=FAKE_URL, api_key=FAKE_KEY, model_name="test-model",
+        )
+        client.client.chat.completions.create = AsyncMock(
+            return_value=_make_text_completion_mock("Ok"),
+        )
+
+        asyncio.run(client.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Hello",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=AsyncMock(),
+        ))
+
+        call_kwargs = client.client.chat.completions.create.call_args[1]
+        tools = call_kwargs["tools"]
+        self.assertEqual(len(tools), 1)
+        self.assertEqual(tools[0]["type"], "function")
+        self.assertEqual(tools[0]["function"]["name"], "search_courses")
+        self.assertIn("parameters", tools[0]["function"])
+
+    def test_tool_result_appended_to_followup(self, MockAsyncOpenAI, mock_get_ctx):
+        """After executing a tool, the follow-up call must include
+        the assistant message, a ``role: tool`` message, and ``tools=``."""
+        tool_output = {"courses": [{"title": "Algorithms"}]}
+        client = ImprovedVllmClient(
+            api_url=FAKE_URL, api_key=FAKE_KEY, model_name="test-model",
+        )
+        client.client.chat.completions.create = AsyncMock(side_effect=[
+            _make_tool_call_mock("search_courses", {"subject": "CSCI"}),
+            _make_text_completion_mock("Here are the results."),
+        ])
+        mock_executor = AsyncMock(return_value=tool_output)
+
+        asyncio.run(client.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Find CSCI courses",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        second_call_kwargs = client.client.chat.completions.create.call_args_list[1][1]
+        messages = second_call_kwargs["messages"]
+
+        assistant_msg = messages[-2]
+        self.assertEqual(assistant_msg["role"], "assistant")
+
+        tool_msg = messages[-1]
+        self.assertEqual(tool_msg["role"], "tool")
+        self.assertEqual(tool_msg["tool_call_id"], "call_123")
+        self.assertEqual(json.loads(tool_msg["content"]), tool_output)
+
+        self.assertIn("tools", second_call_kwargs,
+                       "Follow-up call must include tools= so the model can "
+                       "request additional tool calls if needed")
+
+    # ------------------------------------------------------------------
+    # Error handling
+    # ------------------------------------------------------------------
+
+    def test_tool_executor_failure_serialises_error_and_continues(self, MockAsyncOpenAI, mock_get_ctx):
+        """If the tool executor raises, the error is serialised as the
+        tool result and the loop continues to the follow-up completion."""
+        client = ImprovedVllmClient(
+            api_url=FAKE_URL, api_key=FAKE_KEY, model_name="test-model",
+        )
+        client.client.chat.completions.create = AsyncMock(side_effect=[
+            _make_tool_call_mock("search_courses", {"subject": "CSCI"}),
+            _make_text_completion_mock("Sorry, I couldn't look that up."),
+        ])
+        mock_executor = AsyncMock(side_effect=RuntimeError("network down"))
+
+        result = asyncio.run(client.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Find CSCI courses",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        self.assertTrue(result.used_tool)
+        self.assertEqual(result.tool_name, "search_courses")
+        self.assertEqual(len(result.tool_calls_made), 1)
+
+        second_call_msgs = client.client.chat.completions.create.call_args_list[1][1]["messages"]
+        tool_msg = [m for m in second_call_msgs if m.get("role") == "tool"][0]
+        self.assertIn("network down", json.loads(tool_msg["content"])["error"])
+
+    def test_connection_error_returns_not_used(self, MockAsyncOpenAI, mock_get_ctx):
+        """APIConnectionError during tool calling returns used_tool=False."""
+        client = ImprovedVllmClient(
+            api_url=FAKE_URL, api_key=FAKE_KEY, model_name="test-model",
+        )
+        client.client.chat.completions.create = AsyncMock(
+            side_effect=APIConnectionError(request=MagicMock()),
+        )
+
+        result = asyncio.run(client.generate_with_tools(
+            system_prompt="Test",
+            user_message="Hi",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=AsyncMock(),
+        ))
+
+        self.assertIsInstance(result, ToolCallResult)
+        self.assertFalse(result.used_tool)
+        self.assertIn("unable to connect", result.text.lower())
+
+    # ------------------------------------------------------------------
+    # Multi-tool call in a single response
+    # ------------------------------------------------------------------
+
+    def test_parallel_tool_calls_all_executed(self, MockAsyncOpenAI, mock_get_ctx):
+        """When the model requests multiple tool calls in one response,
+        all of them are executed and their results fed back."""
+        client = ImprovedVllmClient(
+            api_url=FAKE_URL, api_key=FAKE_KEY, model_name="test-model",
+        )
+        client.client.chat.completions.create = AsyncMock(side_effect=[
+            _make_multi_tool_call_mock([
+                ("rate_my_professor", {"professor_name": "Dubson"}, "call_a"),
+                ("rate_my_professor", {"professor_name": "West"}, "call_b"),
+            ]),
+            _make_text_completion_mock("Dubson has a 4.5 rating. West has a 3.8 rating."),
+        ])
+        mock_executor = AsyncMock(
+            side_effect=[
+                {"professors": [{"name": "Dubson", "rating": 4.5}]},
+                {"professors": [{"name": "West", "rating": 3.8}]},
+            ],
+        )
+
+        result = asyncio.run(client.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Is professor Dubson or West rated better?",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        self.assertEqual(mock_executor.call_count, 2)
+        self.assertTrue(result.used_tool)
+        self.assertIn("Dubson", result.text)
+        self.assertIn("West", result.text)
+        self.assertEqual(len(result.tool_calls_made), 2)
+        self.assertEqual(result.tool_calls_made[0].name, "rate_my_professor")
+        self.assertEqual(result.tool_calls_made[1].args, {"professor_name": "West"})
+        self.assertEqual(client.client.chat.completions.create.call_count, 2)
+
+    def test_parallel_tool_results_all_in_followup_messages(self, MockAsyncOpenAI, mock_get_ctx):
+        """All tool results must appear as separate role:tool messages
+        in the follow-up request."""
+        client = ImprovedVllmClient(
+            api_url=FAKE_URL, api_key=FAKE_KEY, model_name="test-model",
+        )
+        client.client.chat.completions.create = AsyncMock(side_effect=[
+            _make_multi_tool_call_mock([
+                ("rate_my_professor", {"professor_name": "Dubson"}, "call_a"),
+                ("rate_my_professor", {"professor_name": "West"}, "call_b"),
+            ]),
+            _make_text_completion_mock("Comparison complete."),
+        ])
+        mock_executor = AsyncMock(side_effect=[
+            {"professors": [{"name": "Dubson"}]},
+            {"professors": [{"name": "West"}]},
+        ])
+
+        asyncio.run(client.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Compare",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        second_call_msgs = client.client.chat.completions.create.call_args_list[1][1]["messages"]
+        tool_msgs = [m for m in second_call_msgs if m.get("role") == "tool"]
+        self.assertEqual(len(tool_msgs), 2)
+        self.assertEqual(tool_msgs[0]["tool_call_id"], "call_a")
+        self.assertEqual(tool_msgs[1]["tool_call_id"], "call_b")
+
+    # ------------------------------------------------------------------
+    # Multi-round tool calling
+    # ------------------------------------------------------------------
+
+    def test_sequential_tool_rounds(self, MockAsyncOpenAI, mock_get_ctx):
+        """The loop handles a second round of tool calls after the first
+        results are fed back."""
+        client = ImprovedVllmClient(
+            api_url=FAKE_URL, api_key=FAKE_KEY, model_name="test-model",
+        )
+        client.client.chat.completions.create = AsyncMock(side_effect=[
+            _make_tool_call_mock("rate_my_professor", {"professor_name": "Dubson"}, "call_1"),
+            _make_tool_call_mock("rate_my_professor", {"professor_name": "West"}, "call_2"),
+            _make_text_completion_mock("Dubson is rated higher than West."),
+        ])
+        mock_executor = AsyncMock(side_effect=[
+            {"professors": [{"name": "Dubson", "rating": 4.5}]},
+            {"professors": [{"name": "West", "rating": 3.8}]},
+        ])
+
+        result = asyncio.run(client.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Compare Dubson and West",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        self.assertEqual(mock_executor.call_count, 2)
+        self.assertTrue(result.used_tool)
+        self.assertEqual(len(result.tool_calls_made), 2)
+        self.assertEqual(result.tool_name, "rate_my_professor")
+        self.assertEqual(client.client.chat.completions.create.call_count, 3)
+
+    # ------------------------------------------------------------------
+    # Tool executor failure in multi-tool context
+    # ------------------------------------------------------------------
+
+    def test_partial_tool_failure_continues(self, MockAsyncOpenAI, mock_get_ctx):
+        """If one tool call in a batch fails, the error is serialised
+        and the loop continues to the follow-up."""
+        client = ImprovedVllmClient(
+            api_url=FAKE_URL, api_key=FAKE_KEY, model_name="test-model",
+        )
+        client.client.chat.completions.create = AsyncMock(side_effect=[
+            _make_multi_tool_call_mock([
+                ("rate_my_professor", {"professor_name": "Dubson"}, "call_a"),
+                ("rate_my_professor", {"professor_name": "West"}, "call_b"),
+            ]),
+            _make_text_completion_mock("Only Dubson data available."),
+        ])
+        mock_executor = AsyncMock(side_effect=[
+            {"professors": [{"name": "Dubson", "rating": 4.5}]},
+            RuntimeError("network down"),
+        ])
+
+        result = asyncio.run(client.generate_with_tools(
+            system_prompt="You are helpful.",
+            user_message="Compare",
+            tool_definitions=[FAKE_TOOL],
+            tool_executor=mock_executor,
+        ))
+
+        self.assertTrue(result.used_tool)
+        self.assertEqual(len(result.tool_calls_made), 2)
+        self.assertEqual(client.client.chat.completions.create.call_count, 2)
+
+        second_call_msgs = client.client.chat.completions.create.call_args_list[1][1]["messages"]
+        tool_msgs = [m for m in second_call_msgs if m.get("role") == "tool"]
+        self.assertEqual(len(tool_msgs), 2)
+        error_content = json.loads(tool_msgs[1]["content"])
+        self.assertIn("error", error_content)
+

multi_llm_chatbot_backend/app/tools/__init__.py

@@ -0,0 +1,125 @@
+"""
+Tool registry — auto-discovers tool modules in app.tools and provides
+a central API for retrieving definitions and dispatching calls.
+
+Every tool module in this package must export:
+    TOOL_DEFINITION : Dict[str, Any]   — OpenAI tool format
+                                         {"type": "function", "function": {"name": ..., ...}}
+    execute         : async (**kwargs)  — returns Dict[str, Any]
+
+Modules that don't export both are silently skipped.
+
+Filtering semantics for the ``enabled`` parameter:
+    None  — no filter; all registered tools are available (default)
+    []    — explicit empty list; no tools are available
+    [ids] — only the named tools are available
+"""
+
+import importlib
+import inspect
+import logging
+import pkgutil
+from typing import Any, Callable, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Shared User-Agent for HTTP clients in tool modules (FOSE, RMP, etc.).
+BROWSER_UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/131.0.0.0 Safari/537.36"
+)
+
+_REGISTRY: Dict[str, Dict[str, Any]] = {}
+
+
+def _discover_tools() -> None:
+    """Scan sibling modules in app.tools and register any that export
+    TOOL_DEFINITION and execute."""
+    import app.tools as tools_pkg
+
+    for _finder, module_name, _is_pkg in pkgutil.iter_modules(tools_pkg.__path__):
+        qualified = f"app.tools.{module_name}"
+        try:
+            mod = importlib.import_module(qualified)
+        except Exception:
+            logger.warning("Failed to import tool module: %s", qualified, exc_info=True)
+            continue
+
+        defn = getattr(mod, "TOOL_DEFINITION", None)
+        executor = getattr(mod, "execute", None)
+
+        if defn is None or executor is None:
+            continue
+
+        if (not isinstance(defn, dict)
+                or defn.get("type") != "function"
+                or not isinstance(defn.get("function"), dict)
+                or "name" not in defn["function"]):
+            logger.warning("Skipping %s: TOOL_DEFINITION not in OpenAI tool format", qualified)
+            continue
+
+        if not callable(executor) or not inspect.iscoroutinefunction(executor):
+            logger.warning("Skipping %s: execute is not an async callable", qualified)
+            continue
+
+        tool_name = defn["function"]["name"]
+        if tool_name in _REGISTRY:
+            logger.warning(
+                "Duplicate tool name '%s' from %s — skipping", tool_name, qualified,
+            )
+            continue
+
+        _REGISTRY[tool_name] = {"definition": defn, "executor": executor}
+        logger.info("Registered tool: %s (from %s)", tool_name, qualified)
+
+
+def get_tool_definitions(enabled: Optional[List[str]] = None) -> List[Dict[str, Any]]:
+    """Return OpenAI-format tool dicts for registered tools.
+
+    If *enabled* is provided, only return tools whose names are in that list.
+    If None, return all registered tools.
+    """
+    if enabled is None:
+        return [entry["definition"] for entry in _REGISTRY.values()]
+
+    return [
+        _REGISTRY[name]["definition"]
+        for name in enabled
+        if name in _REGISTRY
+    ]
+
+
+def get_tool_executor(enabled: Optional[List[str]] = None) -> Callable:
+    """Return a dispatcher compatible with generate_with_tools(tool_executor=...).
+
+    The returned async callable accepts (name, **kwargs) and routes to the
+    correct tool executor.  If *enabled* is provided, only those tools are
+    dispatchable.
+    """
+    if enabled is not None:
+        allowed = {name for name in enabled if name in _REGISTRY}
+    else:
+        allowed = None
+
+    async def dispatch(name: str, **kwargs: Any) -> Dict[str, Any]:
+        if allowed is not None and name not in allowed:
+            logger.warning("Tool '%s' is not enabled", name)
+            return {"error": f"Tool not enabled: {name}"}
+
+        entry = _REGISTRY.get(name)
+        if entry is None:
+            logger.warning("Unknown tool requested: %s", name)
+            return {"error": f"Unknown tool: {name}"}
+
+        return await entry["executor"](name=name, **kwargs)
+
+    return dispatch
+
+
+def list_registered_tools() -> List[str]:
+    """Return the names of all discovered tools."""
+    return list(_REGISTRY.keys())
+
+
+_discover_tools()

multi_llm_chatbot_backend/app/tools/rate_my_professor.py

@@ -0,0 +1,202 @@
+"""
+rate_my_professor tool — live query against RateMyProfessors' GraphQL API.
+
+Exposes TOOL_DEFINITION (OpenAI tool format) and an execute() coroutine
+that the tool-calling loop dispatches to.
+
+Requires ``school_id`` in the tool config (see phd_config.yaml).
+Use ``scripts/rmp_school_lookup.py`` to find the ID for a given school.
+"""
+
+import logging
+import re
+from typing import Any, Dict, List
+import httpx
+from app.tools import BROWSER_UA
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+RMP_GRAPHQL_URL = "https://www.ratemyprofessors.com/graphql"
+RMP_LANDING_URL = "https://www.ratemyprofessors.com/"
+RMP_SEARCH_URL = "https://www.ratemyprofessors.com/search/professors/1087"
+
+
+TEACHER_SEARCH_QUERY = """
+query TeacherSearchPaginationQuery(
+  $count: Int!
+  $cursor: String
+  $query: TeacherSearchQuery!
+) {
+  search: newSearch {
+    teachers(query: $query, first: $count, after: $cursor) {
+      didFallback
+      edges {
+        cursor
+        node {
+          id
+          legacyId
+          firstName
+          lastName
+          department
+          school { id name }
+          avgRating
+          avgDifficulty
+          wouldTakeAgainPercent
+          numRatings
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+    }
+  }
+}
+"""
+
+TOOL_DEFINITION: Dict[str, Any] = {
+    "type": "function",
+    "function": {
+        "name": "rate_my_professor",
+        "description": (
+            "Look up RateMyProfessors ratings for a CU Boulder professor. "
+            "Returns rating, difficulty, percentage of students who would "
+            "take the professor again, and number of ratings."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "professor_name": {
+                    "type": "string",
+                    "description": (
+                        "Full or partial name of the professor to search for, "
+                        "e.g. 'Hoenigman', 'Jane Smith'."
+                    ),
+                },
+            },
+            "required": ["professor_name"],
+        },
+    },
+}
+
+
+def _node_to_professor(node: Dict[str, Any]) -> Dict[str, Any]:
+    """Convert a GraphQL teacher node to a lightweight result dict."""
+    return {
+        "name": f"{node.get('firstName', '')} {node.get('lastName', '')}".strip(),
+        "department": node.get("department", ""),
+        "rating": node.get("avgRating", 0),
+        "difficulty": node.get("avgDifficulty", 0),
+        "would_take_again_pct": node.get("wouldTakeAgainPercent", -1),
+        "num_ratings": node.get("numRatings", 0),
+        "rmp_id": node.get("id", ""),
+    }
+
+
+async def _extract_auth_token(client: httpx.AsyncClient) -> str:
+    """Fetch the RMP landing page and extract the auth token from the JS bundle.
+
+    Falls back to the well-known Basic test:test token.
+    """
+    try:
+        resp = await client.get(
+            RMP_LANDING_URL, headers={"User-Agent": BROWSER_UA},
+        )
+        m = re.search(
+            r'"Authorization"\s*:\s*"(Basic\s+[A-Za-z0-9+/=]+)"', resp.text,
+        )
+        if m:
+            logger.info("Extracted RMP auth token from page JS")
+            return m.group(1)
+    except Exception as exc:
+        logger.debug("RMP auth token extraction failed: %s", exc)
+
+    return "Basic dGVzdDp0ZXN0"
+
+
+async def execute(
+    *,
+    name: str = "",
+    professor_name: str,
+) -> Dict[str, Any]:
+    """Query RateMyProfessors for a CU Boulder professor by name.
+
+    The 'name' kwarg is passed by the dispatch loop and ignored here.
+    Returns {"professors": [...], "query": {...}}.
+    """
+    tool_cfg = get_settings().tools.get_tool_config("rate_my_professor")
+    school_id = tool_cfg.get("school_id")
+    if not school_id:
+        logger.error("No school_id configured for rate_my_professor")
+        return {
+            "professors": [],
+            "error": "No school_id configured for rate_my_professor",
+            "query": {"professor_name": professor_name},
+        }
+
+    professors: List[Dict[str, Any]] = []
+
+    try:
+        async with httpx.AsyncClient(timeout=30, follow_redirects=True) as client:
+            auth_token = await _extract_auth_token(client)
+
+            headers = {
+                "User-Agent": BROWSER_UA,
+                "Authorization": auth_token,
+                "Content-Type": "application/json",
+                "Referer": f"{RMP_SEARCH_URL}?q={professor_name}",
+                "Origin": "https://www.ratemyprofessors.com",
+            }
+
+            variables = {
+                "count": 20,
+                "cursor": "",
+                "query": {
+                    "text": professor_name,
+                    "schoolID": school_id,
+                    "fallback": True,
+                    "departmentID": None,
+                },
+            }
+
+            resp = await client.post(
+                RMP_GRAPHQL_URL,
+                json={"query": TEACHER_SEARCH_QUERY, "variables": variables},
+                headers=headers,
+            )
+
+            if resp.status_code == 403:
+                logger.warning("RMP GraphQL returned 403 — auth may be invalid")
+                return {
+                    "professors": [],
+                    "error": "RateMyProfessors authentication failed",
+                    "query": {"professor_name": professor_name},
+                }
+
+            resp.raise_for_status()
+            data = resp.json()
+
+            teachers = (
+                data.get("data", {})
+                .get("search", {})
+                .get("teachers", {})
+            )
+
+            for edge in teachers.get("edges", []):
+                node = edge.get("node", {})
+                if node:
+                    professors.append(_node_to_professor(node))
+
+    except Exception as exc:
+        logger.error("RMP API error for %s: %s", professor_name, exc)
+        return {
+            "professors": [],
+            "error": str(exc),
+            "query": {"professor_name": professor_name},
+        }
+
+    return {
+        "professors": professors,
+        "query": {"professor_name": professor_name},
+    }

multi_llm_chatbot_backend/app/tools/search_courses.py

@@ -0,0 +1,191 @@
+"""
+search_courses tool — live query against CU Boulder's FOSE class-search API.
+
+Exposes TOOL_DEFINITION (OpenAI tool format) and an execute() coroutine
+that the tool-calling loop dispatches to.
+"""
+
+import logging
+import re
+from typing import Any, Dict, List, Optional
+import httpx
+from app.tools import BROWSER_UA
+from app.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+FOSE_SEARCH_URL = "https://classes.colorado.edu/api/?page=fose&route=search"
+CLASSES_BASE_URL = "https://classes.colorado.edu"
+
+TOOL_DEFINITION: Dict[str, Any] = {
+    "type": "function",
+    "function": {
+        "name": "search_courses",
+        "description": (
+            "Search the CU Boulder course catalog for classes in a given "
+            "subject, optionally filtered by course number and semester. "
+            "Returns a list of matching sections with title, instructor, "
+            "schedule, and location."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "subject": {
+                    "type": "string",
+                    "description": (
+                        "Department / subject code, e.g. 'CSCI', 'MATH', 'PHYS'."
+                    ),
+                },
+                "course_number": {
+                    "type": "string",
+                    "description": (
+                        "Catalog number to filter on, e.g. '1300'. "
+                        "Omit to return all courses in the subject."
+                    ),
+                },
+                "semester": {
+                    "type": "string",
+                    "description": (
+                        "Semester name, e.g. 'Spring 2026', 'Fall 2025'. "
+                        "Defaults to 'Spring 2026' if not provided."
+                    ),
+                },
+            },
+            "required": ["subject"],
+        },
+    },
+}
+
+def _term_to_srcdb(term: str) -> str:
+    """Convert 'Spring 2026' to '2261', 'Fall 2025' to '2257', etc.
+
+    CU Boulder's FOSE API uses a 4-digit code: literal '2', the last
+    two digits of the year, and a season digit (1=Spring, 4=Summer, 7=Fall).
+    """
+    term_lower = term.lower()
+    ym = re.search(r"20(\d{2})", term)
+    yy = ym.group(1) if ym else "26"
+    if "spring" in term_lower:
+        return f"2{yy}1"
+    if "summer" in term_lower:
+        return f"2{yy}4"
+    if "fall" in term_lower:
+        return f"2{yy}7"
+    return f"2{yy}1"
+
+
+def _parse_schedule(meets: str) -> Dict[str, str]:
+    """Parse 'MWF 10:00am-10:50am' into structured fields."""
+    if not meets:
+        return {"days": "", "start_time": "", "end_time": "", "raw": ""}
+
+    day_match = re.match(r"([A-Za-z]+)", meets)
+    days = day_match.group(1) if day_match else ""
+
+    time_match = re.search(
+        r"(\d{1,2}:\d{2}\s*[ap]m)\s*-\s*(\d{1,2}:\d{2}\s*[ap]m)", meets, re.I
+    )
+    start = time_match.group(1).strip() if time_match else ""
+    end = time_match.group(2).strip() if time_match else ""
+
+    return {"days": days, "start_time": start, "end_time": end, "raw": meets}
+
+
+def _row_to_course(item: Dict[str, Any], term: str) -> Optional[Dict[str, Any]]:
+    """Convert a FOSE result row to a lightweight course dict.
+    Returns None for rows that should be skipped (recitations, cancelled sections, etc.).
+    """
+    schd = item.get("schd", "")
+    if schd and schd not in ("LEC", "SEM", ""):
+        return None
+    if item.get("isCancelled"):
+        return None
+
+    code = item.get("code", "").strip()
+    if not code:
+        code = (
+            f"{item.get('subject', '')} "
+            f"{item.get('catalog_nbr', item.get('catalogNbr', ''))}"
+        ).strip()
+
+    return {
+        "course_code": code,
+        "title": item.get("title", ""),
+        "section": item.get("no", "") or item.get("section", ""),
+        "instructor": item.get("instr", "") or item.get("instructor", "Staff"),
+        "schedule": _parse_schedule(item.get("meets", "") or ""),
+        "location": item.get("bldg", item.get("location", "")),
+        "semester": term,
+    }
+
+
+
+async def execute(
+    *,
+    name: str = "",
+    subject: str,
+    course_number: str = "",
+    semester: str = "Spring 2026",
+) -> Dict[str, Any]:
+    """Query the CU Boulder FOSE API and return matching courses.
+
+    The 'name' kwarg is passed by the dispatch loop and ignored here.
+    Returns {"courses": [...], "query": {...}}.
+    """
+    srcdb = _term_to_srcdb(semester)
+    subject = subject.upper().strip()
+
+    payload = {
+        "other": {"srcdb": srcdb},
+        "criteria": [{"field": "subject", "value": subject}],
+    }
+    headers = {
+        "User-Agent": BROWSER_UA,
+        "Content-Type": "application/json",
+        "Referer": CLASSES_BASE_URL,
+        "Origin": CLASSES_BASE_URL,
+    }
+
+    courses: List[Dict[str, Any]] = []
+
+    try:
+        async with httpx.AsyncClient(timeout=30, follow_redirects=True) as client:
+            resp = await client.post(
+                FOSE_SEARCH_URL, json=payload, headers=headers,
+            )
+            if resp.status_code != 200:
+                logger.warning("FOSE API returned %s for %s", resp.status_code, subject)
+                return {"courses": [], "query": {"subject": subject, "semester": semester}}
+
+            body = resp.json()
+            results = body.get("results", body.get("data", []))
+
+            for item in results:
+                row = _row_to_course(item, semester)
+                if row:
+                    courses.append(row)
+
+    except Exception as exc:
+        logger.error("FOSE API error for %s: %s", subject, exc)
+        return {"courses": [], "error": str(exc), "query": {"subject": subject, "semester": semester}}
+
+    if course_number:
+        cn = course_number.strip()
+        courses = [c for c in courses if cn in c["course_code"]]
+
+    max_results = get_settings().tools.get_tool_config("search_courses").get("max_results", 20)
+
+    total = len(courses)
+    truncated = total > max_results
+    courses = courses[:max_results]
+
+    return {
+        "courses": courses,
+        "total_results": total,
+        "truncated": truncated,
+        "query": {
+            "subject": subject,
+            "course_number": course_number or None,
+            "semester": semester,
+        },
+    }

multi_llm_chatbot_backend/requirements.txt

@@ -1,46 +1,43 @@
 # Core FastAPI framework
-fastapi
-uvicorn[standard]
-python-multipart
+fastapi~=0.135
+uvicorn[standard]~=0.44
+python-multipart~=0.0
 
 # HTTP client for LLM APIs
-httpx
+httpx~=0.28
 openai~=2.30
 
 # Document processing
-PyPDF2
-docx2txt
-python-docx
+PyPDF2~=3.0
+docx2txt~=0.9
+python-docx~=1.2
 
 # Environment configuration
-python-dotenv
+python-dotenv~=1.2
 pyyaml~=6.0
 
 # Persona color generation
 colorhash~=2.3
 
 # Vector database and embeddings
-chromadb
-sentence-transformers
+chromadb~=1.5
+sentence-transformers~=5.3
 
 # Natural language processing
-nltk
-tiktoken
+nltk~=3.9
+tiktoken~=0.12
 
 # PDF generation and export
-reportlab
+reportlab~=4.4
 
 # Database (MongoDB)
-pymongo
-motor
+pymongo~=4.16
+motor~=3.7
 
 # Authentication and security
-passlib[bcrypt]
-# `bcrypt` pinned for compat.
-bcrypt~=4.0
-python-jose[cryptography]
+passlib[bcrypt]~=1.7
+bcrypt~=4.3
+python-jose[cryptography]~=3.5
 
 # Data validation (required for EmailStr in Pydantic)
-email-validator
-python-docx
-python-multipart
+email-validator~=2.3

phd-advisor-frontend/src/contexts/AppConfigContext.js

@@ -40,7 +40,11 @@ const buildAdvisors = (personaItems) => {
  */
 const buildGetAdvisorColors = (advisors) => (advisorId, isDark = false) => {
   const advisor = advisors[advisorId];
-  if (!advisor) return { color: '#6B7280', bgColor: '#F3F4F6' };
+  if (!advisor) {
+    return isDark
+      ? { color: '#9CA3AF', bgColor: '#374151', textColor: '#F9FAFB' }
+      : { color: '#6B7280', bgColor: '#F3F4F6', textColor: '#111827' };
+  }
   return {
     color: isDark ? advisor.darkColor : advisor.color,
     bgColor: isDark ? advisor.darkBgColor : advisor.bgColor,

phd_config.yaml

@@ -150,3 +150,13 @@ llm:
 rag:
   embedding_model: "all-MiniLM-L6-v2"
   chroma_collection: "phd_advisor_documents"
+
+# TODO: For development/testing only. PhD Advisor will likely not use these tools.
+tools:
+  search_courses:
+    enabled: true
+    max_results: 20   # Limit the number of results returned by the search_courses tool
+  rate_my_professor:
+    enabled: true
+    # Run `python3 scripts/rmp_school_lookup.py "<school name>"` to find this value
+    school_id: "U2Nob29sLTEwODc="   # CU Boulder school ID

scripts/rmp_school_lookup.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Look up a RateMyProfessors school ID by name.
+
+Usage:
+    python3 scripts/rmp_school_lookup.py "University of Colorado"
+
+Prints matching schools with their GraphQL IDs (the value to put in
+your config.yaml under tools.rate_my_professor.school_id).
+"""
+
+import asyncio
+import re
+import sys
+
+import httpx
+
+RMP_GRAPHQL_URL = "https://www.ratemyprofessors.com/graphql"
+RMP_LANDING_URL = "https://www.ratemyprofessors.com/"
+BROWSER_UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+    "AppleWebKit/537.36 (KHTML, like Gecko) "
+    "Chrome/131.0.0.0 Safari/537.36"
+)
+
+SCHOOL_SEARCH_QUERY = """
+query SchoolSearchQuery($query: SchoolSearchQuery!) {
+  newSearch {
+    schools(query: $query) {
+      edges {
+        node {
+          id
+          name
+          city
+          state
+        }
+      }
+    }
+  }
+}
+"""
+
+
+async def _extract_auth_token(client: httpx.AsyncClient) -> str:
+    try:
+        resp = await client.get(RMP_LANDING_URL, headers={"User-Agent": BROWSER_UA})
+        m = re.search(r'"Authorization"\s*:\s*"(Basic\s+[A-Za-z0-9+/=]+)"', resp.text)
+        if m:
+            return m.group(1)
+    except Exception:
+        pass
+    return "Basic dGVzdDp0ZXN0"
+
+
+async def search_schools(school_name: str) -> list:
+    async with httpx.AsyncClient(timeout=30, follow_redirects=True) as client:
+        auth_token = await _extract_auth_token(client)
+        resp = await client.post(
+            RMP_GRAPHQL_URL,
+            json={
+                "query": SCHOOL_SEARCH_QUERY,
+                "variables": {"query": {"text": school_name}},
+            },
+            headers={
+                "User-Agent": BROWSER_UA,
+                "Authorization": auth_token,
+                "Content-Type": "application/json",
+            },
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        edges = (
+            data.get("data", {})
+            .get("newSearch", {})
+            .get("schools", {})
+            .get("edges", [])
+        )
+        return [
+            {
+                "school_id": edge["node"]["id"],
+                "name": edge["node"]["name"],
+                "city": edge["node"].get("city", ""),
+                "state": edge["node"].get("state", ""),
+            }
+            for edge in edges
+            if edge.get("node")
+        ]
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python3 scripts/rmp_school_lookup.py <school name>")
+        print('Example: python3 scripts/rmp_school_lookup.py "University of Colorado"')
+        sys.exit(1)
+
+    query = " ".join(sys.argv[1:])
+    results = asyncio.run(search_schools(query))
+
+    if not results:
+        print(f"No schools found matching '{query}'")
+        sys.exit(0)
+
+    print(f"Found {len(results)} school(s) matching '{query}':\n")
+    for school in results:
+        location = ", ".join(filter(None, [school["city"], school["state"]]))
+        print(f"  {school['name']}")
+        print(f"    Location:  {location}")
+        print(f"    school_id: {school['school_id']}")
+        print()
+
+
+if __name__ == "__main__":
+    main()