Add account and transaction graph views

.gitignore

@@ -232,3 +232,4 @@ __marimo__/
 /wandb/
 /mlruns/
 /logs/
+/docs/

src/amlgraphx/__init__.py

@@ -1,2 +1,22 @@
+"""AMLGraphX public package exports."""
+
+from .graphs import (
+    AccountGraph,
+    TransactionGraph,
+    build_account_graph,
+    build_transaction_graph,
+)
+
+
 def hello() -> str:
+    """Return the package greeting kept for backwards compatibility."""
     return "Hello from amlgraphx!"
+
+
+__all__ = [
+    "AccountGraph",
+    "TransactionGraph",
+    "build_account_graph",
+    "build_transaction_graph",
+    "hello",
+]

src/amlgraphx/datasets/base.py

@@ -135,6 +135,7 @@ def clean_lazy_frame(
 _SOURCE_ALIASES = (
     "source",
     "sender",
+    "sender account",
     "from",
     "from account",
     "source id",
@@ -146,8 +147,12 @@ def clean_lazy_frame(
 _TARGET_ALIASES = (
     "target",
     "receiver",
+    "receiver account",
     "to",
     "to account",
+    "account.1",
+    "account 1",
+    "account duplicated 0",
     "target id",
     "dst",
     "namedest",

src/amlgraphx/datasets/download.py

@@ -51,7 +51,12 @@ def find_tabular_file(root: Path, preferred_terms: Sequence[str] = ()) -> Path:
     candidates = sorted(
         path
         for path in root.rglob("*")
-        if path.is_file() and path.suffix.lower() in {".csv", ".parquet"}
+        if (
+            path.is_file()
+            and path.suffix.lower() in {".csv", ".parquet"}
+            and "__MACOSX" not in path.parts
+            and not path.name.startswith("._")
+        )
     )
     for term in preferred_terms:
         matches = [path for path in candidates if term.lower() in path.name.lower()]

src/amlgraphx/datasets/paysim.py

@@ -1,5 +1,6 @@
 """PaySim dataset adapter."""
 
+from datetime import UTC, datetime
 from pathlib import Path
 
 import polars as pl
@@ -86,12 +87,23 @@ def transaction_path(self) -> Path:
         return find_tabular_file(self.download(), ("log", "paysim"))
 
     def transactions(self) -> pl.LazyFrame:
-        """Return lazily scanned and cleaned PaySim transactions."""
-        return clean_lazy_frame(
+        """Return lazily scanned PaySim transactions with a logical timestamp.
+
+        PaySim's ``step`` is a simulated hour. The added ``timestamp`` anchors
+        that hour sequence at the Unix epoch solely to support temporal graph
+        construction; the original ``step`` column remains unchanged.
+        """
+        frame = clean_lazy_frame(
             pl.scan_csv(self.transaction_path()),
             source_column="nameOrig",
             target_column="nameDest",
         )
+        return frame.with_columns(
+            (
+                pl.lit(datetime(1970, 1, 1, tzinfo=UTC))
+                + pl.duration(hours=pl.col("step").cast(pl.Int64))
+            ).alias("timestamp")
+        )
 
     def _dataset_root(self) -> Path:
         if self.local_dir is not None: