feat: add DB-backed iter_db_snapshots utility to slice normalized tra…

[soma-enyi]

Closes #68

feat: DB-backed time-windowed snapshot slicer for training data generation

Problem

Training temporal GNN models requires the dataset to be sliced into discrete, ordered graph snapshots — one per time
window (t_0 to t_now). There was no utility to do this from the database; callers had to manually write SQLAlchemy
queries, handle timezone normalization, and reconstruct graph structures themselves.

Changes

astroml/features/graph/snapshot.py

Added two new components:

SnapshotWindow dataclass
A frozen dataclass representing a single time slice, carrying everything a training loop needs:

• index — 0-based position in the sequence
• start / end — window boundaries as timezone-aware datetimes
• edges — list of Edge objects within the window
• nodes — set of all account IDs active in the window

iter_db_snapshots() generator
Queries normalized_transactions and yields SnapshotWindow instances in chronological order from t0 to t_now.

Key behaviours:

• window and step accept human-friendly strings: '7d', '24h', '3600s'
• step == window (default) → non-overlapping slices; step < window → rolling windows
• t0 auto-resolves to the earliest timestamp in the DB; t_now defaults to datetime.now(UTC) — giving the full
  t_0 … t_now range with no manual configuration
• Self-loops and null receivers are filtered at the SQL level
• Session is optional — defaults to get_session() but accepts an injected session for testing

Usage

python
from astroml.features.graph.snapshot import iter_db_snapshots

for snap in iter_db_snapshots(window="7d", t0=t0, t_now=t_now):
print(f"[{snap.index}] {snap.start} → {snap.end}: {len(snap.nodes)} nodes, {len(snap.edges)} edges")
# feed snap.edges / snap.nodes into your GNN pipeline

Rolling windows:
python

7-day window sliding forward 1 day at a time

for snap in iter_db_snapshots(window="7d", step="1d"):
...

Related

Closes #[68] —Build a utility to slice the database into discrete time-windowed snapshots (e.g., t0 to t_now) for
training_

[drips-wave]

@soma-enyi Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits