chllm 0.1.0__py3-none-any.whl

chllm/__init__.py

@@ -0,0 +1,39 @@
+from .builder import PromptBuilder
+from .context import ContextBuilder, ContextItem
+from .exceptions import (
+    AuthenticationError,
+    CHLLMError,
+    ContentBlockedError,
+    InvalidRequestError,
+    ParsingError,
+    QuotaExceededError,
+    RateLimitError,
+    ServiceUnavailableError,
+)
+from .masking import ContentMasker, MaskedResult
+from .metrics import TokenCounter, UsageMetrics
+from .orchestrator import AgentOrchestrator, LLMProvider, Orchestrator, RetryStrategy
+from .parser import RobustLLMParser
+
+__all__ = [
+    "AgentOrchestrator",
+    "AuthenticationError",
+    "CHLLMError",
+    "ContentBlockedError",
+    "ContentMasker",
+    "ContextBuilder",
+    "ContextItem",
+    "InvalidRequestError",
+    "LLMProvider",
+    "MaskedResult",
+    "Orchestrator",
+    "ParsingError",
+    "PromptBuilder",
+    "QuotaExceededError",
+    "RateLimitError",
+    "RetryStrategy",
+    "RobustLLMParser",
+    "ServiceUnavailableError",
+    "TokenCounter",
+    "UsageMetrics",
+]

chllm/antigravity.md

@@ -0,0 +1,30 @@
+# Манифест ИИ: chllm (Robust LLM Framework)
+
+Модуль chllm представляет собой отказоустойчивый фреймворк для взаимодействия с LLM-провайдерами, управления контекстом промптов и надежного парсинга структурированных ответов.
+
+## Назначение и Архитектура
+
+Модуль изолирует работу с нейросетевыми моделями от доменной логики приложения.
+
+### Ключевые компоненты:
+
+1. **RobustLLMParser (parser.py)**:
+   - Извлечение JSON, Markdown и очистка ответа от технического шума LLM.
+   - Восстановление поврежденного JSON и валидация схем Pydantic.
+
+2. **Orchestrator, AgentOrchestrator (orchestrator.py)**:
+   - Управление ротацией API-ключей и прокси.
+   - Стратегии повторных попыток (RetryStrategy) с экспоненциальной задержкой.
+
+3. **ContentMasker (masking.py)**:
+   - Маскирование и защитная подстановка чувствительных данных и тегов Ren'Py перед отправкой в LLM.
+
+4. **PromptBuilder, ContextBuilder (uilder.py, context.py)**:
+   - Динамическая сборка системных и пользовательских промптов с ограничением по токенам.
+
+5. **TokenCounter, UsageMetrics (metrics.py)**:
+   - Подсчет токенов и сбор статистики использования API.
+
+## Правила использования
+- При работе с ответами LLM всегда использовать RobustLLMParser.
+- Ошибки LLM обрабатывать через иерархию CHLLMError (например, RateLimitError, QuotaExceededError).

chllm/builder.py

@@ -0,0 +1,89 @@
+"""
+Компонент для генерации структурированных промптов для LLM.
+Позволяет объединять инструкции, контекст и данные в единый запрос.
+"""
+
+import json
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class PromptBuilder:
+    """Генератор промптов для работы с нейросетями."""
+
+    def __init__(self, template: str | None = None):
+        """
+        Args:
+            template: Основная системная инструкция (шаблон).
+        """
+        self._template = template or ""
+
+    def build(
+        self,
+        input_data: list[Any] | dict[str, Any] | BaseModel,
+        context: list[str] | None = None,
+        instruction: str | list[str] | None = None,
+        data_label: str = "INPUT DATA",
+    ) -> str:
+        """Собирает финальный текст промпта.
+
+        Args:
+            input_data: Данные для обработки (список, словарь или Pydantic-модель).
+            context: Список строк контекста (предыдущие события/диалоги).
+            instruction: Дополнительная инструкция (строка) или список инструкций.
+            data_label: Заголовок для блока данных в промпте.
+
+        Returns:
+            str: Сформированный текст промпта.
+        """
+        parts = []
+
+        # 1. Сбор инструкций (Системный промпт)
+        instructions = []
+        if self._template:
+            instructions.append(self._template.strip())
+
+        if instruction:
+            if isinstance(instruction, list):
+                instructions.extend([i.strip() for i in instruction if i])
+            else:
+                instructions.append(instruction.strip())
+
+        if instructions:
+            parts.append("\n".join(instructions))
+
+        # 2. Контекст
+        if context:
+            parts.append("\n--- CONTEXT ---")
+            parts.append("\n".join(context))
+
+        # 3. Данные (JSON)
+        parts.append(f"\n--- {data_label} ---")
+
+        json_data = self._serialize_data(input_data)
+        parts.append(json_data)
+
+        return "\n\n".join(parts)
+
+    @staticmethod
+    def _serialize_data(data: Any) -> str:
+        """Сериализует данные в JSON строку."""
+        # 1. Проверяем наличие метода Pydantic v2 (важно для Mock-объектов в тестах)
+        if hasattr(data, "model_dump_json") and callable(data.model_dump_json):
+            serialized = data.model_dump_json(indent=2)
+            if isinstance(serialized, str):
+                return serialized
+            # Если это Mock, который вернул другой Mock, пробуем преобразовать в строку
+            return str(serialized)
+
+        # 2. Базовая сериализация для стандартных типов (dict, list)
+        if isinstance(data, (dict, list)):
+            return json.dumps(data, indent=2, ensure_ascii=False)
+
+        # 3. Если это BaseModel (Pydantic v2)
+        if isinstance(data, BaseModel):
+            return data.model_dump_json(indent=2)
+
+        # 4. Фолбэк на строковое представление
+        return str(data)

