chunk-metadata-adapter 3.3.3__py3-none-any.whl

chunk_metadata_adapter/__init__.py

@@ -0,0 +1,139 @@
+"""
+Chunk Metadata Adapter - A package for managing metadata for chunked content.
+
+This package provides tools for creating, managing, and converting metadata
+for chunks of content in various systems, including RAG pipelines, document
+processing, and machine learning training datasets.
+"""
+
+# Core classes
+from .semantic_chunk import SemanticChunk, ChunkMetrics, FeedbackMetrics
+from .chunk_query import ChunkQuery
+from .metadata_builder import ChunkMetadataBuilder
+
+# Data types and enums
+from .data_types import (
+    ChunkType,
+    ChunkRole,
+    ChunkStatus,
+    BlockType,
+    LanguageEnum,
+    ComparableEnum,
+)
+
+# AST and parsing
+from .ast import (
+    ASTNode,
+    ASTVisitor,
+    ASTValidator,
+    ASTAnalyzer,
+    FieldCondition,
+    LogicalOperator,
+    ParenExpression,
+    TypedValue,
+    ASTNodeFactory,
+    ast_to_json,
+    ast_from_json,
+    ast_to_json_string,
+    ast_from_json_string,
+)
+from .filter_parser import FilterParser, FilterParseError
+from .filter_grammar import FILTER_GRAMMAR
+from .ast_optimizer import ASTOptimizer, optimize_ast
+from .filter_executor import FilterExecutor
+
+# Search response handling
+from .search_response import SearchResult, ChunkQueryResponse, SearchResponseBuilder
+
+# Hybrid search functionality
+from .hybrid_search import (
+    HybridStrategy,
+    HybridSearchConfig,
+    HybridSearchHelper,
+    HybridSearchValidator,
+)
+
+# Validation and analysis
+from .query_validator import QueryValidator, ValidationResult
+from .complexity_analyzer import ComplexityAnalyzer, analyze_complexity
+from .security_validator import SecurityValidator
+from .performance_analyzer import PerformanceAnalyzer
+
+# Examples
+from .examples_module import (
+    example_basic_flat_metadata,
+    example_structured_chunk,
+    example_conversion_between_formats,
+    example_chain_processing,
+    example_data_lifecycle,
+    example_metrics_extension,
+    example_full_chain_structured_semantic_flat,
+    example_is_code_detection,
+    example_filter_factory_method,
+    example_filter_usage,
+)
+
+__version__ = "3.3.3"
+
+__all__ = [
+    # Core classes
+    "SemanticChunk",
+    "ChunkMetrics",
+    "ChunkQuery",
+    "ChunkMetadataBuilder",
+    # Data types and enums
+    "ChunkType",
+    "ChunkRole",
+    "ChunkStatus",
+    "BlockType",
+    "LanguageEnum",
+    "FeedbackMetrics",
+    "ComparableEnum",
+    # AST and parsing
+    "ASTNode",
+    "ASTVisitor",
+    "ASTValidator",
+    "ASTAnalyzer",
+    "FieldCondition",
+    "LogicalOperator",
+    "ParenExpression",
+    "TypedValue",
+    "ASTNodeFactory",
+    "ast_to_json",
+    "ast_from_json",
+    "ast_to_json_string",
+    "ast_from_json_string",
+    "FilterParser",
+    "FilterParseError",
+    "FILTER_GRAMMAR",
+    "ASTOptimizer",
+    "optimize_ast",
+    "FilterExecutor",
+    # Search response handling
+    "SearchResult",
+    "ChunkQueryResponse",
+    "SearchResponseBuilder",
+    # Hybrid search functionality
+    "HybridStrategy",
+    "HybridSearchConfig",
+    "HybridSearchHelper",
+    "HybridSearchValidator",
+    # Validation and analysis
+    "QueryValidator",
+    "ValidationResult",
+    "ComplexityAnalyzer",
+    "analyze_complexity",
+    "SecurityValidator",
+    "PerformanceAnalyzer",
+    # Examples
+    "example_basic_flat_metadata",
+    "example_structured_chunk",
+    "example_conversion_between_formats",
+    "example_chain_processing",
+    "example_data_lifecycle",
+    "example_metrics_extension",
+    "example_full_chain_structured_semantic_flat",
+    "example_is_code_detection",
+    "example_filter_factory_method",
+    "example_filter_usage",
+]

chunk_metadata_adapter/ast/__init__.py

