ski-kg-validator 3.0.3__tar.gz

ski_kg_validator-3.0.3/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,78 @@
+# 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/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ski-kg-validator"
+version = "3.0.3"
+description = "Validate and review extracted compliance rules with mandatory human expert oversight."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "KpiFinity", email = "hello@kpifinity.com" }]
+keywords = ["ski-framework", "compliance", "knowledge-graph", "validation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Legal Industry",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "pydantic>=2.13.4,<3",
+    "click>=8.1.7,<9",
+    "python-dotenv>=1.2.2,<2",
+    "rapidfuzz>=3.7,<4",
+    "jinja2>=3.1.6,<4",
+]
+
+[project.urls]
+Homepage = "https://github.com/kpifinity/ski-framework"
+Documentation = "https://kpifinity.github.io/ski-framework/"
+Issues = "https://github.com/kpifinity/ski-framework/issues"
+
+[project.scripts]
+kg-validator = "kg_validator.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+kg_validator = ["py.typed"]

ski_kg_validator-3.0.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ski_kg_validator-3.0.3/src/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",
+]

ski_kg_validator-3.0.3/src/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()

ski_kg_validator-3.0.3/src/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)