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

honeycomb/models/queries.py

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING, Any
 from pydantic import BaseModel, Field, field_validator
 
 from honeycomb.models.query_builder import (
+    VALID_COMPARE_OFFSETS,
     Calculation,
     Filter,
     FilterCombination,
@@ -91,6 +92,15 @@ class QuerySpec(BaseModel):
     havings: list[Having | dict[str, Any]] | None = Field(
         default=None, description="Having clauses"
     )
+    calculated_fields: list[dict[str, str]] | None = Field(
+        default=None,
+        description="Inline calculated fields (derived columns) for this query",
+    )
+    compare_time_offset_seconds: int | None = Field(
+        default=None,
+        description="Compare against historical data offset by N seconds "
+        "(1800, 3600, 7200, 28800, 86400, 604800, 2419200, 15724800)",
+    )
 
     @field_validator("limit")
     @classmethod
@@ -104,6 +114,17 @@ class QuerySpec(BaseModel):
             )
         return v
 
+    @field_validator("compare_time_offset_seconds")
+    @classmethod
+    def validate_compare_time_offset(cls, v: int | None) -> int | None:
+        """Validate that compare_time_offset_seconds is a valid offset value."""
+        if v is not None and v not in VALID_COMPARE_OFFSETS:
+            raise ValueError(
+                f"Invalid compare_time_offset_seconds: {v}. "
+                f"Must be one of: {sorted(VALID_COMPARE_OFFSETS)}"
+            )
+        return v
+
     @classmethod
     def builder(cls) -> QueryBuilder:
         """Create a QueryBuilder for fluent query construction.

honeycomb/models/query_builder.py

@@ -11,12 +11,18 @@ from __future__ import annotations
 from enum import Enum
 from typing import TYPE_CHECKING, Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field
 
 if TYPE_CHECKING:
     from honeycomb.models.queries import QuerySpec
     from honeycomb.models.triggers import TriggerQuery
 
+# Valid time offset values for compare queries (in seconds)
+# 30min, 1hr, 2hr, 8hr, 24hr, 7d, 28d, 6mo
+VALID_COMPARE_OFFSETS: frozenset[int] = frozenset(
+    {1800, 3600, 7200, 28800, 86400, 604800, 2419200, 15724800}
+)
+
 
 # =============================================================================
 # Enums
@@ -51,7 +57,7 @@ class CalcOp(str, Enum):
 
 
 class FilterOp(str, Enum):
-    """Filter operations for Honeycomb queries."""
+    """Filter operations for Honeycomb queries and board views."""
 
     EQUALS = "="
     NOT_EQUALS = "!="
@@ -61,6 +67,8 @@ class FilterOp(str, Enum):
     LESS_THAN_OR_EQUAL = "<="
     STARTS_WITH = "starts-with"
     DOES_NOT_START_WITH = "does-not-start-with"
+    ENDS_WITH = "ends-with"
+    DOES_NOT_END_WITH = "does-not-end-with"
     CONTAINS = "contains"
     DOES_NOT_CONTAIN = "does-not-contain"
     EXISTS = "exists"
@@ -94,21 +102,19 @@ class Calculation(BaseModel):
     Examples:
         >>> Calculation(op=CalcOp.COUNT)
         >>> Calculation(op=CalcOp.P99, column="duration_ms")
-        >>> Calculation(op="AVG", column="response_time", alias="avg_response")
+        >>> Calculation(op="AVG", column="response_time")
     """
 
-    op: CalcOp | str = Field(description="Calculation operation (COUNT, AVG, P99, etc.)")
+    model_config = ConfigDict(extra="forbid")
+
+    op: CalcOp = Field(description="Calculation operation (COUNT, AVG, P99, etc.)")
     column: str | None = Field(default=None, description="Column to calculate on")
-    alias: str | None = Field(default=None, description="Alias for the result column")
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to API dict format."""
-        op_value = self.op.value if isinstance(self.op, CalcOp) else self.op
-        result: dict[str, Any] = {"op": op_value}
+        result: dict[str, Any] = {"op": self.op.value}
         if self.column is not None:
             result["column"] = self.column
-        if self.alias is not None:
-            result["alias"] = self.alias
         return result
 
 
@@ -121,14 +127,15 @@ class Filter(BaseModel):
         >>> Filter(column="service", op="in", value=["api", "web"])
     """
 
