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

honeycomb/tools/resources/columns.py

@@ -0,0 +1,257 @@
+"""Columns tool definitions for Claude API.
+
+This module provides tool generators and descriptions for
+columns resources.
+"""
+
+from typing import Any
+
+from honeycomb.models import ColumnCreate
+from honeycomb.tools.schemas import add_parameter, generate_schema_from_model
+
+# ==============================================================================
+# Columns Descriptions
+# ==============================================================================
+
+COLUMN_DESCRIPTIONS = {
+    "honeycomb_list_columns": (
+        "Lists all columns defined in a dataset's schema. "
+        "Use this to discover available fields for querying, understand your data structure, or validate that new columns are being sent correctly. "
+        "Requires the dataset slug parameter. "
+        "Returns a list of column objects including their IDs, key names, types (string, integer, float, boolean), descriptions, hidden status, and timestamps."
+    ),
+    "honeycomb_get_column": (
+        "Retrieves detailed information about a specific column by its ID. "
+        "Use this to inspect a column's configuration including its data type, visibility, description, and usage statistics. "
+        "Requires both the dataset slug and column ID parameters. "
+        "Returns the complete column configuration including creation timestamp, last update timestamp, and last written timestamp."
+    ),
+    "honeycomb_create_column": (
+        "Creates a new column in a dataset's schema. "
+        "Use this to pre-define columns before sending data, add metadata like descriptions, or create hidden columns for internal fields. "
+        "Requires the dataset slug and key_name (the column identifier). "
+        "Optional parameters include type (string, integer, float, boolean - defaults to string), description for documentation, and hidden flag to exclude from autocomplete. "
+        "Columns are automatically created when new fields appear in events, but pre-defining them allows you to set type and visibility."
+    ),
+    "honeycomb_update_column": (
+        "Updates an existing column's description, type, or visibility settings. "
+        "Use this to add documentation to columns, change data types, or hide internal debugging fields from query builders. "
+        "Requires the dataset slug, column ID, and the complete updated column configuration. "
+        "Note: Changing the type doesn't convert existing data, it only affects how the column is displayed and queried in the UI."
+    ),
+    "honeycomb_delete_column": (
+        "Permanently deletes a column from a dataset's schema. "
+        "Use this when cleaning up unused columns or removing fields that are no longer being sent. "
+        "Requires both the dataset slug and column ID parameters. "
+        "Warning: This action cannot be undone. The column definition will be removed, but existing event data containing this field is preserved."
+    ),
+}
+
+
+def get_description(tool_name: str) -> str:
+    """Get the description for a tool in this resource."""
+    return COLUMN_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
+
+
+# ==============================================================================
+# Columns Tool Definitions
+# ==============================================================================
+
+
+def generate_list_columns_tool() -> dict[str, Any]:
+    """Generate honeycomb_list_columns tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset"]}
+
+    add_parameter(
+        schema, "dataset", "string", "The dataset slug to list columns from", required=True
+    )
+
+    examples: list[dict[str, Any]] = [
+        {"dataset": "api-logs"},
+        {"dataset": "production"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_list_columns",
+        description=get_description("honeycomb_list_columns"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_get_column_tool() -> dict[str, Any]:
+    """Generate honeycomb_get_column tool definition."""
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "column_id"],
+    }
+
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "column_id", "string", "The column ID to retrieve", required=True)
+
+    examples: list[dict[str, Any]] = [
+        {"dataset": "api-logs", "column_id": "col-123"},
+        {"dataset": "production", "column_id": "col-456"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_get_column",
+        description=get_description("honeycomb_get_column"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_create_column_tool() -> dict[str, Any]:
+    """Generate honeycomb_create_column tool definition."""
+    base_schema = generate_schema_from_model(
+        ColumnCreate,
+        exclude_fields={"id", "created_at", "updated_at", "last_written"},
+    )
+
+    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]] = [
+        # Minimal example (string column)
+        {"dataset": "api-logs", "key_name": "endpoint", "type": "string"},
+        # With description and type
+        {
+            "dataset": "api-logs",
+            "key_name": "duration_ms",
+            "type": "float",
+            "description": "Request duration in milliseconds",
+        },
+        # Hidden column
+        {
+            "dataset": "production",
+            "key_name": "internal_id",
+            "type": "integer",
+            "hidden": True,
+            "description": "Internal debugging ID",
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_create_column",
+        description=get_description("honeycomb_create_column"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_update_column_tool() -> dict[str, Any]:
+    """Generate honeycomb_update_column tool definition."""
+    base_schema = generate_schema_from_model(
+        ColumnCreate,
+        exclude_fields={"id", "created_at", "updated_at", "last_written"},
+    )
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "column_id"],
+    }
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "column_id", "string", "The column ID to update", 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]] = [
+        {
+            "dataset": "api-logs",
+            "column_id": "col-123",
+            "key_name": "endpoint",
+            "type": "string",
+            "description": "API endpoint path",
+        },
+        {
+            "dataset": "production",
+            "column_id": "col-456",
+            "key_name": "status_code",
+            "type": "integer",
+            "hidden": False,
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_update_column",
+        description=get_description("honeycomb_update_column"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_delete_column_tool() -> dict[str, Any]:
+    """Generate honeycomb_delete_column tool definition."""
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "column_id"],
+    }
+
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "column_id", "string", "The column ID to delete", required=True)
+
+    examples: list[dict[str, Any]] = [
+        {"dataset": "api-logs", "column_id": "col-123"},
+        {"dataset": "production", "column_id": "col-456"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_delete_column",
+        description=get_description("honeycomb_delete_column"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def get_tools() -> list[dict[str, Any]]:
+    """Get all columns tool definitions."""
+    return [
+        generate_list_columns_tool(),
+        generate_get_column_tool(),
+        generate_create_column_tool(),
+        generate_update_column_tool(),
+        generate_delete_column_tool(),
+    ]

honeycomb/tools/resources/datasets.py

@@ -0,0 +1,215 @@
+"""Datasets tool definitions for Claude API.
+
+This module provides tool generators and descriptions for
+datasets resources.
+"""
+
+from typing import Any
+
+from honeycomb.models import DatasetCreate, DatasetUpdate
+from honeycomb.tools.schemas import add_parameter, generate_schema_from_model
+
+# ==============================================================================
+# Datasets Descriptions
+# ==============================================================================
+
+DATASET_DESCRIPTIONS = {
+    "honeycomb_list_datasets": (
+        "Lists all datasets in your Honeycomb environment (no parameters required). "
+        "Use this to discover existing datasets before creating new ones, when setting up observability for a new service, or when migrating data from another platform. "
+        "This operation requires no parameters - it automatically lists all datasets you have access to. "
+        "Returns a list of dataset objects including their slugs, names, descriptions, and metadata like creation timestamps and column counts."
+    ),
+    "honeycomb_get_dataset": (
+        "Retrieves detailed information about a specific dataset by its slug. "
+        "Use this to inspect a dataset's configuration including its name, description, JSON expansion settings, and usage statistics. "
+        "Requires the dataset slug parameter. "
+        "Returns the complete dataset configuration including creation timestamp, last written timestamp, and regular columns count."
+    ),
+    "honeycomb_create_dataset": (
+        "Creates a new dataset to store telemetry data in Honeycomb. "
+        "Use this when setting up observability for a new service, creating test environments, or segmenting data by application or team. "
+        "Requires a name parameter which will be converted to a URL-safe slug. "
+        "Optional parameters include description for documentation and expand_json_depth (0-10) to automatically expand nested JSON fields into separate columns. "
+        "The dataset slug will be automatically generated from the name and used for API operations."
+    ),
+    "honeycomb_update_dataset": (
+        "Updates an existing dataset's name, description, JSON expansion settings, or delete protection. "
+        "Use this to correct dataset metadata, add documentation, adjust JSON parsing behavior, or toggle delete protection. "
+        "Requires the dataset slug. All other fields are optional - only provided fields will be updated. "
+        "Set delete_protected=true to prevent accidental deletion, or delete_protected=false to allow deletion. "
+        "Note: The slug itself cannot be changed. Changing expand_json_depth only affects new events, not existing data."
+    ),
+    "honeycomb_delete_dataset": (
+        "Permanently deletes a dataset and all its data from Honeycomb. "
+        "Use this when decommissioning services, cleaning up test datasets, or consolidating data storage. "
+        "Requires the dataset slug parameter. "
+        "Warning: This action cannot be undone. All events, columns, queries, triggers, and SLOs in this dataset will be permanently deleted. "
+        "Note: Datasets with delete protection enabled cannot be deleted. Use honeycomb_update_dataset to disable delete_protected first."
+    ),
+}
+
+
+def get_description(tool_name: str) -> str:
+    """Get the description for a tool in this resource."""
+    return DATASET_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
+
+
+# ==============================================================================
+# Datasets Tool Definitions
+# ==============================================================================
+
+
+def generate_list_datasets_tool() -> dict[str, Any]:
+    """Generate honeycomb_list_datasets tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": []}
+
+    examples: list[dict[str, Any]] = [
+        {},  # List all datasets
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_list_datasets",
+        description=get_description("honeycomb_list_datasets"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_get_dataset_tool() -> dict[str, Any]:
+    """Generate honeycomb_get_dataset tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["slug"]}
+
+    add_parameter(schema, "slug", "string", "The dataset slug to retrieve", required=True)
+
+    examples: list[dict[str, Any]] = [
+        {"slug": "api-logs"},
+        {"slug": "production"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_get_dataset",
+        description=get_description("honeycomb_get_dataset"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_create_dataset_tool() -> dict[str, Any]:
+    """Generate honeycomb_create_dataset tool definition."""
+    # Start with DatasetCreate schema
+    base_schema = generate_schema_from_model(
+        DatasetCreate,
+        exclude_fields={"created_at", "last_written_at", "slug", "regular_columns_count"},
+    )
+
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": []}
+    schema["properties"].update(base_schema["properties"])
+    schema["required"].extend(base_schema.get("required", []))
+
+    examples: list[dict[str, Any]] = [
+        # Minimal example
+        {"name": "api-logs"},
+        # With description
+        {
+            "name": "production-logs",
+            "description": "Production API logs from main services",
+        },
+        # With JSON expansion
+        {
+            "name": "trace-data",
+            "description": "Distributed traces with nested JSON",
+            "expand_json_depth": 3,
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_create_dataset",
+        description=get_description("honeycomb_create_dataset"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_update_dataset_tool() -> dict[str, Any]:
+    """Generate honeycomb_update_dataset tool definition."""
+    # Use DatasetUpdate which supports partial updates and delete_protected
+    base_schema = generate_schema_from_model(DatasetUpdate)
+
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["slug"]}
+    add_parameter(schema, "slug", "string", "The dataset slug to update", required=True)
+
+    # Add properties from DatasetUpdate (all optional)
+    schema["properties"].update(base_schema["properties"])
+    # Don't extend required - DatasetUpdate fields are all optional
+
+    examples: list[dict[str, Any]] = [
+        {"slug": "api-logs", "name": "API Logs", "description": "Updated description"},
+        {"slug": "production", "expand_json_depth": 5},
+        {"slug": "critical-data", "delete_protected": True},
+        {"slug": "test-dataset", "delete_protected": False},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_update_dataset",
+        description=get_description("honeycomb_update_dataset"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_delete_dataset_tool() -> dict[str, Any]:
+    """Generate honeycomb_delete_dataset tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["slug"]}
+
+    add_parameter(schema, "slug", "string", "The dataset slug to delete", required=True)
+
+    examples: list[dict[str, Any]] = [
+        {"slug": "test-dataset"},
+        {"slug": "old-logs"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_delete_dataset",
+        description=get_description("honeycomb_delete_dataset"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def get_tools() -> list[dict[str, Any]]:
+    """Get all datasets tool definitions."""
+    return [
+        generate_list_datasets_tool(),
+        generate_get_dataset_tool(),
+        generate_create_dataset_tool(),
+        generate_update_dataset_tool(),
+        generate_delete_dataset_tool(),
+    ]