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

Represents the difference between two graph states.

Attributes:

Name	Type	Description
vertices_added	set	Vertices in b but not in a
vertices_removed	set	Vertices in a but not in b
edges_added	set	Edges in b but not in a
edges_removed	set	Edges in a but not in b
slices_added	set	slices in b but not in a
slices_removed	set	slices in a but not in b

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

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

Namespace for mutation logs and snapshots.

Stored on each graph instance as G.history. The accessor is callable so existing G.history() call sites remain valid while enabling G.history.export(...) and related namespace usage.