python-infrakit-dev 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

infrakit/__init__.py

@@ -0,0 +1,74 @@
+"""
+infrakit
+~~~~~~~~
+A comprehensive Python developer infrastructure toolkit.
+
+Quick imports::
+
+    # Logging
+    from infrakit import setup, get_logger
+
+    # Config
+    from infrakit import load, validate
+
+    # LLM
+    from infrakit import LLMClient
+
+    # Dependencies
+    from infrakit import deps
+
+    # Scaffolding
+    from infrakit import scaffolder
+
+    # Profiling
+    from infrakit import time
+"""
+
+from infrakit.core.logger.setup import setup, get_logger, reset
+from infrakit.core.config import (
+    load,
+    load_env,
+    validate,
+    Schema,
+    field,
+    convert_file,
+    convert_dict,
+    export_file,
+    export_dict,
+    export_string,
+)
+from infrakit import deps, scaffolder, time
+
+try:
+    from infrakit.llm import LLMClient, LLMResponse, Prompt, QuotaConfig
+    _LLM_AVAILABLE = True
+except ImportError:
+    _LLM_AVAILABLE = False
+
+__version__ = "0.1.4"
+
+__all__ = [
+    "__version__",
+    # logging
+    "setup",
+    "get_logger",
+    "reset",
+    # config
+    "load",
+    "load_env",
+    "validate",
+    "Schema",
+    "field",
+    "convert_file",
+    "convert_dict",
+    "export_file",
+    "export_dict",
+    "export_string",
+    # subpackages
+    "deps",
+    "scaffolder",
+    "time",
+]
+
+if _LLM_AVAILABLE:
+    __all__ += ["LLMClient", "LLMResponse", "Prompt", "QuotaConfig"]

infrakit/cli/__init__.py

@@ -1 +1,5 @@
-"""infrakit.cli — command-line interface for infrakit."""
+"""infrakit.cli — command-line interface for infrakit."""
+
+from infrakit.cli.main import main
+
+__all__ = ["main"]

infrakit/cli/commands/__init__.py

@@ -1 +1,19 @@
-"""infrakit.cli.commands — subcommand groups."""
+"""infrakit.cli.commands — subcommand groups."""
+
+from infrakit.cli.commands.config import config_app
+from infrakit.cli.commands.logger import logger_app
+from infrakit.cli.commands.module import module_app
+from infrakit.cli.commands.time import time_app
+from infrakit.cli.commands.deps import deps_app
+from infrakit.cli.commands.llm import app as llm_app
+from infrakit.cli.commands.init import cmd_init
+
+__all__ = [
+    "config_app",
+    "logger_app",
+    "module_app",
+    "time_app",
+    "deps_app",
+    "llm_app",
+    "cmd_init",
+]

infrakit/core/__init__.py

@@ -0,0 +1,46 @@
+"""
+infrakit.core
+~~~~~~~~~~~~~
+Core infrastructure: config management and structured logging.
+
+Quick imports::
+
+    from infrakit.core import setup, get_logger
+    from infrakit.core import load, validate
+"""
+
+from infrakit.core.logger.setup import setup, get_logger, reset
+from infrakit.core.config import (
+    load,
+    load_env,
+    cast_value,
+    detect_format,
+    validate,
+    Schema,
+    field,
+    convert_file,
+    convert_dict,
+    export_file,
+    export_dict,
+    export_string,
+)
+
+__all__ = [
+    # logger
+    "setup",
+    "get_logger",
+    "reset",
+    # config
+    "load",
+    "load_env",
+    "cast_value",
+    "detect_format",
+    "validate",
+    "Schema",
+    "field",
+    "convert_file",
+    "convert_dict",
+    "export_file",
+    "export_dict",
+    "export_string",
+]

infrakit/core/config/__init__.py

