honeycomb-api 0.1.0__py3-none-any.whl

honeycomb/models/board_builder.py

@@ -0,0 +1,387 @@
+"""Board Builder - Fluent interface for creating boards with panels."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+from honeycomb.models.tags_mixin import TagsMixin
+
+if TYPE_CHECKING:
+    from honeycomb.models.query_builder import QueryBuilder
+    from honeycomb.models.slo_builder import SLOBuilder
+
+
+# =============================================================================
+# BoardBundle Data Structures
+# =============================================================================
+
+
+@dataclass
+class QueryBuilderPanel:
+    """Query panel from inline QueryBuilder (needs creation).
+
+    Attributes:
+        builder: QueryBuilder instance with .name() set
+        position: Optional (x, y, width, height) for manual layout
+        style: Display style (graph, table, combo)
+        visualization: Optional visualization settings dict
+        dataset_override: Optional dataset override
+    """
+
+    builder: QueryBuilder
+    position: tuple[int, int, int, int] | None
+    style: Literal["graph", "table", "combo"]
+    visualization: dict[str, Any] | None
+    dataset_override: str | None
+
+
+@dataclass
+class ExistingQueryPanel:
+    """Query panel from existing query ID.
+
+    Attributes:
+        query_id: ID of saved query
+        annotation_id: Annotation ID of query
+        position: Optional (x, y, width, height) for manual layout
+        style: Display style (graph, table, combo)
+        visualization: Optional visualization settings dict
+        dataset: Optional dataset name
+    """
+
+    query_id: str
+    annotation_id: str
+    position: tuple[int, int, int, int] | None
+    style: Literal["graph", "table", "combo"]
+    visualization: dict[str, Any] | None
+    dataset: str | None
+
+
+@dataclass
+class SLOBuilderPanel:
+    """SLO panel from inline SLOBuilder (needs creation).
+
+    Attributes:
+        builder: SLOBuilder instance
+        position: Optional (x, y, width, height) for manual layout
+    """
+
+    builder: SLOBuilder
+    position: tuple[int, int, int, int] | None
+
+
+@dataclass
+class ExistingSLOPanel:
+    """SLO panel from existing SLO ID.
+
+    Attributes:
+        slo_id: ID of the SLO
+        position: Optional (x, y, width, height) for manual layout
+    """
+
+    slo_id: str
+    position: tuple[int, int, int, int] | None
+
+
+@dataclass
+class TextPanel:
+    """Text panel.
+
+    Attributes:
+        content: Markdown text content
+        position: Optional (x, y, width, height) for manual layout
+    """
+
+    content: str
+    position: tuple[int, int, int, int] | None
+
+
+@dataclass
+class BoardBundle:
+    """Board creation bundle for orchestration.
+
+    Returned by BoardBuilder.build(), consumed by boards.create_from_bundle_async().
+
+    Attributes:
+        board_name: Board name
+        board_description: Optional board description
+        layout_generation: Layout mode (auto or manual)
+        tags: Optional tags list
+        preset_filters: Optional preset filters list
+        query_builder_panels: Panels from QueryBuilder instances
+        existing_query_panels: Panels from existing query IDs
+        slo_panels: SLO panels
+        text_panels: Text panels
+    """
+
+    board_name: str
+    board_description: str | None
+    layout_generation: Literal["auto", "manual"]
+    tags: list[dict[str, str]] | None
+    preset_filters: list[dict[str, str]] | None
+    # Panels (in order added)
+    query_builder_panels: list[QueryBuilderPanel]
+    existing_query_panels: list[ExistingQueryPanel]
+    slo_builder_panels: list[SLOBuilderPanel]
+    existing_slo_panels: list[ExistingSLOPanel]
+    text_panels: list[TextPanel]
+
+
+class BoardBuilder(TagsMixin):
+    """Fluent builder for boards with inline QueryBuilder or existing query IDs.
+
+    Example - Inline QueryBuilder with auto-layout:
+        board = await client.boards.create_from_bundle_async(
+            BoardBuilder("Service Dashboard")
+            .description("Overview of API health")
+            .auto_layout()
+            .query(
+                QueryBuilder("Request Count")
+                .dataset("api-logs")
+                .last_1_hour()
+                .count()
+            )
+            .slo("slo-id-1")
+            .text("## Notes\\nMonitor during peak hours")
+            .build()
+        )
+
+    Example - Manual layout with tuple positioning:
+        board = await client.boards.create_from_bundle_async(
+            BoardBuilder("Custom Layout")
+            .manual_layout()
+            .query(
+                QueryBuilder("Requests").dataset("api-logs").last_1_hour().count(),
+                position=(0, 0, 8, 6)
+            )
+            .slo("slo-id-1", position=(8, 0, 4, 6))
+            .build()
+        )
+    """
+
+    def __init__(self, name: str):
+        TagsMixin.__init__(self)
+        self._name = name
+        self._description: str | None = None
+        self._layout_generation: Literal["auto", "manual"] = "manual"
+        self._preset_filters: list[dict[str, str]] = []
+        # Panel storage (in order added)
+        self._query_builder_panels: list[QueryBuilderPanel] = []
+        self._existing_query_panels: list[ExistingQueryPanel] = []
+        self._slo_builder_panels: list[SLOBuilderPanel] = []
+        self._existing_slo_panels: list[ExistingSLOPanel] = []
+        self._text_panels: list[TextPanel] = []
+
+    def description(self, desc: str) -> BoardBuilder:
+        """Set board description (max 1024 chars).
+
+        Args:
+            desc: Description text
+        """
+        self._description = desc
+        return self
+
+    # -------------------------------------------------------------------------
+    # Layout configuration
+    # -------------------------------------------------------------------------
+
+    def auto_layout(self) -> BoardBuilder:
+        """Use automatic layout positioning.
+
+        Panels will be arranged automatically. Position can be omitted.
+        """
+        self._layout_generation = "auto"
+        return self
+
+    def manual_layout(self) -> BoardBuilder:
+        """Use manual layout positioning (default).
+
+        When using manual layout, you must specify position for all panels.
+        """
+        self._layout_generation = "manual"
+        return self
+
+    # -------------------------------------------------------------------------
+    # Preset filters
+    # -------------------------------------------------------------------------
+
+    def preset_filter(self, column: str, alias: str) -> BoardBuilder:
+        """Add a preset filter to the board.
+
+        Preset filters allow dynamic filtering of board data by specific columns.
+
+        Args:
+            column: Original column name to filter on
+            alias: Display name for the filter in the UI
+
+        Example:
+            .preset_filter("service_name", "Service")
+            .preset_filter("environment", "Environment")
+        """
+        self._preset_filters.append({"column": column, "alias": alias})
+        return self
+
+    # -------------------------------------------------------------------------
+    # Add panels
+    # -------------------------------------------------------------------------
+
+    def query(
+        self,
+        query: QueryBuilder | str,
+        annotation_id: str | None = None,
+        *,
+        position: tuple[int, int, int, int] | None = None,
+        style: Literal["graph", "table", "combo"] = "graph",
+        visualization: dict[str, Any] | None = None,
+        dataset: str | None = None,
+    ) -> BoardBuilder:
+        """Add a query panel.
+
+        Args:
+            query: QueryBuilder with .name() OR existing query_id string
+            annotation_id: Required only if query is string
+            position: (x, y, width, height) for manual layout
+            style: graph | table | combo
+            visualization: {"hide_markers": True, "utc_xaxis": True, ...}
+            dataset: Override QueryBuilder's dataset
+
+        Example - Inline QueryBuilder:
+            .query(
+                QueryBuilder("Request Count")
+                    .dataset("api-logs")
+                    .last_24_hours()
+                    .count()
+                    .group_by("service")
+                    .description("Requests by service over 24h"),
+                position=(0, 0, 9, 6),
+                style="graph",
+                visualization={"hide_markers": True, "utc_xaxis": True}
+            )
+
+        Example - Existing query:
+            .query("query-id-123", "annotation-id-456", style="table")
+        """
+        from honeycomb.models.query_builder import QueryBuilder
+
+        if isinstance(query, QueryBuilder):
+            if not query.has_name():
+                raise ValueError("QueryBuilder must have name in constructor for board panels")
+
+            self._query_builder_panels.append(
+                QueryBuilderPanel(
+                    builder=query,
+                    position=position,
+                    style=style,
+                    visualization=visualization,
+                    dataset_override=dataset,
+                )
+            )
+        else:
+            if not annotation_id:
+                raise ValueError("annotation_id required when using existing query ID")
+
+            self._existing_query_panels.append(
+                ExistingQueryPanel(
+                    query_id=query,
+                    annotation_id=annotation_id,
+                    position=position,
+                    style=style,
+                    visualization=visualization,
+                    dataset=dataset,
+                )
+            )
+        return self
+
+    def slo(
+        self,
+        slo: SLOBuilder | str,
+        *,
+        position: tuple[int, int, int, int] | None = None,
+    ) -> BoardBuilder:
+        """Add an SLO panel.
+
+        Args:
+            slo: SLOBuilder instance OR existing SLO ID string
+            position: (x, y, width, height) for manual layout
+
+        Example - Inline SLOBuilder:
+            .slo(
+                SLOBuilder("API Availability")
+                    .dataset("api-logs")
+                    .target_nines(3)
+                    .sli(alias="success_rate"),
+                position=(9, 0, 3, 6)
+            )
+
+        Example - Existing SLO:
+            .slo("slo-id-123", position=(8, 0, 4, 6))
+        """
+        from honeycomb.models.slo_builder import SLOBuilder
+
+        if isinstance(slo, SLOBuilder):
+            self._slo_builder_panels.append(SLOBuilderPanel(builder=slo, position=position))
+        else:
+            self._existing_slo_panels.append(ExistingSLOPanel(slo_id=slo, position=position))
+        return self
+
+    def text(
+        self,
+        content: str,
+        *,
+        position: tuple[int, int, int, int] | None = None,
+    ) -> BoardBuilder:
+        """Add a text panel (supports markdown, max 10000 chars).
+
+        Args:
+            content: Markdown text content
+            position: (x, y, width, height) for manual layout
+
+        Example:
+            .text("## Service Status\\n\\nAll systems operational", position=(0, 6, 12, 2))
+        """
+        if len(content) > 10000:
+            raise ValueError(f"Text content must be <= 10000 characters, got {len(content)}")
+        self._text_panels.append(TextPanel(content=content, position=position))
+        return self
+
+    # -------------------------------------------------------------------------
+    # Build
+    # -------------------------------------------------------------------------
+
+    def build(self) -> BoardBundle:
+        """Build BoardBundle for orchestration.
+
+        Returns:
+            BoardBundle (not BoardCreate) for client orchestration
+
+        Raises:
+            ValueError: If manual layout requires positions but some are missing
+        """
+        # Validate manual layout requires all positions
+        if self._layout_generation == "manual":
+            all_panels = (
+                self._query_builder_panels
+                + self._existing_query_panels
+                + self._slo_builder_panels
+                + self._existing_slo_panels
+                + self._text_panels
+            )
+            for i, panel in enumerate(all_panels):
+                if panel.position is None:
+                    raise ValueError(
+                        f"Manual layout requires position for all panels. "
+                        f"Panel {i} missing position. Use position=(x, y, width, height)"
+                    )
+
+        return BoardBundle(
+            board_name=self._name,
+            board_description=self._description,
+            layout_generation=self._layout_generation,
+            tags=self._get_all_tags(),
+            preset_filters=self._preset_filters if self._preset_filters else None,
+            query_builder_panels=self._query_builder_panels,
+            existing_query_panels=self._existing_query_panels,
+            slo_builder_panels=self._slo_builder_panels,
+            existing_slo_panels=self._existing_slo_panels,
+            text_panels=self._text_panels,
+        )

honeycomb/models/boards.py

@@ -0,0 +1,86 @@
+"""Pydantic models for Honeycomb Boards."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class BoardCreate(BaseModel):
+    """Model for creating a new board.
+
+    The Honeycomb Board API only supports flexible boards.
+
+    Attributes:
+        name: Human-readable name (1-255 chars)
+        description: Longer description (0-1024 chars)
+        type: Board type (only "flexible" is supported)
+        panels: Array of board panels (queries, SLOs, text)
+        layout_generation: Layout mode - "auto" or "manual" (default: "manual")
+        tags: Array of tag objects (max 10 items)
+        preset_filters: Array of preset filter objects
+    """
+
+    name: str = Field(description="Human-readable name for the board (1-255 chars)")
+    description: str | None = Field(default=None, description="Longer description (0-1024 chars)")
+    type: str = Field(
+        default="flexible",
+        description="Board type: only 'flexible' is supported",
+    )
+    panels: list[dict[str, Any]] | None = Field(
+        default=None,
+        description="Array of board panels (queries, SLOs, text)",
+    )
+    layout_generation: Literal["auto", "manual"] = Field(
+        default="manual",
+        description="Layout mode: 'auto' or 'manual'",
+    )
+    tags: list[dict[str, str]] | None = Field(
+        default=None,
+        description="Array of tag objects (max 10)",
+    )
+    preset_filters: list[dict[str, str]] | None = Field(
+        default=None,
+        description="Array of preset filter objects",
+    )
+
+    def model_dump_for_api(self) -> dict[str, Any]:
+        """Serialize for API request."""
+        data: dict[str, Any] = {
+            "name": self.name,
+            "type": self.type,
+            "layout_generation": self.layout_generation,
+        }
+
+        if self.description:
+            data["description"] = self.description
+
+        if self.panels:
+            data["panels"] = self.panels
+
+        if self.tags:
+            data["tags"] = self.tags
+
+        if self.preset_filters:
+            data["preset_filters"] = self.preset_filters
+
+        return data
+
+
+class Board(BaseModel):
+    """A Honeycomb board (response model)."""
+
+    id: str = Field(description="Unique identifier")
+    name: str = Field(description="Human-readable name")
+    description: str | None = Field(default=None, description="Longer description")
+    type: str = Field(default="flexible", description="Board type")
+    panels: list[dict] | None = Field(default=None, description="Board panels")
+    links: dict | None = Field(default=None, description="Board links")
+    layout_generation: str | None = Field(
+        default=None,
+        description="Layout mode: 'auto' or 'manual'",
+    )
+    tags: list[dict] | None = Field(default=None, description="Board tags")
+
+    model_config = {"extra": "allow"}

