edsl 0.1.27.dev2__py3-none-any.whl → 0.1.28__py3-none-any.whl

edsl/surveys/Survey.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 import re
+
 from typing import Any, Generator, Optional, Union, List, Literal, Callable
 
 from rich import print
@@ -88,7 +89,7 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         >>> s = Survey.example()
         >>> s.get_question("q0")
-        Question('multiple_choice', question_name = 'q0', question_text = 'Do you like school?', question_options = ['yes', 'no'])
+        Question('multiple_choice', question_name = \"""q0\""", question_text = \"""Do you like school?\""", question_options = ['yes', 'no'])
         """
         if question_name not in self.question_name_to_index:
             raise KeyError(f"Question name {question_name} not found in survey.")
@@ -101,6 +102,16 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         # warnings.warn("survey.get_question is deprecated. Use subscript operator instead.")
         return self.get(question_name)
 
+    def __hash__(self) -> int:
+        """Return a hash of the question."""
+        from edsl.utilities.utilities import dict_hash
+
+        return dict_hash(self._to_dict())
+
+    @property
+    def parameters(self):
+        return set.union(*[q.parameters for q in self.questions])
+
     @property
     def question_names(self) -> list[str]:
         """Return a list of question names in the survey.
@@ -528,7 +539,7 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
     ###################
     # FORWARD METHODS
     ###################
-    def by(self, *args: Union[Agent, Scenario, LanguageModel]) -> Jobs:
+    def by(self, *args: Union["Agent", "Scenario", "LanguageModel"]) -> "Jobs":
         """Add Agents, Scenarios, and LanguageModels to a survey and returns a runnable Jobs object.
 
         :param args: The Agents, Scenarios, and LanguageModels to add to the survey.
@@ -551,9 +562,7 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         >>> from edsl import QuestionFreeText
         >>> s = Survey([QuestionFreeText.example()])
-        >>> results = s.run(debug = True)
-        >>> results
-        Results(...)
+        >>> results = s.run(debug = True, cache = False)
         >>> results.select('answer.*').print(format = "rich")
         ┏━━━━━━━━━━━━━━┓
         ┃ answer       ┃
@@ -640,18 +649,17 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         >>> i = s.gen_path_through_survey()
         >>> next(i)
-        Question('multiple_choice', question_name = 'q0', question_text = 'Do you like school?', question_options = ['yes', 'no'])
+        Question('multiple_choice', question_name = \"""q0\""", question_text = \"""Do you like school?\""", question_options = ['yes', 'no'])
         >>> i.send({"q0": "yes"})
-        Question('multiple_choice', question_name = 'q2', question_text = 'Why?', question_options = ['**lack*** of killer bees in cafeteria', 'other'])
+        Question('multiple_choice', question_name = \"""q2\""", question_text = \"""Why?\""", question_options = ['**lack*** of killer bees in cafeteria', 'other'])
 
         And here is the path through the survey if the answer to q0 is 'no':
 
         >>> i2 = s.gen_path_through_survey()
         >>> next(i2)
-        Question('multiple_choice', question_name = 'q0', question_text = 'Do you like school?', question_options = ['yes', 'no'])
+        Question('multiple_choice', question_name = \"""q0\""", question_text = \"""Do you like school?\""", question_options = ['yes', 'no'])
         >>> i2.send({"q0": "no"})
-        Question('multiple_choice', question_name = 'q1', question_text = 'Why not?', question_options = ['killer bees in cafeteria', 'other'])
-
+        Question('multiple_choice', question_name = \"""q1\""", question_text = \"""Why not?\""", question_options = ['killer bees in cafeteria', 'other'])
         """
         question = self._first_question()
         while not question == EndOfSurvey:
@@ -761,7 +769,7 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
 
         >>> s = Survey.example()
         >>> s[0]
-        Question('multiple_choice', question_name = 'q0', question_text = 'Do you like school?', question_options = ['yes', 'no'])
+        Question('multiple_choice', question_name = \"""q0\""", question_text = \"""Do you like school?\""", question_options = ['yes', 'no'])
 
         """
         if isinstance(index, int):
@@ -802,22 +810,33 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
     ###################
     # SERIALIZATION METHODS
     ###################
-    @add_edsl_version
-    def to_dict(self) -> dict[str, Any]:
+
+    def _to_dict(self) -> dict[str, Any]:
         """Serialize the Survey object to a dictionary.
 
         >>> s = Survey.example()
-        >>> s.to_dict().keys()
-        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups', 'edsl_version', 'edsl_class_name'])
+        >>> s._to_dict().keys()
+        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups'])
 
         """
         return {
-            "questions": [q.to_dict() for q in self._questions],
+            "questions": [q._to_dict() for q in self._questions],
             "memory_plan": self.memory_plan.to_dict(),
             "rule_collection": self.rule_collection.to_dict(),
             "question_groups": self.question_groups,
         }
 
+    @add_edsl_version
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize the Survey object to a dictionary.
+
+        >>> s = Survey.example()
+        >>> s.to_dict().keys()
+        dict_keys(['questions', 'memory_plan', 'rule_collection', 'question_groups', 'edsl_version', 'edsl_class_name'])
+
+        """
+        return self._to_dict()
+
     @classmethod
     @remove_edsl_version
     def from_dict(cls, data: dict) -> Survey:
@@ -891,7 +910,7 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         """Print the survey in a rich format.
 
         >>> t = Survey.example().rich_print()
-        >>> print(t)
+        >>> print(t) # doctest: +SKIP
         ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
         ┃ Questions                                                                                          ┃
         ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
@@ -938,7 +957,7 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         :param filename: The name of the file to save the CSV to.
 
         >>> s = Survey.example()
-        >>> s.to_csv()
+        >>> s.to_csv() # doctest: +SKIP
            index question_name        question_text                                question_options    question_type
         0      0            q0  Do you like school?                                       [yes, no]  multiple_choice
         1      1            q1             Why not?               [killer bees in cafeteria, other]  multiple_choice
@@ -1003,30 +1022,59 @@ class Survey(SurveyExportMixin, SurveyFlowVisualizationMixin, Base):
         s = s.add_rule(q0, "q0 == 'yes'", q2)
         return s
 
-    def __call__(self, *args, **kwargs):
+    def get_job(self, model=None, agent=None, **kwargs):
+        if not model:
+            from edsl import Model
+
+            model = Model()
+
+        from edsl.scenarios.Scenario import Scenario
+
+        s = Scenario(kwargs)
+
+        if not agent:
+            from edsl import Agent
+
+            agent = Agent()
+
+        return self.by(s).by(agent).by(model)
+
+    def __call__(self, model=None, agent=None, cache=None, **kwargs):
         """Run the survey with default model, taking the required survey as arguments.
 
         >>> from edsl.questions import QuestionFunctional
         >>> def f(scenario, agent_traits): return "yes" if scenario["period"] == "morning" else "no"
         >>> q = QuestionFunctional(question_name = "q0", func = f)
         >>> s = Survey([q])
-        >>> s(period = "morning").select("answer.q0").first()
+        >>> s(period = "morning", cache = False).select("answer.q0").first()
         'yes'
-        >>> s(period = "evening").select("answer.q0").first()
+        >>> s(period = "evening", cache = False).select("answer.q0").first()
         'no'
         """
-        if "model" in kwargs:
-            model = kwargs["model"]
-            del kwargs["model"]
-        else:
-            from edsl import Model
+        job = self.get_job(model, agent, **kwargs)
+        return job.run(cache=cache)
 
-            model = Model()
-        from edsl.scenarios.Scenario import Scenario
+    async def run_async(self, model=None, agent=None, cache=None, **kwargs):
+        """Run the survey with default model, taking the required survey as arguments.
 
-        s = Scenario(kwargs)
+        >>> from edsl.questions import QuestionFunctional
+        >>> def f(scenario, agent_traits): return "yes" if scenario["period"] == "morning" else "no"
+        >>> q = QuestionFunctional(question_name = "q0", func = f)
+        >>> s = Survey([q])
+        >>> s(period = "morning").select("answer.q0").first()
+        'yes'
+        >>> s(period = "evening").select("answer.q0").first()
+        'no'
+        """
+        # TODO: temp fix by creating a cache
+        if cache is None:
+            from edsl.data import Cache
 
-        return self.by(s).by(model).run()
+            c = Cache()
+        else:
+            c = cache
+        jobs: "Jobs" = self.get_job(model, agent, **kwargs)
+        return await jobs.run_async(cache=c)
 
 
 def main():
@@ -1066,4 +1114,4 @@ def main():
 if __name__ == "__main__":
     import doctest
 
-    doctest.testmod(optionflags=doctest.ELLIPSIS)
+    doctest.testmod(optionflags=doctest.ELLIPSIS | doctest.SKIP)

edsl/surveys/SurveyExportMixin.py

@@ -13,6 +13,20 @@ class SurveyExportMixin:
 
         return SurveyCSS.default_style().generate_css()
 
+    def get_description(self) -> str:
+        """Return the description of the survey."""
+        from edsl import QuestionFreeText
+
+        question_texts = "\n".join([q.question_text for q in self._questions])
+        q = QuestionFreeText(
+            question_name="description",
+            question_text=f"""A survey was conducted with the following questions: 
+                             {question_texts}
+                             Please write a description of the survey.
+                             """,
+        )
+        return q.run().select("description").first()
+
     def docx(self, filename=None) -> Union["Document", None]:
         """Generate a docx document for the survey."""
         doc = Document()
@@ -60,10 +74,14 @@ class SurveyExportMixin:
         :param filename: The name of the file to save the code to.
         :param survey_var_name: The name of the survey variable.
 
+        >>> from edsl.surveys import Survey
         >>> survey = Survey.example()
-        >>> survey.code()
-
-
+        >>> print(survey.code())
+        from edsl.surveys.Survey import Survey
+        ...
+        ...
+        survey = Survey(questions=[q0, q1, q2])
+        ...
         """
         header_lines = ["from edsl.surveys.Survey import Survey"]
         header_lines.append("from edsl import Question")

edsl/utilities/__init__.py

@@ -18,4 +18,5 @@ from edsl.utilities.utilities import (
     random_string,
     repair_json,
     shorten_string,
+    time_all_functions,
 )

edsl/utilities/gcp_bucket/cloud_storage.py

@@ -0,0 +1,96 @@
+import requests
+
+
+class CloudStorageManager:
+    def __init__(self, secret_token=None):
+        self.api_url = "https://bucket-server-tte53lsfxq-uc.a.run.app"
+        self.secret_token = secret_token
+
+    def get_signed_url(self, file_name, operation="upload"):
+        """Get a signed URL for uploading or downloading a file."""
+
+        if operation == "upload":
+            if self.secret_token == None:
+                raise "Set secret_token for upload permissions"
+            headers = {
+                "Authorization": self.secret_token,
+                "Content-Type": "application/json",
+            }
+        else:
+            headers = {
+                "Content-Type": "application/json",
+            }
+        data = {"file_name": file_name}
+        endpoint = f"{self.api_url}/generate-{operation}-signed-url"
+        response = requests.post(endpoint, json=data, headers=headers)
+
+        if response.status_code == 200:
+            return response.json().get("signed_url")
+        else:
+            raise Exception(
+                f"Failed to get signed URL: {response.status_code} {response.text}"
+            )
+
+    def upload_file(self, file_path, upload_file_name):
+        """Upload a file to the signed URL."""
+        signed_url = self.get_signed_url(upload_file_name, operation="upload")
+
+        with open(file_path, "rb") as file:
+            upload_response = requests.put(
+                signed_url,
+                data=file,
+                headers={"Content-Type": "application/octet-stream"},
+            )
+
+            if upload_response.status_code == 200:
+                print("File uploaded successfully")
+            else:
+                raise Exception(
+                    f"Failed to upload file: {upload_response.status_code} {upload_response.text}"
+                )
+
+    def download_file(self, file_name, save_name):
+        """Download a file from the signed URL."""
+
+        signed_url = self.get_signed_url(file_name, operation="download")
+        download_response = requests.get(signed_url, stream=True)
+
+        if download_response.status_code == 200:
+            with open(save_name, "wb") as file:
+                for chunk in download_response.iter_content(chunk_size=8192):
+                    file.write(chunk)
+            print("File downloaded successfully")
+        else:
+            raise Exception(
+                f"Failed to download file: {download_response.status_code} {download_response.text}"
+            )
+
+    def delete_file(self, file_name):
+        """Delete a file from the cloud storage."""
+        headers = {
+            "Authorization": self.secret_token,
+            "Content-Type": "application/json",
+        }
+        data = {"file_name": file_name}
+        endpoint = f"{self.api_url}/delete-file"
+        response = requests.delete(endpoint, params=data, headers=headers)
+
+        if response.status_code == 200:
+            print("File deleted successfully")
+        else:
+            raise Exception(
+                f"Failed to delete file: {response.status_code} {response.text}"
+            )
+
+    def list_files(self):
+        url = self.api_url + "/list_files"
+        headers = {
+            "Authorization": self.secret_token,
+            "Content-Type": "application/json",
+        }
+        res = requests.get(url, headers=headers)
+        data = res.json()
+        for x in data["data"]:
+            x["url"] = self.api_url + "/file/" + x["shaKey"]
+
+        return data

edsl/utilities/gcp_bucket/simple_example.py

@@ -0,0 +1,9 @@
+from edsl.utilities.gcp_bucket.cloud_storage import CloudStorageManager
+
+manager = CloudStorageManager()
+
+# Download Process
+file_name = "GSS2022.dta"  # Name for the downloaded file
+save_name = "test.dta"
+
+manager.download_file(file_name, save_name)

edsl/utilities/interface.py

@@ -331,15 +331,15 @@ def create_latex_table_from_data(data, filename=None, split_at_dot=True):
 
     >>> data = [{"a": [1, 2, 3], "b": [4, 5, 6]}]
     >>> print(create_latex_table_from_data(data))
-    \begin{tabular}{|c|c|}
-    \hline
-    a & b \\
-    \hline
-    1 & 4 \\
-    2 & 5 \\
-    3 & 6 \\
-    \hline
-    \end{tabular}
+    \\begin{tabular}{|c|c|}
+    \\hline
+    a & b \\\\
+    \\hline
+    1 & 4 \\\\
+    2 & 5 \\\\
+    3 & 6 \\\\
+    \\hline
+    \\end{tabular}
     """
 
     def escape_latex(s):
@@ -379,7 +379,7 @@ def create_latex_table_from_data(data, filename=None, split_at_dot=True):
     num_rows = len(next(iter(data[0].values())))
 
     # Debugging: Print the keys of the dictionaries
-    print("Keys in data[0]:", list(data[0].keys()))
+    # print("Keys in data[0]:", list(data[0].keys()))
 
     # Add the data rows
     for i in range(num_rows):
@@ -410,9 +410,7 @@ def create_latex_table_from_data(data, filename=None, split_at_dot=True):
     return latex_table_str
 
 
-def print_list_of_dicts_as_html_table(
-    data, filename=None, interactive=True, notebook=False
-):
+def print_list_of_dicts_as_html_table(data, interactive=True):
     """Print a list of dictionaries as an HTML table.
 
     :param data: The list of dictionaries to print.
@@ -459,20 +457,7 @@ def print_list_of_dicts_as_html_table(
     # Close the table
     html_table += "</tbody>\n"
     html_table += "</table>"
-
-    html = gen_html_sandwich(html_table, interactive=interactive)
-
-    # Output or save to file
-    if filename:
-        with open(filename, "w") as f:
-            f.write(html)
-    else:
-        # view_html(html)
-        if notebook:
-            # ipython_diplay(HTML(html))
-            return html
-        else:
-            print(html)
+    return gen_html_sandwich(html_table, interactive=interactive)
 
 
 def print_list_of_dicts_as_markdown_table(data, filename=None):
@@ -486,7 +471,11 @@ def print_list_of_dicts_as_markdown_table(data, filename=None):
         return
 
     # Gather all unique headers
-    headers = list({key for d in data for key in d.keys()})
+    # headers = list({key for d in data for key in d.keys()})
+    headers = []
+    for column in data:
+        headers.append(list(column.keys())[0])
+
     markdown_table = "| " + " | ".join(headers) + " |\n"
     markdown_table += "|-" + "-|-".join(["" for _ in headers]) + "-|\n"
 
@@ -527,6 +516,13 @@ def print_tally_with_rich(data, filename=None):
     Example:
     >>> data = {'a':12, 'b':14, 'c':9}
     >>> print_tally_with_rich(data)
+    ┏━━━━━━━┳━━━━━━━┓
+    ┃ Value ┃ Count ┃
+    ┡━━━━━━━╇━━━━━━━┩
+    │ a     │ 12    │
+    │ b     │ 14    │
+    │ c     │ 9     │
+    └───────┴───────┘
     """
     # Initialize a console object
     console = Console(record=True)

edsl/utilities/repair_functions.py

@@ -0,0 +1,28 @@
+import json
+from edsl.utilities.utilities import valid_json
+
+
+def extract_json_from_string(s):
+    """Extract a JSON string from a string."""
+    # Find the first occurrence of '{'
+    start_idx = s.find("{")
+    # Find the last occurrence of '}'
+    end_idx = s.rfind("}")
+    # If both '{' and '}' are found in the string
+    if start_idx != -1 and end_idx != -1 and start_idx < end_idx:
+        # Extract the substring from start_idx to end_idx (inclusive)
+        json_str = s[start_idx : end_idx + 1]
+        try:
+            return json.loads(json_str)
+        except json.JSONDecodeError:
+            raise ValueError("Invalid JSON string")
+    else:
+        raise ValueError("No JSON object found in string")
+
+
+if __name__ == "__main__":
+    text = (
+        'Sure - here is some JSON { "key": "value", "number": 123, "array": [1, 2, 3] }'
+    )
+    extracted_json = extract_json_from_string(text)
+    d = extracted_json

edsl/utilities/utilities.py

@@ -19,6 +19,55 @@ from pygments.lexers import JsonLexer
 from pygments.formatters import HtmlFormatter
 from IPython.display import HTML
 
+from functools import wraps
+import types
+import time
+
+
+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)
+    )
+
+
+import re
+import json
+
+
+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 clean_json(bad_json_str):
     """
@@ -32,6 +81,7 @@ def clean_json(bad_json_str):
         ("\t", "\\t"),
         ("\b", "\\b"),
         ("\f", "\\f"),
+        ("[/INST]", "removed_inst"),
     ]
 
     s = bad_json_str
@@ -233,9 +283,14 @@ def valid_json(json_string):
         return False
 
 
-def is_valid_variable_name(name):
+def is_valid_variable_name(name, allow_name=True):
     """Check if a string is a valid variable name."""
-    return name.isidentifier() and not keyword.iskeyword(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:

{edsl-0.1.27.dev2.dist-info → edsl-0.1.28.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: edsl
-Version: 0.1.27.dev2
+Version: 0.1.28
 Summary: Create and analyze LLM-based surveys
 Home-page: https://www.expectedparrot.com/
 License: MIT
@@ -30,6 +30,7 @@ Requires-Dist: pandas (>=2.1.4,<3.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: 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: restrictedpython (>=7.1,<8.0)
@@ -45,28 +46,53 @@ Description-Content-Type: text/markdown
   <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. EDSL comes with built-in methods for analyzing, visualizing and sharing your results. 
+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
+- [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)
 
+## 💡 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).
 
-## 💡 Contributions, Feature Requests & Bugs
-Interested in contributing? Want us to add a new feature? Found a nasty bug that you would like us to squash? Please send us an email at info@expectedparrot.com or message us at our Discord server.
+## 💻 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).
 
+## 🌎 Hello, World!
+A quick example:
 
-## 💻 Getting started
-EDSL is compatible with Python 3.9 - 3.12.
-```
-pip install edsl
-```
+```python
+# Import a question type
+from edsl.questions import QuestionMultipleChoice
 
-- Read the docs at http://docs.expectedparrot.com.
-- See https://docs.expectedparrot.com/en/latest/starter_tutorial.html for examples and tutorials.
+# 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"]
+)
 
-## 🔧 Dependencies
-API keys for LLMs that you want to use, stored in a `.env` file
+# Run it with the default language model
+results = q.run()
 
+# Inspect the results in a dataset
+results.select("example_question").print()
+```
+
+Output:
+```python
+┏━━━━━━━━━━━━━━━━━━━┓
+┃ answer            ┃
+┃ .example_question ┃
+┡━━━━━━━━━━━━━━━━━━━┩
+│ Good              │
+└───────────────────┘
+```