@@ -0,0 +1,71 @@
+"""
+infrakit.core.config
+~~~~~~~~~~~~~~~~~~~~~
+Configuration loading, validation, conversion, and export.
+
+Quick imports::
+
+    from infrakit.core.config import load, load_env, validate, Schema, field
+    from infrakit.core.config import convert_file, convert_dict
+    from infrakit.core.config import export_file, export_dict, export_string
+"""
+
+from infrakit.core.config.loader import (
+    load,
+    load_env,
+    cast_value,
+    cast_dict,
+    detect_format,
+    ConfigLoadError,
+    UnsupportedFormatError,
+    MissingDependencyError,
+)
+from infrakit.core.config.validator import (
+    validate,
+    Schema,
+    field,
+    FieldSpec,
+    FieldError,
+    ValidationResult,
+    ConfigValidationError,
+)
+from infrakit.core.config.converter import (
+    convert_file,
+    convert_dict,
+    ConversionError,
+    ConversionWarning,
+)
+from infrakit.core.config.exporter import (
+    export_file,
+    export_dict,
+    export_string,
+)
+
+__all__ = [
+    # loader
+    "load",
+    "load_env",
+    "cast_value",
+    "cast_dict",
+    "detect_format",
+    "ConfigLoadError",
+    "UnsupportedFormatError",
+    "MissingDependencyError",
+    # validator
+    "validate",
+    "Schema",
+    "field",
+    "FieldSpec",
+    "FieldError",
+    "ValidationResult",
+    "ConfigValidationError",
+    # converter
+    "convert_file",
+    "convert_dict",
+    "ConversionError",
+    "ConversionWarning",
+    # exporter
+    "export_file",
+    "export_dict",
+    "export_string",
+]

infrakit/llm/__init__.py

@@ -20,7 +20,7 @@ from .models import (
     QuotaConfig,
     RequestMeta,
 )
