golf-mcp 0.1.19__py3-none-any.whl → 0.2.0__py3-none-any.whl

golf/examples/basic/resources/weather/common.py

@@ -5,6 +5,7 @@ sharing functionality across multiple resources in a directory.
 """
 
 import os
+from typing import Any
 
 # Read configuration from environment variables
 WEATHER_API_KEY = os.environ.get("WEATHER_API_KEY", "mock_key")
@@ -15,30 +16,22 @@ TEMPERATURE_UNIT = os.environ.get("WEATHER_TEMP_UNIT", "fahrenheit")
 class WeatherApiClient:
     """Mock weather API client."""
 
-    def __init__(
-        self, api_key: str = WEATHER_API_KEY, api_url: str = WEATHER_API_URL
-    ) -> None:
+    def __init__(self, api_key: str = WEATHER_API_KEY, api_url: str = WEATHER_API_URL) -> None:
         self.api_key = api_key
         self.api_url = api_url
         self.unit = TEMPERATURE_UNIT
 
-    async def get_forecast(self, city: str, days: int = 3):
+    async def get_forecast(self, city: str, days: int = 3) -> dict[str, Any]:
         """Get weather forecast for a city (mock implementation)."""
         # This would make an API call in a real implementation
-        print(
-            f"Would call {self.api_url}/forecast/{city} with API key {self.api_key[:4]}..."
-        )
         return {
             "city": city,
             "unit": self.unit,
             "forecast": [{"day": i, "temp": 70 + i} for i in range(days)],
         }
 
-    async def get_current(self, city: str):
+    async def get_current(self, city: str) -> dict[str, Any]:
         """Get current weather for a city (mock implementation)."""
-        print(
-            f"Would call {self.api_url}/current/{city} with API key {self.api_key[:4]}..."
-        )
         return {
             "city": city,
             "unit": self.unit,

golf/examples/basic/resources/weather/current.py

@@ -6,19 +6,19 @@ from typing import Any
 from .common import weather_client
 
 # The URI that clients will use to access this resource
-resource_uri = "weather://current/{city}"
+resource_uri = "weather://current"
 
 
-async def current_weather(city: str) -> dict[str, Any]:
-    """Provide current weather for the specified city.
+async def current_weather() -> dict[str, Any]:
+    """Provide current weather for a default city.
 
     This example demonstrates:
     1. Nested resource organization (resources/weather/current.py)
-    2. Dynamic URI parameters (city in this case)
+    2. Resource without URI parameters
     3. Using shared client from the common.py file
     """
     # Use the shared weather client from common.py
