Merge branch 'main' into automate_pypi_deploy

expectedparrot · Jan 7, 2025 · a50dc60 · a50dc60
2 parents af63ee3 + 97b823a
commit a50dc60
Show file tree

Hide file tree

Showing 7 changed files with 305 additions and 75 deletions.
diff --git a/docs/agents.rst b/docs/agents.rst
@@ -212,7 +212,9 @@ Dynamic traits function
 Agents can also be created with a `dynamic_traits_function` parameter. 
 This function can be used to generate traits dynamically based on the question being asked or the scenario in which the question is asked.
 
-For example:
+*Note:* This method is only available with local inference. It does not work with remote inference.
+
+Example:
 
 .. code-block:: python
 

diff --git a/docs/notebooks/starter_tutorial.ipynb b/docs/notebooks/starter_tutorial.ipynb
@@ -12,31 +12,53 @@
    },
    "source": [
     "# Starter Tutorial\n",
-    "This tutorial provides example code for getting started using **EDSL**, an open-source Python library for simulating surveys, experiments and other research tasks with AI agents and large language models. EDSL is available under the MIT License at [PyPI](https://pypi.org/project/edsl/) and [GitHub](https://github.com/expectedparrot/edsl). \n",
     "\n",
-    "In the steps below we show how to construct and run a simple question in EDSL, and then how to design more complex surveys with AI agent personas and multiple language models.\n",
-    "We also demonstrate methods for applying logic and rules to surveys, piping answers into questions, adding data to questions and analyzing survey results as datasets.\n",
+    "This tutorial provides step-by-step instructions for getting started using EDSL (*Expected Parrot Domain-Specific Language*), an open-source Python library for simulating surveys, experiments and other research tasks using AI agents and large language models.\n",
+    "EDSL is developed by [Expected Parrot](https://www.expectedparrot.com/about) and available under the MIT License.\n",
+    "The source code is hosted on [GitHub](https://github.com/expectedparrot/edsl). \n",
     "\n",
-    "We also show how to post and share content that you create at **Coop**, a platform for creating, storing and collaborating on AI-based research. Coop is fully integrated with EDSL and free to use. Create an account [here](https://www.expectedparrot.com/login).\n",
+    "## Goals of this tutorial\n",
+    "We begin with technical setup: instructions for installing the EDSL library and storing API keys to access language models.\n",
+    "Then we demonstrate some of the basic features of EDSL, with examples for constructing and running surveys with agents and models, and analyzing responses as datasets.\n",
+    "By the end of this tutorial, you will be able to use EDSL to do each of the following:\n",
     "\n",
-    "Please also see our [documentation page](https://docs.expectedparrot.com) for more details on the topics covered in this notebook.\n",
-    "If you encounter any issues or have questions, please email us at info@expectedparrot.com or post a question at our [Discord channel](https://discord.com/invite/mxAYkjfy9m)."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "5f8fd10f-8925-4c58-8559-2339125d6875",
-   "metadata": {},
-   "source": [
-    "## Technical setup\n",
-    "To run the examples below you first need to install the EDSL library and choose how you want to access language models.\n",
+    "* Construct various types of questions tailored to your research objectives.\n",
+    "* Combine questions into surveys and integrate logical rules to control the survey flow.\n",
+    "* Design personas for AI agents to simulate responses to your surveys.\n",
+    "* Choose and deploy large language models to generate responses for AI agents.\n",
+    "* Analyze responses as datasets with built-in analytical tools.\n",
+    "\n",
+    "## Storing & sharing your work\n",
+    "We also introduce [Coop](https://www.expectedparrot.com/content/explore): a platform for creating, storing and sharing AI-based research.\n",
+    "Coop is fully integrated with EDSL and free to use. \n",
+    "At the end of the tutorial we show how to use EDSL with Coop by posting content created in this tutorial for anyone to view at the web app.\n",
+    "\n",
+    "## Further reading & questions\n",
+    "Please see our [documentation page](https://docs.expectedparrot.com) for more details on each of the topics covered in this notebook.\n",
+    "If you encounter any issues or have questions, please email us at info@expectedparrot.com or post a question at our [Discord channel](https://discord.com/invite/mxAYkjfy9m).\n",
+    "\n",
+    "## Pre-requisites\n",
+    "EDSL is compatible with Python 3.9 - 3.12.\n",
+    "Before starting this tutorial, please ensure that you have a Python environment set up on your machine or in a cloud-based environment, such as Google Colab.\n",
+    "You can find instructions for installing Python at the [Python Software Foundation](https://www.python.org/downloads/).\n",
     "\n",
-    "*Note: If you are using EDSL in Google Colab, please see the [Colab setup](https://docs.expectedparrot.com/en/latest/colab_setup.html) page for additional instructions.*\n",
+    "## Recommendations \n",
+    "The code examples in this tutorial are designed to be run in a Jupyter notebook or another Python environment, or in a cloud-based environment such as Google Colab.\n",
     "\n",
+    "If you are using Google Colab, please see additional instructions for setting up EDSL in the [Colab setup](https://docs.expectedparrot.com/en/latest/colab_setup.html) page in the documentation.\n",
     "\n",
-    "### Install EDSL\n",
-    "Uncomment and run the following code to install the EDSL library. \n",
-    "See installation [instructions](https://docs.expectedparrot.com/en/latest/installation.html) for more details."
+    "We also recommend using a virtual environment when installing and using EDSL in order to avoid conflicts with other Python packages.\n",
+    "You can find instructions for setting up a virtual environment at the [Python Packaging Authority](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/).\n",
+    "\n",
+    "## Installation\n",
+    "To begin using EDSL, you first need to install the library. \n",
+    "This can either be done locally on your machine or in a cloud-based environment, such as Google Colab.\n",
+    "Once you have decided where to install EDSL, you can choose to whether install it from [PyPI](https://pypi.org/project/edsl/) or [GitHub](https://github.com/expectedparrot/edsl):\n",
+    "\n",
+    "### From PyPI\n",
+    "Install EDSL directly using `pip`, which is straightforward and recommended for most users. \n",
+    "We also recommend using a virtual environment to manage your Python packages (see *Recommendations* above).\n",
+    "Uncomment and run the following command to install EDSL from PyPI:"
    ]
   },
   {
@@ -87,23 +109,82 @@
   },
   {
    "cell_type": "markdown",
-   "id": "0f66434e-2777-45ae-9807-e283d9bdb593",
+   "id": "04e0ca02-fb3e-4137-9165-e5b4f656b6ad",
    "metadata": {},
    "source": [
-    "### Choose how to access language models\n",
-    "Next, decide how you want to access language models with EDSL and obtain the required API keys:\n",
+    "### From GitHub\n",
+    "You can find the source code for EDSL and contribute to the project at [GitHub](https://github.com/expectedparrot/edsl).\n",
+    "Installing from GitHub allows you to get the latest updates to EDSL before they are released to a new version at PyPI.\n",
+    "This is recommended if you are using new features or contributing to the project.\n",
+    "Uncomment and run the following command to install EDSL from GitHub:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a0fc28f0-a52a-46c2-9a31-9321f0cf35ba",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# pip install git+https://github.com/expectedparrot/edsl.git@main"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4b2a4f5c-439a-41f5-9a52-aedc61ef4afc",
+   "metadata": {},
+   "source": [
+    "## Accessing Language Models\n",
+    "\n",
+    "The next step is to decide how you want to access language models for running surveys.\n",
+    "EDSL works with many popular language models that you can choose from to generate responses to your surveys.\n",
+    "These models are hosted by various service providers, such as Anthropic, Azure, Bedrock, Deep Infra, Google, Groq, Mistral, OpenAI, Replicate and Together.\n",
+    "In order to run a survey, you need to provide API keys for the service providers of models that you want to use.\n",
+    "There are two methods for providing API keys to EDSL:\n",
+    "\n",
+    "### Remote inference\n",
+    "This method allows you to use a single API key from Expected Parrot to access all available language models at once, and to run your surveys remotely at the Expected Parrot server.\n",
+    "It is convenient for quickly accessing a wide range of models without needing to create accounts and set up individual API keys with service providers.\n",
+    "It also allows you to automatically store your survey data on the Expected Parrot server to access it anywhere and share it with other users.\n",
+    "\n",
+    "To use remote inference:\n",
+    "\n",
+    "1. Create or log in to your Coop account: https://www.expectedparrot.com/login\n",
+    "2. Navigate to your [Settings](https://www.expectedparrot.com/settings) page. Copy your Expected Parrot API key and activate remote inference.\n",
+    "3. Create a file named *.env* in your working directory and add the following code to it (replace 'your_key_here' with your actual key):\n",
+    "\n",
+    "```\n",
+    "EXPECTED_PARROT_API_KEY = 'your_key_here'\n",
+    "```\n",
+    "\n",
+    "*Note:* If you try to run a survey without storing a required API key, you will be provided a link to activate remote inference and automatically store your Expected Parrot API key in a *.env* file for you.\n",
+    "\n",
+    "\n",
+    "### Local inference\n",
+    "This method allows you to run EDSL on your own machine with your own API keys for service providers.\n",
+    "To use this method, you will need to create accounts with service providers and obtain API keys from them.\n",
+    "You can still use an Expected Parrot API key to post and share content at the Expected Parrot server, but you will need to do this manually.\n",
+    "\n",
+    "To use local inference:\n",
+    "\n",
+    "1. Create accounts with service providers and obtain API keys from them.\n",
+    "2. Create a file named *.env* in your working directory and add the following code to it (replace 'your_key_here' with your actual keys):\n",
     "\n",
-    "* *Remote inference:* This method allows you to run surveys at the Expected Parrot server and access all available language models at once with your Expected Parrot API key. [Learn more](https://docs.expectedparrot.com/en/latest/remote_inference.html).\n",
-    "  \n",
-    "* *Local inference:* Alternatively, you can obtain your own API keys for service providers to run EDSL on your own machine. \n",
+    "```\n",
+    "EXPECTED_PARROT_API_KEY = 'your_key_here'\n",
     "\n",
-    "Your Expected Parrot API key can be found at the Settings page of your [Coop account](https://www.expectedparrot.com/login), where you can select the option to [activate remote inference](https://docs.expectedparrot.com/en/latest/remote_inference.html).\n",
-    "This key also allows you to [post and share content at the Coop](https://www.expectedparrot.com/content/explore) that you create using either remote or local inference. \n",
+    "ANTHROPIC_API_KEY = 'your_key_here'\n",
+    "DEEP_INFRA_API_KEY = 'your_key_here'\n",
+    "GOOGLE_API_KEY = 'your_key_here'\n",
+    "GROQ_API_KEY = 'your_key_here'\n",
+    "MISTRAL_API_KEY = 'your_key_here'\n",
+    "OPENAI_API_KEY = 'your_key_here'\n",
+    "REPLICATE_API_KEY = 'your_key_here'\n",
+    "```\n",
     "\n",
-    "### Store your API keys\n",
-    "Make your keys available to EDSL by storing then in a file named \"**.env**\" in your working directory. \n",
+    "*Note:* Your API keys should be treated like passwords and deleted from notebooks or content that you share with others. \n",
     "\n",
-    "***Note: Your API keys should be treated like passwords and deleted from notebooks or content that you share with others. We recommend deleting your keys from the code below after your .env file has been created.***"
+    "Now that we have installed EDSL and set up API keys, we can start using it to create surveys and analyze results."
    ]
   },
   {
@@ -4436,7 +4517,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "app-uJzvXEU--py3.12",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -4450,7 +4531,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.8"
+   "version": "3.11.7"
   }
  },
  "nbformat": 4,