keycycle 0.1.0__tar.gz

keycycle-0.1.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: keycycle
+Version: 0.1.0
+Summary: A thread-safe key rotation and rate limiting manager for API keys.
+Author-email: William Jin <jinwilliam.jin@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: python-dotenv
+Requires-Dist: sqlalchemy
+Requires-Dist: pymysql
+Requires-Dist: rich
+Provides-Extra: openai
+Requires-Dist: openai; extra == "openai"
+Provides-Extra: agno
+Requires-Dist: agno; extra == "agno"
+Provides-Extra: all
+Requires-Dist: openai; extra == "all"
+Requires-Dist: agno; extra == "all"

keycycle-0.1.0/keycycle/__init__.py

@@ -0,0 +1,8 @@
+from .multi_provider_wrapper import RateLimits, MultiProviderWrapper, RotatingAsyncOpenAIClient, RotatingOpenAIClient
+__all__ = [
+    "RateLimits", 
+    "RotatingKeyManager", 
+    "MultiProviderWrapper",
+    "RotatingAsyncOpenAIClient", 
+    "RotatingOpenAIClient",
+]

keycycle-0.1.0/keycycle/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .openai_adapter import RotatingOpenAIClient, RotatingAsyncOpenAIClient
+
+__all__ = ["RotatingOpenAIClient", "RotatingAsyncOpenAIClient"]

keycycle-0.1.0/keycycle/adapters/openai_adapter.py