+    model_config = ConfigDict(extra="forbid")
+
     column: str = Field(description="Column to filter on")
-    op: FilterOp | str = Field(description="Filter operator (=, !=, >, <, contains, etc.)")
+    op: FilterOp = Field(description="Filter operator (=, !=, >, <, contains, etc.)")
     value: Any = Field(description="Filter value")
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to API dict format."""
-        op_value = self.op.value if isinstance(self.op, FilterOp) else self.op
-        return {"column": self.column, "op": op_value, "value": self.value}
+        return {"column": self.column, "op": self.op.value, "value": self.value}
 
 
 class Order(BaseModel):
@@ -139,17 +146,15 @@ class Order(BaseModel):
         >>> Order(op=CalcOp.AVG, column="duration_ms", order=OrderDirection.ASCENDING)
     """
 
-    op: CalcOp | str = Field(description="Calculation to order by")
+    model_config = ConfigDict(extra="forbid")
+
+    op: CalcOp = Field(description="Calculation to order by")
     column: str | None = Field(default=None, description="Column for the calculation")
-    order: OrderDirection | str = Field(
-        default=OrderDirection.DESCENDING, description="Sort direction"
-    )
+    order: OrderDirection = Field(default=OrderDirection.DESCENDING, description="Sort direction")
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to API dict format."""
-        op_value = self.op.value if isinstance(self.op, CalcOp) else self.op
-        order_value = self.order.value if isinstance(self.order, OrderDirection) else self.order
-        result: dict[str, Any] = {"op": op_value, "order": order_value}
+        result: dict[str, Any] = {"op": self.op.value, "order": self.order.value}
         if self.column is not None:
             result["column"] = self.column
         return result
@@ -163,20 +168,18 @@ class Having(BaseModel):
         >>> Having(calculate_op=CalcOp.AVG, column="duration_ms", op=">", value=500.0)
     """
 
-    calculate_op: CalcOp | str = Field(description="Calculation to filter on")
+    model_config = ConfigDict(extra="forbid")
+
+    calculate_op: CalcOp = Field(description="Calculation to filter on")
     column: str | None = Field(default=None, description="Column for the calculation")
-    op: FilterOp | str = Field(description="Comparison operator")
+    op: FilterOp = Field(description="Comparison operator")
     value: float = Field(description="Threshold value")
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to API dict format."""
-        calc_op_value = (
-            self.calculate_op.value if isinstance(self.calculate_op, CalcOp) else self.calculate_op
-        )
-        op_value = self.op.value if isinstance(self.op, FilterOp) else self.op
         result: dict[str, Any] = {
-            "calculate_op": calc_op_value,
-            "op": op_value,
+            "calculate_op": self.calculate_op.value,
+            "op": self.op.value,
             "value": self.value,
         }
         if self.column is not None:
@@ -243,6 +246,8 @@ class QueryBuilder:
         self._orders: list[Order] = []
         self._limit: int | None = None
         self._havings: list[Having] = []
+        self._calculated_fields: list[dict[str, str]] = []
+        self._compare_time_offset_seconds: int | None = None
         # Query metadata (for board integration)
         self._dataset: str | None = None
         self._query_name: str | None = name
@@ -381,69 +386,66 @@ class QueryBuilder:
     # Calculation Methods (additive - each call adds to the list)
     # -------------------------------------------------------------------------
 
-    def calculate(
-        self, op: CalcOp | str, column: str | None = None, alias: str | None = None
-    ) -> QueryBuilder:
+    def calculate(self, op: CalcOp | str, column: str | None = None) -> QueryBuilder:
         """Add a calculation to the query.
 
         Args:
             op: Calculation operation (e.g., CalcOp.COUNT, "AVG")
             column: Column to calculate on (optional for COUNT)
