rag-core-lib 3.2.0__py3-none-any.whl

rag_core_lib/impl/settings/rag_class_types_settings.py

@@ -0,0 +1,30 @@
+"""Module that contains the settings for the class types, if multiple classes can be selected."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+from rag_core_lib.impl.llms.llm_type import LLMType
+
+
+class RAGClassTypeSettings(BaseSettings):
+    """
+    Settings class for RAG class types.
+
+    This class defines the configuration settings for RAG class types.
+    It inherits from the BaseSettings class.
+
+    Attributes
+    ----------
+    llm_type : LLMType
+        The type of language model to use.
+    """
+
+    class Config:
+        """Config class for reading Fields from env."""
+
+        env_prefix = "RAG_CLASS_TYPE_"
+        case_sensitive = False
+
+    llm_type: LLMType = Field(
+        default=LLMType.STACKIT,
+    )

rag_core_lib/impl/settings/retry_decorator_settings.py

@@ -0,0 +1,78 @@
+"""Module contains settings for the retry decorator."""
+
+from pydantic import Field, PositiveInt, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class RetryDecoratorSettings(BaseSettings):
+    """
+    Contains settings regarding the retry decorator.
+
+    Attributes
+    ----------
+    max_retries : int (> 0)
+        Total retries (not counting the first attempt).
+    retry_base_delay : float (>= 0)
+        Base delay in seconds for the first retry.
+    retry_max_delay : float (> 0)
+        Maximum delay cap for any single wait.
+    backoff_factor : float (>= 1)
+        Exponential backoff factor.
+    attempt_cap : int (>= 0)
+        Cap for exponent growth (backoff_factor ** attempt_cap).
+    jitter_min : float (>= 0)
+        Minimum jitter to add to wait times.
+    jitter_max : float (>= jitter_min)
+        Maximum jitter to add to wait times.
+    """
+
+    model_config = SettingsConfigDict(env_prefix="RETRY_DECORATOR_", case_sensitive=False)
+
+    max_retries: PositiveInt = Field(
+        default=5,
+        title="Max Retries",
+        description="Total retries, not counting the initial attempt.",
+    )
+    retry_base_delay: float = Field(
+        default=0.5,
+        ge=0,
+        title="Retry Base Delay",
+        description="Base delay in seconds for the first retry.",
+    )
+    retry_max_delay: float = Field(
+        default=600.0,
+        gt=0,
+        title="Retry Max Delay",
+        description="Maximum delay cap in seconds for any single wait.",
+    )
+    backoff_factor: float = Field(
+        default=2.0,
+        ge=1.0,
+        title="Backoff Factor",
+        description="Exponential backoff factor (>= 1).",
+    )
+    attempt_cap: int = Field(
+        default=6,
+        ge=0,
+        title="Attempt Cap",
+        description="Cap for exponent growth (backoff_factor ** attempt_cap).",
+    )
+    jitter_min: float = Field(
+        default=0.05,
+        ge=0.0,
+        title="Jitter Min (s)",
+        description="Minimum jitter in seconds.",
+    )
+    jitter_max: float = Field(
+        default=0.25,
+        ge=0.0,
+        title="Jitter Max (s)",
+        description="Maximum jitter in seconds.",
+    )
+
+    @model_validator(mode="after")
+    def _check_relations(self) -> "RetryDecoratorSettings":
+        # Ensure jitter_max >= jitter_min
+        if self.jitter_max < self.jitter_min:
+            raise ValueError("jitter_max must be >= jitter_min")
+        return self

rag_core_lib/impl/settings/stackit_embedder_settings.py

@@ -0,0 +1,36 @@
+"""Settings regarding the STACKIT embedder."""
+
+from typing import Optional
+
+from pydantic import Field, PositiveInt, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class StackitEmbedderSettings(BaseSettings):
+    """Configuration for the STACKIT embeddings endpoint."""
+
+    model_config = SettingsConfigDict(env_prefix="STACKIT_EMBEDDER_", case_sensitive=False)
+
+    model: str = Field(default="intfloat/e5-mistral-7b-instruct")
+    base_url: str = Field(
+        default="https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1",
+    )
+    api_key: str = Field(default="")
+    max_retries: Optional[PositiveInt] = Field(default=None)
+    retry_base_delay: Optional[float] = Field(default=None, ge=0)
+    retry_max_delay: Optional[float] = Field(default=None, gt=0)
+    backoff_factor: Optional[float] = Field(default=None, ge=1.0)
+    attempt_cap: Optional[int] = Field(default=None, ge=0)
+    jitter_min: Optional[float] = Field(default=None, ge=0.0)
+    jitter_max: Optional[float] = Field(default=None, ge=0.0)
+
+    @model_validator(mode="after")
+    def _check_relations(self) -> "StackitEmbedderSettings":
+        """Ensure that retry-related ranges are valid."""
+
+        if not self.jitter_min or not self.jitter_max:
+            return self
+        if self.jitter_max < self.jitter_min:
+            msg = "jitter_max must be >= jitter_min"
+            raise ValueError(msg)
+        return self

rag_core_lib/impl/settings/stackit_vllm_settings.py

@@ -0,0 +1,36 @@
+"""Module contains settings regarding the STACKIT vLLM."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class StackitVllmSettings(BaseSettings):
+    """
+    Contains settings regarding the STACKIT vLLM.
+
+    Attributes
+    ----------
+    model : str
+        The model identifier.
+    base_url : str
+        The base URL for the model serving endpoint.
+    api_key : str
+        The API key for authentication.
+    top_p : float
+        Total probability mass of tokens to consider at each step.
+    temperature : float
+        What sampling temperature to use.
+    """
+
+    class Config:
+        """Config class for reading Fields from env."""
+
+        env_prefix = "STACKIT_VLLM_"
+        case_sensitive = False
+
+    model: str = Field(default="cortecs/Llama-3.3-70B-Instruct-FP8-Dynamic")
+    base_url: str = Field(default="https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1")
+    api_key: str
+
+    top_p: float = Field(default=0.1, title="LLM Top P")
+    temperature: float = Field(default=0, title="LLM Temperature")

