adloop 0.1.0__py3-none-any.whl

adloop/ga4/tracking.py

@@ -0,0 +1,36 @@
+"""GA4 tracking/event tools — list custom events and their volume."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import AdLoopConfig
+
+
+def get_tracking_events(
+    config: AdLoopConfig,
+    *,
+    property_id: str = "",
+    date_range_start: str = "28daysAgo",
+    date_range_end: str = "today",
+) -> dict:
+    """List all GA4 events and their event count for the given date range."""
+    from adloop.ga4.reports import run_ga4_report
+
+    result = run_ga4_report(
+        config,
+        property_id=property_id,
+        dimensions=["eventName"],
+        metrics=["eventCount"],
+        date_range_start=date_range_start,
+        date_range_end=date_range_end,
+        limit=500,
+    )
+
+    if "rows" in result:
+        result["rows"].sort(
+            key=lambda r: int(r.get("eventCount", "0")), reverse=True
+        )
+
+    return result

adloop/safety/audit.py

@@ -0,0 +1,40 @@
+"""Mutation audit logging — every write operation is logged locally."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def log_mutation(
+    log_file: str,
+    *,
+    operation: str,
+    customer_id: str = "",
+    entity_type: str = "",
+    entity_id: str = "",
+    changes: dict[str, Any] | None = None,
+    dry_run: bool = True,
+    result: str = "success",
+    error: str = "",
+) -> None:
+    """Append a mutation record to the audit log file."""
+    path = Path(log_file).expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    record = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "operation": operation,
+        "customer_id": customer_id,
+        "entity_type": entity_type,
+        "entity_id": entity_id,
+        "changes": changes or {},
+        "dry_run": dry_run,
+        "result": result,
+        "error": error,
+    }
+
+    with open(path, "a") as f:
+        f.write(json.dumps(record) + "\n")

adloop/safety/guards.py

@@ -0,0 +1,56 @@
+"""Safety guards — budget caps, bid limits, and blocked operation enforcement."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from adloop.config import SafetyConfig
+
+
+class SafetyViolation(Exception):
+    """Raised when a proposed change violates safety constraints."""
+
+
+def check_budget_cap(daily_budget: float, config: SafetyConfig) -> None:
+    """Reject if proposed daily budget exceeds configured maximum."""
+    if daily_budget > config.max_daily_budget:
+        raise SafetyViolation(
+            f"Daily budget {daily_budget:.2f} exceeds maximum {config.max_daily_budget:.2f}"
+        )
+
+
+def check_bid_increase(current_bid: float, proposed_bid: float, config: SafetyConfig) -> None:
+    """Reject if bid increase percentage exceeds configured maximum."""
+    if current_bid <= 0:
+        return
+    increase_pct = ((proposed_bid - current_bid) / current_bid) * 100
+    if increase_pct > config.max_bid_increase_pct:
+        raise SafetyViolation(
+            f"Bid increase {increase_pct:.0f}% exceeds maximum {config.max_bid_increase_pct}%"
+        )
+
+
+def check_blocked_operation(operation: str, config: SafetyConfig) -> None:
+    """Reject if operation is in the blocked list."""
+    if operation in config.blocked_operations:
+        raise SafetyViolation(f"Operation '{operation}' is blocked by configuration")
+
+
+def requires_double_confirmation(operation: str, **kwargs: object) -> bool:
+    """Return True if this operation is destructive enough to need double confirmation.
+
+    Triggers on:
+    - Any delete or remove operation
+    - Budget increases >50%
+    """
+    if "delete" in operation or "remove" in operation:
+        return True
+
+    current = kwargs.get("current_budget")
+    proposed = kwargs.get("proposed_budget")
+    if isinstance(current, (int, float)) and isinstance(proposed, (int, float)) and current > 0:
+        if ((proposed - current) / current) > 0.5:
+            return True
+
+    return False

adloop/safety/preview.py

@@ -0,0 +1,58 @@
+"""Change preview formatting — structured output for proposed mutations."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass
+class ChangePlan:
+    """A proposed change that must be confirmed before execution."""
+
+    plan_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+    operation: str = ""
+    entity_type: str = ""
+    entity_id: str = ""
+    customer_id: str = ""
+    changes: dict[str, Any] = field(default_factory=dict)
+    created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    requires_double_confirm: bool = False
+    dry_run_result: dict[str, Any] | None = None
+
+    def to_preview(self) -> dict[str, Any]:
+        """Format as a human-readable preview dict for the AI to present."""
+        return {
+            "plan_id": self.plan_id,
+            "operation": self.operation,
+            "entity_type": self.entity_type,
+            "entity_id": self.entity_id,
+            "customer_id": self.customer_id,
+            "changes": self.changes,
+            "requires_double_confirm": self.requires_double_confirm,
+            "status": "PENDING_CONFIRMATION",
+            "instructions": (
+                "Review the changes above. To apply, call confirm_and_apply "
+                f"with plan_id='{self.plan_id}' and dry_run=false."
+            ),
+        }
+
+
+_pending_plans: dict[str, ChangePlan] = {}
+
+
+def store_plan(plan: ChangePlan) -> None:
+    """Store a plan for later retrieval by confirm_and_apply."""
+    _pending_plans[plan.plan_id] = plan
+
+
+def get_plan(plan_id: str) -> ChangePlan | None:
+    """Retrieve a stored plan by ID."""
+    return _pending_plans.get(plan_id)
+
+
+def remove_plan(plan_id: str) -> None:
+    """Remove a plan after execution."""
+    _pending_plans.pop(plan_id, None)