kiarina-llm 1.1.1__tar.gz → 1.3.0__tar.gz

{kiarina_llm-1.1.1 → kiarina_llm-1.3.0}/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2025-10-05
+
+### Changed
+- No changes
+
+## [1.2.0] - 2025-09-25
+
+### Added
+- **Content measurement utilities**: Comprehensive utilities for measuring and managing LLM-handled content
+  - `ContentMetrics`: Tracks token count, file sizes, file counts by type, and media durations
+  - `ContentLimits`: Defines limits for different content types with feature flags
+  - `ContentScale`: Enum for content scale categories (SMALL, MEDIUM, LARGE, EXTRA_LARGE)
+  - `calculate_overflow`: Calculates overflow amounts when content exceeds defined limits
+- **Type safety**: Full type hints and Pydantic validation for all content models
+- **Feature flags**: Enable/disable specific input types (image, audio, video)
+- **Lazy loading**: Efficient module loading using `__getattr__`
+
 ## [1.1.1] - 2025-09-11
 
 ### Changed

{kiarina_llm-1.1.1 → kiarina_llm-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiarina-llm
-Version: 1.1.1
+Version: 1.3.0
 Summary: LLM utilities and context management for kiarina namespace
 Project-URL: Homepage, https://github.com/kiarina/kiarina-python
 Project-URL: Repository, https://github.com/kiarina/kiarina-python
@@ -9,11 +9,10 @@ Project-URL: Changelog, https://github.com/kiarina/kiarina-python/blob/main/pack
 Project-URL: Documentation, https://github.com/kiarina/kiarina-python/tree/main/packages/kiarina-llm#readme
 Author-email: kiarina <kiarinadawa@gmail.com>
 Maintainer-email: kiarina <kiarinadawa@gmail.com>
-License: MIT
+License-Expression: MIT
 Keywords: agent,ai,context,llm,pydantic,runner,settings
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12

{kiarina_llm-1.1.1 → kiarina_llm-1.3.0}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "kiarina-llm"
-version = "1.1.1"
+version = "1.3.0"
 description = "LLM utilities and context management for kiarina namespace"
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
 authors = [
     { name = "kiarina", email = "kiarinadawa@gmail.com" }
 ]
@@ -14,7 +14,6 @@ keywords = ["llm", "ai", "context", "pydantic", "settings", "agent", "runner"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",

kiarina_llm-1.3.0/src/kiarina/llm/content/__init__.py

@@ -0,0 +1,37 @@
+import logging
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._models.content_limits import ContentLimits
+    from ._models.content_metrics import ContentMetrics
+    from ._models.content_scale import ContentScale
+    from ._operations.calculate_overflow import calculate_overflow
+
+__all__ = [
+    # .models
+    "ContentLimits",
+    "ContentMetrics",
+    "ContentScale",
+    # .operations
+    "calculate_overflow",
+]
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+
+def __getattr__(name: str) -> object:
+    if name not in __all__:
+        raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+    module_map = {
+        # .models
+        "ContentLimits": "._models.content_limits",
+        "ContentMetrics": "._models.content_metrics",
+        "ContentScale": "._models.content_scale",
+        # .operations
+        "calculate_overflow": "._operations.calculate_overflow",
+    }
+
+    globals()[name] = getattr(import_module(module_map[name], __name__), name)
+    return globals()[name]

kiarina_llm-1.3.0/src/kiarina/llm/content/_models/content_limits.py

@@ -0,0 +1,69 @@
+from pydantic import BaseModel
+
+
+class ContentLimits(BaseModel):
+    """
+    Content Limits
+    """
+
+    token_input_limit: int = -1
+    """Maximum token count input limit (-1 indicates unlimited)"""
+
+    file_size_limit: int = -1
+    """Maximum total file size limit (in bytes; -1 indicates unlimited)"""
+
+    # --------------------------------------------------
+    # Text Files
+    # --------------------------------------------------
+
+    text_file_limit: int = -1
+    """Maximum number of text files (-1 indicates unlimited)"""
+
+    # --------------------------------------------------
+    # Image Files
+    # --------------------------------------------------
+
+    image_input_enabled: bool = True
+    """Whether image input is enabled"""
+
+    image_file_limit: int = -1
+    """Maximum number of image files (-1 indicates unlimited)"""
+
+    # --------------------------------------------------
+    # Audio Files
+    # --------------------------------------------------
+
+    audio_input_enabled: bool = True
+    """Whether audio input is enabled"""
+
+    audio_duration_limit: float = 60 * 60 * 9.5
+    """Maximum audio duration limit (in seconds; Gemini's limit is 9.5h)"""
+
+    audio_file_limit: int = -1
+    """Maximum number of audio files (-1 indicates unlimited)"""
+
+    # --------------------------------------------------
+    # Video Files
+    # --------------------------------------------------
+
+    video_input_enabled: bool = True
+    """Whether video input is enabled"""
+
+    video_duration_limit: float = 60 * 60 * 1.0
+    """Maximum video duration limit (in seconds; Gemini's limit is 1h)"""
+
+    video_file_limit: int = -1
+    """Maximum number of video files (-1 indicates unlimited)"""
+
+    # --------------------------------------------------
+    # PDF Files
+    # --------------------------------------------------
+
+    pdf_input_enabled: bool = True
+    """Whether PDF input is enabled"""
+
+    pdf_page_limit: int = 100
+    """Maximum number of PDF pages (default is 100)"""
+
+    pdf_file_limit: int = -1
+    """Maximum number of PDF files (-1 indicates unlimited)"""

kiarina_llm-1.3.0/src/kiarina/llm/content/_models/content_metrics.py

@@ -0,0 +1,115 @@
+from typing import Self
+
+from pydantic import BaseModel
+
+
+class ContentMetrics(BaseModel):
+    """
+    Content Metrics
+    """
+
+    # --------------------------------------------------
+    # Properties
+    # --------------------------------------------------
+
+    token_count: int = 0
+    """Token count"""
+
+    file_size: int = 0
+    """Total file size (bytes)"""
+
+    text_file_count: int = 0
+    """Number of text files"""
+
+    image_file_count: int = 0
+    """Number of image files"""
+
+    audio_duration: float = 0.0
+    """Audio duration (seconds)"""
+
+    audio_file_count: int = 0
+    """Number of audio files"""
+
+    video_duration: float = 0.0
+    """Video duration (seconds)"""
+
+    video_file_count: int = 0
+    """Number of video files"""
+
+    pdf_page_count: int = 0
+    """Number of PDF pages"""
+
+    pdf_file_count: int = 0
+    """Number of PDF files"""
+
+    # --------------------------------------------------
+    # Properties for Meta Information
+    # --------------------------------------------------
+
+    text_token_count: int = 0
+    """Text token count"""
+
+    image_token_count: int = 0
+    """Image token count"""
+
+    audio_token_count: int = 0
+    """Audio token count"""
+
+    video_token_count: int = 0
+    """Video token count"""
+
+    pdf_token_count: int = 0
+    """PDF token count"""
+
+    # --------------------------------------------------
+    # Methods
+    # --------------------------------------------------
+
+    def add_text_token_count(self, count: int) -> None:
+        self.text_token_count += count
+        self.token_count += count
+
+    def add_image_token_count(self, count: int) -> None:
+        self.image_token_count += count
+        self.token_count += count
+
+    def add_audio_token_count(self, count: int) -> None:
+        self.audio_token_count += count
+        self.token_count += count
+
+    def add_video_token_count(self, count: int) -> None:
+        self.video_token_count += count
+        self.token_count += count
+
+    def add_pdf_token_count(self, count: int) -> None:
+        self.pdf_token_count += count
+        self.token_count += count
+
+    # --------------------------------------------------
+    # Operators
+    # --------------------------------------------------
+
+    def __add__(self, other: Self) -> Self:
+        """
+        Add metrics
+        """
+        result = self.model_copy()
+
+        result.token_count += other.token_count
+        result.file_size += other.file_size
+        result.text_file_count += other.text_file_count
+        result.image_file_count += other.image_file_count
+        result.audio_duration += other.audio_duration
+        result.audio_file_count += other.audio_file_count
+        result.video_duration += other.video_duration
+        result.video_file_count += other.video_file_count
+        result.pdf_page_count += other.pdf_page_count
+        result.pdf_file_count += other.pdf_file_count
+
+        result.text_token_count += other.text_token_count
+        result.image_token_count += other.image_token_count
+        result.audio_token_count += other.audio_token_count
+        result.video_token_count += other.video_token_count
+        result.pdf_token_count += other.pdf_token_count
+
+        return result

kiarina_llm-1.3.0/src/kiarina/llm/content/_models/content_scale.py

@@ -0,0 +1,113 @@
+from typing import Self
+
+from pydantic import BaseModel, computed_field
+
+from .._operations.calculate_overflow import calculate_overflow
+from .content_limits import ContentLimits
+from .content_metrics import ContentMetrics
+
+
+class ContentScale(BaseModel):
+    """
+    Content Scale
+    """
+
+    limits: ContentLimits
+    """Limits"""
+
+    metrics: ContentMetrics
+    """Metrics (usage)"""
+
+    overflow: ContentMetrics
+    """Overflow amount (in metrics format)"""
+
+    # --------------------------------------------------
+    # Properties
+    # --------------------------------------------------
+
+    @computed_field  # type: ignore
+    @property
+    def token_ratio(self) -> float:
+        """
+        Token usage ratio
+        """
+        if self.limits.token_input_limit == 0:
+            return 0.0
+
+        return self.metrics.token_count / self.limits.token_input_limit
+
+    @computed_field  # type: ignore
+    @property
+    def has_overflow(self) -> bool:
+        """
+        Whether overflow has occurred
+        """
+        return self.is_overflow()
+
+    @computed_field  # type: ignore
+    @property
+    def error_message(self) -> str:
+        """
+        Error message
+        """
+        return self.get_error_message()
+
+    # --------------------------------------------------
+    # Methods
+    # --------------------------------------------------
+
+    def is_overflow(self) -> bool:
+        """
+        Whether the message has overflowed
+        """
+        return (
+            self.overflow.token_count > 0
+            or self.overflow.file_size > 0
+            or self.overflow.text_file_count > 0
+            or self.overflow.image_file_count > 0
+            or self.overflow.audio_duration > 0
+            or self.overflow.audio_file_count > 0
+            or self.overflow.video_duration > 0
+            or self.overflow.video_file_count > 0
+            or self.overflow.pdf_page_count > 0
+            or self.overflow.pdf_file_count > 0
+        )
+
+    def get_error_message(self) -> str:
+        """
+        Get error message
+        """
+        if self.overflow.file_size > 0:
+            return f"Total file size exceeds limit: {self.metrics.file_size} / {self.limits.file_size_limit} bytes"
+        elif self.overflow.pdf_file_count > 0:
+            return f"Number of PDF files exceeds limit: {self.metrics.pdf_file_count} / {self.limits.pdf_file_limit}"
+        elif self.overflow.pdf_page_count > 0:
+            return f"PDF page count exceeds limit: {self.metrics.pdf_page_count} / {self.limits.pdf_page_limit}"
+        elif self.overflow.video_file_count > 0:
+            return f"Number of video files exceeds limit: {self.metrics.video_file_count} / {self.limits.video_file_limit}"
+        elif self.overflow.video_duration > 0:
+            return f"Video duration exceeds limit: {self.metrics.video_duration}s / {self.limits.video_duration_limit}s"
+        elif self.overflow.audio_file_count > 0:
+            return f"Number of audio files exceeds limit: {self.metrics.audio_file_count} / {self.limits.audio_file_limit}"
+        elif self.overflow.audio_duration > 0:
+            return f"Audio duration exceeds limit: {self.metrics.audio_duration}s / {self.limits.audio_duration_limit}s"
+        elif self.overflow.image_file_count > 0:
+            return f"Number of image files exceeds limit: {self.metrics.image_file_count} / {self.limits.image_file_limit}"
+        elif self.overflow.text_file_count > 0:
+            return f"Number of text files exceeds limit: {self.metrics.text_file_count} / {self.limits.text_file_limit}"
+        elif self.overflow.token_count > 0:
+            return f"Token count exceeds limit: {self.metrics.token_count} / {self.limits.token_input_limit}"
+        else:
+            return "Message is valid"
+
+    # --------------------------------------------------
+    # Class Methods
+    # --------------------------------------------------
+
+    @classmethod
+    def create(cls, *, limits: ContentLimits, metrics: ContentMetrics) -> Self:
+        """
+        Create scale information from metrics and limits
+        """
+        overflow = calculate_overflow(limits=limits, metrics=metrics)
+        return cls(limits=limits, metrics=metrics, overflow=overflow)

kiarina_llm-1.3.0/src/kiarina/llm/content/_operations/calculate_overflow.py

@@ -0,0 +1,62 @@
+from .._models.content_limits import ContentLimits
+from .._models.content_metrics import ContentMetrics
+
+
+def calculate_overflow(
+    *, limits: ContentLimits, metrics: ContentMetrics
+) -> ContentMetrics:
+    """
+    Calculate overflow amount from metrics and limits
+    """
+    return ContentMetrics(
+        token_count=(
+            max(0, metrics.token_count - limits.token_input_limit)
+            if limits.token_input_limit != -1
+            else 0
+        ),
+        file_size=(
+            max(0, metrics.file_size - limits.file_size_limit)
+            if limits.file_size_limit != -1
+            else 0
+        ),
+        text_file_count=(
+            max(0, metrics.text_file_count - limits.text_file_limit)
+            if limits.text_file_limit != -1
+            else 0
+        ),
+        image_file_count=(
+            max(0, metrics.image_file_count - limits.image_file_limit)
+            if (limits.image_input_enabled and limits.image_file_limit != -1)
+            else 0
+        ),
+        audio_duration=(
+            max(0.0, metrics.audio_duration - limits.audio_duration_limit)
+            if limits.audio_input_enabled
+            else 0.0
+        ),
+        audio_file_count=(
+            max(0, metrics.audio_file_count - limits.audio_file_limit)
+            if (limits.audio_input_enabled and limits.audio_file_limit != -1)
+            else 0
+        ),
+        video_duration=(
+            max(0.0, metrics.video_duration - limits.video_duration_limit)
+            if limits.video_input_enabled
+            else 0.0
+        ),
+        video_file_count=(
+            max(0, metrics.video_file_count - limits.video_file_limit)
+            if (limits.video_input_enabled and limits.video_file_limit != -1)
+            else 0
+        ),
+        pdf_page_count=(
+            max(0, metrics.pdf_page_count - limits.pdf_page_limit)
+            if limits.pdf_input_enabled
+            else 0
+        ),
+        pdf_file_count=(
+            max(0, metrics.pdf_file_count - limits.pdf_file_limit)
+            if (limits.pdf_input_enabled and limits.pdf_file_limit != -1)
+            else 0
+        ),
+    )

kiarina_llm-1.3.0/src/kiarina/llm/run_context/__init__.py

@@ -0,0 +1,30 @@
+import logging
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._model import RunContext
+    from ._registry import create_run_context
+    from .settings import settings_manager
+
+__all__ = [
+    "create_run_context",
+    "RunContext",
+    "settings_manager",
+]
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+
+def __getattr__(name: str) -> object:
+    if name not in __all__:
+        raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+    module_map = {
+        "create_run_context": "._registry",
+        "RunContext": "._model",
+        "settings_manager": ".settings",
+    }
+
+    globals()[name] = getattr(import_module(module_map[name], __name__), name)
+    return globals()[name]