edsl 0.1.54__py3-none-any.whl → 0.1.55__py3-none-any.whl

edsl/caching/cache_entry.py

@@ -21,12 +21,12 @@ from .exceptions import CacheError
 class CacheEntry(RepresentationMixin):
     """
     Represents a single cached language model response with associated metadata.
-    
+
     CacheEntry objects store language model responses along with the prompts and
     parameters that generated them. Each entry is uniquely identified by a hash
-    of its key fields (model, parameters, prompts, and iteration), making it 
+    of its key fields (model, parameters, prompts, and iteration), making it
     possible to efficiently retrieve cached responses for identical inputs.
-    
+
     Attributes:
         model (str): The language model identifier (e.g., "gpt-3.5-turbo")
         parameters (dict): Model parameters used for generation (e.g., temperature)
@@ -37,14 +37,14 @@ class CacheEntry(RepresentationMixin):
                          with the same prompts (defaults to 0)
         timestamp (int): Unix timestamp when the entry was created
         service (str, optional): The service provider for the model (e.g., "openai")
-        
+
     Class Attributes:
         key_fields (List[str]): Fields used to generate the unique hash key
         all_fields (List[str]): All fields stored in the cache entry
     """
 
     key_fields = ["model", "parameters", "system_prompt", "user_prompt", "iteration"]
-    all_fields = key_fields + ["timestamp", "output", "service"]
+    all_fields = key_fields + ["timestamp", "output", "service", "validated"]
 
     def __init__(
         self,
@@ -57,6 +57,7 @@ class CacheEntry(RepresentationMixin):
         output: str,
         timestamp: Optional[int] = None,
         service: Optional[str] = None,
+        validated: bool = False,
     ):
         self.model = model
         self.parameters = parameters
@@ -68,16 +69,17 @@ class CacheEntry(RepresentationMixin):
             datetime.datetime.now(datetime.timezone.utc).timestamp()
         )
         self.service = service
+        self.validated = validated
         self._check_types()
 
     def _check_types(self) -> None:
         """
         Validates that all attributes have the correct types.
-        
+
         This method is called during initialization to ensure that all
         attributes have the expected types, raising TypeError exceptions
         with descriptive messages when validation fails.
-        
+
         Raises:
             TypeError: If any attribute has an incorrect type
         """
@@ -98,31 +100,38 @@ class CacheEntry(RepresentationMixin):
             raise CacheError("`timestamp` should be an integer")
         if self.service is not None and not isinstance(self.service, str):
             raise CacheError("`service` should be either a string or None")
+        if not isinstance(self.validated, bool):
+            raise CacheError("`validated` should be a boolean")
 
     @classmethod
     def gen_key(
-        cls, *, model: str, parameters: Dict[str, Any], 
-        system_prompt: str, user_prompt: str, iteration: int
+        cls,
+        *,
+        model: str,
+        parameters: Dict[str, Any],
+        system_prompt: str,
+        user_prompt: str,
+        iteration: int,
     ) -> str:
         """
         Generates a unique key hash for the cache entry based on input parameters.
-        
+
         This method creates a deterministic hash key by concatenating the model name,
         parameters (sorted to ensure consistency), system prompt, user prompt, and
         iteration number. The hash enables efficient lookup of cache entries with
         identical inputs.
-        
+
         Args:
             model: The language model identifier
             parameters: Dictionary of model parameters (will be sorted for consistency)
             system_prompt: The system prompt provided to the model
             user_prompt: The user prompt provided to the model
             iteration: Iteration number for this combination of inputs
-            
+
         Returns:
             A hex-encoded MD5 hash string that uniquely identifies this combination
             of inputs
-            
+
         Note:
             - The hash treats single and double quotes as equivalent
             - Parameters are sorted to ensure consistent hashing regardless of order
@@ -134,11 +143,11 @@ class CacheEntry(RepresentationMixin):
     def key(self) -> str:
         """
         Returns the unique hash key for this cache entry.
