ski-kg-validator 3.0.3__py3-none-any.whl

kg_validator/__init__.py

@@ -0,0 +1,45 @@
+"""kg-validator — schema and §3.6 cross-cutting validation for v3 KGs."""
+
+from .loader import KnowledgeGraphV3, load_v3_kg
+from .models import (
+    Citation,
+    Definition,
+    Edge,
+    EdgeType,
+    Exemption,
+    Jurisdiction,
+    Obligation,
+    ObligationType,
+    Precedent,
+    RiskTier,
+    Rule,
+    Subject,
+    V3IssueType,
+    V3ValidationIssue,
+    V3ValidationResult,
+)
+from .validator import V3Validator
+
+__version__ = "3.0.3"
+__author__ = "KpiFinity"
+
+__all__ = [
+    "Citation",
+    "Definition",
+    "Edge",
+    "EdgeType",
+    "Exemption",
+    "Jurisdiction",
+    "KnowledgeGraphV3",
+    "Obligation",
+    "ObligationType",
+    "Precedent",
+    "RiskTier",
+    "Rule",
+    "Subject",
+    "V3IssueType",
+    "V3ValidationIssue",
+    "V3ValidationResult",
+    "V3Validator",
+    "load_v3_kg",
+]

kg_validator/cli.py

@@ -0,0 +1,111 @@
+"""Command-line interface for kg-validator (v3-only).
+
+The validator now accepts a single subcommand — ``validate`` — which
+loads a v3 KG JSON file and runs the spec §3.6 validation passes.
+
+The v2 ``review``, ``detect-conflicts``, ``detect-duplicates``, and
+HTML ``report`` subcommands were retired with PR 10e: they targeted
+the flat-rule list shape that is no longer the framework's currency.
+v3 conflict/duplicate detection happens at the typed-obligation level
+inside :mod:`kg_validator.validator` and surfaces as issues in the
+:class:`V3ValidationResult`.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+import click
+from pydantic import ValidationError
+
+from . import __version__
+from .loader import load_v3_kg
+from .validator import V3Validator
+
+
+@click.group()
+def main() -> None:
+    """Validate v3 KG files against SKI Framework spec v3.0 §3."""
+
+
+@main.command()
+@click.option("--input", "-i", required=True, help="Input v3 KG JSON file.")
+@click.option(
+    "--output",
+    "-o",
+    default=None,
+    help="Output JSON file with validation results. If omitted, results are printed to stdout when issues are found.",
+)
+def validate(input: str, output: Optional[str]) -> None:
+    """Validate a v3 KG against spec §3 schema and §3.6 cross-cutting passes."""
+    try:
+        click.echo(f"Loading v3 KG from: {input}")
+        kg = load_v3_kg(input)
+    except FileNotFoundError as e:
+        click.echo(f"Error: {e!s}", err=True)
+        raise SystemExit(1) from e
+    except ValidationError as e:
+        click.echo("Schema validation failed:", err=True)
+        click.echo(str(e), err=True)
+        raise SystemExit(2) from e
+
+    click.echo(
+        f"Loaded {len(kg.nodes.rules)} rules, {len(kg.nodes.obligations)} obligations, {len(kg.edges)} edges"
+    )
+
+    result = V3Validator(kg).run()
+
+    click.echo("\nValidation complete:")
+    click.echo(f"  Nodes: {result.total_nodes}")
+    click.echo(f"  Edges: {result.total_edges}")
+    click.echo(f"  Issues: {result.total_issues}")
+    if result.total_issues:
+        click.echo("\nIssues by type:")
+        by_type: dict[str, int] = {}
+        for issue in result.issues:
+            key = str(issue.issue_type)
+            by_type[key] = by_type.get(key, 0) + 1
+        for key in sorted(by_type):
+            click.echo(f"  {key}: {by_type[key]}")
+
+    payload = result.model_dump(mode="json")
+    if output:
+        with open(output, "w", encoding="utf-8") as fh:
+            json.dump(payload, fh, indent=2)
+        click.echo(f"\nResults saved to: {output}")
+    elif result.total_issues:
+        click.echo("\n" + json.dumps(payload, indent=2))
+
+    # Exit non-zero on any CRITICAL or HIGH issue so CI flows can gate on it.
+    if not result.is_clean:
+        raise SystemExit(3)
+
+
+@main.command()
+def examples() -> None:
+    """Show usage examples."""
+    examples_text = """
+kg-validator examples (v3):
+
+1. Validate a v3 KG file:
+   kg-validator validate --input kg-energy-v3.json
+
+2. Validate and save the issue report:
+   kg-validator validate --input kg-energy-v3.json --output report.json
+
+3. Compile-extract-validate flow:
+   kg-extractor extract --file regulation.txt --output kg-extracted.json --jurisdiction us.federal
+   kg-validator validate --input kg-extracted.json --output validation-report.json
+"""
+    click.echo(examples_text)
+
+
+@main.command()
+def version() -> None:
+    """Show version."""
+    click.echo(f"kg-validator {__version__}")
+
+
+if __name__ == "__main__":
+    main()

kg_validator/loader.py

@@ -0,0 +1,117 @@
+"""Loader for v3 KG JSON files.
+
+The on-disk v3 KG format is:
+
+    {
+      "metadata": {"name": "...", "schema_version": "3.0", ...},
+      "nodes": {
+        "subjects": [...], "rules": [...], "obligations": [...],
+        "definitions": [...], "exemptions": [...], "precedents": [...],
+        "jurisdictions": [...], "citations": [...]
+      },
+      "edges": [
+        {"type": "applies_to", "from": "...", "to": "..."},
+        ...
+      ]
+    }
+
+Each node array contains objects matching the corresponding Pydantic
+model in :mod:`.models`. Edges use ``from`` / ``to`` keys; the
+:class:`Edge` model declares aliases so the keys can be used directly.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .models import (
+    Citation,
+    Definition,
+    Edge,
+    Exemption,
+    Jurisdiction,
+    Obligation,
+    Precedent,
+    Rule,
+    Subject,
+)
+
+
+class KGV3Metadata(BaseModel):
+    """KG-level metadata (informative; not used in validation passes)."""
+
+    name: str
+    schema_version: str = "3.0"
+    sector: Optional[str] = None
+    description: Optional[str] = None
+    compiled_at: Optional[str] = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class KGV3Nodes(BaseModel):
+    """Container for all node arrays. All keys default to empty lists."""
+
+    subjects: List[Subject] = Field(default_factory=list)
+    rules: List[Rule] = Field(default_factory=list)
+    obligations: List[Obligation] = Field(default_factory=list)
+    definitions: List[Definition] = Field(default_factory=list)
+    exemptions: List[Exemption] = Field(default_factory=list)
+    precedents: List[Precedent] = Field(default_factory=list)
+    jurisdictions: List[Jurisdiction] = Field(default_factory=list)
+    citations: List[Citation] = Field(default_factory=list)
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class KnowledgeGraphV3(BaseModel):
+    """Top-level v3 KG container."""
+
+    metadata: KGV3Metadata
+    nodes: KGV3Nodes = Field(default_factory=KGV3Nodes)
+    edges: List[Edge] = Field(default_factory=list)
+
+    model_config = ConfigDict(extra="forbid")
+
+    def all_node_ids(self) -> Dict[str, str]:
+        """Map every node id to its type name. Useful for edge validation."""
+        out: Dict[str, str] = {}
+        for n in self.nodes.subjects:
+            out[n.id] = "Subject"
+        for n in self.nodes.rules:
+            out[n.id] = "Rule"
+        for n in self.nodes.obligations:
+            out[n.id] = "Obligation"
+        for n in self.nodes.definitions:
+            out[n.id] = "Definition"
+        for n in self.nodes.exemptions:
+            out[n.id] = "Exemption"
+        for n in self.nodes.precedents:
+            out[n.id] = "Precedent"
+        for n in self.nodes.jurisdictions:
+            out[n.id] = "Jurisdiction"
+        for n in self.nodes.citations:
+            out[n.id] = "Citation"
+        return out
+
+
+def load_v3_kg(path: str) -> KnowledgeGraphV3:
+    """Load and validate the Pydantic shape of a v3 KG JSON file.
+
+    Raises :class:`pydantic.ValidationError` if the file does not
+    conform to the schema. Returns the parsed :class:`KnowledgeGraphV3`
+    on success.
+
+    Schema-level validity is necessary but not sufficient. Run
+    :class:`kg_validator.V3Validator` against the loaded KG to
+    surface the cross-cutting issues from spec §3.6.
+    """
+    text = Path(path).read_text(encoding="utf-8")
+    raw: Any = json.loads(text)
+    if not isinstance(raw, dict):
+        raise ValueError(f"Top-level JSON in {path} must be an object, got {type(raw).__name__}")
+    return KnowledgeGraphV3.model_validate(raw)

