Initial setup (#2)

* boilerplate setup

* Add smolagents and tracing code by

@njbrake
.

Minor tweaks.

Co-authored-by: Nathan Brake <[email protected]>

* enh(DEFAULT_PROMPT): Add missing hours word.

* Add test_google_maps_tool

* Update mkdocs.yml

* Update src/surf_spot_finder/cli.py

---------

Co-authored-by: Nathan Brake <[email protected]>

.github/setup.sh

@@ -1,3 +1,2 @@
 python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
 python -m pip install -e .
-python -m pip install --upgrade streamlit

.gitignore

@@ -162,3 +162,5 @@ cython_debug/
 
 .idea/
 .vscode/
+
+telemetry_output

README.md

@@ -13,7 +13,7 @@ This blueprint guides you to ...
 
 📘 To explore this project further and discover other Blueprints, visit the [**Blueprints Hub**](https://developer-hub.mozilla.ai/).
 
-👉 📖 For more detailed guidance on using this project, please visit our [**Docs here**](https://mozilla-ai.github.io/Blueprint-template/)
+👉 📖 For more detailed guidance on using this project, please visit our [**Docs here**](https://mozilla-ai.github.io/surf-spot-finder/)
 
 ### Built with
 - Python 3.10+

demo/app.py

@@ -1,7 +0,0 @@
-import streamlit as st
-
-from blueprint.hello import hello
-
-st.title("Blueprint Demo")
-
-st.write(hello())

demo/run.sh

@@ -1,26 +0,0 @@
-#!/bin/bash
-
-# Adapted from https://docs.streamlit.io/deploy/tutorials/kubernetes
-
-APP_PID=
-stopRunningProcess() {
-    # Based on https://linuxconfig.org/how-to-propagate-a-signal-to-child-processes-from-a-bash-script
-    if test ! "${APP_PID}" = '' && ps -p ${APP_PID} > /dev/null ; then
-       > /proc/1/fd/1 echo "Stopping ${COMMAND_PATH} which is running with process ID ${APP_PID}"
-
-       kill -TERM ${APP_PID}
-       > /proc/1/fd/1 echo "Waiting for ${COMMAND_PATH} to process SIGTERM signal"
-
-        wait ${APP_PID}
-        > /proc/1/fd/1 echo "All processes have stopped running"
-    else
-        > /proc/1/fd/1 echo "${COMMAND_PATH} was not started when the signal was sent or it has already been stopped"
-    fi
-}
-
-trap stopRunningProcess EXIT TERM
-
-streamlit run ${HOME}/document-to-podcast/demo/app.py &
-APP_ID=${!}
-
-wait ${APP_ID}

docs/api.md

@@ -1,3 +1,7 @@
 # API Reference
 
-"::: blueprint.hello"
+::: surf_spot_finder.config.Config
+
+::: surf_spot_finder.agents.smolagents
+
+::: surf_spot_finder.tracing

docs/future-features-contributions.md

@@ -7,21 +7,21 @@ This Blueprint is an evolving project designed to grow with the help of the open
 ## 🌟 **How You Can Contribute**
 
 ### 🛠️ **Enhance the Blueprint**
-- Check the [Issues](https://github.com/mozilla-ai/blueprint-template/issues) page to see if there are feature requests you'd like to implement
-- Refer to our [Contribution Guide](https://github.com/mozilla-ai/blueprint-template/blob/main/CONTRIBUTING.md) for more details on contributions
+- Check the [Issues](https://github.com/mozilla-ai/surf-spot-finder/issues) page to see if there are feature requests you'd like to implement
+- Refer to our [Contribution Guide](https://github.com/mozilla-ai/surf-spot-finder/blob/main/CONTRIBUTING.md) for more details on contributions
 
 ### 🎨 **Extensibility Ideas**
 
 This Blueprint is designed to be a foundation you can build upon. By extending its capabilities, you can open the door to new applications, improve user experience, and adapt the Blueprint to address other use cases. Here are a few ideas for how you can expand its potential:
 
 
-We’d love to see how you can enhance this Blueprint! If you create improvements or extend its capabilities, consider contributing them back to the project so others in the community can benefit from your work. Check out our [Contributions Guide](https://github.com/mozilla-ai/blueprint-template/blob/main/CONTRIBUTING.md) to get started!
+We’d love to see how you can enhance this Blueprint! If you create improvements or extend its capabilities, consider contributing them back to the project so others in the community can benefit from your work. Check out our [Contributions Guide](https://github.com/mozilla-ai/surf-spot-finder/blob/main/CONTRIBUTING.md) to get started!
 
 ### 💡 **Share Your Ideas**
-Got an idea for how this Blueprint could be improved? You can share your suggestions through [GitHub Discussions](https://github.com/mozilla-ai/blueprint-template/discussions).
+Got an idea for how this Blueprint could be improved? You can share your suggestions through [GitHub Discussions](https://github.com/mozilla-ai/surf-spot-finder/discussions).
 
 ### 🌍 **Build New Blueprints**
-This project is part of a larger initiative to create a collection of reusable starter code solutions that use open-source AI tools. If you’re inspired to create your own Blueprint, you can use the [Blueprint-template](https://github.com/new?template_name=Blueprint-template&template_owner=mozilla-ai) to get started.
+This project is part of a larger initiative to create a collection of reusable starter code solutions that use open-source AI tools. If you’re inspired to create your own Blueprint, you can use the [surf-spot-finder](https://github.com/new?template_name=surf-spot-finder&template_owner=mozilla-ai) to get started.
 
 ---
 

mkdocs.yml

@@ -1,6 +1,7 @@
-site_name: Guidance Docs
-repo_url: https://github.com/mozilla-ai/blueprint-template
-repo_name: blueprint-template
+site_name: Surf Spot Finder
+
+repo_url: https://github.com/mozilla-ai/surf-spot-finder
+repo_name: surf-spot-finder
 
 nav:
   - Home: index.md

pyproject.toml

@@ -3,17 +3,26 @@ requires = ["setuptools>=48", "setuptools_scm[toml]>=6.3.1"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "blueprint"
+name = "surf-spot-finder"
 readme = "README.md"
 license = {text = "Apache-2.0"}
 requires-python = ">=3.10"
 dynamic = ["version"]
 dependencies = [
+  "arize-phoenix>=8.12.1",
+  "fire",
   "loguru",
-  "streamlit",
+  "mcp>=1.3.0",
+  "pydantic",
+  "smolagents[litellm,mcp,telemetry]>=1.10.0",
 ]
 
 [project.optional-dependencies]
+demo = [
+  "gradio",
+  "spaces"
+]
+
 docs = [
   "mkdocs",
   "mkdocs-material",
@@ -26,9 +35,9 @@ tests = [
 ]
 
 [project.urls]
-Documentation = "https://mozilla-ai.github.io/Blueprint-template/"
-Issues = "https://github.com/mozilla-ai/Blueprint-template/issues"
-Source = "https://github.com/mozilla-ai/Blueprint-template"
+Documentation = "https://mozilla-ai.github.io/surf-spot-finder/"
+Issues = "https://github.com/mozilla-ai/surf-spot-finder/issues"
+Source = "https://github.com/mozilla-ai/surf-spot-finder"
 
 [tool.setuptools.packages.find]
 exclude = ["tests", "tests.*"]
@@ -36,3 +45,6 @@ where = ["src"]
 namespaces = false
 
 [tool.setuptools_scm]
+
+[project.scripts]
+find-surf-spot = "surf_spot_finder.cli:main"

src/blueprint/hello.py

@@ -1,8 +0,0 @@
-def hello() -> str:
-    """
-    Greets the world
-
-    Returns:
-        str: "Hello, world!"
-    """
-    return "Hello, world!"

src/surf_spot_finder/agents/smolagents.py

@@ -0,0 +1,60 @@
+import os
+from typing import Optional, TYPE_CHECKING
+
+from loguru import logger
+
+if TYPE_CHECKING:
+    from smolagents import CodeAgent
+
+
+@logger.catch(reraise=True)
+def load_smolagent(model_id: str, api_key_var: Optional[str]) -> "CodeAgent":
+    """ """
+    from smolagents import (
+        CodeAgent,
+        ToolCollection,
+        DuckDuckGoSearchTool,
+        VisitWebpageTool,
+        LiteLLMModel,
+    )
+    from mcp import StdioServerParameters
+
+    model = LiteLLMModel(
+        model_id=model_id,
+        api_key_var=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"
+        )
+        agent = CodeAgent(
+            tools=[DuckDuckGoSearchTool(), VisitWebpageTool()],
+            model=model,
+            add_base_tools=True,
+            additional_authorized_imports=["json"],
+        )
+
+    return agent

src/surf_spot_finder/cli.py

@@ -0,0 +1,52 @@
+from typing import Optional
+
+from fire import Fire
+from loguru import logger
+
+from surf_spot_finder.config import (
+    Config,
+    DEFAULT_PROMPT,
+)
+from surf_spot_finder.agents.smolagents import load_smolagent
+from surf_spot_finder.tracing import setup_tracing
+
+
+@logger.catch(reraise=True)
+def find_surf_spot(
+    location: str,
+    date: str,
+    max_driving_hours: int,
+    model_id: str,
+    api_key_var: Optional[str] = None,
+    prompt: str = DEFAULT_PROMPT,
+    json_tracer: bool = True,
+):
+    logger.info("Loading config")
+    config = Config(
+        location=location,
+        date=date,
+        max_driving_hours=max_driving_hours,
+        model_id=model_id,
+        api_key_var=api_key_var,
+        prompt=prompt,
+        json_tracer=json_tracer,
+    )
+
+    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)
+
+    logger.info("Running agent")
+    agent.run(
+        config.prompt.format(
+            LOCATION=config.location,
+            MAX_DRIVING_HOURS=config.max_driving_hours,
+            DATE=config.date,
+        )
+    )
+
+
+def main():
+    Fire(find_surf_spot)

src/surf_spot_finder/config.py

@@ -0,0 +1,26 @@
+from typing import Annotated, Optional
+from pydantic import AfterValidator, BaseModel, FutureDatetime, PositiveInt
+
+
+DEFAULT_PROMPT = (
+    "What will be the best surf spot around {LOCATION}"
+    ", in a radio of {MAX_DRIVING_HOURS} hours driving"
+    ", at {DATE}?"
+)
+
+
+def validate_prompt(value):
+    for placeholder in ("{LOCATION}", "{MAX_DRIVING_HOURS}"):
+        if placeholder not in value:
+            raise ValueError(f"prompt must contain {placeholder}")
+    return value
+
+
+class Config(BaseModel):
+    prompt: str = 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

src/surf_spot_finder/tracing.py

@@ -0,0 +1,57 @@
+from datetime import datetime
+import os
+
+from opentelemetry import trace
+from openinference.instrumentation.smolagents import SmolagentsInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export import SpanExporter
+from phoenix.otel import register
+
+
+class JsonFileSpanExporter(SpanExporter):
+    def __init__(self, file_name: str):
+        self.file_name = file_name
+
+    def export(self, spans) -> None:
+        with open(self.file_name, "a") as f:
+            for span in spans:
+                f.write(
+                    span.to_json() + "\n"
+                )  # Ensure to_json() method is properly implemented
+
+    def shutdown(self):
+        pass
+
+
+def setup_tracing(project_name: str, json_tracer: bool = True) -> TracerProvider:
+    """
+    Set up tracing configuration based on the selected mode.
+
+    Args:
+        project_name: Name of the project for tracing
+        json_tracer: Whether to use the custom JSON file exporter (True) or Phoenix (False)
+
+    Returns:
+        TracerProvider: The configured tracer provider
+    """
+    if json_tracer:
+        local_folder: str = "telemetry_output"
+        if not os.path.exists(local_folder):
+            os.makedirs(local_folder)
+        timestamp = datetime.now().strftime("%Y-%m-%d-%H-%M-%S")
+
+        tracer_provider = TracerProvider()
+        trace.set_tracer_provider(tracer_provider)
+
+        json_file_exporter = JsonFileSpanExporter(
+            file_name=f"{local_folder}/{project_name}-{timestamp}.json"
+        )
+        span_processor = SimpleSpanProcessor(json_file_exporter)
+        tracer_provider.add_span_processor(span_processor)
+    else:
+        tracer_provider = register(project_name=project_name)
+
+    SmolagentsInstrumentor().instrument(tracer_provider=tracer_provider)
+
+    return tracer_provider

tests/unit/agents/test_load_smolagents.py

@@ -0,0 +1,27 @@
+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/test_hello.py

@@ -1,5 +0,0 @@
-from blueprint.hello import hello
-
-
-def test_hello():
-    assert hello() == "Hello, world!"