chllm/context.py

@@ -0,0 +1,83 @@
+"""
+Модуль для управления контекстом и историей в батч-запросах к LLM.
+Реализует различные стратегии формирования предыстории для элементов.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ContextItem:
+    """Элемент данных с привязанным к нему контекстом.
+
+    Attributes:
+        data: Исходные данные элемента.
+        context: Список строк предыстории.
+    """
+
+    data: Any
+    context: list[str]
+
+
+class ContextBuilder:
+    """Универсальный строитель контекста для последовательных данных."""
+
+    def __init__(self, strategy: str = "chain"):
+        """Инициализирует строитель.
+
+        Args:
+            strategy: Стратегия формирования контекста ("chain", "full").
+        """
+        self._strategy = strategy
+
+    def build(
+        self, items: list[Any], initial_history: list[str] | None = None, formatter: Callable[[Any], str] | None = None
+    ) -> list[ContextItem]:
+        """Формирует контекст для списка элементов.
+
+        Args:
+            items: Список элементов для обработки.
+            initial_history: Начальная история (для первого элемента).
+            formatter: Функция для преобразования элемента в строку контекста
+                       для последующих элементов.
+
+        Returns:
+            Список объектов ContextItem.
+        """
+        if not items:
+            return []
+
+        # Используем стандартный строковый форматтер, если не задан кастомный
+        if formatter is None:
+            formatter = self._default_formatter
+
+        result = []
+        history = initial_history or []
+
+        if self._strategy == "chain":
+            for i, item in enumerate(items):
+                if i == 0:
+                    # Первый элемент получает всю начальную историю
+                    context_for_item = history
+                else:
+                    # Последующие получают только предыдущий элемент
+                    prev_item = items[i - 1]
+                    context_for_item = [formatter(prev_item)]
+
+                result.append(ContextItem(data=item, context=context_for_item))
+
+        elif self._strategy == "full":
+            # Стратегия "Полный контекст": каждый получает всю предыдущую историю
+            current_full_history = list(history)
+            for item in items:
+                result.append(ContextItem(data=item, context=list(current_full_history)))
+                current_full_history.append(formatter(item))
+
+        return result
+
+    @staticmethod
+    def _default_formatter(item: Any) -> str:
+        """Стандартный форматтер: преобразует данные в строку."""
+        return str(item)

chllm/exceptions/__init__.py

@@ -0,0 +1,25 @@
+"""Модуль с определениями исключений библиотеки chllm.
+
+Обеспечивает единую иерархию ошибок для различных LLM провайдеров.
+"""
+
+from .base import CHLLMError
+from .parsing import InvalidRequestError, ParsingError
+from .provider import (
+    AuthenticationError,
+    ContentBlockedError,
+    QuotaExceededError,
+    RateLimitError,
+    ServiceUnavailableError,
+)
+
+__all__ = [
+    "AuthenticationError",
+    "CHLLMError",
+    "ContentBlockedError",
+    "InvalidRequestError",
+    "ParsingError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+]

chllm/exceptions/base.py

@@ -0,0 +1,5 @@
+"""Базовые исключения для библиотеки chllm."""
+
+
+class CHLLMError(Exception):
+    """Базовый класс для всех исключений библиотеки chllm."""

chllm/exceptions/parsing.py

@@ -0,0 +1,11 @@
+"""Исключения при валидации запросов и разборе ответов LLM."""
+
+from .base import CHLLMError
+
+
+class InvalidRequestError(CHLLMError):
+    """Ошибка в структуре запроса или параметрах."""
+
+
+class ParsingError(CHLLMError):
+    """Ошибка при разборе ответа от LLM."""

chllm/exceptions/provider.py

@@ -0,0 +1,34 @@
+"""Исключения, связанные с вызовами и квотами LLM-провайдеров."""
+
+from .base import CHLLMError
+
+
+class RateLimitError(CHLLMError):
+    """Превышен лимит запросов (RPM/TPM).
+
+    Обычно это временная ошибка, которую можно повторить через паузу.
+    """
+
+    def __init__(self, message: str, retry_delay: float = 60.0) -> None:
+        super().__init__(message)
+        self.retry_delay: float = retry_delay
+        "Задержка в секундах перед следующей попыткой"
+
+
+class QuotaExceededError(CHLLMError):
+    """Исчерпана квота (обычно дневной лимит или баланс аккаунта).
+
+    Требует вмешательства пользователя или смены ключа.
+    """
+
+
+class ServiceUnavailableError(CHLLMError):
+    """Сервер LLM временно недоступен или перегружен (Error 503/504)."""
+
+
+class AuthenticationError(CHLLMError):
+    """Ошибка аутентификации (неверный API ключ)."""
+
+
+class ContentBlockedError(CHLLMError):
+    """Запрос или ответ заблокирован фильтрами безопасности провайдера."""

chllm/masking.py

@@ -0,0 +1,119 @@
+"""
+Модуль для маскирования (защиты) частей текста от изменений со стороны LLM.
+Используется для защиты переменных, тегов и специальных символов.
+"""
+
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass
+class MaskedResult:
+    """Результат операции маскирования.
+
+    Attributes:
+        masked_text: Текст, в котором целевые части заменены на плейсхолдеры.
+        mapping: Словарь соответствия плейсхолдеров оригинальным значениям.
+    """
+
+    masked_text: str
+    mapping: dict[str, str] = field(default_factory=dict)
+
+
+class ContentMasker:
+    """Универсальный компонент для маскирования текста на основе регулярных выражений."""
+
+    def __init__(
+        self,
+        patterns: list[str] | None = None,
+        placeholder_prefix: str = "VAR",
+        placeholder_template: str = "[[[{prefix}_{index}]]]",
+    ):
+        """Инициализирует маскер.
+
+        Args:
+            patterns: Список регулярных выражений для поиска защищаемых частей.
+            placeholder_prefix: Префикс для плейсхолдеров (напр. "VAR", "TAG").
+            placeholder_template: Шаблон формирования плейсхолдера.
+        """
+        self._patterns = patterns or []
+        self._prefix = placeholder_prefix
+        self._template = placeholder_template
+
+    def mask(
+        self,
+        text: str,
+        extra_patterns: list[str] | None = None,
+        excluded_values: set[str] | list[str] | None = None,
+    ) -> MaskedResult:
+        """Маскирует все вхождения паттернов в тексте.
+
+        Args:
+            text: Исходный текст.
+            extra_patterns: Дополнительные паттерны только для этого вызова.
+            excluded_values: Набор значений/паттернов, которые не должны маскироваться.
+
+        Returns:
+            Объект MaskedResult с результатом и картой маскировки.
+        """
+        if not text:
+            return MaskedResult(masked_text=text)
+
+        all_patterns = self._patterns + (extra_patterns or [])
+        if not all_patterns:
+            return MaskedResult(masked_text=text)
+
+        exclude_set = set(excluded_values or [])
+        mapping: dict[str, str] = {}
+        masked_text = text
+
+        # Объединяем паттерны в одно регулярное выражение для поиска всех вхождений сразу.
+        # Сортируем паттерны по длине в обратном порядке, чтобы длинные вхождения
+        # (напр. \\n) имели приоритет над короткими (напр. \n).
+        sorted_patterns = sorted(all_patterns, key=len, reverse=True)
+        combined_regex = re.compile("|".join(f"({p})" for p in sorted_patterns))
+
+        def replace_match(match: re.Match) -> str:
+            # Извлекаем реально совпавшую строку (первая не-None группа)
+            original_value = match.group(0)
+
+            # Если значение находится в списке исключений, оставляем его без маскировки
+            if original_value in exclude_set:
+                return original_value
+
+            # Проверяем, не маскировали ли мы это значение ранее
+            # (для экономии индексов и единообразия)
+            for p, v in mapping.items():
+                if v == original_value:
+                    return p
+
+            # Создаем новый плейсхолдер
+            index = len(mapping)
+            placeholder = self._template.format(prefix=self._prefix, index=index)
+            mapping[placeholder] = original_value
+            return placeholder
+
+        # Выполняем замену всех найденных вхождений
+        masked_text = combined_regex.sub(replace_match, masked_text)
+
+        return MaskedResult(masked_text=masked_text, mapping=mapping)
+
+    def demask(self, masked_text: str, mapping: dict[str, str]) -> str:
+        """Восстанавливает оригинальный текст из маскированного.
+
+        Args:
+            masked_text: Текст с плейсхолдерами.
+            mapping: Карта маскировки (из MaskedResult).
+
+        Returns:
+            Восстановленный текст.
+        """
+        if not masked_text or not mapping:
+            return masked_text
+
+        demasked_text = masked_text
+        # Заменяем в обратном порядке (плейсхолдеры на оригиналы)
+        for placeholder, original_value in mapping.items():
+            demasked_text = demasked_text.replace(placeholder, original_value)
+
+        return demasked_text

chllm/metrics.py

@@ -0,0 +1,122 @@
+"""
+Модуль для работы с метриками и подсчета токенов в запросах к LLM.
+"""
+
+import json
+import math
+from typing import Any
+
+from pydantic import BaseModel, Field, computed_field
+
+
+class UsageMetrics(BaseModel):
+    """Модель для хранения данных об использовании токенов.
+
+    Attributes:
+        prompt_tokens: Количество токенов в запросе.
+        candidates_tokens: Количество токенов в ответе.
+    """
+
+    prompt_tokens: int = Field(default=0, ge=0)
+    candidates_tokens: int = Field(default=0, ge=0)
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def total_tokens(self) -> int:
+        """Вычисляет общую сумму токенов (вычисляемое поле)."""
+        return self.prompt_tokens + self.candidates_tokens
+
+
+class TokenCounter:
+    """Универсальный калькулятор для оценки количества токенов.
+
+    Поддерживает различные стратегии подсчета: от простой эвристики
+    до использования библиотек-токенизаторов.
+    """
+
+    def __init__(
+        self, strategy: str = "heuristic", model: str | None = None, chars_per_token: dict[str, float] | None = None
+    ):
+        """Инициализирует счетчик.
+
+        Args:
+            strategy: Стратегия подсчета ("heuristic", "tiktoken").
+            model: Имя модели для точного подбора токенизатора.
+            chars_per_token: Кастомные коэффициенты символов на токен.
+        """
+        self._strategy = strategy
+        self._model = model
+
+        # Константы по умолчанию (символов на токен)
+        default_ratios = {"en": 2.5, "ru": 2.5, "default": 3.5}
+
+        # Объединяем дефолты с пользовательскими настройками
+        self._chars_per_token = default_ratios
+        if chars_per_token:
+            self._chars_per_token.update(chars_per_token)
+
+    def count(self, data: Any, language: str | None = None) -> int:
+        """Подсчитывает или оценивает количество токенов в данных.
+
+        Args:
+            data: Текст, словарь или список данных для подсчета.
+            language: Код языка. Если None, используется коэффициент 'default'.
+
+        Returns:
+            Оценочное или точное количество токенов.
+        """
+        if data is None:
+            return 0
+
+        # Превращаем данные в строку для оценки
+        text = self._to_string(data)
+
+        if self._strategy == "heuristic":
+            # Если язык не указан, используем 'default'
+            return self._heuristic_count(text, language or "default")
+
+        # TODO: Реализовать интеграцию с tiktoken при необходимости
+        return self._heuristic_count(text, language or "default")
+
+    def estimate_completion_tokens(
+        self, items: list[str], scaling_factor: float = 1.2, per_item_overhead_chars: int = 50, language: str = "ru"
+    ) -> int:
+        """Оценивает примерное количество токенов в будущем ответе (Completion) ИИ.
+
+        Полезно для планирования лимитов и логирования ожидаемой нагрузки.
+
+        Args:
+            items: Список исходных строк (элементов), которые будут обработаны.
+            scaling_factor: Коэффициент изменения объема текста (1.2 для перевода, 0.5 для суммаризации).
+            per_item_overhead_chars: Технический оверхед на один элемент (структура JSON).
+            language: Ожидаемый язык ответа.
+
+        Returns:
+            Приблизительное количество токенов в ответе.
+        """
+        if not items:
+            return 0
+
+        total_chars: float = 0.0
+        for text in items:
+            # Считаем длину результата + оверхед
+            item_len = len(text) * scaling_factor
+            total_chars += item_len + per_item_overhead_chars
+
+        return self.count(" " * int(total_chars), language=language)
+
+    def _heuristic_count(self, text: str, language: str) -> int:
+        """Оценивает количество токенов по количеству символов."""
+        chars_per_token = self._chars_per_token.get(language, self._chars_per_token["default"])
+        if chars_per_token <= 0:
+            return 0
+        return math.ceil(len(text) / chars_per_token)
+
+    @staticmethod
+    def _to_string(data: Any) -> str:
+        """Приводит любые входные данные к строковому виду."""
+        if isinstance(data, str):
+            return data
+        if isinstance(data, (dict, list)):
+            return json.dumps(data, ensure_ascii=False)
+        return str(data)