-        
+
         This property extracts the key fields from the instance and generates
         a hash key using the gen_key classmethod. The key uniquely identifies
         this combination of model, parameters, prompts, and iteration.
-        
+
         Returns:
             A hex-encoded MD5 hash string that uniquely identifies this cache entry
         """
@@ -148,17 +157,17 @@ class CacheEntry(RepresentationMixin):
     def to_dict(self, add_edsl_version: bool = True) -> Dict[str, Any]:
         """
         Converts the cache entry to a dictionary representation.
-        
+
         This method creates a dictionary containing all fields of the cache entry,
         making it suitable for serialization or storage.
-        
+
         Args:
             add_edsl_version: If True, adds EDSL version information to the dict
                               (Currently disabled pending implementation)
-                              
+
         Returns:
             A dictionary representation of the cache entry with all fields
-        
+
         Note:
             The edsl_version feature is currently disabled in the implementation
         """
@@ -171,6 +180,7 @@ class CacheEntry(RepresentationMixin):
             "iteration": self.iteration,
             "timestamp": self.timestamp,
             "service": self.service,
+            "validated": self.validated,
         }
         # Feature for adding version information (currently disabled)
         # if add_edsl_version:
@@ -182,9 +192,9 @@ class CacheEntry(RepresentationMixin):
     def keys(self) -> List[str]:
         """
         Returns a list of field names in this cache entry.
-        
+
         This method enables dict-like access to cache entry field names.
-        
+
         Returns:
             List of field names from the dictionary representation
         """
@@ -193,9 +203,9 @@ class CacheEntry(RepresentationMixin):
     def values(self) -> List[Any]:
         """
         Returns a list of values for all fields in this cache entry.
-        
+
         This method enables dict-like access to cache entry values.
-        
+
         Returns:
             List of values from the dictionary representation
         """
@@ -204,16 +214,16 @@ class CacheEntry(RepresentationMixin):
     def __getitem__(self, key: str) -> Any:
         """
         Enables dictionary-style access to cache entry attributes.
-        
+
         This method allows accessing cache entry attributes using dictionary
         syntax (e.g., entry["model"] instead of entry.model).
-        
+
         Args:
             key: The name of the attribute to access
-            
+
         Returns:
             The value of the specified attribute
-            
+
         Raises:
             AttributeError: If the specified attribute doesn't exist
         """
@@ -223,17 +233,17 @@ class CacheEntry(RepresentationMixin):
     def from_dict(cls, data: Dict[str, Any]) -> CacheEntry:
         """
         Creates a CacheEntry object from a dictionary representation.
-        
+
         This factory method enables reconstruction of CacheEntry objects
         from serialized dictionary representations, such as those produced
         by the to_dict method.
-        
+
         Args:
             data: Dictionary containing required CacheEntry fields
-            
+
         Returns:
             A new CacheEntry instance with fields populated from the dictionary
-            
+
         Raises:
             TypeError: If data contains fields with incorrect types
             KeyError: If required fields are missing from data
@@ -243,18 +253,18 @@ class CacheEntry(RepresentationMixin):
     def __eq__(self, other: Any) -> bool:
         """
         Compares this cache entry with another for equality.
-        
+
         This method checks if all fields except timestamp are equal between
-        this cache entry and another. The timestamp is excluded from the 
+        this cache entry and another. The timestamp is excluded from the
         comparison because it's typically not relevant for determining if
         two entries represent the same cached response.
-        
+
         Args:
             other: Another object to compare with this cache entry
-            
+
         Returns:
             True if all fields except timestamp are equal, False otherwise
-            
+
         Note:
             Returns False if other is not a CacheEntry instance
         """
