KaifAhmad1
581dbf8301
Every deprecation warning added in this PR (and the class docstring) points to docs/migration/kg-provenance-tracker.md, but the file was never added, so the reference was dead. Adds the guide with a method-mapping table to semantica.provenance.ProvenanceManager.
3.3 KiB
title, description
| title | description |
|---|---|
| Migrating from kg.ProvenanceTracker | How to move from the deprecated semantica.kg.ProvenanceTracker to the unified semantica.provenance.ProvenanceManager. |
Why migrate
semantica.kg.ProvenanceTracker is deprecated and will be removed in a future major version. It was a standalone, in-memory implementation that never delegated to the unified provenance backend — semantica.provenance.ProvenanceManager is that backend, and is now the supported way to track entity and relationship provenance across every Semantica module (see the Provenance & Audit Trails guide).
Every method on kg.ProvenanceTracker now emits a DeprecationWarning on use, but existing code keeps working unchanged until the class is removed — there is no forced migration deadline yet.
Method mapping
kg.ProvenanceTracker |
ProvenanceManager equivalent |
Notes |
|---|---|---|
ProvenanceTracker() |
ProvenanceManager() |
ProvenanceManager also accepts storage_path= for SQLite persistence instead of in-memory only. |
track_entity(entity_id, source, metadata) |
track_entity(entity_id, source, metadata) |
Same call shape. ProvenanceManager additionally auto-links each update to its prior version via parent_entity_id. |
get_all_sources(entity_id) |
get_all_sources(entity_id) |
Field name differs: the kg tracker returns each record's time under "recorded_at"; ProvenanceManager returns "timestamp". |
clear(entity_id=None) |
clear() |
ProvenanceManager.clear() clears all provenance data; there is no per-entity clear yet. |
query_recorded_between(start, end) |
No direct equivalent yet | Filter the entries returned by get_lineage() / trace_lineage() client-side in the meantime. |
revision_history(fact_id) |
No direct equivalent yet | get_lineage(fact_id)["lineage_chain"] returns the full chain of ProvenanceEntry records but not in the same versioned shape. |
export_audit_log(fact_ids, format) |
No direct equivalent yet | Build the export from get_lineage() output, or serialize get_statistics() for a summary view. |
Methods with no direct equivalent are not planned to be reimplemented on kg.ProvenanceTracker — they will need a small adapter in caller code, or a feature request against ProvenanceManager if you rely on them heavily.
Example
# Before
from semantica.kg import ProvenanceTracker
tracker = ProvenanceTracker()
tracker.track_entity("entity_1", source="doc_1", metadata={"confidence": 0.9})
sources = tracker.get_all_sources("entity_1") # [{"source": ..., "recorded_at": ..., "confidence": 0.9}]
# After
from semantica.provenance import ProvenanceManager
prov = ProvenanceManager()
prov.track_entity("entity_1", source="doc_1", metadata={"confidence": 0.9})
sources = prov.get_all_sources("entity_1") # [{"source": ..., "timestamp": ..., "metadata": {...}, ...}]
Suppressing the warning during migration
If you need to keep using kg.ProvenanceTracker temporarily and want to silence the warning while you plan the switch:
import warnings
with warnings.catch_warnings():
warnings.simplefilter("ignore", DeprecationWarning)
tracker = ProvenanceTracker()
This is a stopgap, not a fix — plan to move to ProvenanceManager before kg.ProvenanceTracker is removed.