-            alias: Alias for the result column
 
         Returns:
             self for chaining
         """
-        self._calculations.append(Calculation(op=op, column=column, alias=alias))
+        self._calculations.append(Calculation(op=op, column=column))
         return self
 
-    def count(self, alias: str | None = None) -> QueryBuilder:
+    def count(self) -> QueryBuilder:
         """Add a COUNT calculation."""
-        return self.calculate(CalcOp.COUNT, alias=alias)
+        return self.calculate(CalcOp.COUNT)
 
-    def sum(self, column: str, alias: str | None = None) -> QueryBuilder:
+    def sum(self, column: str) -> QueryBuilder:
         """Add a SUM calculation on a column."""
-        return self.calculate(CalcOp.SUM, column=column, alias=alias)
+        return self.calculate(CalcOp.SUM, column=column)
 
-    def avg(self, column: str, alias: str | None = None) -> QueryBuilder:
+    def avg(self, column: str) -> QueryBuilder:
         """Add an AVG calculation on a column."""
-        return self.calculate(CalcOp.AVG, column=column, alias=alias)
+        return self.calculate(CalcOp.AVG, column=column)
 
-    def min(self, column: str, alias: str | None = None) -> QueryBuilder:
+    def min(self, column: str) -> QueryBuilder:
         """Add a MIN calculation on a column."""
-        return self.calculate(CalcOp.MIN, column=column, alias=alias)
+        return self.calculate(CalcOp.MIN, column=column)
 
-    def max(self, column: str, alias: str | None = None) -> QueryBuilder:
+    def max(self, column: str) -> QueryBuilder:
         """Add a MAX calculation on a column."""
-        return self.calculate(CalcOp.MAX, column=column, alias=alias)
+        return self.calculate(CalcOp.MAX, column=column)
 
-    def count_distinct(self, column: str, alias: str | None = None) -> QueryBuilder:
+    def count_distinct(self, column: str) -> QueryBuilder:
         """Add a COUNT_DISTINCT calculation on a column."""
-        return self.calculate(CalcOp.COUNT_DISTINCT, column=column, alias=alias)
+        return self.calculate(CalcOp.COUNT_DISTINCT, column=column)
 
-    def p50(self, column: str, alias: str | None = None) -> QueryBuilder:
+    def p50(self, column: str) -> QueryBuilder:
         """Add a P50 (median) calculation on a column."""
-        return self.calculate(CalcOp.P50, column=column, alias=alias)
+        return self.calculate(CalcOp.P50, column=column)
 
-    def p90(self, column: str, alias: str | None = None) -> QueryBuilder:
+    def p90(self, column: str) -> QueryBuilder:
         """Add a P90 calculation on a column."""
-        return self.calculate(CalcOp.P90, column=column, alias=alias)
+        return self.calculate(CalcOp.P90, column=column)
 
-    def p95(self, column: str, alias: str | None = None) -> QueryBuilder:
+    def p95(self, column: str) -> QueryBuilder:
         """Add a P95 calculation on a column."""
-        return self.calculate(CalcOp.P95, column=column, alias=alias)
+        return self.calculate(CalcOp.P95, column=column)
 
-    def p99(self, column: str, alias: str | None = None) -> QueryBuilder:
+    def p99(self, column: str) -> QueryBuilder:
         """Add a P99 calculation on a column."""
-        return self.calculate(CalcOp.P99, column=column, alias=alias)
+        return self.calculate(CalcOp.P99, column=column)
 
-    def heatmap(self, column: str, alias: str | None = None) -> QueryBuilder:
+    def heatmap(self, column: str) -> QueryBuilder:
         """Add a HEATMAP calculation on a column."""
-        return self.calculate(CalcOp.HEATMAP, column=column, alias=alias)
+        return self.calculate(CalcOp.HEATMAP, column=column)
 
-    def concurrency(self, alias: str | None = None) -> QueryBuilder:
+    def concurrency(self) -> QueryBuilder:
         """Add a CONCURRENCY calculation."""
-        return self.calculate(CalcOp.CONCURRENCY, alias=alias)
+        return self.calculate(CalcOp.CONCURRENCY)
 
     # -------------------------------------------------------------------------
     # Filter Methods
@@ -568,10 +570,10 @@ class QueryBuilder:
         Returns:
             self for chaining
         """
