ALwrity/docs-site/docs/features/ai/grounding-ui.md

# Grounding UI

ALwrity's Grounding UI feature provides AI-powered content verification and fact-checking capabilities, ensuring your content is accurate, reliable, and trustworthy. This advanced feature helps maintain content credibility by grounding AI-generated content in verified information sources.

## Visuals

<p align="center">
  <img src="../../assests/assistive-2.png" alt="Inline fact checking with citations and claim statuses" width="60%">
</p>

## What is Grounding UI?

Grounding UI is an intelligent content verification system that connects AI-generated content with real-world data sources, ensuring accuracy and reliability. It provides visual indicators, source citations, and verification status to help you create trustworthy, fact-checked content.

## Implementation Overview (Concise)

- Backend service: `backend/services/hallucination_detector.py` (claim extraction → evidence search → verification)
- Models: `backend/models/hallucination_models.py`
- API router: `backend/api/hallucination_detector.py` (registered in `backend/app.py`)
- Frontend service: `frontend/src/services/hallucinationDetectorService.ts`
- UI: LinkedIn Writer selection menu + FactCheckResults modal

### API Endpoints (Summary)
- `POST /api/hallucination-detector/detect` – main fact-checking
- `POST /api/hallucination-detector/extract-claims` – claims only
- `POST /api/hallucination-detector/verify-claim` – single claim
- `GET  /api/hallucination-detector/health` – health check

### Minimal Setup
- Backend env:
  - `EXA_API_KEY=...` (evidence search)
  - `OPENAI_API_KEY=...` (claim extraction + verification)
- Frontend env:
  - `REACT_APP_API_URL=http://localhost:8000`

### Quick Usage (UI)
1) In LinkedIn Writer, select a passage (10+ chars)  
2) Click “Check Facts” in the selection menu  
3) Review claims, assessments (supported/refuted/insufficient), confidence, and sources in the results modal

### Quick Usage (API)

```bash
curl -X POST "$API_URL/api/hallucination-detector/detect" \
  -H "Content-Type: application/json" \
  -d '{"text":"The Eiffel Tower is in Paris and built in 1889.","include_sources":true,"max_claims":5}'
```

### Key Benefits

- **Content Verification**: Verify facts and claims in real-time
- **Source Attribution**: Provide proper source citations
- **Credibility Enhancement**: Build trust with accurate content
- **Risk Mitigation**: Reduce misinformation and false claims
- **Quality Assurance**: Ensure content meets high standards

## Core Features

### Real-Time Fact Checking

#### Information Verification
- **Fact Validation**: Verify factual claims against reliable sources
- **Data Accuracy**: Check statistics and numerical data
- **Source Reliability**: Assess source credibility and authority
- **Claim Verification**: Validate specific claims and statements
- **Trend Analysis**: Verify current trends and developments

#### Source Integration
- **Multiple Sources**: Cross-reference information from multiple sources
- **Source Diversity**: Include various types of sources
- **Authority Assessment**: Evaluate source authority and expertise
- **Recency Check**: Ensure information is current and up-to-date
- **Bias Detection**: Identify potential bias in sources

### Visual Grounding Indicators

#### Verification Status
- **Verified**: Green indicators for verified information
- **Unverified**: Yellow indicators for unverified claims
- **Disputed**: Red indicators for disputed information
- **Outdated**: Orange indicators for outdated information
- **Source Missing**: Gray indicators for missing sources

#### Source Citations
- **Inline Citations**: Source links within content
- **Reference Lists**: Comprehensive reference sections
- **Source Types**: Different icons for different source types
- **Credibility Scores**: Visual credibility indicators
- **Last Updated**: Timestamp of last verification

### Content Enhancement

#### Accuracy Improvement
- **Fact Correction**: Suggest corrections for inaccurate information
- **Source Addition**: Recommend additional sources
- **Clarification**: Suggest clarifications for ambiguous content
- **Update Recommendations**: Suggest updates for outdated information
- **Bias Reduction**: Identify and suggest bias reduction

#### Trust Building
- **Transparency**: Show verification process and sources
- **Credibility Indicators**: Display content credibility scores
- **Expert Validation**: Highlight expert-reviewed content
- **Peer Review**: Show peer review status
- **Quality Metrics**: Display content quality indicators

## Integration with Research

### Web Research Integration

#### Real-Time Research
- **Live Data**: Access current information from web sources
- **Trend Monitoring**: Track real-time trends and developments
- **News Integration**: Include latest news and updates
- **Market Data**: Access current market information
- **Social Media**: Monitor social media discussions

#### Source Verification
- **Domain Authority**: Check website authority and credibility
- **Content Freshness**: Verify content recency
- **Author Credibility**: Assess author expertise and credentials
- **Publication Standards**: Evaluate publication quality
- **Fact-Checking Organizations**: Cross-reference with fact-checkers

### Database Integration

#### Knowledge Base
- **Internal Database**: Access internal knowledge base
- **Historical Data**: Reference historical information
- **Expert Knowledge**: Include expert-curated information
- **Industry Standards**: Reference industry best practices
- **Regulatory Information**: Include regulatory and compliance data

#### External Databases
- **Academic Sources**: Access academic and research databases
- **Government Data**: Include government and official sources
- **Industry Reports**: Reference industry research and reports
- **Statistical Databases**: Access statistical and data sources
- **News Archives**: Search historical news and information

## User Interface Features

### Visual Indicators

#### Status Icons
- **Checkmark**: Verified and accurate information
- **Warning**: Unverified or potentially inaccurate
- **Exclamation**: Disputed or controversial information
- **Clock**: Outdated or time-sensitive information
- **Question**: Missing or unclear information

#### Color Coding
- **Green**: Verified and reliable information
- **Yellow**: Requires verification or attention
- **Red**: Disputed or inaccurate information
- **Blue**: Source information and citations
- **Gray**: Neutral or informational content