@@ -268,11 +278,11 @@ class CacheEntry(RepresentationMixin):
     def __repr__(self) -> str:
         """
         Returns a string representation of this cache entry.
-        
+
         This method creates a string representation that displays all fields
         of the cache entry in a format that can be evaluated to recreate
         the object.
-        
+
         Returns:
             A string representation that can be passed to eval() to recreate
             this cache entry
@@ -285,24 +295,25 @@ class CacheEntry(RepresentationMixin):
             f"output={repr(self.output)}, "
             f"iteration={self.iteration}, "
             f"timestamp={self.timestamp}, "
-            f"service={repr(self.service)})"
+            f"service={repr(self.service)}, "
+            f"validated={self.validated})"
         )
 
     @classmethod
     def example(cls, randomize: bool = False) -> CacheEntry:
         """
         Creates an example CacheEntry instance for testing and demonstration.
-        
+
         This factory method generates a pre-populated CacheEntry with example
         values, useful for testing, documentation, and examples.
-        
+
         Args:
             randomize: If True, adds a random UUID to the system prompt to make
                       the entry unique and generate a different hash key
-                      
+
         Returns:
             A fully populated example CacheEntry instance
-            
+
         Example:
             >>> entry = CacheEntry.example()
             >>> isinstance(entry, CacheEntry)
@@ -320,20 +331,21 @@ class CacheEntry(RepresentationMixin):
             iteration=1,
             timestamp=int(datetime.datetime.now(datetime.timezone.utc).timestamp()),
             service="openai",
+            validated=True,
         )
 
     @classmethod
     def example_dict(cls) -> Dict[str, CacheEntry]:
         """
         Creates an example dictionary mapping a key to a CacheEntry.
-        
+
         This method demonstrates how CacheEntry objects are typically stored
         in a cache, with their hash keys as dictionary keys.
-        
+
         Returns:
             A dictionary with a single entry mapping the example entry's key
             to the example entry
-            
+
         Note:
             This is particularly useful for testing and demonstrating the
             Cache class functionality
@@ -345,13 +357,13 @@ class CacheEntry(RepresentationMixin):
     def fetch_input_example(cls) -> Dict[str, Any]:
         """
         Creates an example input dictionary for a 'fetch' operation.
-        
+
         This method generates a dictionary containing the fields needed to
         look up a cache entry (everything except the response/output fields).
-        
+
         Returns:
             A dictionary with fields needed to generate a cache key for lookup
-            
+
         Note:
             This is used by the Cache class to demonstrate fetch operations
         """
@@ -365,14 +377,14 @@ class CacheEntry(RepresentationMixin):
     def store_input_example(cls) -> Dict[str, Any]:
         """
         Creates an example input dictionary for a 'store' operation.
-        
+
         This method generates a dictionary containing the fields needed to
         store a new cache entry, with 'output' renamed to 'response' to match
         the API of the Cache.store method.
-        
+
         Returns:
             A dictionary with fields needed to store a new cache entry
-            
+
         Note:
             This is used by the Cache class to demonstrate store operations
         """
@@ -385,11 +397,11 @@ class CacheEntry(RepresentationMixin):
 def main() -> None:
     """
     Demonstration of CacheEntry functionality for interactive testing.
-    
+
     This function demonstrates the key features of the CacheEntry class,
     including creating entries, calculating hash keys, converting to/from
     dictionaries, and comparing entries.
-    
+
     Note:
         This function is intended to be run in an interactive Python session
         for exploration and testing, not as part of normal code execution.
@@ -402,20 +414,20 @@ def main() -> None:
 
     # Demonstrate key generation
     print(f"Cache key: {cache_entry.key}")
-    
+
     # Demonstrate serialization and deserialization
     entry_dict = cache_entry.to_dict()
     print(f"Dictionary representation: {entry_dict}")
     reconstructed = CacheEntry.from_dict(entry_dict)
     print(f"Reconstructed from dict: {reconstructed}")
-    
+
     # Demonstrate equality comparisons
     print(f"Same content equals: {cache_entry == CacheEntry.example()}")
     print(f"Same key equals: {cache_entry.key == CacheEntry.example().key}")