@@ -0,0 +1,254 @@
+import logging
+import time
+from typing import List, Any, Optional, Union, Callable, Generator, AsyncGenerator
+
+from ..config.dataclasses import KeyUsage, RateLimits
+from ..key_rotation.rotation_manager import RotatingKeyManager
+
+logger = logging.getLogger(__name__)
+
+try:
+    import openai
+    from openai import OpenAI, AsyncOpenAI, RateLimitError, APIError
+    HAS_OPENAI = True
+except ImportError:
+    HAS_OPENAI = False
+    # Generic placeholders
+    OpenAI = object
+    AsyncOpenAI = object
+    RateLimitError = Exception
+    APIError = Exception
+
+PROVIDER_BASE_URLS = {
+    "openai": "https://api.openai.com/v1",
+    "openrouter": "https://openrouter.ai/api/v1",
+    "gemini": "https://generativelanguage.googleapis.com/v1beta/openai/",
+    "cerebras": "https://api.cerebras.ai/v1",
+    "groq": "https://api.groq.com/openai/v1",
+    "cohere": "https://api.cohere.ai/compatibility/v1",
+
+}
+
+class BaseRotatingClient:
+    def __init__(self, 
+        manager: RotatingKeyManager, 
+        limit_resolver: Callable[[str], RateLimits],
+        default_model: str, 
+        estimated_tokens: int = 1000, 
+        max_retries: int = 5,
+        base_url: Optional[str] = None,
+        provider: Optional[str] = None,
+        client_kwargs: dict = None
+    ):
+        """
+        Initialize the rotating client.
+        
+        Args:
+            manager: The key rotation manager
+            limit_resolver: Function to resolve rate limits for a model
+            default_model: Default model to use
+            estimated_tokens: Estimated tokens per request
+            max_retries: Maximum number of retries on rate limit
+            base_url: Base URL for the API (takes precedence over provider)
+            provider: Provider name (openai, openrouter, gemini, cerebras, groq)
+            client_kwargs: Additional kwargs to pass to OpenAI client
+        """
+        
+        if not HAS_OPENAI:
+            raise ImportError("The 'openai' library is required. Install with `pip install openai`.")
+            
+        self.manager = manager
+        self.limit_resolver = limit_resolver
+        self.default_model = default_model
+        self.estimated_tokens = estimated_tokens
+        self.max_retries = max_retries
+        self.client_kwargs = client_kwargs or {}
+
+        if base_url:
+            self.base_url = base_url
+        elif provider:
+            provider_lower = provider.lower()
+            if provider_lower not in PROVIDER_BASE_URLS:
+                raise ValueError(
+                    f"Unknown provider: {provider}. "
+                    f"Valid providers: {', '.join(PROVIDER_BASE_URLS.keys())}"
+                )
+            self.base_url = PROVIDER_BASE_URLS[provider_lower]
+        else:
+            self.base_url = None  # Will use OpenAI's default
+
+        if self.base_url:
+            self.client_kwargs['base_url'] = self.base_url
+
+    def _is_rate_limit(self, e: Exception) -> bool:
+        if isinstance(e, RateLimitError):
+            return True
+        err_str = str(e).lower()
+        return "429" in err_str or "too many requests" in err_str or "rate limit" in err_str or "resource exhausted" in err_str
+
+    def _record_usage(self, key_usage: KeyUsage, model_id: str, actual_tokens: int):
+        self.manager.record_usage(
+            key_obj=key_usage, 
+            model_id=model_id, 
+            actual_tokens=actual_tokens, 
+            estimated_tokens=self.estimated_tokens
+        )
+        
+    def _extract_usage(self, response: Any) -> int:
+        try:
+            if hasattr(response, 'usage') and response.usage:
+                return response.usage.total_tokens
+        except:
+            pass
+        return 0
+
+# --- SYNC IMPLEMENTATION ---
+
+class RotatingOpenAIClient(BaseRotatingClient):
+    def _get_fresh_client(self, api_key: str):
+        return OpenAI(api_key=api_key, **self.client_kwargs)
+
+    def __getattr__(self, name):
+        return SyncProxyHelper(self, [name])
+
+    def _execute(self, path: List[str], args, kwargs):
+        model_id = kwargs.get('model', self.default_model)
+        if 'model' not in kwargs:
+            kwargs['model'] = model_id
+        limits = self.limit_resolver(model_id)
+        
+        for attempt in range(self.max_retries + 1):
+            key_usage = self.manager.get_key(model_id, limits, self.estimated_tokens)
+            if not key_usage:
+                raise RuntimeError(f"No available keys for {model_id}")
+
+            try:
+                real_client = self._get_fresh_client(key_usage.api_key)
+                
+                target = real_client
+                for p in path:
+                    target = getattr(target, p)
+                
+                result = target(*args, **kwargs)
+                
+                if kwargs.get('stream', False):
+                    return self._wrap_stream(result, key_usage, model_id)
+                
+                self._record_usage(key_usage, model_id, self._extract_usage(result))
+                return result
+
+            except Exception as e:
+                if self._is_rate_limit(e) and attempt < self.max_retries:
+                    logger.warning(f"429/RateLimit hit for {model_id} on key ...{key_usage.api_key[-8:]}. Rotating. (Attempt {attempt + 1}/{self.max_retries + 1})")
+                    key_usage.trigger_cooldown()
+                    self.manager.force_rotate_index()
+                    time.sleep(0.5)
+                    continue
+                self._record_usage(key_usage, model_id, 0) 
+                raise e
+
+    def _wrap_stream(self, generator: Generator, key_usage: KeyUsage, model_id: str):
+        accumulated_tokens = 0
+        try:
+            for chunk in generator:
+                if hasattr(chunk, 'usage') and chunk.usage:
+                    accumulated_tokens = chunk.usage.total_tokens
+                yield chunk
+        except Exception as e:
+            if self._is_rate_limit(e):
+                logger.warning(f"Rate limit hit during streaming for {model_id} on key ...{key_usage.api_key[-8:]}.")
+                key_usage.trigger_cooldown()
+                self.manager.force_rotate_index()
+            raise
+        finally:
+            self._record_usage(key_usage, model_id, accumulated_tokens)
+
+class SyncProxyHelper:
+    def __init__(self, client: RotatingOpenAIClient, path: List[str]):
+        self.client = client
+        self.path = path
+
+    def __getattr__(self, name):
+        return SyncProxyHelper(self.client, self.path + [name])
+
+    def __call__(self, *args, **kwargs):
+        return self.client._execute(self.path, args, kwargs)
+
+
+# --- ASYNC IMPLEMENTATION ---
+
+class RotatingAsyncOpenAIClient(BaseRotatingClient):
+    def _get_fresh_client(self, api_key: str):
+        return AsyncOpenAI(api_key=api_key, **self.client_kwargs)
+
+    def __getattr__(self, name):
+        return AsyncProxyHelper(self, [name])
+
+    async def _execute(self, path: List[str], args, kwargs: dict):
+        model_id = kwargs.get('model', self.default_model)
+        if 'model' not in kwargs:
+            kwargs['model'] = model_id
+        limits = self.limit_resolver(model_id)
+        
+        if kwargs.get('stream', False) and 'stream_options' not in kwargs:
+            kwargs['stream_options'] = {"include_usage": True}
+        
+        if kwargs.get('stream', False) and 'stream_options' not in kwargs:
+            kwargs['stream_options'] = {"include_usage": True}
+
+        for attempt in range(self.max_retries + 1):
+            key_usage = self.manager.get_key(model_id, limits, self.estimated_tokens)
+            if not key_usage:
+                raise RuntimeError(f"No available keys for {model_id}")
+
+            try:
+                real_client = self._get_fresh_client(key_usage.api_key)
+                
+                target = real_client
+                for p in path:
+                    target = getattr(target, p)
+                
+                result = await target(*args, **kwargs)
+                
+                if kwargs.get('stream', False):
+                    return self._wrap_stream(result, key_usage, model_id)
+                
+                self._record_usage(key_usage, model_id, self._extract_usage(result))
+                return result
+
+            except Exception as e:
+                if self._is_rate_limit(e) and attempt < self.max_retries:
+                    logger.warning(f"429/RateLimit hit for {model_id} on key ...{key_usage.api_key[-8:]}. Rotating. (Attempt {attempt + 1}/{self.max_retries + 1})")
+                    key_usage.trigger_cooldown()
+                    self.manager.force_rotate_index()
+                    time.sleep(0.5)
+                    continue
+                self._record_usage(key_usage, model_id, 0) 
+                raise e
+
+    async def _wrap_stream(self, generator: AsyncGenerator, key_usage: KeyUsage, model_id: str):
+        accumulated_tokens = 0
+        try:
+            async for chunk in generator:
+                if hasattr(chunk, 'usage') and chunk.usage:
+                    accumulated_tokens = chunk.usage.total_tokens
+                yield chunk
+        except Exception as e:
+            if self._is_rate_limit(e):
+                logger.warning(f"Rate limit hit during streaming for {model_id} on key ...{key_usage.api_key[-8:]}.")
+                key_usage.trigger_cooldown()
+                self.manager.force_rotate_index()
+            raise
+        finally:
+            self._record_usage(key_usage, model_id, accumulated_tokens)
+
+class AsyncProxyHelper:
+    def __init__(self, client: RotatingAsyncOpenAIClient, path: List[str]):
+        self.client = client
+        self.path = path
+
+    def __getattr__(self, name):
+        return AsyncProxyHelper(self.client, self.path + [name])
+
+    async def __call__(self, *args, **kwargs):
+        return await self.client._execute(self.path, args, kwargs)