-from .providers import GeminiProvider, OpenAIProvider
+from .providers import GeminiProvider, GroqProvider, OpenAIProvider
 
 __all__ = [
     "LLMClient",
@@ -32,4 +32,5 @@ __all__ = [
     "Provider",
     "OpenAIProvider",
     "GeminiProvider",
+    "GroqProvider",
 ]

infrakit/llm/client.py

@@ -80,6 +80,7 @@ from .key_manager import KeyManager
 from .models import BatchResult, LLMResponse, Prompt, Provider, QuotaConfig, RequestMeta
 from .providers.base import BaseProvider
 from .providers.gemini import GeminiProvider
+from .providers.groq import GroqProvider
 from .providers.openai import OpenAIProvider
 from .rate_limiter import RateLimiter
 
@@ -103,6 +104,7 @@ class LLMClient:
                         {
                             "openai_keys": ["sk-key1", "sk-key2"],
                             "gemini_keys": ["AIza-key1"],
+                            "groq_keys":   ["gsk_key1"],
                         }
 
     storage_dir     Path to a folder where key state is persisted.
@@ -119,7 +121,17 @@ class LLMClient:
     meta_window     How many recent request metadata records to keep per key.
                     Default: 50.
     openai_model    Default OpenAI model.  Default: ``"gpt-4o-mini"``.
-    gemini_model    Default Gemini model.  Default: ``"gemini-1.5-flash"``.
+    gemini_model    Default Gemini model.  Default: ``"gemini-2.5-flash"``.
+    groq_model      Default Groq model.    Default: ``"llama-3.3-70b-versatile"``.
+    fallback_order  Provider priority list for automatic fallback when all keys
+                    for the primary provider are exhausted.  Example::
+
+                        fallback_order=["gemini", "groq"]
+
+                    When a ``generate()`` call fails with "all keys exhausted",
+                    the client retries each provider in *fallback_order* (skipping
+                    the already-tried primary).  Fallback only triggers on key
+                    exhaustion, not on transient errors.
     show_progress   Show tqdm progress bar during batch calls.  Default: True.
     """
 
@@ -135,9 +147,12 @@ class LLMClient:
         meta_window: int = _DEFAULT_META_WINDOW,
         openai_model: Optional[str] = None,
         gemini_model: Optional[str] = None,
+        groq_model: Optional[str] = None,
+        fallback_order: Optional[list[str]] = None,
         show_progress: bool = True,
     ) -> None:
         self._mode = mode
+        self._fallback_order: list[str] = fallback_order or []
         self._max_concurrent = max_concurrent
         self._key_retries = key_retries
         self._schema_retries = schema_retries
@@ -154,11 +169,17 @@ class LLMClient:
         # Rate limiter (RPM/TPM gating)
         self._rl = RateLimiter(self._km)
 
-        # Providers
-        self._providers: dict[str, BaseProvider] = {
-            Provider.OPENAI: OpenAIProvider(model=openai_model),
-            Provider.GEMINI: GeminiProvider(model=gemini_model),
-        }
+        # Providers — only register those whose SDK is installed
+        self._providers: dict[str, BaseProvider] = {}
+        for enum_val, cls, mdl in [
+            (Provider.OPENAI, OpenAIProvider, openai_model),
+            (Provider.GEMINI, GeminiProvider, gemini_model),
+            (Provider.GROQ,   GroqProvider,   groq_model),
+        ]:
+            try:
+                self._providers[enum_val] = cls(model=mdl)
+            except ImportError:
+                pass  # SDK not installed; skip this provider
 
     # ── public: single generate ────────────────────────────────────────────
 
@@ -178,15 +199,24 @@ class LLMClient:
         If you are inside an async function use ``await async_generate()``
         instead; that path uses the async SDK clients end-to-end.
 
-        Handles key rotation, RPM waiting, retries, and metadata recording.
+        Handles key rotation, RPM waiting, retries, metadata recording, and
+        automatic provider fallback when ``fallback_order`` is configured.
         Always returns an LLMResponse — check ``.error`` for failures.
         """
-        return self._sync_single_generate(
-            prompt=prompt,
-            response_model=response_model,
-            provider=provider,
-            **kwargs,
+        result = self._sync_single_generate(
+            prompt=prompt, response_model=response_model, provider=provider, **kwargs
         )
+        if result.error is None or not self._fallback_order:
+            return result
+        for fb_prov in self._fallback_order:
+            if fb_prov == provider or fb_prov not in self._providers:
+                continue
+            fb = self._sync_single_generate(
+                prompt=prompt, response_model=response_model, provider=fb_prov, **kwargs
+            )
+            if fb.error is None:
+                return fb
+        return result
 
     async def async_generate(
         self,
@@ -196,12 +226,20 @@ class LLMClient:
         **kwargs: Any,
     ) -> LLMResponse:
         """Async version of generate() — await this inside an async context."""
-        return await self._async_single_generate(
-            prompt=prompt,
-            response_model=response_model,
-            provider=provider,
-            **kwargs,
+        result = await self._async_single_generate(
+            prompt=prompt, response_model=response_model, provider=provider, **kwargs
         )
+        if result.error is None or not self._fallback_order:
+            return result
+        for fb_prov in self._fallback_order:
+            if fb_prov == provider or fb_prov not in self._providers:
+                continue
+            fb = await self._async_single_generate(
+                prompt=prompt, response_model=response_model, provider=fb_prov, **kwargs
+            )
+            if fb.error is None:
+                return fb
+        return result
 
     # ── public: batch generate ─────────────────────────────────────────────
 
@@ -384,6 +422,87 @@ class LLMClient:
                     )
         print(sep)
 
+    # ── public: runtime key management ────────────────────────────────────
+
+    def add_key(self, provider: str, key: str) -> None:
+        """
+        Add a new API key for *provider* at runtime.
+
+        The key is immediately available for new requests.  Adding a key
+        that is already registered is a no-op.  Thread-safe.
+
+        Parameters
+        ----------
+        provider    ``"openai"``, ``"gemini"``, or ``"groq"``.
+        key         Raw API key string.
+        """
+        self._km.add_key(provider, key)
+
+    def remove_key(self, provider: str, key_id: str) -> None:
+        """
+        Remove a key by its ``key_id`` prefix (first 8 chars).
+        No-op if not found.  Thread-safe.
+        """
+        self._km.remove_key(provider, key_id)
+
+    # ── class method: environment-variable bootstrap ───────────────────────
+
+    @classmethod
+    def from_env(
+        cls,
+        storage_dir: Optional[str | "Path"] = None,
+        quota_file: Optional[str | "Path"] = None,
+        mode: Literal["async", "threaded"] = "async",
+        max_concurrent: int = _DEFAULT_MAX_CONCURRENT,
+        key_retries: int = _DEFAULT_KEY_RETRIES,
+        schema_retries: int = _DEFAULT_SCHEMA_RETRIES,
+        meta_window: int = _DEFAULT_META_WINDOW,
+        openai_model: Optional[str] = None,
+        gemini_model: Optional[str] = None,
+        groq_model: Optional[str] = None,
+        fallback_order: Optional[list[str]] = None,
+        show_progress: bool = True,
+    ) -> "LLMClient":
+        """
+        Create an LLMClient with API keys read from environment variables.
+
+        Reads ``OPENAI_API_KEY``, ``GEMINI_API_KEY``, and ``GROQ_API_KEY``.
+        Each variable may contain a comma-separated list of keys::
+
+            OPENAI_API_KEY=sk-key1,sk-key2
+            GROQ_API_KEY=gsk-key1
+
+        Example::
+
+            client = LLMClient.from_env(fallback_order=["gemini", "groq"])
+        """
+        import os
+
+        def _split(env_var: str) -> list[str]:
+            val = os.environ.get(env_var, "").strip()
+            return [k.strip() for k in val.split(",") if k.strip()] if val else []
+
+        keys = {
+            "openai_keys": _split("OPENAI_API_KEY"),
+            "gemini_keys": _split("GEMINI_API_KEY"),
+            "groq_keys":   _split("GROQ_API_KEY"),
+        }
+        return cls(
+            keys=keys,
+            storage_dir=storage_dir,
+            quota_file=quota_file,
+            mode=mode,
+            max_concurrent=max_concurrent,
+            key_retries=key_retries,
+            schema_retries=schema_retries,
+            meta_window=meta_window,
+            openai_model=openai_model,
+            gemini_model=gemini_model,
+            groq_model=groq_model,
+            fallback_order=fallback_order,
+            show_progress=show_progress,
+        )
+
     # ── internal: async single generate ───────────────────────────────────
 
     async def _async_single_generate(
@@ -462,8 +581,8 @@ class LLMClient:
                         )
                         break  # rotate to next key/model
                     if attempt < self._key_retries:
-                        # small backoff before same-key retry
-                        await asyncio.sleep(1.0 * (attempt + 1))
+                        # exponential backoff: 1s, 2s, 4s, …
+                        await asyncio.sleep(2.0 ** attempt)
                     # else: fall through and rotate key
 
             keys_tried.add((ks.key_hash, prov_impl.model))
@@ -541,7 +660,8 @@ class LLMClient:
                         )
                         break
                     if attempt < self._key_retries:
-                        time.sleep(1.0 * (attempt + 1))
+                        # exponential backoff: 1s, 2s, 4s, …
+                        time.sleep(2.0 ** attempt)
 
             keys_tried.add((ks.key_hash, prov_impl.model))
 

infrakit/llm/key_manager.py

@@ -210,7 +210,7 @@ class KeyManager:
 
     Parameters
     ----------
-    keys            ``{"openai_keys": [...], "gemini_keys": [...]}``.
+    keys            ``{"openai_keys": [...], "gemini_keys": [...], "groq_keys": [...]}``.
     storage_dir     Folder where ``key_state.json`` is written.
                     Defaults to ``~/.infrakit/llm/``.
     quota_file      Path to a JSON quota definition file.
@@ -237,7 +237,7 @@ class KeyManager:
         self._storage_path = storage_path / _STATE_FILE
 
         # quota file: explicit arg > default location > skip
-        if quota_file is not None:
+        if quota_file is not None and str(quota_file).strip():
             self._quota_file: Optional[Path] = Path(quota_file)
         elif (DEFAULT_LLM_DIR / _QUOTA_FILE).exists():
             self._quota_file = DEFAULT_LLM_DIR / _QUOTA_FILE
@@ -252,20 +252,25 @@ class KeyManager:
         self._states: dict[str, list[KeyState]] = {
             Provider.OPENAI: [],
             Provider.GEMINI: [],
+            Provider.GROQ:   [],
         }
         self._rr_index: dict[str, dict[str, int]] = {
             # per-provider, per-model round-robin index
             Provider.OPENAI: {},
             Provider.GEMINI: {},
+            Provider.GROQ:   {},
         }
 
         provider_map = {
             "openai_keys": Provider.OPENAI,
             "gemini_keys": Provider.GEMINI,
+            "groq_keys":   Provider.GROQ,
         }
 
         for key_field, provider in provider_map.items():
             for raw_key in keys.get(key_field, []):
+                if not raw_key or not isinstance(raw_key, str):
+                    continue  # skip invalid entries
                 key_hash = hashlib.sha256(raw_key.encode()).hexdigest()
                 key_id   = raw_key[:8]
 
@@ -428,6 +433,52 @@ class KeyManager:
                 ks.model_states["__all__"] = sentinel
             self._persist()
 
+    # ── public: runtime key management ────────────────────────────────────
+
+    def add_key(self, provider: str, raw_key: str) -> None:
+        """
+        Add a new API key at runtime without re-initialising the client.
+
+        The key becomes immediately available for new requests.
+        Adding a key that is already registered is a no-op (idempotent).
+        Thread-safe.
+        """
+        import hashlib
+
+        if not raw_key or not isinstance(raw_key, str):
+            raise ValueError(
+                f"Invalid API key for {provider!r}: must be a non-empty string."
+            )
+        if provider not in self._states:
+            raise ValueError(
+                f"Unknown provider {provider!r}. "
+                f"Valid options: {list(self._states)}"
+            )
+
+        with self._lock:
+            key_hash = hashlib.sha256(raw_key.encode()).hexdigest()
+            if any(ks.key_hash == key_hash for ks in self._states[provider]):
+                return  # already registered
+            key_id = raw_key[:8]
+            ks = KeyState(provider=provider, key_id=key_id, key_hash=key_hash)
+            ks._raw_key = raw_key  # type: ignore[attr-defined]
+            self._states[provider].append(ks)
+            self._persist()
+
+    def remove_key(self, provider: str, key_id: str) -> None:
+        """
+        Remove a key by its ``key_id`` prefix (first 8 chars).
+        No-op if the key is not found.  Thread-safe.
+        """
+        with self._lock:
+            before = len(self._states.get(provider, []))
+            self._states[provider] = [
+                ks for ks in self._states.get(provider, [])
+                if ks.key_id != key_id
+            ]
+            if len(self._states[provider]) < before:
+                self._persist()
+
     # ── public: quota config ───────────────────────────────────────────────
 
     def set_quota(
@@ -553,11 +604,11 @@ class KeyManager:
         """Auto-reactivate a model if its daily reset hour has passed."""
         if ms.status != ModelStatus.INACTIVE or ms.deactivated_at is None:
             return
-        now_utc = datetime.datetime.utcnow()
+        now_utc = datetime.datetime.now(datetime.timezone.utc)
         reset_today = now_utc.replace(
             hour=ms.reset_hour_utc, minute=0, second=0, microsecond=0
         )
-        deactivated_dt = datetime.datetime.utcfromtimestamp(ms.deactivated_at)
+        deactivated_dt = datetime.datetime.fromtimestamp(ms.deactivated_at, datetime.timezone.utc)
         if deactivated_dt < reset_today <= now_utc:
             ms.status         = ModelStatus.ACTIVE
             ms.deactivated_at = None
@@ -571,11 +622,11 @@ class KeyManager:
 
     def _maybe_reset_day(self, ms: ModelState) -> None:
         """Reset daily token counter if the reset hour has passed today."""
-        now_utc = datetime.datetime.utcnow()
+        now_utc = datetime.datetime.now(datetime.timezone.utc)
         reset_today = now_utc.replace(
             hour=ms.reset_hour_utc, minute=0, second=0, microsecond=0
         )
-        day_start_dt = datetime.datetime.utcfromtimestamp(ms.day_start_epoch)
+        day_start_dt = datetime.datetime.fromtimestamp(ms.day_start_epoch, datetime.timezone.utc)
         if day_start_dt < reset_today <= now_utc:
             ms.day_token_total = 0
             ms.day_start_epoch = time.time()

infrakit/llm/models.py

@@ -19,6 +19,7 @@ from pydantic import BaseModel
 class Provider(str, Enum):
     OPENAI = "openai"
     GEMINI = "gemini"
+    GROQ   = "groq"
 
 
 class KeyStatus(str, Enum):

infrakit/llm/providers/__init__.py

@@ -1,5 +1,6 @@
 from .base import BaseProvider
 from .openai import OpenAIProvider
 from .gemini import GeminiProvider
+from .groq import GroqProvider
 
-__all__ = ["BaseProvider", "OpenAIProvider", "GeminiProvider"]
+__all__ = ["BaseProvider", "OpenAIProvider", "GeminiProvider", "GroqProvider"]