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

honeycomb/tools/resources/triggers.py

@@ -0,0 +1,328 @@
+"""Triggers tool definitions for Claude API.
+
+This module provides tool generators and descriptions for
+triggers resources.
+"""
+
+from typing import Any
+
+from honeycomb.models import TriggerCreate
+from honeycomb.tools.schemas import add_parameter, generate_schema_from_model
+
+# ==============================================================================
+# Triggers Descriptions
+# ==============================================================================
+
+TRIGGER_DESCRIPTIONS = {
+    "honeycomb_list_triggers": (
+        "Lists all triggers (alerts) configured in a Honeycomb dataset. "
+        "Use this to discover existing alerting rules before creating new ones or when migrating from another observability platform. "
+        "Requires the dataset slug parameter to specify which dataset's triggers to retrieve. "
+        "Returns a list of trigger objects with their IDs, names, thresholds, and recipient configurations."
+    ),
+    "honeycomb_get_trigger": (
+        "Retrieves detailed configuration for a specific trigger by ID. "
+        "Use this to inspect an existing trigger's query specification, threshold settings, frequency, and recipients before modifying or replicating it. "
+        "Requires both the dataset slug and trigger ID parameters. "
+        "Returns the complete trigger configuration including the query spec, threshold operator and value, evaluation frequency, and notification recipients."
+    ),
+    "honeycomb_create_trigger": (
+        "Creates a new trigger (alert) that fires when query results cross a threshold. "
+        "Use this when setting up alerting rules for service health monitoring, error rates, latency thresholds, or when migrating Datadog monitors to Honeycomb. "
+        "Requires a dataset, query specification with calculations and filters, threshold operator and value, and evaluation frequency in seconds. "
+        "The query can be provided inline with calculations, filters, and time range. "
+        "IMPORTANT: Recipients can be provided inline using the 'recipients' array - each recipient needs 'type' (email/webhook/slack/pagerduty/msteams) and 'target' (email address/URL/channel). "
+        "Inline recipient creation is PREFERRED - create trigger and recipients in one call for efficiency. Alternatively, you can reference existing recipient IDs. "
+        "Note: Trigger queries have a maximum time_range of 3600 seconds (1 hour) and support only a single calculation."
+    ),
+    "honeycomb_update_trigger": (
+        "Updates an existing trigger's configuration including its query, threshold, frequency, or recipients. "
+        "Use this to adjust alerting thresholds, change notification targets, or update query filters as service behavior evolves. "
+        "Requires the dataset slug, trigger ID, and the complete updated trigger configuration. "
+        "Note: This replaces the entire trigger configuration, so include all fields you want to preserve."
+    ),
+    "honeycomb_delete_trigger": (
+        "Permanently deletes a trigger from Honeycomb. "
+        "Use this when decommissioning services, consolidating redundant alerts, or cleaning up test triggers. "
+        "Requires both the dataset slug and trigger ID. "
+        "Warning: This action cannot be undone. The trigger will stop firing immediately and historical alert data will be lost."
+    ),
+}
+
+
+def get_description(tool_name: str) -> str:
+    """Get the description for a tool in this resource."""
+    return TRIGGER_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
+
+
+# ==============================================================================
+# Triggers Tool Definitions
+# ==============================================================================
+
+
+def generate_list_triggers_tool() -> dict[str, Any]:
+    """Generate honeycomb_list_triggers tool definition."""
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset"]}
+
+    add_parameter(
+        schema,
+        "dataset",
+        "string",
+        "The dataset slug to list triggers from",
+        required=True,
+    )
+
+    examples = [
+        {"dataset": "api-logs"},
+        {"dataset": "production"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_list_triggers",
+        description=get_description("honeycomb_list_triggers"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_get_trigger_tool() -> dict[str, Any]:
+    """Generate honeycomb_get_trigger tool definition."""
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "trigger_id"],
+    }
+
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "trigger_id", "string", "The trigger ID to retrieve", required=True)
+
+    examples = [
+        {"dataset": "api-logs", "trigger_id": "aBcD123"},
+        {"dataset": "production", "trigger_id": "xyz789"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_get_trigger",
+        description=get_description("honeycomb_get_trigger"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_create_trigger_tool() -> dict[str, Any]:
+    """Generate honeycomb_create_trigger tool definition."""
+    # Start with TriggerCreate schema
+    base_schema = generate_schema_from_model(
+        TriggerCreate,
+        exclude_fields={"created_at", "updated_at", "id"},
+    )
+
+    # Add dataset parameter
+    schema: dict[str, Any] = {"type": "object", "properties": {}, "required": ["dataset"]}
+    add_parameter(
+        schema, "dataset", "string", "The dataset slug to create the trigger in", required=True
+    )
+
+    # Merge with TriggerCreate schema
+    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 = [
+        # Minimal example with COUNT
+        {
+            "dataset": "api-logs",
+            "name": "High Error Rate",
+            "query": {
+                "time_range": 900,
+                "calculations": [{"op": "COUNT"}],
+                "filters": [{"column": "status_code", "op": ">=", "value": 500}],
+            },
+            "threshold": {"op": ">", "value": 100},
+            "frequency": 900,
+        },
+        # P99 latency with recipients
+        {
+            "dataset": "production",
+            "name": "P99 Latency Alert",
+            "description": "Alerts when P99 latency exceeds 2 seconds",
+            "query": {
+                "time_range": 3600,
+                "calculations": [{"op": "P99", "column": "duration_ms"}],
+            },
+            "threshold": {"op": ">=", "value": 2000},
+            "frequency": 3600,
+            "recipients": [{"type": "email", "target": "oncall@example.com"}],
+            "alert_type": "on_change",
+        },
+        # Advanced: Multiple filters with string operations and tags
+        {
+            "dataset": "api-logs",
+            "name": "API Gateway Errors",
+            "description": "Monitors error rates for specific service with path filtering",
+            "query": {
+                "time_range": 1800,
+                "calculations": [{"op": "COUNT"}],
+                "filters": [
+                    {"column": "status_code", "op": ">=", "value": 500},
+                    {"column": "service_name", "op": "=", "value": "api-gateway"},
+                    {"column": "path", "op": "starts-with", "value": "/api/v2"},
+                ],
+                "filter_combination": "AND",
+                "breakdowns": ["endpoint"],
+            },
+            "threshold": {"op": ">", "value": 50, "exceeded_limit": 2},
+            "frequency": 900,
+            "recipients": [
+                {"type": "slack", "target": "#alerts"},
+                {
+                    "type": "pagerduty",
+                    "target": "routing-key-123",
+                    "details": {"severity": "critical"},
+                },
+            ],
+            "tags": [
+                {"key": "team", "value": "platform"},
+                {"key": "severity", "value": "high"},
+            ],
+        },
+        # HEATMAP calculation example
+        {
+            "dataset": "traces",
+            "name": "Request Duration Distribution",
+            "query": {
+                "time_range": 3600,
+                "calculations": [{"op": "HEATMAP", "column": "duration_ms"}],
+            },
+            "threshold": {"op": ">", "value": 1000},
+            "frequency": 3600,
+        },
+        # COUNT_DISTINCT example
+        {
+            "dataset": "api-logs",
+            "name": "Unique Error Messages",
+            "query": {
+                "time_range": 3600,
+                "calculations": [{"op": "COUNT_DISTINCT", "column": "error_message"}],
+                "filters": [{"column": "level", "op": "=", "value": "error"}],
+            },
+            "threshold": {"op": ">", "value": 10},
+            "frequency": 1800,
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_create_trigger",
+        description=get_description("honeycomb_create_trigger"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_update_trigger_tool() -> dict[str, Any]:
+    """Generate honeycomb_update_trigger tool definition."""
+    base_schema = generate_schema_from_model(
+        TriggerCreate,
+        exclude_fields={"created_at", "updated_at", "id"},
+    )
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "trigger_id"],
+    }
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "trigger_id", "string", "The trigger 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",
+            "trigger_id": "abc123",
+            "name": "Updated High Error Rate",
+            "query": {
+                "time_range": 900,
+                "calculations": [{"op": "COUNT"}],
+                "filters": [{"column": "status_code", "op": ">=", "value": 500}],
+            },
+            "threshold": {"op": ">", "value": 150},  # Updated threshold
+            "frequency": 900,
+        },
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_update_trigger",
+        description=get_description("honeycomb_update_trigger"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def generate_delete_trigger_tool() -> dict[str, Any]:
+    """Generate honeycomb_delete_trigger tool definition."""
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {},
+        "required": ["dataset", "trigger_id"],
+    }
+
+    add_parameter(schema, "dataset", "string", "The dataset slug", required=True)
+    add_parameter(schema, "trigger_id", "string", "The trigger ID to delete", required=True)
+
+    examples = [
+        {"dataset": "api-logs", "trigger_id": "abc123"},
+        {"dataset": "production", "trigger_id": "xyz789"},
+    ]
+
+    return create_tool_definition(
+        name="honeycomb_delete_trigger",
+        description=get_description("honeycomb_delete_trigger"),
+        input_schema=schema,
+        input_examples=examples,
+    )
+
+
+def get_tools() -> list[dict[str, Any]]:
+    """Get all triggers tool definitions."""
+    return [
+        generate_list_triggers_tool(),
+        generate_get_trigger_tool(),
+        generate_create_trigger_tool(),
+        generate_update_trigger_tool(),
+        generate_delete_trigger_tool(),
+    ]

honeycomb/tools/schemas.py

@@ -9,6 +9,87 @@ from typing import Any
 
 from pydantic import BaseModel
 
+# ==============================================================================
+# Metadata Field Schemas (for Claude reasoning - stripped before API execution)
+# ==============================================================================
+
+CONFIDENCE_SCHEMA: dict[str, Any] = {
+    "type": "string",
+    "enum": ["high", "medium", "low", "none"],
+    "description": (
+        "Claude's confidence level in this tool call. "
+        "'high' = certain this matches user intent and will succeed, "
+        "'medium' = likely correct but some uncertainty, "
+        "'low' = uncertain but best available option, "
+        "'none' = guessing or placeholder value."
+    ),
+}
+
+NOTES_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "description": (
+        "Structured reasoning notes explaining Claude's decision-making process. "
+        "All categories are optional arrays of single-sentence strings."
+    ),
+    "properties": {
+        "decisions": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Key decisions made (e.g., 'Chose COUNT over AVG for error rate')",
+        },
+        "concerns": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Potential issues or risks (e.g., 'Time range may be too short')",
+        },
+        "assumptions": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "Assumptions being made (e.g., 'Assuming status_code column exists')",
+        },
+        "questions": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": (
+                "Clarifying questions for increased confidence "
+                "(e.g., 'I would be more confident if I knew the expected error baseline')"
+            ),
+        },
+    },
+    "additionalProperties": False,
+}
+
+# Fields that are metadata for downstream applications, not sent to Honeycomb API
+METADATA_FIELDS: set[str] = {"confidence", "notes"}
+
+
+def add_metadata_fields(schema: dict[str, Any]) -> None:
+    """Add confidence and notes metadata fields to a tool schema.
+
+    These fields are for Claude's reasoning and are NOT sent to the Honeycomb API.
+    They are stripped by the executor before API calls.
+
+    Both fields are optional - they are not added to the required list.
+
+    Args:
+        schema: The tool input schema to modify (mutated in place)
+
+    Example:
+        >>> schema = {"type": "object", "properties": {}, "required": ["dataset"]}
+        >>> add_metadata_fields(schema)
+        >>> "confidence" in schema["properties"]
+        True
+        >>> "notes" in schema["properties"]
+        True
+        >>> "confidence" in schema.get("required", [])
+        False
+    """
+    import copy
+
+    schema["properties"]["confidence"] = copy.deepcopy(CONFIDENCE_SCHEMA)
+    schema["properties"]["notes"] = copy.deepcopy(NOTES_SCHEMA)
+    # Note: Both fields are OPTIONAL - not added to required list
+
 
 def validate_tool_name(name: str) -> None:
     """Validate tool name follows Claude's naming constraints.

{honeycomb_api-0.1.0.dist-info → honeycomb_api-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: honeycomb-api
-Version: 0.1.0
+Version: 0.5.3
 Summary: Python client for the Honeycomb.io API
 License-Expression: MIT
 License-File: LICENSE
@@ -20,6 +20,9 @@ Requires-Dist: httpx (>=0.27)
 Requires-Dist: pydantic (>=2.0)
 Requires-Dist: pytest-xdist (>=3.8.0,<4.0.0)
 Requires-Dist: python-dateutil (>=2.8)
+Requires-Dist: pyyaml (>=6.0)
+Requires-Dist: rich (>=13.0)
+Requires-Dist: typer (>=0.21.0)
 Project-URL: Homepage, https://github.com/irvingpop/honeycomb-api-python
 Project-URL: Repository, https://github.com/irvingpop/honeycomb-api-python
 Description-Content-Type: text/markdown
@@ -38,22 +41,22 @@ A modern, async-first Python client for the [Honeycomb.io](https://www.honeycomb
 
 - **Async-first design** with full sync support
 - **Fluent builder pattern** for queries, triggers, SLOs, and boards
+- **CLI tool** for porting objects between environments
+- **Claude tool definitions** exposing the full Honeycomb API for Claude-based agents
 - **Pydantic models** for type-safe request/response handling
 - **Automatic retries** with exponential backoff for transient failures
 - **Comprehensive error handling** with specific exception types
 - **Dual authentication** support (API keys and Management keys)
 - **Resource-oriented API** for intuitive usage
 
-## Installation (coming soon)
+## Installation
 
 ```bash
-pip install honeycomb-api-python
-```
-
-Or with Poetry:
+# Using Poetry
+poetry add honeycomb-api
 
-```bash
-poetry add honeycomb-api-python
+# Using uv
+uv add honeycomb-api
 ```
 
 ## Quick Start
@@ -227,6 +230,28 @@ client = HoneycombClient(
 
 Management credentials are sent via the `Authorization: Bearer` header.
 
+## CLI Tool
+
+For quick operations without writing Python:
+
+```bash
+# Run without installing (using uvx or pipx)
+export HONEYCOMB_API_KEY=your_api_key_here
+uvx honeycomb-api triggers list
+# or
+pipx run honeycomb-api triggers list
+
+# Or install and use the short alias
+uv tool install honeycomb-api
+# or
+pipx install honeycomb-api
+
+hny triggers list
+hny query run --dataset my-dataset --count --last-30-minutes
+```
+
+See the [CLI Reference](https://irvingpop.github.io/honeycomb-api-python/cli/) for full documentation.
+
 ## Usage Guide
 
 For complete usage examples and guides, see the [full documentation](https://irvingpop.github.io/honeycomb-api-python/):