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

honeycomb/tools/resources/marker_settings.py

@@ -0,0 +1,216 @@
+"""Marker Settings tool definitions for Claude API.
+
+This module provides tool generators and descriptions for
+marker settings resources.
+"""
+
+from typing import Any
+
+from honeycomb.models import MarkerSettingCreate
+from honeycomb.tools.schemas import add_parameter, generate_schema_from_model
+
+# ==============================================================================
+# Marker Settings Descriptions
+# ==============================================================================
+
+MARKER_SETTING_DESCRIPTIONS = {
+    "honeycomb_list_marker_settings": (
+        "Lists all marker type-to-color mappings for a dataset. "
+        "Use this as the primary way to view all marker settings, see which marker types have custom colors, or audit marker visualization configuration. "
+        "Requires the dataset slug parameter (or '__all__' for environment-wide settings). "
+        "Returns a list of all marker settings showing type names (e.g., 'deploy', 'incident') and their associated hex color codes."
+    ),
+    "honeycomb_get_marker_setting": (
+        "Retrieves a specific marker setting by its ID. "
+        "Use this rarely when you need a specific setting by ID - prefer list_marker_settings to view all settings. "
+        "Requires both the dataset slug and setting ID parameters. "
+        "Returns the marker setting configuration including type name and color code."
+    ),
+    "honeycomb_create_marker_setting": (
+        "Creates a new marker type-to-color mapping. "
+        "Use this to assign colors to marker types for visual consistency (e.g., deployments in green, incidents in red). "
+        "Requires the dataset slug (or '__all__' for environment-wide), marker type name, and hex color code (e.g., '#00FF00'). "
+        "Once created, all markers of this type will display in the specified color on graphs and timelines."
+    ),
+    "honeycomb_update_marker_setting": (
+        "Updates an existing marker setting's type or color. "
+        "Use this to change marker colors for better visual distinction or rename marker types. "
+        "Requires the dataset slug, setting ID, and updated configuration (type and color). "
+        "The color change applies immediately to all existing and future markers of this type."
+    ),
+    "honeycomb_delete_marker_setting": (
+        "Permanently deletes a marker setting. "
+        "Use this when removing unused marker types or resetting color customizations. "
+        "Requires both the dataset slug and setting ID parameters. "
+        "Warning: Existing markers of this type will lose their custom color and revert to default visualization."
+    ),
+}
+
+
+def get_description(tool_name: str) -> str:
+    """Get the description for a tool in this resource."""
+    return MARKER_SETTING_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
+
+
+# ==============================================================================
+# Marker Settings Tool Definitions
+# ==============================================================================
+
+
+def generate_list_marker_settings_tool() -> dict[str, Any]:
+    """Generate honeycomb_list_marker_settings tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset"]}
+    add_parameter(
+        schema,
+        "dataset",
+        "string",
+        "The dataset slug (or '__all__' for environment-wide)",
+        required=True,
+    )
+
+    examples: list[dict[str, Any]] = [{"dataset": "api-logs"}, {"dataset": "__all__"}]
+
+    return create_tool_definition(
+        name="honeycomb_list_marker_settings",
+        description=get_description("honeycomb_list_marker_settings"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_get_marker_setting_tool() -> dict[str, Any]:
+    """Generate honeycomb_get_marker_setting tool definition."""
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "setting_id"],
+    }
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "setting_id", "string", "The marker setting ID", required=True)
+
+    examples: list[dict[str, Any]] = [{"dataset": "api-logs", "setting_id": "set-123"}]
+
+    return create_tool_definition(
+        name="honeycomb_get_marker_setting",
+        description=get_description("honeycomb_get_marker_setting"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_create_marker_setting_tool() -> dict[str, Any]:
+    """Generate honeycomb_create_marker_setting tool definition."""
+    base_schema = generate_schema_from_model(
+        MarkerSettingCreate, exclude_fields={"id", "created_at", "updated_at"}
+    )
+
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset"]}
+    add_parameter(
+        schema,
+        "dataset",
+        "string",
+        "The dataset slug (or '__all__' for environment-wide)",
+        required=True,
+    )
+
+    schema["properties"].update(base_schema["properties"])
+    schema["required"].extend(base_schema.get("required", []))
+
+    examples: list[dict[str, Any]] = [
+        {"dataset": "api-logs", "type": "deploy", "color": "#00FF00"},
+        {"dataset": "__all__", "type": "incident", "color": "#FF0000"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_create_marker_setting",
+        description=get_description("honeycomb_create_marker_setting"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_update_marker_setting_tool() -> dict[str, Any]:
+    """Generate honeycomb_update_marker_setting tool definition."""
+    base_schema = generate_schema_from_model(
+        MarkerSettingCreate, exclude_fields={"id", "created_at", "updated_at"}
+    )
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "setting_id"],
+    }
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "setting_id", "string", "The marker setting ID to update", required=True)
+
+    schema["properties"].update(base_schema["properties"])
+    schema["required"].extend(base_schema.get("required", []))
+
+    examples: list[dict[str, Any]] = [
+        {"dataset": "api-logs", "setting_id": "set-123", "type": "deploy", "color": "#0000FF"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_update_marker_setting",
+        description=get_description("honeycomb_update_marker_setting"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_delete_marker_setting_tool() -> dict[str, Any]:
+    """Generate honeycomb_delete_marker_setting tool definition."""
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "setting_id"],
+    }
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "setting_id", "string", "The marker setting ID to delete", required=True)
+
+    examples: list[dict[str, Any]] = [{"dataset": "api-logs", "setting_id": "set-123"}]
+
+    return create_tool_definition(
+        name="honeycomb_delete_marker_setting",
+        description=get_description("honeycomb_delete_marker_setting"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def get_tools() -> list[dict[str, Any]]:
+    """Get all marker settings tool definitions."""
+    return [
+        generate_list_marker_settings_tool(),
+        generate_get_marker_setting_tool(),
+        generate_create_marker_setting_tool(),
+        generate_update_marker_setting_tool(),
+        generate_delete_marker_setting_tool(),
+    ]

honeycomb/tools/resources/markers.py

@@ -0,0 +1,197 @@
+"""Markers tool definitions for Claude API.
+
+This module provides tool generators and descriptions for
+markers resources.
+"""
+
+from typing import Any
+
+from honeycomb.models import MarkerCreate
+from honeycomb.tools.schemas import add_parameter, generate_schema_from_model
+
+# ==============================================================================
+# Markers Descriptions
+# ==============================================================================
+
+MARKER_DESCRIPTIONS = {
+    "honeycomb_list_markers": (
+        "Lists all markers (event annotations) in a dataset. "
+        "Use this to view deployment history, configuration changes, incidents, or other significant events marked on your data. "
+        "Requires the dataset slug parameter. "
+        "Returns a list of marker objects including their IDs, messages, types, timestamps, colors, and URLs."
+    ),
+    "honeycomb_create_marker": (
+        "Creates a new marker to annotate your data with significant events like deployments, configuration changes, or incidents. "
+        "Use this to track deployments, mark maintenance windows, document configuration changes, or flag incidents for correlation with metrics. "
+        "Requires dataset slug (or '__all__' for environment-wide), message, and type parameters. "
+        "Optional color parameter (hex code like '#FF5733') can be provided for visual customization - if the marker setting for that type doesn't exist, it should be created first. "
+        "Optional start_time and end_time (Unix timestamps) create time-range markers, otherwise defaults to current time as a point marker."
+    ),
+    "honeycomb_update_marker": (
+        "Updates an existing marker's message, type, timestamps, or URL. "
+        "Use this to correct marker details, update deployment notes, or adjust time ranges for maintenance windows. "
+        "Requires the dataset slug, marker ID, and updated marker configuration. "
+        "Note: Colors are controlled by marker settings, not directly on markers."
+    ),
+    "honeycomb_delete_marker": (
+        "Permanently deletes a marker from a dataset. "
+        "Use this when removing incorrect markers, cleaning up test annotations, or removing outdated event tracking. "
+        "Requires both the dataset slug and marker ID parameters. "
+        "Warning: This action cannot be undone. The marker will be removed from all visualizations."
+    ),
+}
+
+
+def get_description(tool_name: str) -> str:
+    """Get the description for a tool in this resource."""
+    return MARKER_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
+
+
+# ==============================================================================
+# Markers Tool Definitions
+# ==============================================================================
+
+
+def generate_list_markers_tool() -> dict[str, Any]:
+    """Generate honeycomb_list_markers tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset"]}
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+
+    examples: list[dict[str, Any]] = [{"dataset": "api-logs"}, {"dataset": "production"}]
+
+    return create_tool_definition(
+        name="honeycomb_list_markers",
+        description=get_description("honeycomb_list_markers"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_create_marker_tool() -> dict[str, Any]:
+    """Generate honeycomb_create_marker tool definition."""
+    base_schema = generate_schema_from_model(
+        MarkerCreate, exclude_fields={"id", "created_at", "updated_at", "color"}
+    )
+
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset"]}
+    add_parameter(
+        schema,
+        "dataset",
+        "string",
+        "The dataset slug (or '__all__' for environment-wide)",
+        required=True,
+    )
+    add_parameter(schema, "color", "string", "Optional hex color (e.g., '#FF5733')", required=False)
+
+    schema["properties"].update(base_schema["properties"])
+    schema["required"].extend(base_schema.get("required", []))
+
+    examples: list[dict[str, Any]] = [
+        {"dataset": "api-logs", "message": "deploy v1.2.3", "type": "deploy"},
+        {
+            "dataset": "__all__",
+            "message": "maintenance window",
+            "type": "maintenance",
+            "start_time": 1640000000,
+            "end_time": 1640003600,
+        },
+        {"dataset": "production", "message": "config change", "type": "config", "color": "#FF5733"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_create_marker",
+        description=get_description("honeycomb_create_marker"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_update_marker_tool() -> dict[str, Any]:
+    """Generate honeycomb_update_marker tool definition."""
+    base_schema = generate_schema_from_model(
+        MarkerCreate, exclude_fields={"id", "created_at", "updated_at", "color"}
+    )
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "marker_id"],
+    }
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "marker_id", "string", "The marker ID to update", required=True)
+
+    schema["properties"].update(base_schema["properties"])
+    schema["required"].extend(base_schema.get("required", []))
+
+    examples: list[dict[str, Any]] = [
+        {
+            "dataset": "api-logs",
+            "marker_id": "abc123",
+            "message": "updated deploy v1.2.4",
+            "type": "deploy",
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_update_marker",
+        description=get_description("honeycomb_update_marker"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_delete_marker_tool() -> dict[str, Any]:
+    """Generate honeycomb_delete_marker tool definition."""
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "marker_id"],
+    }
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "marker_id", "string", "The marker ID to delete", required=True)
+
+    examples: list[dict[str, Any]] = [{"dataset": "api-logs", "marker_id": "abc123"}]
+
+    return create_tool_definition(
+        name="honeycomb_delete_marker",
+        description=get_description("honeycomb_delete_marker"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def get_tools() -> list[dict[str, Any]]:
+    """Get all markers tool definitions."""
+    return [
+        generate_list_markers_tool(),
+        generate_create_marker_tool(),
+        generate_update_marker_tool(),
+        generate_delete_marker_tool(),
+    ]

honeycomb/tools/resources/queries.py

@@ -0,0 +1,220 @@
+"""Queries tool definitions for Claude API.
+
+This module provides tool generators and descriptions for
+queries resources.
+"""
+
+from typing import Any
+
+from honeycomb.models import QuerySpec
+from honeycomb.tools.schemas import add_parameter, generate_schema_from_model
+
+# ==============================================================================
+# Queries Descriptions
+# ==============================================================================
+
+QUERY_DESCRIPTIONS = {
+    "honeycomb_create_query": (
+        "Creates a new saved query in a dataset that can be reused in boards, analysis, or referenced by ID. "
+        "Use this to save frequently-used queries, create queries for dashboard panels, or prepare queries for trigger definitions. "
+        "Requires the dataset slug and query specification including time_range and calculations. "
+        "Optional annotation_name parameter creates the query with a display name for easier identification in the UI. "
+        "The query specification supports multiple calculations (unlike triggers which allow only one), filters, breakdowns, orders, havings, and limits for comprehensive data analysis."
+        "Queries can include calculated_fields (derived columns) - see honeycomb_create_derived_column for expression syntax. "
+    ),
+    "honeycomb_get_query": (
+        "Retrieves a saved query's configuration by its ID. "
+        "Use this to inspect an existing query's calculations, filters, time range, and other settings before modifying it or using it as a template. "
+        "Requires both the dataset slug and query ID parameters. "
+        "Returns the complete query specification including all calculation definitions, filter conditions, breakdown fields, and ordering rules."
+    ),
+    "honeycomb_run_query": (
+        "Creates a saved query, executes it, and returns results with automatic polling until completion. "
+        "Use this for ad-hoc data analysis, investigating issues, or when you want both a saved query and immediate results in one operation. "
+        "Requires the dataset slug (or '__all__' for environment-wide queries) and query specification (time_range, calculations, optional filters/breakdowns/orders/havings/limit). "
+        "This tool performs two operations: first creates a permanent saved query, then executes it with polling and returns the query results including data rows and metadata. "
+        "Supports all query features including multiple calculations (COUNT, AVG, SUM, MIN, MAX, P50-P99, HEATMAP, RATE_*), complex filters, breakdowns, ordering, HAVING clauses, and result limits."
+    ),
+}
+
+
+def get_description(tool_name: str) -> str:
+    """Get the description for a tool in this resource."""
+    return QUERY_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
+
+
+# ==============================================================================
+# Queries Tool Definitions
+# ==============================================================================
+
+
+def generate_create_query_tool() -> dict[str, Any]:
+    """Generate honeycomb_create_query tool definition."""
+    base_schema = generate_schema_from_model(
+        QuerySpec,
+        exclude_fields={"id", "created_at", "updated_at"},
+    )
+
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset"]}
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+
+    # Add optional annotation_name parameter
+    add_parameter(
+        schema,
+        "annotation_name",
+        "string",
+        "Optional name for the query annotation (saves query with a display name)",
+        required=False,
+    )
+
+    schema["properties"].update(base_schema["properties"])
+    schema["required"].extend(base_schema.get("required", []))
+
+    # Add definitions if present
+    if "$defs" in base_schema:
+        schema["$defs"] = base_schema["$defs"]
+
+    examples: list[dict[str, Any]] = [
+        # Simple COUNT query
+        {
+            "dataset": "api-logs",
+            "time_range": 3600,
+            "calculations": [{"op": "COUNT"}],
+        },
+        # P99 with filters
+        {
+            "dataset": "api-logs",
+            "time_range": 3600,
+            "calculations": [{"op": "P99", "column": "duration_ms"}],
+            "filters": [{"column": "status_code", "op": ">=", "value": 200}],
+        },
+        # With annotation name
+        {
+            "dataset": "api-logs",
+            "annotation_name": "Error Rate Dashboard",
+            "time_range": 7200,
+            "calculations": [{"op": "COUNT"}],
+            "filters": [{"column": "status_code", "op": ">=", "value": 500}],
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_create_query",
+        description=get_description("honeycomb_create_query"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_get_query_tool() -> dict[str, Any]:
+    """Generate honeycomb_get_query tool definition."""
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "query_id"],
+    }
+
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "query_id", "string", "The query ID to retrieve", required=True)
+
+    examples: list[dict[str, Any]] = [
+        {"dataset": "api-logs", "query_id": "q-123"},
+        {"dataset": "production", "query_id": "q-456"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_get_query",
+        description=get_description("honeycomb_get_query"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_run_query_tool() -> dict[str, Any]:
+    """Generate honeycomb_run_query tool definition."""
+    base_schema = generate_schema_from_model(
+        QuerySpec,
+        exclude_fields={"id", "created_at", "updated_at"},
+    )
+
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset"]}
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+
+    schema["properties"].update(base_schema["properties"])
+    schema["required"].extend(base_schema.get("required", []))
+
+    # Add definitions if present
+    if "$defs" in base_schema:
+        schema["$defs"] = base_schema["$defs"]
+
+    examples: list[dict[str, Any]] = [
+        # Count in last hour
+        {
+            "dataset": "api-logs",
+            "time_range": 3600,
+            "calculations": [{"op": "COUNT"}],
+        },
+        # P99 with breakdowns
+        {
+            "dataset": "api-logs",
+            "time_range": 7200,
+            "calculations": [{"op": "P99", "column": "duration_ms"}],
+            "breakdowns": ["endpoint"],
+        },
+        # Multiple calculations with filters and ordering
+        {
+            "dataset": "api-logs",
+            "time_range": 3600,
+            "calculations": [
+                {"op": "COUNT"},
+                {"op": "AVG", "column": "duration_ms"},
+                {"op": "P99", "column": "duration_ms"},
+            ],
+            "filters": [{"column": "status_code", "op": ">=", "value": 500}],
+            "orders": [{"column": "COUNT", "order": "descending"}],
+            "limit": 100,
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_run_query",
+        description=get_description("honeycomb_run_query"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def get_tools() -> list[dict[str, Any]]:
+    """Get all queries tool definitions."""
+    return [
+        generate_create_query_tool(),
+        generate_get_query_tool(),
+        generate_run_query_tool(),
+    ]