kg_validator/models.py

@@ -0,0 +1,247 @@
+"""Pydantic v2 models for the v3 KG schema.
+
+Mirrors SKI Framework specification v3.0 §3:
+
+* §3.1 Node types: Subject, Rule, Obligation, Definition, Exemption,
+  Precedent, Jurisdiction, Citation.
+* §3.2 Edge types: applies_to, consists_of, defined_by, exempted_by,
+  amended_by, interpreted_by, scoped_to, cited_by.
+* §3.3 Typed obligations: the closed enumeration.
+* §3.4 Jurisdictional scope and effective-date intervals.
+
+These models are the source of truth for kg-validator's schema parsing.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, List, Literal, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ---------------------------------------------------------------------------
+# Enumerations
+# ---------------------------------------------------------------------------
+
+
+class ObligationType(str, Enum):
+    """Spec v3.0 §3.3 — typed obligations (closed enumeration)."""
+
+    MUST = "must"
+    MUST_NOT = "must_not"
+    MUST_NOT_EXCEED = "must_not_exceed"
+    MUST_BE_AT_LEAST = "must_be_at_least"
+    MUST_BE_BELOW = "must_be_below"
+    MUST_BE_ABOVE = "must_be_above"
+    MUST_BE_WITHIN = "must_be_within"
+    MUST_BE_ONE_OF = "must_be_one_of"
+    MUST_NOT_BE_ONE_OF = "must_not_be_one_of"
+    MUST_BE_RECORDED_WITHIN = "must_be_recorded_within"
+    SHOULD = "should"
+    DISCRETIONARY = "discretionary"
+
+
+class RiskTier(str, Enum):
+    """Spec v3.0 §5.4 — risk tier governor."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class EdgeType(str, Enum):
+    """Spec v3.0 §3.2 — edge types."""
+
+    APPLIES_TO = "applies_to"
+    CONSISTS_OF = "consists_of"
+    DEFINED_BY = "defined_by"
+    EXEMPTED_BY = "exempted_by"
+    AMENDED_BY = "amended_by"
+    INTERPRETED_BY = "interpreted_by"
+    SCOPED_TO = "scoped_to"
+    CITED_BY = "cited_by"
+
+
+# ---------------------------------------------------------------------------
+# Node base
+# ---------------------------------------------------------------------------
+
+
+class _NodeBase(BaseModel):
+    """Common fields every node carries (spec §3.1)."""
+
+    id: str = Field(..., description="Stable globally-unique identifier")
+    version: str = Field(
+        ...,
+        description=(
+            "Content-addressed SHA-256 of the canonical serialization of this "
+            "node's content excluding the version field itself."
+        ),
+    )
+
+    model_config = ConfigDict(use_enum_values=True, extra="forbid")
+
+
+# ---------------------------------------------------------------------------
+# Node types
+# ---------------------------------------------------------------------------
+
+
+class Subject(_NodeBase):
+    """A telemetry subject a rule can apply to."""
+
+    type: Literal["Subject"] = "Subject"
+    name: str = Field(..., description="Human-readable label")
+    description: Optional[str] = None
+
+
+class Rule(_NodeBase):
+    """A regulatory requirement composed of one or more obligations.
+
+    Carries the ``risk_tier`` field consumed by the risk-tier governor
+    (spec §5.4).
+    """
+
+    type: Literal["Rule"] = "Rule"
+    name: str
+    risk_tier: RiskTier = RiskTier.MEDIUM
+    description: Optional[str] = None
+
+
+class Obligation(_NodeBase):
+    """A typed normative statement (spec §3.3).
+
+    The operand (``value``) is loosely typed because different
+    obligation types carry different operand shapes: a numeric value
+    for bound-style relations, a list for set membership, a
+    duration-in-seconds for temporal predicates.
+    """
+
+    type: Literal["Obligation"] = "Obligation"
+    obligation_type: ObligationType
+    metric: str = Field(
+        ...,
+        description="Dotted-path identifier into the telemetry record's measurement object",
+    )
+    value: Union[float, int, str, List[Any], None] = None
+    unit: Optional[str] = None
+    effective_date_start: datetime = Field(
+        ...,
+        description="RFC 3339 timestamp; required per spec §3.4.",
+    )
+    effective_date_end: Optional[datetime] = None
+    summary: Optional[str] = None
+
+
+class Definition(_NodeBase):
+    """A regulatory term and its scope-restricted meaning."""
+
+    type: Literal["Definition"] = "Definition"
+    term: str
+    definition_text: str
+    scope: Optional[str] = Field(
+        default=None,
+        description="The scope within which this definition applies (e.g., a regulation section).",
+    )
+
+
+class Exemption(_NodeBase):
+    """A condition under which an obligation does not apply."""
+
+    type: Literal["Exemption"] = "Exemption"
+    condition: str
+    description: Optional[str] = None
+
+
+class Precedent(_NodeBase):
+    """A prior obligation that the present one amends, supersedes, or interprets."""
+
+    type: Literal["Precedent"] = "Precedent"
+    summary: str
+    relation: Literal["amends", "supersedes", "interprets"]
+
+
+class Jurisdiction(_NodeBase):
+    """A scope identifier (country, state, regulatory body, internal policy)."""
+
+    type: Literal["Jurisdiction"] = "Jurisdiction"
+    name: str
+    parent: Optional[str] = Field(
+        default=None,
+        description="Parent jurisdiction id (e.g., 'us.federal' is parent of 'us.federal.epa').",
+    )
+
+
+class Citation(_NodeBase):
+    """A reference to the originating regulatory text."""
+
+    type: Literal["Citation"] = "Citation"
+    source_document: str
+    source_clause: str
+    url: Optional[str] = None
+
+
+# ---------------------------------------------------------------------------
+# Edges
+# ---------------------------------------------------------------------------
+
+
+class Edge(BaseModel):
+    """A typed, directed edge between two nodes (spec §3.2)."""
+
+    type: EdgeType
+    from_id: str = Field(..., alias="from")
+    to_id: str = Field(..., alias="to")
+
+    model_config = ConfigDict(
+        use_enum_values=True,
+        extra="forbid",
+        populate_by_name=True,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Validation result types
+# ---------------------------------------------------------------------------
+
+
+class V3IssueType(str, Enum):
+    """Issue categories surfaced by the v3 validator."""
+
+    DUPLICATE_NODE_ID = "DUPLICATE_NODE_ID"
+    UNKNOWN_OBLIGATION_TYPE = "UNKNOWN_OBLIGATION_TYPE"
+    MISSING_EFFECTIVE_DATE = "MISSING_EFFECTIVE_DATE"
+    DANGLING_EDGE = "DANGLING_EDGE"
+    INVALID_EDGE_TARGET_TYPE = "INVALID_EDGE_TARGET_TYPE"
+    RULE_WITHOUT_OBLIGATION = "RULE_WITHOUT_OBLIGATION"
+    OBLIGATION_WITHOUT_RULE = "OBLIGATION_WITHOUT_RULE"
+    UNKNOWN_RISK_TIER = "UNKNOWN_RISK_TIER"
+
+
+class V3ValidationIssue(BaseModel):
+    """A single finding produced by the v3 validator."""
+
+    issue_type: V3IssueType
+    severity: Literal["LOW", "MEDIUM", "HIGH", "CRITICAL"] = "HIGH"
+    node_id: Optional[str] = None
+    edge: Optional[Edge] = None
+    message: str
+    suggested_action: Optional[str] = None
+
+    model_config = ConfigDict(use_enum_values=True)
+
+
+class V3ValidationResult(BaseModel):
+    """The aggregated output of one v3 validation run."""
+
+    schema_version: str = "3.0"
+    total_nodes: int = 0
+    total_edges: int = 0
+    total_issues: int = 0
+    issues: List[V3ValidationIssue] = Field(default_factory=list)
+
+    @property
+    def is_clean(self) -> bool:
+        """True iff no CRITICAL or HIGH severity issues were found."""
+        return not any(i.severity in ("CRITICAL", "HIGH") for i in self.issues)

kg_validator/validator.py

@@ -0,0 +1,238 @@
+"""V3 validator — runs the spec §3.6 validation passes against a loaded KG.
+
+Implements the subset that does not require sophisticated unit handling:
+
+* Duplicate node IDs across all node types.
+* Edges pointing at undefined node IDs (dangling edges).
+* Edge target type matches what the edge type expects
+  (``applies_to`` must point at a Subject, ``consists_of`` at an
+  Obligation, etc.).
+* Rules with no ``consists_of`` edge (every rule must have at least
+  one obligation per spec §2.1.2).
+* Obligations with no incoming ``consists_of`` edge from a Rule
+  (orphan obligations).
+
+Deferred to follow-up PRs:
+
+* Contradictory obligations (needs sophisticated unit handling).
+* Date-interval overlaps for mutually exclusive obligations.
+* Cyclic precedent edges.
+* Definition scope checking.
+
+Obligation-type validity and missing ``effective_date_start`` are
+already enforced at the Pydantic layer by :mod:`kg_validator.models`,
+so they surface as :class:`pydantic.ValidationError` at
+:func:`load_v3_kg` time rather than as runtime issues here.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Set, Tuple
+
+from .loader import KnowledgeGraphV3
+from .models import (
+    EdgeType,
+    V3IssueType,
+    V3ValidationIssue,
+    V3ValidationResult,
+)
+
+# Expected target-type per edge type. ``cited_by`` accepts any source
+# node, so it does not appear here.
+_EDGE_TARGET_TYPE: Dict[EdgeType, str] = {
+    EdgeType.APPLIES_TO: "Subject",
+    EdgeType.CONSISTS_OF: "Obligation",
+    EdgeType.DEFINED_BY: "Definition",
+    EdgeType.EXEMPTED_BY: "Exemption",
+    EdgeType.AMENDED_BY: "Obligation",
+    EdgeType.INTERPRETED_BY: "Precedent",
+    EdgeType.SCOPED_TO: "Jurisdiction",
+    EdgeType.CITED_BY: "Citation",
+}
+
+
+class V3Validator:
+    """Run the §3.6 validation passes against a loaded v3 KG."""
+
+    def __init__(self, kg: KnowledgeGraphV3) -> None:
+        self._kg = kg
+        self._issues: List[V3ValidationIssue] = []
+
+    def run(self) -> V3ValidationResult:
+        """Execute every validation pass and return the aggregated result."""
+        self._issues = []
+        self._check_duplicate_node_ids()
+        node_types = self._kg.all_node_ids()
+        self._check_dangling_edges(node_types)
+        self._check_edge_target_types(node_types)
+        self._check_rule_obligation_coverage()
+
+        total_nodes = sum(
+            (
+                len(self._kg.nodes.subjects),
+                len(self._kg.nodes.rules),
+                len(self._kg.nodes.obligations),
+                len(self._kg.nodes.definitions),
+                len(self._kg.nodes.exemptions),
+                len(self._kg.nodes.precedents),
+                len(self._kg.nodes.jurisdictions),
+                len(self._kg.nodes.citations),
+            )
+        )
+        return V3ValidationResult(
+            total_nodes=total_nodes,
+            total_edges=len(self._kg.edges),
+            total_issues=len(self._issues),
+            issues=list(self._issues),
+        )
+
+    # ------------------------------------------------------------------ #
+    # Individual validation passes                                       #
+    # ------------------------------------------------------------------ #
+
+    def _check_duplicate_node_ids(self) -> None:
+        seen: Set[str] = set()
+        for node_id in self._kg.all_node_ids():
+            if node_id in seen:
+                self._issues.append(
+                    V3ValidationIssue(
+                        issue_type=V3IssueType.DUPLICATE_NODE_ID,
+                        severity="CRITICAL",
+                        node_id=node_id,
+                        message=f"Node id '{node_id}' appears more than once across node arrays.",
+                        suggested_action="Rename one of the duplicates, then re-sign the KG.",
+                    )
+                )
+            seen.add(node_id)
+
+        # all_node_ids() is a dict so duplicates within the same array
+        # are already collapsed. Detect them explicitly by counting.
+        for collection in (
+            self._kg.nodes.subjects,
+            self._kg.nodes.rules,
+            self._kg.nodes.obligations,
+            self._kg.nodes.definitions,
+            self._kg.nodes.exemptions,
+            self._kg.nodes.precedents,
+            self._kg.nodes.jurisdictions,
+            self._kg.nodes.citations,
+        ):
+            counts: Dict[str, int] = {}
+            for node in collection:
+                counts[node.id] = counts.get(node.id, 0) + 1
+            for node_id, count in counts.items():
+                if count > 1:
+                    self._issues.append(
+                        V3ValidationIssue(
+                            issue_type=V3IssueType.DUPLICATE_NODE_ID,
+                            severity="CRITICAL",
+                            node_id=node_id,
+                            message=(
+                                f"Node id '{node_id}' appears {count} times within the same node array."
+                            ),
+                            suggested_action="Rename one of the duplicates, then re-sign the KG.",
+                        )
+                    )
+
+    def _check_dangling_edges(self, node_types: Dict[str, str]) -> None:
+        for edge in self._kg.edges:
+            if edge.from_id not in node_types:
+                self._issues.append(
+                    V3ValidationIssue(
+                        issue_type=V3IssueType.DANGLING_EDGE,
+                        severity="HIGH",
+                        edge=edge,
+                        message=(
+                            f"Edge {edge.type} from '{edge.from_id}' references an undefined source node."
+                        ),
+                        suggested_action="Add the missing source node or remove the edge.",
+                    )
+                )
+            if edge.to_id not in node_types:
+                self._issues.append(
+                    V3ValidationIssue(
+                        issue_type=V3IssueType.DANGLING_EDGE,
+                        severity="HIGH",
+                        edge=edge,
+                        message=(f"Edge {edge.type} to '{edge.to_id}' references an undefined target node."),
+                        suggested_action="Add the missing target node or remove the edge.",
+                    )
+                )
+
+    def _check_edge_target_types(self, node_types: Dict[str, str]) -> None:
+        for edge in self._kg.edges:
+            expected = _EDGE_TARGET_TYPE.get(EdgeType(edge.type))
+            if expected is None:
+                continue
+            actual = node_types.get(edge.to_id)
+            if actual is None:
+                # Already flagged by _check_dangling_edges.
+                continue
+            if actual != expected:
+                self._issues.append(
+                    V3ValidationIssue(
+                        issue_type=V3IssueType.INVALID_EDGE_TARGET_TYPE,
+                        severity="HIGH",
+                        edge=edge,
+                        message=(
+                            f"Edge '{edge.type}' from '{edge.from_id}' targets a "
+                            f"'{actual}' node ('{edge.to_id}') but spec §3.2 requires a "
+                            f"'{expected}' target."
+                        ),
+                        suggested_action=(
+                            f"Repoint the edge at a {expected} node, or use a different edge type."
+                        ),
+                    )
+                )
+
+    def _check_rule_obligation_coverage(self) -> None:
+        rule_ids: Set[str] = {r.id for r in self._kg.nodes.rules}
+        obligation_ids: Set[str] = {o.id for o in self._kg.nodes.obligations}
+        consists_of: List[Tuple[str, str]] = [
+            (e.from_id, e.to_id) for e in self._kg.edges if e.type == EdgeType.CONSISTS_OF.value
+        ]
+        rules_with_obligation: Set[str] = {src for src, _ in consists_of if src in rule_ids}
+        obligations_with_rule: Set[str] = {dst for _, dst in consists_of if dst in obligation_ids}
+
+        for rule_id in rule_ids - rules_with_obligation:
+            self._issues.append(
+                V3ValidationIssue(
+                    issue_type=V3IssueType.RULE_WITHOUT_OBLIGATION,
+                    severity="HIGH",
+                    node_id=rule_id,
+                    message=(
+                        f"Rule '{rule_id}' has no consists_of edge to any Obligation. "
+                        "Spec §2.1.2 requires every rule to reference at least one typed "
+                        "obligation."
+                    ),
+                    suggested_action="Add a consists_of edge to one or more Obligation nodes.",
+                )
+            )
+
+        for obligation_id in obligation_ids - obligations_with_rule:
+            self._issues.append(
+                V3ValidationIssue(
+                    issue_type=V3IssueType.OBLIGATION_WITHOUT_RULE,
+                    severity="MEDIUM",
+                    node_id=obligation_id,
+                    message=(
+                        f"Obligation '{obligation_id}' is not referenced by any Rule via a "
+                        "consists_of edge. The obligation is unreachable from the runtime."
+                    ),
+                    suggested_action=("Either add a consists_of edge from a Rule, or remove the obligation."),
+                )
+            )
+
+    # ------------------------------------------------------------------ #
+    # Convenience accessors                                              #
+    # ------------------------------------------------------------------ #
+
+    @property
+    def issues(self) -> List[V3ValidationIssue]:
+        """The issues from the most recent :meth:`run`."""
+        return list(self._issues)
+
+    @staticmethod
+    def edge_target_type(edge_type: EdgeType) -> str:
+        """Public accessor for the expected target type of an edge."""
+        return _EDGE_TARGET_TYPE[edge_type]

ski_kg_validator-3.0.3.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: ski-kg-validator
+Version: 3.0.3
+Summary: Validate and review extracted compliance rules with mandatory human expert oversight.
+Author-email: KpiFinity <hello@kpifinity.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/kpifinity/ski-framework
+Project-URL: Documentation, https://kpifinity.github.io/ski-framework/
+Project-URL: Issues, https://github.com/kpifinity/ski-framework/issues
+Keywords: ski-framework,compliance,knowledge-graph,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Legal Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3,>=2.13.4
+Requires-Dist: click<9,>=8.1.7
+Requires-Dist: python-dotenv<2,>=1.2.2
+Requires-Dist: rapidfuzz<4,>=3.7
+Requires-Dist: jinja2<4,>=3.1.6
+
+# kg-validator
+
+> Install from PyPI: `pip install ski-kg-validator` (publishing starts with the first release after June 2026).
+
+> **Status:** v3.0 — first production-target release.
+
+Validate v3 Knowledge Graphs against SKI Framework specification v3.0
+§3 (schema) and §3.6 (cross-cutting validation passes). Phase 1
+(compilation) tool.
+
+## What it does
+
+- **Schema validation.** Parses a v3 KG JSON file into the typed-node
+  Pydantic models. Unknown obligation types, unknown edge types,
+  unknown risk tiers, missing required fields, and extra unknown keys
+  are all rejected at load time.
+- **Cross-cutting validation (§3.6).** Detects duplicate node IDs,
+  dangling edges, edges pointing at the wrong target node type, rules
+  without any obligation, and orphan obligations.
+
+## What it no longer does (v2 retired in PR 10e)
+
+- The v2 flat-rule-list format is gone. v3 typed obligations are the
+  only currency.
+- Interactive `review`, `detect-conflicts`, `detect-duplicates`, and
+  HTML `report` subcommands were retired with the v2 path — they
+  worked on the flat-rule shape and have no v3 equivalent. v3
+  conflict and duplicate detection happen at the typed-obligation
+  level inside the validation passes and surface as issues in the
+  output JSON.
+- The `ConfidenceLevel` enum is gone. The extractor now carries an
+  `ExtractionQuality` value (separate concept; see `kg-extractor`).
+
+## Installation
+
+```bash
+pip install -e tools/kg-validator
+```
+
+## Quick start
+
+```bash
+# Validate a v3 KG and print the issue summary:
+kg-validator validate --input examples/energy/knowledge-graphs/kg-energy-v3-demo.json
+
+# Validate and persist the full issue report:
+kg-validator validate \
+  --input kg-energy-v3.json \
+  --output validation-report.json
+
+# Show usage examples:
+kg-validator examples
+
+# Show version:
+kg-validator version
+```
+
+The `validate` command exits with code 0 on a clean KG, code 2 on a
+schema-level Pydantic validation failure, and code 3 on any CRITICAL
+or HIGH severity §3.6 issue.
+
+## Architecture
+
+```
+kg_validator/
+├── __init__.py    public API: KnowledgeGraphV3, V3Validator, load_v3_kg, models
+├── loader.py      KnowledgeGraphV3 container + load_v3_kg(path) entry point
+├── models.py      typed Pydantic models per spec v3.0 §3 (nodes, edges, enums)
+├── validator.py   V3Validator runs the §3.6 cross-cutting passes
+└── cli.py         click-based CLI (`validate`, `examples`, `version`)
+```
+
+## Conformance
+
+The `examples/energy/knowledge-graphs/kg-energy-v3-demo.json` sample
+KG must load cleanly and produce zero validation issues. This is
+exercised by `tests/test_v3_validator.py` and by the CI durability
+suite.

ski_kg_validator-3.0.3.dist-info/RECORD

@@ -0,0 +1,11 @@
+kg_validator/__init__.py,sha256=Q5dKadHu3jmR9ozkWqSd9LUo8ZOXqKIXNOctJ4UrT_U,818
+kg_validator/cli.py,sha256=a0MtREfXw7r-QmtAxorCEQCIJHOJxbfmcHF3u1b2pv0,3514
+kg_validator/loader.py,sha256=7slXE54-knuIEmmebA4-fj-XB858Nb3FreatQqzKR0o,3689
+kg_validator/models.py,sha256=ZkHKwYOvmuJvipYFzevHb8CxAN1BxTQG3h3vz7wnYSc,7391
+kg_validator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kg_validator/validator.py,sha256=hOghfsHsueHFwGFCiZitKjEpRYDK-bVnqwh2UjI4Q1A,9920
+ski_kg_validator-3.0.3.dist-info/METADATA,sha256=oJaw_77L9EZaNSSsvBc6RXwyIFgAoxqzMeTMcs4yVXU,3883
+ski_kg_validator-3.0.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+ski_kg_validator-3.0.3.dist-info/entry_points.txt,sha256=HCO5XDLYv5yVZQoNPvVrkKFMiTKggq1TUuXQjFIJpfs,55
+ski_kg_validator-3.0.3.dist-info/top_level.txt,sha256=yn3SfyTuRJQnT4rO60D6iofSUSh27k6ac6Hu_oFfuvU,13
+ski_kg_validator-3.0.3.dist-info/RECORD,,

ski_kg_validator-3.0.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ski_kg_validator-3.0.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kg-validator = kg_validator.cli:main

ski_kg_validator-3.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+kg_validator