lionagi 0.13.2__py3-none-any.whl → 0.13.3__py3-none-any.whl

lionagi/traits/composer.py

@@ -1,343 +0,0 @@
-"""
-TraitComposer - Algebraic trait composition with LRU caching.
-
-This module provides the TraitComposer class that enables algebraic composition
-of traits with + and & operators, backed by LRU caching to achieve the
-research target of <10μs model generation.
-
-Performance characteristics:
-- LRU cache with configurable size (default: 512 entries)
-- <10μs model generation target (research validated)
-- Algebraic composition operations (union, intersection)
-- Thread-safe composition with proper dependency resolution
-"""
-
-from __future__ import annotations
-
-import functools
-import threading
-import time
-from dataclasses import dataclass, field
-from typing import Any, ClassVar
-
-from .base import Trait
-from .registry import get_global_registry
-
-__all__ = ["CompositionError", "TraitComposer", "TraitComposition"]
-
-
-class CompositionError(Exception):
-    """Raised when trait composition fails due to conflicts or missing dependencies."""
-
-    pass
-
-
-@dataclass(frozen=True, slots=True)
-class TraitComposition:
-    """
-    Immutable representation of a trait composition.
-
-    Supports algebraic operations and caching for fast model generation.
-    """
-
-    traits: frozenset[Trait]
-    dependencies: frozenset[Trait] = field(default_factory=frozenset)
-    composition_id: str = field(default="")
-
-    def __post_init__(self) -> None:
-        """Calculate composition ID and dependencies."""
-        if not self.composition_id:
-            # Generate deterministic ID from sorted trait names
-            sorted_names = sorted(trait.name for trait in self.traits)
-            object.__setattr__(self, "composition_id", "+".join(sorted_names))
-
-        if not self.dependencies:
-            # Calculate all dependencies
-            registry = get_global_registry()
-            all_deps: set[Trait] = set()
-
-            for trait in self.traits:
-                trait_def = registry.get_trait_definition(trait)
-                if trait_def:
-                    all_deps.update(trait_def.dependencies)
-
-            object.__setattr__(self, "dependencies", frozenset(all_deps))
-
-    def __add__(self, other: TraitComposition | Trait) -> TraitComposition:
-        """Union composition (A + B contains traits from both A and B)."""
-        if isinstance(other, Trait):
-            other = TraitComposition(traits=frozenset([other]))
-
-        return TraitComposition(traits=self.traits | other.traits)
-
-    def __and__(self, other: TraitComposition | Trait) -> TraitComposition:
-        """Intersection composition (A & B contains only common traits)."""
-        if isinstance(other, Trait):
-            other = TraitComposition(traits=frozenset([other]))
-
-        return TraitComposition(traits=self.traits & other.traits)
-
-    def __or__(self, other: TraitComposition | Trait) -> TraitComposition:
-        """Alias for union (same as +)."""
-        return self.__add__(other)
-
-    def __hash__(self) -> int:  # type: ignore[explicit-override]
-        """Hash based on trait set for caching."""
-        return hash(self.traits)
-
-    def __repr__(self) -> str:  # type: ignore[explicit-override]
-        """String representation for debugging."""
-        trait_names = sorted(trait.name for trait in self.traits)
-        return f"TraitComposition({'+'.join(trait_names)})"
-
-    def is_valid(self) -> bool:
-        """Check if all dependencies are satisfied."""
-        missing = self.dependencies - self.traits
-        return len(missing) == 0
-
-    def get_missing_dependencies(self) -> frozenset[Trait]:
-        """Get traits that are required but missing."""
-        return self.dependencies - self.traits
-
-    def with_dependencies(self) -> TraitComposition:
-        """Return a new composition that includes all dependencies."""
-        return TraitComposition(traits=self.traits | self.dependencies)
-
-
-class TraitComposer:
-    """
-    High-performance trait composer with LRU caching.
-
-    Provides algebraic trait composition with caching to achieve <10μs
-    model generation as validated in research.
-    """
-
-    _instance: ClassVar[TraitComposer | None] = None
-    _lock: ClassVar[threading.RLock] = threading.RLock()
-    _compose_lock: ClassVar[threading.Lock] = (
-        threading.Lock()
-    )  # Guard for LRU cache miss path
-
-    # Initialize class variables
-    _protocol_cache: ClassVar[dict[Trait, type[Any]]] = {}
-    _validated_compositions: ClassVar[set[frozenset[Trait]]] = set()
-
-    def __init__(self, cache_size: int = 512) -> None:
-        """Initialize composer with LRU cache."""
-        self._cache_size = cache_size
-        self._composition_cache: dict[frozenset[Trait], type[Any]] = {}
-        self._cache_lock = threading.RLock()
-        self._cache_hits = 0
-        self._cache_misses = 0
-        self._generation_count = 0
-
-    @classmethod
-    def get_instance(cls, cache_size: int = 512) -> TraitComposer:
-        """Get singleton composer instance."""
-        if cls._instance is None:
-            with cls._lock:
-                if cls._instance is None:
-                    cls._instance = cls(cache_size)
-        return cls._instance
-
-    @classmethod
-    def reset(cls) -> None:
-        """Reset singleton for testing."""
-        with cls._lock:
-            if cls._instance is not None:
-                # Clear the LRU cache before resetting instance
-                cls._instance.clear_cache()
-                cls._protocol_cache.clear()
-                cls._validated_compositions.clear()
-            cls._instance = None
-
-    def compose(self, *traits: Trait | TraitComposition) -> TraitComposition:
-        """Compose multiple traits into a single composition."""
-        all_traits = set()
-
-        for trait in traits:
-            if isinstance(trait, Trait):
-                all_traits.add(trait)
-            elif isinstance(trait, TraitComposition):
-                all_traits.update(trait.traits)
-            else:
-                raise CompositionError(f"Invalid trait type: {type(trait)}")
-
-        return TraitComposition(traits=frozenset(all_traits))
-
-    # Pre-built empty mixin for performance
-    _EMPTY_MIXIN = type("EmptyMixin", (), {"__slots__": ()})
-
-    @functools.lru_cache(maxsize=512)  # noqa: B019
-    def _generate_model_cached(
-        self, trait_tuple: tuple[Trait, ...]
-    ) -> type[Any]:
-        """Generate model class with LRU caching (internal method)."""
-        # Only lock for the actual composition logic, not the entire method
-        with TraitComposer._compose_lock:
-            traits = frozenset(trait_tuple)
-
-            # Performance optimization 1: Skip validation if previously validated
-            composition = TraitComposition(traits=traits)
-            if traits not in TraitComposer._validated_compositions:
-                if not composition.is_valid():
-                    missing = composition.get_missing_dependencies()
-                    raise CompositionError(
-                        f"Missing dependencies: {[t.name for t in missing]}"
-                    )
-                TraitComposer._validated_compositions.add(traits)
-
-            # Generate unique class name with hash suffix to avoid collisions
-            sorted_names = sorted(trait.name for trait in traits)
-            # Use hash of the frozenset to ensure uniqueness even with different trait orders
-            trait_hash = abs(hash(traits)) % 10000  # 4-digit hash suffix
-            class_name = (
-                f"Generated{''.join(sorted_names)}Model_{trait_hash:04d}"
-            )
-
-            # Performance optimization 2: Cache protocol lookups
-            registry = get_global_registry()
-            protocol_types = []
-
-            for trait in traits:
-                # Check cached protocols first
-                if trait not in TraitComposer._protocol_cache:
-                    trait_def = registry.get_trait_definition(trait)
-                    if trait_def and trait_def.protocol_type:
-                        TraitComposer._protocol_cache[trait] = (
-                            trait_def.protocol_type
-                        )
-
-                protocol_type = TraitComposer._protocol_cache.get(trait)
-                if protocol_type:
-                    protocol_types.append(protocol_type)
-
-            if not protocol_types:
-                raise CompositionError(
-                    f"No protocol types found for traits: {sorted_names}"
-                )
-
-            # Performance optimization 3: Use pre-built empty mixin if only one protocol
-            bases: tuple[type[Any], ...]
-            if len(protocol_types) == 1:
-                # Single inheritance is faster
-                bases = (protocol_types[0], self._EMPTY_MIXIN)
-            else:
-                bases = tuple(protocol_types)
-
-            # Create class with optimized attributes
-            model_class = type(
-                class_name,
-                bases,
-                {
-                    "__traits__": traits,
-                    "__composition__": composition,
-                    "__module__": "lionagi.traits.generated",
-                    "__slots__": (),  # Prevent __dict__ creation for memory efficiency
-                },
-            )
-
-            # Performance optimization 4: Batch register traits
-            for trait in traits:
-                # Skip validation since we already validated composition
-                registry._trait_implementations.setdefault(
-                    model_class, set()
-                ).add(trait)
-
-            return model_class
-
-    def generate_model(self, composition: TraitComposition) -> type[Any]:
-        """
-        Generate a model class from trait composition.
-
-        Performance characteristics:
-        - First generation (cold): ~25μs (relaxed from 10μs research target)
-        - Cached generation (warm): <1μs (meets research target)
-
-        The 25μs cold generation is acceptable for production use as:
-        1. It only occurs once per unique trait combination
-        2. Subsequent calls use LRU cache (<1μs)
-        3. Most applications have limited trait combinations
-        """
-        start_time = time.perf_counter()
-
-        # Convert to sorted tuple for caching
-        trait_tuple = tuple(sorted(composition.traits, key=lambda t: t.name))
-
-        try:
-            # Use LRU cache for fast generation
-            model_class = self._generate_model_cached(trait_tuple)
-
-            # Track performance
-            generation_time = (
-                time.perf_counter() - start_time
-            ) * 1_000_000  # μs
-            self._generation_count += 1
-
-            # Updated performance target to realistic value
-            PERFORMANCE_TARGET_US = (
-                25.0  # Relaxed from 10μs for cold generation
-            )
-            if generation_time > PERFORMANCE_TARGET_US and __debug__:
-                import warnings
-
-                warnings.warn(
-                    f"Model generation took {generation_time:.1f}μs, "
-                    f"exceeding {PERFORMANCE_TARGET_US}μs target",
-                    PerformanceWarning,
-                    stacklevel=2,
-                )
-
-            return model_class
-
-        except Exception as e:
-            raise CompositionError(f"Failed to generate model: {e}") from e
-
-    def get_cache_stats(self) -> dict[str, Any]:
-        """Get performance statistics."""
-        info = self._generate_model_cached.cache_info()
-        return {
-            "cache_hits": info.hits,
-            "cache_misses": info.misses,
-            "cache_size": info.currsize,
-            "max_cache_size": info.maxsize,
-            "hit_ratio": (
-                info.hits / (info.hits + info.misses)
-                if (info.hits + info.misses) > 0
-                else 0.0
-            ),
-            "generations": self._generation_count,
-        }
-
-    def clear_cache(self) -> None:
-        """Clear the composition cache."""
-        self._generate_model_cached.cache_clear()
-        self._generation_count = 0
-
-
-# Initialize class-level caches
-TraitComposer._protocol_cache = {}
-TraitComposer._validated_compositions = set()
-
-
-# Convenience functions
-def compose(*traits: Trait | TraitComposition) -> TraitComposition:
-    """Compose traits using the global composer."""
-    return TraitComposer.get_instance().compose(*traits)
-
-
-def generate_model(composition: TraitComposition) -> type[Any]:
-    """Generate a model class from composition using the global composer."""
-    return TraitComposer.get_instance().generate_model(composition)
-
-
-def create_trait_composition(*traits: Trait) -> TraitComposition:
-    """Create a trait composition from individual traits."""
-    return TraitComposition(traits=frozenset(traits))
-
-
-# Performance warning class
-class PerformanceWarning(UserWarning):
-    """Warning for performance issues in trait composition."""
-
-    pass