Documentation Index
Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
Use this file to discover all available pages before exploring further.
Delta tracking captures all changes made to a document during a tracking session, enabling you to export those changes as a portable delta, preview them, and apply them to other documents. This is useful for collaborative editing, change review workflows, and synchronization.
Overview
The delta system supports:
- Tracking Sessions: Start and stop change recording
- Delta Export: Export captured changes as JSON or binary format
- Delta Preview: Preview what changes would be applied
- Delta Apply: Apply changes to a document with conflict detection
- Session Management: List and manage tracking sessions
Starting and Stopping Tracking
from kodexa_document import Document
with Document() as doc:
root = doc.create_node("document", "Original content")
doc.content_node = root
# Start tracking changes
session = doc.delta.start_tracking(
username="user@example.com",
comment="Initial extraction review"
)
print(f"Tracking session started: {session}")
# Make changes while tracking is active
para = doc.create_node("paragraph", "New paragraph", parent=root)
para.tag("reviewed")
# Check tracking status
status = doc.delta.get_status()
print(f"Delta status: {status}")
# Get the active session
active = doc.delta.get_active_session()
print(f"Active session: {active}")
# Stop tracking (finalizes the session)
result = doc.delta.stop_tracking()
print(f"Session stopped: {result}")
Cancelling a Session
If you want to discard a tracking session without finalizing it:
with Document() as doc:
root = doc.create_node("document", "Content")
doc.content_node = root
doc.delta.start_tracking(username="user@example.com")
# Make some changes...
# Cancel - discard the tracking session
doc.delta.cancel_tracking()
Exporting Deltas
After stopping a tracking session, export the captured changes:
with Document() as doc:
root = doc.create_node("document", "Content")
doc.content_node = root
doc.delta.start_tracking(username="reviewer")
# Make changes...
para = doc.create_node("paragraph", "Added content", parent=root)
doc.delta.stop_tracking()
# Export as JSON (for inspection/debugging)
delta_json = doc.delta.export_json()
print(f"Delta JSON: {delta_json}")
# Export as bytes (for storage/transfer)
delta_bytes = doc.delta.export_bytes()
if delta_bytes:
print(f"Delta size: {len(delta_bytes)} bytes")
# Save to file
with open("changes.delta", "wb") as f:
f.write(delta_bytes)
Previewing and Applying Deltas
Preview Changes
Before applying a delta, preview what would change:
with Document.from_kddb("target.kddb") as doc:
# Load delta bytes
with open("changes.delta", "rb") as f:
delta_bytes = f.read()
# Preview the changes without applying
preview = doc.delta.preview(delta_bytes)
print(f"Preview: {preview}")
Apply Changes
with Document.from_kddb("target.kddb") as doc:
with open("changes.delta", "rb") as f:
delta_bytes = f.read()
# Apply the delta
result = doc.delta.apply(delta_bytes, options={
"stopOnConflict": False,
"skipMissingRefs": True,
"createAuditTrail": True,
"actorUri": "user://reviewer@example.com",
"comment": "Applied review changes"
})
print(f"Applied: {result}")
doc.save("updated.kddb")
Import a Delta
Import a previously exported delta back into a document:
with Document.from_kddb("document.kddb") as doc:
with open("changes.delta", "rb") as f:
delta_bytes = f.read()
# Import the delta
result = doc.delta.import_delta(delta_bytes)
print(f"Import result: {result}")
Managing Sessions
with Document.from_kddb("document.kddb") as doc:
# List all tracking sessions
sessions = doc.delta.list_sessions()
for session in sessions:
print(f"Session: {session}")
# Filter by status
active_sessions = doc.delta.list_sessions(status_filter="active")
completed_sessions = doc.delta.list_sessions(status_filter="completed")
API Reference
DeltaAccessor Methods
| Method (Python) | Method (TypeScript) | Description |
|---|
start_tracking(username, comment) | startTracking(username, comment) | Start a tracking session |
stop_tracking() | stopTracking() | Stop and finalize the session |
cancel_tracking() | cancelTracking() | Discard the session |
get_active_session() | getActiveSession() | Get the current session |
get_status() | getStatus() | Get tracking status |
export_json() | exportJson() | Export delta as JSON |
export_bytes() | exportBytes() | Export delta as binary |
import_delta(bytes) | importDelta(bytes) | Import a delta |
apply(bytes, options) | apply(bytes, options) | Apply a delta |
preview(bytes) | preview(bytes) | Preview a delta |
list_sessions(filter) | listSessions(filter) | List tracking sessions |
Apply Options
| Option | Type | Description |
|---|
stopOnConflict | boolean | Stop applying on first conflict |
skipMissingRefs | boolean | Skip operations referencing missing entities |
createAuditTrail | boolean | Record applied changes in the audit trail |
actorUri | string | URI identifying who applied the changes |
comment | string | Description of the applied changes |