-    weather_data = await weather_client.get_current(city)
+    weather_data = await weather_client.get_current("New York")
 
     # Add some additional data
     weather_data.update(

golf/examples/basic/resources/weather/forecast.py

@@ -6,19 +6,19 @@ from typing import Any
 from .common import weather_client
 
 # The URI that clients will use to access this resource
-resource_uri = "weather://forecast/{city}"
+resource_uri = "weather://forecast"
 
 
-async def forecast_weather(city: str) -> dict[str, Any]:
-    """Provide a weather forecast for the specified city.
+async def forecast_weather() -> dict[str, Any]:
+    """Provide a weather forecast for a default city.
 
     This example demonstrates:
     1. Nested resource organization (resources/weather/forecast.py)
-    2. Dynamic URI parameters (city in this case)
+    2. Resource without URI parameters
     3. Using shared client from the common.py file
     """
     # Use the shared weather client from common.py
-    forecast_data = await weather_client.get_forecast(city, days=5)
+    forecast_data = await weather_client.get_forecast("New York", days=5)
 
     # Add some additional data
     forecast_data.update(

golf/examples/basic/tools/calculator.py

@@ -0,0 +1,94 @@
+"""Enhanced calculator tool with optional LLM-powered explanations."""
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+from golf.utilities import sample
+
+
+class CalculationResult(BaseModel):
+    """Result of a mathematical calculation."""
+
+    result: float
+    operation: str
+    expression: str
+
+
+async def calculate(
+    expression: Annotated[
+        str,
+        Field(
+            description="Mathematical expression to evaluate (e.g., '2 + 3', '10 * 5', '100 / 4')",
+            examples=["2 + 3", "10 * 5.5", "(8 - 3) * 2"],
+        ),
+    ],
+    explain: Annotated[
+        bool,
+        Field(
+            description="Whether to provide an LLM-powered step-by-step explanation",
+            default=False,
+        ),
+    ] = False,
+) -> CalculationResult:
+    """Evaluate a mathematical expression with optional LLM explanation.
+
+    This enhanced calculator can:
+    - Perform basic arithmetic operations (+, -, *, /, parentheses)
+    - Handle decimal numbers
+    - Optionally provide LLM-powered step-by-step explanations
+
+    Examples:
+    - calculate("2 + 3") → 5
+    - calculate("10 * 5.5") → 55.0
+    - calculate("(8 - 3) * 2", explain=True) → 10 with explanation
+    """
+    try:
+        # Simple expression evaluation using eval (safe for basic math)
+        # In production, consider using a proper math expression parser
+        allowed_chars = set("0123456789+-*/.() ")
+        if not all(c in allowed_chars for c in expression):
+            raise ValueError("Expression contains invalid characters")
+
+        # Evaluate the expression
+        result = eval(expression, {"__builtins__": {}}, {})
+
+        # Ensure result is a number
+        if not isinstance(result, (int, float)):
+            raise ValueError("Expression did not evaluate to a number")
+
+        # Generate explanation if requested
+        result_expression = expression
+        if explain:
+            try:
+                explanation = await sample(
+                    f"Explain this mathematical expression step by step: {expression} = {result}",
+                    system_prompt="You are a helpful math tutor. Provide clear, step-by-step explanations.",
+                    max_tokens=200,
+                )
+                result_expression = f"{expression}\n\nExplanation: {explanation}"
+            except Exception:
+                # If sampling fails, continue without explanation
+                result_expression = f"{expression}\n\n(Explanation unavailable)"
+
+        return CalculationResult(
+            result=float(result),
+            operation="evaluate",
+            expression=result_expression,
+        )
+
+    except ZeroDivisionError:
+        return CalculationResult(
+            result=float("inf"),
+            operation="error",
+            expression=f"{expression} → Division by zero",
+        )
+    except Exception as e:
+        return CalculationResult(
+            result=0.0,
+            operation="error",
+            expression=f"{expression} → Error: {str(e)}",
+        )
+
+
+# Export the tool
+export = calculate

golf/examples/basic/tools/say/hello.py

@@ -0,0 +1,65 @@
+"""Enhanced hello tool with elicitation capabilities."""
+
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+from golf.utilities import elicit
+
+
+class Output(BaseModel):
+    """Response from the hello tool."""
+
+    message: str
+
+
+async def hello(
+    name: Annotated[str, Field(description="The name of the person to greet")] = "World",
+    greeting: Annotated[str, Field(description="The greeting phrase to use")] = "Hello",
+    personalized: Annotated[
+        bool,
+        Field(
+            description="Whether to ask for additional personal details to create a personalized greeting",
+            default=False,
+        ),
+    ] = False,
+) -> Output:
+    """Say hello with optional personalized elicitation.
+
+    This enhanced tool can:
+    - Provide basic greetings
+    - Elicit additional personal information for personalized messages
+    - Demonstrate Golf's elicitation capabilities
+
+    Examples:
+    - hello("Alice") → "Hello, Alice!"
+    - hello("Bob", personalized=True) → Asks for details, then personalized greeting
+    """
+    # Basic greeting
+    basic_message = f"{greeting}, {name}!"
+
+    # If personalized greeting is requested, elicit additional info
+    if personalized:
+        try:
+            # Ask for user's mood
+            mood = await elicit(
+                "How are you feeling today?",
+                ["happy", "excited", "calm", "focused", "creative"],
+            )
+
+            # Create personalized message
+            personalized_message = f"{greeting}, {name}! Hope you're having a {mood} day!"
+
+            return Output(message=personalized_message)
+
+        except Exception as e:
+            # If elicitation fails, fall back to basic greeting
+            print(f"Personalization failed: {e}")
+            return Output(message=f"{basic_message} (personalization unavailable)")
+
+    # Return basic greeting
+    print(f"{greeting} {name}...")
+    return Output(message=basic_message)
+
+
+# Designate the entry point function
+export = hello

golf/metrics/collector.py

@@ -66,6 +66,38 @@ class MetricsCollector:
                 ["prompt_name"],
             )
 
+            # Sampling metrics
+            self._metrics["sampling_requests"] = Counter(
+                "golf_sampling_requests_total",
+                "Total number of sampling requests",
+                ["sampling_type", "status"],
+            )
+
+            self._metrics["sampling_duration"] = Histogram(
+                "golf_sampling_duration_seconds",
+                "Sampling request duration in seconds",
+                ["sampling_type"],
+            )
+
+            self._metrics["sampling_tokens"] = Histogram(
+                "golf_sampling_tokens",
+                "Number of tokens in sampling responses",
+                ["sampling_type"],
+            )
+
+            # Elicitation metrics
+            self._metrics["elicitation_requests"] = Counter(
+                "golf_elicitation_requests_total",
+                "Total number of elicitation requests",
+                ["elicitation_type", "status"],
+            )
+
+            self._metrics["elicitation_duration"] = Histogram(
+                "golf_elicitation_duration_seconds",
+                "Elicitation request duration in seconds",
+                ["elicitation_type"],
+            )
+
             # Error metrics
             self._metrics["errors"] = Counter(
                 "golf_errors_total",
@@ -74,18 +106,14 @@ class MetricsCollector:
             )
 
             # Session metrics
-            self._metrics["sessions_total"] = Counter(
-                "golf_sessions_total", "Total number of sessions created"
-            )
+            self._metrics["sessions_total"] = Counter("golf_sessions_total", "Total number of sessions created")
 
             self._metrics["session_duration"] = Histogram(
                 "golf_session_duration_seconds", "Session duration in seconds"
             )
 
             # System metrics
-            self._metrics["uptime"] = Gauge(
-                "golf_uptime_seconds", "Server uptime in seconds"
-            )
+            self._metrics["uptime"] = Gauge("golf_uptime_seconds", "Server uptime in seconds")
 
         except ImportError:
             # Prometheus client not available, disable metrics
@@ -101,9 +129,7 @@ class MetricsCollector:
         if not self.enabled or "tool_executions" not in self._metrics:
             return
 
-        self._metrics["tool_executions"].labels(
-            tool_name=tool_name, status=status
-        ).inc()
+        self._metrics["tool_executions"].labels(tool_name=tool_name, status=status).inc()
 
     def record_tool_duration(self, tool_name: str, duration: float) -> None:
         """Record tool execution duration.
@@ -128,9 +154,7 @@ class MetricsCollector:
         if not self.enabled or "http_requests" not in self._metrics:
             return
 
-        self._metrics["http_requests"].labels(
-            method=method, status_code=str(status_code), path=path
-        ).inc()
+        self._metrics["http_requests"].labels(method=method, status_code=str(status_code), path=path).inc()
 
     def record_http_duration(self, method: str, path: str, duration: float) -> None:
         """Record HTTP request duration.
@@ -143,9 +167,7 @@ class MetricsCollector:
         if not self.enabled or "http_duration" not in self._metrics:
             return
 
-        self._metrics["http_duration"].labels(method=method, path=path).observe(
-            duration
-        )
+        self._metrics["http_duration"].labels(method=method, path=path).observe(duration)
 
     def increment_resource_read(self, resource_uri: str) -> None:
         """Record a resource read.
@@ -174,14 +196,13 @@ class MetricsCollector:
 
         Args:
             component_type: Type of component ('tool', 'resource', 'prompt', 'http')
-            error_type: Type of error ('timeout', 'auth_error', 'validation_error', etc.)
+            error_type: Type of error ('timeout', 'auth_error',
+                'validation_error', etc.)
         """
         if not self.enabled or "errors" not in self._metrics:
             return
 
-        self._metrics["errors"].labels(
-            component_type=component_type, error_type=error_type
-        ).inc()
+        self._metrics["errors"].labels(component_type=component_type, error_type=error_type).inc()
 
     def increment_session(self) -> None:
         """Record a new session."""
@@ -212,6 +233,66 @@ class MetricsCollector:
 
         self._metrics["uptime"].set(seconds)
 
+    def increment_sampling(self, sampling_type: str, status: str) -> None:
+        """Record a sampling request.
+
+        Args:
+            sampling_type: Type of sampling ('sample', 'structured', 'context')
+            status: Request status ('success' or 'error')
+        """
+        if not self.enabled or "sampling_requests" not in self._metrics:
+            return
+
+        self._metrics["sampling_requests"].labels(sampling_type=sampling_type, status=status).inc()
+
+    def record_sampling_duration(self, sampling_type: str, duration: float) -> None:
+        """Record sampling request duration.
+
+        Args:
+            sampling_type: Type of sampling
+            duration: Request duration in seconds
+        """
+        if not self.enabled or "sampling_duration" not in self._metrics:
+            return
+
+        self._metrics["sampling_duration"].labels(sampling_type=sampling_type).observe(duration)
+
+    def record_sampling_tokens(self, sampling_type: str, token_count: int) -> None:
+        """Record sampling token count.
+
+        Args:
+            sampling_type: Type of sampling
+            token_count: Number of tokens in the response
+        """
+        if not self.enabled or "sampling_tokens" not in self._metrics:
+            return
+
+        self._metrics["sampling_tokens"].labels(sampling_type=sampling_type).observe(token_count)
+
+    def increment_elicitation(self, elicitation_type: str, status: str) -> None:
+        """Record an elicitation request.
+
+        Args:
+            elicitation_type: Type of elicitation ('elicit', 'confirmation')
+            status: Request status ('success' or 'error')
+        """
+        if not self.enabled or "elicitation_requests" not in self._metrics:
+            return
+
+        self._metrics["elicitation_requests"].labels(elicitation_type=elicitation_type, status=status).inc()
+
+    def record_elicitation_duration(self, elicitation_type: str, duration: float) -> None:
+        """Record elicitation request duration.
+
+        Args:
+            elicitation_type: Type of elicitation
+            duration: Request duration in seconds
+        """
+        if not self.enabled or "elicitation_duration" not in self._metrics:
+            return
+
+        self._metrics["elicitation_duration"].labels(elicitation_type=elicitation_type).observe(duration)
+
 
 def init_metrics_collector(enabled: bool = False) -> MetricsCollector:
     """Initialize the global metrics collector.

golf/telemetry/__init__.py

@@ -3,8 +3,10 @@
 from golf.telemetry.instrumentation import (
     get_tracer,
     init_telemetry,
+    instrument_elicitation,
     instrument_prompt,
     instrument_resource,
+    instrument_sampling,
     instrument_tool,
     telemetry_lifespan,
 )
@@ -13,6 +15,8 @@ __all__ = [
     "instrument_tool",
     "instrument_resource",
     "instrument_prompt",
+    "instrument_elicitation",
+    "instrument_sampling",
     "telemetry_lifespan",
     "init_telemetry",
     "get_tracer",