First commit

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## Unreleased
+
+## [0.1.0] - 2023-12-20
+### Added
+- Base feature
+
+## [0.1.1] - 2023-12-24
+### Added
+- Changelog file
+
+### Fixed
+- Image display and description text in README.md
+
+### Removed
+- Unused files

LICENSE

@@ -1,6 +1,6 @@
-MIT License
+The MIT License
 
-Copyright (c) 2024 Emeritus
+Copyright (c) Apostolos Filippas, John Joseph Horton, Roberta Horton.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +9,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

Makefile

@@ -0,0 +1,44 @@
+GIT_ROOT ?= $(shell git rev-parse --show-toplevel)
+PROJECT_NAME ?= $(shell basename $(GIT_ROOT))
+.PHONY: integration
+
+
+help: ## Show all Makefile targets.
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(GIT_ROOT)/Makefile | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[33m%-30s\033[0m %s\n", $$1, $$2}'
+
+backup: ## Backup the code to `edsl/.backups/`
+	TIMESTAMP=$$(date +"%Y%m%d_%H%M%S"); \
+	BACKUP_NAME=$(PROJECT_NAME)_$${TIMESTAMP}.tar.gz; \
+	mkdir -p "./.backups"; \
+	tar -czf $${BACKUP_NAME} --exclude="*pkl" --exclude="*tar.gz" --exclude="*db" --exclude="*csv" --exclude="./.*" --exclude="node_modules" --exclude="__pycache__" .;\
+	mv $${BACKUP_NAME} "./.backups";\
+	echo "Backup created: $${BACKUP_NAME}"
+
+clean: ## Cleans non-essential files and folders
+	[ ! -f .coverage ] || rm .coverage
+	[ ! -d .mypy_cache ] || rm -rf .mypy_cache
+	[ ! -d .venv ] || rm -rf .venv
+	[ ! -d htmlcov ] || rm -rf htmlcov
+	[ ! -d dist ] || rm -rf dist
+	[ ! -f edsl/data/database.db ] || rm edsl/data/database.db
+	find . -type d -name '__pycache__' -exec rm -rf {} +
+	find . -type d -name '.pytest_cache' -exec rm -rf {} +
+
+coverage: ## Run tests and get a coverage report
+	poetry run coverage run -m pytest tests && poetry run coverage html && open htmlcov/index.html
+
+format: ## Run code autoformatters (black).
+	pre-commit install
+	pre-commit run black-jupyter --all-files --all
+
+integration: ## Run integration tests via pytest **consumes API credits**
+	pytest -v -s integration/
+
+lint: ## Run code linters (flake8, pylint, mypy).
+	mypy edsl
+
+test: ## Run tests via pytest
+	pytest tests
+
+watch-docs: ## Build and watch documentation.
+	sphinx-autobuild docs/ docs/_build/html --open-browser --watch $(GIT_ROOT)/edsl/

README.md

@@ -0,0 +1,31 @@
+# Emeritus Domain-Specific Language 
+<p align="center">
+  <img src="https://github.com/goemeritus/edsl-public/blob/main/static/logo.png?raw=true" alt="edsl.png" width="100"/>
+</p>
+
+The Emeritus Domain-Specific Language (EDSL) package lets you conduct social science and market research with AI. Use it to design surveys and experiments, simulate responses with LLMs, and analyze results. 
+
+
+## 🔗 Links
+- PyPI: https://pypi.org/project/edsl/
+- Documentation: https://www.goemeritus.com/getting-started/
+- Discord: https://discord.gg/HQbBKYvb
+
+## 💡 Contributing, Feature Asks, and 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 [email protected] or message us at our discord server.
+
+
+## 💻 Getting started
+Our package is compatible with Python 3.9 - 3.11.
+```
+pip install edsl
+```
+
+See https://www.goemeritus.com/getting-started/
+ for examples and tutorials.
+
+## 🔧 Dependencies
+The main third-party package requirement is  `openai`.
+
+## 📖 Citation
+Reference to cite if you use EDSL in a paper: TBA

docs/conf.py

@@ -0,0 +1,78 @@
+"""Configuration for sphinx."""
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath("../"))
+
+with open("../edsl/VERSION") as f:
+    version = f.read()
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+
+project = "EDSL"
+copyright = "2023, Go Emeritus Inc"
+author = "Go Emeritus Inc"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.autodoc.typehints",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    # "sphinx_rtd_theme",
+    "sphinx.ext.mathjax",
+    # "m2r2",
+    # "myst_nb",
+    # "sphinxcontrib.autodoc_pydantic",
+    # "sphinx_reredirects",
+]
+
+myst_heading_anchors = 5
+# TODO: Fix the non-consecutive header level in our docs, until then
+# disable the sphinx/myst warnings
+# suppress_warnings = ["myst.header"]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "DOCS_README.md"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+# html_theme = "furo"
+html_title = project + " " + version
+html_static_path = ["_static"]
+
+# html_css_files = [
+#     "css/custom.css",
+#     "css/algolia.css",
+#     "https://cdn.jsdelivr.net/npm/@docsearch/css@3",
+# ]
+# html_js_files = [
+#     "js/mendablesearch.js",
+#     (
+#         "https://cdn.jsdelivr.net/npm/@docsearch/[email protected]/dist/umd/index.js",
+#         {"defer": "defer"},
+#     ),
+#     ("js/algolia.js", {"defer": "defer"}),
+# ]
+
+nb_execution_mode = "off"
+autodoc_pydantic_model_show_json_error_strategy = "coerce"
+nitpicky = True

