Updating docs

CHANGELOG.md

@@ -21,9 +21,9 @@
 
 - `ScenarioList` method `give_valid_names()` allows you to automatically generate valid Pythonic identifiers for scenario keys. 
 
-- `ScenarioList` method `group_by()` allows you to group scenarios by specified identifies and apply a function to the values of the specified variables.
+- `ScenarioList` method `group_by()` allows you to group scenarios by specified identities and apply a function to the values of the specified variables.
 
-- `ScenarioList` method `from_wikipedia_table()` allows you to convert a Wikipedia table into a scenario list. Example usage: https://www.expectedparrot.com/content/247589dd-ad1e-45f4-9c82-e71dbeac8c96 (Notebook: *Using an LLM to Augment Existing Tabular Data*)
+- `ScenarioList` method `from_wikipedia_table()` allows you to convert a Wikipedia table into a scenario list. Example usage: https://docs.expectedparrot.com/en/latest/notebooks/scenario_list_wikipedia.html
 
 - `ScenarioList` method `to_docx()` allows you to export scenario lists as structured Docx documents.
 
@@ -35,7 +35,7 @@
 
 - `Results` methods `generate_html` and `save_html` can be called to generate and save HTML code for displaying results.
 
-- Ability to run a `Model` with a boolean parameter `raise_validation_errors = False` or `raise_validation_errors = True`. If False, exceptions will only be raised (interrupting survey execution) when the model returns nothing at all.
+- Ability to run a `Model` with a boolean parameter `raise_validation_errors = False` or `raise_validation_errors = True`. If False, exceptions will only be raised (interrupting survey execution) when the model returns nothing at all. Another optional parameter `print_exceptions = False` can be passed to not print exceptions at all.
 
 ### Changed
 - Improvements to exceptions reports. 

docs/conf.py

@@ -82,4 +82,6 @@ def setup(app):
     "github_user": "",
     "github_repo": "",
     "github_version": "",
-}
+}
+
+nbsphinx_allow_errors = True

docs/exceptions.rst

@@ -4,67 +4,7 @@ Exceptions & Debugging
 ======================
 
 An exception is an error that occurs during the execution of a question or survey. 
-When an exception is raised, EDSL will display a message about the error that includes a link to a report with more details.
-
-Example 
--------
-
-Here's an example of a poorly written question that is likely to raise an exception:
-
-.. code-block:: python
-
-    from edsl.questions import QuestionMultipleChoice
-
-    q = QuestionMultipleChoice(
-        question_name = "bad_instruction",
-        question_text = "What is your favorite color?",
-        question_options = ["breakfast", "lunch", "dinner"] # Non-sensical options for the question
-    )
-
-    results = q.run()
-
-
-The above code will likely raise a `QuestionAnswerValidationError` exception because the question options are not related to the question text.
-Output:
-
-.. code-block:: text
-
-    Attempt 1 failed with exception:Answer code must be a string, a bytes-like object or a real number (got Invalid). now waiting 1.00 seconds before retrying.Parameters: start=1.0, max=60.0, max_attempts=5.
-
-
-    Attempt 2 failed with exception:Answer code must be a string, a bytes-like object or a real number (got The question asks for a favorite color, but the options provided are meal times, not colors. Therefore, I cannot select an option that accurately reflects a favorite color.). now waiting 2.00 seconds before retrying.Parameters: start=1.0, max=60.0, max_attempts=5.
-
-
-    Attempt 3 failed with exception:Answer code must be a string, a bytes-like object or a real number (got The question does not match the provided options as they pertain to meals, not colors.). now waiting 4.00 seconds before retrying.Parameters: start=1.0, max=60.0, max_attempts=5.
-
-
-    Attempt 4 failed with exception:Answer code must be a string, a bytes-like object or a real number (got This is an invalid question since colors are not listed as options. The options provided are meals, not colors.). now waiting 8.00 seconds before retrying.Parameters: start=1.0, max=60.0, max_attempts=5.
-
-
-    Exceptions were raised in 1 out of 1 interviews.
-
-    Open report to see details.
-
-
-Exceptions report 
------------------
-
-The exceptions report can be accessed by clicking on the link provided in the exceptions message.
-It contains details on the exceptions that were raised:
-
-.. image:: /static/exceptions_message.png
-    :width: 800
-    :align: center
-
-
-Performance plot 
-^^^^^^^^^^^^^^^^
-
-The report includes a Performance Plot with graphical details about the API calls that were made (started, failed, in progress, canceled, etc.; scroll to the end of the report to view it):
-
-.. image:: /static/exceptions_performance_plot.png
-    :width: 800
-    :align: center
+When an exception is raised, EDSL will display a message about the error and an interactive report with more details in a new browser tab.
 
 
 Help debugging
@@ -77,16 +17,12 @@ You can use the following code to generate a link to your notebook:
 
 .. code-block:: python
 
-    from edsl import Coop, notebook
-
-    coop = Coop()
-
-    notebook = Notebook(path="path/to/your/notebook.ipynb")
+    from edsl import notebook
 
-    coop.create(notebook, description="Notebook with code that raises an exception", visibility="private")
+    n = Notebook(path="path/to/your/notebook.ipynb")
 
+    n.push(description="Notebook with code that raises an exception", visibility="private")
 
-A notebook showing the above example question and exception message is available at the Coop: https://www.expectedparrot.com/content/f6a19c77-3f57-4900-b0c9-436058a2ad27
 
 
 Common exceptions
@@ -113,14 +49,6 @@ The default settings (which can be modified) are as follows:
     MAX_QUESTION_LENGTH = 100000
 
 
-JSON errors
-^^^^^^^^^^^
-
-Some exceptions may indicate that the response from the language model is not properly formatted JSON.
-This can be caused by a problem with the inference provider or the way that the question has been constructed (e.g., the model is not capable of following the question prompts as written).
-A useful starting point for debugging these exceptions is to check the `Settings` class for the `Questions` model (see *Answer validation errors* above) and try variations in the question prompts and types (e.g., does `QuestionFreeText` produce an answer to the same question formatted as a different question type).
-
-
 Missing API key 
 ^^^^^^^^^^^^^^^
 

docs/index.rst

@@ -66,7 +66,7 @@ Working with Results
 - :ref:`results`: Access built-in methods for analyzing and utilizing survey results as datasets.
 - :ref:`caching`: Learn about caching and sharing results.
 - :ref:`exceptions`: Identify and handle exceptions in your survey design.
-- :ref:`token_limits`: Manage token limits for language models.
+- :ref:`token_usage`: Manage token limits for language models, and monitor and reduce token usage as desired.
 
 Coop 
 ----
@@ -147,7 +147,7 @@ Information about additional functionality for developers.
    results
    data
    exceptions
-   token_limits
+   token_usage
 
 .. toctree::
    :maxdepth: 2
@@ -171,6 +171,7 @@ Information about additional functionality for developers.
    :caption: How-to Guides
    :hidden:
 
+   notebooks/edsl_intro.ipynb
    notebooks/data_labeling_example.ipynb
    notebooks/image_scenario_example.ipynb
    notebooks/question_loop_scenario.ipynb
@@ -190,6 +191,7 @@ Information about additional functionality for developers.
    :caption: Notebooks
    :hidden:
 
+   notebooks/next_token_probs.ipynb
    notebooks/scenariolist_unpivot.ipynb
    notebooks/nps_survey.ipynb
    notebooks/agentifying_responses.ipynb