{"id":28916396,"url":"https://github.com/intuit/sac3","last_synced_at":"2025-09-12T21:48:54.704Z","repository":{"id":208500679,"uuid":"709558050","full_name":"intuit/sac3","owner":"intuit","description":"Official repo for SAC3: Reliable Hallucination Detection in Black-Box Language Models via Semantic-aware Cross-check Consistency","archived":false,"fork":false,"pushed_at":"2025-01-18T06:19:21.000Z","size":5109,"stargazers_count":34,"open_issues_count":0,"forks_count":7,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-01-18T07:20:40.689Z","etag":null,"topics":["blackbox","consistency","hallucinations","large-language-models","llm","reliability","semantic"],"latest_commit_sha":null,"homepage":"https://arxiv.org/abs/2311.01740","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intuit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2023-10-24T23:35:23.000Z","updated_at":"2025-01-18T06:19:22.000Z","dependencies_parsed_at":"2023-12-06T23:29:34.137Z","dependency_job_id":"2a2cb701-2ed7-4cdf-8932-7a565a292161","html_url":"https://github.com/intuit/sac3","commit_stats":{"total_commits":16,"total_committers":2,"mean_commits":8.0,"dds":0.125,"last_synced_commit":"f270f140ae8b71539d1f5769c8b4432b08cfdc10"},"previous_names":["intuit/sac3"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/intuit/sac3","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intuit%2Fsac3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intuit%2Fsac3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intuit%2Fsac3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intuit%2Fsac3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intuit","download_url":"https://codeload.github.com/intuit/sac3/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intuit%2Fsac3/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261211973,"owners_count":23125548,"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":["blackbox","consistency","hallucinations","large-language-models","llm","reliability","semantic"],"created_at":"2025-06-21T23:39:21.255Z","updated_at":"2025-09-12T21:48:54.648Z","avatar_url":"https://github.com/intuit.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![made-with-python](https://img.shields.io/badge/Made%20with-Python-red.svg)](#python)\n[![License](https://img.shields.io/github/license/intuit/email-decomposer)](https://raw.githubusercontent.com/intuit/email-decomposer/master/LICENSE)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n\n# SAC$`^3`$: Reliable Hallucination Detection in Black-Box Language Models via Semantic-aware Cross-check Consistency [EMNLP2023]\n\n\n## :fire: News\n- [2024.05] SAC$`^3`$ work was presented as a lightning talk in [Intuit Open Source Meetup](https://lu.ma/intuitoss)!  \n- [2024.02] FastSAC$`^3`$ is a faster version of SAC$`^3`$, reducing the time cost via multithread parallelization.\n- [2024.02] SAC$`^3`$ work will be presented in [AI for Production](https://home.mlops.community/home/events/ai-in-production-2024-02-15) organized by MLOps community!  \n- [2023.12] SAC$`^3`$ blog is published in [Intuit Engineering](https://medium.com/intuit-engineering/intuit-ai-research-debuts-novel-approach-to-reliable-hallucination-detection-in-black-box-language-746d7f720c50) \n- [2023.11] SAC$`^3`$ code and datasets are released.\n- [2023.11] SAC$`^3`$ [arxiv link](https://arxiv.org/abs/2311.01740) is available.\n- [2023.10] SAC$`^3`$ paper is accepted and to appear at EMNLP 2023.\n\n\n## 🤔 What is SAC$`^3`$\n\nSemantic-aware cross-check consistency (SAC$`^3`$) is a novel sampling-based hallucination detection method that expands on the principle of self-consistency checking and incorporates additional mechanisms to detect both question-level and model-level hallucinations by leveraging advances including semantically equivalent question perturbation and cross-model response consistency checking. More details can be found in our paper [arxiv link](https://arxiv.org/abs/2311.01740).\n\n![](notebook/overview_sac3.png)\n\n\n**Key observation**: solely checking the self-consistency of LLMs is not sufficient for deciding factuality. Left: generated responses to the same question may be consistent but non-factual. Right: generated responses may be inconsistent with the original answer that is factually correct.\n\n![](notebook/key_observation.png)\n\n\n--- \n### 🤔 What is FastSAC$`^3`$ [NEW!]\n\nThe major time cost of SAC$`^3`$ is from two phases: sampled evaluations and pair-wise consistency checks. However, both phases can be accelerated by using multithread parallelization. We provide a parallelized version to significantly reduce the time cost while maintaining the same performance accuracy. \n\nWe tested 100 data from [HotpotQA-halu](https://github.com/RUCAIBox/HaluEval) dataset, with different sample sizes (3,5,10,15). The average time per query/question is slightly increasing as the sample size increases but the AUROC performance is almost consistent. Please see our [HotpotQA demo](https://github.com/intuit/sac3/blob/main/fastsac3/hotpotQA_demo.ipynb). \n\n   |    100 data    | 3 samples | 5 samples | 10 samples | 15 samples |\n   |:--------------:|:---------:|:---------:|:----------:|:----------:|\n   | Time per query |   2.23s   |   2.30s   |    4.01s   |    5.45s   |\n   |      AUROC     |   0.682   |   0.671   |    0.678   |    0.680   |\n\n\n\n\n\n\n## 🤖 Installation\n\n\n#### Requirements \n\n- python 3.8\n- openai \u003c= 0.28.1\n\n- Create env and download all the packages required as follows: \n\n```\nconda create -n sac3 python=3.8\nsource activate sac3\npip install -r requirements.txt\n```\n\n\nSAC$`^3`$  can be installed from pip (coming soon!):\n\n```bash\npip install sac3\n```\n\n\n## 🚀 Quickstart\nThe easiest way to start playing is\n1. [```Jupyter Notebook```](notebook/quick_start.ipynb)\n2. Directly run ```python main.py```\n3. Google Colab (coming soon)\n\n\n## 📃 Usage\n\n### Semantic Paraphaser \n\u003e Stage 1: Question-level Cross-checking via Semantically Equivalent Perturbations\n\n``` python\nfrom sac3 import paraphraser\n\n# input information - user question and target answer \nquestion = 'is 3691 a prime number?'\ntarget_answer = 'No, it is not a prime number'\n\n# question pertubations\ngen_question = paraphraser.paraphrase(question, number = 5, model = 'gpt-3.5-turbo', temperature=1.0)\n\n```\nThe output is \n``` \ngen_question = ['1. Can 3691 only be divided by 1 and itself?',\n '2. Are there any factors of 3691 other than 1 and itself?',\n '3. Does 3691 belong to the set of prime numbers?',\n '4. Is 3691 indivisible except by 1 and itself?',\n '5. Is 3691 not evenly divisible by any number other than 1 and itself?']\n\n```\n### LLM Evaluator\n\u003e Stage 2: Model-level Cross-check with Additional Verifier LM\n\n```python\nfrom sac3.evaluator import Evaluate\n\n# call target model, e.g., gpt-3.5 or gpt-4\nllm_evaluate = Evaluate(model='gpt-3.5-turbo')\n\n# sampled multiple responses given the original question \nself_responses = llm_evaluate.self_evaluate(self_question = question, temperature = 1.0, self_num = 5)\n\n# sampled multiple responses given perturbed question\nperb_responses = llm_evaluate.perb_evaluate(perb_question = gen_question, temperature=0.0)\n```\nThe outputs are \n```\nself_responses = \n[\"A: We can check if 3691 is a prime number by testing if it's divisible by any prime number less than or equal to its square root. \\n\\nThe square root of 3691 is approximately 60.77, so we only need to check if it's divisible by prime numbers less than or equal to 60. \\n\\nWe can quickly eliminate even numbers, since 3691 is odd. \\n\\nDivisibility by 3:\\n3 + 6 + 9 + 1 = 19, which is not divisible by 3. Therefore, 3691 is not divisible by 3. \\n\\nDivisibility by 5:\\n3691 does not end in 5 or 0, so it's not divisible by 5. \\n\\nDivisibility by 7:\\nTo check if 3691 is divisible by 7, we can take the last digit (1) and double it, then subtract that result from the remaining digits (369 - 2 = 367). We can continue this process until we get a number we know the divisibility of. \\n\\n36 - 2*1 = 34\\n3 - 2*4 = -5\\n\\nSince -5 is not divisible by 7, neither is 3691. \\n\\nWe can continue checking for divisibility by other prime numbers, but it's clear that 3691 is not divisible by any primes less than or equal to 60. Therefore, 3691 is a prime number.\",\n 'Yes, 3691 is a prime number.',\n 'A: Yes, 3691 is a prime number.',\n 'No, 3691 is not a prime number. It is divisible by 7 and 17.',\n 'A: Yes, 3691 is a prime number.']\n```\n```\nperb_responses = \n['As an AI language model, I can say that 3691 can only be divided by 1 and itself, as it is a prime number.',\n 'As an AI language model, I do not have the ability to manually factorize numbers. However, I can tell you that if there are any factors of 3691 other than 1 and itself, then 3691 would not be a prime number.',\n 'A: No, 3691 is not a prime number as it is divisible by 7 and 527.',\n 'A: Yes, 3691 is indivisible except by 1 and itself, making it a prime number.',\n 'As an AI language model, I can calculate that 3691 is not evenly divisible by any number other than 1 and itself. Therefore, it is a prime number.']\n ```\n### Consistency Checker\n\u003e Stage 3: Semantic-aware Consistency Check of Question-Answering (QA) Pairs\n\n-  Self-checking Consistency (SC$`^2`$) Score\n```python\nfrom sac3.consistency_checker import SemanticConsistnecyCheck\n\n# call LLM to evaluate if the sampled responses are semantically equivalent to the target answer\nscc = SemanticConsistnecyCheck(model='gpt-3.5-turbo')\n\n# self-consistency check \nsc2_score, sc2_vote = scc.score_scc(question, target_answer, candidate_answer = self_responses, temperature = 0.0)\nprint(sc2_score, sc2_vote)\n```\nThe output is \n```\n0.8 [1, 1, 1, 0, 1]\n```\n-   Question-level Consistency (SAC$`^3`$-Q) Score\n``` python\n# question-level consistency check \nsac3_q_score, sac3_q_vote = scc.score_scc(question, target_answer, candidate_answer = perb_responses, temperature = 0.0)\nprint(sac3_q_score, sac3_q_vote)\n```\nThe output is \n```\n0.6 [1, 0, 0, 1, 1]\n```\n\n### Illustrative Example \n\nAn illustrative example of self-consistency, cross-question consistency, and cross-model consistency check.\nThe original question and answer are “Is 3691 a prime number?” and “No, 3691 is not a prime number.\nIt is divisible by 7 and 13”, respectively. Each row presents a set of sampled QA pairs along with its\nconsistency regarding the original answer, and the predicted factuality of the original answer. \n\n![](notebook/example.png)\n\n\n## 💁Citation \n\n```\n@inproceedings{zhang-etal-2023-sac3,\n    title = \"{SAC}$^3$: Reliable Hallucination Detection in Black-Box Language Models via Semantic-aware Cross-check Consistency\",\n    author = \"Zhang, Jiaxin  and\n      Li, Zhuohang  and\n      Das, Kamalika  and\n      Malin, Bradley  and\n      Kumar, Sricharan\",\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.1032\",\n    doi = \"10.18653/v1/2023.findings-emnlp.1032\",\n    pages = \"15445--15458\"\n}\n```\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintuit%2Fsac3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintuit%2Fsac3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintuit%2Fsac3/lists"}