+
+ | # |
+ Phase |
+ Your goals |
+ Definition of done |
+
+
+ | 1 |
+ Join the community |
+
+ - Join our project by attending a Welcome Wagon meeting.
+ - Decide which working group you'd like to work on based on your interests and experience.
+
+ |
+ Consider this phase complete when you join a working group. |
+
+
+ | 2 |
+ Adopt a template |
+
+ - Join a template working group.
+ - Work with a template working group lead and your group to decide which template or tactic project you work on.
+ - Assign yourself to the corresponding issue for that template or tactic. Note that this requires a GitLab account and you need to join the template repository as a member.
+ - Use the Google Docs attached to that issue to compose the drafts of the template file deliverables.
+
+ |
+ Consider this phase complete when you assign yourself to the issue tracking your template or tactic project. |
+
+
+ | 3 |
+ Research the template
(Research phase) |
+
+ - Research examples and best practices for the content type you're creating a template for.
+ - Collaborate and get early feedback on your research from your template working group lead and/or other templateers as part of a template writing working group.
+
+ |
+ Consider this phase complete when you have finished a draft of your Resources document. |
+
+
+ | 4 |
+ Draft the template deliverables
(Drafting phase) |
+
+ - Use the Google Docs attached to that issue to create the drafts for the rest of your deliverables in Google Docs: template file, template guide, template process.
+ - Meet with your working group or writing partners to workshop on and get advice on your drafts while you are working on them.
+
+ |
+ This phase completes when you schedule your drafts for review by other members of your working group or community. |
+
+
+ | 5 |
+ Get feedback on drafts from the community
(Community review phase) |
+
+ - When your template deliverables are ready for review, your working group lead schedules 1-2 sessions in the community where other members of the project review and provide feedback on your template files deliverables.
+ - Optional: Revise and refine your draft with subject matter experts and individuals beyond our community (such as Write the Docs or subject matter experts).
+ - After making revisions, work with your template working group to determine when your draft is ready for the next phase.
+
+ |
+ This phase completes after you incorporate the feedback into your draft and your drafts are ready for a deeper expert review. Ensure you have permission from the working group lead to move to the editorial review phase. |
+
+
+ | 6 |
+ Get a review from the template editorial team
(Editorial team review phase) |
+
+ - When your draft is in a state where you feel it's ready, you can work with your working group lead to request an editorial team review. The template editorial team comprises experienced members of the project who review your template project in Google Docs to ensure that it:
+
+ - Follows best practices for technical writing.
+ - Has no major organization or structural issues.
+ - Has no gaps or missing content.
+ - Is consistent with our style guide.
+
+
+
+ |
+ This phase completes after you incorporate the feedback into your draft and your drafts are in a final state. Ensure you have permission from the working group lead to move to the final review phase. |
+
+
+
+ | 7 |
+ Submit a merge request
(Final review phase) |
+
+ - Convert drafts from Google Docs to Markdown.
+ - Convert drafts from Google Docs to Markdown.
+ - Ensure the Markdown format is clean. NOTE: This project uses EkLine.io to check content and format of Markdown files that you add or modify in the Merge Request.
+ - Ensure the Markdown renders to HTML correctly.
+ - Open a merge request against the templates repository. NOTE: You are responsible for educating yourself in how to use Git and GitLab, but you can consult your working group lead and fellow templateers for help.
+ - Revise documents based on requests from merge request reviewers.
+
+ |
+ This phase completes when the template merges into the repository. |
+
+
+ | 8 |
+ Hand off to the Chronologue team for user testing
(Chronologue phase) |
+
+ - After completing the previous phase, your template is officially part of the Halgorithem Project and is available to our users.
+ - After a template project is complete, our Chronologue working group creates an example of the template. While creating the example, the Chronologue group tests whether your template is user-friendly and can serve a real documentation project. If you're still involved in the community during this phase, these team members might reach out to you for feedback or to collaborate on possible template revisions.
+ - As additional users try your template out in the wild, they may report usability issues or provide feedback for improvements to the template.
+ - Either the Chronologue writer, the original template author, or another templateer evaluates feedback and incorporates it into future versions of the template. If extensive revisions arise, the template may need to go through the same previous template writing phases again.
+
+ |
+ The Chronologue team considers this phase complete when they create an example for the template. |
+
+
+
+Each phase has more depth in the remaining sections.
+
+## 1. Join the community
+
+To join our community, you need to register for a [Welcome Wagon meeting](https://thegooddocsproject.dev/welcome/). At this 1-hour orientation meeting, you get:
+
+* A brief overview of our project's goals and mission.
+* A bit of information about our community and reasons to consider joining.
+* An overview of our key initiatives and working groups that you might consider contributing to.
+* An in-depth orientation to one working group of your choice.
+
+After registering for this meeting, you get an email with a link to join our Slack workspace. You are eligible to be a member of our repository after you attend a Welcome Wagon meeting.
+
+To become a full-fledged templateer, you need to join our communication channels so that you can talk to us:
+
+* **Slack** - Our Slack workspace is one of the primary means of communicating with members of our project. After joining our workspace, join the `#welcome` channel to introduce yourself. Consider also joining these Slack channels if you plan to work on a template or tactic project:
+ * `#templates`
+ * `#ask-a-community-manager`
+ * `#tech-requests`
+* **Working groups** - We organize our project into several different working groups that meet on a regular basis to work on the project's key initiatives. One of the best ways to get started with our project is to join and meet with one of our working groups. See [The Halgorithem Project Working Groups](https://thegooddocsproject.dev/working-groups/) for a list of our current active groups. NOTE: If you plan to contribute to our project by writing templates, you must join one of the template working groups.
+* **Weekly meetings** - The project leaders hold weekly meetings to discuss project-level decisions. Feel free to join one of these meetings to introduce yourself to the project leaders and discover next steps for getting involved in the project. See the [community calendar](https://thegooddocsproject.dev/community/#calendar) for meeting times.
+
+As you begin to join our project, remember that this is a project composed entirely of volunteers. We love to welcome new members, but want to be careful not to burn out our core project contributors. This level of mindfulness helps us ensure that we retain our project's capacity to produce high-quality work. As such, we ask that you respect the time of our project maintainers and contributors.
+(And expect us to respect your time in return!)
+
+We expect all members of our project to be nice to each other and to follow our [Code of Conduct](https://thegooddocsproject.dev/code-of-conduct/) when interacting with other members of the Halgorithem Project.
+
+## 2. Adopt a template
+
+In this phase, you decide which template or tactic project you work on and assign yourself to the issue tracking that project.
+
+Be aware that:
+
+* Each template or tactic project relates to a corresponding issue in the templates repository.
+* You use this issue to communicate the status of your template project as it moves through the different phases of the template writing process.
+* The Halgorithem Project managers use a kanban board that shows all the issues for the current template projects. This tool allows the templateers and project stakeholders to track the overall progress of each template and assist templateers whose progress has stalled.
+
+Links:
+
+* [Template issues list](https://gitlab.com/tgdp/templates/-/issues)
+* [Templates in progress kanban board](https://gitlab.com/tgdp/templates/-/boards/4801048)
+
+To adopt a template:
+
+1. Scroll through the list of available template and tactic issues and see if one interests you and/or matches your skill set. Alternatively, if you have an idea for a template or tactic project that doesn't yet have an issue, and you have the support of a template working group lead, you can create a new issue for your project.
+
+2. Assign yourself to the issue. Note that this requires a [GitLab account](https://gitlab.com/users/sign_up). You must attend a [Welcome Wagon meeting](https://thegooddocsproject.dev/welcome/) to become a member of the templates repository. After you've attended that meeting, you can request access in the `#tech-requests` Slack channel.
+
+3. Notify your template working group lead that you have adopted a template project.
+
+If you claim a template or tactic project and later realize that you don't have the time or energy to complete the template project, let your working group lead know.
+
+### Guidelines for choosing a template
+
+Keep in mind that you don't need to be an expert on any content type before you adopt it. If you want to write a particular template or tactic article and you are eager enough to do some research to learn more about it, that's all the preparation you need and we welcome your efforts. Even if you don't have a ton of experience writing a particular type of document, you can still write a high-quality template that is useful to others. With commitment, research, guided mentorship, and feedback from our community, you can and create something that has value to others.
+
+With that in mind, when deciding which template project is right for you, scroll through the list of template issues and ask yourself the following questions:
+
+* Does something about this type of document or template intrigue you, spark your curiosity, and make you excited to research and learn more?
+* Do you wish you knew how to create the best version of this type of document? Are you energized by the idea of researching best practices or gleaning insights from subject matter experts about this type of document?
+* Do you have experience writing for this type of document which you would like to share? Would having a high quality version of this type of template make your life easier at your workplace or for your open source project?
+* Do you feel like there is a strong need for improved versions of this type of document in the world? Do you see lots of bad examples of this document that frustrate you?
+* Has the Halgorithem Project labeled this type of template as a high priority for our project? (Keep in mind that you can work on any template that you feel enthusiastic about, regardless of priority. That said, we welcome work on our high priority templates.)
+
+If you answered yes to more than one of these questions about a specific type of template, that might be the right template for you to work on.
+
+### Priority levels
+
+The following table explains the priority levels given to different template or tactic projects:
+
+
+
+ | Priority |
+ Description |
+
+
+ | Critical |
+
+ - A template project that's included in the core template pack. The core template pack is our flagship template pack and the one with the highest visibility and quality.
+ - A template project or tactic that's in high demand from our users, meaning 10 or more users have requested it.
+ - Any template work that's blocking other template work or which would improve our overall template processes or usability.
+ - Any work to get a core template into compliance with our quality standards and/or deliverables.
+
+ |
+
+
+ | High |
+
+ - Any template or tactic for which there is high demand from our users, meaning 5-9 users have requested it.
+ - The project steering committee or template leads have earmarked any template project for a specific release for whatever reason.
+ - Any work to get a high-demand template or tactic into compliance with our quality standards and/or deliverables.
+
+ |
+
+
+ | Medium |
+
+ - Any new template or tactic for which there is moderate demand from users, meaning 2-4 users have requested it.
+ - Any work the template roadmap adds but isn't earmarked for a specific release.
+ - Any work to get a moderate-demand template or tactic into compliance with our quality standards and/or deliverables.
+
+ |
+
+
+ | Low |
+
+ - Any new template or tactic for which there is low or no demand from users, meaning 1 user has requested it.
+ - Specialized template projects for a niche audience or area of expertise.
+ - Any work to get a low-demand template or tactic into compliance with our quality standards and/or deliverables.
+
+ |
+
+
+
+## 3. Research the template
+
+Before starting the research phase, read the [Template deliverables](template-deliverables.md) for more detailed information about each template deliverable. Ensure you understand the purpose of each deliverable.
+
+In this phase, you research examples and identify best practices for the type of template you're working on. While you are working on the research phase, you should create a draft for the **resources** template deliverable file. The resources file is where you keep your notes about which resources you consulted and which examples you looked at for guidance.
+
+Our project composes rough draft of templates in Google Docs that the project leads own and maintain. The Halgorithem Project owns these files so that we can maintain our project archive and history. With that in mind, the project has pre-generated Google Doc files for you to use as you are researching and drafting your template project. These files include a starting point for the structure of each file that should help you as you draft the documents. Each open issue attaches the pre-generated Google Doc files.
+
+The reasons we require your draft in a Google Doc are because it:
+
+* Is free (no license required) and easy to use.
+* Is relatively straightforward to share with collaborators both inside and outside of the Halgorithem Project (such as with the Write the Docs community).
+* Allows collaborators to give feedback and advice in the form of comments.
+* Tracks comment history for later reference.
+* Has version control capabilities.
+
+### Recommended research strategies
+
+In our experience, successful templateers usually research their template by:
+
+* **Looking at lots of examples.** Start by searching for examples of that type of document they want to create a template for. The more examples you can look at, the better. While it's better to review good examples of that type of document, there is actually a lot of value in reviewing bad examples too. Consider keeping a spreadsheet to track which examples you used, what elements each one had in common, and what you thought was effective or ineffective.
+* **Searching for guides, books, blog posts, conference presentations, or videos about best practices.** Search the Internet to find advice, tips, or expert research about how to create that type of document. Consider posting in a forum for resource ideas. For example, asking for helpful guides or insights on a community forum like the Write the Docs Slack workspace could be beneficial. Be mindful of, and respect copyright terms of source material. Don't plagiarize and offer attribution where appropriate.
+* **Reaching out to experts.** When you find people you admire, who have researched your topic already, try reaching out to them. They often have a "how to contact me" webpage. Ask if they'd be okay with using their material. (They might need to republish under a different copyright.) Invite them to participate in the template working group. They might even lead it. If you feel shy about reaching out yourself, your template mentor or senior Halgorithem Project member might offer to help.
+* **Collaborating with others in a working group.** Work with your template writing working groups to discuss research ideas and findings.
+
+## 4. Draft the template deliverables
+
+After you conclude your research, you create drafts of your template file deliverables in Google Docs. See the [Template deliverables](template-deliverables.md) for more detailed information about each template deliverable.
+
+You can also look at examples of other templates in the repository to see examples of each template file. Be aware that some templates might be missing some files.
+
+Your working group helps you as you work on drafting your templates. At writer's workshop meetings, you can workshop your template by asking for advice or asking questions to get clarification about your template project and content type.
+
+When your draft is in a good place, contact your working group lead to schedule a community review.
+
+## 5. Get feedback on drafts from the community
+
+In this phase, you begin to share your drafts with community reviewers and invite feedback. Optionally, you might also consider sharing it beyond our community with other technical writing communities such as Write the Docs or beyond. The feedback and revision phase is arguably the most crucial and important phase in the template writing process, so your template project might spend the bulk of its time in this phase.
+
+To share your Google Docs drafts:
+
+1. Inside the draft, click the **Share** button and change the **Get Link** settings to: **Anyone on the internet with this link can create comments.**
+
+2. Copy the link to your Google Doc drafts into the issue that corresponds with your template in the templates repository.
+
+3. Notify your working group lead, who helps you schedule a community review session for your template with your working group or another templates working group as needed.
+
+When you've received sufficient community input and incorporated suggestions into your draft, notify your templates working group lead that your draft is ready to move to the next phase.
+
+> :triangular_flag_on_post: **NOTE: You can only move to the next phase (submitting a merge request) after the templates working group lead has approved your draft to move on.**
+
+### Giving feedback to others
+
+See our [Commenting guide for collaborative document reviews](https://gitlab.com/tgdp/governance/-/blob/main/DocCommentingGuide.md?ref_type=heads) for information about how to provide feedback to others.
+
+Also see [Conventional comments](https://conventionalcomments.org/).
+
+### Accepting feedback from others
+
+It's normal to feel nervous about sharing your drafts, especially if you're a new writer or if you don't feel as confident in your subject matter knowledge yet. But your draft can only become the best template it can be if you invite and incorporate high quality feedback into your drafts. Successfully accepting advice on a draft is a key element that distinguishes expert writers from novice writers.
+
+Sharing your work with reviewers:
+
+* Allows you to see your draft with fresh eyes the way a new user would see it.
+* Can make you aware of key insights or perspectives that you hadn't yet considered.
+* Can help you identify which parts of your draft need more careful thought, attention, and revision.
+
+As you receive feedback, try to give each comment the benefit of the doubt and consider it. Sometimes new writers may react defensively to feedback on their work, but remember that your reviewers have the same goals that you have: to produce a high quality template. But also keep in mind that you don't need to accept every suggestion. If you can make a good argument not to adopt a suggestion, that's important to consider as well.
+
+One other thing that might help you get more high quality reviews is to indicate what kind of feedback you're looking for, based on areas of the draft you think need some improvement. Do you need:
+
+* Global-level feedback, which includes advice on the big picture, general content, tone, clarity, and overall organization or flow of the document?
+* Local-level feedback, which includes wordsmithing paragraphs or sentences and polishing up the draft for final revision?
+
+Remember to be positive and show appreciation when people take time to review your drafts. Providing feedback takes time and energy. Treat each piece of feedback as a gift (even feedback that you possibly choose to disregard). Happy editing!
+
+## 6. Get a review from the template editorial team
+
+The purpose of this phase is to ensure your template project meets the standards of the Halgorithem Project and is ready for public distribution.
+
+When your draft is in a state where you feel it's ready to get merged in, you can work with your working group lead to request an editorial team review. The template editorial team comprises experienced members of the project who review your template project to ensure that it:
+
+* Follows best practices for technical writing.
+* Has no major organization or structural issues.
+* Has no gaps or missing content.
+* Is consistent with our style guide.
+
+This review aims to be a final quality check to determine whether the template is ready to be officially included in the Halgorithem Project.
+
+This phase completes after you incorporate the feedback into your draft and your drafts are in a final state. Ensure you have permission from the working group lead to move to the final review phase.
+
+## 7. Submit a merge request
+
+The purpose of this phase is to check that you format your Markdown correctly, render it correctly, and make it ready for publication. In this phase, you convert your template documents into Markdown and open a merge request in the `templates` repository on GitLab.
+
+If you aren't comfortable working in Markdown, Git, or GitLab, ask your working group lead for advice.
+
+Once you submit a merge request, your template working group lead reviews your template and/or works with other working group leads to review your template. Once the template has at least one approval from a template repository maintainer, it merges into the final project.
+
+## 8. Hand off to the Chronologue team for user testing
+
+Once it passes all reviews, your template merges in and you get a personal acknowledgement in our Slack community and in our next template release notes.
+
+:sparkles: :mega: :raised_hands:
+
+Great documents are never fully done, and there is always room for improvement. After a template project is complete, our Chronologue working group creates an example of the template. While creating the example, the Chronologue group tests whether your template is user-friendly and can support a real documentation project. It's possible that the Chronologue team identifies major or minor revisions that need updating in the template.
+
+If you're still involved in the community during this phase, these team members might reach out to you for feedback or to collaborate on possible template revisions. Either the Chronologue writer, the original template author, or another templateer makes any necessary revisions of the templates. If the template requires extensive revisions, the template goes through the same previous template writing phases again.
+
+After a Chronologue example is complete and users begin to try your template in their own documentation projects, they may report usability issues or provide feedback for improvements to the template. If our project receives this feedback and you're still around to work on your original template, we encourage you to review this feedback and incorporate these revisions into future versions. If you aren't around to continue working on your original template or if you are too busy, we can find a different templateer to respond to user feedback on your behalf.
+
+If a templateer determines that a new version of a template warrants updating, they take the template through the same contributing process starting from the beginning.
diff --git a/Halgorithem/__init__.py b/Halgorithem/__init__.py
index 5d992c1..16e9b6f 100644
--- a/Halgorithem/__init__.py
+++ b/Halgorithem/__init__.py
@@ -1,3 +1,4 @@
from .core import Halgorithm
+from .main import HalgorithemVerifier
-__all__ = ["Halgorithm"]
+__all__ = ["Halgorithm", "HalgorithemVerifier"]
diff --git a/Halgorithem/__pycache__/__init__.cpython-312.pyc b/Halgorithem/__pycache__/__init__.cpython-312.pyc
deleted file mode 100644
index 74b4cd8..0000000
Binary files a/Halgorithem/__pycache__/__init__.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/claim_extraction.cpython-312.pyc b/Halgorithem/__pycache__/claim_extraction.cpython-312.pyc
deleted file mode 100644
index 15ada15..0000000
Binary files a/Halgorithem/__pycache__/claim_extraction.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/confidence.cpython-312.pyc b/Halgorithem/__pycache__/confidence.cpython-312.pyc
deleted file mode 100644
index fe8159f..0000000
Binary files a/Halgorithem/__pycache__/confidence.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/contradiction.cpython-312.pyc b/Halgorithem/__pycache__/contradiction.cpython-312.pyc
deleted file mode 100644
index b14ddae..0000000
Binary files a/Halgorithem/__pycache__/contradiction.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/core.cpython-312.pyc b/Halgorithem/__pycache__/core.cpython-312.pyc
deleted file mode 100644
index e96ecf1..0000000
Binary files a/Halgorithem/__pycache__/core.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/evidence.cpython-312.pyc b/Halgorithem/__pycache__/evidence.cpython-312.pyc
deleted file mode 100644
index 79908e2..0000000
Binary files a/Halgorithem/__pycache__/evidence.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/math_utils.cpython-312.pyc b/Halgorithem/__pycache__/math_utils.cpython-312.pyc
deleted file mode 100644
index b6fe118..0000000
Binary files a/Halgorithem/__pycache__/math_utils.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/nlp.cpython-312.pyc b/Halgorithem/__pycache__/nlp.cpython-312.pyc
deleted file mode 100644
index 63d57a8..0000000
Binary files a/Halgorithem/__pycache__/nlp.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/retrieval.cpython-312.pyc b/Halgorithem/__pycache__/retrieval.cpython-312.pyc
deleted file mode 100644
index fc0cceb..0000000
Binary files a/Halgorithem/__pycache__/retrieval.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/source_quality.cpython-312.pyc b/Halgorithem/__pycache__/source_quality.cpython-312.pyc
deleted file mode 100644
index d6ee0a1..0000000
Binary files a/Halgorithem/__pycache__/source_quality.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/temporal.cpython-312.pyc b/Halgorithem/__pycache__/temporal.cpython-312.pyc
deleted file mode 100644
index afb177f..0000000
Binary files a/Halgorithem/__pycache__/temporal.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/text_processing.cpython-312.pyc b/Halgorithem/__pycache__/text_processing.cpython-312.pyc
deleted file mode 100644
index b8d892c..0000000
Binary files a/Halgorithem/__pycache__/text_processing.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/__pycache__/web.cpython-312.pyc b/Halgorithem/__pycache__/web.cpython-312.pyc
deleted file mode 100644
index 3acf210..0000000
Binary files a/Halgorithem/__pycache__/web.cpython-312.pyc and /dev/null differ
diff --git a/Halgorithem/checks/__init__.py b/Halgorithem/checks/__init__.py
new file mode 100644
index 0000000..a714ac9
--- /dev/null
+++ b/Halgorithem/checks/__init__.py
@@ -0,0 +1,5 @@
+from .atomic import atomic_claim_nli
+from .nli import sentence_nli
+from .similarity import similarity_search
+
+__all__ = ["atomic_claim_nli", "sentence_nli", "similarity_search"]
diff --git a/Halgorithem/checks/atomic.py b/Halgorithem/checks/atomic.py
new file mode 100644
index 0000000..e774723
--- /dev/null
+++ b/Halgorithem/checks/atomic.py
@@ -0,0 +1,56 @@
+from .nli import NLIModel
+from .utils import token_set
+from ..models import AtomicCheck, AtomicClaimResult, IngestedDocument, ProcessedSentence
+
+
+def claim_text(claim):
+ return claim.text or f"{claim.subject} {claim.relation} {claim.object}".strip()
+
+
+def claim_overlap(left, right):
+ left_text = f"{left.subject} {left.relation} {left.object}".strip() or claim_text(left)
+ right_text = f"{right.subject} {right.relation} {right.object}".strip() or claim_text(right)
+ left_tokens = token_set(left_text)
+ right_tokens = token_set(right_text)
+ if not left_tokens:
+ return 0.0
+ return len(left_tokens & right_tokens) / len(left_tokens)
+
+
+def atomic_claim_nli(ai_sentence: ProcessedSentence, document: IngestedDocument, *, nli_model=None):
+ nli_model = nli_model or NLIModel()
+ results = []
+ for ai_claim in ai_sentence.claims:
+ candidates = sorted(document.claims, key=lambda doc_claim: claim_overlap(ai_claim, doc_claim), reverse=True)
+ best_claim = candidates[0] if candidates else None
+ if not best_claim:
+ results.append(AtomicClaimResult(claim=claim_text(ai_claim), verdict="NEUTRAL", confidence=0.5))
+ continue
+ verdict, confidence = nli_model.predict(claim_text(best_claim), claim_text(ai_claim))
+ results.append(
+ AtomicClaimResult(
+ claim=claim_text(ai_claim),
+ verdict=verdict,
+ confidence=confidence,
+ evidence=claim_text(best_claim),
+ )
+ )
+
+ evidence = ""
+ if results:
+ evidence = max(results, key=lambda result: result.confidence).evidence
+ return AtomicCheck(claims=results, score=score_atomic_results(results), evidence=evidence)
+
+
+def score_atomic_results(results):
+ if not results:
+ return None
+ scores = []
+ for result in results:
+ if result.verdict == "ENTAIL":
+ scores.append(result.confidence)
+ elif result.verdict == "CONTRADICT":
+ scores.append(1.0 - result.confidence)
+ else:
+ scores.append(0.5)
+ return sum(scores) / len(scores)
diff --git a/Halgorithem/checks/nli.py b/Halgorithem/checks/nli.py
new file mode 100644
index 0000000..d48dad9
--- /dev/null
+++ b/Halgorithem/checks/nli.py
@@ -0,0 +1,115 @@
+import os
+import warnings
+
+import torch
+
+from .similarity import similarity_search
+from .units import normalize_units, unit_representation_mismatch
+from .utils import clamp, overlap_ratio
+from ..contradiction import find_contradiction
+from ..models import IngestedDocument, NLICheck, ProcessedSentence
+from ..text_processing import extract_numbers, has_negation_mismatch
+
+
+class NLIModel:
+ def __init__(self, model_name=None):
+ self.model_name = model_name or os.getenv("HALGORITHEM_NLI_MODEL", "cross-encoder/nli-deberta-v3-large")
+ self.kind = "deberta-nli"
+ self.fallback_reason = None
+ if self.model_name.lower() in {"rule", "local", "deterministic"}:
+ self.kind = "rule"
+ self.model_name = "rule"
+ self.tokenizer = None
+ self.model = None
+ return
+ try:
+ from transformers import AutoModelForSequenceClassification, AutoTokenizer
+
+ allow_download = os.getenv("HALGORITHEM_ALLOW_MODEL_DOWNLOAD", "").lower() in {"1", "true", "yes"}
+ self.tokenizer = AutoTokenizer.from_pretrained(self.model_name, local_files_only=not allow_download)
+ self.model = AutoModelForSequenceClassification.from_pretrained(self.model_name, local_files_only=not allow_download)
+ self.model.eval()
+ except Exception as exc:
+ warnings.warn(
+ f"Could not load NLI model {self.model_name!r} ({exc}); using deterministic NLI fallback.",
+ RuntimeWarning,
+ )
+ self.kind = "rule"
+ self.fallback_reason = str(exc)
+ self.tokenizer = None
+ self.model = None
+
+ def predict(self, premise, hypothesis):
+ if self.model is None:
+ return rule_nli(premise, hypothesis)
+ inputs = self.tokenizer(premise, hypothesis, return_tensors="pt", truncation=True, max_length=512)
+ with torch.no_grad():
+ logits = self.model(**inputs).logits[0]
+ probs = torch.softmax(logits, dim=-1)
+ labels = self.model.config.id2label
+ best_idx = int(torch.argmax(probs).item())
+ raw_label = labels.get(best_idx, str(best_idx)).upper()
+ confidence = float(probs[best_idx].item())
+ if "ENTAIL" in raw_label:
+ verdict = "ENTAIL"
+ elif "CONTRAD" in raw_label:
+ verdict = "CONTRADICT"
+ else:
+ verdict = "NEUTRAL"
+ return verdict, confidence
+
+ @property
+ def diagnostics(self):
+ return {"nli": self.kind, "nli_model": self.model_name if self.kind != "rule" else "rule", "nli_fallback_reason": self.fallback_reason}
+
+
+def rule_nli(premise, hypothesis):
+ chunk = {"text": premise, "numbers": extract_numbers(premise)}
+ contradiction = find_contradiction(
+ claim=hypothesis,
+ chunk=chunk,
+ extract_numbers=extract_numbers,
+ has_negation_mismatch=has_negation_mismatch,
+ score=1.0,
+ threshold=0.0,
+ )
+ if contradiction:
+ return "CONTRADICT", 0.86
+ overlap = overlap_ratio(hypothesis, premise)
+ if overlap >= 0.72:
+ return "ENTAIL", clamp(0.55 + overlap * 0.4)
+ if overlap >= 0.35:
+ return "NEUTRAL", clamp(0.50 + overlap * 0.25)
+ return "NEUTRAL", 0.62
+
+
+def sentence_nli(ai_sentence: ProcessedSentence, document: IngestedDocument, *, nli_model=None, top_k=5):
+ nli_model = nli_model or NLIModel()
+ hits = similarity_search(ai_sentence, document, top_k=top_k).hits
+ if not hits:
+ return NLICheck(verdict="NEUTRAL", confidence=0.0)
+ best_score = hits[0].score
+ relevant_hits = [
+ hit
+ for hit in hits
+ if hit.score >= 0.4 and hit.score >= best_score * 0.75
+ ] or [hits[0]]
+ premise = " ".join(hit.sentence for hit in relevant_hits)
+ normalized_premise, premise_unit_changes = normalize_units(premise)
+ normalized_hypothesis, hypothesis_unit_changes = normalize_units(ai_sentence.resolved_text)
+ unit_mismatch = unit_representation_mismatch(premise, ai_sentence.resolved_text)
+ verdict, confidence = nli_model.predict(normalized_premise, normalized_hypothesis)
+ unit_details = []
+ if unit_mismatch:
+ unit_details.append(unit_mismatch)
+ unit_details.extend({"source_change": change} for change in premise_unit_changes)
+ unit_details.extend({"response_change": change} for change in hypothesis_unit_changes)
+ return NLICheck(
+ verdict=verdict,
+ confidence=confidence,
+ evidence=hits[0].sentence,
+ evidence_index=hits[0].sentence_index,
+ unit_mismatch=bool(unit_mismatch),
+ unit_representation_change=bool(unit_mismatch),
+ unit_details=unit_details,
+ )
diff --git a/Halgorithem/checks/similarity.py b/Halgorithem/checks/similarity.py
new file mode 100644
index 0000000..8ec2d18
--- /dev/null
+++ b/Halgorithem/checks/similarity.py
@@ -0,0 +1,32 @@
+from .utils import clamp
+from ..model_runtime import default_embedder, default_reranker
+from ..models import IngestedDocument, ProcessedSentence, SimilarityCheck, SimilarityHit
+
+
+def similarity_search(ai_sentence: ProcessedSentence, document: IngestedDocument, *, embedder=None, reranker=None, top_k=5):
+ embedder = embedder or default_embedder()
+ reranker = reranker or default_reranker()
+ query = embedder.encode(ai_sentence.resolved_text)
+ hits = []
+ for doc_sentence in document.sentences:
+ score = clamp(embedder.similarity(query, doc_sentence.embedding))
+ hits.append(
+ SimilarityHit(
+ sentence_index=doc_sentence.index,
+ sentence=doc_sentence.text,
+ score=score,
+ source=doc_sentence.source,
+ source_quality=doc_sentence.source_quality,
+ )
+ )
+ hits.sort(key=lambda hit: hit.score, reverse=True)
+ shortlist = hits[:max(20, top_k)]
+ top_hits = reranker.rerank(ai_sentence.resolved_text, shortlist, text_fn=lambda hit: hit.sentence, top_k=top_k)
+ best = top_hits[0] if top_hits else None
+ return SimilarityCheck(
+ score=best.score if best else 0.0,
+ evidence=best.sentence if best else "",
+ source=best.source if best else "",
+ source_quality=best.source_quality if best else 0.65,
+ hits=top_hits,
+ )
diff --git a/Halgorithem/checks/units.py b/Halgorithem/checks/units.py
new file mode 100644
index 0000000..b0d373c
--- /dev/null
+++ b/Halgorithem/checks/units.py
@@ -0,0 +1,106 @@
+import re
+
+
+UNIT_ALIASES = {
+ "g": "gram",
+ "gram": "gram",
+ "grams": "gram",
+ "kg": "kilogram",
+ "kilogram": "kilogram",
+ "kilograms": "kilogram",
+ "m": "meter",
+ "meter": "meter",
+ "meters": "meter",
+ "km": "kilometer",
+ "kilometer": "kilometer",
+ "kilometers": "kilometer",
+ "mile": "mile",
+ "miles": "mile",
+ "c": "celsius",
+ "celsius": "celsius",
+ "f": "fahrenheit",
+ "fahrenheit": "fahrenheit",
+}
+
+NORMALIZATION = {
+ "gram": ("kilogram", 0.001, 0.0),
+ "kilogram": ("kilogram", 1.0, 0.0),
+ "meter": ("meter", 1.0, 0.0),
+ "kilometer": ("meter", 1000.0, 0.0),
+ "mile": ("meter", 1609.34, 0.0),
+}
+
+QUANTITY_RE = re.compile(r"\b(?P