rag_core_lib/impl/tracers/langfuse_traced_runnable.py

@@ -0,0 +1,49 @@
+"""Module for the LangfuseTraceChain class."""
+
+from typing import Optional
+
+from langchain_core.runnables import Runnable, RunnableConfig
+from langfuse.langchain import CallbackHandler
+
+from rag_core_lib.impl.settings.langfuse_settings import LangfuseSettings
+from rag_core_lib.tracers.traced_runnable import TracedRunnable
+
+
+class LangfuseTracedRunnable(TracedRunnable):
+    """A class to trace the execution of a Runnable using Langfuse.
+
+    This class wraps an inner Runnable and adds tracing capabilities using the Langfuse tracer.
+    It allows for the configuration of the tracer through the provided settings.
+
+    Attributes
+    ----------
+    CONFIG_CALLBACK_KEY : str
+        The key used to store callbacks in the configuration.
+    """
+
+    CONFIG_CALLBACK_KEY = "callbacks"
+
+    def __init__(self, inner_chain: Runnable, settings: LangfuseSettings):
+        """
+        Initialize the LangfuseTracedChain with the given inner chain and settings.
+
+        Parameters
+        ----------
+        inner_chain : Runnable
+            The inner chain to be wrapped by this tracer.
+        settings : LangfuseSettings
+            The settings to configure the Langfuse tracer.
+        """
+        super().__init__(inner_chain)
+        self._settings = settings
+
+    def _add_tracing_callback(self, config: Optional[RunnableConfig]) -> RunnableConfig:
+        handler = CallbackHandler(
+            public_key=self._settings.public_key,
+        )
+        if not config:
+            return RunnableConfig(callbacks=[handler])
+
+        current_callbacks = config.get(self.CONFIG_CALLBACK_KEY, [])
+        config[self.CONFIG_CALLBACK_KEY] = (current_callbacks if current_callbacks else []) + [handler]
+        return config