@@ -0,0 +1,85 @@
+"""
+AST (Abstract Syntax Tree) module for filter expression parsing and execution.
+
+This module provides the core data structures for representing filter expressions
+as Abstract Syntax Trees (AST). It includes typed nodes for field conditions,
+logical operators, and parenthesized expressions.
+
+Key features:
+- TypedValue: Type-safe value representation with validation
+- FieldCondition: Field comparison conditions (age > 18)
+- LogicalOperator: Logical operations (AND, OR, NOT)
+- ParenExpression: Parenthesized expressions for precedence
+- JSON serialization: Full serialization/deserialization support
+- Visitor pattern: AST traversal and analysis
+
+Usage examples:
+    >>> from chunk_metadata_adapter.ast import FieldCondition, TypedValue
+    >>> condition = FieldCondition("age", ">", TypedValue("int", 18))
+    >>> result = condition.evaluate({"age": 25})
+
+Dependencies:
+- dataclasses: For data structure definitions
+- typing: For type hints and annotations
+- datetime: For date/time value support
+- json: For serialization support
+
+Author: Development Team
+Created: 2024-01-15
+Updated: 2024-01-20
+"""
+
+# Core AST classes
+from .nodes import (
+    ASTNode, FieldCondition, LogicalOperator, ParenExpression, TypedValue
+)
+
+# Visitor pattern classes
+from .visitors import (
+    ASTVisitor, ASTPrinter, ASTValidator, ASTAnalyzer, ASTOptimizer
+)
+
+# Factory for creating AST nodes
+from .factory import ASTNodeFactory
+
+# JSON serialization utilities
+from .serialization import (
+    ast_to_json, ast_from_json, ast_to_json_string, ast_from_json_string
+)
+
+# Parameterization and caching
+from .parameterization import (
+    ParameterValue, ParameterizedAST, ASTParameterizer, ASTInstantiator, QueryCache
+)
+
+__all__ = [
+    # Core AST classes
+    "ASTNode",
+    "FieldCondition", 
+    "LogicalOperator",
+    "ParenExpression",
+    "TypedValue",
+    
+    # Visitor pattern
+    "ASTVisitor",
+    "ASTPrinter",
+    "ASTValidator", 
+    "ASTAnalyzer",
+    "ASTOptimizer",
+    
+    # Factory
+    "ASTNodeFactory",
+    
+    # JSON serialization
+    "ast_to_json",
+    "ast_from_json", 
+    "ast_to_json_string",
+    "ast_from_json_string",
+    
+    # Parameterization and caching
+    "ParameterValue",
+    "ParameterizedAST", 
+    "ASTParameterizer",
+    "ASTInstantiator",
+    "QueryCache",
+] 

chunk_metadata_adapter/ast/factory.py

@@ -0,0 +1,91 @@
+"""
+AST node factory for convenient node creation.
+
+This module provides a factory class for creating various types of AST nodes
+with proper validation and convenient methods.
+
+Key features:
+- ASTNodeFactory: Factory for creating AST nodes
+- Convenient methods for common node types
+- Automatic validation and error handling
+
+Usage examples:
+    >>> from ast.factory import ASTNodeFactory
+    >>> condition = ASTNodeFactory.create_simple_condition("age", ">", "int", 18)
+    >>> operator = ASTNodeFactory.create_and_operator([condition1, condition2])
+
+Dependencies:
+- typing: For type hints and annotations
+- .nodes: For AST node classes
+
+Author: Development Team
+Created: 2024-01-15
+Updated: 2024-01-20
+"""
+
+from typing import List, Literal, Any
+from .nodes import ASTNode, FieldCondition, LogicalOperator, ParenExpression, TypedValue
+
+
+class ASTNodeFactory:
+    """
+    Factory for creating AST nodes.
+
+    This class provides convenient methods for creating
+    various types of AST nodes with proper validation.
+    """
+
+    @staticmethod
+    def create_field_condition(field: str, operator: str, value: TypedValue) -> FieldCondition:
+        """Create a field condition node."""
+        return FieldCondition(field=field, operator=operator, value=value)
+
+    @staticmethod
+    def create_logical_operator(operator: Literal["AND", "OR", "NOT", "XOR"],
+                               children: List[ASTNode]) -> LogicalOperator:
+        """Create a logical operator node."""
+        return LogicalOperator(operator=operator, children=children)
+
+    @staticmethod
+    def create_paren_expression(expression: ASTNode) -> ParenExpression:
+        """Create a parenthesized expression node."""
+        return ParenExpression(expression=expression)
+
+    @staticmethod
+    def create_typed_value(type_name: str, value: Any) -> TypedValue:
+        """Create a typed value."""
+        return TypedValue(type=type_name, value=value)
+
+    @staticmethod
+    def create_and_operator(children: List[ASTNode]) -> LogicalOperator:
+        """Create an AND operator node."""
+        return ASTNodeFactory.create_logical_operator("AND", children)
+
+    @staticmethod
+    def create_or_operator(children: List[ASTNode]) -> LogicalOperator:
+        """Create an OR operator node."""
+        return ASTNodeFactory.create_logical_operator("OR", children)
+
+    @staticmethod
+    def create_not_operator(child: ASTNode) -> LogicalOperator:
+        """Create a NOT operator node."""
+        return ASTNodeFactory.create_logical_operator("NOT", [child])
+
+    @staticmethod
+    def create_simple_condition(field: str, operator: str, type_name: str, value: Any) -> FieldCondition:
+        """Create a simple field condition with automatic typed value creation."""
+        typed_value = ASTNodeFactory.create_typed_value(type_name, value)
+        return ASTNodeFactory.create_field_condition(field, operator, typed_value)
+
+    @staticmethod
+    def create_complex_expression(conditions: List[tuple],
+                                 operator: Literal["AND", "OR"] = "AND") -> LogicalOperator:
+        """Create a complex expression from a list of conditions."""
+        field_conditions = []
+        for field, op, type_name, value in conditions:
+            condition = ASTNodeFactory.create_simple_condition(field, op, type_name, value)
+            field_conditions.append(condition)
+        if operator == "AND":
+            return ASTNodeFactory.create_and_operator(field_conditions)
+        else:
+            return ASTNodeFactory.create_or_operator(field_conditions)