pgbeam 0.2.7__tar.gz → 0.2.8__tar.gz

{pgbeam-0.2.7 → pgbeam-0.2.8}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @pgbeam/python-sdk
 
+## 0.2.8
+
+### Patch Changes
+
+- a9c235e: feat(api): anomaly rules, the authoring surface (roadmap item 4, slice 3)
+
 ## 0.2.7
 
 ### Patch Changes

{pgbeam-0.2.7 → pgbeam-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pgbeam
-Version: 0.2.7
+Version: 0.2.8
 Summary: Python SDK for the PgBeam API, a Postgres proxy for safe AI agent access with policy enforcement in the wire protocol
 Project-URL: Homepage, https://pgbeam.com
 Project-URL: Documentation, https://pgbeam.com/docs/python-sdk

{pgbeam-0.2.7 → pgbeam-0.2.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pgbeam"
-version = "0.2.7"
+version = "0.2.8"
 description = "Python SDK for the PgBeam API, a Postgres proxy for safe AI agent access with policy enforcement in the wire protocol"
 readme = "README.md"
 license = "Apache-2.0"

{pgbeam-0.2.7 → pgbeam-0.2.8}/src/pgbeam/models.py

@@ -36,6 +36,9 @@ __all__ = [
     "AgentUsageMarginalRates",
     "AgentUsageReport",
     "AnomalyAlert",
+    "AnomalyMetric",
+    "AnomalyRule",
+    "AnomalyRuleInput",
     "ApprovalDecisionRequest",
     "ApprovalRequest",
     "AssignableOrgRole",
@@ -99,6 +102,7 @@ __all__ = [
     "LatencySummary",
     "ListAgentCredentialsResponse",
     "ListAnomalyAlertsResponse",
+    "ListAnomalyRulesResponse",
     "ListApprovalRequestsResponse",
     "ListAuditLogsResponse",
     "ListCacheRulesResponse",
@@ -517,6 +521,48 @@ class AnomalyAlert(TypedDict):
     acknowledged_by: NotRequired[str | None]
 
 
+# One of the five detection metrics. A rule retunes how sensitive one of them is; it adds no detection algorithm and no alert kind.
+AnomalyMetric = Literal[
+    "queries_per_hour", "bytes_per_hour", "distinct_shapes", "errors_per_hour", "active_hours"
+]
+
+
+class AnomalyRule(TypedDict):
+    """Per-project (and optionally per-credential) sensitivity for one detection metric. Without a rule every metric resolves to the deployment default, so a noisy credential cannot be loosened, a sensitive one cannot be tightened, and off-hours cannot be silenced for a credential that legitimately runs at 3am."""
+
+    # Unique anomaly rule identifier.
+    id: str
+    # Project the rule belongs to.
+    project_id: str
+    # Agent credential the rule applies to. Null applies it to every credential in the project.
+    credential_id: NotRequired[str | None]
+    metric: AnomalyMetric
+    # N in the "mean + N * dispersion" spike rule. Null leaves the deployment default in place.
+    sigma_threshold: NotRequired[float | None]
+    # Absolute floor below which the metric never alerts. Null leaves the deployment default in place. Only queries_per_hour, bytes_per_hour and errors_per_hour have a floor.
+    floor: NotRequired[float | None]
+    # False silences this metric for this scope. Note the polarity is the opposite of honeytokens.enabled: the rule IS the switch, so disabling it disables the metric rather than deactivating the rule.
+    enabled: bool
+    # When the rule was created.
+    created_at: str
+    # When the rule was last updated.
+    updated_at: str
+
+
+class AnomalyRuleInput(TypedDict):
+    """Request body for creating or updating an anomaly rule. One rule exists per (project, credential, metric); creating a second for the same scope is a conflict."""
+
+    # Agent credential to scope the rule to. Null or omitted applies it to every credential in the project. The credential must belong to this project.
+    credential_id: NotRequired[str | None]
+    metric: AnomalyMetric
+    # N in the "mean + N * dispersion" spike rule. Must be greater than zero; the detector reads any value at or below zero as "use the default", so a stored zero could never mean what setting it would suggest. Rejected for distinct_shapes and active_hours, which have no rate for sigma to put a threshold on. Null or omitted leaves the deployment default in place.
+    sigma_threshold: NotRequired[float | None]
+    # Absolute floor below which the metric never alerts. Must be greater than zero, for the same reason as sigma_threshold. Rejected for distinct_shapes and active_hours, which have no rate for a floor to bound. Null or omitted leaves the deployment default in place.
+    floor: NotRequired[float | None]
+    # False silences this metric for this scope. The baseline keeps advancing while it is silenced, so re-enabling resumes from the existing history rather than a cold warm-up.
+    enabled: NotRequired[bool]
+
+
 class ApprovalDecisionRequest(TypedDict):
     """Optional note attached to an approve/reject decision."""
 
@@ -1497,6 +1543,15 @@ class ListAnomalyAlertsResponse(TypedDict):
     next_page_token: NotRequired[str]
 
 
+class ListAnomalyRulesResponse(TypedDict):
+    """Cursor-paginated anomaly rules for a project."""
+
+    # Anomaly rules on the current page.
+    anomaly_rules: list[AnomalyRule]
+    # Opaque token for cursor-based pagination.
+    next_page_token: NotRequired[str]
+
+
 class ListApprovalRequestsResponse(TypedDict):
     """Cursor-paginated list of approval requests for a project."""
 

{pgbeam-0.2.7 → pgbeam-0.2.8}/src/pgbeam/operations.py

@@ -161,6 +161,17 @@ OPERATIONS_BY_TAG: dict[str, dict[str, OperationMeta]] = {
         "update_anomaly_alert": OperationMeta(
             "PATCH", "/v1/projects/{project_id}/anomalies/{anomaly_id}"
         ),
+        "list_anomaly_rules": OperationMeta("GET", "/v1/projects/{project_id}/anomaly-rules"),
+        "create_anomaly_rule": OperationMeta("POST", "/v1/projects/{project_id}/anomaly-rules"),
+        "get_anomaly_rule": OperationMeta(
+            "GET", "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}"
+        ),
+        "update_anomaly_rule": OperationMeta(
+            "PUT", "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}"
+        ),
+        "delete_anomaly_rule": OperationMeta(
+            "DELETE", "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}"
+        ),
     },
     "branches": {
         "list_database_branches": OperationMeta("GET", "/v1/projects/{project_id}/branches"),
@@ -283,6 +294,21 @@ OPERATIONS_BY_PATH: dict[str, OperationMeta] = {
     "PATCH /v1/projects/{project_id}/anomalies/{anomaly_id}": OperationMeta(
         "PATCH", "/v1/projects/{project_id}/anomalies/{anomaly_id}"
     ),
+    "GET /v1/projects/{project_id}/anomaly-rules": OperationMeta(
+        "GET", "/v1/projects/{project_id}/anomaly-rules"
+    ),
+    "POST /v1/projects/{project_id}/anomaly-rules": OperationMeta(
+        "POST", "/v1/projects/{project_id}/anomaly-rules"
+    ),
+    "GET /v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}": OperationMeta(
+        "GET", "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}"
+    ),
+    "PUT /v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}": OperationMeta(
+        "PUT", "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}"
+    ),
+    "DELETE /v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}": OperationMeta(
+        "DELETE", "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}"
+    ),
     "GET /v1/projects/{project_id}/approvals": OperationMeta(
         "GET", "/v1/projects/{project_id}/approvals"
     ),

{pgbeam-0.2.7 → pgbeam-0.2.8}/src/pgbeam/services.py

@@ -19,6 +19,8 @@ from .models import (
     AgentCredentialSecrets,
     AgentUsageReport,
     AnomalyAlert,
+    AnomalyRule,
+    AnomalyRuleInput,
     ApprovalDecisionRequest,
     ApprovalRequest,
     AuditChainVerification,
@@ -54,6 +56,7 @@ from .models import (
     HoneytokenInput,
     ListAgentCredentialsResponse,
     ListAnomalyAlertsResponse,
+    ListAnomalyRulesResponse,
     ListApprovalRequestsResponse,
     ListAuditLogsResponse,
     ListCacheRulesResponse,
@@ -2065,6 +2068,150 @@ class AnomaliesService:
             ),
         )
 
+    def list_anomaly_rules(
+        self,
+        project_id: str,
+        *,
+        page_size: int | None = None,
+        page_token: str | None = None,
+    ) -> ListAnomalyRulesResponse:
+        """List anomaly rules.
+
+        Lists the project's anomaly rules, including silenced ones.
+
+        ``GET /v1/projects/{project_id}/anomaly-rules``
+
+        Args:
+            project_id: Unique project identifier (prefixed, e.g. prj_xxx).
+            page_size: Maximum number of items to return (1-100, default 20).
+            page_token: Opaque token for cursor-based pagination.
+        """
+        return cast(
+            ListAnomalyRulesResponse,
+            self._transport.request(
+                "GET",
+                "/v1/projects/{project_id}/anomaly-rules",
+                path_params={
+                    "project_id": project_id,
+                },
+                query={
+                    "page_size": page_size,
+                    "page_token": page_token,
+                },
+            ),
+        )
+
+    def create_anomaly_rule(
+        self,
+        project_id: str,
+        *,
+        body: AnomalyRuleInput,
+    ) -> AnomalyRule:
+        """Create an anomaly rule.
+
+        Retunes one detection metric for this project, or for one agent credential in it. Without a rule every metric resolves to the deployment default. A rule adds no detection algorithm and no alert kind: it changes how sensitive one of the five existing metrics is. enabled=false silences that metric for that scope; the baseline keeps advancing, so re-enabling resumes from the existing history rather than a cold warm-up.
+
+        ``POST /v1/projects/{project_id}/anomaly-rules``
+
+        Args:
+            project_id: Unique project identifier (prefixed, e.g. prj_xxx).
+            body: The request body.
+        """
+        return cast(
+            AnomalyRule,
+            self._transport.request(
+                "POST",
+                "/v1/projects/{project_id}/anomaly-rules",
+                path_params={
+                    "project_id": project_id,
+                },
+                body=body,
+            ),
+        )
+
+    def get_anomaly_rule(
+        self,
+        project_id: str,
+        anomaly_rule_id: str,
+    ) -> AnomalyRule:
+        """Get an anomaly rule.
+
+        Returns a single anomaly rule by ID.
+
+        ``GET /v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}``
+
+        Args:
+            project_id: Unique project identifier (prefixed, e.g. prj_xxx).
+            anomaly_rule_id: Unique anomaly rule identifier (prefixed, e.g. anr_xxx).
+        """
+        return cast(
+            AnomalyRule,
+            self._transport.request(
+                "GET",
+                "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}",
+                path_params={
+                    "project_id": project_id,
+                    "anomaly_rule_id": anomaly_rule_id,
+                },
+            ),
+        )
+
+    def update_anomaly_rule(
+        self,
+        project_id: str,
+        anomaly_rule_id: str,
+        *,
+        body: AnomalyRuleInput,
+    ) -> AnomalyRule:
+        """Update an anomaly rule.
+
+        Replaces the rule's scope, metric and sensitivity. A rule whose enabled flag is turned off silences its metric for its scope rather than being deactivated.
+
+        ``PUT /v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}``
+
+        Args:
+            project_id: Unique project identifier (prefixed, e.g. prj_xxx).
+            anomaly_rule_id: Unique anomaly rule identifier (prefixed, e.g. anr_xxx).
+            body: The request body.
+        """
+        return cast(
+            AnomalyRule,
+            self._transport.request(
+                "PUT",
+                "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}",
+                path_params={
+                    "project_id": project_id,
+                    "anomaly_rule_id": anomaly_rule_id,
+                },
+                body=body,
+            ),
+        )
+
+    def delete_anomaly_rule(
+        self,
+        project_id: str,
+        anomaly_rule_id: str,
+    ) -> None:
+        """Delete an anomaly rule.
+
+        Removes the rule, so its metric returns to the deployment default for that scope. Deleting a rule that was silencing a metric turns that metric's alerts back on.
+
+        ``DELETE /v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}``
+
+        Args:
+            project_id: Unique project identifier (prefixed, e.g. prj_xxx).
+            anomaly_rule_id: Unique anomaly rule identifier (prefixed, e.g. anr_xxx).
+        """
+        self._transport.request(
+            "DELETE",
+            "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}",
+            path_params={
+                "project_id": project_id,
+                "anomaly_rule_id": anomaly_rule_id,
+            },
+        )
+        return None
+
 
 class BranchesService:
     """The Branches operations, blocking. Reached as ``client.branches``."""
@@ -5092,6 +5239,150 @@ class AsyncAnomaliesService:
             ),
         )
 
+    async def list_anomaly_rules(
+        self,
+        project_id: str,
+        *,
+        page_size: int | None = None,
+        page_token: str | None = None,
+    ) -> ListAnomalyRulesResponse:
+        """List anomaly rules.
+
+        Lists the project's anomaly rules, including silenced ones.
+
+        ``GET /v1/projects/{project_id}/anomaly-rules``
+
+        Args:
+            project_id: Unique project identifier (prefixed, e.g. prj_xxx).
+            page_size: Maximum number of items to return (1-100, default 20).
+            page_token: Opaque token for cursor-based pagination.
+        """
+        return cast(
+            ListAnomalyRulesResponse,
+            await self._transport.request(
+                "GET",
+                "/v1/projects/{project_id}/anomaly-rules",
+                path_params={
+                    "project_id": project_id,
+                },
+                query={
+                    "page_size": page_size,
+                    "page_token": page_token,
+                },
+            ),
+        )
+
+    async def create_anomaly_rule(
+        self,
+        project_id: str,
+        *,
+        body: AnomalyRuleInput,
+    ) -> AnomalyRule:
+        """Create an anomaly rule.
+
+        Retunes one detection metric for this project, or for one agent credential in it. Without a rule every metric resolves to the deployment default. A rule adds no detection algorithm and no alert kind: it changes how sensitive one of the five existing metrics is. enabled=false silences that metric for that scope; the baseline keeps advancing, so re-enabling resumes from the existing history rather than a cold warm-up.
+
+        ``POST /v1/projects/{project_id}/anomaly-rules``
+
+        Args:
+            project_id: Unique project identifier (prefixed, e.g. prj_xxx).
+            body: The request body.
+        """
+        return cast(
+            AnomalyRule,
+            await self._transport.request(
+                "POST",
+                "/v1/projects/{project_id}/anomaly-rules",
+                path_params={
+                    "project_id": project_id,
+                },
+                body=body,
+            ),
+        )
+
+    async def get_anomaly_rule(
+        self,
+        project_id: str,
+        anomaly_rule_id: str,
+    ) -> AnomalyRule:
+        """Get an anomaly rule.
+
+        Returns a single anomaly rule by ID.
+
+        ``GET /v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}``
+
+        Args:
+            project_id: Unique project identifier (prefixed, e.g. prj_xxx).
+            anomaly_rule_id: Unique anomaly rule identifier (prefixed, e.g. anr_xxx).
+        """
+        return cast(
+            AnomalyRule,
+            await self._transport.request(
+                "GET",
+                "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}",
+                path_params={
+                    "project_id": project_id,
+                    "anomaly_rule_id": anomaly_rule_id,
+                },
+            ),
+        )
+
+    async def update_anomaly_rule(
+        self,
+        project_id: str,
+        anomaly_rule_id: str,
+        *,
+        body: AnomalyRuleInput,
+    ) -> AnomalyRule:
+        """Update an anomaly rule.
+
+        Replaces the rule's scope, metric and sensitivity. A rule whose enabled flag is turned off silences its metric for its scope rather than being deactivated.
+
+        ``PUT /v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}``
+
+        Args:
+            project_id: Unique project identifier (prefixed, e.g. prj_xxx).
+            anomaly_rule_id: Unique anomaly rule identifier (prefixed, e.g. anr_xxx).
+            body: The request body.
+        """
+        return cast(
+            AnomalyRule,
+            await self._transport.request(
+                "PUT",
+                "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}",
+                path_params={
+                    "project_id": project_id,
+                    "anomaly_rule_id": anomaly_rule_id,
+                },
+                body=body,
+            ),
+        )
+
+    async def delete_anomaly_rule(
+        self,
+        project_id: str,
+        anomaly_rule_id: str,
+    ) -> None:
+        """Delete an anomaly rule.
+
+        Removes the rule, so its metric returns to the deployment default for that scope. Deleting a rule that was silencing a metric turns that metric's alerts back on.
+
+        ``DELETE /v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}``
+
+        Args:
+            project_id: Unique project identifier (prefixed, e.g. prj_xxx).
+            anomaly_rule_id: Unique anomaly rule identifier (prefixed, e.g. anr_xxx).
+        """
+        await self._transport.request(
+            "DELETE",
+            "/v1/projects/{project_id}/anomaly-rules/{anomaly_rule_id}",
+            path_params={
+                "project_id": project_id,
+                "anomaly_rule_id": anomaly_rule_id,
+            },
+        )
+        return None
+
 
 class AsyncBranchesService:
     """The Branches operations, awaitable. Reached as ``client.branches``."""