keycycle-0.1.0/keycycle/config/__init__.py

@@ -0,0 +1,25 @@
+from .dataclasses import (
+    RateLimits,
+    UsageSnapshot,
+    UsageBucket,
+    KeyUsage,
+    KeyDetailedStats,
+    KeySummary,
+    GlobalStats,
+    ModelAggregatedStats,
+)
+from .enums import RateLimitStrategy
+from .log_config import configure_logging
+
+__all__ = [
+    "RateLimits",
+    "UsageSnapshot",
+    "UsageBucket",
+    "KeyUsage",
+    "KeyDetailedStats",
+    "KeySummary",
+    "GlobalStats",
+    "ModelAggregatedStats",
+    "RateLimitStrategy",
+    "configure_logging",
+]

keycycle-0.1.0/keycycle/config/constants.py

@@ -0,0 +1,56 @@
+from .dataclasses import RateLimits
+from .enums import RateLimitStrategy
+
+PROVIDER_STRATEGIES = {
+    'cerebras': RateLimitStrategy.PER_MODEL,
+    'groq': RateLimitStrategy.PER_MODEL,
+    'gemini': RateLimitStrategy.PER_MODEL,
+    'openrouter': RateLimitStrategy.GLOBAL,
+}
+
+MODEL_LIMITS = {
+    'cerebras': {
+        'gpt-oss-120b': RateLimits(30, 900, 14400, 60000, 1000000, 1000000),
+        'llama3.1-8b': RateLimits(30, 900, 14400, 60000, 1000000, 1000000),
+        'llama-3.3-70b': RateLimits(30, 900, 14400, 60000, 1000000, 1000000),
+        'qwen-3-32b': RateLimits(30, 900, 14400, 60000, 1000000, 1000000),
+        'qwen-3-235b-a22b-instruct-2507': RateLimits(30, 900, 14400, 60000, 1000000, 1000000),
+        'zai-glm-4.6': RateLimits(10, 100, 100, 150000, 1000000, 1000000),
+    },
+    'groq': {
+        'allam-2-7b': RateLimits(30, 1800, 7000, 6000, 360000, 500000),
+        'groq/compound': RateLimits(30, 250, 250, 70000, None, None),
+        'groq/compound-mini': RateLimits(30, 250, 250, 70000, None, None),
+        'llama-3.1-8b-instant': RateLimits(30, 1800, 14400, 6000, 360000, 500000),
+        'llama-3.3-70b-versatile': RateLimits(30, 1000, 1000, 12000, 720000, 100000),
+        'meta-llama/llama-4-maverick-17b-128e-instruct': RateLimits(30, 1000, 1000, 6000, 360000, 500000),
+        'meta-llama/llama-4-scout-17b-16e-instruct': RateLimits(30, 1000, 1000, 30000, 1800000, 500000),
+        'meta-llama/llama-guard-4-12b': RateLimits(30, 1800, 14400, 15000, 900000, 500000),
+        'meta-llama/llama-prompt-guard-2-22m': RateLimits(30, 1800, 14400, 15000, 900000, 500000),
+        'meta-llama/llama-prompt-guard-2-86m': RateLimits(30, 1800, 14400, 15000, 900000, 500000),
+        'moonshotai/kimi-k2-instruct': RateLimits(60, 1000, 1000, 10000, 600000, 300000),
+        'moonshotai/kimi-k2-instruct-0905': RateLimits(60, 1000, 1000, 10000, 600000, 300000),
+        'openai/gpt-oss-120b': RateLimits(30, 1000, 1000, 8000, 480000, 200000),
+        'openai/gpt-oss-20b': RateLimits(30, 1000, 1000, 8000, 480000, 200000),
+        'openai/gpt-oss-safeguard-20b': RateLimits(30, 1000, 1000, 8000, 480000, 200000),
+        'playai-tts': RateLimits(10, 100, 100, 1200, 72000, 3600),
+        'playai-tts-arabic': RateLimits(10, 100, 100, 1200, 72000, 3600),
+        'qwen/qwen3-32b': RateLimits(60, 1000, 1000, 6000, 360000, 500000),
+        'whisper-large-v3': RateLimits(20, 2000, 2000),
+        'whisper-large-v3-turbo': RateLimits(20, 2000, 2000),
+    },
+    'gemini': {
+        'gemini-2.5-flash': RateLimits(5, 300, 20, 250000, 15000000),
+        'gemini-2.5-flash-lite': RateLimits(10, 600, 20, 250000, 15000000),
+        'gemini-2.5-flash-tts': RateLimits(3, 180, 10, 10000, 600000),
+        'gemini-robotics-er-1.5-preview': RateLimits(10, 600, 250, 250000, 15000000),
+        'gemma-3-12b': RateLimits(30, 1800, 14400, 15000, 900000),
+        'gemma-3-1b': RateLimits(30, 1800, 14400, 15000, 900000),
+        'gemma-3-27b': RateLimits(30, 1800, 14400, 15000, 900000),
+        'gemma-3-2b': RateLimits(30, 1800, 14400, 15000, 900000),
+        'gemma-3-4b': RateLimits(30, 1800, 14400, 15000, 900000),
+    },
+    'openrouter': {
+        'default': RateLimits(20, 50, 50),
+    },
+}

