fix: resolve conflicts with main branch

.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

.vscode/extensions.json

@@ -5,6 +5,8 @@
 
     "charliermarsh.ruff",  // Ruff
 
+    "davidanson.vscode-markdownlint",  // MarkdownLint
+
     "soulcode.vscode-unwanted-recommendations"  // Unwanted Recommendations
   ],
 

Makefile

@@ -41,10 +41,10 @@ install:
 		--with=dev --with=docs --with=lint --with=test
 
 install-editable:
-	@python3 -m pip install -e ".[contrib]" --upgrade
+	@python3 -m pip install -e ".[contrib, langchain]" --upgrade
 
 install-editable-mac-sys:
-	@python3 -m pip install -e ".[contrib]" --upgrade --user --break-system-packages
+	@python3 -m pip install -e ".[contrib, langchain]" --upgrade --user --break-system-packages
 
 
 # LINTING

README.md

@@ -1,50 +1,39 @@
-<!-- markdownlint-disable MD013 MD043 -->
+<!-- markdownlint-disable MD013 MD043 MD050 -->
 
-# `OpenSSA`: Small Specialist Agents for Problem-Solving
+# OpenSSA: Neurosymbolic Agentic AI for Industrial Problem-Solving
 
-`OpenSSA` is an agentic AI framework for solving complex problems in real-world industry domains,
-overcoming the limitations of LLMs and RAG in such settings.
+OpenSSA is an open-source neurosymbolic agentic AI framework
+designed to solve complex, high-stakes problems in industries like semiconductor, energy and finance,
+where consistency, accuracy and deterministic outcomes are paramount.
 
-## Level-2 Intelligence with Planning, Reasoning, domain-specific Knowledge and diverse Resources
+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,
+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.
 
-`OpenSSA` agents, built with powerful Hierarchical Task Planning (HTP) and Observe-Orient-Decide-Act Reasoning (OODAR),
-go far beyond the Level-1 pattern-matching intelligence performed by LLMs and RAG and achieve superior outcomes
-in complex multi-faceted, multi-step tasks. See our [comparative study](https://arxiv.org/abs/2404.11792).
+## Key Benefits of OpenSSA
 
-`OpenSSA` agents can also be armed with domain-specific Knowledge, connected to diverse Resources
-(files, databases, web sources, etc.), and/or be guided by specialized industry experts
-to maximize the accuracy and comprehensiveness in their planning, reasoning and deliberative/iterative problem-solving.
-
-## Open and Extensible Architecture
-
-Committed to promoting and supporting open development in generative AI,
-`OpenSSA` would strive to integrate with a diverse array of LLM backends, especially open-source LLMs.
-If you would like certain LLMs to be supported, please suggest through a GitHub issue, or, even better, submit your PRs.
-
-Additionally, `OpenSSA`'s key Planning, Reasoning, Knowledge and Resource interfaces
-are designed with customizability and extensibility as first-class concerns,
-in order to enable developers to effectively solve problems in their specific industries and specialized domains.
-
-## Small and Resource-Efficient Agents for Practical Real-World Deployment
-
-Specialized, Level-2 intelligence allows `OpenSSA` agents to work well in many applications
-using significantly smaller component models, thereby greatly economizing computing resources.
+- __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 by `pip install openssa` (on Python 3.12 only).
-
-- for bleeding-edge latest capabilities: `pip install https://github.com/aitomatic/openssa/archive/main.zip`
+- 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`__
 
-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 more information, see our [Contribution Guide](CONTRIBUTING.md).
+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/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`