-        if isinstance(combination, str):
-            self._filter_combination = FilterCombination(combination)
-        else:
+        if isinstance(combination, FilterCombination):
             self._filter_combination = combination
+        else:
+            self._filter_combination = FilterCombination(combination)
         return self
 
     # -------------------------------------------------------------------------
@@ -678,6 +680,62 @@ class QueryBuilder:
         self._havings.append(Having(calculate_op=calculate_op, column=column, op=op, value=value))
         return self
 
+    # -------------------------------------------------------------------------
+    # Calculated Fields (Inline Derived Columns)
+    # -------------------------------------------------------------------------
+
+    def calculated_field(self, name: str, expression: str) -> QueryBuilder:
+        """Add an inline calculated field (derived column) for this query only.
+
+        Creates a computed column available within this query. For reusable
+        derived columns, use the Derived Columns API instead.
+
+        Args:
+            name: Field name/alias to reference in calculations and breakdowns
+            expression: Formula using $column_name syntax
+                       See https://docs.honeycomb.io/reference/derived-column-formula/
+
+        Returns:
+            self for chaining
+
+        Example:
+            >>> (QueryBuilder()
+            ...     .calculated_field("latency_bucket",
+            ...         "IF(LTE($duration_ms, 100), 'fast', 'slow')")
+            ...     .group_by("latency_bucket")
+            ...     .count())
+        """
+        self._calculated_fields.append({"name": name, "expression": expression})
+        return self
+
+    # -------------------------------------------------------------------------
+    # Compare Time Offset (Historical Comparison)
+    # -------------------------------------------------------------------------
+
+    def compare_time_offset(self, seconds: int) -> QueryBuilder:
+        """Compare against historical data offset by N seconds.
+
+        When set, the query results will include comparison data from
+        the specified time in the past.
+
+        Args:
+            seconds: Offset in seconds. Must be one of:
+                     1800 (30min), 3600 (1hr), 7200 (2hr), 28800 (8hr),
+                     86400 (24hr), 604800 (7d), 2419200 (28d), 15724800 (6mo)
+
+        Returns:
+            self for chaining
+
+        Example:
+            >>> QueryBuilder().last_1_hour().count().compare_time_offset(86400)  # Compare to 24h ago
+        """
+        if seconds not in VALID_COMPARE_OFFSETS:
+            raise ValueError(
+                f"Invalid compare_time_offset: {seconds}. Must be one of: {sorted(VALID_COMPARE_OFFSETS)}"
+            )
+        self._compare_time_offset_seconds = seconds
+        return self
+
     # -------------------------------------------------------------------------
     # Dataset Scoping
     # -------------------------------------------------------------------------
@@ -803,6 +861,8 @@ class QueryBuilder:
             orders=self._orders if self._orders else None,
             limit=self._limit,
             havings=self._havings if self._havings else None,
+            calculated_fields=self._calculated_fields if self._calculated_fields else None,
+            compare_time_offset_seconds=self._compare_time_offset_seconds,
         )
 
     def build_for_trigger(self) -> TriggerQuery:

honeycomb/models/recipient_builder.py

@@ -78,13 +78,22 @@ class RecipientMixin:
         )
         return self
 
-    def webhook(self, url: str, name: str = "Webhook", secret: str | None = None) -> Self:
+    def webhook(
+        self,
+        url: str,
+        name: str = "Webhook",
+        secret: str | None = None,
+        headers: list[dict[str, str]] | None = None,
+    ) -> Self:
         """Add a webhook recipient (inline format for triggers/burn alerts).
 
         Args:
             url: Webhook URL to POST to.
             name: A name for this webhook (default: "Webhook").
             secret: Optional webhook secret for signing.
+            headers: Optional HTTP headers (max 5). Each dict should have
+                    'header' (required) and optionally 'value'.
+                    Example: [{"header": "Authorization", "value": "Bearer xyz"}]
 
         Returns:
             Self for method chaining.
@@ -99,6 +108,8 @@ class RecipientMixin:
         }
         if secret:
             details["webhook_secret"] = secret
+        if headers:
+            details["webhook_headers"] = headers
 
         self._new_recipients.append(
             {
@@ -209,16 +220,43 @@ class RecipientBuilder:
         url: str,
         name: str = "Webhook",
         secret: str | None = None,
+        headers: list[dict[str, str]] | None = None,
+        payload_templates: dict[str, dict[str, str]] | None = None,
+        template_variables: list[dict[str, str]] | None = None,
     ) -> RecipientCreate:
         """Create a webhook recipient.
 
         Args:
