Add LinkML validator documentation for hallucination guardrails

[dragon-ai-agent]

Summary

This PR extends the hallucination guardrails documentation to include information about two new LinkML validation plugins, as requested in issue #51:

• linkml-term-validator: For validating ontology terms
• linkml-reference-validator: For validating text excerpts against source publications

Changes Made

The documentation now includes:

1. Two Key Validation Strategies section that explains:

   • The dual validation approach (ID + label) for ontology terms
   • The deterministic matching approach for text excerpts
   • Key principles and implementation considerations for each

2. Implementation Tools section that:

   • Links to the two LinkML validator plugins
   • Provides brief descriptions of what each tool does
   • Includes a link to the OBO file validation guide

Approach

Following @cmungall's preference, the documentation focuses on concepts rather than implementation details:

• Explains what validation strategies exist and why they work
• Describes the principles behind each approach
• Links to the actual implementations at the end for users who want to use these tools

The existing content about ID/label validation flows naturally into the new material, making it a cohesive guide.

Closes #51

🤖 Generated with Claude Code

[claude]

Claude finished @dragon-ai-agent's task —— View job

---

PR Review: LinkML Validator Documentation

Todo List

• Read the modified documentation file
• Analyze content quality and documentation standards compliance
• Check for consistency with existing content
• Provide comprehensive review feedback

Review Summary

This PR adds valuable documentation about LinkML validation tools for preventing hallucinations. The content is well-written and follows the repository's focus on practical, actionable guidance. Here's my detailed feedback:

✅ Strengths

1. Excellent Integration: The new sections (lines 92-206) flow naturally from the existing content, building on the ID+label validation concept already established.

2. Conceptual Focus: Following the repository's guidelines, the documentation properly emphasizes what and why over implementation details, which aligns with @cmungall's stated preferences.

3. Practical Structure: The two validation strategies are clearly differentiated:

   • Ontology term validation (dual validation approach)
   • Text excerpt validation (deterministic matching)

4. Comprehensive Coverage: Addresses key implementation considerations like caching, performance, error handling, and API integration.

🔍 Areas for Improvement

Content & Accuracy

• Line 104: "statistically unlikely" could be more precise - perhaps "computationally difficult" or "extremely unlikely"
• Lines 123-128: The deterministic matching section could benefit from a concrete example showing bracketed clarifications or ellipsis handling
• Lines 198-206: Consider adding version information or installation commands for the LinkML plugins

Documentation Standards

• Consistency: The new sections maintain good consistency with existing writing style and terminology
• Link Validation: All external links should be verified (OLS, OAK, LinkML plugin URLs)
• Cross-references: Consider adding internal links to the "Useful APIs" section from the validation strategy descriptions

Technical Considerations

• No Security Issues: This is documentation-only with no executable code
• No Performance Impact: Changes are purely additive to documentation
• No Breaking Changes: Extends existing content without modifying core concepts

📝 Minor Suggestions

1. Line 133: "EBI's comprehensive API" - could expand to "European Bioinformatics Institute's (EBI)"
2. Line 196: Consider adding a brief transition sentence before the "Implementation Tools" section
3. Lines 200-201: The parenthetical description could be more concise

🎯 Overall Assessment

Verdict: Approve with minor suggestions

This PR successfully addresses issue #51 by:

• Adding comprehensive coverage of LinkML validation tools
• Maintaining conceptual focus over implementation details
• Providing practical guidance for curation workflows
• Following repository documentation standards

The content quality is high, the integration is seamless, and it adds genuine value for the target audience of curators and maintainers.

🔗 References

• Changed Files: docs/how-tos/make-ids-hallucination-resistant.md:92-206
• Issue: Closes Add docs on new linkml validator AI guardrails #51 ✓

---

[cmungall]

dupe of #53