{"id":15169640,"url":"https://github.com/expectedparrot/edsl","last_synced_at":"2025-05-15T13:06:41.388Z","repository":{"id":215172667,"uuid":"738290765","full_name":"expectedparrot/edsl","owner":"expectedparrot","description":"Design, conduct and analyze results of AI-powered surveys and experiments. Simulate social science and market research with large numbers of AI agents and LLMs.","archived":false,"fork":false,"pushed_at":"2025-05-07T11:01:07.000Z","size":61562,"stargazers_count":238,"open_issues_count":153,"forks_count":24,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-07T11:23:54.918Z","etag":null,"topics":["anthropic","data-labeling","deepinfra","domain-specific-language","experiments","llama2","llm","llm-agent","llm-framework","llm-inference","market-research","mixtral","open-source","openai","python","social-science","surveys","synthetic-data"],"latest_commit_sha":null,"homepage":"https://docs.expectedparrot.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/expectedparrot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-02T22:18:47.000Z","updated_at":"2025-05-05T16:05:02.000Z","dependencies_parsed_at":"2025-04-07T18:33:16.687Z","dependency_job_id":"9dad6f65-1d94-4049-b8b3-2c12791f076d","html_url":"https://github.com/expectedparrot/edsl","commit_stats":{"total_commits":2991,"total_committers":13,"mean_commits":"230.07692307692307","dds":0.66934135740555,"last_synced_commit":"c5a531c9c45f1caff35c6c0b637eadc28c86e9ea"},"previous_names":["goemeritus/edsl","expectedparrot/edsl"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/expectedparrot%2Fedsl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/expectedparrot%2Fedsl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/expectedparrot%2Fedsl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/expectedparrot%2Fedsl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/expectedparrot","download_url":"https://codeload.github.com/expectedparrot/edsl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253505324,"owners_count":21918927,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","data-labeling","deepinfra","domain-specific-language","experiments","llama2","llm","llm-agent","llm-framework","llm-inference","market-research","mixtral","open-source","openai","python","social-science","surveys","synthetic-data"],"created_at":"2024-09-27T07:04:14.174Z","updated_at":"2025-05-15T13:06:36.370Z","avatar_url":"https://github.com/expectedparrot.png","language":"Python","readme":"# Expected Parrot Domain-Specific Language (EDSL)\n\nThe Expected Parrot Domain-Specific Language (EDSL) package makes it easy to conduct computational social science and market research with AI. Use it to design surveys and experiments, collect responses from humans and large language models, and perform data labeling and many other research tasks. Results are formatted as specified datasets and come with built-in methods for analyzing, visualizing and sharing. \n\n\u003cp align=\"right\"\u003e\n  \u003cimg src=\"https://github.com/expectedparrot/edsl/blob/main/static/logo.png?raw=true\" alt=\"edsl.png\" width=\"100\"/\u003e\n\u003c/p\u003e\n\n## Features \n\n**Declarative design**: \nSpecified \u003ca href=\"https://docs.expectedparrot.con/en/latest/questions.html\" target=\"_blank\" rel=\"noopener noreferrer\"\u003equestion types\u003c/a\u003e ensure consistent results without requiring a JSON schema (\u003ca href=\"https://www.expectedparrot.com/content/2a848a0e-f9de-46bc-98d0-a13b9a1caf11\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eview at Coop\u003c/a\u003e):\n\n```python\nfrom edsl import QuestionMultipleChoice\n\nq = QuestionMultipleChoice(\n  question_name = \"example\",\n  question_text = \"How do you feel today?\",\n  question_options = [\"Bad\", \"OK\", \"Good\"]\n)\n\nresults = q.run()\n\nresults.select(\"example\")\n```\n\n\u003e | answer.example  |\n\u003e |-----------------|\n\u003e | Good            |\n\n\u003cbr\u003e\n\n**Parameterized prompts**: \nEasily parameterize and control prompts with \"\u003ca href=\"https://docs.expectedparrot.com/en/latest/scenarios.html\" target=\"_blank\" rel=\"noopener noreferrer\"\u003escenarios\u003c/a\u003e\" of data automatically imported from many sources (CSV, PDF, PNG, etc.)(\u003ca href=\"https://www.expectedparrot.com/content/7bb9ec2e-827b-4867-ac02-33163df1a1d1\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eview at Coop\u003c/a\u003e):\n\n```python\nfrom edsl import ScenarioList, QuestionLinearScale\n\nq = QuestionLinearScale(\n  question_name = \"example\",\n  question_text = \"How much do you enjoy {{ activity }}?\",\n  question_options = [1,2,3,4,5,],\n  option_labels = {1:\"Not at all\", 5:\"Very much\"}\n)\n\nsl = ScenarioList.from_list(\"activity\", [\"coding\", \"sleeping\"])\n\nresults = q.by(sl).run()\n\nresults.select(\"activity\", \"example\")\n```\n\n\u003e | scenario.activity  | answer.example  |\n\u003e |--------------------|-----------------|\n\u003e | Coding             | 5               |\n\u003e | Sleeping           | 5               |\n\n\u003cbr\u003e\n\n**Design AI agent personas to answer questions**: \nConstruct agents with relevant traits to provide diverse responses to your surveys (\u003ca href=\"https://www.expectedparrot.com/content/b639a2d7-4ae6-48fe-8b9e-58350fab93de\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eview at Coop\u003c/a\u003e)\n\n```python\nfrom edsl import Agent, AgentList, QuestionList\n\nal = AgentList(Agent(traits = {\"persona\":p}) for p in [\"botanist\", \"detective\"])\n\nq = QuestionList(\n  question_name = \"example\",\n  question_text = \"What are your favorite colors?\",\n  max_list_items = 3\n)\n\nresults = q.by(al).run()\n\nresults.select(\"persona\", \"example\")\n```\n\n\u003e | agent.persona  | answer.example                              |\n\u003e |----------------|---------------------------------------------|\n\u003e | botanist       | ['Green', 'Earthy Brown', 'Sunset Orange']  |\n\u003e | detective      | ['Gray', 'Black', 'Navy Blye']              |\n\n\u003cbr\u003e\n\n**Simplified access to LLMs**: \nChoose whether to use your own keys for LLMs, or access all \u003ca href=\"https://www.expectedparrot.com/getting-started/coop-pricing\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eavailable models\u003c/a\u003e with an Expected Parrot API key. Run surveys with many models at once and compare responses at a convenient inferface (\u003ca href=\"https://www.expectedparrot.com/content/044465f0-b87f-430d-a3b9-4fd3b8560299\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eview at Coop\u003c/a\u003e)\n\n```python\nfrom edsl import Model, ModelList, QuestionFreeText\n\nml = ModelList(Model(m) for m in [\"gpt-4o\", \"gemini-1.5-flash\"])\n\nq = QuestionFreeText(\n  question_name = \"example\",\n  question_text = \"What is your top tip for using LLMs to answer surveys?\"\n)\n\nresults = q.by(ml).run()\n\nresults.select(\"model\", \"example\")\n```\n\n\u003e | model.model        | answer.example                                                                                  |\n\u003e |--------------------|-------------------------------------------------------------------------------------------------|\n\u003e | gpt-4o             | When using large language models (LLMs) to answer surveys, my top tip is to ensure that the ... |\n\u003e | gemini-1.5-flash   | My top tip for using LLMs to answer surveys is to **treat the LLM as a sophisticated brainst... |\n\n\u003cbr\u003e\n\n**Piping \u0026 skip-logic**: \nBuild rich data labeling flows with features for piping answers and adding survey logic such as skip and stop rules (\u003ca href=\"https://www.expectedparrot.com/content/b8afe09d-49bf-4c05-b753-d7b0ae782eb3\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eview at Coop\u003c/a\u003e):\n\n```python\nfrom edsl import QuestionMultipleChoice, QuestionFreeText, Survey\n\nq1 = QuestionMultipleChoice(\n  question_name = \"color\",\n  question_text = \"What is your favorite primary color?\",\n  question_options = [\"red\", \"yellow\", \"blue\"]\n)\n\nq2 = QuestionFreeText(\n  question_name = \"flower\",\n  question_text = \"Name a flower that is {{ color.answer }}.\"\n)\n\nsurvey = Survey(questions = [q1, q2])\n\nresults = survey.run()\n\nresults.select(\"color\", \"flower\")\n```\n\n\u003e | answer.color  | answer.flower                                                                     |\n\u003e |---------------|-----------------------------------------------------------------------------------|\n\u003e | blue          | A commonly known blue flower is the bluebell. Another example is the cornflower.  |\n\n\u003cbr\u003e\n\n**Caching**: \nAPI calls to LLMs are cached automatically, allowing you to retrieve responses to questions that have already been run and reproduce experiments at no cost. Learn more about how the \u003ca href=\"https://docs.expectedparrot.com/en/latest/remote_caching.html\" target=\"_blank\" rel=\"noopener noreferrer\"\u003euniversal remote cache\u003c/a\u003e works.\n\n**Logging**:\nEDSL includes a comprehensive logging system to help with debugging and monitoring. Control log levels and see important information about operations:\n\n```python\nfrom edsl import logger\nimport logging\n\n# Set the logging level\nlogger.set_level(logging.DEBUG)  # Show all log messages\n\n# Get a module-specific logger\nmy_logger = logger.get_logger(__name__)\nmy_logger.info(\"This is a module-specific log message\")\n\n# Log messages at different levels\nlogger.debug(\"Detailed debugging information\")\nlogger.info(\"General information about operation\")\nlogger.warning(\"Something unexpected but not critical\")\nlogger.error(\"Something went wrong\")\n```\n\n**Flexibility**: \nChoose whether to run surveys on your own computer or at the Expected Parrot server.\n\n**Tools for collaboration**: \nEasily share workflows and projects privately or publicly at Coop: an integrated platform for AI-based research. Your account comes with free credits for running surveys, and lets you securely share keys, track expenses and usage for your team.\n\n**Built-in tools for analyis**: \nAnalyze results as specified datasets from your account or workspace. Easily import data to use with your surveys and export results.\n\n## Getting started\n\n1. Run `pip install edsl` to install the package.\n\n2. \u003ca href=\"https://www.expectedparrot.com/login\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eCreate an account\u003c/a\u003e to run surveys at the Expected Parrot server and access a \u003ca href=\"https://docs.expectedparrot.com/en/latest/remote_caching.html\" target=\"_blank\" rel=\"noopener noreferrer\"\u003euniversal remote cache\u003c/a\u003e of stored responses for reproducing results.\n\n3. Choose whether to use your own keys for language models or get an Expected Parrot key to access all available models at once. Securely \u003ca href=\"https://docs.expectedparrot.com/en/latest/api_keys.html\" target=\"_blank\" rel=\"noopener noreferrer\"\u003emanage keys\u003c/a\u003e, share expenses and track usage for your team from your account.\n\n4. Run the \u003ca href=\"https://docs.expectedparrot.com/en/latest/starter_tutorial.html\" target=\"_blank\" rel=\"noopener noreferrer\"\u003estarter tutorial\u003c/a\u003e and explore other demo notebooks. \n\n5. Share workflows and survey results at \u003ca href=\"https://www.expectedparrot.com/content/explore\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eCoop\u003c/a\u003e\n\n6. Join our \u003ca href=\"https://discord.com/invite/mxAYkjfy9m\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eDiscord\u003c/a\u003e for updates and discussions! Request new features!\n\n## Code \u0026 Docs\n- \u003ca href=\"https://pypi.org/project/edsl/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003ePyPI\u003c/a\u003e\n- \u003ca href=\"https://github.com/expectedparrot/edsl\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eGitHub\u003c/a\u003e\n- \u003ca href=\"https://docs.expectedparrot.com\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eDocumentation\u003c/a\u003e\n\n## Requirements\n- Python 3.9 - 3.12\n- API keys for language models. You can use your own keys or an Expected Parrot key that provides access to all available models.\nSee instructions on \u003ca href=\"https://docs.expectedparrot.com/en/latest/api_keys.html\" target=\"_blank\" rel=\"noopener noreferrer\"\u003emanaging keys\u003c/a\u003e and \u003ca href=\"https://www.expectedparrot.com/getting-started/coop-pricing\" target=\"_blank\" rel=\"noopener noreferrer\"\u003emodel pricing and performance\u003c/a\u003e information.\n\n## Developer Notes\n\n### Running Tests\n- Unit tests: `python -m pytest tests/`  \n- Integration tests: `python -m pytest integration/`\n- Doctests: `python run_doctests.py` (use `-v` flag for verbose output)\n\n## Coop\nAn integrated platform for running experiments, sharing workflows and launching hybrid human/AI surveys.\n- \u003ca href=\"https://www.expectedparrot.com/login\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eLogin / Signup\u003c/a\u003e\n- \u003ca href=\"https://www.expectedparrot.com/content/explore\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eExplore\u003c/a\u003e\n\n## Community\n- \u003ca href=\"https://discord.com/invite/mxAYkjfy9m\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eDiscord\u003c/a\u003e\n- \u003ca href=\"https://x.com/ExpectedParrot\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eTwitter\u003c/a\u003e\n- \u003ca href=\"https://www.linkedin.com/company/expectedparrot/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eLinkedIn\u003c/a\u003e\n- \u003ca href=\"https://blog.expectedparrot.com\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eBlog\u003c/a\u003e.\n\n## Contact\n- \u003ca href=\"mailto:info@expectedparrot.com\" target=\"_blank\" rel=\"noopener noreferrer\"\u003eEmail\u003c/a\u003e.\n","funding_links":[],"categories":["The latest additions 🎉"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexpectedparrot%2Fedsl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexpectedparrot%2Fedsl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexpectedparrot%2Fedsl/lists"}