Fix SEO skill 34 bugs, Korean labels, and transition Ahrefs refs to our-seo-agent (#2)

custom-skills/34-seo-reporting-dashboard/code/scripts/base_client.py

@@ -20,8 +20,10 @@ from tenacity import (
     retry_if_exception_type,
 )
 
+# Load environment variables
 load_dotenv()
 
+# Logging setup
 logging.basicConfig(
     level=logging.INFO,
     format="%(asctime)s - %(levelname)s - %(message)s",
@@ -34,6 +36,13 @@ class RateLimiter:
     """Rate limiter using token bucket algorithm."""
 
     def __init__(self, rate: float, per: float = 1.0):
+        """
+        Initialize rate limiter.
+
+        Args:
+            rate: Number of requests allowed
+            per: Time period in seconds (default: 1 second)
+        """
         self.rate = rate
         self.per = per
         self.tokens = rate
@@ -41,6 +50,7 @@ class RateLimiter:
         self._lock = asyncio.Lock()
 
     async def acquire(self) -> None:
+        """Acquire a token, waiting if necessary."""
         async with self._lock:
             now = datetime.now()
             elapsed = (now - self.last_update).total_seconds()
@@ -64,6 +74,14 @@ class BaseAsyncClient:
         requests_per_second: float = 3.0,
         logger: logging.Logger | None = None,
     ):
+        """
+        Initialize base client.
+
+        Args:
+            max_concurrent: Maximum concurrent requests
+            requests_per_second: Rate limit
+            logger: Logger instance
+        """
         self.semaphore = Semaphore(max_concurrent)
         self.rate_limiter = RateLimiter(requests_per_second)
         self.logger = logger or logging.getLogger(self.__class__.__name__)
@@ -83,6 +101,7 @@ class BaseAsyncClient:
         self,
         coro: Callable[[], Any],
     ) -> Any:
+        """Execute a request with rate limiting and retry."""
         async with self.semaphore:
             await self.rate_limiter.acquire()
             self.stats["requests"] += 1
@@ -100,6 +119,7 @@ class BaseAsyncClient:
         requests: list[Callable[[], Any]],
         desc: str = "Processing",
     ) -> list[Any]:
+        """Execute multiple requests concurrently."""
         try:
             from tqdm.asyncio import tqdm
             has_tqdm = True
@@ -124,6 +144,7 @@ class BaseAsyncClient:
             return await asyncio.gather(*tasks, return_exceptions=True)
 
     def print_stats(self) -> None:
+        """Print request statistics."""
         self.logger.info("=" * 40)
         self.logger.info("Request Statistics:")
         self.logger.info(f"  Total Requests: {self.stats['requests']}")
@@ -140,6 +161,8 @@ class ConfigManager:
 
     @property
     def google_credentials_path(self) -> str | None:
+        """Get Google service account credentials path."""
+        # Prefer SEO-specific credentials, fallback to general credentials
         seo_creds = os.path.expanduser("~/.credential/ourdigital-seo-agent.json")
         if os.path.exists(seo_creds):
             return seo_creds
@@ -147,23 +170,38 @@ class ConfigManager:
 
     @property
     def pagespeed_api_key(self) -> str | None:
+        """Get PageSpeed Insights API key."""
         return os.getenv("PAGESPEED_API_KEY")
 
+    @property
+    def custom_search_api_key(self) -> str | None:
+        """Get Custom Search API key."""
+        return os.getenv("CUSTOM_SEARCH_API_KEY")
+
+    @property
+    def custom_search_engine_id(self) -> str | None:
+        """Get Custom Search Engine ID."""
+        return os.getenv("CUSTOM_SEARCH_ENGINE_ID")
+
     @property
     def notion_token(self) -> str | None:
+        """Get Notion API token."""
         return os.getenv("NOTION_TOKEN") or os.getenv("NOTION_API_KEY")
 
     def validate_google_credentials(self) -> bool:
+        """Validate Google credentials are configured."""
         creds_path = self.google_credentials_path
         if not creds_path:
             return False
         return os.path.exists(creds_path)
 
     def get_required(self, key: str) -> str:
+        """Get required environment variable or raise error."""
         value = os.getenv(key)
         if not value:
             raise ValueError(f"Missing required environment variable: {key}")
         return value
 
 
+# Singleton config instance
 config = ConfigManager()