edsl 0.1.14__py3-none-any.whl → 0.1.40__py3-none-any.whl

edsl/utilities/utilities.py

@@ -1,3 +1,9 @@
+"""Utility functions for working with strings, dictionaries, and files."""
+
+from functools import wraps
+import types
+import time
+
 import hashlib
 import json
 import keyword
@@ -8,11 +14,138 @@ import string
 import tempfile
 import gzip
 import webbrowser
+import json
+
 from html import escape
 from typing import Callable, Union
 
 
+class CustomEncoder(json.JSONEncoder):
+    def default(self, obj):
+        try:
+            return json.JSONEncoder.default(self, obj)
+        except TypeError:
+            return str(obj)
+
+
+def time_it(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        result = func(*args, **kwargs)
+        end_time = time.time()
+        execution_time = end_time - start_time
+        class_name = args[0].__class__.__name__ if args else func.__module__
+        print(
+            f"Function {class_name}.{func.__name__} took {execution_time:.4f} seconds to execute"
+        )
+        return result
+
+    return wrapper
+
+
+def time_all_functions(module_or_class):
+    for name, obj in vars(module_or_class).items():
+        if isinstance(obj, types.FunctionType):
+            setattr(module_or_class, name, time_it(obj))
+
+
+def dict_hash(data: dict):
+    return hash(
+        int(hashlib.md5(json.dumps(data, sort_keys=True).encode()).hexdigest(), 16)
+    )
+
+
+def extract_json_from_string(text):
+    pattern = re.compile(r"\{.*?\}")
+    match = pattern.search(text)
+    if match:
+        json_data = match.group(0)
+        try:
+            json_object = json.loads(json_data)
+            return json_object
+        except json.JSONDecodeError:
+            return None
+    return None
+
+
+def fix_partial_correct_response(text: str) -> dict:
+    # Find the start position of the key "answer"
+    answer_key_start = text.find('"answer"')
+
+    if answer_key_start == -1:
+        return {"error": "No 'answer' key found in the text"}
+
+    # Define regex to find the complete JSON object starting with "answer"
+    json_pattern = r'(\{[^\{\}]*"answer"[^\{\}]*\})'
+    match = re.search(json_pattern, text)
+
+    if not match:
+        return {"error": "No valid JSON object found"}
+
+    # Extract the matched JSON object
+    json_object = match.group(0)
+
+    # Find the start and stop positions of the JSON object in the original text
+    start_pos = text.find(json_object)
+    stop_pos = start_pos + len(json_object)
+
+    # Parse the JSON object to validate it
+    try:
+        parsed_json = json.loads(json_object)
+    except json.JSONDecodeError:
+        return {"error": "Failed to parse JSON object"}
+
+    # Return the result as a dictionary with positions
+    return {"start": start_pos, "stop": stop_pos, "extracted_json": json_object}
+
+
+def clean_json(bad_json_str):
+    """
+    Clean JSON string by replacing single quotes with double quotes
+
+    """
+    replacements = [
+        ("\\", "\\\\"),
+        ("\n", "\\n"),
+        ("\r", "\\r"),
+        ("\t", "\\t"),
+        ("\b", "\\b"),
+        ("\f", "\\f"),
+        ("[/INST]", "removed_inst"),
+    ]
+
+    s = bad_json_str
+    for old, new in replacements:
+        s = s.replace(old, new)
+    return s
+
+
+# def data_to_html(data, replace_new_lines=False):
+#     if "edsl_version" in data:
+#         _ = data.pop("edsl_version")
+#     if "edsl_class_name" in data:
+#         _ = data.pop("edsl_class_name")
+
+#     from pygments import highlight
+#     from pygments.lexers import JsonLexer
+#     from pygments.formatters import HtmlFormatter
+#     from IPython.display import HTML
+
+#     json_str = json.dumps(data, indent=4, cls=CustomEncoder)
+#     formatted_json = highlight(
+#         json_str,
+#         JsonLexer(),
+#         HtmlFormatter(style="default", full=False, noclasses=False),
+#     )
+#     if replace_new_lines:
+#         formatted_json = formatted_json.replace("\\n", "<br>")
+
+#     return HTML(formatted_json).data
+
+
 def is_gzipped(file_path):
+    """Check if a file is gzipped."""
     try:
         with gzip.open(file_path, "rb") as file:
             file.read(1)  # Try reading a small amount of data
@@ -22,7 +155,7 @@ def is_gzipped(file_path):
 
 
 def hash_value(value: Union[str, int]) -> str:
-    """Hashes a string or integer value using SHA-256."""
+    """Hash a string or integer value using SHA-256."""
     if isinstance(value, str):
         value_bytes = value.encode("utf-8")
     elif isinstance(value, int):
@@ -34,7 +167,7 @@ def hash_value(value: Union[str, int]) -> str:
 
 
 def repair_json(json_string: str) -> str:
-    """Attempts to repair a JSON string that is not valid JSON."""
+    """Attempt to repair a JSON string that is not valid JSON."""
     json_string = json_string.replace("\n", "\\n").replace("\r", "\\r")
     json_string = json_string.replace("'", "\\'")
     json_string = json_string.replace("'", '"')
@@ -45,6 +178,7 @@ def repair_json(json_string: str) -> str:
 
 
 def dict_to_html(d):
+    """Convert a dictionary to an HTML table."""
     # Start the HTML table
     html_table = f'<table border="1">\n<tr><th>{escape("Key")}</th><th>{escape("Value")}</th></tr>\n'
 
@@ -60,29 +194,53 @@ def dict_to_html(d):
 
 
 def is_notebook() -> bool:
+    """Check if the code is running in a Jupyter notebook or Google Colab."""
     try:
         shell = get_ipython().__class__.__name__
         if shell == "ZMQInteractiveShell":
             return True  # Jupyter notebook or qtconsole
+        elif shell == "Shell":  # Google Colab's shell class
+            import sys
+
+            if "google.colab" in sys.modules:
+                return True  # Running in Google Colab
+            return False
         elif shell == "TerminalInteractiveShell":
             return False  # Terminal running IPython
         else:
-            return False  # Other type (e.g., IDLE, PyCharm, etc.)
+            return False  # Other type
     except NameError:
         return False  # Probably standard Python interpreter
 
 
+def file_notice(file_name):
+    """Print a notice about the file being created."""
+    if is_notebook():
+        from IPython.display import HTML, display
+
+        link_text = "Download file"
+        display(
+            HTML(
+                f'<p>File created: {file_name}</p>.<a href="{file_name}" download>{link_text}</a>'
+            )
+        )
+    else:
+        print(f"File created: {file_name}")
+
+
 class HTMLSnippet(str):
-    """
-    Creates an object with html content (`value`).
+    """Create an object with html content (`value`).
+
     `view` method allows you to view the html content in a web browser.
     """
 
     def __init__(self, value):
+        """Initialize the HTMLSnippet object."""
         super().__init__()
         self.value = value
 
     def view(self):
+        """View the HTML content in a web browser."""
         html_content = self.value
 
         # create a tempfile to write the HTML content
@@ -94,12 +252,12 @@ class HTMLSnippet(str):
 
 
 def random_string() -> str:
-    """Generate a random string of fixed length"""
+    """Generate a random string of fixed length."""
     return "".join(random.choice(string.ascii_letters) for i in range(10))
 
 
 def shortname_proposal(question, max_length=None):
-    """Take a question text and generate a slug"""
+    """Take a question text and generate a slug."""
     question = question.lower()
     tokens = question.split()
     stopwords = set(
@@ -138,7 +296,7 @@ def shortname_proposal(question, max_length=None):
 
 
 def text_to_shortname(long_text, forbidden_names=[]):
-    """Creates a slug for the question"""
+    """Create a slug for the question."""
     proposed_name = shortname_proposal(long_text)
     counter = 1
     # make sure the name is unique
@@ -149,7 +307,7 @@ def text_to_shortname(long_text, forbidden_names=[]):
 
 
 def merge_dicts(dict_list):
-    """Merges a list of dictionaries into a single dictionary."""
+    """Merge a list of dictionaries into a single dictionary."""
     result = {}
     all_keys = set()
     for d in dict_list:
@@ -160,7 +318,7 @@ def merge_dicts(dict_list):
 
 
 def extract_json_from_string(s):
-    """Extracts a JSON string from a string."""
+    """Extract a JSON string from a string."""
     # Find the first occurrence of '{'
     start_idx = s.find("{")
     # Find the last occurrence of '}'
@@ -175,6 +333,7 @@ def extract_json_from_string(s):
 
 
 def valid_json(json_string):
+    """Check if a string is valid JSON."""
     try:
         _ = json.loads(json_string)
         return True
@@ -182,12 +341,18 @@ def valid_json(json_string):
         return False
 
 
-def is_valid_variable_name(name):
-    return name.isidentifier() and not keyword.iskeyword(name)
+def is_valid_variable_name(name, allow_name=True):
+    """Check if a string is a valid variable name."""
+    if allow_name:
+        return name.isidentifier() and not keyword.iskeyword(name)
+    else:
+        return (
+            name.isidentifier() and not keyword.iskeyword(name) and not name == "name"
+        )
 
 
 def create_valid_var_name(s, transform_func: Callable = lambda x: x.lower()) -> str:
-    """Creates a valid variable name from a string."""
+    """Create a valid variable name from a string."""
     if transform_func is None:
         transform_func = lambda x: x
 
@@ -221,6 +386,7 @@ def create_valid_var_name(s, transform_func: Callable = lambda x: x.lower()) ->
 
 
 def shorten_string(s, max_length, placeholder="..."):
+    """Shorten a string to a maximum length by removing characters from the middle."""
     if len(s) <= max_length:
         return s
 
@@ -244,3 +410,27 @@ def shorten_string(s, max_length, placeholder="..."):
         end_remove = end_space
 
     return s[:start_remove] + placeholder + s[end_remove:]
+
+
+def write_api_key_to_env(api_key: str) -> str:
+    """
+    Write the user's Expected Parrot key to their .env file.
+
+    If a .env file doesn't exist in the current directory, one will be created.
+
+    Returns a string representing the absolute path to the .env file.
+    """
+    from pathlib import Path
+    from dotenv import set_key
+
+    # Create .env file if it doesn't exist
+    env_path = ".env"
+    env_file = Path(env_path)
+    env_file.touch(exist_ok=True)
+
+    # Write API key to file
+    set_key(env_path, "EXPECTED_PARROT_API_KEY", str(api_key))
+
+    absolute_path_to_env = env_file.absolute().as_posix()
+
+    return absolute_path_to_env

edsl-0.1.40.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.1
+Name: edsl
+Version: 0.1.40
+Summary: Create and analyze LLM-based surveys
+Home-page: https://www.expectedparrot.com/
+License: MIT
+Keywords: LLM,social science,surveys,user research
+Author: Apostolos Filippas
+Author-email: apostolos@expectedparrot.com
+Requires-Python: >=3.9.1,<3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: aiohttp (>=3.9.1,<4.0.0)
+Requires-Dist: anthropic (>=0.23.1,<0.24.0)
+Requires-Dist: azure-ai-inference (>=1.0.0b3,<2.0.0)
+Requires-Dist: black[jupyter] (>=24.4.2,<25.0.0)
+Requires-Dist: boto3 (>=1.34.161,<2.0.0)
+Requires-Dist: google-generativeai (>=0.8.2,<0.9.0)
+Requires-Dist: groq (>=0.9.0,<0.10.0)
+Requires-Dist: jinja2 (>=3.1.2,<4.0.0)
+Requires-Dist: json-repair (>=0.28.4,<0.29.0)
+Requires-Dist: jupyter (>=1.0.0,<2.0.0)
+Requires-Dist: markdown2 (>=2.4.11,<3.0.0)
+Requires-Dist: matplotlib (>=3.8,<3.9)
+Requires-Dist: mistralai (>=1.0.2,<2.0.0)
+Requires-Dist: nest-asyncio (>=1.5.9,<2.0.0)
+Requires-Dist: numpy (>=1.22,<2.0)
+Requires-Dist: openai (>=1.4.0,<2.0.0)
+Requires-Dist: openpyxl (>=3.1.5,<4.0.0)
+Requires-Dist: pandas (>=2.1.4,<3.0.0)
+Requires-Dist: platformdirs (>=4.3.6,<5.0.0)
+Requires-Dist: pydot (>=2.0.0,<3.0.0)
+Requires-Dist: pygments (>=2.17.2,<3.0.0)
+Requires-Dist: pymupdf (>=1.24.4,<2.0.0)
+Requires-Dist: pypdf2 (>=3.0.1,<4.0.0)
+Requires-Dist: pyreadstat (>=1.2.7,<2.0.0)
+Requires-Dist: python-docx (>=1.1.0,<2.0.0)
+Requires-Dist: python-dotenv (>=1.0.0,<2.0.0)
+Requires-Dist: python-pptx (>=1.0.2,<2.0.0)
+Requires-Dist: restrictedpython (>=7.1,<8.0)
+Requires-Dist: rich (>=13.7.0,<14.0.0)
+Requires-Dist: setuptools (<72.0)
+Requires-Dist: simpleeval (>=0.9.13,<0.10.0)
+Requires-Dist: sqlalchemy (>=2.0.23,<3.0.0)
+Requires-Dist: tabulate (>=0.9.0,<0.10.0)
+Requires-Dist: tenacity (>=8.2.3,<9.0.0)
+Requires-Dist: urllib3 (>=1.25.4,<1.27)
+Project-URL: Documentation, https://docs.expectedparrot.com
+Description-Content-Type: text/markdown
+
+# Expected Parrot Domain-Specific Language 
+<p align="center">
+  <img src="https://github.com/expectedparrot/edsl/blob/main/static/logo.png?raw=true" alt="edsl.png" width="100"/>
+</p>
+
+The Expected Parrot Domain-Specific Language (EDSL) package lets you conduct computational social science and market research with AI. Use it to design surveys and experiments, simulate responses with large language models, and perform data labeling and other research tasks. Results are formatted as specified datasets and come with built-in methods for analyzing, visualizing, and sharing. 
+
+## 🔗 Links
+- [PyPI](https://pypi.org/project/edsl/)
+- [Documentation](https://docs.expectedparrot.com)
+- [Getting started](https://docs.expectedparrot.com/en/latest/starter_tutorial.html) 
+- [Discord](https://discord.com/invite/mxAYkjfy9m)
+- [Twitter](https://x.com/ExpectedParrot)
+- [LinkedIn](https://www.linkedin.com/company/expectedparrot/)
+- [Blog](https://blog.expectedparrot.com)
+
+## 🌎 Hello, World!
+A quick example:
+
+```python
+# Import a question type
+from edsl import QuestionMultipleChoice
+
+# Construct a question using the question type template
+q = QuestionMultipleChoice(
+    question_name="example_question",
+    question_text="How do you feel today?",
+    question_options=["Bad", "OK", "Good"]
+)
+
+# Run it with the default language model
+results = q.run()
+
+# Inspect the results 
+results.select("example_question")
+```
+
+Output:
+```python
+┏━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ answer.example_question ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ Good                    │
+└─────────────────────────┘
+```
+
+## 💻 Requirements
+* EDSL is compatible with Python 3.9 - 3.12.
+* API keys for large language models that you want to use, stored in a `.env` file.
+See instructions on [storing API keys](https://docs.expectedparrot.com/en/latest/api_keys.html) and [activating remote inference](https://docs.expectedparrot.com/en/latest/remote_inference.html).
+
+## 💡 Contributions, feature requests & bugs
+Interested in contributing? Want us to add a new feature? Found a bug for us to squash? 
+Please send us an email at [info@expectedparrot.com](mailto:info@expectedparrot.com) or message us at our [Discord channel](https://discord.com/invite/mxAYkjfy9m).
+