keycycle-0.1.0/keycycle/config/dataclasses.py

@@ -0,0 +1,190 @@
+from typing import Dict, List, Optional
+from .enums import RateLimitStrategy
+import time
+from collections import deque, defaultdict
+from dataclasses import dataclass, field
+
+# --- CONFIGURATION DATA ---
+
+@dataclass
+class RateLimits:
+    """Rate limits for a provider"""
+    requests_per_minute: int
+    requests_per_hour: int
+    requests_per_day: int
+    tokens_per_minute: Optional[int] = None
+    tokens_per_hour: Optional[int] = None
+    tokens_per_day: Optional[int] = None
+
+@dataclass
+class UsageSnapshot:
+    """Standardized view of usage counters"""
+    rpm: int = 0
+    rph: int = 0
+    rpd: int = 0
+    tpm: int = 0
+    tph: int = 0
+    tpd: int = 0
+    total_requests: int = 0
+    total_tokens: int = 0
+
+    def __add__(self, other):
+        """Allow summing snapshots for aggregation"""
+        if not isinstance(other, UsageSnapshot): return NotImplemented
+        return UsageSnapshot(
+            self.rpm + other.rpm, self.rph + other.rph, self.rpd + other.rpd,
+            self.tpm + other.tpm, self.tph + other.tph, self.tpd + other.tpd,
+            self.total_requests + other.total_requests, self.total_tokens + other.total_tokens
+        )
+
+# --- STATS DATA TRANSFER OBJECTS (DTOs) ---
+
+@dataclass
+class KeySummary:
+    index: int; suffix: str; snapshot: UsageSnapshot
+@dataclass
+class GlobalStats:
+    total: UsageSnapshot; keys: List[KeySummary]
+@dataclass
+class KeyDetailedStats:
+    index: int; suffix: str; total: UsageSnapshot; breakdown: Dict[str, UsageSnapshot]
+@dataclass
+class ModelAggregatedStats:
+    model_id: str; total: UsageSnapshot; keys: List[KeySummary]
+    
+
+# --- USAGE TRACKING ---
+@dataclass
+class UsageBucket:
+    """Tracks counters for a SINGLE model context"""
+    requests_minute: deque[float] = field(default_factory=deque)
+    requests_hour: deque[float] = field(default_factory=deque)
+    requests_day: deque[float] = field(default_factory=deque)
+    
+    tokens_minute: deque[tuple[float, int]] = field(default_factory=deque)
+    tokens_hour: deque[tuple[float, int]] = field(default_factory=deque)
+    tokens_day: deque[tuple[float, int]] = field(default_factory=deque)
+    
+    total_requests: int = 0
+    total_tokens: int = 0
+    
+    pending_tokens: int = 0
+    
+    def clean(self):
+        """Clean old entries based on current time"""
+        now = time.time()
+        cutoffs = (now - 60, now - 3600, now - 86400)
+        
+        for d, cut in zip(
+            [self.requests_minute, self.requests_hour, self.requests_day], cutoffs
+        ):
+            while d and d[0] <= cut: d.popleft()
+            
+        for d, cut in zip(
+            [self.tokens_minute, self.tokens_hour, self.tokens_day], cutoffs
+        ):
+            while d and d[0][0] <= cut: d.popleft()
+    
+    def add(self, tokens: int, timestamp: float):
+        self.requests_minute.append(timestamp)
+        self.requests_hour.append(timestamp)
+        self.requests_day.append(timestamp)
+        self.total_requests += 1
+        
+        if tokens > 0:
+            self.tokens_minute.append((timestamp, tokens))
+            self.tokens_hour.append((timestamp, tokens))
+            self.tokens_day.append((timestamp, tokens))
+            self.total_tokens += tokens
+    
+    def check_limits(self, limits: RateLimits, estimated_tokens: int) -> bool:
+        self.clean()
+        if len(self.requests_minute) >= limits.requests_per_minute: return False
+        if len(self.requests_hour) >= limits.requests_per_hour: return False
+        if len(self.requests_day) >= limits.requests_per_day: return False
+        
+        current_tpm = sum(t[1] for t in self.tokens_minute) + self.pending_tokens
+        current_tph = sum(t[1] for t in self.tokens_hour) + self.pending_tokens
+        current_tpd = sum(t[1] for t in self.tokens_day) + self.pending_tokens
+        
+        if limits.tokens_per_minute and (current_tpm + estimated_tokens > limits.tokens_per_minute): return False
+        if limits.tokens_per_hour and (current_tph + estimated_tokens > limits.tokens_per_hour): return False
+        if limits.tokens_per_day and (current_tpd + estimated_tokens > limits.tokens_per_day): return False
+        
+        return True
+    
+    def reserve(self, tokens: int):
+        """Lock in estimated tokens"""
+        self.pending_tokens += tokens
+    
+    def commit(self, actual_tokens: int, reserved_tokens: int, timestamp: float):
+        """Remove reservation and add actual usage"""
+        self.pending_tokens -= reserved_tokens
+        if self.pending_tokens < 0: self.pending_tokens = 0 # Safety floor
+        self.add(actual_tokens, timestamp)
+    
+    def get_snapshot(self) -> UsageSnapshot:
+        """Return current counts as a clean snapshot"""
+        self.clean()
+        return UsageSnapshot(
+            rpm=len(self.requests_minute),
+            rph=len(self.requests_hour),
+            rpd=len(self.requests_day),
+            tpm=sum(t[1] for t in self.tokens_minute),
+            tph=sum(t[1] for t in self.tokens_hour),
+            tpd=sum(t[1] for t in self.tokens_day),
+            total_requests=self.total_requests,
+            total_tokens=self.total_tokens
+        )
+    
+
+@dataclass
+class KeyUsage:
+    """Represents an API Key and holds multiple UsageBuckets (one per model)"""
+    api_key: str
+    strategy: RateLimitStrategy
+    buckets: Dict[str, UsageBucket] = field(default_factory=lambda: defaultdict(UsageBucket))
+    global_bucket: UsageBucket = field(default_factory=UsageBucket)
+    last_429: float = 0.0
+    
+    def record_usage(self, model_id: str, tokens: int, timestamp: float = None):
+        ts = timestamp if timestamp else time.time()
+        self.buckets[model_id].add(tokens, ts)
+        if self.strategy == RateLimitStrategy.GLOBAL:
+            self.global_bucket.add(tokens, ts)
+        
+    def can_use_model(self, model_id: str, limits: RateLimits, estimated_tokens: int = 1000) -> bool:
+        """Check limits based on the provider's strategy"""
+        if self.strategy == RateLimitStrategy.GLOBAL:
+            return self.global_bucket.check_limits(limits, estimated_tokens)
+        else: # Per-Model Limits
+            return self.buckets[model_id].check_limits(limits, estimated_tokens)
+
+    def get_total_snapshot(self) -> UsageSnapshot:
+        if self.strategy == RateLimitStrategy.GLOBAL:
+            return self.global_bucket.get_snapshot()
+        total = UsageSnapshot()
+        for b in self.buckets.values():
+            total = total + b.get_snapshot()
+        return total
+    
+    def reserve(self, model_id: str, tokens: int):
+        self.buckets[model_id].reserve(tokens)
+        if self.strategy == RateLimitStrategy.GLOBAL:
+            self.global_bucket.reserve(tokens)
+    
+    def commit(self, model_id: str, actual_tokens: int, reserved_tokens: int, timestamp: float = None):
+        ts = timestamp if timestamp else time.time()
+        self.buckets[model_id].commit(actual_tokens, reserved_tokens, ts)
+        if self.strategy == RateLimitStrategy.GLOBAL:
+            self.global_bucket.commit(actual_tokens, reserved_tokens, ts)
+
+
+    def is_cooling_down(self, cooldown_seconds: int = 30) -> bool:
+        """Returns True if the key is still in its 30s penalty box."""
+        if self.last_429 == 0: return False
+        return (time.time() - self.last_429) < cooldown_seconds
+
+    def trigger_cooldown(self):
+        """Mark this key as rate-limited."""
+        self.last_429 = time.time()

