Some re-arranging to make MCP work, add some doc and tests (#3)

* Some re-arranging to make MCP work, add some doc and tests

* prompt grammar fix

* Add Phoenix info

* Updates from code review

.gitignore

@@ -1,3 +1,7 @@
+# Custom gitignores
+uv.lock
+
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -9,20 +9,49 @@
   </picture>
 </p>
 
-This blueprint guides you to ...
+Many Large Language Model (LLM) capabilities are unlocked when they are given access to tools and given control of their
+own runtime and execution path. However, it's important that as they are given greater capabilities, they are properly
+evaluated and controlled.
 
-📘 To explore this project further and discover other Blueprints, visit the [**Blueprints Hub**](https://developer-hub.mozilla.ai/).
+In this Blueprint, we demonstrate an AI agent designed for an extremely specific task (some refer to this as a "Vertical Agent")
+that is given the web and searching access it needs to find an answer the same way you would find the answer as a human.
+
+This agent is designed for help in finding the next great surf spot near you: the agent is provided with a location, a distance,
+a timestamp, and it's able to independently search and browse the web to recommend the best spot to you along with the
+relevant information!
 
-👉 📖 For more detailed guidance on using this project, please visit our [**Docs here**](https://mozilla-ai.github.io/surf-spot-finder/)
+Although this exact use-case may not be useful to you directly, the framework we provide here is intended to be easily
+adapted to the Agent use case you have in mind.
+
+This implementation uses the [smolagents](https://huggingface.co/docs/smolagents/index) library for Agentic capabilities, alongside
+of the increasingly Model Context Protocol (MCP) which allows for a standard access communication standard for a large number of tools.
+
+📘 To explore this project further and discover other Blueprints, visit the [**Blueprints Hub**](https://developer-hub.mozilla.ai/).
 
 ### Built with
-- Python 3.10+
-- Open-Source Tool 1
-- Open-Source Tool 2
-- ...
+![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
+[![smolagents](https://img.shields.io/badge/Smolagents-%F0%9F%A4%97-yellow)](https://huggingface.co/docs/smolagents/index)
+
+
+## 🚀 Quick Start
 
-## Quick-start
+### 1️⃣ Clone the Project
+```bash
+git clone https://github.com/mozilla-ai/surf-spot-finder.git
+cd surf-spot-finder
+```
 
+### 2️⃣ Update submodule and install dependencies
+```bash
+pip install -e .  # Install root project dependencies
+```
+
+### 3️⃣ Run
+
+```bash
+export OPENAI_API_KEY=yourkeyhere
+surf-spot-finder --location="Pittsburgh Pennsylvania" --date="2025-03-11 22:00" --max-driving-hours=5 --model-id="openai/o1" --api-key-var="OPENAI_API_KEY"
+```
 
 ## How it Works
 
@@ -36,8 +65,26 @@ This blueprint guides you to ...
   - Disk space:
 
 - **Dependencies**:
+  - Docker
   - Dependencies listed in `pyproject.toml`
 
+## Run Tests
+
+```bash
+pip install -e .[tests]
+```
+
+### Unit Tests
+
+```bash
+pytest
+```
+
+### Integration Tests
+
+```bash
+INTEGRATION_TESTS=Y pytest # Requires docker and OPENAI_API_KEY
+```
 
 ## Troubleshooting
 

pyproject.toml

@@ -34,6 +34,11 @@ tests = [
   "pytest-sugar>=0.9.6",
 ]
 
+# TODO maybe we don't want to keep this, or we want to swap this to Lumigator SDK
+tracing = [
+  "arize-phoenix>=8.12.1",
+]
+
 [project.urls]
 Documentation = "https://mozilla-ai.github.io/surf-spot-finder/"
 Issues = "https://github.com/mozilla-ai/surf-spot-finder/issues"
@@ -47,4 +52,6 @@ namespaces = false
 [tool.setuptools_scm]
 
 [project.scripts]
-find-surf-spot = "surf_spot_finder.cli:main"
+surf-spot-finder = "surf_spot_finder.cli:main"
+# TODO maybe this would be lumigator
+start-phoenix = "phoenix.server.main:main"

src/surf_spot_finder/agents/smolagents.py

@@ -8,53 +8,67 @@ if TYPE_CHECKING:
 
 
 @logger.catch(reraise=True)
-def load_smolagent(model_id: str, api_key_var: Optional[str]) -> "CodeAgent":
-    """ """
-    from smolagents import (
+def run_smolagent(
+    model_id: str,
+    prompt: str,
+    api_key_var: Optional[str] = None,
+    api_base: Optional[str] = None,
+) -> "CodeAgent":
+    """
+    Create and configure a Smolagents CodeAgent with the specified model.
+    See https://docs.litellm.ai/docs/providers for details on available LiteLLM providers.
+    Args:
+        model_id (str): Model identifier using LiteLLM syntax (e.g., 'openai/o1', 'anthropic/claude-3-sonnet')
+        prompt (str): Prompt to provide to the model
+        api_key_var (Optional[str]): Name of environment variable containing the API key
+        api_base (Optional[str]): Custom API base URL, if needed for non-default endpoints
+
+    Returns:
+        CodeAgent: Configured agent ready to process requests
+
+    Example:
+        >>> agent = run_smolagent("anthropic/claude-3-haiku", "my prompt here", "ANTHROPIC_API_KEY", None, None)
+        >>> agent.run("Find surf spots near San Diego")
+    """
+    from smolagents import (  # pylint: disable=import-outside-toplevel
         CodeAgent,
-        ToolCollection,
         DuckDuckGoSearchTool,
-        VisitWebpageTool,
         LiteLLMModel,
+        ToolCollection,
+    )
+
+    model = LiteLLMModel(
+        model_id=model_id,
+        api_base=api_base if api_base else None,
+        api_key=os.environ[api_key_var] if api_key_var else None,
     )
+
     from mcp import StdioServerParameters
 
     model = LiteLLMModel(
         model_id=model_id,
-        api_key_var=os.environ[api_key_var] if api_key_var else None,
+        api_base=api_base if api_base else None,
+        api_key=os.environ[api_key_var] if api_key_var else None,
     )
 
-    if "GOOGLE_MAPS_API_KEY" in os.environ:
-        # We could easily use any of the MCPs at https://github.com/modelcontextprotocol/servers
-        # or at https://glama.ai/mcp/servers
-        # or at https://smithery.ai/
-        # https://github.com/modelcontextprotocol/servers/tree/main/src/google-maps
-        server_parameters = StdioServerParameters(
-            command="npx",
-            args=["@modelcontextprotocol/server-google-maps"],
-            env={**os.environ},
-        )
-        # https://huggingface.co/docs/smolagents/v1.10.0/en/reference/tools#smolagents.ToolCollection.from_mcp
-        with ToolCollection.from_mcp(server_parameters) as tool_collection:
-            agent = CodeAgent(
-                tools=[
-                    *tool_collection.tools,
-                    DuckDuckGoSearchTool(),
-                    VisitWebpageTool(),
-                ],
-                model=model,
-                add_base_tools=True,
-                additional_authorized_imports=["json"],
-            )
-    else:
-        logger.debug(
-            "GOOGLE_MAPS_api_key_var not set, running without Google Maps tool"
-        )
+    # We could easily use any of the MCPs at https://github.com/modelcontextprotocol/servers
+    # or at https://glama.ai/mcp/servers
+    # or at https://smithery.ai/
+    server_parameters = StdioServerParameters(
+        command="docker",
+        args=["run", "-i", "--rm", "mcp/fetch"],
+        env={**os.environ},
+    )
+    # https://huggingface.co/docs/smolagents/v1.10.0/en/reference/tools#smolagents.ToolCollection.from_mcp
+    with ToolCollection.from_mcp(server_parameters) as tool_collection:
         agent = CodeAgent(
-            tools=[DuckDuckGoSearchTool(), VisitWebpageTool()],
+            tools=[
+                *tool_collection.tools,
+                DuckDuckGoSearchTool(),
+            ],
             model=model,
-            add_base_tools=True,
-            additional_authorized_imports=["json"],
+            add_base_tools=False,  # Turn this on if you want to let it run python code as it sees fit
         )
+        agent.run(prompt)
 
     return agent

src/surf_spot_finder/cli.py

@@ -7,7 +7,7 @@ from surf_spot_finder.config import (
     Config,
     DEFAULT_PROMPT,
 )
-from surf_spot_finder.agents.smolagents import load_smolagent
+from surf_spot_finder.agents.smolagents import run_smolagent
 from surf_spot_finder.tracing import setup_tracing
 
 
@@ -20,6 +20,7 @@ def find_surf_spot(
     api_key_var: Optional[str] = None,
     prompt: str = DEFAULT_PROMPT,
     json_tracer: bool = True,
+    api_base: Optional[str] = None,
 ):
     logger.info("Loading config")
     config = Config(
@@ -30,21 +31,22 @@ def find_surf_spot(
         api_key_var=api_key_var,
         prompt=prompt,
         json_tracer=json_tracer,
+        api_base=api_base,
     )
 
-    logger.info("Loading agent")
-    agent = load_smolagent(config.model_id, config.api_key_var)
-
     logger.info("Setting up tracing")
-    setup_tracing(project_name="find-surf-spot", json_tracer=config.json_tracer)
+    setup_tracing(project_name="surf-spot-finder", json_tracer=config.json_tracer)
 
     logger.info("Running agent")
-    agent.run(
-        config.prompt.format(
+    run_smolagent(
+        model_id=config.model_id,
+        api_key_var=config.api_key_var,
+        api_base=config.api_base,
+        prompt=config.prompt.format(
             LOCATION=config.location,
             MAX_DRIVING_HOURS=config.max_driving_hours,
             DATE=config.date,
-        )
+        ),
     )
 
 

src/surf_spot_finder/config.py

@@ -1,26 +1,32 @@
 from typing import Annotated, Optional
 from pydantic import AfterValidator, BaseModel, FutureDatetime, PositiveInt
+from datetime import datetime
 
+CURRENT_DATE = datetime.now().strftime("%Y-%m-%d")
 
 DEFAULT_PROMPT = (
     "What will be the best surf spot around {LOCATION}"
-    ", in a radio of {MAX_DRIVING_HOURS} hours driving"
-    ", at {DATE}?"
+    ", in a {MAX_DRIVING_HOURS} hour driving radius"
+    ", at {DATE}? it is currently "
+    + CURRENT_DATE
+    + ". find me the best surf spot and the"
+    " up to date weather forecast for that day."
 )
 
 
-def validate_prompt(value):
-    for placeholder in ("{LOCATION}", "{MAX_DRIVING_HOURS}"):
+def validate_prompt(value) -> str:
+    for placeholder in ("{LOCATION}", "{MAX_DRIVING_HOURS}", "{DATE}"):
         if placeholder not in value:
             raise ValueError(f"prompt must contain {placeholder}")
     return value
 
 
 class Config(BaseModel):
-    prompt: str = Annotated[str, AfterValidator(validate_prompt)]
+    prompt: Annotated[str, AfterValidator(validate_prompt)]
     location: str
     max_driving_hours: PositiveInt
     date: FutureDatetime
     model_id: str
     api_key_var: Optional[str] = None
     json_tracer: bool = True
+    api_base: Optional[str] = None

src/surf_spot_finder/tracing.py

@@ -24,7 +24,7 @@ class JsonFileSpanExporter(SpanExporter):
         pass
 
 
-def setup_tracing(project_name: str, json_tracer: bool = True) -> TracerProvider:
+def setup_tracing(project_name: str, json_tracer: bool) -> TracerProvider:
     """
     Set up tracing configuration based on the selected mode.
 

tests/integration/agents/test_integration_smolagents.py

@@ -0,0 +1,67 @@
+import os
+import pytest
+from unittest.mock import patch
+
+from surf_spot_finder.agents.smolagents import run_smolagent
+
+# TODO I'd rather not use openai
+INTEGRATION_MODEL = "openai/gpt-3.5-turbo"
+API_KEY_VAR = "OPENAI_API_KEY"
+
+
+@pytest.mark.skipif(
+    "INTEGRATION_TESTS" not in os.environ,
+    reason="Integration tests require INTEGRATION_TESTS env var",
+)
+def test_smolagent_integration():
+    """
+    Full integration test of the smolagent functionality.
+
+    Requires:
+    - Docker to be running
+    - OPENAI_API_KEY in environment variables
+    - INTEGRATION_TESTS env var to be set
+    """
+    with patch("smolagents.CodeAgent") as MockCodeAgent:
+        # Create a mock agent that returns itself from run()
+        mock_agent = MockCodeAgent.return_value
+        mock_agent.run.return_value = mock_agent
+
+        # Run the agent
+        result = run_smolagent(
+            INTEGRATION_MODEL,
+            "Find popular surf spots in California",
+            api_key_var=API_KEY_VAR,
+        )
+
+        # Verify the agent was created and run
+        MockCodeAgent.assert_called_once()
+        mock_agent.run.assert_called_once_with("Find popular surf spots in California")
+        assert result is mock_agent
+
+
+@pytest.mark.skipif(
+    "INTEGRATION_TESTS" not in os.environ,
+    reason="Full integration tests require INTEGRATION_TESTS env var",
+)
+def test_smolagent_real_execution():
+    """
+    Tests the actual execution of the agent against real APIs.
+
+    WARNING: This will make actual API calls and incur costs.
+    Only run when explicitly needed for full system testing.
+
+    Requires:
+    - Docker to be running
+    - OPENAI_API_KEY in environment variables
+    - INTEGRATION_TESTS env var to be set
+    """
+    # Run with a simple, inexpensive request
+    agent = run_smolagent(
+        INTEGRATION_MODEL,
+        "What are three popular surf spots in California?",
+        api_key_var=API_KEY_VAR,
+    )
+
+    # Basic verification that we got an agent back
+    assert agent is not None

tests/unit/agents/test_load_smolagents.py

@@ -1,27 +0,0 @@
-from surf_spot_finder.agents.smolagents import load_smolagent
-
-
-def test_google_maps_tool(monkeypatch):
-    monkeypatch.setenv("GEMINI_API_KEY", "FOO")
-
-    no_google_maps_agent = load_smolagent("gemini/gemini-2.0-flash", "GEMINI_API_KEY")
-    assert sorted(list(no_google_maps_agent.tools.keys())) == [
-        "final_answer",
-        "visit_webpage",
-        "web_search",
-    ]
-
-    monkeypatch.setenv("GOOGLE_MAPS_API_KEY", "BAR")
-    google_maps_agent = load_smolagent("gemini/gemini-2.0-flash", "GEMINI_API_KEY")
-    assert sorted(list(google_maps_agent.tools.keys())) == [
-        "final_answer",
-        "maps_directions",
-        "maps_distance_matrix",
-        "maps_elevation",
-        "maps_geocode",
-        "maps_place_details",
-        "maps_reverse_geocode",
-        "maps_search_places",
-        "visit_webpage",
-        "web_search",
-    ]

tests/unit/agents/test_unit_smolagents.py

@@ -0,0 +1,103 @@
+import os
+import pytest
+from unittest.mock import patch, MagicMock
+
+from surf_spot_finder.agents.smolagents import run_smolagent
+
+
+@pytest.fixture
+def mock_smolagents_imports():
+    """Mock the smolagents imports to avoid actual instantiation."""
+    mock_code_agent = MagicMock()
+    mock_ddg_tool = MagicMock()
+    mock_litellm_model = MagicMock()
+    mock_tool_collection = MagicMock()
+
+    # Configure the mock tool collection to work as a context manager
+    mock_tool_collection.from_mcp.return_value.__enter__.return_value = (
+        mock_tool_collection
+    )
+    mock_tool_collection.from_mcp.return_value.__exit__.return_value = None
+    mock_tool_collection.tools = ["mock_tool"]
+
+    with patch.dict(
+        "sys.modules",
+        {
+            "smolagents": MagicMock(
+                CodeAgent=mock_code_agent,
+                DuckDuckGoSearchTool=mock_ddg_tool,
+                LiteLLMModel=mock_litellm_model,
+                ToolCollection=mock_tool_collection,
+            ),
+            "mcp": MagicMock(
+                StdioServerParameters=MagicMock(),
+            ),
+        },
+    ):
+        yield {
+            "CodeAgent": mock_code_agent,
+            "DuckDuckGoSearchTool": mock_ddg_tool,
+            "LiteLLMModel": mock_litellm_model,
+            "ToolCollection": mock_tool_collection,
+        }
+
+
+@pytest.mark.usefixtures("mock_smolagents_imports")
+def test_run_smolagent_with_api_key_var():
+    """Test smolagent creation with an API key from environment variable."""
+    # The patch.dict(os.environ, {"TEST_API_KEY": "test-key-12345"})
+    # is a testing construct that temporarily modifies the environment variables
+    # for the duration of the test.
+    # some tests use TEST_API_KEY while others don't
+    with patch.dict(os.environ, {"TEST_API_KEY": "test-key-12345"}):
+        from smolagents import CodeAgent, LiteLLMModel
+
+        run_smolagent("openai/gpt-4", "Test prompt", api_key_var="TEST_API_KEY")
+
+        LiteLLMModel.assert_called()
+        model_call_kwargs = LiteLLMModel.call_args[1]
+        assert model_call_kwargs["model_id"] == "openai/gpt-4"
+        assert model_call_kwargs["api_key"] == "test-key-12345"
+        assert model_call_kwargs["api_base"] is None
+
+        CodeAgent.assert_called_once()
+        CodeAgent.return_value.run.assert_called_once_with("Test prompt")
+
+
+@pytest.mark.usefixtures("mock_smolagents_imports")
+def test_run_smolagent_with_custom_api_base():
+    """Test smolagent creation with a custom API base."""
+    with patch.dict(os.environ, {"TEST_API_KEY": "test-key-12345"}):
+        from smolagents import LiteLLMModel
+
+        # Act
+        run_smolagent(
+            "anthropic/claude-3-sonnet",
+            "Test prompt",
+            api_key_var="TEST_API_KEY",
+            api_base="https://custom-api.example.com",
+        )
+        last_call = LiteLLMModel.call_args_list[-1]
+
+        assert last_call[1]["model_id"] == "anthropic/claude-3-sonnet"
+        assert last_call[1]["api_key"] == "test-key-12345"
+        assert last_call[1]["api_base"] == "https://custom-api.example.com"
+
+
+@pytest.mark.usefixtures("mock_smolagents_imports")
+def test_run_smolagent_without_api_key():
+    """You should be able to run the smolagent without an API key."""
+    from smolagents import LiteLLMModel
+
+    run_smolagent("ollama_chat/deepseek-r1", "Test prompt")
+
+    last_call = LiteLLMModel.call_args_list[-1]
+    assert last_call[1]["model_id"] == "ollama_chat/deepseek-r1"
+    assert last_call[1]["api_key"] is None
+
+
+def test_run_smolagent_environment_error():
+    """Test that passing a bad api_key_var throws an error"""
+    with patch.dict(os.environ, {}, clear=True):
+        with pytest.raises(KeyError, match="MISSING_KEY"):
+            run_smolagent("test-model", "Test prompt", api_key_var="MISSING_KEY")