docs/index.rst

@@ -0,0 +1,68 @@
+Welcome to EDSL!
+##########################
+
+LlamaIndex is a framework for creating `LLM <https://en.wikipedia.org/wiki/Large_language_model>`_-based applications to conduct social science. It's available in Python.
+
+🚀 Why EDSL?
+******************
+
+LLMs offer a natural language interface between humans and data. Widely available models come pre-trained on huge amounts of publicly available data like Wikipedia, mailing lists, textbooks, source code and more.
+
+However, it takes a tremendous amount of work to work with LLMs. What is more, their results cannot be trusted for social science off the shelf.
+
+EDSL solves this problem by ... .
+
+👨‍👩‍👧‍👦 How can EDSL help?
+***************************
+
+EDSL provides the following tools:
+
+- **Survey creating** easily ask the questions you want.
+- **Agent creations** easily create ... .
+
+👨‍👩‍👧‍👦 Who is EDSL for?
+*******************************************
+
+EDSL provides tools for beginners, advanced users, and everyone in between.
+
+Our high-level API allows beginner users to use EDSL to ... .
+
+For more complex applications, our lower-level APIs allow advanced users to customize and extend any ... to fit their needs.
+
+Getting Started
+****************
+
+To install the library:
+
+``pip install edsl``
+
+We recommend starting at `how to read these docs <getting_started/reading.md>`_, which will point you to the right place based on your experience level.
+
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Getting Started
+   :hidden:
+
+   getting_started/installation.md
+   getting_started/reading.md
+   getting_started/starter_example.md
+   getting_started/concepts.md
+   getting_started/customization.rst
+   getting_started/discover_edsl.md
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Use Cases
+   :hidden:
+
+   use_cases/use_case_one.md
+   use_cases/use_case_two.md
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Understanding
+   :hidden:
+
+   understanding/understanding.md

edsl/__init__.py

@@ -0,0 +1,16 @@
+import os
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+ROOT_DIR = os.path.dirname(BASE_DIR)
+
+from edsl.config import Config, CONFIG
+from edsl.agents.Agent import Agent
+from edsl.questions import (
+    QuestionFreeText,
+    QuestionMultipleChoice,
+    QuestionNumerical,
+    QuestionCheckBox,
+)
+from edsl.scenarios.Scenario import Scenario
+from edsl.utilities.interface import print_dict_with_rich
+from edsl.surveys.Survey import Survey