semantica/docs/reference/kg_qa.md

KG QA

Knowledge Graph Quality Assurance system for validation, metrics, and automated repair.

---

🎯 Overview

• :material-check-decagram:{ .lg .middle } Quality Metrics

  ---

  Calculate Completeness, Consistency, and Accuracy scores

• :material-shield-check:{ .lg .middle } Validation Engine

  ---

  Validate against schema constraints and custom rules

• :material-wrench:{ .lg .middle } Automated Fixes

  ---

  Auto-repair duplicates, missing fields, and inconsistencies

• :material-file-document-edit:{ .lg .middle } Reporting

  ---

  Generate detailed quality reports (JSON, HTML, YAML)

• :material-relation-many-to-many:{ .lg .middle } Consistency

  ---

  Check logical, temporal, and hierarchical consistency

• :material-lightbulb:{ .lg .middle } Suggestions

  ---

  Get actionable improvement suggestions

!!! tip "When to Use" - Pre-Deployment: Validate graph quality before production use - Monitoring: Continuous quality monitoring of live graphs - Debugging: Identify and fix issues in problematic graphs

---

⚙️ Algorithms Used

Quality Metrics

• Weighted Averaging: Score = w1*Completeness + w2*Consistency
• Normalization: Min-max scaling of scores to 0.0 - 1.0
• Completeness Ratio: PresentProperties / RequiredProperties

Consistency Checking

• Logical Consistency: Contradiction detection (e.g., A > B and B > A)
• Temporal Consistency: Time range validation (Start < End)
• Hierarchical Consistency: Cycle detection in taxonomy (DFS)
• Domain/Range: Type compatibility checking for relationships

Automated Fixes

• Duplicate Merging: Using Deduplication module strategies
• Conflict Resolution: Using Conflicts module strategies
• Default Injection: Filling missing required fields with defaults
• Inference: Inferring missing types or links based on topology

---

Main Classes

KGQualityAssessor

Coordinator for overall quality assessment.

Methods:

Method	Description
assess_quality(kg)	Calculate all metrics
generate_report(kg)	Create full report

Example:

from semantica.kg_qa import KGQualityAssessor

assessor = KGQualityAssessor()
score = assessor.assess_overall_quality(kg)
print(f"Graph Quality Score: {score}")

ConsistencyChecker

Validates graph consistency.

Methods:

Method	Description	Algorithm
check_logical(kg)	Logical rules	Rule Engine
check_temporal(kg)	Time validity	Range Check
check_hierarchical(kg)	Cycles/Tree	DFS

CompletenessValidator

Checks for missing data.

Methods:

Method	Description
validate_entities(kg)	Check entity fields
validate_schema(kg)	Check schema compliance

AutomatedFixer

Applies automatic repairs.

Methods:

Method	Description
fix_issues(kg, issues)	Fix reported issues
merge_duplicates(kg)	Fix duplicates
resolve_conflicts(kg)	Fix conflicts

---

Convenience Functions

from semantica.kg_qa import assess_quality, generate_quality_report, fix_issues

# 1. Assess
score = assess_quality(kg)

# 2. Report
report = generate_quality_report(kg, schema=my_schema)

# 3. Fix
fixed_kg = fix_issues(kg, report.issues)

---

Configuration

Environment Variables

export KG_QA_MIN_SCORE=0.7
export KG_QA_STRICT_MODE=true

YAML Configuration

kg_qa:
  thresholds:
    overall: 0.7
    completeness: 0.8
    consistency: 0.9
    
  weights:
    completeness: 0.6
    consistency: 0.4
    
  auto_fix:
    enabled: true
    strategies:
      duplicates: merge
      missing_fields: default

---

Integration Examples

CI/CD Pipeline

from semantica.kg_qa import assess_quality

def validate_graph_deployment(kg):
    score = assess_quality(kg)
    
    if score < 0.8:
        raise ValueError(f"Quality score {score} too low for deployment!")
        
    print("Graph passed quality checks.")

---

Best Practices

1. Define Schema: QA is most effective when validated against a strict schema (Ontology).
2. Run Regularly: Graph quality degrades over time; run QA jobs periodically.
3. Review Fixes: Automated fixes are powerful but verify them for critical data.
4. Handle Warnings: Don't ignore warnings; they often indicate creeping data quality issues.

---

See Also

• Ontology Module - Defining schemas for validation
• Deduplication Module - Used for fixing duplicates
• Conflicts Module - Used for resolving inconsistencies