ciris-agent 1.7.7__py3-none-any.whl

ciris_adapters/reddit/error_handler.py

@@ -0,0 +1,307 @@
+"""Reddit API error handling with retry logic and classification."""
+
+import asyncio
+import logging
+import random
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Any, Callable, Optional
+
+import httpx
+from pydantic import BaseModel
+
+logger = logging.getLogger(__name__)
+
+
+class ErrorSeverity(str, Enum):
+    """Error severity levels."""
+
+    LOW = "low"  # Minor issues, automatic recovery
+    MEDIUM = "medium"  # Temporary issues, retry possible
+    HIGH = "high"  # Serious issues, may need intervention
+    CRITICAL = "critical"  # Service-breaking issues
+
+
+class RedditErrorInfo(BaseModel):
+    """Structured information about a Reddit API error."""
+
+    severity: ErrorSeverity
+    message: str
+    can_retry: bool
+    error_type: str
+    retry_after: Optional[float] = None
+    operation: Optional[str] = None
+    endpoint: Optional[str] = None
+    suggested_action: Optional[str] = None
+
+
+class RedditErrorHandler:
+    """Error handler for Reddit API operations with exponential backoff."""
+
+    def __init__(self) -> None:
+        """Initialize error handler."""
+        self._error_counts: dict[str, int] = {}
+        self._last_errors: dict[str, datetime] = {}
+        self._error_threshold = 5  # Errors before escalation
+        self._error_window = timedelta(minutes=5)  # Time window for error counting
+
+    def classify_error(self, error: Exception, operation: str = "unknown") -> RedditErrorInfo:
+        """Classify an error and determine retry strategy.
+
+        Args:
+            error: The exception that occurred
+            operation: What operation was being performed
+
+        Returns:
+            Error classification with retry guidance
+        """
+        error_key = f"{operation}_{type(error).__name__}"
+        severity = ErrorSeverity.MEDIUM
+        can_retry = True
+        retry_after = None
+        suggested_action = None
+
+        # Network-level errors (transient, always retryable)
+        if isinstance(error, (httpx.ConnectTimeout, httpx.ReadTimeout, httpx.WriteTimeout)):
+            severity = ErrorSeverity.MEDIUM
+            can_retry = True
+            suggested_action = "exponential_backoff"
+            message = f"Network timeout during {operation}: {type(error).__name__}"
+
+        elif isinstance(error, httpx.ConnectError):
+            severity = ErrorSeverity.HIGH
+            can_retry = True
+            suggested_action = "exponential_backoff"
+            message = f"Connection error during {operation}: {str(error)}"
+
+        elif isinstance(error, httpx.NetworkError):
+            severity = ErrorSeverity.MEDIUM
+            can_retry = True
+            suggested_action = "exponential_backoff"
+            message = f"Network error during {operation}: {str(error)}"
+
+        # HTTP response errors
+        elif isinstance(error, httpx.HTTPStatusError):
+            status_code = error.response.status_code
+
+            if status_code == 401:
+                severity = ErrorSeverity.HIGH
+                can_retry = True
+                suggested_action = "refresh_token"
+                message = "Unauthorized - token may have expired"
+
+            elif status_code == 403:
+                severity = ErrorSeverity.HIGH
+                can_retry = False
+                suggested_action = "check_permissions"
+                message = f"Forbidden - no permission for {operation}"
+
+            elif status_code == 404:
+                severity = ErrorSeverity.LOW
+                can_retry = False
+                suggested_action = "verify_resource_exists"
+                message = f"Resource not found for {operation}"
+
+            elif status_code == 429:
+                severity = ErrorSeverity.LOW
+                can_retry = True
+                suggested_action = "respect_rate_limit"
+                # Extract Retry-After header
+                retry_after = self._extract_retry_after(error.response)
+                message = f"Rate limited - retry after {retry_after}s"
+
+            elif 500 <= status_code < 600:
+                severity = ErrorSeverity.MEDIUM
+                can_retry = True
+                suggested_action = "exponential_backoff"
+                message = f"Reddit server error {status_code} during {operation}"
+
+            else:
+                severity = ErrorSeverity.MEDIUM
+                message = f"HTTP error {status_code} during {operation}: {error.response.text[:100]}"
+
+        # Runtime errors - check for authentication failures
+        elif isinstance(error, RuntimeError):
+            error_str = str(error).lower()
+            # Authentication failures (suspended account, invalid credentials, OAuth errors)
+            # Covers: "authentication failed", "suspended", "invalid credentials"
+            # Plus Reddit OAuth error codes: "invalid_grant", "invalid_client"
+            # Plus 401 status in token requests (always auth failure, never transient)
+            if (
+                "authentication failed" in error_str
+                or "suspended" in error_str
+                or "invalid credentials" in error_str
+                or "invalid_grant" in error_str
+                or "invalid_client" in error_str
+                or ("token request failed" in error_str and "(401)" in error_str)
+            ):
+                severity = ErrorSeverity.CRITICAL
+                can_retry = False  # Don't retry auth failures - requires manual intervention
+                suggested_action = "check_account_status"
+                message = f"Reddit authentication failure: {str(error)}"
+            # Token refresh failures (temporary, non-auth issues like 5xx)
+            elif "token request failed" in error_str:
+                severity = ErrorSeverity.HIGH
+                can_retry = True  # Temporary token issues may resolve
+                suggested_action = "exponential_backoff"
+                message = f"Token refresh failed: {str(error)}"
+            else:
+                severity = ErrorSeverity.MEDIUM
+                message = f"Runtime error during {operation}: {str(error)}"
+
+        # Generic errors
+        else:
+            severity = ErrorSeverity.MEDIUM
+            message = f"Unexpected error during {operation}: {str(error)}"
+
+        # Track error frequency
+        self._track_error(error_key, severity)
+
+        result = RedditErrorInfo(
+            severity=severity,
+            message=message,
+            can_retry=can_retry,
+            error_type=type(error).__name__,
+            retry_after=retry_after,
+            operation=operation,
+            suggested_action=suggested_action,
+        )
+
+        # Log based on severity
+        if severity == ErrorSeverity.CRITICAL:
+            logger.critical(f"Reddit API critical error: {result.model_dump()}")
+        elif severity == ErrorSeverity.HIGH:
+            logger.error(f"Reddit API error: {result.model_dump()}")
+        elif severity == ErrorSeverity.MEDIUM:
+            logger.warning(f"Reddit API warning: {result.model_dump()}")
+        else:
+            logger.info(f"Reddit API info: {result.model_dump()}")
+
+        return result
+
+    def _extract_retry_after(self, response: httpx.Response) -> float:
+        """Extract retry-after value from response headers.
+
+        Args:
+            response: HTTP response with potential Retry-After header
+
+        Returns:
+            Seconds to wait (defaults to 1.0 if not present)
+        """
+        retry_after_header = response.headers.get("Retry-After", "1")
+        try:
+            return float(retry_after_header)
+        except ValueError:
+            # Header might be HTTP-date format, default to 1 second
+            return 1.0
+
+    def _track_error(self, error_key: str, severity: ErrorSeverity) -> None:
+        """Track error frequency and escalate if needed.
+
+        Args:
+            error_key: Unique key for this error type
+            severity: Error severity
+        """
+        now = datetime.now(timezone.utc)
+
+        # Clean old errors
+        cutoff = now - self._error_window
+        self._error_counts = {
+            k: v for k, v in self._error_counts.items() if k not in self._last_errors or self._last_errors[k] > cutoff
+        }
+
+        # Track this error
+        self._error_counts[error_key] = self._error_counts.get(error_key, 0) + 1
+        self._last_errors[error_key] = now
+
+        # Check for escalation
+        if self._error_counts[error_key] >= self._error_threshold:
+            logger.warning(
+                f"Error threshold reached for {error_key}: "
+                f"{self._error_counts[error_key]} errors in {self._error_window}"
+            )
+
+    async def retry_with_backoff(
+        self,
+        operation: Callable[[], Any],
+        max_retries: int = 3,
+        base_delay: float = 1.0,
+        max_delay: float = 60.0,
+        operation_name: str = "reddit_operation",
+    ) -> Any:
+        """Retry an operation with exponential backoff and jitter.
+
+        Implements industry best practices:
+        - Exponential backoff (2^attempt * base_delay)
+        - Jitter (random variation to prevent thundering herd)
+        - Max retry limit
+        - Max delay cap
+        - Error classification
+
+        Args:
+            operation: Async callable to retry
+            max_retries: Maximum number of retry attempts (default: 3)
+            base_delay: Base delay in seconds (default: 1.0)
+            max_delay: Maximum delay in seconds (default: 60.0)
+            operation_name: Name of operation for logging
+
+        Returns:
+            Result of the operation
+
+        Raises:
+            Last exception if all retries exhausted
+        """
+        last_error = None
+
+        for attempt in range(max_retries + 1):
+            try:
+                return await operation()
+
+            except Exception as exc:
+                last_error = exc
+                error_info = self.classify_error(exc, operation_name)
+
+                # Don't retry non-retryable errors
+                if not error_info.can_retry:
+                    logger.warning(f"{operation_name} failed with non-retryable error: {error_info.message}")
+                    raise
+
+                # Last attempt - don't wait
+                if attempt == max_retries:
+                    logger.error(f"{operation_name} failed after {max_retries + 1} attempts: {error_info.message}")
+                    raise
+
+                # Calculate backoff with jitter
+                if error_info.retry_after:
+                    # Use Retry-After header if available (429 rate limit)
+                    delay = error_info.retry_after
+                else:
+                    # Exponential backoff: 2^attempt * base_delay
+                    delay = min((2**attempt) * base_delay, max_delay)
+                    # Add jitter: ±25% random variation
+                    jitter = delay * 0.25 * (2 * random.random() - 1)
+                    delay = max(0.1, delay + jitter)
+
+                logger.info(
+                    f"{operation_name} attempt {attempt + 1}/{max_retries + 1} failed, "
+                    f"retrying in {delay:.2f}s: {error_info.message}"
+                )
+
+                await asyncio.sleep(delay)
+
+        # Should not reach here, but just in case
+        if last_error:
+            raise last_error
+        raise RuntimeError(f"{operation_name} failed with unknown error")
+
+    def get_error_stats(self) -> dict[str, Any]:
+        """Get current error statistics.
+
+        Returns:
+            Error statistics including counts, threshold, and window
+        """
+        return {
+            "error_counts": self._error_counts.copy(),
+            "threshold": self._error_threshold,
+            "window_minutes": self._error_window.total_seconds() / 60,
+        }

