feat: add generic tier-aware rate limiting framework

Add RATE_LIMIT_TIERS class attribute and resolve_rate_limiter() static
method to BaseProvider. Any provider with subscription tiers can define
RATE_LIMIT_TIERS and pass tier + tiers to resolve_rate_limiter() to get
automatic tier-aware rate limiter creation.

Precedence: tier > explicit rate_limiter > None.
Tier matching is case-insensitive. Invalid tiers raise ValueError.

This is a provider-agnostic foundation -- no provider-specific code.
Providers adopt it by defining RATE_LIMIT_TIERS and calling
resolve_rate_limiter() in their constructor.

Ref: repowise-dev#68

Author: Societus

packages/core/src/repowise/core/providers/llm/base.py

@@ -15,7 +15,10 @@
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
-from typing import Any, AsyncIterator, Protocol, runtime_checkable
+from typing import Any, AsyncIterator, Protocol, TYPE_CHECKING, runtime_checkable
+
+if TYPE_CHECKING:
+    from repowise.core.rate_limiter import RateLimitConfig, RateLimiter
 
 
 @dataclass
@@ -59,8 +62,60 @@ class BaseProvider(ABC):
     - Return GeneratedResponse with correct token counts
     - Raise ProviderError on non-recoverable API errors
     - Raise RateLimitError on 429 responses after retries are exhausted
+
+    Class Attributes:
+        RATE_LIMIT_TIERS: Optional mapping of tier name to RateLimitConfig.
+            Providers with subscription tiers (e.g., Z.AI's lite/pro/max,
+            MiniMax's starter/plus/max) define this to support tier-aware
+            rate limiting. When set, users can pass ``tier="pro"`` to the
+            constructor and the appropriate rate limiter is created automatically.
     """
 
+    RATE_LIMIT_TIERS: dict[str, Any] = {}  # Override in subclasses
+
+    @staticmethod
+    def resolve_rate_limiter(
+        tier: str | None = None,
+        tiers: dict[str, Any] | None = None,
+        rate_limiter: Any | None = None,
+    ) -> Any | None:
+        """Resolve rate limiter using tier precedence.
+
+        Precedence: tier > explicit rate_limiter > None.
+
+        When tier is set, it takes precedence -- it represents a specific
+        provider signal that overrides the generic registry default.
+
+        Args:
+            tier: Tier name (e.g., 'lite', 'pro', 'max'). Case-insensitive.
+            tiers: Mapping of tier name to RateLimitConfig.
+            rate_limiter: Explicitly provided RateLimiter instance.
+
+        Returns:
+            A RateLimiter instance, or None if neither tier nor
+            rate_limiter is provided.
+
+        Raises:
+            ValueError: If tier is not found in the tiers mapping.
+        """
+        # Late import to avoid circular dependency at module level
+        from repowise.core.rate_limiter import RateLimiter
+
+        if tier is not None:
+            if not tiers:
+                msg = f"Tier {tier!r} specified but provider defines no tiers"
+                raise ValueError(msg)
+            tier_key = tier.lower()
+            tier_config = tiers.get(tier_key)
+            if tier_config is None:
+                valid = ", ".join(sorted(tiers))
+                msg = f"Unknown tier {tier!r}. Valid tiers: {valid}"
+                raise ValueError(msg)
+            return RateLimiter(tier_config)
+        if rate_limiter is not None:
+            return rate_limiter
+        return None
+
     @abstractmethod
     async def generate(
         self,

tests/unit/test_providers/test_generic_tier_framework.py

@@ -0,0 +1,71 @@
+"""Unit tests for BaseProvider.resolve_rate_limiter (generic tier framework).
+
+These tests verify the tier resolution logic independent of any specific provider.
+Any provider that defines RATE_LIMIT_TIERS gets this behavior for free via
+BaseProvider.resolve_rate_limiter().
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.providers.llm.base import BaseProvider
+from repowise.core.rate_limiter import RateLimitConfig, RateLimiter
+
+
+def test_resolve_rate_limiter_with_tier():
+    """resolve_rate_limiter should create a limiter from tier config."""
+    tiers = {
+        "basic": RateLimitConfig(requests_per_minute=5, tokens_per_minute=10_000),
+        "premium": RateLimitConfig(requests_per_minute=50, tokens_per_minute=100_000),
+    }
+    limiter = BaseProvider.resolve_rate_limiter(tier="premium", tiers=tiers)
+    assert limiter is not None
+    assert limiter.config.requests_per_minute == 50
+
+
+def test_resolve_rate_limiter_tier_overrides_explicit():
+    """Tier should take precedence over explicit rate_limiter."""
+    tiers = {"pro": RateLimitConfig(requests_per_minute=30, tokens_per_minute=100_000)}
+    explicit = RateLimiter(RateLimitConfig(requests_per_minute=999, tokens_per_minute=999_999))
+    limiter = BaseProvider.resolve_rate_limiter(tier="pro", tiers=tiers, rate_limiter=explicit)
+    assert limiter is not explicit
+    assert limiter.config.requests_per_minute == 30
+
+
+def test_resolve_rate_limiter_explicit_without_tier():
+    """Without tier, explicit rate_limiter should be returned."""
+    explicit = RateLimiter(RateLimitConfig(requests_per_minute=42, tokens_per_minute=420_000))
+    limiter = BaseProvider.resolve_rate_limiter(rate_limiter=explicit)
+    assert limiter is explicit
+
+
+def test_resolve_rate_limiter_none_when_nothing_provided():
+    """Should return None when neither tier nor rate_limiter is provided."""
+    limiter = BaseProvider.resolve_rate_limiter()
+    assert limiter is None
+
+
+def test_resolve_rate_limiter_invalid_tier():
+    """Invalid tier should raise ValueError."""
+    tiers = {"basic": RateLimitConfig(requests_per_minute=5, tokens_per_minute=10_000)}
+    with pytest.raises(ValueError, match="Unknown tier"):
+        BaseProvider.resolve_rate_limiter(tier="enterprise", tiers=tiers)
+
+
+def test_resolve_rate_limiter_tier_but_no_tiers_defined():
+    """Tier with empty tiers dict should raise ValueError."""
+    with pytest.raises(ValueError, match="defines no tiers"):
+        BaseProvider.resolve_rate_limiter(tier="pro", tiers={})
+
+
+def test_resolve_rate_limiter_case_insensitive():
+    """Tier matching should be case-insensitive."""
+    tiers = {"pro": RateLimitConfig(requests_per_minute=30, tokens_per_minute=100_000)}
+    limiter = BaseProvider.resolve_rate_limiter(tier="PRO", tiers=tiers)
+    assert limiter.config.requests_per_minute == 30
+
+
+def test_base_provider_default_empty_tiers():
+    """BaseProvider should have empty RATE_LIMIT_TIERS by default."""
+    assert BaseProvider.RATE_LIMIT_TIERS == {}