{"id":19290925,"url":"https://github.com/the-openroad-project/orassistant","last_synced_at":"2025-04-22T06:31:16.675Z","repository":{"id":243367873,"uuid":"810883820","full_name":"The-OpenROAD-Project/ORAssistant","owner":"The-OpenROAD-Project","description":"OpenROAD's Chatbot Assistant","archived":false,"fork":false,"pushed_at":"2025-04-19T23:06:49.000Z","size":12897,"stargazers_count":13,"open_issues_count":19,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-20T00:22:24.048Z","etag":null,"topics":["eda","llm","openroad","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/The-OpenROAD-Project.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-06-05T14:28:10.000Z","updated_at":"2025-04-03T04:19:46.000Z","dependencies_parsed_at":"2024-10-26T14:23:38.393Z","dependency_job_id":"cf52b269-3e38-43a6-9494-4cf522867e2e","html_url":"https://github.com/The-OpenROAD-Project/ORAssistant","commit_stats":null,"previous_names":["the-openroad-project/orassistant"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-OpenROAD-Project%2FORAssistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-OpenROAD-Project%2FORAssistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-OpenROAD-Project%2FORAssistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/The-OpenROAD-Project%2FORAssistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/The-OpenROAD-Project","download_url":"https://codeload.github.com/The-OpenROAD-Project/ORAssistant/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250183135,"owners_count":21388663,"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":["eda","llm","openroad","python3"],"created_at":"2024-11-09T22:22:58.923Z","updated_at":"2025-04-22T06:31:16.668Z","avatar_url":"https://github.com/The-OpenROAD-Project.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ORAssistant\n\n[![ORAssistant CI](https://github.com/The-OpenROAD-Project/ORAssistant/actions/workflows/ci.yaml/badge.svg)](https://github.com/The-OpenROAD-Project/ORAssistant/actions/workflows/ci.yaml)\n\n## Introduction\n\nThe OpenROAD chat assistant aims to provide easy and quick access to information regarding tools, responses to questions and commonly occurring problems in OpenROAD and its native flow OpenROAD-flow-scripts.\n\nThe current architecture uses certain retrieval techniques on OpenROAD documentation and other online data sources. We aim to continuously improve the architecture and the associated the dataset to improve accuracy, coverage and robustness.\n\n## Use Cases\n\n- **Installation and Troubleshooting Assistance:** The chatbot will provide users with quick and accurate solutions to common installation issues and troubleshooting steps.\n- **Easy Access to Existing Resources:** The chatbot will be able to summarize relevant information from OpenROAD documentation, user guides, and online resources to provide concise and actionable answers to user queries.\n\n## Components\n\nWe have divided our app into three components, each of which can be hosted on a separate machine for scalability. \n- Backend: Generates the necessary chat endpoints for users to communicate with.\n- Frontend: We use Streamlit to communicate with a chat endpoint, providing a user-friendly chat interface.\n- Evaluation: Besides the vanilla chat interface, we also have a human evaluation interface for research and development.\n\n## Setup\n\nThis setup involves the setting of both the frontend and backend components. We shall begin with backend: \n\n### Backend Setup\n\n#### Option 1 - Docker\n\nEnsure you have `docker` and `docker-compose` installed in your system.\n\n**Step 1**: Clone the repository:\n\n```bash\ngit clone https://github.com/The-OpenROAD-Project/ORAssistant.git\n```\n\n**Step 2**: Copy the `.env.example` file, and update your `.env` file with the appropriate API keys.\n\n```bash\ncd backend\ncp .env.example .env\n```\n\n**Step 3**: Start the docker container by running the following command:\n\n```bash\ndocker compose up\n```\n\n#### Option 2 - Local Install\n\nPrerequisites: \n- `Python 3.12`, recommended using a virtual environment like `conda`.\n- `wget`\n- `pandoc`\n- `git`\n\n**Step 1**: Install the required dependencies.\n\n ```bash\npip install -r backend/requirements.txt\n```\n\n**Step 2**: Copy the `.env.example` file, and update your `.env` file with the appropriate API keys.\n\n```bash\ncd backend\ncp .env.example .env\n```\n\n**Step 3**: For populating the `data` folder with OR/ORFS docs, OpenSTA docs and Yosys docs, run:\n\n```bash\npython build_docs.py\n\n# Alternatively, pull the latest docs\nmkdir data\nhuggingface-cli download The-OpenROAD-Project/ORAssistant_RAG_Dataset --repo-type dataset --local-dir data/\n```\n\n**Step 4**: To run the server, run:\n\n```bash\npython main.py\n```\n\n**Optionally**: To interact with the chatbot in your terminal, run:\n\n```bash\npython chatbot.py\n```\n\nThe backend will then be hosted at [http://0.0.0.0:8000](http://0.0.0.0:8000). \n\nOpen [http://0.0.0.0:8000/docs](http://0.0.0.0:8000/docs) for the API docs.\n\n### Frontend Setup\n\n**Note**: Please refer to the frontend [README](./frontend/README.md) for more detailed instructions.\n\n- **Step 1**: Set up the `.env` as per the instructions in the frontend [README](./frontend/README.md). Get the [Google Sheet API Key](https://developers.google.com/sheets/api/guides/concepts)\n\n```bash\ncd frontend\ncp .env.example .env\n```\n\n- **Step 2**: Install the necessary requirements. You are encouraged to use a virtual environment for this.\n\n```bash\npip install -r requirements.txt\n```\n\n- **Step 3**: Run streamlit application\n\n```bash\nstreamlit run streamlit_app.py\n```\n\n## Architecture Overview\n\nOpenROAD documentation, OpenROAD-flow-scripts documentation, manpages and OpenSTA documentation is chunked and embedded into FAISS Vector Databases.  \n\nDocuments are first retrieved from the vectorstore using a hybrid retriever, combining vector and semantic search methods. These retrieved documents undergo re-ranking using a cross-encoder re-ranker model.\n\n```mermaid\nflowchart LR\n    id0([Query]) --\u003e id1\n\n    id1([Vectorstore]) --- id2([Semantic Retriever])\n    id1([Vectorstore]) --- id3([MMR Retriever])\n    id1([Vectorstore]) --- id4([BM25 Retriever])\n\n    id2([Semantic Retriever]) -- Retrieved Docs ---\u003e id5([Reranking]) \n    id3([MMR Retriever]) -- Retrieved Docs ---\u003e id5([Reranking])\n    id4([BM25 Retriever]) -- Retrieved Docs ---\u003e id5([Reranking])\n\n    id5([Reranking]) ---\u003e id6(top-n docs)\n \n``` \n\nDepending on the input query, each query can be forwarded to any one of the following retrievers,\n1. General OR/ORFS information\n2. OR tools and commands\n3. OR/ORFS installation\n4. OR Error Messages\n5. OpenSTA docs\n6. Yosys docs\n7. Klayout docs\n\nThe retrievers act as separate tools and can be accessed by the LLM's tool-calling capabilities.\n\nThe `langgraph` framework has been used to make effective use of the multiple retriever tools. Upon receiving a query, a routing LLM call classifies the query and forwards it to the corresponding retriever tool. Relevant documents are the queried from the vectorstore by the tool and sent to the LLM for response generation.\n\n```mermaid\ngraph TD\n    __start__ --\u003e router_agent\n    router_agent -.-\u003e retrieve_general\n    router_agent -.-\u003e retrieve_cmds\n    router_agent -.-\u003e retrieve_install\n    router_agent -.-\u003e retrieve_errinfo\n    router_agent -.-\u003e retrieve_opensta\n    router_agent -.-\u003e retrieve_yosys\n    router_agent -.-\u003e retrieve_klayout\n    retrieve_general --\u003e generate\n    retrieve_cmds --\u003e generate\n    retrieve_install --\u003e generate\n    retrieve_errinfo --\u003e generate\n    retrieve_opensta --\u003e generate\n    retrieve_yosys --\u003e generate\n    retrieve_klayout --\u003e generate\n    generate --\u003e __end__\n```\n\n## Dataset overview\n\nThe RAG dataset used in this project can be found [here](https://huggingface.co/datasets/The-OpenROAD-Project/ORAssistant_RAG_Dataset).\n\nTo modify the dataset, please refer to [build_docs.py](./backend/build_docs.py)\n\n## Tests\n\n```\nmake format\nmake check\n```\n\n## Hosted Version\n\nORAssistant is currently hosted at this [link](https://orassistant.netlify.app/). Feel free to use the application and provide feedback!\n\n## Acknowledgements\n\nThis work is completed as part of the Google Summer of Code 2024 project under the \n[UCSC Open-Source Program Office](https://ucsc-ospo.github.io/osre24/).\nPlease see their contributions at this [link](https://github.com/The-OpenROAD-Project/ORAssistant/wiki/Google-Summer-of-Code-2024).\n\n## Citing this work\n\n**2024-10-27**: Our work has been accepted to [Workshop on Open-Source EDA Technology 2024](https://woset-workshop.github.io/). Kudos to our talented contributors Palaniappan R and Aviral Kaintura (contributed equally)!\n\nIf you use this software in any published work, we would appreciate a citation! Please use the following reference:\n\n```\n@article{kaintura2024orassistant,\n  title={ORAssistant: A Custom RAG-based Conversational Assistant for OpenROAD},\n  author={Kaintura, Aviral and R, Palaniappan and Luar, Shui Song and Almeida, Indira Iyer},\n  journal={arXiv preprint arXiv:2410.03845},\n  year={2024}\n}\n```\n\n```\n@misc{orassistant2024,\n  author = {Kaintura, Aviral and R, Palaniappan and Luar, Shui Song and Iyer, Indira},\n  title = {ORAssistant Repository},\n  year = {2024},\n  url = {https://github.com/The-OpenROAD-Project/ORAssistant},\n  note = {Accessed: 20xx-xx-xx}\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-openroad-project%2Forassistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthe-openroad-project%2Forassistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthe-openroad-project%2Forassistant/lists"}