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

…ples/FinanceBench

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

@@ -17,7 +17,7 @@ jobs:
       matrix:
         python-version:  # github.com/actions/python-versions/releases
           - 3.12
-          # - 3.13.0-beta.4
+          - 3.13
 
     steps:
       - name: Checkout Repo

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

@@ -17,7 +17,7 @@ jobs:
       matrix:
         python-version:  # github.com/actions/python-versions/releases
           - 3.12
-          # - 3.13.0-beta.4
+          - 3.13
 
     steps:
       - name: Checkout Repo

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

@@ -17,7 +17,7 @@ jobs:
       matrix:
         python-version:  # github.com/actions/python-versions/releases
           - 3.12
-          - 3.13.0-beta.4
+          - 3.13
 
     steps:
       - name: Checkout Repo

.gitignore

@@ -39,6 +39,13 @@ docs/_build/
 # DATA & EXAMPLE FILES
 # ====================
 examples/**/*.json
+!examples/**/package.json
+!examples/**/package-lock.json
+
+
+# Exception
+!examples/semiconductor/semiconductor-ui/api/poetry.lock
+
 .openssa/
 test*.ipynb
 tmp/

.ruff.toml

@@ -40,6 +40,7 @@ ignore = [
   "B008",  # do not perform function call in argument defaults;
            # 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
+  "B903",  # class could be dataclass or namedtuple
   "B905",  # `zip()` without an explicit `strict=` parameter
   "BLE001",  # do not catch blind exception
   "COM812",  # trailing comma missing
@@ -93,6 +94,7 @@ ignore = [
   "PGH004",  # use specific rule codes when using `ruff: noqa`
   "PIE790",  # unnecessary `pass` statement
   "PLC2701",  # private name import from external module
+  "PT028",  # test function parameter has default argument
   "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()`
@@ -101,6 +103,7 @@ ignore = [
   "PTH118",  # `os.path.join()` should be replaced by `Path` with `/` operator
   "PTH119",  # `os.path.basename()` should be replaced by `Path.name`
   "PTH123",  # `open()` should be replaced by `Path.open()`
+  "PTH208",  # use `pathlib.Path.iterdir()` instead
   "PLC0415",  # `import` should be at the top-level of a file
   "PLR0904",  # too many public methods
   "PLR0917",  # too many positional arguments
@@ -126,6 +129,7 @@ ignore = [
   "RUF017",  # Avoid quadratic list summation"
   "RUF018",  # avoid assignment expressions in `assert` statements
   "RUF022",  # __all__` is not sorted
+  "RUF051",  # Use `pop` instead of `key in dict` followed by `del dict[key]`
   "RUF100",  # unused `noqa` directive
   "S101",  # use of `assert` detected
   "S106",  # possible hardcoded password assigned to argument
@@ -150,4 +154,5 @@ ignore = [
   "UP007",  # use `X | Y` for type annotations
   "UP035",  # `typing.[X]` is deprecated, use `[x]` instead
   "UP039",  # unnecessary parentheses after class definition
+  "UP045",  # use `X | None` for type annotations
 ]

.vscode/settings.json

@@ -19,7 +19,12 @@
   // ======
 
   "[python]": {
-    "editor.formatOnSave": false
+    "editor.formatOnSave": false,
+    "editor.defaultFormatter": null
+    // "editor.codeActionsOnSave": {
+    //   "source.fixAll": "explicit",
+    //   "source.organizeImports": "explicit"
+    // }
   },
 
   "python.analysis.diagnosticSeverityOverrides": {
@@ -31,6 +36,7 @@
 
   // FLAKE8
   // ======
+  // marketplace.visualstudio.com/items?itemName=ms-python.flake8
 
   // Arguments passed to Flake8 for linting Python files.
   // Each argument should be provided as a separate string in the array.
@@ -54,14 +60,14 @@
     "info": "Information",
     "refactor": "Hint",
     "warning": "Warning"
-  },	
+  },
 
   // Path or command to be used by the extension to lint Python files with Flake8.
   // Accepts an array of a single or multiple strings.
   // If passing a command, each argument should be provided as a separate string in the array.
   // If set to ["flake8"], it will use the version of Flake8 available in the PATH environment variable.
   // Note: Using this option may slowdown linting.
-  // "flake8.path": [], 
+  // "flake8.path": [],
 
   // Path to a Python executable or a command that will be used to launch the Flake8 server and any subprocess.
   // Accepts an array of a single or multiple strings.
@@ -82,9 +88,6 @@
   // Accepted values are onError, onWarning, always and off.
   "flake8.showNotification": "onWarning",
 
-  // Enable linting Python files with Flake8 as you type.
-  "flake8.lintOnChange": true,
-
   // Configure glob patterns as supported by the fnmatch Python library (https://docs.python.org/3/library/fnmatch.html)
   // to exclude files or folders from being linted with Flake8.
   "flake8.ignorePatterns": [
@@ -94,6 +97,7 @@
 
   // PYLINT
   // ======
+  // marketplace.visualstudio.com/items?itemName=ms-python.pylint
 
   // Arguments passed to Pylint for linting Python files.
   // Each argument should be provided as a separate string in the array.
@@ -161,43 +165,22 @@
 
   // RUFF
   // ====
+  // marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
+  // docs.astral.sh/ruff/editors/settings
 
-  // Additional command-line arguments to pass to ruff check, e.g., "args": ["--config=/path/to/pyproject.toml"].
-  // Supports a subset of Ruff's command-line arguments, ignoring those that are required to operate the LSP,
-  // like --force-exclude and --verbose.
-  "ruff.lint.args": [
-  ],
-
-  // Path to a custom ruff executable, e.g., ["/path/to/ruff"].
-  "ruff.path": [],
-
-  // Path to a Python interpreter to use to run the linter server.
-  "ruff.interpreter": [],
-
-  // Strategy for loading the ruff executable.
-  // fromEnvironment picks up Ruff from the environment, falling back to the bundled version if needed.
-  // useBundled uses the version bundled with the extension.
-  "ruff.importStrategy": "fromEnvironment",
-
-  // Run Ruff on every keystroke (onType) or on save (onSave).
-  "ruff.lint.run": "onSave",
-
-  // Whether to enable the Ruff extension.
-  // Modifying this setting requires restarting VS Code to take effect.
-  "ruff.enable": true,
-
-  // Whether to register Ruff as capable of handling source.organizeImports actions.
-  "ruff.organizeImports": true,
+  "ruff.nativeServer": "on",
 
-  // Whether to register Ruff as capable of handling source.fixAll actions.
-  "ruff.fixAll": false,
+  "ruff.configuration": ".ruff.toml",
 
-  // Whether to display Quick Fix actions to autofix violations.
-  "ruff.codeAction.fixViolation.enable": true,
+  "ruff.lineLength": 120,
+  "ruff.organizeImports": false
 
-  // Whether to display Quick Fix actions to disable rules via noqa suppression comments.
-  "ruff.codeAction.disableRuleComment.enable": true,
+  // Python-based Ruff server only
+  // -----------------------------
+  // "ruff.importStrategy": "fromEnvironment",
+  // "ruff.interpreter": [],
+  // "ruff.path": [],
 
-  // Setting to control when a notification is shown: off, onError, onWarning, always.
-  "ruff.showNotification": "onWarning"
+  // "ruff.lint.args": [],
+  // "ruff.format.args": [],
 }

README.md

@@ -2,43 +2,38 @@
 
 # OpenSSA: Neurosymbolic Agentic AI for Industrial Problem-Solving
 
-**Why OpenSSA?**
 OpenSSA is an open-source neurosymbolic agentic AI framework
-designed to solve complex, high-stakes problems in industries like semiconductor, manufacturing and finance,
-where consistency, accuracy and deterministic outcomes are essential.
+designed to solve complex, high-stakes problems in industries like semiconductor, energy and finance,
+where consistency, accuracy and deterministic outcomes are paramount.
 
-At the core of OpenSSA is the **Domain-Aware Neurosymbolic Agent (DANA)** architecture,
-advancing AI from basic pattern-matching and information retrieval to true problem-solving.
-It overcomes the limitations of traditional LLMs and RAG in high-precision, multi-step problem-solving
-by combining **Hierarchical Task Plans (HTPs)** to structure complex programs and the **Observe-Orient-Decide-Act Reasoning (OODAR)** paradigm to execute such programs.
+At the core of OpenSSA is the [__Domain-Aware Neurosymbolic Agent (DANA)__](https://arxiv.org/abs/2410.02823) architecture,
+advancing generative AI from basic pattern matching and information retrieval to industrial-grade problem solving.
 By integrating domain-specific knowledge with neural and symbolic planning and reasoning,
-OpenSSA consistently delivers accurate solutions for complex industrial challenges.
+such as __Hierarchical Task Planning (HTP)__ for structuring programs
+and __Observe-Orient-Decide-Act Reasoning (OODAR)__ for executing such programs,
+OpenSSA DANA agents consistently deliver accurate solutions, often using much smaller models.
 
 ## Key Benefits of OpenSSA
 
-- **Consistent Results**: Delivers repeatable, high-precision outcomes for complex tasks.
-- **Advanced Problem-Solving**: Combines HTPs and OODAR for multi-step planning and reasoning.
-- **Scalable Expertise**: Leverages domain knowledge to scale AI without heavy data requirements.
-- **Resource Efficiency**: Uses smaller, resource-efficient models, minimizing computational costs.
-- **Extensible and Developer-Friendly**: Supports diverse LLM backends and is fully customizable for industry-specific needs.
+- __Consistent and Accurate Results__ for complex industrial problems
+- __Scalable Expertise__ through AI agents incorporating deep domain knowledge from human experts
+- __Economical and Efficient Computation__ thanks to usage of small models
+- __Full Ownership__ of intellectual property when used with open-source models such as Llama
 
 ## Getting Started
 
-- Install with __`pip install openssa`__
-_(supports Python 3.12 and 3.13)_
+- Install with __`pip install openssa`__ _(Python 3.12 and 3.13)_
+  - For bleeding-edge capabilities: __`pip install https://github.com/aitomatic/openssa/archive/main.zip`__
 
-- For the latest capabilities:
-__`pip install https://github.com/aitomatic/openssa/archive/main.zip`__.
-
-- Explore the `examples/` directory and developer guides and tutorials on our [documentation site](https://aitomatic.github.io/openssa).
+- Explore the `examples/` directory and developer guides and tutorials on our [documentation site](https://aitomatic.github.io/openssa)
 
 ## [API Documentation](https://aitomatic.github.io/openssa/modules)
 
 ## Contributing
 
 We welcome contributions from the community!
 
-- Join the discussion on our [Community Forum](https://github.com/aitomatic/openssa/discussions)
-- Submit pull requests for bug fixes, enhancements, or new features
+- Join discussions on our [Community Forum](https://github.com/aitomatic/openssa/discussions)
+- Submit pull requests for bug fixes, enhancements and new features
 
 For detailed guidelines, refer to our [Contribution Guide](CONTRIBUTING.md).

docs/GETTING_STARTED.md

@@ -16,10 +16,10 @@ Go straight to [OpenSSA Streamlit app](https://openssa.streamlit.app/) and start
 
 ## Getting Started as a Developer
 
-See some example user programs in the [examples/notebooks](./examples/notebooks) directory. For example, to see the sample use case on ALD semiconductor knowledge, do:
+See some example user programs in the [examples](./examples) directory. For example, to see the sample use case on semiconductor knowledge, do:
 
 ```bash
-% cd examples/notebooks
+% cd examples/semiconductor
 ```
 
 ### Common `make` targets for OpenSSA developers

examples/FDUA/.gitignore

@@ -0,0 +1,15 @@
+# data files
+.data/
+
+# environment variables
+.env
+
+# iPython/Jupyter notebooks
+*.ipynb
+
+# log files
+.log/
+*.log
+
+# Streamlit secrets
+.streamlit/secrets.toml

examples/FinanceBench-Lite/.env.template

@@ -0,0 +1,2 @@
+HF_API_KEY=[... HuggingFace API key if running HuggingFace-hosted models ...]
+OPENAI_API_KEY=[... OpenAI API key if running on OpenAI services ...]

examples/FinanceBench-Lite/.gitignore

@@ -0,0 +1,15 @@
+# data files
+.data/
+
+# environment variables
+.env
+
+# iPython/Jupyter notebooks
+*.ipynb
+
+# log files
+.log/
+*.log
+
+# Streamlit secrets
+.streamlit/secrets.toml

examples/FinanceBench-Lite/Makefile

@@ -0,0 +1,33 @@
+dana-solve:
+	@poetry run python dana.py ${id}
+
+dana-solve-w-knowledge:
+	@poetry run python dana.py ${id} --knowledge
+
+dana-solve-w-prog-store:
+	@poetry run python dana.py ${id} --prog-store
+
+dana-solve-w-knowledge-and-prog-store:
+	@poetry run python dana.py ${id} --knowledge --prog-store
+
+dana-solve-w-llama3:
+	@poetry run python dana.py ${id} --llama3
+
+dana-solve-w-knowledge-w-llama3:
+	@poetry run python dana.py ${id} --knowledge --llama3
+
+dana-solve-w-prog-store-w-llama3:
+	@poetry run python dana.py ${id} --prog-store --llama3
+
+dana-solve-w-knowledge-and-prog-store-w-llama3:
+	@poetry run python dana.py ${id} --knowledge --prog-store --llama3
+
+dana-solve-all-combos:
+	@poetry run python dana.py ${id}
+	@poetry run python dana.py ${id} --knowledge
+	@poetry run python dana.py ${id} --prog-store
+	@poetry run python dana.py ${id} --knowledge --prog-store
+	@poetry run python dana.py ${id} --llama3
+	@poetry run python dana.py ${id} --knowledge --llama3
+	@poetry run python dana.py ${id} --prog-store --llama3
+	@poetry run python dana.py ${id} --knowledge --prog-store --llama3

examples/FinanceBench-Lite/README.md

@@ -0,0 +1,58 @@
+<!-- markdownlint-disable MD013 MD043 -->
+
+# OpenSSA-FinanceBench Lite benchmarking
+
+This is a lite version of the benchmarking of `OpenSSA` performance
+on the `FinanceBench` dataset. We will use 1 question from the dataset to demonstrate the use of `OpenSSA` with `DANA` architecture.
+
+## [`FinanceBench` Dataset](https://github.com/patronus-ai/financebench/blob/main/financebench_sample_150.csv)
+
+## Getting Started with DANA Agent
+
+Have Python 3.12 installed.
+
+__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 problem `00807` `financebench_id`:
+__`make dana-solve id=00807`__.
+
+### Question
+
+`Does 3M have a reasonably healthy liquidity profile based on its quick ratio for Q2 of FY2023? If the quick ratio is not relevant to measure liquidity, please state that and explain why.`
+
+### Knowledge
+
+To solve this question, you can add knowledge related to `liquidity`. See the example below:
+
+- Liquidity Metric Formulas
+  - `(Net) Working Capital` = `(Total) Current Assets` - `(Total) Current Liabilities`
+  - `Working Capital Ratio` = `(Total) Current Assets` / `(Total) Current Liabilities`
+
+Go to `knowledge-store.txt` to add relevant knowledge yourself and see how it helps the agent to solve this question.
+
+### Program
+
+With the above-provided knowledge, the program we can provide to the agent could be as below:
+
+- Goal: To assess liquidity health of a company, calculate `quick ratio`
+  - Task: To calculate `quick ratio`, use this formula
+            `Quick Ratio` = (
+          (`Cash & Cash Equivalents` +
+           `Short-Term Investments or (Current) Marketable Securities` +
+           `(Net) Accounts Receivable, a.k.a. (Net) (Trade) Receivables`)
+          / `(Total) Current Liabilities`
+        )
+        - Sub-task 1: What are values in dollars of `Cash & Cash Equivalents`?
+        - Sub-task 2: What are values in dollars of `Short-Term Investments or (Current) Marketable Securities`?
+        - Sub-task 3: What are values in dollars of `(Net) Accounts Receivable, a.k.a. (Net) (Trade) Receivables`?
+        - Sub-task 4: What are values in dolloars of `(Total) Current Liabilities`?
+
+Go to `program-store.yml` to see details of the program yourself! You can experimenting with different plans to see how it helps the agent solve the problem as well.
+
+## Advancing DANA Agent with Domain Knowledge and Program Store
+
+- To solve the question with added domain knowledge, run `make dana-solve-w-knowledge id=00807`
+- To solve the question with added domain knowledge and program store, run `make dana-solve-w-knowledge-and-prog-store id=00807`