# SpecificityAnnotation
#
# Structured metadata for RAG retrieval specificity scoring.
# Documents how specific/general a class is for different search templates.
#
# Generation date: 2026-01-07

id: https://nde.nl/ontology/hc/class/SpecificityAnnotation
name: SpecificityAnnotation
title: Specificity Annotation

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  prov: http://www.w3.org/ns/prov#
  skos: http://www.w3.org/2004/02/skos/core#

default_prefix: hc

imports:
  - linkml:types
  - ./TemplateSpecificityScores
  - ../slots/specificity_agent
  - ../slots/specificity_rationale
  - ../slots/specificity_score
  - ../slots/specificity_timestamp
  - ../slots/template_specificity

# Slot definitions are inlined here to avoid circular imports
# These slots are also available separately in ../slots/ for reuse

slots:
  specificity_score:
    slot_uri: hc:specificityScore
    description: |
      Specificity score for RAG retrieval filtering (0.0-1.0).
      LOWER scores = more broadly relevant; HIGHER scores = more specific.
    range: float
    minimum_value: 0.0
    maximum_value: 1.0
  
  specificity_rationale:
    slot_uri: skos:note
    description: |
      Explanation for the assigned specificity score.
    range: string
  
  specificity_timestamp:
    slot_uri: prov:generatedAtTime
    description: |
      ISO 8601 timestamp when the specificity annotation was created.
    range: datetime
  
  specificity_agent:
    slot_uri: prov:wasAttributedTo
    description: |
      Agent (human or AI) that created the specificity annotation.
    range: string
  
  template_specificity:
    slot_uri: hc:templateSpecificity
    description: |
      Per-template specificity scores for context-aware RAG filtering.
    range: TemplateSpecificityScores
    inlined: true

classes:
  SpecificityAnnotation:
    class_uri: hc:SpecificityAnnotation
    description: |
      Structured metadata for RAG retrieval specificity scoring.
      Documents how specific/general a class is for different search templates.
      
      **Scoring Semantics** (LOWER = more broadly relevant):
      - 0.00-0.20: Universal (HeritageCustodian, Location)
      - 0.20-0.40: Broadly useful (Collection, Identifier)
      - 0.40-0.60: Moderately specific (ChangeEvent, PersonProfile)
      - 0.60-0.80: Fairly specific (Archive, Museum, Library)
      - 0.80-1.00: Highly specific (LinkedInConnectionExtraction)
    slots:
      - specificity_score
      - specificity_rationale
      - specificity_timestamp
      - specificity_agent
      - template_specificity
    annotations:
      specificity_score: 0.2
      specificity_rationale: "Meta-class for specificity annotations"