rag_core_lib/impl/utils/async_threadsafe_semaphore.py

@@ -0,0 +1,71 @@
+"""Module containing the AsyncThreadsafeSemaphore class."""
+
+import asyncio
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from typing import Optional, Type
+
+
+class AsyncThreadsafeSemaphore:
+    """A threadsafe version of asyncio.Semaphore that can be used in async and sync contexts."""
+
+    def __init__(self, value: int = 1) -> None:
+        """
+        Initialize the AsyncThreadsafeSemaphore.
+
+        Parameters
+        ----------
+        value : int
+            The initial value for the semaphore (default 1).
+        """
+        self._semaphore = threading.Semaphore(value)
+        self._executor = ThreadPoolExecutor()
+
+    # Context manager methods for synchronous usage
+    def __enter__(self) -> "AsyncThreadsafeSemaphore":
+        """Enter the runtime context related to this object."""
+        self._acquire()
+        return self
+
+    def __exit__(self, *args: Optional[Type[BaseException]]) -> None:
+        """Exit the runtime context related to this object."""
+        self.release()
+
+    # Async context manager methods for asynchronous usage
+    async def __aenter__(self) -> "AsyncThreadsafeSemaphore":
+        """Enter the async runtime context related to this object."""
+        await self.acquire()
+        return self
+
+    async def __aexit__(self, *args: Optional[Type[BaseException]]) -> None:
+        """Exit the async runtime context related to this object."""
+        self.release()
+
+    def release(self) -> None:
+        """
+        Release a semaphore, incrementing the internal counter by one.
+
+        This method wakes up one of the threads waiting for the semaphore, if any.
+
+        Returns
+        -------
+        None
+        """
+        self._semaphore.release()
+
+    async def acquire(self) -> None:
+        """
+        Asynchronously acquires a semaphore.
+
+        This method uses the event loop to run the semaphore acquisition in an executor,
+        allowing it to be thread-safe.
+
+        Returns
+        -------
+        None
+        """
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(self._executor, self._acquire)
+
+    def _acquire(self) -> None:
+        self._semaphore.acquire()

rag_core_lib/impl/utils/retry_decorator.py

