History

Change tracking helpers from annnet.core._History.

History methods are mixed into AnnNet. Direct imports from underscore modules follow the internal API policy.

annnet.core._History.GraphDiff

Set difference between two graph snapshots (vertices/edges/slices added/removed).

Functions

summary

summary()

Return a human-readable summary of differences.

Returns:

Type	Description
str	Summary text describing added/removed vertices, edges, and slices.

is_empty

is_empty()

Check whether the diff contains no changes.

Returns:

Type	Description
bool

to_dict

to_dict()

Convert the diff to a serializable dictionary.

Returns:

Type	Description
dict

annnet.core._History.History

Mutation logging, version counter, snapshots, and diffs (mixed into AnnNet).

Functions

history

history(as_df=False)

Return the append-only mutation history.

Parameters:

Name	Type	Description	Default
as_df	bool	If True, return a DataFrame; otherwise return a list of dicts.	False

Returns:

Type	Description
list[dict] | DataFrame	Event records including version, ts_utc, mono_ns, op, and captured arguments/results.

Notes

Ordering is guaranteed by version and mono_ns. The log is in-memory until exported.

export_history

export_history(path)

Write the mutation history to disk.

Parameters:

Name	Type	Description	Default
path	str	Output path. Supported extensions: .parquet, .ndjson/.jsonl, .json, .csv. Unknown extensions default to Parquet.	required

Returns:

Type	Description
int	Number of events written. Returns 0 if the history is empty.

Raises:

Type	Description
OSError	If the file cannot be written.

Notes

Unknown extensions default to Parquet by appending .parquet.

enable_history

enable_history(flag=True)

Enable or disable in-memory mutation logging.

Parameters:

Name	Type	Description	Default
flag	bool	When True, start/continue logging; when False, pause logging.	True

Returns:

Type	Description
None

clear_history

clear_history()

Clear the in-memory mutation log.

Returns:

Type	Description
None

Notes

This does not delete any files previously exported.

mark

mark(label)

Insert a manual marker into the mutation history.

Parameters:

Name	Type	Description	Default
label	str	Human-readable tag for the marker event.	required

Returns:

Type	Description
None

Notes

The event is recorded with op='mark' alongside standard fields (version, ts_utc, mono_ns). Logging must be enabled for the marker to be recorded.

annnet.core._History.HistoryAccessor

Callable G.history namespace for logs and snapshots.

Functions

enable

enable(flag=True)

Enable or disable mutation history recording.

clear

clear()

Clear the recorded history log and stored snapshots.

export

export(path)

Write the recorded history log to disk.

mark

mark(label)

Append a labeled marker event to the history log.

snapshot

snapshot(label=None)

Capture and return a snapshot of the current graph state.

diff

diff(a=None, b=None)

Return a diff between two snapshots or snapshot references.

list_snapshots

list_snapshots()

Return the recorded snapshot list.