-    
+
     # Demonstrate repr evaluation
     print(f"Repr can be evaluated: {eval(repr(cache_entry)) == cache_entry}")
-    
+
     # Demonstrate utility methods
     print(f"Example dict: {CacheEntry.example_dict()}")
     print(f"Fetch input example: {CacheEntry.fetch_input_example()}")

edsl/caching/sql_dict.py

@@ -363,6 +363,23 @@ class SQLiteDict:
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(db_path={self.db_path!r})"
+        
+    def close(self):
+        """Close database connections and clean up resources.
+        
+        This method properly disposes of the SQLAlchemy engine,
+        closing all connections in the pool to prevent memory leaks.
+        """
+        if hasattr(self, 'engine') and self.engine:
+            self.engine.dispose()
+            
+    def __del__(self):
+        """Destructor for proper resource cleanup.
+        
+        Ensures SQLAlchemy connections are properly closed when the
+        object is garbage collected.
+        """
+        self.close()
 
     @classmethod
     def example(cls) -> SQLiteDict:

edsl/cli.py

@@ -6,6 +6,8 @@ This module provides the main entry point for the EDSL command-line tool.
 
 import sys
 import typer
+import json
+from pathlib import Path
 from typing import Optional
 from rich.console import Console
 from importlib import metadata
@@ -20,6 +22,103 @@ from .plugins.cli_typer import app as plugins_app
 # Add the plugins subcommand
 app.add_typer(plugins_app, name="plugins")
 
