rag-core-lib 3.2.0__tar.gz

rag_core_lib-3.2.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.3
+Name: rag-core-lib
+Version: 3.2.0
+Summary: The perfect rag template
+Author: STACKIT GmbH & Co. KG
+Requires-Python: >=3.13,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: deprecated (>=1.2.18,<2.0.0)
+Requires-Dist: flashrank (>=0.2.10,<0.3.0)
+Requires-Dist: langchain (>=0.3.25,<0.4.0)
+Requires-Dist: langchain-community (==0.3.30)
+Requires-Dist: langchain-core (==0.3.77)
+Requires-Dist: langchain-openai (>=0.3.27,<0.4.0)
+Requires-Dist: langfuse (==3.6.1)
+Requires-Dist: oauthlib (>=3.2.2,<4.0.0)
+Requires-Dist: openai (>=1.77.0,<2.0.0)
+Requires-Dist: pydantic (>=2.11.4,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.2.1,<3.0.0)
+Requires-Dist: requests-oauthlib (>=2.0.0,<3.0.0)

rag_core_lib-3.2.0/pyproject.toml

@@ -0,0 +1,111 @@
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "rag-core-lib"
+version = "v3.2.0"
+description = "The perfect rag template"
+authors = ["STACKIT GmbH & Co. KG"]
+packages = [{ include = "rag_core_lib", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.13"
+langchain = "^0.3.25"
+langchain-community = "0.3.30"
+flashrank = "^0.2.10"
+pydantic-settings = "^2.2.1"
+pydantic = "^2.11.4"
+oauthlib = "^3.2.2"
+requests-oauthlib = "^2.0.0"
+langfuse = "3.6.1"
+deprecated = "^1.2.18"
+openai = "^1.77.0"
+langchain-core = "0.3.77"
+langchain-openai = "^0.3.27"
+
+
+[tool.poetry.group.dev.dependencies]
+debugpy = "^1.8.14"
+pytest = "^8.3.5"
+pytest-asyncio = "^0.26.0"
+coverage = "^7.5.4"
+flake8 = "^7.2.0"
+flake8-black = "^0.4.0"
+flake8-pyproject = "^1.2.3"
+flake8-quotes = "^3.4.0"
+flake8-return = "^1.2.0"
+flake8-annotations-complexity = "^0.1.0"
+flake8-bandit = "^4.1.1"
+flake8-bugbear = "^24.12.12"
+flake8-builtins = "^2.5.0"
+flake8-comprehensions = "^3.15.0"
+flake8-eradicate = "^1.5.0"
+flake8-expression-complexity = "^0.0.11"
+flake8-pytest-style = "^2.1.0"
+pep8-naming = "^0.15.1"
+flake8-eol = "^0.0.8"
+flake8-exceptions = "^0.0.1a0"
+flake8-simplify = "^0.22.0"
+flake8-wot = "^0.2.0"
+flake8-function-order = "^0.0.5"
+flake8-tidy-imports = "^4.10.0"
+black = "^25.1.0"
+# flake8-logging-format = "^2024.24.12"
+# flake8-docstrings = "^1.7.0"
+
+
+[tool.flake8]
+exclude= [".eggs", ".git", ".hg", ".mypy_cache", ".tox", ".venv", ".devcontainer", "venv", "_build", "buck-out", "build", "dist", "**/__init__.py"]
+statistics = true
+show-source = false
+max-complexity = 8
+max-annotations-complexity = 3
+docstring-convention = 'numpy'
+max-line-length = 120
+ignore = ["E203", "W503", "E704"]
+inline-quotes = '"'
+docstring-quotes = '"""'
+multiline-quotes = '"""'
+dictionaries = ["en_US", "python", "technical", "pandas"]
+ban-relative-imports = true
+per-file-ignores = """
+./src/rag_core/impl/prompt_templates/answer_generation_prompt.py: E501,
+./tests/*: S101,E402,
+./src/rag_core_lib/impl/llms/llm_factory.py: B009
+"""
+
+[tool.black]
+line-length = 120
+exclude = """
+/(
+     .eggs
+    | .git
+    | .hg
+    | .mypy_cache
+    | .nox
+    | .pants.d
+    | .tox
+    | .venv
+    | _build
+    | buck-out
+    | build
+    | dist
+    | node_modules
+    | venv
+)/
+"""
+
+[tool.isort]
+profile = "black"
+skip = ['.eggs', '.git', '.hg', '.mypy_cache', '.nox', '.pants.d', '.tox', '.venv', '_build', 'buck-out', 'build', 'dist', 'node_modules', 'venv']
+skip_gitignore = true
+
+[tool.pylint]
+max-line-length = 120
+
+[tool.pytest.ini_options]
+log_cli = 1
+log_cli_level = "DEBUG"
+pythonpath = "src"
+testpaths = "src/tests"

rag_core_lib-3.2.0/src/rag_core_lib/impl/data_types/content_type.py

@@ -0,0 +1,13 @@
+"""Enum describing the type of information extracted from a document."""
+
+from enum import StrEnum, unique
+
+
+@unique
+class ContentType(StrEnum):
+    """Enum describing the type of information extracted from a document."""
+
+    TEXT = "TEXT"
+    TABLE = "TABLE"
+    SUMMARY = "SUMMARY"
+    IMAGE = "IMAGE"

rag_core_lib-3.2.0/src/rag_core_lib/impl/data_types/search_request.py

@@ -0,0 +1,21 @@
+"""Module for the SearchRequest data type."""
+
+from typing import Optional
+
+from pydantic import BaseModel, StrictStr
+
+
+class SearchRequest(BaseModel):
+    """
+    Represents a search request.
+
+    Parameters
+    ----------
+    search_term : str
+        The search term to be used.
+    metadata : Optional[dict[str, str]], optional
+        Additional metadata for the search request (default None)
+    """
+
+    search_term: StrictStr
+    metadata: Optional[dict[str, str]] = None

rag_core_lib-3.2.0/src/rag_core_lib/impl/embeddings/__init__.py

@@ -0,0 +1,13 @@
+"""Embeddings helpers shared across STACKIT libraries."""
+
+from rag_core_lib.impl.embeddings.embedder import Embedder
+from rag_core_lib.impl.embeddings.embedder_type import EmbedderType
+from rag_core_lib.impl.embeddings.langchain_community_embedder import LangchainCommunityEmbedder
+from rag_core_lib.impl.embeddings.stackit_embedder import StackitEmbedder
+
+__all__ = [
+    "Embedder",
+    "EmbedderType",
+    "LangchainCommunityEmbedder",
+    "StackitEmbedder",
+]

rag_core_lib-3.2.0/src/rag_core_lib/impl/embeddings/embedder.py

@@ -0,0 +1,11 @@
+"""Module containing the Embedder abstract base class."""
+
+from abc import ABC, abstractmethod
+
+
+class Embedder(ABC):
+    """Abstract base class for an embedder."""
+
+    @abstractmethod
+    def get_embedder(self) -> "Embedder":
+        """Return an instance of the embedder itself."""

rag_core_lib-3.2.0/src/rag_core_lib/impl/embeddings/embedder_type.py

@@ -0,0 +1,12 @@
+"""Module containing the EmbedderType enumeration."""
+
+from enum import StrEnum, unique
+
+
+@unique
+class EmbedderType(StrEnum):
+    """An enumeration representing different types of embedders."""
+
+    OLLAMA = "ollama"
+    STACKIT = "stackit"
+    FAKE = "fake"

rag_core_lib-3.2.0/src/rag_core_lib/impl/embeddings/langchain_community_embedder.py

@@ -0,0 +1,34 @@
+"""Module that contains the LangchainCommunityEmbedder class."""
+
+from langchain_core.embeddings import Embeddings
+
+from rag_core_lib.impl.embeddings.embedder import Embedder
+
+
+class LangchainCommunityEmbedder(Embedder, Embeddings):
+    """A wrapper around any LangChain-provided embedder."""
+
+    def __init__(self, embedder: Embeddings):
+        """Initialise the wrapper with the provided embedder.
+
+        Parameters
+        ----------
+        embedder : Embeddings
+            The embedder instance to delegate to.
+        """
+        self._embedder = embedder
+
+    def get_embedder(self) -> "LangchainCommunityEmbedder":
+        """Return the embedder instance."""
+
+        return self
+
+    def embed_documents(self, texts: list[str]) -> list[list[float]]:
+        """Embed a list of documents using the wrapped embedder."""
+
+        return self._embedder.embed_documents(texts)
+
+    def embed_query(self, text: str) -> list[float]:
+        """Embed a single query using the wrapped embedder."""
+
+        return self._embedder.embed_query(text)

rag_core_lib-3.2.0/src/rag_core_lib/impl/embeddings/stackit_embedder.py

@@ -0,0 +1,80 @@
+"""Module that contains the StackitEmbedder class."""
+
+import logging
+
+from langchain_core.embeddings import Embeddings
+from openai import APIConnectionError, APIError, APITimeoutError, OpenAI, RateLimitError
+
+from rag_core_lib.impl.embeddings.embedder import Embedder
+from rag_core_lib.impl.settings.retry_decorator_settings import RetryDecoratorSettings
+from rag_core_lib.impl.settings.stackit_embedder_settings import StackitEmbedderSettings
+from rag_core_lib.impl.utils.retry_decorator import (
+    create_retry_decorator_settings,
+    retry_with_backoff,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class StackitEmbedder(Embedder, Embeddings):
+    """LangChain-compatible embedder for STACKIT's OpenAI-compatible service."""
+
+    def __init__(
+        self,
+        stackit_embedder_settings: StackitEmbedderSettings,
+        retry_decorator_settings: RetryDecoratorSettings,
+    ) -> None:
+        """Initialise the Stackit embedder.
+
+        Parameters
+        ----------
+        stackit_embedder_settings : StackitEmbedderSettings
+            Configuration for the STACKIT embeddings endpoint.
+        retry_decorator_settings : RetryDecoratorSettings
+            Fallback retry configuration when the STACKIT-specific overrides are missing.
+        """
+        self._client = OpenAI(
+            api_key=stackit_embedder_settings.api_key,
+            base_url=stackit_embedder_settings.base_url,
+        )
+        self._settings = stackit_embedder_settings
+        self._retry_decorator_settings = create_retry_decorator_settings(
+            stackit_embedder_settings,
+            retry_decorator_settings,
+        )
+
+    def get_embedder(self) -> "StackitEmbedder":
+        """Return the embedder instance."""
+
+        return self
+
+    def embed_documents(self, texts: list[str]) -> list[list[float]]:
+        """Embed multiple documents using the STACKIT embeddings endpoint."""
+
+        @self._retry_with_backoff_wrapper()
+        def _call(documents: list[str]) -> list[list[float]]:
+            responses = self._client.embeddings.create(
+                input=documents,
+                model=self._settings.model,
+            )
+            return [data.embedding for data in responses.data]
+
+        return _call(texts)
+
+    def embed_query(self, text: str) -> list[float]:
+        """Embed a single query using the STACKIT embeddings endpoint."""
+
+        embeddings_list = self.embed_documents([text])
+        if embeddings_list:
+            embeddings = embeddings_list[0]
+            return embeddings if embeddings else []
+        logger.warning("No embeddings found for query: %s", text)
+        return embeddings_list
+
+    def _retry_with_backoff_wrapper(self):
+        return retry_with_backoff(
+            settings=self._retry_decorator_settings,
+            exceptions=(APIError, RateLimitError, APITimeoutError, APIConnectionError),
+            rate_limit_exceptions=(RateLimitError,),
+            logger=logger,
+        )

rag_core_lib-3.2.0/src/rag_core_lib/impl/langfuse_manager/langfuse_manager.py

@@ -0,0 +1,208 @@
+"""Module for managing Langfuse prompts and Langfuse Language Models (LLMs)."""
+
+import logging
+from typing import Optional
+
+from langchain.prompts import ChatPromptTemplate
+from langchain_core.language_models.llms import LLM
+from langfuse import Langfuse
+from langfuse.api.resources.commons.errors.not_found_error import NotFoundError
+from langfuse.model import TextPromptClient
+from langchain_core.prompts import SystemMessagePromptTemplate, HumanMessagePromptTemplate
+
+logger = logging.getLogger(__name__)
+
+
+class LangfuseManager:
+    """Manage prompts using Langfuse and a Large Language Model (LLM).
+
+    Attributes
+    ----------
+    API_KEY_FILTER : str
+        A filter string used to exclude the API key from configurations.
+    """
+
+    API_KEY_FILTER: str = "api_key"
+
+    def __init__(
+        self,
+        langfuse: Langfuse,
+        managed_prompts: dict[str, ChatPromptTemplate],
+        llm: LLM,
+    ):
+        """
+        Initialize the LangfuseManager.
+
+        Parameters
+        ----------
+        langfuse : Langfuse
+            An instance of the Langfuse class.
+        managed_prompts : dict of ChatPromptTemplate
+            A dictionary where keys are strings and values are ChatPromptTemplate instances representing
+            managed prompts.
+        llm : LLM
+            An instance of the LLM class.
+        """
+        self._langfuse = langfuse
+        self._llm = llm
+        self._managed_prompts = managed_prompts
+
+    def init_prompts(self) -> None:
+        """
+        Initialize the prompts managed by the LangfuseManager.
+
+        This method iterates over the keys of the managed prompts and retrieves
+        each prompt using the `get_langfuse_prompt` method.
+
+        Returns
+        -------
+        None
+        """
+        for key in list(self._managed_prompts.keys()):
+            self.get_langfuse_prompt(key)
+
+    def get_langfuse_prompt(self, base_prompt_name: str) -> Optional[TextPromptClient]:
+        """
+        Retrieve the prompt from Langfuse Prompt Management.
+
+        This method tries to fetch the prompt from Langfuse. If not found, it creates
+        a new chat prompt from the local ChatPromptTemplate.
+
+        Parameters
+        ----------
+        base_prompt_name : str
+            The name of the base prompt to retrieve.
+
+        Returns
+        -------
+        Optional[TextPromptClient]
+            The Langfuse prompt client if found, None otherwise.
+        """
+        try:
+            langfuse_prompt = self._langfuse.get_prompt(base_prompt_name, type="chat")
+            return langfuse_prompt
+        except NotFoundError:
+            logger.info("Prompt '%s' not found in Langfuse. Creating new chat prompt.", base_prompt_name)
+
+            local_prompt = self._managed_prompts[base_prompt_name]
+            chat_messages = self._convert_chat_prompt_to_langfuse_format(local_prompt)
+
+            # Get LLM config (excluding API keys)
+            llm_configurable_configs = {
+                config.id: config.default for config in self._llm.config_specs if self.API_KEY_FILTER not in config.id
+            }
+
+            self._langfuse.create_prompt(
+                name=base_prompt_name,
+                type="chat",
+                prompt=chat_messages,
+                config=llm_configurable_configs,
+                labels=["production"],
+            )
+
+            langfuse_prompt = self._langfuse.get_prompt(base_prompt_name, type="chat")
+            return langfuse_prompt
+
+        except Exception:
+            logger.exception("Error occurred while getting prompt template from langfuse")
+            return None
+
+    def get_base_llm(self, name: str) -> LLM:
+        """
+        Get the Langfuse prompt, the configuration as well as Large Language Model (LLM).
+
+        Parameters
+        ----------
+        name : str
+            The name of the Langfuse prompt to retrieve the configuration for.
+
+        Returns
+        -------
+        LLM
+            The base Large Language Model. If the Langfuse prompt is not found,
+            returns the LLM with a fallback configuration.
+        """
+        langfuse_prompt = self.get_langfuse_prompt(name)
+        if not langfuse_prompt:
+            logger.error("Using fallback for llm")
+            return self._llm
+
+        return self._llm.with_config({"configurable": langfuse_prompt.config})
+
+    def get_base_prompt(self, name: str) -> ChatPromptTemplate:
+        """
+        Retrieve the base prompt from managed prompts, with optional Langfuse integration.
+
+        This method attempts to fetch the prompt from Langfuse. If found, it creates a
+        ChatPromptTemplate with Langfuse metadata for proper tracing integration.
+        If not found, it returns the fallback ChatPromptTemplate.
+
+        Parameters
+        ----------
+        name : str
+            The name of the prompt to retrieve.
+
+        Returns
+        -------
+        ChatPromptTemplate
+            The ChatPromptTemplate for the requested prompt, optionally with Langfuse metadata.
+        """
+        langfuse_prompt = self.get_langfuse_prompt(name)
+
+        if langfuse_prompt:
+            # For chat prompts, get_langchain_prompt() returns a list of messages
+            # We need to convert this back to ChatPromptTemplate
+            chat_messages = langfuse_prompt.get_langchain_prompt()
+
+            langchain_messages = []
+            for message in chat_messages:
+                if isinstance(message, dict):
+                    role = message.get("role")
+                    content = message.get("content", "")
+                elif isinstance(message, (list, tuple)) and len(message) >= 2:
+                    role = message[0]
+                    content = message[1] if len(message) > 1 else ""
+                else:
+                    logger.warning("Unexpected message format: %s", message)
+                    continue
+
+                if role == "system":
+                    langchain_messages.append(SystemMessagePromptTemplate.from_template(content))
+                elif role == "user":
+                    langchain_messages.append(HumanMessagePromptTemplate.from_template(content))
+
+            chat_prompt_template = ChatPromptTemplate.from_messages(langchain_messages)
+
+            chat_prompt_template.metadata = {"langfuse_prompt": langfuse_prompt}
+
+            return chat_prompt_template
+        logger.error("Could not retrieve prompt template from langfuse. Using fallback value.")
+        return self._managed_prompts[name]
+
+    def _convert_chat_prompt_to_langfuse_format(self, chat_prompt: ChatPromptTemplate) -> list[dict]:
+        """
+        Convert a ChatPromptTemplate to Langfuse chat format.
+
+        Parameters
+        ----------
+        chat_prompt : ChatPromptTemplate
+            The ChatPromptTemplate to convert.
+
+        Returns
+        -------
+        list[dict]
+            A list of message dictionaries in Langfuse format.
+        """
+        chat_messages = []
+
+        for message in chat_prompt.messages:
+            # Convert SystemMessagePromptTemplate
+            if hasattr(message, "prompt") and message.prompt.template:
+                if message.__class__.__name__ == "SystemMessagePromptTemplate":
+                    chat_messages.append({"role": "system", "content": message.prompt.template})
+                elif message.__class__.__name__ == "HumanMessagePromptTemplate":
+                    chat_messages.append({"role": "user", "content": message.prompt.template})
+                elif message.__class__.__name__ == "AIMessagePromptTemplate":
+                    chat_messages.append({"role": "assistant", "content": message.prompt.template})
+
+        return chat_messages

rag_core_lib-3.2.0/src/rag_core_lib/impl/llms/llm_factory.py

@@ -0,0 +1,88 @@
+from pydantic_settings import BaseSettings
+from langchain.chat_models import init_chat_model
+from langchain.chat_models.base import _SUPPORTED_PROVIDERS
+from langchain_core.language_models.base import BaseLanguageModel
+from langchain_core.runnables import ConfigurableField
+
+
+def extract_configurable_fields(settings: BaseSettings) -> dict[str, ConfigurableField]:
+    """
+    Extract configurable fields from the given settings.
+
+    Parameters
+    ----------
+    settings : BaseSettings
+        Pydantic settings instance containing model field metadata.
+
+    Returns
+    -------
+    dict[str, ConfigurableField]
+        Mapping from field name to ConfigurableField for fields with a title.
+
+    Notes
+    -----
+    Uses getattr() to access the class attribute 'model_fields' so as to avoid
+    instance-level deprecation warnings in Pydantic v2+ and static analysis tools.
+    """
+    fields: dict[str, ConfigurableField] = {}
+    cls = settings.__class__
+    fields_meta = getattr(cls, "model_fields")
+    for name, meta in fields_meta.items():
+        if meta.title:
+            fields[name] = ConfigurableField(id=name, name=meta.title)
+    return fields
+
+
+# Mapping of generic names to provider-specific kwarg keys
+_PROVIDER_KEY_MAP: dict[str, dict[str, str]] = {
+    "openai": {"api_key": "openai_api_key", "base_url": "openai_api_base"},
+}
+
+
+def chat_model_provider(
+    settings: BaseSettings,
+    provider: str = "openai",
+) -> BaseLanguageModel:
+    """
+    Initialize a LangChain chat model with unified settings mapping and configurable fields.
+
+    Parameters
+    ----------
+    settings : BaseSettings
+        Pydantic settings subclass containing at least 'model'.
+    provider : str, optional
+        Name of the chat model provider (default 'openai').
+
+    Returns
+    -------
+    BaseLanguageModel
+        Initialized chat model instance.
+
+    Raises
+    ------
+    ValueError
+        If 'model' is not defined in settings or if the provider is unsupported.
+    """
+    data = settings.model_dump(exclude_none=True)
+    model_name = data.pop("model", None)
+    if not model_name:
+        raise ValueError("'model' must be defined in settings")
+
+    key_map = _PROVIDER_KEY_MAP.get(provider, {})
+    for generic_key, specific_key in key_map.items():
+        if generic_key in data:
+            data[specific_key] = data.pop(generic_key)
+
+    if provider not in _SUPPORTED_PROVIDERS:
+        raise ValueError(f"Unsupported provider '{provider}'. Supported: {_SUPPORTED_PROVIDERS}")
+
+    chat = init_chat_model(
+        model=model_name,
+        model_provider=provider,
+        **data,
+    )
+    config_fields = extract_configurable_fields(settings)
+    if config_fields:
+        return chat.configurable_fields(**config_fields)
+
+    return chat

rag_core_lib-3.2.0/src/rag_core_lib/impl/llms/llm_type.py

@@ -0,0 +1,12 @@
+"""Module containing the Large Language Model (LLM) type enum class."""
+
+from enum import StrEnum, unique
+
+
+@unique
+class LLMType(StrEnum):
+    """Enum class representing different types of Large Language Models (LLMs)."""
+
+    OLLAMA = "ollama"
+    STACKIT = "stackit"
+    FAKE = "fake"

rag_core_lib-3.2.0/src/rag_core_lib/impl/settings/embedder_class_type_settings.py

@@ -0,0 +1,18 @@
+"""Settings for selecting the embedder implementation."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+from rag_core_lib.impl.embeddings.embedder_type import EmbedderType
+
+
+class EmbedderClassTypeSettings(BaseSettings):
+    """Settings controlling which embedder implementation is used."""
+
+    class Config:
+        """Configure environment integration for the settings."""
+
+        env_prefix = "EMBEDDER_CLASS_TYPE_"
+        case_sensitive = False
+
+    embedder_type: EmbedderType = Field(default=EmbedderType.STACKIT)

rag_core_lib-3.2.0/src/rag_core_lib/impl/settings/fake_embedder_settings.py

@@ -0,0 +1,16 @@
+"""Settings for the deterministic fake embedder used in tests."""
+
+from pydantic import Field, PositiveInt
+from pydantic_settings import BaseSettings
+
+
+class FakeEmbedderSettings(BaseSettings):
+    """Configuration for the fake embedder implementation."""
+
+    class Config:
+        """Configure environment integration for the settings."""
+
+        env_prefix = "FAKE_EMBEDDER_"
+        case_sensitive = False
+
+    size: PositiveInt = Field(default=768)