Merge branch 'main' of https://GitHub.com/Aitomatic/OpenSSA into contrib

.github/workflows/install-lint-test-on-ubuntu.yml

@@ -16,8 +16,7 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - '3.10'
-          - 3.11
+          - 3.12
 
     steps:
       - name: Checkout Repo

.github/workflows/install-lint-test-on-win.yml

@@ -16,8 +16,7 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - '3.10'
-          - 3.11
+          - 3.12
 
     steps:
       - name: Checkout Repo

.github/workflows/publish-docs.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Set Up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.11
+          python-version: 3.12
 
       - name: Install Poetry
         run: make get-poetry

.github/workflows/release.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Set Up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.11
+          python-version: 3.12
 
       - name: Install Poetry
         run: make get-poetry

.gitignore

@@ -37,3 +37,4 @@ docs/_build/
 .env
 tmp/
 examples/data/cache/dense
+examples/data/*.csv

.prospector.yaml

@@ -0,0 +1,3 @@
+pycodestyle:
+  disable:
+    - E901  # invalid syntax

.ruff.toml

@@ -38,6 +38,7 @@ ignore = [
            # instead, perform the call within the function, or read the default from a module-level singleton variable
   "B027",  # ... is an empty method in an abstract base class, but has no abstract decorator
   "B905",  # `zip()` without an explicit `strict=` parameter
+  "BLE001",  # do not catch blind exception
   "COM812",  # trailing comma missing
   "CPY001",  # missing copyright notice at top of file
   "D100",  # missing docstring in public module
@@ -72,13 +73,15 @@ ignore = [
   "FBT002",  # boolean default positional argument in function definition
   "FBT003",  # boolean positional value in function call
   "FIX002",  # line contains TODO, consider resolving the issue
+  "FURB101",  # `open` and `read` should be replaced by `Path(file_path).read_bytes()`
   "I001",  # import block is un-sorted or un-formatted
   "INP001",  # file is part of an implicit namespace package; add an `__init__.py`
   "LOG009",  # use of undocumented `logging.WARN` constant
   "N811",  # constant `SSM` imported as non-constant `LlamaIndexSSM`
   "PERF401",  # use a list comprehension to create a transformed list
   "PGH003",  # use specific rule codes when ignoring type issues
   "PIE790",  # unnecessary `pass` statement
+  "PLC2701",  # private name import from external module
   "PTH100",  # `os.path.abspath()` should be replaced by `Path.resolve()`
   "PTH103",  # `os.makedirs()` should be replaced by `Path.mkdir(parents=True)`
   "PTH109",  # `os.getcwd()` should be replaced by `Path.cwd()`
@@ -108,16 +111,21 @@ ignore = [
   "RUF013",  # PEP 484 prohibits implicit `Optional`
   "RUF017",  # Avoid quadratic list summation"
   "RUF018",  # avoid assignment expressions in `assert` statements
+  "RUF022",  # __all__` is not sorted
+  "RUF100",  # unused `noqa` directive
   "S101",  # use of `assert` detected
   "S106",  # possible hardcoded password assigned to argument
+  "S110",  # `try`-`except`-`pass` detected, consider logging the exception
   "S605",  # starting a process with a shell, possible injection detected
   "S607",  # starting a process with a partial executable path
   "SIM102",  # use a single `if` statement instead of nested `if` statements
   "SIM108",  # use ternary operator `temp = temp["content"] if isinstance(temp, dict) else temp.content` instead of `if`-`else`-block
+  "SIM105",  # use `contextlib.suppress(Exception)` instead of `try`-`except`-`pass`
   "SIM112",  # use capitalized environment variable
   "SIM401",  # use `item.get("role", "assistant")` instead of an `if` block
   "SLF001",  # private member accessed
   "T201",  # `print` found
+  "T203",  # `pprint` found
   "TD002",  # missing author in TODO; try: `# TODO(<author_name>): ...` or `# TODO @<author_name>: ...`
   "TD003",  # missing issue link on the line following this TODO
   "TRY003",  # avoid specifying long messages outside the exception class

.vscode/extensions.json

@@ -9,8 +9,11 @@
   ],
 
   "unwantedRecommendations": [
-    "ms-python.mypy-type-checker",  // MyPy Type Checker (Microsoft)
+    "ms-python.autopep8",  // AutoPEP8 (Microsoft)
+    "ms-python.black-formatter",  // Black Formatter (Microsoft)
+    "eeyore.yapf",  // Yet Another Python Formatter
 
+    "ms-python.mypy-type-checker",  // MyPy Type Checker (Microsoft)
     "matangover.mypy"  // MyPy
   ]
 }

.vscode/settings.json

@@ -23,6 +23,9 @@
   },
 
   "python.analysis.diagnosticSeverityOverrides": {
+    "reportInvalidTypeForm": "none",
+    "reportMissingImports": "none",
+    "reportMissingModuleSource": "none"
   },
 
 

Makefile

@@ -26,17 +26,23 @@ ANSI_WHITE="\033[0;37m"
 # POETRY
 # ======
 get-poetry:
-	python3 -m pip install Poetry --upgrade
+	@python3 -m pip install Poetry --upgrade
+
+get-poetry-mac-sys:
+	@python3 -m pip install Poetry --upgrade --user --break-system-packages
 
 
 # INSTALLATION
 # ============
 install:
-	poetry lock
-	poetry install --extras=contrib --with=docs --with=lint --with=test
+	@poetry lock
+	@poetry install --extras=contrib --with=dev --with=docs --with=lint --with=test
 
 install-editable:
-	python3 -m pip install -e ".[contrib]" --upgrade --user
+	@python3 -m pip install -e ".[contrib]" --upgrade
+
+install-editable-mac-sys:
+	@python3 -m pip install -e ".[contrib]" --upgrade --user --break-system-packages
 
 
 # LINTING
@@ -46,17 +52,16 @@ lint: lint-flake8 lint-pylint lint-ruff
 lint-flake8:
 	# flake8.pycqa.org/en/latest/user/invocation.html
 	# flake8.pycqa.org/en/latest/user/options.html
-	poetry run flake8 $(LIB_DIR) $(DOCS_DIR) $(EXAMPLES_DIR) $(TESTS_DIR) \
+	@poetry run flake8 $(LIB_DIR) $(DOCS_DIR) $(EXAMPLES_DIR) $(TESTS_DIR) \
 		--verbose --color always
 
 lint-pylint:
 	# pylint.readthedocs.io/en/latest/user_guide/usage/run.html
-	poetry run pylint $(LIB_DIR) $(DOCS_DIR) $(EXAMPLES_DIR) $(TESTS_DIR)
+	@poetry run pylint $(LIB_DIR) $(DOCS_DIR) $(EXAMPLES_DIR) $(TESTS_DIR)
 
 lint-ruff:
 	# docs.astral.sh/ruff/linter
-	poetry run ruff check $(LIB_DIR) $(DOCS_DIR) $(EXAMPLES_DIR) $(TESTS_DIR) \
-		--show-source \
+	@poetry run ruff check $(LIB_DIR) $(DOCS_DIR) $(EXAMPLES_DIR) $(TESTS_DIR) \
 		--output-format text \
 		--target-version py310 \
 		--preview \
@@ -93,17 +98,17 @@ release: build
 # DOCUMENTATION
 # =============
 docs: docs-build-clean docs-build-api
-	poetry run sphinx-autobuild "$(DOCS_DIR)" "$(DOCS_BUILD_DIR)"
+	@poetry run sphinx-autobuild "$(DOCS_DIR)" "$(DOCS_BUILD_DIR)"
 
 docs-build-clean:
-	rm -f "$(DOCS_DIR)"/*.rst
-	rm -rf "$(DOCS_BUILD_DIR)"
+	@rm -f "$(DOCS_DIR)"/*.rst
+	@rm -rf "$(DOCS_BUILD_DIR)"
 
 docs-build-api:
 	# generate .rst files from module code & docstrings
 	# any pathnames given at the end are paths to be excluded ignored during generation.
 	# sphinx-doc.org/en/master/man/sphinx-apidoc.html
-	poetry run sphinx-apidoc \
+	@poetry run sphinx-apidoc \
 		--force \
 		--follow-links \
 		--maxdepth 9 \
@@ -118,46 +123,46 @@ docs-build-api:
 	# rm "$(DOCS_DIR)"/*.orig
 
 docs-build: docs-build-clean docs-build-api
-	poetry run sphinx-build "$(DOCS_DIR)" "$(DOCS_BUILD_DIR)"
+	@poetry run sphinx-build "$(DOCS_DIR)" "$(DOCS_BUILD_DIR)"
 
 docs-deploy: docs-build
-	git fetch --all
+	@git fetch --all
 
-	git checkout gh-pages --
+	@git checkout gh-pages --
 
-	git config user.email "[email protected]"
-	git config user.name "The Vinh LUONG (LƯƠNG Thế Vinh)"
+	@git config user.email "[email protected]"
+	@git config user.name "The Vinh LUONG (LƯƠNG Thế Vinh)"
 
-	rm *.html
-	cp "$(DOCS_BUILD_DIR)"/*.html .
-	git add --all "*.html"
-	git reset "$(DOCS_DIR)/*.html"
+	@rm *.html
+	@cp "$(DOCS_BUILD_DIR)"/*.html .
+	@git add --all "*.html"
+	@git reset "$(DOCS_DIR)/*.html"
 
-	for docs_subdir_to_publish in $(DOCS_SUBDIRS_TO_PUBLISH) ; do \
+	@for docs_subdir_to_publish in $(DOCS_SUBDIRS_TO_PUBLISH) ; do \
 		echo "syncing $$docs_subdir_to_publish..." ; \
 		rsync -av --delete --links "$(DOCS_BUILD_DIR)/$$docs_subdir_to_publish"/ $$docs_subdir_to_publish/ ; \
 		git add --all "$$docs_subdir_to_publish/*" ; \
 	done
 
-	git commit -m "update GitHub Pages documentation site"
-	git push
+	@git commit -m "update GitHub Pages documentation site"
+	@git push
 
-	git checkout docs --
+	@git checkout docs --
 
 
 # VERSION MANAGEMENT
 # ==================
 version:
-	poetry version $(v)
+	@poetry version $(v)
 
 
 # MISC / OTHER
 # ============
 launch-solver:
-	poetry run openssa launch solver
+	@poetry run openssa launch solver
 
 public:
-	rsync . ../openssa/ \
+	@rsync . ../openssa/ \
 		--archive \
 		--delete \
 		--exclude .git \

README.md

@@ -81,7 +81,8 @@ Our primary audience includes:
 
 4. A committer to OpenSSA
 
-## Getting Started as an End-User
+### Getting Started as an End-User
+
 Go straight to [OpenSSA Streamlit app](https://openssa.streamlit.app/) and start building your own SSA with your domain document today!
 
 
@@ -146,7 +147,7 @@ Head to [Lepton](https://dashboard.lepton.ai/) to get your API key.
 * Select `API tokens`
 * Copy `<YOUR_LEPTON_API_TOKEN>`
 
-In terminal, run 
+In terminal, run
 ```bash=
 export LEPTON_API_KEY=<YOUR_LEPTON_API_TOKEN>
 ```

docs/conf.py

@@ -7,11 +7,7 @@
 from collections.abc import Sequence
 from datetime import date
 from pathlib import Path
-from sys import version_info
-if version_info < (3, 11):
-    import tomli as tomllib
-else:
-    import tomllib
+import tomllib
 
 
 # pylint: disable=invalid-name

examples/.env.template

@@ -0,0 +1,2 @@
+LEPTON_API_KEY=[... Lepton key (obtainable at dashboard.lepton.ai) if running on Aitomatic services ...]
+OPENAI_API_KEY=[... OpenAI creds if running directly on OpenAI services ...]

examples/FinanceBench/.env.template

@@ -0,0 +1,2 @@
+LEPTON_API_KEY=[... Lepton key (obtainable at dashboard.lepton.ai) if running SSAs on Aitomatic services ...]
+OPENAI_API_KEY=[... OpenAI creds if running SSAs directly on OpenAI services ...]

examples/FinanceBench/.gitignore

@@ -0,0 +1,2 @@
+.data/
+.streamlit/secrets.toml

examples/FinanceBench/.streamlit/secrets.toml.template

@@ -0,0 +1 @@
+LEPTON_API_KEY = '...'

examples/FinanceBench/Makefile

@@ -0,0 +1,5 @@
+run-streamlit:
+	@streamlit run streamlit-main.py --server.allowRunOnSave=true --server.runOnSave=true
+
+solve:
+	@poetry run python3 fb_ssa/prob_solve.py ${id}

examples/FinanceBench/README.md

@@ -0,0 +1,32 @@
+<!-- markdownlint-disable MD043 -->
+
+# OpenSSA-FinanceBench benchmarking
+
+This example conducts the benchmarking of `OpenSSA` performance
+on the `FinanceBench` dataset.
+
+## [`FinanceBench` Dataset](https://github.com/patronus-ai/financebench/blob/main/financebench_sample_150.csv)
+
+## Running Aitomatic SSA benchmarking project
+
+Have Python 3.10-3.11 installed.
+
+Have Poetry installed: __`make get-poetry`__.
+
+__Install__ project, and update its dependencies from time to time:
+__`make install`__.
+
+Create `.env` file following the `.env.template` and fill in necessary credentials.
+
+__Solve__ the problem corresponding to a specific `financebench_id`:
+__`make solve id=...`__.
+
+- refer to `FinanceBench` dataset above for `financebench_id`s
+and corresponding information
+
+## Notes to Aitomatic Developers
+
+The OpenSSA dependency for this benchmarking project is from the `experimental`
+branch of the private [SSA](https://github.com/aitomatic/ssa) repository.
+Hence, all improvements to OpenSSA during this project must be
+committed/pushed/merged into that repository and branch.