rdf-construct 0.3.0__py3-none-any.whl

rdf_construct/merge/config.py

@@ -0,0 +1,354 @@
+"""Configuration dataclasses for the merge command.
+
+Defines configuration structures for:
+- Source files with priority ordering
+- Namespace remapping rules
+- Conflict resolution strategies
+- Data migration settings
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from pathlib import Path
+from typing import Any
+
+import yaml
+from rdflib import URIRef
+
+
+class ConflictStrategy(Enum):
+    """Strategy for resolving conflicting values."""
+
+    PRIORITY = auto()  # Higher priority source wins
+    FIRST = auto()  # First source encountered wins
+    LAST = auto()  # Last source encountered wins
+    MARK_ALL = auto()  # Mark all conflicts for manual resolution
+
+
+class ImportsStrategy(Enum):
+    """Strategy for handling owl:imports statements."""
+
+    PRESERVE = auto()  # Keep all imports from all sources
+    REMOVE = auto()  # Remove all imports
+    UPDATE = auto()  # Update imports to point to merged output
+    MERGE = auto()  # Merge and deduplicate imports
+
+
+@dataclass
+class SourceConfig:
+    """Configuration for a single source file.
+
+    Attributes:
+        path: Path to the source RDF file.
+        priority: Priority for conflict resolution (higher wins).
+        namespace_remap: Optional namespace remapping rules.
+    """
+
+    path: Path
+    priority: int = 1
+    namespace_remap: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | str) -> "SourceConfig":
+        """Create from dictionary or simple path string.
+
+        Args:
+            data: Either a path string or dict with path, priority, remap
+
+        Returns:
+            SourceConfig instance
+        """
+        if isinstance(data, str):
+            return cls(path=Path(data))
+
+        return cls(
+            path=Path(data["path"]),
+            priority=data.get("priority", 1),
+            namespace_remap=data.get("namespace_remap", {}),
+        )
+
+
+@dataclass
+class NamespaceConfig:
+    """Configuration for namespace handling.
+
+    Attributes:
+        base: Base namespace for the merged output.
+        remappings: Global namespace remapping rules.
+        preferred_prefixes: Preferred prefix bindings for output.
+    """
+
+    base: str | None = None
+    remappings: dict[str, str] = field(default_factory=dict)
+    preferred_prefixes: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class ConflictConfig:
+    """Configuration for conflict handling.
+
+    Attributes:
+        strategy: How to resolve conflicts.
+        report_path: Optional path to write conflict report.
+        ignore_predicates: Predicates to ignore in conflict detection.
+    """
+
+    strategy: ConflictStrategy = ConflictStrategy.PRIORITY
+    report_path: Path | None = None
+    ignore_predicates: set[str] = field(default_factory=set)
+
+
+@dataclass
+class MigrationRule:
+    """A single data migration rule.
+
+    Supports two types:
+    - rename: Simple URI substitution
+    - transform: SPARQL CONSTRUCT-style transformation
+
+    Attributes:
+        type: Either "rename" or "transform"
+        description: Human-readable description of the rule
+        from_uri: For rename: source URI to match
+        to_uri: For rename: target URI to replace with
+        match: For transform: SPARQL pattern to match
+        construct: For transform: list of patterns to construct
+        delete_matched: Whether to delete matched triples
+    """
+
+    type: str  # "rename" or "transform"
+    description: str = ""
+    # For rename type
+    from_uri: str | None = None
+    to_uri: str | None = None
+    # For transform type
+    match: str | None = None
+    construct: list[dict[str, str]] = field(default_factory=list)
+    delete_matched: bool = True
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MigrationRule":
+        """Create from dictionary.
+
+        Args:
+            data: Dictionary with rule configuration
+
+        Returns:
+            MigrationRule instance
+        """
+        return cls(
+            type=data.get("type", "rename"),
+            description=data.get("description", ""),
+            from_uri=data.get("from"),
+            to_uri=data.get("to"),
+            match=data.get("match"),
+            construct=data.get("construct", []),
+            delete_matched=data.get("delete_matched", True),
+        )
+
+
+@dataclass
+class DataMigrationConfig:
+    """Configuration for data graph migration.
+
+    Attributes:
+        data_sources: Paths to data files to migrate.
+        output_path: Path for migrated data output.
+        rules: List of migration rules to apply.
+        rules_file: Optional path to YAML file with rules.
+    """
+
+    data_sources: list[Path] = field(default_factory=list)
+    output_path: Path | None = None
+    rules: list[MigrationRule] = field(default_factory=list)
+    rules_file: Path | None = None
+
+
+@dataclass
+class OutputConfig:
+    """Configuration for output generation.
+
+    Attributes:
+        path: Output file path.
+        format: RDF serialization format.
+        preserve_prefixes: Whether to preserve source prefix bindings.
+    """
+
+    path: Path
+    format: str = "turtle"
+    preserve_prefixes: bool = True
+
+
+@dataclass
+class MergeConfig:
+    """Complete configuration for a merge operation.
+
+    Attributes:
+        sources: List of source file configurations.
+        output: Output configuration.
+        namespaces: Namespace handling configuration.
+        conflicts: Conflict resolution configuration.
+        imports: owl:imports handling strategy.
+        migrate_data: Optional data migration configuration.
+        dry_run: If True, report what would happen without writing.
+    """
+
+    sources: list[SourceConfig] = field(default_factory=list)
+    output: OutputConfig | None = None
+    namespaces: NamespaceConfig = field(default_factory=NamespaceConfig)
+    conflicts: ConflictConfig = field(default_factory=ConflictConfig)
+    imports: ImportsStrategy = ImportsStrategy.PRESERVE
+    migrate_data: DataMigrationConfig | None = None
+    dry_run: bool = False
+
+    @classmethod
+    def from_yaml(cls, path: Path) -> "MergeConfig":
+        """Load configuration from a YAML file.
+
+        Args:
+            path: Path to YAML configuration file
+
+        Returns:
+            MergeConfig instance
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+            ValueError: If config is invalid
+        """
+        if not path.exists():
+            raise FileNotFoundError(f"Config file not found: {path}")
+
+        with open(path) as f:
+            data = yaml.safe_load(f)
+
+        return cls.from_dict(data)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "MergeConfig":
+        """Create from dictionary.
+
+        Args:
+            data: Dictionary with configuration
+
+        Returns:
+            MergeConfig instance
+        """
+        # Parse sources
+        sources = []
+        for src in data.get("sources", []):
+            sources.append(SourceConfig.from_dict(src))
+
+        # Parse output
+        output = None
+        if "output" in data:
+            out_data = data["output"]
+            if isinstance(out_data, str):
+                output = OutputConfig(path=Path(out_data))
+            else:
+                output = OutputConfig(
+                    path=Path(out_data["path"]),
+                    format=out_data.get("format", "turtle"),
+                    preserve_prefixes=out_data.get("preserve_prefixes", True),
+                )
+
+        # Parse namespaces
+        ns_data = data.get("namespaces", {})
+        namespaces = NamespaceConfig(
+            base=ns_data.get("base"),
+            remappings=ns_data.get("remappings", {}),
+            preferred_prefixes=ns_data.get("preferred_prefixes", {}),
+        )
+
+        # Parse conflicts
+        conf_data = data.get("conflicts", {})
+        strategy_str = conf_data.get("strategy", "priority").upper()
+        conflicts = ConflictConfig(
+            strategy=ConflictStrategy[strategy_str],
+            report_path=Path(conf_data["report"]) if conf_data.get("report") else None,
+            ignore_predicates=set(conf_data.get("ignore_predicates", [])),
+        )
+
+        # Parse imports strategy
+        imports_str = data.get("imports", "preserve").upper()
+        imports = ImportsStrategy[imports_str]
+
+        # Parse data migration
+        migrate_data = None
+        if "migrate_data" in data:
+            mig_data = data["migrate_data"]
+            rules = [MigrationRule.from_dict(r) for r in mig_data.get("rules", [])]
+            migrate_data = DataMigrationConfig(
+                data_sources=[Path(p) for p in mig_data.get("sources", [])],
+                output_path=Path(mig_data["output"]) if mig_data.get("output") else None,
+                rules=rules,
+                rules_file=Path(mig_data["rules_file"]) if mig_data.get("rules_file") else None,
+            )
+
+        return cls(
+            sources=sources,
+            output=output,
+            namespaces=namespaces,
+            conflicts=conflicts,
+            imports=imports,
+            migrate_data=migrate_data,
+            dry_run=data.get("dry_run", False),
+        )
+
+
+def load_merge_config(path: Path) -> MergeConfig:
+    """Load merge configuration from a YAML file.
+
+    Args:
+        path: Path to configuration file
+
+    Returns:
+        MergeConfig instance
+    """
+    return MergeConfig.from_yaml(path)
+
+
+def create_default_config() -> str:
+    """Generate default merge configuration as YAML string.
+
+    Returns:
+        YAML configuration template
+    """
+    return '''# rdf-construct merge configuration
+# See MERGE_GUIDE.md for full documentation
+
+# Source files to merge (in order of priority, lowest to highest)
+sources:
+  - path: core.ttl
+    priority: 1
+  - path: extension.ttl
+    priority: 2
+
+# Output configuration
+output:
+  path: merged.ttl
+  format: turtle
+
+# Namespace handling
+namespaces:
+  # base: "http://example.org/merged#"
+  remappings: {}
+  preferred_prefixes: {}
+
+# Conflict resolution
+conflicts:
+  strategy: priority  # priority, first, last, or mark_all
+  # report: conflicts.md  # Optional conflict report
+
+# owl:imports handling
+imports: preserve  # preserve, remove, update, or merge
+
+# Optional data migration
+# migrate_data:
+#   sources:
+#     - split_instances.ttl
+#   output: migrated.ttl
+#   rules:
+#     - type: rename
+#       from: "http://old.example.org/ont#OldClass"
+#       to: "http://example.org/ont#NewClass"
+'''

rdf_construct/merge/conflicts.py

@@ -0,0 +1,281 @@
+"""Conflict detection and resolution for ontology merging.
+
+This module handles:
+- Detecting conflicting values for the same subject+predicate
+- Resolving conflicts based on configured strategy
+- Marking unresolved conflicts in output
+- Generating conflict reports
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Iterator
+
+from rdflib import Graph, URIRef, Literal, BNode
+from rdflib.namespace import RDF, RDFS, OWL
+from rdflib.term import Node
+
+
+class ConflictType(Enum):
+    """Classification of conflict types."""
+
+    VALUE_DIFFERENCE = auto()  # Same predicate, different literal values
+    TYPE_DIFFERENCE = auto()  # Different rdf:type declarations
+    HIERARCHY_DIFFERENCE = auto()  # Different subClassOf/subPropertyOf
+    SEMANTIC_CONTRADICTION = auto()  # Logically incompatible (e.g., disjoint + subclass)
+
+
+@dataclass
+class ConflictValue:
+    """A single value in a conflict.
+
+    Attributes:
+        value: The RDF value (Literal, URIRef, or BNode)
+        source_path: Path to the source file
+        priority: Priority of the source
+    """
+
+    value: Node
+    source_path: str
+    priority: int
+
+    def __str__(self) -> str:
+        """Return string representation of the value."""
+        if isinstance(self.value, Literal):
+            lang = f"@{self.value.language}" if self.value.language else ""
+            dtype = f"^^{self.value.datatype}" if self.value.datatype else ""
+            return f'"{self.value}"{lang}{dtype}'
+        return str(self.value)
+
+
+@dataclass
+class Conflict:
+    """Represents a conflict between source files.
+
+    Attributes:
+        subject: The subject URI where conflict occurs
+        predicate: The predicate where conflict occurs
+        values: List of conflicting values from different sources
+        conflict_type: Classification of the conflict
+        resolution: The resolved value, if any
+        is_resolved: Whether the conflict was automatically resolved
+    """
+
+    subject: URIRef | BNode
+    predicate: URIRef
+    values: list[ConflictValue]
+    conflict_type: ConflictType = ConflictType.VALUE_DIFFERENCE
+    resolution: ConflictValue | None = None
+    is_resolved: bool = False
+
+    @property
+    def requires_attention(self) -> bool:
+        """Check if this conflict requires manual attention."""
+        return not self.is_resolved
+
+    def resolve_by_priority(self) -> None:
+        """Resolve conflict by choosing highest priority value."""
+        if self.values:
+            sorted_vals = sorted(self.values, key=lambda v: v.priority, reverse=True)
+            self.resolution = sorted_vals[0]
+            self.is_resolved = True
+
+    def resolve_by_first(self) -> None:
+        """Resolve conflict by choosing first value."""
+        if self.values:
+            self.resolution = self.values[0]
+            self.is_resolved = True
+
+    def resolve_by_last(self) -> None:
+        """Resolve conflict by choosing last value."""
+        if self.values:
+            self.resolution = self.values[-1]
+            self.is_resolved = True
+
+
+@dataclass
+class SourceGraph:
+    """A loaded source graph with metadata.
+
+    Attributes:
+        graph: The RDF graph
+        path: Path to the source file
+        priority: Priority for conflict resolution
+        triple_count: Number of triples in the graph
+    """
+
+    graph: Graph
+    path: str
+    priority: int
+    triple_count: int = 0
+
+    def __post_init__(self):
+        """Calculate triple count."""
+        self.triple_count = len(self.graph)
+
+
+class ConflictDetector:
+    """Detects conflicts between multiple source graphs.
+
+    A conflict occurs when the same subject has different values for
+    the same predicate across different sources. This is particularly
+    important for functional properties or single-valued predicates.
+    """
+
+    # Predicates that typically should have single values
+    SINGLE_VALUE_PREDICATES: set[URIRef] = {
+        RDFS.label,
+        RDFS.comment,
+        RDFS.domain,
+        RDFS.range,
+        OWL.inverseOf,
+    }
+
+    def __init__(self, ignore_predicates: set[str] | None = None):
+        """Initialize the conflict detector.
+
+        Args:
+            ignore_predicates: Predicates to ignore in conflict detection
+        """
+        self.ignore_predicates: set[URIRef] = set()
+        if ignore_predicates:
+            self.ignore_predicates = {URIRef(p) for p in ignore_predicates}
+
+    def detect_conflicts(self, sources: list[SourceGraph]) -> list[Conflict]:
+        """Detect conflicts across multiple source graphs.
+
+        Args:
+            sources: List of source graphs to compare
+
+        Returns:
+            List of detected conflicts
+        """
+        conflicts: list[Conflict] = []
+
+        # Build index: subject -> predicate -> [(value, source, priority)]
+        index: dict[Node, dict[URIRef, list[ConflictValue]]] = {}
+
+        for source in sources:
+            for s, p, o in source.graph:
+                # Skip ignored predicates
+                if p in self.ignore_predicates:
+                    continue
+
+                # Skip blank node subjects for now (complex to handle)
+                if isinstance(s, BNode):
+                    continue
+
+                if s not in index:
+                    index[s] = {}
+                if p not in index[s]:
+                    index[s][p] = []
+
+                # Check if this exact value already exists
+                existing_values = [cv.value for cv in index[s][p]]
+                if o not in existing_values:
+                    index[s][p].append(
+                        ConflictValue(value=o, source_path=source.path, priority=source.priority)
+                    )
+
+        # Find predicates with multiple different values
+        for subject, predicates in index.items():
+            for predicate, values in predicates.items():
+                if len(values) > 1:
+                    conflict_type = self._classify_conflict(predicate)
+                    conflicts.append(
+                        Conflict(
+                            subject=subject,
+                            predicate=predicate,
+                            values=values,
+                            conflict_type=conflict_type,
+                        )
+                    )
+
+        return conflicts
+
+    def _classify_conflict(self, predicate: URIRef) -> ConflictType:
+        """Classify the type of conflict based on the predicate.
+
+        Args:
+            predicate: The conflicting predicate
+
+        Returns:
+            ConflictType classification
+        """
+        pred_str = str(predicate)
+
+        if predicate == RDF.type:
+            return ConflictType.TYPE_DIFFERENCE
+
+        if any(
+            x in pred_str for x in ["subClassOf", "subPropertyOf", "equivalentClass"]
+        ):
+            return ConflictType.HIERARCHY_DIFFERENCE
+
+        if "disjoint" in pred_str.lower():
+            return ConflictType.SEMANTIC_CONTRADICTION
+
+        return ConflictType.VALUE_DIFFERENCE
+
+
+def generate_conflict_marker(conflict: Conflict, graph: Graph) -> str:
+    """Generate a conflict marker comment for Turtle output.
+
+    Args:
+        conflict: The conflict to mark
+        graph: Graph for namespace resolution
+
+    Returns:
+        Multi-line comment string marking the conflict
+    """
+    lines = []
+
+    # Try to get a readable name for the subject
+    try:
+        subject_name = graph.namespace_manager.normalizeUri(conflict.subject)
+    except Exception:
+        subject_name = str(conflict.subject)
+
+    try:
+        pred_name = graph.namespace_manager.normalizeUri(conflict.predicate)
+    except Exception:
+        pred_name = str(conflict.predicate)
+
+    lines.append(f"# === CONFLICT: {subject_name} {pred_name} ===")
+
+    for cv in conflict.values:
+        lines.append(f"# Source: {cv.source_path} (priority {cv.priority}): {cv}")
+
+    if conflict.is_resolved and conflict.resolution:
+        lines.append(f"# Resolution: Used {conflict.resolution} (highest priority)")
+    else:
+        lines.append("# Resolution: UNRESOLVED - values differ, manual review required")
+        lines.append(
+            "# To resolve: keep one value below, delete the other and this comment block"
+        )
+
+    return "\n".join(lines)
+
+
+def generate_conflict_end_marker() -> str:
+    """Generate the end marker for a conflict block.
+
+    Returns:
+        End marker comment string
+    """
+    return "# === END CONFLICT ==="
+
+
+def filter_semantic_conflicts(conflicts: list[Conflict]) -> list[Conflict]:
+    """Filter to only semantic contradictions that require attention.
+
+    Semantic contradictions are logically incompatible assertions,
+    such as declaring two classes both disjoint and related by subclass.
+
+    Args:
+        conflicts: All detected conflicts
+
+    Returns:
+        Only conflicts classified as semantic contradictions
+    """
+    return [c for c in conflicts if c.conflict_type == ConflictType.SEMANTIC_CONTRADICTION]