+# Create the validation app
+validation_app = typer.Typer(help="Manage EDSL validation failures")
+app.add_typer(validation_app, name="validation")
+
+@validation_app.command("logs")
+def list_validation_logs(
+    count: int = typer.Option(10, "--count", "-n", help="Number of logs to show"),
+    question_type: Optional[str] = typer.Option(None, "--type", "-t", help="Filter by question type"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output file path"),
+):
+    """List validation failure logs."""
+    from .questions.validation_logger import get_validation_failure_logs
+    
+    logs = get_validation_failure_logs(n=count)
+    
+    # Filter by question type if provided
+    if question_type:
+        logs = [log for log in logs if log.get("question_type") == question_type]
+    
+    if output:
+        with open(output, "w") as f:
+            json.dump(logs, f, indent=2)
+        console.print(f"[green]Logs written to {output}[/green]")
+    else:
+        console.print_json(json.dumps(logs, indent=2))
+        
+@validation_app.command("clear")
+def clear_validation_logs():
+    """Clear validation failure logs."""
+    from .questions.validation_logger import clear_validation_logs
+    
+    clear_validation_logs()
+    console.print("[green]Validation logs cleared.[/green]")
+        
+@validation_app.command("stats")
+def validation_stats(
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output file path"),
+):
+    """Show validation failure statistics."""
+    from .questions.validation_analysis import get_validation_failure_stats
+    
+    stats = get_validation_failure_stats()
+    
+    if output:
+        with open(output, "w") as f:
+            json.dump(stats, f, indent=2)
+        console.print(f"[green]Stats written to {output}[/green]")
+    else:
+        console.print_json(json.dumps(stats, indent=2))
+        
+@validation_app.command("suggest")
+def suggest_improvements(
+    question_type: Optional[str] = typer.Option(None, "--type", "-t", help="Filter by question type"),
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output file path"),
+):
+    """Suggest improvements for fix methods."""
+    from .questions.validation_analysis import suggest_fix_improvements
+    
+    suggestions = suggest_fix_improvements(question_type=question_type)
+    
+    if output:
+        with open(output, "w") as f:
+            json.dump(suggestions, f, indent=2)
+        console.print(f"[green]Suggestions written to {output}[/green]")
+    else:
+        console.print_json(json.dumps(suggestions, indent=2))
+        
+@validation_app.command("report")
+def generate_report(
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output file path"),
+):
+    """Generate a comprehensive validation report."""
+    from .questions.validation_analysis import export_improvements_report
+    
+    report_path = export_improvements_report(output_path=output)
+    console.print(f"[green]Report generated at: {report_path}[/green]")
+    
+@validation_app.command("html-report")
+def generate_html_report(
+    output: Optional[Path] = typer.Option(None, "--output", "-o", help="Output file path"),
+    open_browser: bool = typer.Option(True, "--open/--no-open", help="Open the report in a browser"),
+):
+    """Generate an HTML validation report and optionally open it in a browser."""
+    from .questions.validation_html_report import generate_html_report
+    import webbrowser
+    
+    report_path = generate_html_report(output_path=output)
+    console.print(f"[green]HTML report generated at: {report_path}[/green]")
+    
+    if open_browser:
+        try:
+            webbrowser.open(f"file://{report_path}")
+            console.print("[green]Opened report in browser[/green]")
+        except Exception as e:
+            console.print(f"[yellow]Could not open browser: {e}[/yellow]")
+            console.print(f"[yellow]Report is available at: {report_path}[/yellow]")
+
 @app.callback()
 def callback():
     """

edsl/config/config_class.py

@@ -58,6 +58,10 @@ CONFIG_MAP = {
         "default": "True",
         "info": "This config var determines whether to fetch prices for tokens used in remote inference",
     },
+    "EDSL_LOG_DIR": {
+        "default": str(os.path.join(platformdirs.user_data_dir('edsl'), 'logs')),
+        "info": "This config var determines the directory where logs are stored.",
+    },
     "EDSL_LOG_LEVEL": {
         "default": "ERROR",
         "info": "This config var determines the logging level for the EDSL package (DEBUG, INFO, WARNING, ERROR, CRITICAL).",
@@ -90,6 +94,18 @@ CONFIG_MAP = {
         "default": "None",
         "info": "This config var holds the URL of the remote token bucket server.",
     },
+    "EDSL_SQLLIST_MEMORY_THRESHOLD": {
+        "default": "10",  # Change to a very low threshold (10 bytes) to test SQLite offloading
+        "info": "This config var determines the memory threshold in bytes before SQLList offloads data to SQLite.",
+    },
+    "EDSL_SQLLIST_DB_PATH": {
+        "default": f"sqlite:///{os.path.join(platformdirs.user_cache_dir('edsl'), 'sql_list_data.db')}",
+        "info": "This config var determines the default database path for SQLList instances.",
+    },
+    "EDSL_RESULTS_MEMORY_THRESHOLD": {
+        "default": "10",  # Change to a very low threshold (10 bytes) to test SQLite offloading
+        "info": "This config var determines the memory threshold in bytes before Results' SQLList offloads data to SQLite.",
+    },
 }
 
 

edsl/conversation/__init__.py

@@ -0,0 +1,31 @@
+"""
+The conversation module provides tools for simulating conversations between agents.
+
+It includes classes for managing dialogues, tracking statements, and controlling
+conversation flow between multiple participants.
+"""
+
+from .Conversation import Conversation, ConversationList, AgentStatement, AgentStatements
+from .exceptions import ConversationError, ConversationValueError, ConversationStateError
+from .next_speaker_utilities import (
+    default_turn_taking_generator,
+    turn_taking_generator_with_focal_speaker,
+    random_turn_taking_generator,
+    random_inclusive_generator,
+    speaker_closure,
+)
+
+__all__ = [
+    "Conversation",
+    "ConversationList",
+    "AgentStatement",
+    "AgentStatements",
+    "ConversationError",
+    "ConversationValueError",
+    "ConversationStateError",
+    "default_turn_taking_generator",
+    "turn_taking_generator_with_focal_speaker",
+    "random_turn_taking_generator",
+    "random_inclusive_generator",
+    "speaker_closure",
+]