@@ -0,0 +1,211 @@
+"""Reusable exponential backoff / retry decorator for sync and async functions."""
+
+import asyncio
+import inspect
+import logging
+import random
+import time
+from functools import wraps
+from typing import Callable, Optional, ParamSpec, TypeVar
+
+from pydantic_settings import BaseSettings
+
+from rag_core_lib.impl.settings.retry_decorator_settings import RetryDecoratorSettings
+from rag_core_lib.impl.utils.utils import (
+    headers_from_exception,
+    status_code_from_exception,
+    wait_from_rate_limit_headers,
+)
+
+
+# Use ParamSpec and TypeVar for type-safe decorators
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class _RetryEngine:
+    """Internal helper to keep retry logic small in the public API function."""
+
+    def __init__(
+        self,
+        cfg: RetryDecoratorSettings,
+        exceptions: tuple[type[BaseException], ...],
+        rate_limit_exceptions: tuple[type[BaseException], ...],
+        rate_limit_statuses: tuple[int, ...],
+        rate_limit_header_names: tuple[str, ...],
+        is_rate_limited: Optional[Callable[[BaseException], bool]],
+        logger: Optional[logging.Logger],
+    ) -> None:
+        self.cfg = cfg
+        self.exceptions = exceptions
+        self.rate_limit_exceptions = rate_limit_exceptions
+        self.rate_limit_statuses = rate_limit_statuses
+        self.rate_limit_header_names = rate_limit_header_names
+        self.is_rate_limited_cb = is_rate_limited
+        self.logger = logger
+
+    def decorate(self, fn: Callable[P, R]) -> Callable[P, R]:
+        if inspect.iscoroutinefunction(fn):
+            return self._decorate_async(fn)
+        return self._decorate_sync(fn)
+
+    def _decorate_async(self, fn: Callable[P, R]) -> Callable[P, R]:
+        @wraps(fn)
+        async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            for attempt in range(self.cfg.max_retries + 1):
+                try:
+                    return await fn(*args, **kwargs)
+                except self.exceptions as exc:  # type: ignore[misc]
+                    wait_time = self._calculate_wait_time(attempt, exc)
+                    if wait_time is None:
+                        raise
+                    await asyncio.sleep(wait_time)
+            raise AssertionError("Retry loop exited unexpectedly.")
+
+        return async_wrapper
+
+    def _decorate_sync(self, fn: Callable[P, R]) -> Callable[P, R]:
+        @wraps(fn)
+        def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            for attempt in range(self.cfg.max_retries + 1):
+                try:
+                    return fn(*args, **kwargs)
+                except self.exceptions as exc:  # type: ignore[misc]
+                    wait_time = self._calculate_wait_time(attempt, exc)
+                    if wait_time is None:
+                        raise
+                    time.sleep(wait_time)
+            raise AssertionError("Retry loop exited unexpectedly.")
+
+        return sync_wrapper
+
+    def _should_rate_limited(self, exc: BaseException) -> bool:
+        if self.is_rate_limited_cb and self.is_rate_limited_cb(exc):
+            return True
+        if isinstance(exc, self.rate_limit_exceptions):
+            return True
+        status_code = status_code_from_exception(exc)
+        if status_code in self.rate_limit_statuses:
+            return True
+        msg = str(exc).lower()
+        return ("rate limit" in msg) or ("ratelimit" in msg)
+
+    def _compute_backoff_wait(self, attempt: int) -> float:
+        delay = self.cfg.retry_base_delay * (self.cfg.backoff_factor ** min(attempt, self.cfg.attempt_cap))
+        return min(delay, self.cfg.retry_max_delay)
+
+    def _with_jitter(self, seconds: float) -> float:
+        return min(
+            seconds + random.uniform(self.cfg.jitter_min, self.cfg.jitter_max),  # noqa: S311 non-crypto jitter
+            self.cfg.retry_max_delay,
+        )
+
+    def _calculate_wait_time(self, attempt: int, exc: BaseException) -> Optional[float]:
+        """Return wait seconds or None to re-raise."""
+        total_attempts = self.cfg.max_retries + 1
+        if attempt == self.cfg.max_retries:
+            if self.logger:
+                self.logger.error("Failed after %d attempts: %s", total_attempts, exc, exc_info=False)
+            return None
+
+        if self._should_rate_limited(exc):
+            headers = headers_from_exception(exc)
+            wait = wait_from_rate_limit_headers(headers, self.rate_limit_header_names)
+            if wait is None:
+                wait = self._compute_backoff_wait(attempt)
+            final_wait = self._with_jitter(wait)
+            if self.logger:
+                self.logger.warning(
+                    (
+                        "Rate limited. Remaining: req=%s tok=%s. Reset in: req=%s tok=%s. "
+                        "Retrying in %.2fs (attempt %d/%d)..."
+                    ),
+                    headers.get("x-ratelimit-remaining-requests", "?"),
+                    headers.get("x-ratelimit-remaining-tokens", "?"),
+                    headers.get("x-ratelimit-reset-requests", "?"),
+                    headers.get("x-ratelimit-reset-tokens", "?"),
+                    final_wait,
+                    attempt + 1,
+                    total_attempts,
+                )
+            return final_wait
+
+        delay = self._compute_backoff_wait(attempt)
+        if self.logger:
+            self.logger.warning(
+                "Attempt %d/%d failed: %s. Retrying in %.2fs...",
+                attempt + 1,
+                total_attempts,
+                exc,
+                delay,
+                exc_info=False,
+            )
+        return delay
+
+
+def retry_with_backoff(
+    *,
+    settings: RetryDecoratorSettings | None = None,
+    exceptions: tuple[type[BaseException], ...] = (Exception,),
+    rate_limit_exceptions: tuple[type[BaseException], ...] = (),
+    rate_limit_statuses: tuple[int, ...] = (429,),
+    rate_limit_header_names: tuple[str, ...] = (
+        "x-ratelimit-reset-requests",
+        "x-ratelimit-reset-tokens",
+    ),
+    is_rate_limited: Optional[Callable[[BaseException], bool]] = None,
+    logger: Optional[logging.Logger] = None,
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """Apply robust retry logic with exponential backoff and rate-limit awareness."""
+    cfg = settings or RetryDecoratorSettings()
+    engine = _RetryEngine(
+        cfg=cfg,
+        exceptions=exceptions,
+        rate_limit_exceptions=rate_limit_exceptions,
+        rate_limit_statuses=rate_limit_statuses,
+        rate_limit_header_names=rate_limit_header_names,
+        is_rate_limited=is_rate_limited,
+        logger=logger,
+    )
+    return engine.decorate
+
+
+def create_retry_decorator_settings(
+    ai_settings: BaseSettings, retry_decorator_settings: RetryDecoratorSettings
+) -> RetryDecoratorSettings:
+    """Create retry decorator settings based on AI and default settings.
+
+    If the corresponding field in ai_settings is not set, the value from retry_decorator_settings will be used.
+
+    Parameters
+    ----------
+    ai_settings : BaseSettings
+        Those are the AI settings, e.g. Embeddings, Summarizers etc.
+    retry_decorator_settings : RetryDecoratorSettings
+        Those are the default retry settings.
+
+    Returns
+    -------
+    RetryDecoratorSettings
+        The combined retry settings.
+    """
+    fields = [
+        "max_retries",
+        "retry_base_delay",
+        "retry_max_delay",
+        "backoff_factor",
+        "attempt_cap",
+        "jitter_min",
+        "jitter_max",
+    ]
+    settings_kwargs = {
+        field: (
+            getattr(ai_settings, field)
+            if getattr(ai_settings, field) is not None
+            else getattr(retry_decorator_settings, field)
+        )
+        for field in fields
+    }
+    if settings_kwargs["jitter_max"] < settings_kwargs["jitter_min"]:
+        raise ValueError("jitter_max must be >= jitter_min")
+    return RetryDecoratorSettings(**settings_kwargs)

rag_core_lib/impl/utils/utils.py

@@ -0,0 +1,71 @@
+import re
+from typing import Any, Iterable, Optional
+
+
+def _to_seconds(v):
+    if v is None:
+        return None
+    try:
+        s = str(v).strip().lower()
+        # Support composite durations like "1h21m55s", as well as single-unit values
+        if any(u in s for u in ("h", "m", "s")):
+            total = 0.0
+            for val, unit in re.findall(r"([0-9]+(?:\.[0-9]+)?)([hms])", s):
+                num = float(val)
+                if unit == "h":
+                    total += num * 3600
+                elif unit == "m":
+                    total += num * 60
+                else:  # "s"
+                    total += num
+            return total
+        # Fallback: plain number interpreted as seconds
+        return float(s)
+    except Exception:
+        return None
+
+
+def _normalize_dict_items(items: Iterable[Any]) -> dict[str, str]:
+    """Normalize dict items by converting keys and values to a consistent format."""
+    return {str(k).lower(): str(v).lower() for k, v in items if k is not None and v is not None}
+
+
+def _normalize_headers(raw_headers: Any) -> dict[str, str]:
+    """Return a lowercased dict[str, str] from httpx.Headers or mapping-like objects."""
+    if not raw_headers:
+        return {}
+    try:
+        if hasattr(raw_headers, "items"):
+            items = list(raw_headers.items())  # works for dict-like and httpx.Headers
+        else:
+            items = list(dict(raw_headers).items())
+    except Exception:
+        try:
+            items = list(dict(raw_headers).items())
+        except Exception:
+            items = []
+
+    return _normalize_dict_items(items)
+
+
+def status_code_from_exception(exc: BaseException) -> Optional[int]:
+    resp = getattr(exc, "response", None)
+    return getattr(resp, "status_code", None)
+
+
+def headers_from_exception(exc: BaseException) -> dict[str, str]:
+    resp = getattr(exc, "response", None)
+    raw = getattr(resp, "headers", None)
+    return _normalize_headers(raw)
+
+
+def wait_from_rate_limit_headers(
+    headers: dict[str, str],
+    header_names: Iterable[str] = ("x-ratelimit-reset-requests", "x-ratelimit-reset-tokens"),
+) -> Optional[float]:
+    candidates = []
+    for name in header_names:
+        sec = _to_seconds(headers.get(name))
+        if sec is not None:
+            candidates.append(sec)
+    return max(candidates) if candidates else None

rag_core_lib/runnables/async_runnable.py

@@ -0,0 +1,60 @@
+"""Module for the base class of asynchronous chains."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+from langchain_core.runnables import Runnable, RunnableConfig
+from langchain_core.runnables.utils import Input, Output
+
+
+class AsyncRunnable(Runnable[Input, Output], ABC):
+    """Base class for asynchronous chains."""
+
+    @abstractmethod
+    async def ainvoke(self, chain_input: Input, config: Optional[RunnableConfig] = None, **kwargs: Any) -> Output:
+        """Asynchronously invoke the chain with the given input and configuration.
+
+        Parameters
+        ----------
+        chain_input : Input
+            The input data required to asynchronously invoke the chain.
+        config : Optional[RunnableConfig], optional
+            The configuration settings for the chain invocation, by default None.
+        **kwargs : Any
+            Additional keyword arguments that may be required for the chain invocation.
+
+        Returns
+        -------
+        Output
+            The result of the chain invocation.
+        """
+
+    def invoke(self, chain_input: Input, config: Optional[RunnableConfig] = None, **kwargs: Any) -> Output:
+        """
+        Invoke the chain with the given input and configuration.
+
+            Typing indicates `Output` will be the return, but because no implementation is planned,
+            this will never be returned. This method is not implemented and will raise a not implemented error.
+
+        Notes
+        -----
+        This method should never be called. It exists only because the base class requires an implementation.
+
+        Parameters
+        ----------
+        chain_input : Input
+            The input data required to invoke the chain.
+        config : Optional[RunnableConfig], optional
+            The configuration settings for the chain invocation, by default None.
+
+        Returns
+        -------
+        Output
+            The result of the chain invocation.
+
+        Raises
+        ------
+        NotImplementedError
+            Is not implemented, so will raise not implemented error.
+        """
+        raise NotImplementedError("Please use the async implementation.")

rag_core_lib/secret_provider/secret_provider.py

@@ -0,0 +1,30 @@
+"""Interface for providing API tokens."""
+
+from abc import ABC, abstractmethod
+
+
+class SecretProvider(ABC):
+    """Interface for providing API tokens."""
+
+    @property
+    @abstractmethod
+    def provided_key(self) -> str:
+        """
+        Abstract property that should be implemented to provide a secret key.
+
+        Returns
+        -------
+        str
+            The secret key provided by the implementing class.
+        """
+
+    @abstractmethod
+    def provide_token(self) -> dict:
+        """
+        Abstract method that should be implemented to provide an API token.
+
+        Returns
+        -------
+        dict
+            A dictionary containing the API token.
+        """