-            url: Webhook URL to POST to.
-            name: A name for this webhook.
-            secret: Optional webhook secret for signing.
+            url: Webhook URL to POST to (max 2048 chars).
+            name: A name for this webhook (max 255 chars).
+            secret: Optional webhook secret for signing (max 255 chars).
+            headers: Optional HTTP headers (max 5). Each dict should have
+                    'header' (required, max 64 chars) and optionally 'value' (max 750 chars).
+                    Example: [{"header": "Authorization", "value": "Bearer xyz"}]
+            payload_templates: Optional custom payload templates for different alert types.
+                    Example: {"trigger": {"body": "{\"custom\": \"json\"}"}}
+            template_variables: Optional template variables for payload substitution (max 10).
+                    Example: [{"name": "severity", "default_value": "warning"}]
 
         Returns:
             RecipientCreate object.
+
+        Example:
+            >>> # Basic webhook
+            >>> RecipientBuilder.webhook("https://example.com/webhook")
+
+            >>> # Webhook with auth header
+            >>> RecipientBuilder.webhook(
+            ...     "https://example.com/webhook",
+            ...     headers=[{"header": "Authorization", "value": "Bearer token123"}]
+            ... )
+
+            >>> # Advanced webhook with custom payload
+            >>> RecipientBuilder.webhook(
+            ...     "https://example.com/webhook",
+            ...     template_variables=[{"name": "env", "default_value": "prod"}],
+            ...     payload_templates={"trigger": {"body": "{\"environment\": \"{{env}}\"}"}}
+            ... )
         """
         details: dict[str, Any] = {
             "webhook_url": url,
@@ -226,6 +264,15 @@ class RecipientBuilder:
         }
         if secret:
             details["webhook_secret"] = secret
+        if headers:
+            details["webhook_headers"] = headers
+        if template_variables or payload_templates:
+            webhook_payloads: dict[str, Any] = {}
+            if template_variables:
+                webhook_payloads["template_variables"] = template_variables
+            if payload_templates:
+                webhook_payloads["payload_templates"] = payload_templates
+            details["webhook_payloads"] = webhook_payloads
         return RecipientCreate(type=RecipientType.WEBHOOK, details=details)
 
     @staticmethod

honeycomb/models/slo_builder.py

@@ -195,7 +195,7 @@ class SLOBuilder:
         slo = (
             SLOBuilder("Cross-Service Availability")
             .datasets(["api-logs", "web-logs", "worker-logs"])
-            .target_nines(3)  # 99.9%
+            .target_percentage(99.9)
             .sli(
                 alias="service_success",
                 expression="IF(EQUALS($status, 200), 1, 0)",
@@ -219,6 +219,7 @@ class SLOBuilder:
         self._time_period_days: int = 30
         self._sli: SLIDefinition | None = None
         self._burn_alerts: list[BurnAlertDefinition] = []
+        self._tags: list[dict[str, str]] = []
 
     # -------------------------------------------------------------------------
     # Basic configuration
@@ -229,6 +230,25 @@ class SLOBuilder:
         self._description = desc
         return self
 
+    def tag(self, key: str, value: str) -> SLOBuilder:
+        """Add a tag key-value pair for organizing the SLO.
+
+        Tags are useful for filtering and grouping SLOs by team, service,
+        criticality, or other dimensions.
+
+        Args:
+            key: Tag key (lowercase letters, max 32 chars)
+            value: Tag value (alphanumeric, /, -, max 128 chars)
+
+        Example:
+            >>> builder.tag("team", "platform").tag("service", "api")
+
+        Returns:
+            self for chaining
+        """
+        self._tags.append({"key": key, "value": value})
+        return self
+
     # -------------------------------------------------------------------------
     # Dataset scope
     # -------------------------------------------------------------------------
@@ -267,20 +287,6 @@ class SLOBuilder:
         self._target_per_million = int(percent * 10000)
         return self
 
-    def target_nines(self, nines: int) -> SLOBuilder:
-        """Set target by number of nines.
-
-        Examples:
-            2 nines = 99%
-            3 nines = 99.9%
-            4 nines = 99.99%
-
-        Args:
-            nines: Number of nines (1-5)
-        """
-        percentage = 100 - (100 / (10**nines))
-        return self.target_percentage(percentage)
-
     def target_per_million(self, value: int) -> SLOBuilder:
         """Set target directly as per-million value.
 
