honeycomb-api 0.1.0__py3-none-any.whl → 0.5.3__py3-none-any.whl

honeycomb/tools/resources/boards.py

@@ -0,0 +1,313 @@
+"""Boards tool definitions for Claude API.
+
+This module provides tool generators and descriptions for
+boards resources.
+"""
+
+from typing import Any
+
+from honeycomb.models import BoardCreate
+from honeycomb.models.tool_inputs import BoardToolInput
+from honeycomb.tools.schemas import add_parameter, generate_schema_from_model
+
+# ==============================================================================
+# Boards Descriptions
+# ==============================================================================
+
+BOARD_DESCRIPTIONS = {
+    "honeycomb_list_boards": (
+        "Lists all boards (dashboards) in your Honeycomb environment (no parameters required). "
+        "Use this to discover existing dashboards before creating new ones, audit dashboard organization, or find boards to update. "
+        "This operation requires no parameters - it automatically lists all boards you have access to. "
+        "Returns a list of board objects including their IDs, names, descriptions, panel configurations, and layout settings."
+    ),
+    "honeycomb_get_board": (
+        "Retrieves detailed configuration for a specific board by its ID. "
+        "Use this to inspect a board's panel layout, query configurations, SLO displays, and text content before modifying it. "
+        "Requires the board ID parameter. "
+        "Returns the complete board configuration including all panel definitions, layout mode (auto or manual), tags, and links to visualizations."
+    ),
+    "honeycomb_create_board": (
+        "Creates a new board (dashboard) with inline query panels, SLO panels, text panels, board views, and preset filters in a single operation. "
+        "Use this to build comprehensive dashboards for service monitoring, create SRE views, or consolidate related visualizations. "
+        "Requires a name and supports inline_query_panels (array of query definitions that will be created automatically), text_panels (markdown content), slo_panels (SLO IDs), views (filtered perspectives), and preset_filters (dynamic filters). "
+        "Each inline query panel needs a name, dataset, time_range, and calculations - optionally include filters, breakdowns, orders, and limit. "
+        "Query panels can include calculated_fields (derived columns) - see honeycomb_create_derived_column for expression syntax. "
+        "For inline SLO panels with SLI expressions: must return boolean, use $ prefix for columns. Example: LT($status_code, 500). "
+        "Board views allow creating filtered perspectives (max 50 per board): each view has a name and filters array with column, operation (=, !=, >, >=, <, <=, contains, starts-with, ends-with, exists, in), and value. "
+        "Preset filters (max 5) allow dynamic filtering of board data: each has column and alias properties. "
+        "Layout defaults to auto-layout (Honeycomb arranges panels) but supports manual layout with explicit positioning. "
+        "The tool orchestrates: creating all inline queries with annotations, inline SLOs, board views, preset filters, assembling panel configurations, and creating the board with all components in one API call."
+    ),
+    "honeycomb_update_board": (
+        "Updates an existing board's name, description, or panel configuration. "
+        "Use this to add new panels, reorder visualizations, update board metadata, or reorganize dashboards as monitoring needs evolve. "
+        "Requires the board ID and the complete updated board configuration. "
+        "Note: This replaces the entire board configuration, so include all panels you want to preserve."
+    ),
+    "honeycomb_delete_board": (
+        "Permanently deletes a board from Honeycomb. "
+        "Use this when removing outdated dashboards, cleaning up test boards, or consolidating overlapping views. "
+        "Requires the board ID parameter. "
+        "Warning: This action cannot be undone. The board and its panel configurations will be permanently deleted, but the underlying queries and SLOs are preserved."
+    ),
+}
+
+
+def get_description(tool_name: str) -> str:
+    """Get the description for a tool in this resource."""
+    return BOARD_DESCRIPTIONS[tool_name]
+
+
+def create_tool_definition(
+    name: str,
+    description: str,
+    input_schema: dict[str, Any],
+    input_examples: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Create a Claude tool definition."""
+    from honeycomb.tools.descriptions import validate_description
+    from honeycomb.tools.schemas import add_metadata_fields, validate_schema, validate_tool_name
+
+    validate_tool_name(name)
+    validate_description(description)
+    validate_schema(input_schema)
+    add_metadata_fields(input_schema)
+
+    definition: dict[str, Any] = {
+        "name": name,
+        "description": description,
+        "input_schema": input_schema,
+    }
+
+    if input_examples:
+        definition["input_examples"] = input_examples
+
+    return definition
+
+
+# ==============================================================================
+# Boards Tool Definitions
+# ==============================================================================
+
+
+def generate_list_boards_tool() -> dict[str, Any]:
+    """Generate honeycomb_list_boards tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": []}
+
+    examples: list[dict[str, Any]] = [
+        {},  # List all boards
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_list_boards",
+        description=get_description("honeycomb_list_boards"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_get_board_tool() -> dict[str, Any]:
+    """Generate honeycomb_get_board tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["board_id"]}
+
+    add_parameter(schema, "board_id", "string", "The board ID to retrieve", required=True)
+
+    examples: list[dict[str, Any]] = [
+        {"board_id": "board-123"},
+        {"board_id": "board-456"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_get_board",
+        description=get_description("honeycomb_get_board"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_create_board_tool() -> dict[str, Any]:
+    """Generate honeycomb_create_board tool definition."""
+    # Use Pydantic model for schema generation (replaces 300+ lines of manual schema building)
+    schema = BoardToolInput.model_json_schema()
+
+    examples: list[dict[str, Any]] = [
+        # Simple: inline query panels with auto-layout
+        {
+            "name": "API Dashboard",
+            "layout_generation": "auto",
+            "inline_query_panels": [
+                {
+                    "name": "Error Count",
+                    "dataset": "api-logs",
+                    "time_range": 3600,
+                    "calculations": [{"op": "COUNT"}],
+                    "filters": [{"column": "status_code", "op": ">=", "value": 500}],
+                },
+                {
+                    "name": "P99 Latency",
+                    "dataset": "api-logs",
+                    "time_range": 3600,
+                    "calculations": [{"op": "P99", "column": "duration_ms"}],
+                },
+            ],
+        },
+        # With text panel
+        {
+            "name": "Service Overview",
+            "description": "Main service health dashboard",
+            "layout_generation": "auto",
+            "inline_query_panels": [
+                {
+                    "name": "Request Rate",
+                    "dataset": "production",
+                    "time_range": 7200,
+                    "calculations": [{"op": "COUNT"}],
+                    "breakdowns": ["endpoint"],
+                }
+            ],
+            "text_panels": [{"content": "## Service Status\nMonitor during peak hours"}],
+        },
+        # Complex: with existing SLO ID
+        {
+            "name": "SRE Dashboard",
+            "layout_generation": "auto",
+            "inline_query_panels": [
+                {
+                    "name": "Error Rate",
+                    "dataset": "api-logs",
+                    "time_range": 3600,
+                    "calculations": [{"op": "COUNT"}],
+                    "filters": [{"column": "status_code", "op": ">=", "value": 500}],
+                    "breakdowns": ["service"],
+                    "orders": [{"op": "COUNT", "order": "descending"}],
+                    "limit": 20,
+                }
+            ],
+            "slo_panels": ["slo-123"],
+            "text_panels": [{"content": "## Alerts\nCheck PagerDuty for incidents"}],
+            "tags": [{"key": "team", "value": "platform"}],
+        },
+        # Advanced: inline SLO creation with derived column
+        {
+            "name": "Production Monitoring",
+            "layout_generation": "auto",
+            "inline_query_panels": [
+                {
+                    "name": "Request Count",
+                    "dataset": "production",
+                    "time_range": 86400,
+                    "calculations": [{"op": "COUNT"}],
+                    "breakdowns": ["service"],
+                }
+            ],
+            "inline_slo_panels": [
+                {
+                    "name": "API Availability",
+                    "dataset": "api-logs",
+                    "sli": {
+                        "alias": "success_rate",
+                        "expression": "IF(LT($status_code, 400), 1, 0)",
+                        "description": "1 if successful, 0 if error",
+                    },
+                    "target_percentage": 99.9,
+                    "time_period_days": 30,
+                    "description": "99.9% availability target",
+                }
+            ],
+            "text_panels": [{"content": "## SLO Policy\nReview weekly"}],
+        },
+        # With board views for filtered perspectives
+        {
+            "name": "Service Dashboard",
+            "layout_generation": "auto",
+            "inline_query_panels": [
+                {
+                    "name": "Request Metrics",
+                    "dataset": "api-logs",
+                    "time_range": 3600,
+                    "calculations": [{"op": "COUNT"}],
+                    "breakdowns": ["service"],
+                }
+            ],
+            "views": [
+                {
+                    "name": "Active Services",
+                    "filters": [{"column": "status", "operation": "=", "value": "active"}],
+                },
+                {
+                    "name": "Production Errors",
+                    "filters": [
+                        {"column": "environment", "operation": "=", "value": "production"},
+                        {"column": "status_code", "operation": ">=", "value": 500},
+                    ],
+                },
+            ],
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_create_board",
+        description=get_description("honeycomb_create_board"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_update_board_tool() -> dict[str, Any]:
+    """Generate honeycomb_update_board tool definition."""
+    base_schema = generate_schema_from_model(
+        BoardCreate,
+        exclude_fields={"id", "links"},
+    )
+
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["board_id"]}
+    add_parameter(schema, "board_id", "string", "The board ID to update", required=True)
+
+    schema["properties"].update(base_schema["properties"])
+    schema["required"].extend(base_schema.get("required", []))
+
+    examples: list[dict[str, Any]] = [
+        {
+            "board_id": "board-123",
+            "name": "Updated Dashboard",
+            "description": "New description",
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_update_board",
+        description=get_description("honeycomb_update_board"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_delete_board_tool() -> dict[str, Any]:
+    """Generate honeycomb_delete_board tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["board_id"]}
+
+    add_parameter(schema, "board_id", "string", "The board ID to delete", required=True)
+
+    examples: list[dict[str, Any]] = [
+        {"board_id": "board-123"},
+        {"board_id": "board-456"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_delete_board",
+        description=get_description("honeycomb_delete_board"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def get_tools() -> list[dict[str, Any]]:
+    """Get all boards tool definitions."""
+    return [
+        generate_list_boards_tool(),
+        generate_get_board_tool(),
+        generate_create_board_tool(),
+        generate_update_board_tool(),
+        generate_delete_board_tool(),
+    ]

honeycomb/tools/resources/burn_alerts.py

@@ -0,0 +1,278 @@
+"""Burn Alerts tool definitions for Claude API.
+
+This module provides tool generators and descriptions for
+burn alerts resources.
+"""
+
+from typing import Any
+
+from honeycomb.models import BurnAlertCreate
+from honeycomb.tools.schemas import add_parameter, generate_schema_from_model
+
+# ==============================================================================
+# Burn Alerts Descriptions
+# ==============================================================================
+
+BURN_ALERT_DESCRIPTIONS = {
+    "honeycomb_list_burn_alerts": (
+        "Lists all burn alerts configured for a specific SLO. "
+        "Use this to discover existing error budget alerts before creating new ones or when reviewing SLO alerting configuration. "
+        "Requires both the dataset slug and SLO ID parameters. "
+        "Returns a list of burn alert objects with their IDs, alert types (exhaustion_time or budget_rate), thresholds, and recipients."
+    ),
+    "honeycomb_get_burn_alert": (
+        "Retrieves detailed configuration for a specific burn alert by ID. "
+        "Use this to inspect an existing burn alert's threshold, alert type, and recipient configuration. "
+        "Requires both the dataset slug and burn alert ID. "
+        "Returns the complete burn alert configuration including the SLO it's attached to."
+    ),
+    "honeycomb_create_burn_alert": (
+        "Creates a new burn alert that fires when an SLO's error budget is depleting too quickly. "
+        "Use this to get early warning when service reliability is degrading, before completely exhausting your error budget. "
+        "Requires a dataset, the SLO ID to attach to, alert type (exhaustion_time or budget_rate), and threshold value. "
+        "For exhaustion_time alerts, specify the threshold in minutes (fires when budget will be exhausted in X minutes). "
+        "For budget_rate alerts, specify threshold as percentage drop within a time window. "
+        "Recipients are OPTIONAL - omit them to create a silent alert, or include inline recipients "
+        "(type + target) to create and attach them automatically."
+    ),
+    "honeycomb_update_burn_alert": (
+        "Updates an existing burn alert's threshold, recipients, or alert type. "
+        "Use this to adjust alerting sensitivity as you learn about your service's error budget consumption patterns. "
+        "Requires the dataset slug, burn alert ID, and the complete updated burn alert configuration. "
+        "Note: This replaces the entire burn alert configuration, so include all fields you want to preserve."
+    ),
+    "honeycomb_delete_burn_alert": (
+        "Permanently deletes a burn alert from an SLO. "
+        "Use this when adjusting SLO alerting strategy or removing redundant burn alerts. "
+        "Requires both the dataset slug and burn alert ID. "
+        "Warning: This action cannot be undone. The alert will stop firing immediately."
+    ),
+}
+
+
+def get_description(tool_name: str) -> str:
+    """Get the description for a tool in this resource."""
+    return BURN_ALERT_DESCRIPTIONS[tool_name]
+
+
+def create_tool_definition(
+    name: str,
+    description: str,
+    input_schema: dict[str, Any],
+    input_examples: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Create a Claude tool definition."""
+    from honeycomb.tools.descriptions import validate_description
+    from honeycomb.tools.schemas import add_metadata_fields, validate_schema, validate_tool_name
+
+    validate_tool_name(name)
+    validate_description(description)
+    validate_schema(input_schema)
+    add_metadata_fields(input_schema)
+
+    definition: dict[str, Any] = {
+        "name": name,
+        "description": description,
+        "input_schema": input_schema,
+    }
+
+    if input_examples:
+        definition["input_examples"] = input_examples
+
+    return definition
+
+
+# ==============================================================================
+# Burn Alerts Tool Definitions
+# ==============================================================================
+
+
+def generate_list_burn_alerts_tool() -> dict[str, Any]:
+    """Generate honeycomb_list_burn_alerts tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset", "slo_id"]}
+
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "slo_id", "string", "The SLO ID to list burn alerts for", required=True)
+
+    examples = [
+        {"dataset": "api-logs", "slo_id": "slo-123"},
+        {"dataset": "production", "slo_id": "slo-456"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_list_burn_alerts",
+        description=get_description("honeycomb_list_burn_alerts"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_get_burn_alert_tool() -> dict[str, Any]:
+    """Generate honeycomb_get_burn_alert tool definition."""
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "burn_alert_id"],
+    }
+
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "burn_alert_id", "string", "The burn alert ID to retrieve", required=True)
+
+    examples = [
+        {"dataset": "api-logs", "burn_alert_id": "ba-123"},
+        {"dataset": "production", "burn_alert_id": "ba-456"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_get_burn_alert",
+        description=get_description("honeycomb_get_burn_alert"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_create_burn_alert_tool() -> dict[str, Any]:
+    """Generate honeycomb_create_burn_alert tool definition."""
+    base_schema = generate_schema_from_model(
+        BurnAlertCreate,
+        exclude_fields={"created_at", "updated_at", "id"},
+    )
+
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset"]}
+    add_parameter(
+        schema, "dataset", "string", "The dataset slug to create the burn alert in", required=True
+    )
+
+    schema["properties"].update(base_schema["properties"])
+    schema["required"].extend(base_schema.get("required", []))
+
+    if "$defs" in base_schema:
+        schema["$defs"] = base_schema["$defs"]
+
+    examples = [
+        # Exhaustion time alert without recipients (recipients are optional)
+        {
+            "dataset": "api-logs",
+            "alert_type": "exhaustion_time",
+            "slo_id": "slo-123",
+            "exhaustion_minutes": 60,
+        },
+        # Exhaustion time alert with ID-based recipient
+        {
+            "dataset": "api-logs",
+            "alert_type": "exhaustion_time",
+            "slo_id": "slo-456",
+            "exhaustion_minutes": 60,
+            "recipients": [{"id": "recip-123"}],
+        },
+        # Budget rate alert with inline recipients
+        {
+            "dataset": "production",
+            "alert_type": "budget_rate",
+            "slo_id": "slo-789",
+            "budget_rate_window_minutes": 60,
+            "budget_rate_decrease_threshold_per_million": 10000,  # 1% drop in 1 hour
+            "description": "Alert when error budget drops by 1% in 1 hour",
+            "recipients": [
+                {"type": "email", "target": "sre@example.com"},
+                {"type": "slack", "target": "#slo-alerts"},
+            ],
+        },
+        # Critical exhaustion alert with PagerDuty
+        {
+            "dataset": "critical-services",
+            "alert_type": "exhaustion_time",
+            "slo_id": "slo-abc",
+            "exhaustion_minutes": 30,
+            "description": "Critical: Budget exhausting in 30 minutes",
+            "recipients": [
+                {
+                    "type": "pagerduty",
+                    "target": "routing-key-critical",
+                    "details": {"severity": "critical"},
+                },
+            ],
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_create_burn_alert",
+        description=get_description("honeycomb_create_burn_alert"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_update_burn_alert_tool() -> dict[str, Any]:
+    """Generate honeycomb_update_burn_alert tool definition."""
+    base_schema = generate_schema_from_model(
+        BurnAlertCreate,
+        exclude_fields={"created_at", "updated_at", "id"},
+    )
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "burn_alert_id"],
+    }
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "burn_alert_id", "string", "The burn alert ID to update", required=True)
+
+    schema["properties"].update(base_schema["properties"])
+    schema["required"].extend(base_schema.get("required", []))
+
+    if "$defs" in base_schema:
+        schema["$defs"] = base_schema["$defs"]
+
+    examples = [
+        {
+            "dataset": "api-logs",
+            "burn_alert_id": "ba-123",
+            "alert_type": "exhaustion_time",
+            "slo_id": "slo-123",
+            "exhaustion_minutes": 30,  # Updated from 60 to 30
+            "recipients": [{"id": "recip-123"}],
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_update_burn_alert",
+        description=get_description("honeycomb_update_burn_alert"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_delete_burn_alert_tool() -> dict[str, Any]:
+    """Generate honeycomb_delete_burn_alert tool definition."""
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "burn_alert_id"],
+    }
+
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "burn_alert_id", "string", "The burn alert ID to delete", required=True)
+
+    examples = [
+        {"dataset": "api-logs", "burn_alert_id": "ba-123"},
+        {"dataset": "production", "burn_alert_id": "ba-456"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_delete_burn_alert",
+        description=get_description("honeycomb_delete_burn_alert"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def get_tools() -> list[dict[str, Any]]:
+    """Get all burn alerts tool definitions."""
+    return [
+        generate_list_burn_alerts_tool(),
+        generate_get_burn_alert_tool(),
+        generate_create_burn_alert_tool(),
+        generate_update_burn_alert_tool(),
+        generate_delete_burn_alert_tool(),
+    ]