### Interactive Elements

#### Hover Information
- **Source Details**: Show source information on hover
- **Verification Status**: Display verification details
- **Last Updated**: Show last verification timestamp
- **Credibility Score**: Display source credibility rating
- **Related Sources**: Show related source information

#### Click Actions
- **Source Links**: Direct links to source materials
- **Verification Details**: Detailed verification information
- **Source Analysis**: In-depth source analysis
- **Fact-Checking Reports**: Access to fact-checking reports
- **Update Requests**: Request content updates

## Content Types and Applications

### Blog Content

#### Fact-Checking
- **Statistical Claims**: Verify statistics and data
- **Historical Facts**: Check historical information
- **Expert Quotes**: Verify expert statements
- **Research Findings**: Validate research claims
- **Trend Analysis**: Verify trend information

#### Source Attribution
- **Research Citations**: Proper research citations
- **Expert References**: Expert opinion attribution
- **Data Sources**: Statistical data attribution
- **News References**: News and media citations
- **Industry Sources**: Industry-specific references

### Social Media Content

#### Quick Verification
- **Fact Checking**: Rapid fact verification
- **Source Links**: Quick access to sources
- **Credibility Indicators**: Visual credibility markers
- **Update Alerts**: Notifications for outdated information
- **Bias Warnings**: Bias detection and warnings

#### Engagement Enhancement
- **Trust Building**: Build audience trust
- **Transparency**: Show verification process
- **Credibility**: Enhance content credibility
- **Authority**: Establish thought leadership
- **Reliability**: Demonstrate content reliability

### Professional Content

#### Business Communications
- **Market Data**: Verify market information
- **Financial Data**: Check financial statistics
- **Regulatory Information**: Verify compliance data
- **Industry Standards**: Reference industry standards
- **Best Practices**: Validate best practice claims

#### Research and Analysis
- **Data Validation**: Verify research data
- **Methodology Review**: Check research methods
- **Source Evaluation**: Assess source quality
- **Bias Assessment**: Identify potential bias
- **Quality Assurance**: Ensure research quality

## Best Practices

### Content Creation

#### Verification Process
1. **Enable Grounding**: Activate grounding features
2. **Review Indicators**: Check verification status
3. **Verify Claims**: Ensure all claims are verified
4. **Add Sources**: Include proper source citations
5. **Update Regularly**: Keep information current

#### Quality Standards
1. **Source Diversity**: Use multiple source types
2. **Authority Sources**: Prioritize authoritative sources
3. **Current Information**: Ensure information is current
4. **Bias Awareness**: Be aware of potential bias
5. **Transparency**: Show verification process

### Source Management

#### Source Selection
- **Authority**: Choose authoritative sources
- **Recency**: Prefer recent information
- **Relevance**: Ensure source relevance
- **Diversity**: Include diverse perspectives
- **Credibility**: Verify source credibility

#### Citation Standards
- **Proper Attribution**: Give proper credit
- **Link Accessibility**: Ensure links work
- **Source Description**: Describe source context
- **Date Information**: Include publication dates
- **Author Information**: Include author details

## Advanced Features

### Customization Options

#### Verification Settings
- **Source Preferences**: Set preferred source types
- **Credibility Thresholds**: Define credibility standards
- **Update Frequency**: Set verification update frequency
- **Bias Sensitivity**: Adjust bias detection sensitivity
- **Quality Standards**: Set quality requirements

#### Display Options
- **Indicator Style**: Customize visual indicators
- **Color Schemes**: Choose color coding schemes
- **Information Density**: Adjust information display
- **Hover Details**: Customize hover information
- **Click Actions**: Set click action preferences

### Integration Features

#### API Integration
- **External APIs**: Connect to external data sources
- **Custom Databases**: Integrate custom databases
- **Real-Time Data**: Access real-time information
- **Automated Updates**: Enable automatic updates
- **Custom Sources**: Add custom source types

#### Workflow Integration
- **Content Review**: Integrate with content review process
- **Quality Gates**: Set quality checkpoints
- **Approval Workflow**: Include in approval process
- **Publishing Pipeline**: Integrate with publishing workflow
- **Performance Tracking**: Track verification performance

## Troubleshooting

### Common Issues

#### Verification Problems
- **Source Unavailable**: Handle unavailable sources
- **Outdated Information**: Manage outdated content
- **Bias Detection**: Address bias concerns
- **Credibility Issues**: Resolve credibility problems
- **Update Delays**: Manage update delays

#### Technical Issues
- **API Connectivity**: Resolve API connection issues
- **Data Synchronization**: Fix data sync problems
- **Performance Issues**: Address performance concerns
- **Display Problems**: Fix visual indicator issues
- **Integration Errors**: Resolve integration problems

### Environment & Health
- “EXA_API_KEY not found” → add key to backend `.env`, restart server  
- “OpenAI API key not found” → add `OPENAI_API_KEY`, verify credits  
- Health check: `GET /api/hallucination-detector/health`

### Getting Help

#### Support Resources
- **Documentation**: Review feature documentation
- **Tutorials**: Watch grounding UI tutorials
- **Best Practices**: Follow best practice guides
- **Community**: Join user community discussions
- **Support**: Contact technical support

#### Optimization Tips
- **Settings Review**: Regularly review settings
- **Source Management**: Maintain source quality
- **Update Monitoring**: Monitor update status
- **Performance Tracking**: Track verification performance
- **Continuous Improvement**: Continuously improve process

---

*Ready to enhance your content credibility with grounding UI? [Start with our First Steps Guide](../../getting-started/first-steps.md) and [Explore Blog Writer Features](../blog-writer/overview.md) to begin creating verified, trustworthy content!*