golf-mcp 0.2.16__py3-none-any.whl

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

@@ -0,0 +1,36 @@
+"""Weather forecast resource example demonstrating nested resources."""
+
+from datetime import datetime
+from typing import Any
+
+from .client import weather_client
+
+# The URI that clients will use to access this resource
+resource_uri = "weather://forecast"
+
+
+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. Resource without URI parameters
+    3. Using shared client from the client.py file
+    """
+    # Use the shared weather client from client.py
+    forecast_data = await weather_client.get_forecast("New York", days=5)
+
+    # Add some additional data
+    forecast_data.update(
+        {
+            "updated_at": datetime.now().isoformat(),
+            "source": "GolfMCP Weather API",
+            "unit": "fahrenheit",
+        }
+    )
+
+    return forecast_data
+
+
+# Designate the entry point function
+export = forecast_weather

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/__init__.py

@@ -0,0 +1,10 @@
+"""Golf metrics module for Prometheus-compatible metrics collection."""
+
+from golf.metrics.collector import MetricsCollector, get_metrics_collector
+from golf.metrics.registry import init_metrics
+
+__all__ = [
+    "MetricsCollector",
+    "get_metrics_collector",
+    "init_metrics",
+]

golf/metrics/collector.py

@@ -0,0 +1,320 @@
+"""Metrics collector for Golf MCP servers."""
+
+from typing import Optional
+
+# Global metrics collector instance
+_metrics_collector: Optional["MetricsCollector"] = None
+
+
+class MetricsCollector:
+    """Collects metrics for Golf MCP servers using Prometheus client."""
+
+    def __init__(self, enabled: bool = False) -> None:
+        """Initialize the metrics collector.
+
+        Args:
+            enabled: Whether metrics collection is enabled
+        """
+        self.enabled = enabled
+        self._metrics = {}
+
+        if self.enabled:
+            self._init_prometheus_metrics()
+
+    def _init_prometheus_metrics(self) -> None:
+        """Initialize Prometheus metrics if enabled."""
+        try:
+            from prometheus_client import Counter, Histogram, Gauge
+
+            # Tool execution metrics
+            self._metrics["tool_executions"] = Counter(
+                "golf_tool_executions_total",
+                "Total number of tool executions",
+                ["tool_name", "status"],
+            )
+
+            self._metrics["tool_duration"] = Histogram(
+                "golf_tool_duration_seconds",
+                "Tool execution duration in seconds",
+                ["tool_name"],
+            )
+
+            # HTTP request metrics
+            self._metrics["http_requests"] = Counter(
+                "golf_http_requests_total",
+                "Total number of HTTP requests",
+                ["method", "status_code", "path"],
+            )
+
+            self._metrics["http_duration"] = Histogram(
+                "golf_http_request_duration_seconds",
+                "HTTP request duration in seconds",
+                ["method", "path"],
+            )
+
+            # Resource access metrics
+            self._metrics["resource_reads"] = Counter(
+                "golf_resource_reads_total",
+                "Total number of resource reads",
+                ["resource_uri"],
+            )
+
+            # Prompt generation metrics
+            self._metrics["prompt_generations"] = Counter(
+                "golf_prompt_generations_total",
+                "Total number of prompt generations",
+                ["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",
+                "Total number of errors",
+                ["component_type", "error_type"],
+            )
+
+            # Session metrics
+            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")
+
+        except ImportError:
+            # Prometheus client not available, disable metrics
+            self.enabled = False
+
+    def increment_tool_execution(self, tool_name: str, status: str) -> None:
+        """Record a tool execution.
+
+        Args:
+            tool_name: Name of the tool that was executed
+            status: Execution status ('success' or 'error')
+        """
+        if not self.enabled or "tool_executions" not in self._metrics:
+            return
+
+        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.
+
+        Args:
+            tool_name: Name of the tool
+            duration: Execution duration in seconds
+        """
+        if not self.enabled or "tool_duration" not in self._metrics:
+            return
+
+        self._metrics["tool_duration"].labels(tool_name=tool_name).observe(duration)
+
+    def increment_http_request(self, method: str, status_code: int, path: str) -> None:
+        """Record an HTTP request.
+
+        Args:
+            method: HTTP method (GET, POST, etc.)
+            status_code: HTTP status code
+            path: Request path
+        """
+        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()
+
+    def record_http_duration(self, method: str, path: str, duration: float) -> None:
+        """Record HTTP request duration.
+
+        Args:
+            method: HTTP method
+            path: Request path
+            duration: Request duration in seconds
+        """
+        if not self.enabled or "http_duration" not in self._metrics:
+            return
+
+        self._metrics["http_duration"].labels(method=method, path=path).observe(duration)
+
+    def increment_resource_read(self, resource_uri: str) -> None:
+        """Record a resource read.
+
+        Args:
+            resource_uri: URI of the resource that was read
+        """
+        if not self.enabled or "resource_reads" not in self._metrics:
+            return
+
+        self._metrics["resource_reads"].labels(resource_uri=resource_uri).inc()
+
+    def increment_prompt_generation(self, prompt_name: str) -> None:
+        """Record a prompt generation.
+
+        Args:
+            prompt_name: Name of the prompt that was generated
+        """
+        if not self.enabled or "prompt_generations" not in self._metrics:
+            return
+
+        self._metrics["prompt_generations"].labels(prompt_name=prompt_name).inc()
+
+    def increment_error(self, component_type: str, error_type: str) -> None:
+        """Record an error.
+
+        Args:
+            component_type: Type of component ('tool', 'resource', 'prompt', 'http')
+            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()
+
+    def increment_session(self) -> None:
+        """Record a new session."""
+        if not self.enabled or "sessions_total" not in self._metrics:
+            return
+
+        self._metrics["sessions_total"].inc()
+
+    def record_session_duration(self, duration: float) -> None:
+        """Record session duration.
+
+        Args:
+            duration: Session duration in seconds
+        """
+        if not self.enabled or "session_duration" not in self._metrics:
+            return
+
+        self._metrics["session_duration"].observe(duration)
+
+    def set_uptime(self, seconds: float) -> None:
+        """Set the server uptime.
+
+        Args:
+            seconds: Server uptime in seconds
+        """
+        if not self.enabled or "uptime" not in self._metrics:
+            return
+
+        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.
+
+    Args:
+        enabled: Whether to enable metrics collection
+
+    Returns:
+        The initialized metrics collector
+    """
+    global _metrics_collector
+    _metrics_collector = MetricsCollector(enabled=enabled)
+    return _metrics_collector
+
+
+def get_metrics_collector() -> MetricsCollector:
+    """Get the global metrics collector instance.
+
+    Returns:
+        The metrics collector, or a disabled one if not initialized
+    """
+    global _metrics_collector
+    if _metrics_collector is None:
+        _metrics_collector = MetricsCollector(enabled=False)
+    return _metrics_collector

golf/metrics/registry.py

@@ -0,0 +1,12 @@
+"""Metrics registry for Golf MCP servers."""
+
+from golf.metrics.collector import init_metrics_collector
+
+
+def init_metrics(enabled: bool = False) -> None:
+    """Initialize the metrics system.
+
+    Args:
+        enabled: Whether to enable metrics collection
+    """
+    init_metrics_collector(enabled=enabled)

golf/telemetry/__init__.py

@@ -0,0 +1,23 @@
+"""Golf telemetry module for OpenTelemetry instrumentation."""
+
+from golf.telemetry.instrumentation import (
+    get_tracer,
+    init_telemetry,
+    instrument_elicitation,
+    instrument_prompt,
+    instrument_resource,
+    instrument_sampling,
+    instrument_tool,
+    telemetry_lifespan,
+)
+
+__all__ = [
+    "instrument_tool",
+    "instrument_resource",
+    "instrument_prompt",
+    "instrument_elicitation",
+    "instrument_sampling",
+    "telemetry_lifespan",
+    "init_telemetry",
+    "get_tracer",
+]