Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(provenance): resolve broken imports in ingest and parse provenance wrappers (#1872)

Kevinaae1ccb2fd19
diff --git a/semantica/ingest/ingest_provenance.py b/semantica/ingest/ingest_provenance.py
index 51930fa4..2d2e40df 100644
--- a/semantica/ingest/ingest_provenance.py
+++ b/semantica/ingest/ingest_provenance.py
@@ -5,7 +5,7 @@ Tracks: file paths, pages, metadata, ingestion timestamps
Usage:
from semantica.ingest.ingest_provenance import PDFIngestorWithProvenance
-
+
ingestor = PDFIngestorWithProvenance(provenance=True)
docs = ingestor.ingest("document.pdf")
@@ -13,8 +13,9 @@ Author: Semantica Contributors
License: MIT
"""
-from typing import Optional, List
+from typing import Optional
from datetime import datetime
+from pathlib import Path
import uuid
@@ -51,17 +52,35 @@ class PDFIngestorWithProvenance(IngestProvenanceMixin):
is_automated: bool = True,
**config,
):
- from .pdf_ingestor import PDFIngestor
+ from .file_ingestor import FileIngestor
IngestProvenanceMixin.__init__(
self, provenance=provenance, agent_id=agent_id, is_automated=is_automated
)
- self._ingestor = PDFIngestor(**config)
+ self._ingestor = FileIngestor(**config)
def ingest(self, file_path: str, **kwargs):
- """Ingest PDF with provenance tracking."""
+ """Ingest a single PDF file with provenance tracking.
+
+ ``FileIngestor`` accepts any file or directory, but this wrapper records
+ every result as ``file_type="pdf"``. To keep that provenance truthful,
+ only a single ``.pdf`` file is accepted; directories and other file
+ types are rejected before anything is read.
+
+ Raises:
+ ValidationError: If *file_path* does not have a ``.pdf`` extension,
+ or (from ``FileIngestor``) does not exist / is not a file.
+ """
+ from ..utils.exceptions import ValidationError
+
+ if Path(file_path).suffix.lower() != ".pdf":
+ raise ValidationError(
+ f"PDFIngestorWithProvenance only ingests .pdf files, got: {file_path}"
+ )
+
activity_started_at_time = datetime.utcnow().isoformat()
- docs = self._ingestor.ingest(file_path, **kwargs)
+ # ingest_file (not ingest) so a directory can never be expanded here.
+ docs = [self._ingestor.ingest_file(file_path, **kwargs)]
activity_ended_at_time = datetime.utcnow().isoformat()
if self.provenance and self._prov_manager:
@@ -81,9 +100,9 @@ class PDFIngestorWithProvenance(IngestProvenanceMixin):
"pages": getattr(doc, 'page_count', None)
}
)
-
+
return docs
-
+
def __getattr__(self, name):
return getattr(self._ingestor, name)
diff --git a/semantica/parse/parse_provenance.py b/semantica/parse/parse_provenance.py
index 85a514ba..c2c8b992 100644
--- a/semantica/parse/parse_provenance.py
+++ b/semantica/parse/parse_provenance.py
@@ -5,7 +5,7 @@ Tracks: file parsed, format, structure, parsing method
Usage:
from semantica.parse.parse_provenance import JSONParserWithProvenance
-
+
parser = JSONParserWithProvenance(provenance=True)
data = parser.parse("data.json")
@@ -28,10 +28,10 @@ class ParserWithProvenance:
is_automated: bool = True,
**config,
):
- from .parser import Parser
+ from .document_parser import DocumentParser
self.provenance = provenance
- self._parser = Parser(**config)
+ self._parser = DocumentParser(**config)
self._prov_manager = None
self._agent_id = agent_id or self.__class__.__name__
self._is_automated = is_automated
@@ -64,9 +64,9 @@ class ParserWithProvenance:
"format": kwargs.get('format', 'unknown')
}
)
-
+
return data
-
+
def __getattr__(self, name):
return getattr(self._parser, name)
diff --git a/tests/provenance/test_provenance_wrapper_imports.py b/tests/provenance/test_provenance_wrapper_imports.py
new file mode 100644
index 00000000..5bd0a18a
--- /dev/null
+++ b/tests/provenance/test_provenance_wrapper_imports.py
@@ -0,0 +1,127 @@
+"""
+Regression tests for provenance wrapper import resolution.
+
+Every ``*WithProvenance`` wrapper imports its underlying implementation lazily,
+inside ``__init__``. A wrong import path is therefore invisible at import time
+and only surfaces when the wrapper is instantiated. The surrounding suites
+guard those instantiations with ``except ImportError: pytest.skip(...)``, which
+converts the failure into a skip and hides it from CI.
+
+These tests intentionally do not skip: if a wrapper cannot resolve its
+underlying implementation, the test fails.
+"""
+
+
+class TestIngestProvenanceWrapper:
+ """PDFIngestorWithProvenance must resolve the file ingestor it wraps."""
+
+ def test_instantiates_and_wraps_file_ingestor(self):
+ from semantica.ingest.file_ingestor import FileIngestor
+ from semantica.ingest.ingest_provenance import PDFIngestorWithProvenance
+
+ wrapper = PDFIngestorWithProvenance(provenance=False)
+ assert isinstance(wrapper._ingestor, FileIngestor)
+
+ def test_delegates_unknown_attributes(self):
+ from semantica.ingest.ingest_provenance import PDFIngestorWithProvenance
+
+ wrapper = PDFIngestorWithProvenance(provenance=False)
+ # `ingest_file` is defined on FileIngestor, not on the wrapper.
+ assert callable(wrapper.ingest_file)
+
+
+def _tracked_ingest_wrapper():
+ """Return a PDF wrapper whose provenance manager is a recording mock."""
+ from unittest.mock import MagicMock
+
+ from semantica.ingest.ingest_provenance import PDFIngestorWithProvenance
+
+ wrapper = PDFIngestorWithProvenance(provenance=False)
+ wrapper.provenance = True
+ wrapper._prov_manager = MagicMock()
+ return wrapper
+
+
+class TestPDFIngestProvenanceContract:
+ """Provenance must never label a non-PDF (or a directory) as ``pdf``."""
+
+ def test_pdf_file_is_ingested_and_tracked_as_pdf(self, tmp_path):
+ pdf = tmp_path / "doc.PDF"
+ pdf.write_bytes(b"%PDF-1.4 minimal")
+ wrapper = _tracked_ingest_wrapper()
+
+ docs = wrapper.ingest(str(pdf))
+
+ assert [d.file_type for d in docs] == ["pdf"]
+ wrapper._prov_manager.track_entity.assert_called_once()
+ kwargs = wrapper._prov_manager.track_entity.call_args.kwargs
+ assert kwargs["source"] == str(pdf)
+ assert kwargs["metadata"]["file_type"] == "pdf"
+
+ def test_non_pdf_file_is_rejected_without_provenance(self, tmp_path):
+ import pytest
+
+ from semantica.utils.exceptions import ValidationError
+
+ txt = tmp_path / "notes.txt"
+ txt.write_text("not a pdf")
+ wrapper = _tracked_ingest_wrapper()
+
+ with pytest.raises(ValidationError):
+ wrapper.ingest(str(txt))
+ wrapper._prov_manager.track_entity.assert_not_called()
+
+ def test_directories_are_rejected_without_provenance(self, tmp_path):
+ import pytest
+
+ from semantica.utils.exceptions import ValidationError
+
+ (tmp_path / "inner.pdf").write_bytes(b"%PDF-1.4")
+ wrapper = _tracked_ingest_wrapper()
+
+ # A plain directory and a directory whose *name* ends in .pdf.
+ fake_pdf_dir = tmp_path / "looks_like.pdf"
+ fake_pdf_dir.mkdir()
+ (fake_pdf_dir / "secret.txt").write_text("x")
+
+ for target in (tmp_path, fake_pdf_dir):
+ with pytest.raises(ValidationError):
+ wrapper.ingest(str(target))
+ wrapper._prov_manager.track_entity.assert_not_called()
+
+
+class TestParseProvenanceWrapper:
+ """ParserWithProvenance must resolve the document parser it wraps."""
+
+ def test_instantiates_and_wraps_document_parser(self):
+ from semantica.parse.document_parser import DocumentParser
+ from semantica.parse.parse_provenance import ParserWithProvenance
+
+ wrapper = ParserWithProvenance(provenance=False)
+ assert isinstance(wrapper._parser, DocumentParser)
+
+ def test_delegates_unknown_attributes(self):
+ from semantica.parse.parse_provenance import ParserWithProvenance
+
+ wrapper = ParserWithProvenance(provenance=False)
+ # `parse_document` is defined on DocumentParser, not on the wrapper.
+ assert callable(wrapper.parse_document)
+
+ def test_parse_delegates_and_tracks_provenance(self, tmp_path):
+ from unittest.mock import MagicMock
+
+ from semantica.parse.parse_provenance import ParserWithProvenance
+
+ txt = tmp_path / "a.txt"
+ txt.write_text("hello")
+ wrapper = ParserWithProvenance(provenance=False)
+ wrapper.provenance = True
+ wrapper._prov_manager = MagicMock()
+
+ result = wrapper.parse(str(txt))
+
+ assert result["text"] == "hello"
+ wrapper._prov_manager.track_entity.assert_called_once()
+ kwargs = wrapper._prov_manager.track_entity.call_args.kwargs
+ assert kwargs["source"] == str(txt)
+ assert kwargs["entity_type"] == "parsed_data"