ciris_adapters/reddit/manifest.json

@@ -0,0 +1,218 @@
+{
+  "module": {
+    "name": "reddit_adapter",
+    "version": "1.0.0",
+    "description": "Adapter that connects CIRIS to Reddit with tool, communication, and observation services",
+    "author": "CIRIS Team",
+    "safe_domain": true
+  },
+  "services": [
+    {
+      "type": "TOOL",
+      "priority": "NORMAL",
+      "class": "reddit.service.RedditToolService",
+      "capabilities": [
+        "tool:reddit",
+        "tool:reddit:get_user_context",
+        "tool:reddit:submit_post",
+        "tool:reddit:submit_comment",
+        "tool:reddit:remove_content",
+        "tool:reddit:get_submission",
+        "tool:reddit:observe"
+      ]
+    },
+    {
+      "type": "COMMUNICATION",
+      "priority": "LOW",
+      "class": "reddit.service.RedditCommunicationService",
+      "capabilities": [
+        "communication:send_message",
+        "communication:fetch_messages"
+      ]
+    }
+  ],
+  "capabilities": [
+    "tool:reddit",
+    "tool:reddit:get_user_context",
+    "tool:reddit:submit_post",
+    "tool:reddit:submit_comment",
+    "tool:reddit:remove_content",
+    "tool:reddit:get_submission",
+    "tool:reddit:observe",
+    "communication:send_message",
+    "communication:fetch_messages"
+  ],
+  "dependencies": {
+    "protocols": [
+      "ciris_engine.protocols.services.ToolService",
+      "ciris_engine.protocols.services.CommunicationService"
+    ],
+    "schemas": [
+      "ciris_engine.schemas.adapters.tools",
+      "ciris_engine.schemas.runtime.enums",
+      "ciris_engine.schemas.runtime.messages"
+    ],
+    "external": {
+      "httpx": ">=0.25.0,<1.0.0"
+    }
+  },
+  "exports": {
+    "tool_service": "reddit.service.RedditToolService",
+    "communication_service": "reddit.service.RedditCommunicationService",
+    "observer": "reddit.observer.RedditObserver",
+    "protocol": "reddit.protocol.RedditOAuthProtocol",
+    "schemas": "reddit.schemas",
+    "adapter": "reddit.adapter.RedditAdapter",
+    "configurable": "reddit.configurable.RedditConfigurableAdapter"
+  },
+  "configuration": {
+    "reddit_client_id": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_CLIENT_ID",
+      "description": "Reddit OAuth client identifier"
+    },
+    "reddit_client_secret": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_CLIENT_SECRET",
+      "description": "Reddit OAuth client secret"
+    },
+    "reddit_username": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_USERNAME",
+      "description": "Bot account username"
+    },
+    "reddit_password": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_PASSWORD",
+      "sensitivity": "HIGH",
+      "description": "Bot account password"
+    },
+    "reddit_user_agent": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_USER_AGENT",
+      "default": "CIRIS-RedditAdapter/1.0 (+https://ciris.ai)",
+      "description": "User-Agent header that complies with Reddit API rules"
+    },
+    "reddit_subreddit": {
+      "type": "string",
+      "env": "CIRIS_REDDIT_SUBREDDIT",
+      "default": "ciris",
+      "description": "Home subreddit for passive observation"
+    }
+  },
+  "interactive_config": {
+    "required": false,
+    "workflow_type": "wizard",
+    "steps": [
+      {
+        "step_id": "client_credentials",
+        "step_type": "input",
+        "title": "Reddit OAuth Application Credentials",
+        "description": "Enter your Reddit OAuth app credentials from https://www.reddit.com/prefs/apps",
+        "fields": [
+          {
+            "field_id": "client_id",
+            "label": "Client ID",
+            "description": "OAuth client ID from your Reddit app",
+            "input_type": "text",
+            "required": true,
+            "placeholder": "Enter your Reddit client ID"
+          },
+          {
+            "field_id": "client_secret",
+            "label": "Client Secret",
+            "description": "OAuth client secret from your Reddit app",
+            "input_type": "password",
+            "required": true,
+            "placeholder": "Enter your Reddit client secret"
+          }
+        ]
+      },
+      {
+        "step_id": "bot_account",
+        "step_type": "input",
+        "title": "Reddit Bot Account Credentials",
+        "description": "Enter credentials for your Reddit bot account",
+        "fields": [
+          {
+            "field_id": "username",
+            "label": "Bot Username",
+            "description": "Reddit bot account username",
+            "input_type": "text",
+            "required": true,
+            "placeholder": "Enter your bot username"
+          },
+          {
+            "field_id": "password",
+            "label": "Bot Password",
+            "description": "Reddit bot account password",
+            "input_type": "password",
+            "required": true,
+            "placeholder": "Enter your bot password"
+          }
+        ],
+        "depends_on": ["client_credentials"]
+      },
+      {
+        "step_id": "user_agent",
+        "step_type": "input",
+        "title": "User-Agent Configuration",
+        "description": "Reddit requires a unique User-Agent string for API requests",
+        "fields": [
+          {
+            "field_id": "user_agent",
+            "label": "User-Agent",
+            "description": "Unique User-Agent string (required by Reddit API)",
+            "input_type": "text",
+            "required": true,
+            "default": "CIRIS-RedditAdapter/1.0 (+https://ciris.ai)",
+            "placeholder": "CIRIS-RedditAdapter/1.0 (+https://ciris.ai)"
+          }
+        ],
+        "depends_on": ["bot_account"]
+      },
+      {
+        "step_id": "select_subreddit",
+        "step_type": "input",
+        "title": "Home Subreddit",
+        "description": "Choose the primary subreddit for monitoring and interaction",
+        "fields": [
+          {
+            "field_id": "subreddit",
+            "label": "Subreddit",
+            "description": "Primary subreddit (without r/ prefix)",
+            "input_type": "text",
+            "required": false,
+            "default": "ciris",
+            "placeholder": "ciris"
+          }
+        ],
+        "depends_on": ["user_agent"],
+        "optional": true
+      },
+      {
+        "step_id": "select_post_types",
+        "step_type": "select",
+        "title": "Post Types to Monitor",
+        "description": "Choose which types of posts to monitor (optional)",
+        "options_method": "get_config_options",
+        "depends_on": ["user_agent"],
+        "optional": true
+      },
+      {
+        "step_id": "confirm",
+        "step_type": "confirm",
+        "title": "Confirm Configuration",
+        "description": "Review and apply your Reddit configuration"
+      }
+    ],
+    "completion_method": "apply_config"
+  },
+  "metadata": {
+    "api": "Reddit OAuth API",
+    "requires_api_key": true,
+    "safe_domain": "community_outreach",
+    "prohibited": ["medical", "political_campaigning"],
+    "channel_format": "reddit:r/<subreddit>:post/<submission_id>:comment/<comment_id>"
+  }
+}