honeycomb/models/burn_alerts.py

@@ -0,0 +1,124 @@
+"""Pydantic models for Honeycomb Burn Alerts."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class BurnAlertType(str, Enum):
+    """Burn alert types."""
+
+    EXHAUSTION_TIME = "exhaustion_time"
+    BUDGET_RATE = "budget_rate"
+
+
+class BurnAlertRecipient(BaseModel):
+    """A recipient for burn alert notifications.
+
+    Either id (recommended) OR type+target (deprecated) must be provided.
+    """
+
+    id: str | None = Field(default=None, description="ID of the recipient")
+    type: str | None = Field(default=None, description="Type of recipient (email, slack, etc)")
+    target: str | None = Field(default=None, description="Target address (for backwards compat)")
+    details: dict[str, Any] | None = Field(default=None, description="Additional details")
+
+
+class BurnAlertCreate(BaseModel):
+    """Model for creating a new burn alert."""
+
+    alert_type: BurnAlertType = Field(description="Type of burn alert")
+    slo_id: str = Field(description="ID of the SLO to monitor")
+    description: str | None = Field(default=None, description="Description of the burn alert")
+    recipients: list[BurnAlertRecipient] = Field(
+        default_factory=list,
+        description="List of recipients to notify when alert fires",
+    )
+
+    # Exhaustion time fields (required when alert_type=exhaustion_time)
+    exhaustion_minutes: int | None = Field(
+        default=None,
+        description="Minutes until SLO budget exhaustion (for exhaustion_time alerts)",
+    )
+
+    # Budget rate fields (required when alert_type=budget_rate)
+    budget_rate_window_minutes: int | None = Field(
+        default=None, description="Time window in minutes (for budget_rate alerts)"
+    )
+    budget_rate_decrease_threshold_per_million: int | None = Field(
+        default=None,
+        description="Budget decrease threshold per million (for budget_rate alerts)",
+    )
+
+    def model_dump_for_api(self) -> dict[str, Any]:
+        """Serialize for API request."""
+        # Build recipient list - support both id-based and inline (type+target) formats
+        recipients_data = []
+        for r in self.recipients:
+            recipient_dict: dict[str, Any] = {}
+            if r.id:
+                # ID-based recipient (recommended)
+                recipient_dict["id"] = r.id
+                if r.type:
+                    recipient_dict["type"] = r.type
+            else:
+                # Inline recipient (deprecated but still supported)
+                if r.type:
+                    recipient_dict["type"] = r.type
+                if r.target:
+                    recipient_dict["target"] = r.target
+                if r.details:
+                    recipient_dict["details"] = r.details
+            recipients_data.append(recipient_dict)
+
+        data: dict[str, Any] = {
+            "alert_type": self.alert_type.value,
+            "slo": {"id": self.slo_id},
+            "recipients": recipients_data,
+        }
+
+        if self.description:
+            data["description"] = self.description
+
+        if self.alert_type == BurnAlertType.EXHAUSTION_TIME and self.exhaustion_minutes:
+            data["exhaustion_minutes"] = self.exhaustion_minutes
+        elif self.alert_type == BurnAlertType.BUDGET_RATE:
+            if self.budget_rate_window_minutes:
+                data["budget_rate_window_minutes"] = self.budget_rate_window_minutes
+            if self.budget_rate_decrease_threshold_per_million:
+                data["budget_rate_decrease_threshold_per_million"] = (
+                    self.budget_rate_decrease_threshold_per_million
+                )
+
+        return data
+
+
+class BurnAlert(BaseModel):
+    """A Honeycomb burn alert (response model)."""
+
+    id: str = Field(description="Unique identifier")
+    alert_type: BurnAlertType = Field(description="Type of burn alert")
+    slo_id: str | None = Field(default=None, description="ID of the associated SLO")
+    description: str | None = Field(default=None, description="Description of the burn alert")
+    triggered: bool = Field(default=False, description="Whether alert is currently triggered")
+
+    # Exhaustion time fields
+    exhaustion_minutes: int | None = Field(default=None, description="Minutes until exhaustion")
+
+    # Budget rate fields
+    budget_rate_window_minutes: int | None = Field(default=None, description="Time window")
+    budget_rate_decrease_threshold_per_million: int | None = Field(
+        default=None, description="Budget decrease threshold"
+    )
+
+    recipients: list[dict] | None = Field(default=None, description="List of recipients")
+    slo: dict | None = Field(default=None, description="SLO details")
+
+    created_at: datetime | None = Field(default=None, description="Creation timestamp")
+    updated_at: datetime | None = Field(default=None, description="Last update timestamp")
+
+    model_config = {"extra": "allow"}

honeycomb/models/columns.py

@@ -0,0 +1,59 @@
+"""Pydantic models for Honeycomb Columns."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class ColumnType(str, Enum):
+    """Column data types."""
+
+    STRING = "string"
+    INTEGER = "integer"
+    FLOAT = "float"
+    BOOLEAN = "boolean"
+
+
+class ColumnCreate(BaseModel):
+    """Model for creating a new column."""
+
+    key_name: str = Field(description="Name of the column")
+    type: ColumnType = Field(
+        default=ColumnType.STRING, description="Type of data the column contains"
+    )
+    description: str | None = Field(default=None, description="Column description")
+    hidden: bool = Field(
+        default=False,
+        description="If true, column is excluded from autocomplete and raw data field lists",
+    )
+
+    def model_dump_for_api(self) -> dict:
+        """Serialize for API request."""
+        data = {
+            "key_name": self.key_name,
+            "type": self.type.value,
+            "hidden": self.hidden,
+        }
+        if self.description:
+            data["description"] = self.description
+        return data
+
+
+class Column(BaseModel):
+    """A Honeycomb column (response model)."""
+
+    id: str = Field(description="Unique identifier")
+    key_name: str = Field(description="Name of the column")
+    type: ColumnType = Field(description="Type of data the column contains")
+    description: str | None = Field(default=None, description="Column description")
+    hidden: bool = Field(default=False, description="Whether column is hidden")
+    last_written: datetime | None = Field(
+        default=None, description="Timestamp when column was last written to"
+    )
+    created_at: datetime | None = Field(default=None, description="Creation timestamp")
+    updated_at: datetime | None = Field(default=None, description="Last update timestamp")
+
+    model_config = {"extra": "allow"}