{"id":18440632,"url":"https://github.com/stanford-oval/ovalchat","last_synced_at":"2025-04-07T22:31:45.148Z","repository":{"id":134838096,"uuid":"604465020","full_name":"stanford-oval/ovalchat","owner":"stanford-oval","description":"OVALChat is a customizable Web app aimed at conducting user studies with chatbots","archived":false,"fork":false,"pushed_at":"2024-01-09T19:41:35.000Z","size":3904,"stargazers_count":28,"open_issues_count":6,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-23T01:23:40.535Z","etag":null,"topics":["chatbots","crowdsourcing","nextjs","nlp","react","tailwindcss"],"latest_commit_sha":null,"homepage":"https://wikichat.genie.stanford.edu/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stanford-oval.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-02-21T05:40:08.000Z","updated_at":"2025-03-22T18:27:24.000Z","dependencies_parsed_at":"2023-10-12T04:54:11.421Z","dependency_job_id":"1ba033f6-9e1f-4a21-a2cc-f7d54a4d18d0","html_url":"https://github.com/stanford-oval/ovalchat","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stanford-oval%2Fovalchat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stanford-oval%2Fovalchat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stanford-oval%2Fovalchat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stanford-oval%2Fovalchat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stanford-oval","download_url":"https://codeload.github.com/stanford-oval/ovalchat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247740929,"owners_count":20988296,"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":["chatbots","crowdsourcing","nextjs","nlp","react","tailwindcss"],"created_at":"2024-11-06T06:31:57.536Z","updated_at":"2025-04-07T22:31:40.329Z","avatar_url":"https://github.com/stanford-oval.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003ch1 align=\"center\"\u003e\u003cb\u003eOVALChat\u003c/b\u003e\u003c/h1\u003e\n    \u003cp align=\"center\"\u003eQuick and easy way to conduct user studies with chatbots\u003c/p\u003e\n    \u003cp align=\"center\"\u003e\n        \u003ca href=\"https://stanford.edu\" target=\"_blank\"\u003e\n            \u003cimg src=\"./public/img/logos/stanford/university.png\" width=\"140px\" alt=\"Stanford University\" /\u003e\n        \u003c/a\u003e\n    \u003c/p\u003e\n    \u003cp align=\"center\" style=\"align: center;\"\u003e\n        \u003ca href=\"https://vercel.com/?utm_source=[stanford-oval]\u0026utm_campaign=oss\" target=\"_blank\"\u003e\n            \u003cimg src=\"./public/img/logos/vercel/powered-by.svg\" width=\"150px\" alt=\"Powered by Vercel\" /\u003e\n        \u003c/a\u003e\n    \u003c/p\u003e\n\u003c/p\u003e\n\n\u003chr /\u003e\n\n\n## About\n\nThis repository contains researcher-friendly code to quickly bring up a web-based chatbot to conduct user studies.\nFeatures include:\n- Support for multiple users at the same time\n- Easily customizable UI\n- Ready to deploy to [Vercel](https://vercel.com/)\n- Support for user studies: You can easily ask users to select the best system configuration per turn, by showing them side-by-side replies via the \"Contribute\" page. They will receive a code after finishing a predetermined number of turns, which can be used to link their response to other platforms like Amazon Mechanical Turk.\n\nThis project built with Next.js, Tailwind CSS, OpenAI's GPT-3, and Microsoft Azure's Speech Services.\n\n## Customize the UI\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://user-images.githubusercontent.com/60150701/227457109-82c5e33e-8c17-4a10-82bf-acbbd87857fb.png\" height=\"300\"/\u003e\n    \u003cbr\u003e\n    This is what the default chat interface looks like.\n\u003c/p\u003e\n\nYou can customize this and the full page, by simply changing the following files:\n- `src/components/global/branding.tsx`: Contains \"branding\" information for the website. Update all functions to match your brand.\n- `src/data/socials.ts`: Update social media and website links.\n- `tailwind.config.js`: Update the theme colors under `ovalchat`.\n\n\n## Developer Setup\n\nCreate a `.env.local` file for the following environment variables. \n\nFor the chatbot to talk to the back-end, you should set `NEXT_PUBLIC_CHAT_BACKEND=https://[your back-end domain]:[port number]` (without `/` at the end).\n\nFor the speech-to-text and text-to-speech functionality, create an Azure speech resource (and a corresponding resource group).\n\n```bash\nSPEECH_KEY=[your API key]\nSPEECH_REGION=[your API key]\n```\n\nTo do crowdsourcing in the \"Contribute\" page, set the following variables to your desired values in the same file.\n```bash\nNEXT_PUBLIC_CROWDSOURCE_MAX_TURNS=8     # Users will be prompted to stop after this many turns\n```\n\n## Run in Development Mode\n### Implement a custom back-end\nA mock back-end implementation is available in `test_backend.py`. Install the python packages in `requirements.txt`.\n\nThis mock implementation only echoes back the inputs it receives. To make your chatbot actually work, you need to implement a custom back-end in this file. Read through `test_backend.py` and implement your own logic there. Most applications need to read and write user inputs to/from a database like MongoDB. If you only have a single user, e.g. when testing the application on your local system, you can use a Python data structure for this purpose instaed of a database, but note that these data structures are not [thread-safe](https://en.wikipedia.org/wiki/Thread_safety) and therefore not suitable for applications that have concurrent users.\n\n### Run the back-end\nRun\n\n```bash\npython test_backend.py\n```\nThis will bring up a local web server on port 5001. Meaning that requests to `http://localhost:5001` will be handled by this server.\nYou can set `NEXT_PUBLIC_CHAT_BACKEND` to `http://localhost:5001` to develop and test the application on your local system.\n\n### Run the front-end\nTo run the front-end locally for development, install the dependencies from your package manager and start the Next.js app.\n\n```bash\nyarn install\nyarn run dev\n```\nYou will see a message like `ready - started server on 0.0.0.0:3000, url: http://localhost:3000`. This means that you can access the website via a web browser by visiting http://localhost:3000.\n\n## Deploy the front-end\nSo far, we have been running the server in \"development\" mode, where changes to the code automatically refreshes any open webpage, and provides extensive debugging information when an error happens. This is not needed when deploying the front-end, and just slows down the website. To run the server in deployment mode, run:\n```bash\nyarn build\nyarn start\n```\nIf you want to deploy the front-end on port 80 (so that you can visit the front-end without the need to type in a port number in the browser), you need to first give node permission to use ports below 1024. Run:\n```bash\nsudo apt-get install libcap2-bin\nsudo setcap cap_net_bind_service=+ep `readlink -f \\`which node\\``\n```\nThen add `-p 80` option to the above `yarn start` command.\n\n### Deploy the front-end to Vercel\nThis website can be easily deployed to vercel.com\nIf you want to deploy from a branch other than `main`, you need to change the `vercel-deploy-branch.sh` script to allow your branch to be deployed.\n\n## Citation\n\nIf you have used this repository, please cite the following paper:\n\n```bibtex\n@inproceedings{semnani-etal-2023-wikichat,\n    title = \"{W}iki{C}hat: Stopping the Hallucination of Large Language Model Chatbots by Few-Shot Grounding on {W}ikipedia\",\n    author = \"Semnani, Sina  and\n      Yao, Violet  and\n      Zhang, Heidi  and\n      Lam, Monica\",\n    booktitle = \"Findings of the Association for Computational Linguistics: EMNLP 2023\",\n    month = dec,\n    year = \"2023\",\n    address = \"Singapore\",\n    publisher = \"Association for Computational Linguistics\",\n    url = \"https://aclanthology.org/2023.findings-emnlp.157\",\n    pages = \"2387--2413\",\n}\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstanford-oval%2Fovalchat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstanford-oval%2Fovalchat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstanford-oval%2Fovalchat/lists"}