@@ -422,10 +428,7 @@ class SLOBuilder:
             raise ValueError("At least one dataset is required. Use dataset() or datasets().")
 
         if self._target_per_million is None:
-            raise ValueError(
-                "Target is required. Use target_percentage(), "
-                "target_nines(), or target_per_million()."
-            )
+            raise ValueError("Target is required. Use target_percentage() or target_per_million().")
 
         if self._sli is None:
             raise ValueError("SLI is required. Use sli(alias=...) to define it.")
@@ -452,6 +455,8 @@ class SLOBuilder:
             sli=SLI(alias=self._sli.alias),
             time_period_days=self._time_period_days,
             target_per_million=self._target_per_million,
+            tags=self._tags if self._tags else None,
+            dataset_slugs=self._datasets if is_multi_dataset else None,
         )
 
         return SLOBundle(

honeycomb/models/slos.py

@@ -7,11 +7,32 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
+from honeycomb.models.tool_inputs import TagInput
+
 
 class SLI(BaseModel):
-    """Service Level Indicator configuration."""
+    """Service Level Indicator configuration.
+
+    The SLI references a derived column by alias. You can either:
+    1. Reference an existing derived column: just provide alias
+    2. Create a new derived column inline: provide alias + expression
+
+    When expression is provided, a new derived column will be created automatically
+    before the SLO is created.
+    """
 
-    alias: str | None = Field(default=None, description="Alias for the SLI")
+    alias: str | None = Field(
+        default=None, description="Alias for the derived column (existing or new)"
+    )
+    expression: str | None = Field(
+        default=None,
+        description="If provided, creates a new derived column with this expression. "
+        "If omitted, uses an existing derived column with the given alias.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Description for the new derived column (only used when expression is provided)",
+    )
 
 
 class SLOCreate(BaseModel):
@@ -28,9 +49,17 @@ class SLOCreate(BaseModel):
     )
     target_per_million: int = Field(
         ge=0,
-        le=1000000,
+        le=999999,
         description="Target success rate per million (e.g., 999000 = 99.9%)",
     )
+    tags: list[TagInput] | None = Field(
+        default=None,
+        description="Key-value pairs for organizing SLOs (max 10 tags)",
+    )
+    dataset_slugs: list[str] | None = Field(
+        default=None,
+        description="Dataset slugs for multi-dataset SLOs (used with __all__ endpoint)",
+    )
 
     def model_dump_for_api(self) -> dict[str, Any]:
         """Serialize for API request."""
@@ -47,6 +76,12 @@ class SLOCreate(BaseModel):
         if self.sli.alias:
             data["sli"]["alias"] = self.sli.alias
 
+        if self.tags:
+            data["tags"] = [{"key": tag.key, "value": tag.value} for tag in self.tags]
+
+        if self.dataset_slugs:
+            data["dataset_slugs"] = self.dataset_slugs
+
         return data
 
 
@@ -64,3 +99,15 @@ class SLO(BaseModel):
     updated_at: datetime | None = Field(default=None, description="Last update timestamp")
 
     model_config = {"extra": "allow"}
+
+    @property
+    def dataset(self) -> str | None:
+        """Return the first dataset slug for convenience (SLOs can span multiple datasets)."""
+        if self.dataset_slugs and len(self.dataset_slugs) > 0:
+            return self.dataset_slugs[0]
+        return None
+
+    @property
+    def target_percentage(self) -> float:
+        """Convert target_per_million to percentage for display (e.g., 999000 → 99.9)."""
+        return self.target_per_million / 10000