open-keypool 0.2.0__py3-none-any.whl

open_keypool/__init__.py

@@ -0,0 +1,57 @@
+"""open_keypool — a minimal Python library for pooling and rotating API keys.
+
+Avoids HTTP 429 rate-limit errors by cycling through a pool of keys with
+cooldown and disablement support. Provide a list of keys (or pull them from
+Doppler), choose a rotation strategy (round-robin or least-recently-used),
+and the pool handles cooldown on rate-limit responses and permanent
+disablement on invalid keys — all thread-safe.
+
+Install
+-------
+.. code-block:: bash
+
+    pip install open-keypool
+
+Quickstart — Local keys array
+-----------------------------
+.. code-block:: python
+
+    from open_keypool import KeyPool, AllKeysExhaustedError
+
+    pool = KeyPool(keys=["sk-key1", "sk-key2", "sk-key3"], strategy="round_robin")
+
+    for attempt in range(pool.max_retries):
+        key = pool.get_key()
+        response = call_your_api(key)
+        if response.status_code == 429:
+            retry_after = float(response.headers.get("Retry-After", 0))
+            pool.mark_rate_limited(key, retry_after=retry_after or None)
+        elif response.status_code in (401, 403):
+            pool.mark_invalid(key)
+        else:
+            pool.mark_success(key)
+            break
+
+Quickstart — Doppler
+--------------------
+.. code-block:: python
+
+    import os
+    from open_keypool import KeyPool
+
+    DOPPLER_TOKEN = os.getenv("DOPPLER_TOKEN", "dp.st.YOUR_SERVICE_TOKEN")
+    PROJECT_NAME = "refactor-ai"
+    CONFIG_NAME = "dev"
+
+    pool = KeyPool.from_doppler(
+        token=DOPPLER_TOKEN,
+        project=PROJECT_NAME,
+        config=CONFIG_NAME,
+        key_prefix="MY_APP_",
+        strategy="lru",
+    )
+"""
+
+from open_keypool.core import AllKeysExhaustedError, KeyPool, KeyState
+
+__all__ = ["KeyPool", "AllKeysExhaustedError", "KeyState"]

open_keypool/core.py