keycycle-0.1.0/keycycle/config/enums.py

@@ -0,0 +1,5 @@
+from enum import Enum
+
+class RateLimitStrategy(Enum):
+    PER_MODEL = "per_model"  # Cerebras, Groq, Gemini
+    GLOBAL = "global"        # OpenRouter (Shared limits across all models)

keycycle-0.1.0/keycycle/config/log_config.py

@@ -0,0 +1,53 @@
+import logging
+import logging.config
+from logging.handlers import RotatingFileHandler
+from rich.logging import RichHandler
+
+LOGGING_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "standard": {
+            "format": "%(asctime)s | %(levelname)-8s | %(name)s:%(lineno)d | %(message)s",
+            "datefmt": "%Y-%m-%d %H:%M:%S",
+        },
+    },
+
+    "handlers": {
+        "console": {
+            "class": "rich.logging.RichHandler",
+            "level": "DEBUG",
+            "rich_tracebacks": True, # Beautiful traceback formatting
+            "markup": True,          # Allow "[bold]text[/]" inside log messages!
+            "show_path": False       # Cleaner output (hides file path column)
+        },
+         "file": {
+            "class": "logging.handlers.RotatingFileHandler",
+            "level": "INFO",
+            "formatter": "standard",
+            "filename": "app.log",
+            "maxBytes": 10 * 1024 * 1024,   # 10 MiB per file
+            "backupCount": 5,
+            "encoding": "utf-8",
+        },
+    },
+    
+    "root": {
+        "handlers": ["console", "file"],
+        "level": "WARNING", 
+    },
+    
+    "loggers": {
+       "key_manager": {
+            "handlers": ["console", "file"],
+            "level": "DEBUG",
+            "propagate": False,
+        },
+    },
+}
+
+def configure_logging():
+    logging.config.dictConfig(LOGGING_CONFIG)
+
+configure_logging()
+default_logger = logging.getLogger(__name__)

keycycle-0.1.0/keycycle/key_rotation/__init__.py

@@ -0,0 +1,7 @@
+from .rotating_mixin import RotatingCredentialsMixin
+from .rotation_manager import RotatingKeyManager
+
+__all__ = [
+    "RotatingKeyManager",
+    "RotatingCredentialsMixin"
+]