exonware-xwnode 0.0.1.12__py3-none-any.whl

exonware/xwnode/strategies/nodes/node_bloom_filter.py

@@ -0,0 +1,347 @@
+"""
+Bloom Filter Node Strategy Implementation
+
+This module implements the BLOOM_FILTER strategy for memory-efficient
+probabilistic membership testing with no false negatives.
+"""
+
+from typing import Any, Iterator, List, Dict, Optional
+import hashlib
+import math
+from ._base_node import aNodeStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class xBloomFilterStrategy(aNodeStrategy):
+    """
+    Bloom Filter node strategy for probabilistic membership testing.
+    
+    Provides memory-efficient approximate membership testing with:
+    - No false negatives (if it says "no", it's definitely not there)
+    - Possible false positives (if it says "yes", it might be there)
+    - Configurable false positive rate
+    """
+    
+    def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
+        """Initialize the Bloom Filter strategy."""
+        super().__init__(NodeMode.BLOOM_FILTER, traits, **options)
+        
+        # Bloom filter parameters
+        self.expected_elements = options.get('expected_elements', 1000)
+        self.false_positive_rate = options.get('false_positive_rate', 0.01)
+        
+        # Calculate optimal parameters
+        self.bit_array_size = self._calculate_bit_array_size()
+        self.num_hash_functions = self._calculate_num_hash_functions()
+        
+        # Core storage
+        self._bit_array = [0] * self.bit_array_size
+        self._values: Dict[str, Any] = {}  # Store actual values for retrieval
+        self._size = 0
+        self._insertions = 0
+        
+        # Hash functions
+        self._hash_seeds = self._generate_hash_seeds()
+    
+    def get_supported_traits(self) -> NodeTrait:
+        """Get the traits supported by the bloom filter strategy."""
+        return (NodeTrait.PROBABILISTIC | NodeTrait.COMPRESSED | NodeTrait.STREAMING)
+    
+    def _calculate_bit_array_size(self) -> int:
+        """Calculate optimal bit array size."""
+        # m = -(n * ln(p)) / (ln(2)^2)
+        # where n = expected elements, p = false positive rate
+        n = self.expected_elements
+        p = self.false_positive_rate
+        
+        if p <= 0 or p >= 1:
+            p = 0.01  # Default to 1% false positive rate
+        
+        m = -(n * math.log(p)) / (math.log(2) ** 2)
+        return max(1, int(math.ceil(m)))
+    
+    def _calculate_num_hash_functions(self) -> int:
+        """Calculate optimal number of hash functions."""
+        # k = (m / n) * ln(2)
+        # where m = bit array size, n = expected elements
+        m = self.bit_array_size
+        n = self.expected_elements
+        
+        k = (m / n) * math.log(2)
+        return max(1, int(round(k)))
+    
+    def _generate_hash_seeds(self) -> List[int]:
+        """Generate seeds for multiple hash functions."""
+        seeds = []
+        for i in range(self.num_hash_functions):
+            # Use different primes as seeds
+            seed = [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47][i % 15]
+            seeds.append(seed * (i + 1))
+        return seeds
+    
+    def _hash_element(self, element: str, seed: int) -> int:
+        """Hash an element with a given seed."""
+        hash_obj = hashlib.md5(f"{element}{seed}".encode())
+        hash_int = int(hash_obj.hexdigest(), 16)
+        return hash_int % self.bit_array_size
+    
+    def _get_bit_positions(self, element: str) -> List[int]:
+        """Get all bit positions for an element."""
+        positions = []
+        for seed in self._hash_seeds:
+            pos = self._hash_element(element, seed)
+            positions.append(pos)
+        return positions
+    
+    # ============================================================================
+    # CORE OPERATIONS (Key-based interface for compatibility)
+    # ============================================================================
+    
+    def put(self, key: Any, value: Any = None) -> None:
+        """Add an element to the bloom filter."""
+        element = str(key)
+        
+        # Set bits for this element
+        positions = self._get_bit_positions(element)
+        for pos in positions:
+            self._bit_array[pos] = 1
+        
+        # Store actual value for retrieval (optional)
+        was_new = element not in self._values
+        self._values[element] = value if value is not None else key
+        
+        if was_new:
+            self._size += 1
+        
+        self._insertions += 1
+    
+    def get(self, key: Any, default: Any = None) -> Any:
+        """Get value if definitely present (may have false positives)."""
+        element = str(key)
+        
+        # Check if element might be present
+        if self.has(element):
+            return self._values.get(element, default)
+        else:
+            # Definitely not present
+            return default
+    
+    def has(self, key: Any) -> bool:
+        """Check if element might be present (probabilistic)."""
+        element = str(key)
+        
+        # Check all bit positions
+        positions = self._get_bit_positions(element)
+        for pos in positions:
+            if self._bit_array[pos] == 0:
+                # Definitely not present
+                return False
+        
+        # Might be present (could be false positive)
+        return True
+    
+    def remove(self, key: Any) -> bool:
+        """Remove from stored values (cannot remove from bloom filter)."""
+        element = str(key)
+        
+        if element in self._values:
+            del self._values[element]
+            self._size -= 1
+            return True
+        
+        return False
+    
+    def delete(self, key: Any) -> bool:
+        """Remove from stored values (alias for remove)."""
+        return self.remove(key)
+    
+    def clear(self) -> None:
+        """Clear all data."""
+        self._bit_array = [0] * self.bit_array_size
+        self._values.clear()
+        self._size = 0
+        self._insertions = 0
+    
+    def keys(self) -> Iterator[str]:
+        """Get all stored keys (not all elements in filter)."""
+        return iter(self._values.keys())
+    
+    def values(self) -> Iterator[Any]:
+        """Get all stored values."""
+        return iter(self._values.values())
+    
+    def items(self) -> Iterator[tuple[str, Any]]:
+        """Get all stored key-value pairs."""
+        return iter(self._values.items())
+    
+    def __len__(self) -> int:
+        """Get the number of stored elements."""
+        return self._size
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert to native Python dict of stored values."""
+        return dict(self._values)
+    
+    @property
+    def is_list(self) -> bool:
+        """This is not a list strategy."""
+        return False
+    
+    @property
+    def is_dict(self) -> bool:
+        """This behaves like a dict but with probabilistic semantics."""
+        return True
+    
+    # ============================================================================
+    # BLOOM FILTER SPECIFIC OPERATIONS
+    # ============================================================================
+    
+    def add(self, element: Any) -> None:
+        """Add an element to the bloom filter."""
+        self.put(element, element)
+    
+    def might_contain(self, element: Any) -> bool:
+        """Check if element might be in the filter (same as has)."""
+        return self.has(element)
+    
+    def definitely_not_contains(self, element: Any) -> bool:
+        """Check if element is definitely not in the filter."""
+        return not self.has(element)
+    
+    def get_false_positive_probability(self) -> float:
+        """Calculate current false positive probability."""
+        if self._insertions == 0:
+            return 0.0
+        
+        # p = (1 - e^(-k*n/m))^k
+        # where k = num hash functions, n = insertions, m = bit array size
+        k = self.num_hash_functions
+        n = self._insertions
+        m = self.bit_array_size
+        
+        if m == 0:
+            return 1.0
+        
+        exponent = -(k * n) / m
+        try:
+            probability = (1 - math.exp(exponent)) ** k
+            return min(1.0, max(0.0, probability))
+        except (OverflowError, ValueError):
+            return 1.0
+    
+    def get_capacity_utilization(self) -> float:
+        """Get the utilization of the bit array capacity."""
+        bits_set = sum(self._bit_array)
+        return bits_set / self.bit_array_size if self.bit_array_size > 0 else 0.0
+    
+    def union(self, other: 'xBloomFilterStrategy') -> 'xBloomFilterStrategy':
+        """Create union of two bloom filters (must have same parameters)."""
+        if (self.bit_array_size != other.bit_array_size or 
+            self.num_hash_functions != other.num_hash_functions):
+            raise ValueError("Bloom filters must have same parameters for union")
+        
+        result = xBloomFilterStrategy(
+            traits=self._traits,
+            expected_elements=max(self.expected_elements, other.expected_elements),
+            false_positive_rate=max(self.false_positive_rate, other.false_positive_rate)
+        )
+        
+        # OR the bit arrays
+        for i in range(self.bit_array_size):
+            result._bit_array[i] = self._bit_array[i] | other._bit_array[i]
+        
+        # Combine stored values
+        result._values.update(self._values)
+        result._values.update(other._values)
+        result._size = len(result._values)
+        result._insertions = self._insertions + other._insertions
+        
+        return result
+    
+    def intersection_estimate(self, other: 'xBloomFilterStrategy') -> float:
+        """Estimate intersection size (approximate)."""
+        if (self.bit_array_size != other.bit_array_size or 
+            self.num_hash_functions != other.num_hash_functions):
+            raise ValueError("Bloom filters must have same parameters for intersection")
+        
+        # Count bits set in both filters
+        intersection_bits = sum(1 for i in range(self.bit_array_size) 
+                              if self._bit_array[i] == 1 and other._bit_array[i] == 1)
+        
+        # Rough estimation (not mathematically precise)
+        if intersection_bits == 0:
+            return 0.0
+        
+        # Simple heuristic: intersection bits relative to total bits
+        total_bits_set = sum(self._bit_array) + sum(other._bit_array)
+        if total_bits_set == 0:
+            return 0.0
+        
+        estimated_ratio = intersection_bits / (total_bits_set / 2)
+        estimated_size = estimated_ratio * min(self._insertions, other._insertions)
+        return max(0.0, estimated_size)
+    
+    def export_bit_array(self) -> List[int]:
+        """Export the bit array for analysis or storage."""
+        return self._bit_array.copy()
+    
+    def import_bit_array(self, bit_array: List[int]) -> None:
+        """Import a bit array (must match current size)."""
+        if len(bit_array) != self.bit_array_size:
+            raise ValueError(f"Bit array size mismatch: expected {self.bit_array_size}, got {len(bit_array)}")
+        
+        self._bit_array = [int(bit) for bit in bit_array]
+    
+    def optimize_for_insertions(self, actual_insertions: int) -> 'xBloomFilterStrategy':
+        """Create an optimized bloom filter based on actual insertion count."""
+        optimized = xBloomFilterStrategy(
+            traits=self._traits,
+            expected_elements=actual_insertions,
+            false_positive_rate=self.false_positive_rate
+        )
+        
+        # Re-insert all stored values
+        for key, value in self._values.items():
+            optimized.put(key, value)
+        
+        return optimized
+    
+    # ============================================================================
+    # PERFORMANCE CHARACTERISTICS
+    # ============================================================================
+    
+    @property
+    def backend_info(self) -> Dict[str, Any]:
+        """Get backend implementation info."""
+        return {
+            'strategy': 'BLOOM_FILTER',
+            'backend': 'Probabilistic bit array',
+            'bit_array_size': self.bit_array_size,
+            'num_hash_functions': self.num_hash_functions,
+            'expected_elements': self.expected_elements,
+            'target_false_positive_rate': self.false_positive_rate,
+            'complexity': {
+                'add': 'O(k)',
+                'contains': 'O(k)',
+                'space': 'O(m)',
+                'false_negatives': '0%',
+                'false_positives': f'{self.false_positive_rate * 100:.2f}% target'
+            }
+        }
+    
+    @property
+    def metrics(self) -> Dict[str, Any]:
+        """Get performance metrics."""
+        current_fp_rate = self.get_false_positive_probability()
+        capacity_util = self.get_capacity_utilization()
+        
+        return {
+            'stored_elements': self._size,
+            'total_insertions': self._insertions,
+            'bit_array_size': self.bit_array_size,
+            'bits_set': sum(self._bit_array),
+            'capacity_utilization': f"{capacity_util * 100:.1f}%",
+            'current_false_positive_rate': f"{current_fp_rate * 100:.2f}%",
+            'target_false_positive_rate': f"{self.false_positive_rate * 100:.2f}%",
+            'memory_usage': f"{self.bit_array_size // 8} bytes (bit array)"
+        }

exonware/xwnode/strategies/nodes/node_btree.py

@@ -0,0 +1,357 @@
+"""
+B-Tree Node Strategy Implementation
+
+This module implements the B_TREE strategy for efficient range queries
+and sorted key operations with guaranteed O(log n) performance.
+"""
+
+from typing import Any, Iterator, List, Optional, Union, Dict
+from .base import ANodeTreeStrategy
+from ...types import NodeMode, NodeTrait
+
+
+class BTreeNode:
+    """A node in the B-tree."""
+    
+    def __init__(self, degree: int, is_leaf: bool = False):
+        self.degree = degree
+        self.keys: List[str] = []
+        self.values: List[Any] = []
+        self.children: List['BTreeNode'] = []
+        self.is_leaf = is_leaf
+    
+    def is_full(self) -> bool:
+        """Check if node is full."""
+        return len(self.keys) == 2 * self.degree - 1
+    
+    def search(self, key: str) -> Optional[Any]:
+        """Search for a key in this subtree."""
+        i = 0
+        while i < len(self.keys) and key > self.keys[i]:
+            i += 1
+        
+        if i < len(self.keys) and key == self.keys[i]:
+            return self.values[i]
+        
+        if self.is_leaf:
+            return None
+        
+        return self.children[i].search(key)
+    
+    def insert_non_full(self, key: str, value: Any):
+        """Insert key-value pair into non-full node."""
+        i = len(self.keys) - 1
+        
+        if self.is_leaf:
+            # Insert into leaf
+            self.keys.append("")
+            self.values.append(None)
+            while i >= 0 and key < self.keys[i]:
+                self.keys[i + 1] = self.keys[i]
+                self.values[i + 1] = self.values[i]
+                i -= 1
+            self.keys[i + 1] = key
+            self.values[i + 1] = value
+        else:
+            # Find child to insert into
+            while i >= 0 and key < self.keys[i]:
+                i -= 1
+            i += 1
+            
+            if self.children[i].is_full():
+                self.split_child(i)
+                if key > self.keys[i]:
+                    i += 1
+            
+            self.children[i].insert_non_full(key, value)
+    
+    def split_child(self, i: int):
+        """Split the full child at index i."""
+        full_child = self.children[i]
+        new_child = BTreeNode(full_child.degree, full_child.is_leaf)
+        
+        # Move half of the keys/values to new child
+        mid = self.degree - 1
+        new_child.keys = full_child.keys[mid + 1:]
+        new_child.values = full_child.values[mid + 1:]
+        full_child.keys = full_child.keys[:mid]
+        full_child.values = full_child.values[:mid]
+        
+        # Move children if not leaf
+        if not full_child.is_leaf:
+            new_child.children = full_child.children[mid + 1:]
+            full_child.children = full_child.children[:mid + 1]
+        
+        # Insert new child and promote middle key
+        self.children.insert(i + 1, new_child)
+        self.keys.insert(i, full_child.keys[mid])
+        self.values.insert(i, full_child.values[mid])
+
+
+class BTreeStrategy(ANodeTreeStrategy):
+    """
+    B-Tree node strategy for efficient sorted operations and range queries.
+    
+    Provides O(log n) search, insert, and delete operations with excellent
+    cache performance for range queries.
+    """
+    
+    def __init__(self, traits: NodeTrait = NodeTrait.NONE, **options):
+        """Initialize the B-tree strategy."""
+        super().__init__(NodeMode.B_TREE, traits, **options)
+        self.degree = options.get('degree', 3)  # Minimum degree
+        self.root: Optional[BTreeNode] = BTreeNode(self.degree, is_leaf=True)
+        self._size = 0
+    
+    def get_supported_traits(self) -> NodeTrait:
+        """Get the traits supported by the B-tree strategy."""
+        return (NodeTrait.ORDERED | NodeTrait.INDEXED | NodeTrait.HIERARCHICAL)
+    
+    # ============================================================================
+    # CORE OPERATIONS (Key-based interface for compatibility)
+    # ============================================================================
+    
+    def put(self, key: Any, value: Any = None) -> None:
+        """Store a value with the given key."""
+        key_str = str(key)
+        
+        # Check if key already exists (update case)
+        if self.has(key_str):
+            self._update_existing(key_str, value)
+            return
+        
+        if self.root.is_full():
+            # Create new root
+            new_root = BTreeNode(self.degree, is_leaf=False)
+            new_root.children.append(self.root)
+            new_root.split_child(0)
+            self.root = new_root
+        
+        self.root.insert_non_full(key_str, value)
+        self._size += 1
+    
+    def _update_existing(self, key: str, value: Any) -> None:
+        """Update existing key with new value."""
+        def update_in_node(node: BTreeNode) -> bool:
+            i = 0
+            while i < len(node.keys) and key > node.keys[i]:
+                i += 1
+            
+            if i < len(node.keys) and key == node.keys[i]:
+                node.values[i] = value
+                return True
+            
+            if not node.is_leaf:
+                return update_in_node(node.children[i])
+            
+            return False
+        
+        update_in_node(self.root)
+    
+    def get(self, key: Any, default: Any = None) -> Any:
+        """Retrieve a value by key."""
+        if not self.root:
+            return default
+        
+        result = self.root.search(str(key))
+        return result if result is not None else default
+    
+    def has(self, key: Any) -> bool:
+        """Check if key exists in B-tree."""
+        return self.get(key, None) is not None
+    
+    def remove(self, key: Any) -> bool:
+        """Remove value by key (simplified implementation)."""
+        # Note: Full B-tree deletion is complex. This is a simplified version.
+        key_str = str(key)
+        if not self.has(key_str):
+            return False
+        
+        # For simplicity, we'll rebuild without the key
+        # In production, implement proper B-tree deletion
+        all_items = list(self.items())
+        filtered_items = [(k, v) for k, v in all_items if k != key_str]
+        
+        self.clear()
+        for k, v in filtered_items:
+            self.put(k, v)
+        
+        return True
+    
+    def delete(self, key: Any) -> bool:
+        """Remove value by key (alias for remove)."""
+        return self.remove(key)
+    
+    def clear(self) -> None:
+        """Clear all data."""
+        self.root = BTreeNode(self.degree, is_leaf=True)
+        self._size = 0
+    
+    def keys(self) -> Iterator[str]:
+        """Get all keys in sorted order."""
+        def inorder_keys(node: BTreeNode) -> Iterator[str]:
+            if node.is_leaf:
+                yield from node.keys
+            else:
+                for i in range(len(node.keys)):
+                    yield from inorder_keys(node.children[i])
+                    yield node.keys[i]
+                if node.children:
+                    yield from inorder_keys(node.children[-1])
+        
+        if self.root:
+            yield from inorder_keys(self.root)
+    
+    def values(self) -> Iterator[Any]:
+        """Get all values in key-sorted order."""
+        def inorder_values(node: BTreeNode) -> Iterator[Any]:
+            if node.is_leaf:
+                yield from node.values
+            else:
+                for i in range(len(node.keys)):
+                    yield from inorder_values(node.children[i])
+                    yield node.values[i]
+                if node.children:
+                    yield from inorder_values(node.children[-1])
+        
+        if self.root:
+            yield from inorder_values(self.root)
+    
+    def items(self) -> Iterator[tuple[str, Any]]:
+        """Get all key-value pairs in sorted order."""
+        def inorder_items(node: BTreeNode) -> Iterator[tuple[str, Any]]:
+            if node.is_leaf:
+                yield from zip(node.keys, node.values)
+            else:
+                for i in range(len(node.keys)):
+                    yield from inorder_items(node.children[i])
+                    yield (node.keys[i], node.values[i])
+                if node.children:
+                    yield from inorder_items(node.children[-1])
+        
+        if self.root:
+            yield from inorder_items(self.root)
+    
+    def __len__(self) -> int:
+        """Get the number of items."""
+        return self._size
+    
+    def to_native(self) -> Dict[str, Any]:
+        """Convert to native Python dict."""
+        return dict(self.items())
+    
+    @property
+    def is_list(self) -> bool:
+        """This is not a list strategy."""
+        return False
+    
+    @property
+    def is_dict(self) -> bool:
+        """This is a dict-like strategy."""
+        return True
+    
+    # ============================================================================
+    # B-TREE SPECIFIC OPERATIONS
+    # ============================================================================
+    
+    def range_query(self, start_key: str, end_key: str) -> List[tuple[str, Any]]:
+        """Get all key-value pairs in the specified range [start_key, end_key]."""
+        result = []
+        for key, value in self.items():
+            if start_key <= key <= end_key:
+                result.append((key, value))
+            elif key > end_key:
+                break
+        return result
+    
+    def prefix_search(self, prefix: str) -> List[tuple[str, Any]]:
+        """Find all keys that start with the given prefix."""
+        result = []
+        for key, value in self.items():
+            if key.startswith(prefix):
+                result.append((key, value))
+            elif key > prefix:
+                # Since keys are sorted, we can stop when we pass the prefix range
+                if not key.startswith(prefix):
+                    break
+        return result
+    
+    def min_key(self) -> Optional[str]:
+        """Get the minimum key."""
+        if not self.root or self._size == 0:
+            return None
+        
+        node = self.root
+        while not node.is_leaf:
+            node = node.children[0]
+        
+        return node.keys[0] if node.keys else None
+    
+    def max_key(self) -> Optional[str]:
+        """Get the maximum key."""
+        if not self.root or self._size == 0:
+            return None
+        
+        node = self.root
+        while not node.is_leaf:
+            node = node.children[-1]
+        
+        return node.keys[-1] if node.keys else None
+    
+    def successor(self, key: str) -> Optional[str]:
+        """Find the successor of the given key."""
+        found = False
+        for k in self.keys():
+            if found and k > key:
+                return k
+            if k == key:
+                found = True
+        return None
+    
+    def predecessor(self, key: str) -> Optional[str]:
+        """Find the predecessor of the given key."""
+        prev_key = None
+        for k in self.keys():
+            if k == key:
+                return prev_key
+            prev_key = k
+        return None
+    
+    # ============================================================================
+    # PERFORMANCE CHARACTERISTICS
+    # ============================================================================
+    
+    @property
+    def backend_info(self) -> Dict[str, Any]:
+        """Get backend implementation info."""
+        return {
+            'strategy': 'B_TREE',
+            'backend': 'Custom B-tree implementation',
+            'degree': self.degree,
+            'complexity': {
+                'search': 'O(log n)',
+                'insert': 'O(log n)',
+                'delete': 'O(log n)',
+                'range_query': 'O(log n + k)',
+                'iteration': 'O(n)'
+            }
+        }
+    
+    @property
+    def metrics(self) -> Dict[str, Any]:
+        """Get performance metrics."""
+        # Calculate tree height
+        height = 0
+        if self.root:
+            node = self.root
+            while not node.is_leaf and node.children:
+                node = node.children[0]
+                height += 1
+        
+        return {
+            'size': self._size,
+            'degree': self.degree,
+            'height': height,
+            'memory_usage': f"{self._size * (24 + 16)} bytes (estimated)",
+            'is_sorted': True
+        }