@@ -0,0 +1,845 @@
+"""Core implementation of the open_keypool library.
+
+Provides the `KeyPool` class for managing a pool of API keys with automatic
+cooldown, disablement, and rotation strategies to avoid HTTP 429 rate-limit
+errors.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+
+import cachetools
+import httpx
+from dotenv import load_dotenv
+
+
+class KeyState(Enum):
+    """Possible states for a key in the pool.
+
+    Attributes:
+        ACTIVE: The key is healthy and available for use.
+        COOLDOWN: The key is temporarily unavailable (rate-limited) and will
+            automatically recover after *cooldown_seconds* elapses.
+        DISABLED: The key is permanently unusable and will never auto-recover.
+    """
+
+    ACTIVE = "active"
+    COOLDOWN = "cooldown"
+    DISABLED = "disabled"
+
+
+@dataclass(slots=True)
+class _KeyRecord:
+    """Internal representation of a single API key and its health metadata."""
+
+    key: str
+    state: KeyState = KeyState.ACTIVE
+    cooldown_until: float | None = None
+    last_used: float = field(default_factory=time.monotonic)
+    failure_count: int = 0
+    last_status_code: int | None = None
+    last_error_code: str | None = None
+    last_error_message: str | None = None
+
+
+class AllKeysExhaustedError(Exception):
+    """Raised when no ACTIVE key is available in the pool.
+
+    The exception message includes the soonest recovery time in seconds if any
+    key is in COOLDOWN, otherwise it reports that all keys are disabled.
+    """
+
+    pass
+
+
+def mask(key: str) -> str:
+    """Return a masked representation of an API key.
+
+    Produces a string of the form ``"sk-1...b2c9"`` — the first few characters
+    followed by ``...`` and the last 4 characters. Never use the raw key value
+    in logs, print statements, or exception messages.
+
+    Parameters
+    ----------
+    key : str
+        The raw API key to mask.
+
+    Returns
+    -------
+    str
+        Masked key string, e.g. ``"sk-1a2b3...b2c9"``.
+
+    Examples
+    --------
+    >>> mask("sk-1a2b3c4d5e6f7g8h9i0j")
+    'sk-1a2b3...9i0j'
+    """
+    if len(key) <= 7:
+        return key[:3] + "..." + key[-4:] if len(key) >= 4 else "..."
+    return key[:6] + "..." + key[-4:]
+
+
+_DOPPLER_CACHE: cachetools.TTLCache = cachetools.TTLCache(maxsize=64, ttl=3600)
+_DOPPLER_DOWNLOAD_URL = "https://api.doppler.com/v3/configs/config/secrets"
+
+
+class KeyPool:
+    """A thread-safe pool of API keys with cooldown and rotation strategies.
+
+    Manages a collection of API keys, cycling through them using a configurable
+    strategy (round-robin or least-recently-used). Keys that receive HTTP 429
+    responses can be placed on cooldown and will automatically recover after
+    the cooldown period. Permanently invalid keys can be explicitly disabled.
+
+    Parameters
+    ----------
+    keys : list[str]
+        Initial list of API key strings. At least one key is required.
+    max_retries : int, optional
+        Maximum number of retries the caller should attempt per operation.
+        Stored as ``self.max_retries`` for the caller's reference; the library
+        does not perform automatic retries. Default is 3.
+    cooldown_seconds : int, optional
+        Number of seconds a key stays in COOLDOWN after being rate-limited
+        before it becomes ACTIVE again. Default is 60.
+    strategy : str, optional
+        Rotation strategy. ``"round_robin"`` cycles through keys in insertion
+        order. ``"lru"`` selects the key with the oldest ``last_used``
+        timestamp. Default is ``"round_robin"``.
+
+    Raises
+    ------
+    ValueError
+        If *keys* is empty or ``None``.
+
+    Examples
+    --------
+    >>> pool = KeyPool(["key-a", "key-b", "key-c"], strategy="round_robin")
+    >>> pool.get_key()
+    >>> pool.mark_success(pool.get_key())
+    """
+
+    def __init__(
+        self,
+        keys: list[str] | None = None,
+        max_retries: int = 3,
+        cooldown_seconds: int = 60,
+        strategy: str = "round_robin",
+    ) -> None:
+        if not keys:
+            raise ValueError("KeyPool requires at least one key (keys must be a non-empty list).")
+
+        if strategy not in ("round_robin", "lru"):
+            raise ValueError(f"Unknown strategy '{strategy}'. Use 'round_robin' or 'lru'.")
+
+        self.max_retries: int = max_retries
+        self.cooldown_seconds: int = cooldown_seconds
+        self.strategy: str = strategy
+
+        self._records: list[_KeyRecord] = [_KeyRecord(key=k) for k in keys]
+        self._round_robin_index: int = 0
+        self._lock: threading.Lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _find_record(self, key: str) -> _KeyRecord | None:
+        """Return the ``_KeyRecord`` for *key*, or ``None`` if not found."""
+        for rec in self._records:
+            if rec.key == key:
+                return rec
+        return None
+
+    def _recover_cooldown_keys(self) -> None:
+        """Flip COOLDOWN keys whose cooldown has expired back to ACTIVE."""
+        now = time.monotonic()
+        for rec in self._records:
+            if rec.state == KeyState.COOLDOWN and rec.cooldown_until is not None and now >= rec.cooldown_until:
+                rec.state = KeyState.ACTIVE
+                rec.cooldown_until = None
+
+    def _active_records(self) -> list[_KeyRecord]:
+        """Return all currently-ACTIVE records."""
+        return [r for r in self._records if r.state == KeyState.ACTIVE]
+
+    @classmethod
+    def from_doppler(
+        cls,
+        token: str,
+        project: str,
+        config: str,
+        key_prefix: str | None = None,
+        max_retries: int = 3,
+        cooldown_seconds: int = 60,
+        strategy: str = "round_robin",
+        force_refresh: bool = False,
+    ) -> KeyPool:
+        """Create a ``KeyPool`` by fetching API keys from Doppler.
+
+        Calls the Doppler secrets-download REST endpoint and populates the
+        pool with secret values that match *key_prefix* (if given). Results
+        are cached in an in-memory, module-level ``TTLCache`` (1 hour TTL)
+        keyed by ``(project, config, key_prefix)`` so that repeated calls
+        within the same process avoid redundant network requests.
+
+        The cache is purely in-memory and empties naturally on every fresh
+        process start — it is never persisted to disk.
+
+        Parameters
+        ----------
+        token : str
+            Doppler service-token for bearer authentication
+            (e.g. ``"dp.st.YOUR_SERVICE_TOKEN"``).
+        project : str
+            Doppler project name.
+        config : str
+            Doppler config/environment name (e.g. ``"dev"``, ``"prd"``).
+        key_prefix : str | None, optional
+            If provided, only secrets whose name starts with this string are
+            included as keys. ``None`` (default) includes all secrets.
+        max_retries : int, optional
+            Passed through to the ``KeyPool`` constructor. Default is 3.
+        cooldown_seconds : int, optional
+            Passed through to the ``KeyPool`` constructor. Default is 60.
+        strategy : str, optional
+            Passed through to the ``KeyPool`` constructor.
+            Default is ``"round_robin"``.
+        force_refresh : bool, optional
+            If ``True``, bypass the cache and re-fetch from Doppler even when
+            a valid cache entry exists. Default is ``False``.
+
+        Returns
+        -------
+        KeyPool
+            A new ``KeyPool`` instance populated with the fetched keys.
+
+        Raises
+        ------
+        RuntimeError
+            If the Doppler API call fails (non-2xx status) or returns zero
+            keys — the cache is **not** populated on failure.
+
+        Examples
+        --------
+        >>> import os
+        >>> pool = KeyPool.from_doppler(
+        ...     token=os.getenv("DOPPLER_TOKEN", "dp.st.YOUR_SERVICE_TOKEN"),
+        ...     project="refactor-ai",
+        ...     config="dev",
+        ...     key_prefix="API_KEY_",
+        ... )
+        """
+        cache_key = (project, config, key_prefix)
+
+        if not force_refresh:
+            cached = _DOPPLER_CACHE.get(cache_key)
+            if cached is not None:
+                return cls(
+                    keys=list(cached),
+                    max_retries=max_retries,
+                    cooldown_seconds=cooldown_seconds,
+                    strategy=strategy,
+                )
+
+        try:
+            response = httpx.get(
+                _DOPPLER_DOWNLOAD_URL,
+                params={"project": project, "config": config},
+                headers={"Authorization": f"Bearer {token}"},
+            )
+            response.raise_for_status()
+            data = response.json()
+        except httpx.HTTPError as exc:
+            raise RuntimeError(
+                f"Doppler API request failed: {exc.__class__.__name__}"
+            ) from exc
+
+        secrets: dict[str, str] = data.get("secrets", {})
+        fetched_keys: list[str] = []
+        for name, secret_data in secrets.items():
+            if isinstance(secret_data, dict):
+                raw = secret_data.get("raw") or secret_data.get("computed", "")
+            else:
+                raw = str(secret_data)
+            if key_prefix is None or name.startswith(key_prefix):
+                fetched_keys.append(raw)
+
+        if not fetched_keys:
+            raise RuntimeError(
+                f"Doppler returned zero keys for project='{project}', "
+                f"config='{config}', key_prefix={key_prefix!r}"
+            )
+
+        _DOPPLER_CACHE[cache_key] = tuple(fetched_keys)
+
+        return cls(
+            keys=fetched_keys,
+            max_retries=max_retries,
+            cooldown_seconds=cooldown_seconds,
+            strategy=strategy,
+        )
+
+    @classmethod
+    def from_env(
+        cls,
+        suffix: str,
+        env_file: str | None = None,
+        max_retries: int = 3,
+        cooldown_seconds: int = 60,
+        strategy: str = "round_robin",
+    ) -> KeyPool:
+        """Create a ``KeyPool`` from environment variables matching a suffix.
+
+        Calls ``python-dotenv``'s ``load_dotenv()`` to load a ``.env`` file
+        (if *env_file* is given or a ``.env`` exists in the current directory),
+        then scans **all** environment variables for names ending with
+        *suffix*. The matching variable values are used as API keys.
+
+        Parameters
+        ----------
+        suffix : str
+            Environment-variable name suffix to match (case-sensitive).
+            For example, ``"GROQ_KEY"`` matches ``TSN_GROQ_KEY``,
+            ``BACKUP_GROQ_KEY``, etc.
+        env_file : str | None, optional
+            Path to a ``.env`` file to load before scanning. ``None``
+            (default) lets ``load_dotenv()`` find ``.env`` automatically.
+        max_retries : int, optional
+            Passed through to the ``KeyPool`` constructor. Default is 3.
+        cooldown_seconds : int, optional
+            Passed through to the ``KeyPool`` constructor. Default is 60.
+        strategy : str, optional
+            Passed through to the ``KeyPool`` constructor.
+            Default is ``"round_robin"``.
+
+        Returns
+        -------
+        KeyPool
+            A new ``KeyPool`` instance populated with matching env values.
+
+        Raises
+        ------
+        ValueError
+            If *suffix* is empty or ``None``.
+        RuntimeError
+            If no environment variables match *suffix*.
+
+        Examples
+        --------
+        >>> # .env contains: TSN_GROQ_KEY_1=sk-abc  TSN_GROQ_KEY_2=sk-def
+        >>> pool = KeyPool.from_env(suffix="GROQ_KEY")
+        """
+        if not suffix:
+            raise ValueError("suffix must be a non-empty string.")
+
+        load_dotenv(env_file)
+
+        import os
+
+        matched: list[str] = []
+        for name, value in os.environ.items():
+            if name.endswith(suffix) and value.strip():
+                matched.append(value.strip())
+
+        if not matched:
+            raise RuntimeError(
+                f"No environment variables ending with '{suffix}' found "
+                f"(env_file={env_file!r})."
+            )
+
+        return cls(
+            keys=matched,
+            max_retries=max_retries,
+            cooldown_seconds=cooldown_seconds,
+            strategy=strategy,
+        )
+
+    @classmethod
+    def from_json(
+        cls,
+        path: str,
+        suffix: str | None = None,
+        max_retries: int = 3,
+        cooldown_seconds: int = 60,
+        strategy: str = "round_robin",
+    ) -> KeyPool:
+        """Create a ``KeyPool`` from a JSON file.
+
+        The JSON file must contain a **flat object** whose values are the
+        API key strings. Only entries whose *key name* ends with *suffix*
+        are included (if *suffix* is ``None``, all entries are used).
+
+        Expected JSON format::
+
+            {
+                "TSN_GROQ_KEY_1": "sk-abc123",
+                "TSN_GROQ_KEY_2": "sk-def456",
+                "OTHER_SECRET":   "sk-ghi789"
+            }
+
+        Parameters
+        ----------
+        path : str
+            Path to the JSON file.
+        suffix : str | None, optional
+            If provided, only entries whose key name ends with this string
+            are included. ``None`` (default) includes all entries.
+        max_retries : int, optional
+            Passed through to the ``KeyPool`` constructor. Default is 3.
+        cooldown_seconds : int, optional
+            Passed through to the ``KeyPool`` constructor. Default is 60.
+        strategy : str, optional
+            Passed through to the ``KeyPool`` constructor.
+            Default is ``"round_robin"``.
+
+        Returns
+        -------
+        KeyPool
+            A new ``KeyPool`` instance populated with matching JSON values.
+
+        Raises
+        ------
+        FileNotFoundError
+            If *path* does not exist.
+        ValueError
+            If the file is not valid JSON or is not a flat object.
+        RuntimeError
+            If no entries match *suffix* (or the object is empty).
+
+        Examples
+        --------
+        >>> # keys.json: {"GROQ_1": "sk-abc", "GROQ_2": "sk-def", "OTHER": "sk-ghi"}
+        >>> pool = KeyPool.from_json("keys.json", suffix="GROQ")
+        """
+        import json as _json
+        import os
+
+        if not os.path.isfile(path):
+            raise FileNotFoundError(f"JSON file not found: {path}")
+
+        with open(path, "r", encoding="utf-8") as fh:
+            try:
+                data = _json.load(fh)
+            except _json.JSONDecodeError as exc:
+                raise ValueError(f"Invalid JSON in {path}: {exc}") from exc
+
+        if not isinstance(data, dict):
+            raise ValueError(
+                f"Expected a JSON object at top level in {path}, got {type(data).__name__}."
+            )
+
+        if not data:
+            raise RuntimeError(f"JSON object in {path} is empty.")
+
+        matched: list[str] = []
+        for name, value in data.items():
+            if not isinstance(value, str):
+                raise ValueError(
+                    f"All values must be strings in {path}. "
+                    f"Key '{name}' has type {type(value).__name__}."
+                )
+            if suffix is None or name.endswith(suffix):
+                if value.strip():
+                    matched.append(value.strip())
+
+        if not matched:
+            raise RuntimeError(
+                f"No entries ending with '{suffix}' found in {path}."
+            )
+
+        return cls(
+            keys=matched,
+            max_retries=max_retries,
+            cooldown_seconds=cooldown_seconds,
+            strategy=strategy,
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def add_key(self, key: str) -> None:
+        """Add a new ACTIVE key to the pool at runtime.
+
+        If the key is already present in the pool, this is a no-op.
+
+        Parameters
+        ----------
+        key : str
+            The API key string to add.
+
+        Examples
+        --------
+        >>> pool = KeyPool(["key-a"])
+        >>> pool.add_key("key-b")
+        """
+        with self._lock:
+            if self._find_record(key) is None:
+                self._records.append(_KeyRecord(key=key))
+
+    def remove_key(self, key: str) -> None:
+        """Remove a key from the pool regardless of its current state.
+
+        If the key is not in the pool, this is a no-op.
+
+        Parameters
+        ----------
+        key : str
+            The API key string to remove.
+
+        Examples
+        --------
+        >>> pool = KeyPool(["key-a", "key-b"])
+        >>> pool.remove_key("key-b")
+        """
+        with self._lock:
+            rec = self._find_record(key)
+            if rec is not None:
+                self._records.remove(rec)
+
+    def get_key(self) -> str:
+        """Return the next available ACTIVE key according to the pool's strategy.
+
+        Before selecting, any COOLDOWN key whose cooldown period has expired
+        is automatically flipped back to ACTIVE.
+
+        **Round-robin** (``strategy="round_robin"``): iterates through keys
+        in insertion order, maintaining an internal cursor that wraps around.
+
+        **LRU** (``strategy="lru"``): picks the ACTIVE key with the oldest
+        ``last_used`` timestamp and updates it to now upon selection.
+
+        Returns
+        -------
+        str
+            An ACTIVE API key.
+
+        Raises
+        ------
+        AllKeysExhaustedError
+            If no ACTIVE key exists in the pool. The message includes the
+            soonest recovery time in seconds when at least one key is in
+            COOLDOWN, otherwise it says all keys are disabled.
+
+        Examples
+        --------
+        >>> pool = KeyPool(["key-a", "key-b"])
+        >>> key = pool.get_key()
+        >>> pool.mark_success(key)
+        """
+        with self._lock:
+            self._recover_cooldown_keys()
+            active = self._active_records()
+
+            if not active:
+                cooldown_records = [r for r in self._records if r.state == KeyState.COOLDOWN]
+                if cooldown_records:
+                    now = time.monotonic()
+                    soonest = min(
+                        (r.cooldown_until - now for r in cooldown_records if r.cooldown_until is not None),
+                        default=None,
+                    )
+                    if soonest is not None and soonest > 0:
+                        raise AllKeysExhaustedError(
+                            f"No active keys available. Recovery in {soonest:.1f}s "
+                            f"({self._cooldown_summary(cooldown_records, now)})."
+                        )
+                    else:
+                        raise AllKeysExhaustedError(
+                            "No active keys available. All keys are in cooldown or disabled."
+                        )
+                raise AllKeysExhaustedError("No active keys available. All keys are disabled.")
+
+            if self.strategy == "round_robin":
+                self._round_robin_index %= len(active)
+                rec = active[self._round_robin_index]
+                self._round_robin_index += 1
+            else:  # lru
+                rec = min(active, key=lambda r: r.last_used)
+                rec.last_used = time.monotonic()
+
+        return rec.key
+
+    def handle_response(
+        self,
+        key: str,
+        status_code: int,
+        headers: dict[str, str] | None = None,
+        body: dict | str | None = None,
+    ) -> KeyState:
+        """Feed an HTTP response to the pool — it decides what to do with the key.
+
+        Introspects the status code and response body and automatically:
+
+        - On **2xx**: marks the key as successful (``mark_success``).
+        - On **429** or **413**, or when the response body contains
+          ``error.code == "rate_limit_exceeded"``: places the key on
+          COOLDOWN using ``Retry-After`` if present, otherwise the pool's
+          ``cooldown_seconds``.
+        - On **401** or **403**: permanently disables the key
+          (``mark_invalid``).
+        - On **5xx**: places the key on COOLDOWN (transient server error).
+
+        All relevant details (status code, error code, error message) are
+        stored on the key record and surfaced in ``status()``.
+
+        Parameters
+        ----------
+        key : str
+            The API key that was used for the request.
+        status_code : int
+            HTTP status code from the response.
+        headers : dict[str, str] | None, optional
+            Response headers (used to extract ``Retry-After``).
+        body : dict | str | None, optional
+            Parsed JSON body (``dict``) or raw response text (``str``).
+
+        Returns
+        -------
+        KeyState
+            The new state of the key after processing.
+
+        Examples
+        --------
+        >>> pool = KeyPool(["key-a", "key-b"])
+        >>> k = pool.get_key()
+        >>> # Successful call:
+        >>> pool.handle_response(k, 200, body={"choices": [...]})
+        <KeyState.ACTIVE: 'active'>
+        >>> # Rate-limit (Groq-style in-body):
+        >>> pool.handle_response(k, 200, body={"error": {"code": "rate_limit_exceeded", "message": "TPM limit"}})
+        <KeyState.COOLDOWN: 'cooldown'>
+        >>> # Re-raise to get a fresh key on cooldown:
+        >>> k2 = pool.get_key()
+        """
+        headers = headers or {}
+
+        # ── parse body for error details ──
+        error_code = str(status_code)
+        error_message = ""
+        if isinstance(body, dict):
+            err = body.get("error", {})
+            if isinstance(err, dict):
+                if err.get("code") == "rate_limit_exceeded":
+                    error_code = "rate_limit_exceeded"
+                error_message = err.get("message", "")
+            elif isinstance(err, str):
+                error_message = err
+        elif isinstance(body, str):
+            error_message = body[:200]
+
+        with self._lock:
+            rec = self._find_record(key)
+            if rec is None:
+                return KeyState.DISABLED  # key doesn't exist, nothing to do
+
+            rec.last_status_code = status_code
+
+            # ── 2xx success ──
+            if 200 <= status_code < 300:
+                rec.failure_count = 0
+                rec.state = KeyState.ACTIVE
+                rec.last_error_code = None
+                rec.last_error_message = None
+                return KeyState.ACTIVE
+
+            # ── rate-limit (429, 413, or rate_limit_exceeded in body) ──
+            if status_code in (429, 413) or error_code == "rate_limit_exceeded":
+                ra = headers.get("Retry-After")
+                try:
+                    retry_after = float(ra) if ra else None
+                except (ValueError, TypeError):
+                    retry_after = None
+                rec.state = KeyState.COOLDOWN
+                rec.cooldown_until = time.monotonic() + (
+                    retry_after if retry_after is not None else self.cooldown_seconds
+                )
+                rec.failure_count += 1
+                rec.last_error_code = error_code
+                rec.last_error_message = error_message
+                return KeyState.COOLDOWN
+
+            # ── auth failure (401, 403) ──
+            if status_code in (401, 403):
+                rec.state = KeyState.DISABLED
+                rec.last_error_code = error_code
+                rec.last_error_message = error_message
+                return KeyState.DISABLED
+
+            # ── server error (5xx) — transient, put on cooldown ──
+            if 500 <= status_code < 600:
+                rec.state = KeyState.COOLDOWN
+                rec.cooldown_until = time.monotonic() + self.cooldown_seconds
+                rec.failure_count += 1
+                rec.last_error_code = error_code
+                rec.last_error_message = error_message
+                return KeyState.COOLDOWN
+
+            # ── unknown status — also cooldown ──
+            rec.state = KeyState.COOLDOWN
+            rec.cooldown_until = time.monotonic() + self.cooldown_seconds
+            rec.failure_count += 1
+            rec.last_error_code = error_code
+            rec.last_error_message = error_message
+            return KeyState.COOLDOWN
+
+    def mark_rate_limited(
+        self,
+        key: str,
+        retry_after: float | None = None,
+        error_code: str | None = None,
+        error_message: str | None = None,
+    ) -> None:
+        """Mark a key as rate-limited (COOLDOWN).
+
+        The key will remain in COOLDOWN for *retry_after* seconds (or the
+        pool's ``cooldown_seconds`` if *retry_after* is ``None``). Its
+        ``failure_count`` is incremented.
+
+        Parameters
+        ----------
+        key : str
+            The API key string.
+        retry_after : float | None, optional
+            Custom cooldown duration in seconds. If ``None``, defaults to
+            ``self.cooldown_seconds``.
+        error_code : str | None, optional
+            Machine-readable code for the last rate-limit error (e.g.
+            ``"rate_limit_exceeded"``, ``"413"``). Stored and surfaced in
+            ``status()``.
+        error_message : str | None, optional
+            Human-readable description of the last rate-limit error.
+            Stored and surfaced in ``status()``.
+
+        Examples
+        --------
+        >>> pool = KeyPool(["key-a"])
+        >>> pool.mark_rate_limited("key-a", retry_after=30)
+        >>> pool.mark_rate_limited("key-a", error_code="rate_limit_exceeded",
+        ...                        error_message="TPM limit 8000 exceeded")
+        """
+        with self._lock:
+            rec = self._find_record(key)
+            if rec is None:
+                return
+            rec.state = KeyState.COOLDOWN
+            rec.cooldown_until = time.monotonic() + (retry_after if retry_after is not None else self.cooldown_seconds)
+            rec.failure_count += 1
+            rec.last_error_code = error_code
+            rec.last_error_message = error_message
+
+    def mark_invalid(
+        self,
+        key: str,
+        error_code: str | None = None,
+        error_message: str | None = None,
+    ) -> None:
+        """Permanently disable a key (DISABLED).
+
+        Disabled keys never auto-recover. Use this when a key returns an
+        authentication error (e.g. HTTP 401) rather than a rate-limit error.
+
+        Parameters
+        ----------
+        key : str
+            The API key string.
+        error_code : str | None, optional
+            Machine-readable error code (e.g. ``"401"``, ``"invalid_api_key"``).
+        error_message : str | None, optional
+            Human-readable error description.
+
+        Examples
+        --------
+        >>> pool = KeyPool(["key-a"])
+        >>> pool.mark_invalid("key-a")
+        >>> pool.mark_invalid("key-a", error_code="401", error_message="Invalid API key")
+        """
+        with self._lock:
+            rec = self._find_record(key)
+            if rec is None:
+                return
+            rec.state = KeyState.DISABLED
+            rec.last_error_code = error_code
+            rec.last_error_message = error_message
+
+    def mark_success(self, key: str) -> None:
+        """Reset a key's failure count to 0 and keep it ACTIVE.
+
+        Call this after a successful API response to indicate the key is
+        healthy and reset any transient failure tracking.
+
+        Parameters
+        ----------
+        key : str
+            The API key string.
+
+        Examples
+        --------
+        >>> pool = KeyPool(["key-a"])
+        >>> k = pool.get_key()
+        >>> pool.mark_success(k)
+        """
+        with self._lock:
+            rec = self._find_record(key)
+            if rec is None:
+                return
+            rec.failure_count = 0
+            rec.state = KeyState.ACTIVE
+            rec.last_status_code = None
+            rec.last_error_code = None
+            rec.last_error_message = None
+
+    def status(self) -> dict[str, dict]:
+        """Return a snapshot of every key's state without exposing raw keys.
+
+        Every key value in the returned dictionary is passed through ``mask()``
+        so the caller can safely log or print the result.
+
+        Returns
+        -------
+        dict[str, dict]
+            A mapping of ``{masked_key: {"state": str, "failure_count": int,
+            "cooldown_remaining": float | None, "last_status_code": int | None,
+            "last_error_code": str | None, "last_error_message": str | None}}``
+            for every key in the pool.
+
+        Examples
+        --------
+        >>> pool = KeyPool(["sk-abcdef1234567890"])
+        >>> pool.status()
+        {'sk-abc...7890': {'state': 'active', 'failure_count': 0, 'cooldown_remaining': None, 'last_status_code': None, 'last_error_code': None, 'last_error_message': None}}
+        """
+        with self._lock:
+            result: dict[str, dict] = {}
+            now = time.monotonic()
+            for rec in self._records:
+                if rec.state == KeyState.COOLDOWN and rec.cooldown_until is not None:
+                    remaining = max(0.0, rec.cooldown_until - now)
+                else:
+                    remaining = None
+                result[mask(rec.key)] = {
+                    "state": rec.state.value,
+                    "failure_count": rec.failure_count,
+                    "cooldown_remaining": round(remaining, 1) if remaining is not None else None,
+                    "last_status_code": rec.last_status_code,
+                    "last_error_code": rec.last_error_code,
+                    "last_error_message": rec.last_error_message,
+                }
+            return result
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _cooldown_summary(self, cooldown_records: list[_KeyRecord], now: float) -> str:
+        """Return a brief summary of cooldown keys for error messages."""
+        parts: list[str] = []
+        for rec in cooldown_records:
+            if rec.cooldown_until is not None:
+                parts.append(f"{mask(rec.key)} in {max(0, rec.cooldown_until - now):.1f}s")
+        return ", ".join(parts) if parts else "unknown"

open_keypool-0.2.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.5
+Name: open-keypool
+Version: 0.2.0
+Summary: Minimal Python library for pooling and rotating API keys to avoid HTTP 429 rate-limit errors.
+Author: Open KeyPool Contributors
+License: MIT License
+        
+        Copyright (c) 2026 Open KeyPool Contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api-keys,key-pool,key-rotation,rate-limiting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: cachetools>=5.3.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pdoc>=15.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# open-keypool
+
+Minimal Python library for pooling and rotating API keys to avoid HTTP 429 rate-limit errors. Provide a list of keys (or pull them from Doppler), choose a rotation strategy (round-robin or least-recently-used), and the pool handles cooldown on rate-limit responses and permanent disablement on invalid keys — all thread-safe.
+
+## Install
+
+```bash
+# From TestPyPI (until published on PyPI):
+pip install --index-url https://test.pypi.org/simple/ open-keypool
+```
+
+## Quickstart
+
+### Local keys array
+
+```python
+from open_keypool import KeyPool, AllKeysExhaustedError, KeyState
+
+pool = KeyPool(keys=["sk-key1", "sk-key2", "sk-key3"], strategy="round_robin")
+
+for attempt in range(pool.max_retries):
+    key = pool.get_key()
+    response = call_your_api(key)
+
+    # Feed the response — the pool decides success / cooldown / disable
+    new_state = pool.handle_response(
+        key, response.status_code,
+        headers=dict(response.headers),
+        body=response.json(),
+    )
+
+    if new_state == KeyState.ACTIVE:
+        break  # success
+    elif new_state == KeyState.COOLDOWN:
+        continue  # key is rate-limited, rotate to next
+    elif new_state == KeyState.DISABLED:
+        continue  # key is invalid, rotate to next
+```
+
+### Handle response auto-dispatching
+
+`pool.handle_response(key, status_code, headers, body)` introspects the HTTP response and automatically:
+
+| Status | Action |
+|---|---|
+| **2xx** | Marks success — clears errors, resets failure count |
+| **429**, **413**, or `"rate_limit_exceeded"` in body | Marks cooldown, reads `Retry-After` header |
+| **401**, **403** | Permanently disables the key |
+| **5xx** | Places on cooldown (transient) |
+
+Returns `KeyState` so you can branch on the result.
+
+### Multi-key Doppler pool with status tracking
+
+```python
+import os
+from open_keypool import KeyPool
+
+DOPPLER_TOKEN = os.getenv("DOPPLER_TOKEN", "dp.st.YOUR_SERVICE_TOKEN")
+
+pool = KeyPool.from_doppler(
+    token=DOPPLER_TOKEN,
+    project="refactor-ai",
+    config="dev",
+    key_prefix="GROQ_",
+    strategy="round_robin",
+)
+
+# Every key's state, error history, and cooldown — safely masked
+for masked_key, info in pool.status().items():
+    print(f"{masked_key}  state={info['state']}  "
+          f"http={info.get('last_status_code')}  "
+          f"err=[{info.get('last_error_code')}]  "
+          f"failures={info['failure_count']}")
+```
+
+### Load keys from `.env` file
+
+```python
+from open_keypool import KeyPool
+
+# .env contains:
+#   TSN_GROQ_KEY=sk-aaa
+#   BACKUP_GROQ_KEY=sk-bbb
+#   OTHER_SECRET=sk-ccc
+
+pool = KeyPool.from_env(suffix="GROQ_KEY")
+# Picks TSN_GROQ_KEY and BACKUP_GROQ_KEY (ends with "GROQ_KEY")
+```
+
+### Load keys from JSON file
+
+```json
+{
+    "TSN_GROQ_KEY": "sk-aaa",
+    "BACKUP_GROQ_KEY": "sk-bbb",
+    "OTHER_SECRET": "sk-ccc"
+}
+```
+
+```python
+from open_keypool import KeyPool
+
+pool = KeyPool.from_json("keys.json", suffix="GROQ_KEY")
+# Picks TSN_GROQ_KEY and BACKUP_GROQ_KEY (ends with "GROQ_KEY")
+```
+
+## Constructor parameters
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `keys` | `list[str]` | *required* | Initial API key strings (non-empty). |
+| `max_retries` | `int` | `3` | Max retry count reference for the caller's loop. |
+| `cooldown_seconds` | `int` | `60` | How long a rate-limited key stays in cooldown. |
+| `strategy` | `str` | `"round_robin"` | Rotation strategy: `"round_robin"` or `"lru"`. |
+
+## Doppler caching
+
+`KeyPool.from_doppler()` uses an in-memory TTL cache with a 1-hour expiration. On the first call within a process, keys are fetched from Doppler and cached. Subsequent calls within the same hour serve keys from memory without touching the network. After one hour (if the process is still running), the cache entry expires and the next call fetches fresh keys automatically. The cache is never persisted across process restarts — every fresh process starts with an empty cache.
+
+Pass `force_refresh=True` to bypass the cache and re-fetch immediately (useful after rotating keys in Doppler when you don't want to wait out the TTL).
+
+## Full API reference
+
+[docs/index.html](docs/index.html) — self-contained HTML page with quickstart + class/method documentation generated from docstrings.

open_keypool-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+open_keypool/__init__.py,sha256=OvAC-__PfSsvGsjHSbRGbFmOj8YEm4CSY_bZClCYN5s,1739
+open_keypool/core.py,sha256=UT7TZ3GuucTXwPxzDIVhrAe0LGp5JDFGfN3DL1X5YBc,30430
+open_keypool/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+open_keypool-0.2.0.dist-info/METADATA,sha256=Wp-fc4YiIaS0X3iiVW4aaoHia-_S5Cen5MXYgwOxbjA,6504
+open_keypool-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+open_keypool-0.2.0.dist-info/licenses/LICENSE,sha256=4AiRILGrgOBZ1vgRMbnMyi8u2OppGtw-Z7AVd-HzVkE,1082
+open_keypool-0.2.0.dist-info/RECORD,,

open_keypool-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

open_keypool-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Open KeyPool Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.