event2vector 0.1.0__tar.gz

event2vector-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+exclude *.pkl
+exclude *.model
+exclude data/*

event2vector-0.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: event2vector
+Version: 0.1.0
+Summary: A geometric approach to learning composable representations of event sequences.
+Author: Antonin Sulc
+License: MIT
+Project-URL: Homepage, https://github.com/sulcantonin/event2vec_public
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: torch
+Requires-Dist: numpy
+Requires-Dist: tqdm
+Requires-Dist: matplotlib
+Requires-Dist: scikit-learn
+Requires-Dist: openTSNE
+Requires-Dist: gensim
+Requires-Dist: seaborn
+Dynamic: requires-python
+
+<div align="center">
+
+# Event2Vector
+## A Geometric Approach to Learning Composable Representations of Event Sequences
+
+[![PyPI version](https://badge.fury.io/py/event2vector.svg)](https://badge.fury.io/py/event2vector)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.6+](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)
+[![arXiv](https://img.shields.io/badge/arXiv-2509.12188-b31b1b.svg)](https://arxiv.org/abs/2509.12188)
+
+![Teaser](./images/teaser.png)
+
+</div>
+
+## Overview
+
+**Event2Vector** is a framework for learning representations of discrete event sequences. Inspired by the geometric structures found in neural representations, this model uses a simple, additive recurrent structure to create composable and interpretable embeddings.
+
+## Key Concepts
+* **Linear Additive Hypothesis**: The core idea behind Event2Vector is that the representation of an event sequence can be modeled as the vector sum of the embeddings of its individual events. This allows for intuitive vector arithmetic, enabling the composition and decomposition of event trajectories.
+* **Euclidean and Hyperbolic Models**: Event2Vector is offered in two geometric variants:
+    * **Euclidean model**: Uses standard vector addition, providing a straightforward, flat geometry for event trajectories.
+    * **Hyperbolic model**: Employs Möbius addition, which is better suited for hierarchical data structures, as it can embed tree-like patterns with less distortion.
+
+For more details, check *Sulc A., Event2Vector: A Geometric Approach to Learning Composable Representations of Event Sequences*
+
+## Installation
+
+Install the package directly from PyPI:
+
+```bash
+pip install event2vector
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/sulcantonin/event2vec_public.git
+cd event2vec_public
+pip install .
+```
+
+
+## Brown Example
+Afeer installation, you can try to run Brown Part-of-Speech tagging example from the paper. 
+
+```bash
+python3 -m experiments.prepare_brown_data.py
+python3 -m experiments.train_brown_data.py
+python3 -m experiments.visualize_brown_corpus.py
+```
+
+## Quickstart (tiny synthetic dataset)
+
+The snippet below trains a small `EuclideanModel` on a toy event graph for a few epochs and prints an embedding for a short sequence. It runs in seconds on CPU.
+
+We have 5 events: `START, A, B, C, END` and we test if we add `START + A + C ~ C`. The example should be self contained for educational purposes, as the main interest is the loss function. 
+
+```python
+import random
+import torch
+import numpy as np
+from sklearn.decomposition import PCA
+import matplotlib.pyplot as plt
+
+# Reproducibility: fix all relevant seeds so results are stable across runs
+SEED = 42
+random.seed(SEED)                    # Python's RNG (used by get_sequences and shuffling)
+np.random.seed(SEED)                 # NumPy RNG (used by PCA and any NumPy ops)
+torch.manual_seed(SEED)              # Torch CPU RNG
+if torch.cuda.is_available():
+    torch.cuda.manual_seed_all(SEED) # Torch CUDA RNG (all devices)
+
+# Optional: prefer deterministic behavior in cuDNN (may have performance impact)
+torch.backends.cudnn.deterministic = True
+torch.backends.cudnn.benchmark = False
+
+# Expected results (for the tiny toy graph START→A/B→C→END):
+# - Training loss should decrease over epochs (with minor wobble due to randomness/dropout).
+# - The printed sequence embedding for [START, A, C] is a single 8-D vector (shape (1, 8)).
+# - Nearest tokens by cosine similarity to that sequence embedding should rank 'C' highest
+#   (since the encoder is additive and the last token is C), with 'END' somewhat aligned.
+# - The decoder's top-1 next-event probability from that state should be 'END' with high
+#   confidence (≈0.9+) because the toy transitions force C→END.
+# Visualization (below): a 2D PCA of token embeddings plus the sequence embedding should show
+# 'SEQ(START-A-C)' lying near the point labeled 'C'.
+
+from event2vector import EuclideanModel
+from event2vector.data import get_sequences
+
+# 1) Define a tiny state-transition toy dataset
+#    We model a simple Markovian process: START → (A or B) → C → END
+#    The model will learn to predict the next token and produce a sequence embedding
+#    by additive composition of token embeddings.
+event_types = ['START', 'A', 'B', 'C', 'END']
+event_transitions = {
+    'START': [('A', 0.5), ('B', 0.5)],
+    'A': [('C', 0.6), ('B', 0.4)],
+    'B': [('C', 0.7), ('A', 0.3)],
+    'C': [('END', 1.0)],
+}
+
+# 2) Generate synthetic sequences (reproducible thanks to the fixed seeds above)
+#    get_sequences returns: raw sequences, tensorized sequences, and vocab mappings.
+_, processed_sequences, event_2_idx, _ = get_sequences(
+    event_types=event_types,
+    event_transitions=event_transitions,
+    initial='START',
+    terminal='END',
+    num_seq=200,            # generate 200 short sequences
+    max_seq_length=6,       # keep them small for speed
+    generate_new=True,
+    prefix='tiny_quickstart'
+)
+
+# 3) Initialize model and optimizer
+#    EuclideanModel composes sequence representations via additive updates.
+device = 'cuda' if torch.cuda.is_available() else 'cpu'
+embedding_dim = 8
+model = EuclideanModel(num_event_types=len(event_types), embedding_dim=embedding_dim, dropout_p=0.1).to(device)
+loss_fn = torch.nn.CrossEntropyLoss()              # prediction loss (next-token)
+optimizer = torch.optim.AdamW(model.parameters(), lr=5e-3)
+lambda_reconstruction = 0.2                        # weight for reconstruction loss (h1 - e ≈ h_old)
+lambda_consistency = 0.2                           # weight for consistency loss (h1 ≈ h2)
+mse_loss = torch.nn.MSELoss()
+
+# 4) Minimal training loop
+#    Objective: next-token prediction with cross-entropy.
+#    We iterate tokens in each sequence and accumulate loss over (t → t+1) pairs.
+model.train()
+for epoch in range(128):
+    random.shuffle(processed_sequences)  # shuffling is deterministic given the fixed Python seed
+    total_loss = 0.0
+    for seq_tensor in processed_sequences:
+        if len(seq_tensor) < 2:
+            continue
+        # h is the running sequence representation; encoder adds current token embedding
+        h = torch.zeros((1, embedding_dim), device=device)
+        seq_tensor = seq_tensor.to(device)
+
+        sequence_loss = 0.0
+        for t in range(len(seq_tensor) - 1):
+            x = seq_tensor[t].unsqueeze(0)
+            target = seq_tensor[t + 1].unsqueeze(0)
+            # Brown pipeline: two forward passes from the same h_old to compute a consistency loss
+            h_old = h.detach()
+            y1, h1, e_curr1 = model(x, h_old)
+            y2, h2, e_curr2 = model(x, h_old)
+
+            # Prediction: next-token cross-entropy on the first pass
+            prediction_loss = loss_fn(y1.view(1, -1), target)
+
+            # Reconstruction: undo the additive step (h1 - e ≈ h_old)
+            h_reconstructed = h1 - e_curr1
+            reconstruction_loss = mse_loss(h_reconstructed, h_old)
+
+            # Consistency: two identical passes should produce similar states
+            consistency_loss = mse_loss(h1, h2)
+
+            combined = (prediction_loss +
+                        lambda_reconstruction * reconstruction_loss +
+                        lambda_consistency * consistency_loss)
+            sequence_loss = sequence_loss + combined
+
+            # Advance hidden state using the first pass
+            h = h1.detach()
+
+        if (len(seq_tensor) - 1) > 0:
+            avg_seq_loss = sequence_loss / (len(seq_tensor) - 1)
+            optimizer.zero_grad()
+            avg_seq_loss.backward()
+            optimizer.step()
+            total_loss += avg_seq_loss.item()
+
+    print(f"epoch {epoch + 1}: loss={total_loss / max(1, len(processed_sequences)):.4f}")
+
+# 5) Use the learned representation for a short sequence
+#    We encode [START, A, C] step-by-step; the final h is the sequence embedding.
+model.eval()
+with torch.no_grad():
+    seq = torch.tensor([
+        event_2_idx['START'], event_2_idx['A'], event_2_idx['C']
+    ], device=device)
+    h = torch.zeros((1, embedding_dim), device=device)
+    for idx in seq:
+        _, h, _ = model(idx.unsqueeze(0), h)
+    print('Sequence embedding (START-A-C):', h.cpu().numpy())
+
+
+with torch.no_grad():
+    # 6) Qualitative check: nearest tokens to the sequence embedding by cosine similarity
+    #    Expect 'C' to be nearest (last consumed token) and 'END' reasonably aligned.
+    emb = model.embedding.weight.detach()                  # [V, 8]
+    h_norm = torch.nn.functional.normalize(h, dim=1)
+    emb_norm = torch.nn.functional.normalize(emb, dim=1)
+    sims = (emb_norm @ h_norm.squeeze(0))
+    top_sim = torch.topk(sims, k=3)
+    print('Nearest tokens by cosine:', [ (list(event_2_idx.keys())[i], float(sims[i])) for i in top_sim.indices ])
+
+with torch.no_grad():
+    # 7) Next-event distribution from the current state
+    #    Expect 'END' to be top-1 with high probability because C→END with p=1.0
+    logits = model.decoder(h)                              # [1, V]
+    probs = torch.softmax(logits, dim=-1).squeeze(0)
+    top = torch.topk(probs, k=3)
+    inv = {v:k for k,v in event_2_idx.items()}
+    print('Top-3 next events:', [ (inv[i.item()], float(probs[i])) for i in top.indices ])
+
+# 8) Visualization: PCA of token embeddings + sequence embedding
+#    Expect the red star (sequence) to lie near the point labeled 'C'.
+with torch.no_grad():
+    token_emb = model.embedding.weight.detach().cpu().numpy()   # [V, 8]
+    seq_emb = h.detach().cpu().numpy()                           # [1, 8]
+    X = np.vstack([token_emb, seq_emb])
+    pca = PCA(n_components=2, random_state=SEED)
+    X2 = pca.fit_transform(X)
+    tokens2, seq2 = X2[:-1], X2[-1]
+
+inv = {v:k for k,v in event_2_idx.items()}
+plt.figure(figsize=(6, 6))
+plt.scatter(tokens2[:, 0], tokens2[:, 1], c='gray', label='tokens')
+for i, (x, y) in enumerate(tokens2):
+    plt.text(x + 0.02, y + 0.02, inv[i], fontsize=9)
+plt.scatter([seq2[0]], [seq2[1]], c='red', marker='*', s=160, label='SEQ(START-A-C)')
+plt.title('PCA: token embeddings + sequence embedding (expect SEQ near C)')
+plt.legend(loc='best')
+plt.tight_layout()
+plt.show()
+```
+
+## References
+For citations please use following Bibtex. 
+```bibtex
+@article{sulc2025event2vec,
+  title={Event2Vector: A Geometric Approach to Learning Composable Representations of Event Sequences},
+  author={Sulc, Antonin},
+  journal={arXiv preprint arXiv:2509.12188},
+  year={2025}
+}
+```

event2vector-0.1.0/README.md

@@ -0,0 +1,240 @@
+<div align="center">
+
+# Event2Vector
+## A Geometric Approach to Learning Composable Representations of Event Sequences
+
+[![PyPI version](https://badge.fury.io/py/event2vector.svg)](https://badge.fury.io/py/event2vector)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.6+](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)
+[![arXiv](https://img.shields.io/badge/arXiv-2509.12188-b31b1b.svg)](https://arxiv.org/abs/2509.12188)
+
+![Teaser](./images/teaser.png)
+
+</div>
+
+## Overview
+
+**Event2Vector** is a framework for learning representations of discrete event sequences. Inspired by the geometric structures found in neural representations, this model uses a simple, additive recurrent structure to create composable and interpretable embeddings.
+
+## Key Concepts
+* **Linear Additive Hypothesis**: The core idea behind Event2Vector is that the representation of an event sequence can be modeled as the vector sum of the embeddings of its individual events. This allows for intuitive vector arithmetic, enabling the composition and decomposition of event trajectories.
+* **Euclidean and Hyperbolic Models**: Event2Vector is offered in two geometric variants:
+    * **Euclidean model**: Uses standard vector addition, providing a straightforward, flat geometry for event trajectories.
+    * **Hyperbolic model**: Employs Möbius addition, which is better suited for hierarchical data structures, as it can embed tree-like patterns with less distortion.
+
+For more details, check *Sulc A., Event2Vector: A Geometric Approach to Learning Composable Representations of Event Sequences*
+
+## Installation
+
+Install the package directly from PyPI:
+
+```bash
+pip install event2vector
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/sulcantonin/event2vec_public.git
+cd event2vec_public
+pip install .
+```
+
+
+## Brown Example
+Afeer installation, you can try to run Brown Part-of-Speech tagging example from the paper. 
+
+```bash
+python3 -m experiments.prepare_brown_data.py
+python3 -m experiments.train_brown_data.py
+python3 -m experiments.visualize_brown_corpus.py
+```
+
+## Quickstart (tiny synthetic dataset)
+
+The snippet below trains a small `EuclideanModel` on a toy event graph for a few epochs and prints an embedding for a short sequence. It runs in seconds on CPU.
+
+We have 5 events: `START, A, B, C, END` and we test if we add `START + A + C ~ C`. The example should be self contained for educational purposes, as the main interest is the loss function. 
+
+```python
+import random
+import torch
+import numpy as np
+from sklearn.decomposition import PCA
+import matplotlib.pyplot as plt
+
+# Reproducibility: fix all relevant seeds so results are stable across runs
+SEED = 42
+random.seed(SEED)                    # Python's RNG (used by get_sequences and shuffling)
+np.random.seed(SEED)                 # NumPy RNG (used by PCA and any NumPy ops)
+torch.manual_seed(SEED)              # Torch CPU RNG
+if torch.cuda.is_available():
+    torch.cuda.manual_seed_all(SEED) # Torch CUDA RNG (all devices)
+
+# Optional: prefer deterministic behavior in cuDNN (may have performance impact)
+torch.backends.cudnn.deterministic = True
+torch.backends.cudnn.benchmark = False
+
+# Expected results (for the tiny toy graph START→A/B→C→END):
+# - Training loss should decrease over epochs (with minor wobble due to randomness/dropout).
+# - The printed sequence embedding for [START, A, C] is a single 8-D vector (shape (1, 8)).
+# - Nearest tokens by cosine similarity to that sequence embedding should rank 'C' highest
+#   (since the encoder is additive and the last token is C), with 'END' somewhat aligned.
+# - The decoder's top-1 next-event probability from that state should be 'END' with high
+#   confidence (≈0.9+) because the toy transitions force C→END.
+# Visualization (below): a 2D PCA of token embeddings plus the sequence embedding should show
+# 'SEQ(START-A-C)' lying near the point labeled 'C'.
+
+from event2vector import EuclideanModel
+from event2vector.data import get_sequences
+
+# 1) Define a tiny state-transition toy dataset
+#    We model a simple Markovian process: START → (A or B) → C → END
+#    The model will learn to predict the next token and produce a sequence embedding
+#    by additive composition of token embeddings.
+event_types = ['START', 'A', 'B', 'C', 'END']
+event_transitions = {
+    'START': [('A', 0.5), ('B', 0.5)],
+    'A': [('C', 0.6), ('B', 0.4)],
+    'B': [('C', 0.7), ('A', 0.3)],
+    'C': [('END', 1.0)],
+}
+
+# 2) Generate synthetic sequences (reproducible thanks to the fixed seeds above)
+#    get_sequences returns: raw sequences, tensorized sequences, and vocab mappings.
+_, processed_sequences, event_2_idx, _ = get_sequences(
+    event_types=event_types,
+    event_transitions=event_transitions,
+    initial='START',
+    terminal='END',
+    num_seq=200,            # generate 200 short sequences
+    max_seq_length=6,       # keep them small for speed
+    generate_new=True,
+    prefix='tiny_quickstart'
+)
+
+# 3) Initialize model and optimizer
+#    EuclideanModel composes sequence representations via additive updates.
+device = 'cuda' if torch.cuda.is_available() else 'cpu'
+embedding_dim = 8
+model = EuclideanModel(num_event_types=len(event_types), embedding_dim=embedding_dim, dropout_p=0.1).to(device)
+loss_fn = torch.nn.CrossEntropyLoss()              # prediction loss (next-token)
+optimizer = torch.optim.AdamW(model.parameters(), lr=5e-3)
+lambda_reconstruction = 0.2                        # weight for reconstruction loss (h1 - e ≈ h_old)
+lambda_consistency = 0.2                           # weight for consistency loss (h1 ≈ h2)
+mse_loss = torch.nn.MSELoss()
+
+# 4) Minimal training loop
+#    Objective: next-token prediction with cross-entropy.
+#    We iterate tokens in each sequence and accumulate loss over (t → t+1) pairs.
+model.train()
+for epoch in range(128):
+    random.shuffle(processed_sequences)  # shuffling is deterministic given the fixed Python seed
+    total_loss = 0.0
+    for seq_tensor in processed_sequences:
+        if len(seq_tensor) < 2:
+            continue
+        # h is the running sequence representation; encoder adds current token embedding
+        h = torch.zeros((1, embedding_dim), device=device)
+        seq_tensor = seq_tensor.to(device)
+
+        sequence_loss = 0.0
+        for t in range(len(seq_tensor) - 1):
+            x = seq_tensor[t].unsqueeze(0)
+            target = seq_tensor[t + 1].unsqueeze(0)
+            # Brown pipeline: two forward passes from the same h_old to compute a consistency loss
+            h_old = h.detach()
+            y1, h1, e_curr1 = model(x, h_old)
+            y2, h2, e_curr2 = model(x, h_old)
+
+            # Prediction: next-token cross-entropy on the first pass
+            prediction_loss = loss_fn(y1.view(1, -1), target)
+
+            # Reconstruction: undo the additive step (h1 - e ≈ h_old)
+            h_reconstructed = h1 - e_curr1
+            reconstruction_loss = mse_loss(h_reconstructed, h_old)
+
+            # Consistency: two identical passes should produce similar states
+            consistency_loss = mse_loss(h1, h2)
+
+            combined = (prediction_loss +
+                        lambda_reconstruction * reconstruction_loss +
+                        lambda_consistency * consistency_loss)
+            sequence_loss = sequence_loss + combined
+
+            # Advance hidden state using the first pass
+            h = h1.detach()
+
+        if (len(seq_tensor) - 1) > 0:
+            avg_seq_loss = sequence_loss / (len(seq_tensor) - 1)
+            optimizer.zero_grad()
+            avg_seq_loss.backward()
+            optimizer.step()
+            total_loss += avg_seq_loss.item()
+
+    print(f"epoch {epoch + 1}: loss={total_loss / max(1, len(processed_sequences)):.4f}")
+
+# 5) Use the learned representation for a short sequence
+#    We encode [START, A, C] step-by-step; the final h is the sequence embedding.
+model.eval()
+with torch.no_grad():
+    seq = torch.tensor([
+        event_2_idx['START'], event_2_idx['A'], event_2_idx['C']
+    ], device=device)
+    h = torch.zeros((1, embedding_dim), device=device)
+    for idx in seq:
+        _, h, _ = model(idx.unsqueeze(0), h)
+    print('Sequence embedding (START-A-C):', h.cpu().numpy())
+
+
+with torch.no_grad():
+    # 6) Qualitative check: nearest tokens to the sequence embedding by cosine similarity
+    #    Expect 'C' to be nearest (last consumed token) and 'END' reasonably aligned.
+    emb = model.embedding.weight.detach()                  # [V, 8]
+    h_norm = torch.nn.functional.normalize(h, dim=1)
+    emb_norm = torch.nn.functional.normalize(emb, dim=1)
+    sims = (emb_norm @ h_norm.squeeze(0))
+    top_sim = torch.topk(sims, k=3)
+    print('Nearest tokens by cosine:', [ (list(event_2_idx.keys())[i], float(sims[i])) for i in top_sim.indices ])
+
+with torch.no_grad():
+    # 7) Next-event distribution from the current state
+    #    Expect 'END' to be top-1 with high probability because C→END with p=1.0
+    logits = model.decoder(h)                              # [1, V]
+    probs = torch.softmax(logits, dim=-1).squeeze(0)
+    top = torch.topk(probs, k=3)
+    inv = {v:k for k,v in event_2_idx.items()}
+    print('Top-3 next events:', [ (inv[i.item()], float(probs[i])) for i in top.indices ])
+
+# 8) Visualization: PCA of token embeddings + sequence embedding
+#    Expect the red star (sequence) to lie near the point labeled 'C'.
+with torch.no_grad():
+    token_emb = model.embedding.weight.detach().cpu().numpy()   # [V, 8]
+    seq_emb = h.detach().cpu().numpy()                           # [1, 8]
+    X = np.vstack([token_emb, seq_emb])
+    pca = PCA(n_components=2, random_state=SEED)
+    X2 = pca.fit_transform(X)
+    tokens2, seq2 = X2[:-1], X2[-1]
+
+inv = {v:k for k,v in event_2_idx.items()}
+plt.figure(figsize=(6, 6))
+plt.scatter(tokens2[:, 0], tokens2[:, 1], c='gray', label='tokens')
+for i, (x, y) in enumerate(tokens2):
+    plt.text(x + 0.02, y + 0.02, inv[i], fontsize=9)
+plt.scatter([seq2[0]], [seq2[1]], c='red', marker='*', s=160, label='SEQ(START-A-C)')
+plt.title('PCA: token embeddings + sequence embedding (expect SEQ near C)')
+plt.legend(loc='best')
+plt.tight_layout()
+plt.show()
+```
+
+## References
+For citations please use following Bibtex. 
+```bibtex
+@article{sulc2025event2vec,
+  title={Event2Vector: A Geometric Approach to Learning Composable Representations of Event Sequences},
+  author={Sulc, Antonin},
+  journal={arXiv preprint arXiv:2509.12188},
+  year={2025}
+}
+```

event2vector-0.1.0/event2vector/__init__.py

@@ -0,0 +1,4 @@
+from .models import EuclideanModel, HyperbolicModel, HyperbolicUtils
+from .data import generate_sequences, get_sequences
+
+

event2vector-0.1.0/event2vector/data.py

@@ -0,0 +1,52 @@
+import random
+import torch
+import pickle
+
+def generate_sequences(event_types, event_transitions, initial, terminal, num_seq, max_length):
+    """
+    Generates synthetic sequences of events based on a state transition graph.
+    This function simulates realistic life trajectories by performing a guided
+    random walk on the graph.
+    """
+    sequences = []
+    for _ in range(num_seq):
+        seq = [initial]
+        while seq[-1] != terminal and len(seq) < max_length:
+            current_event = seq[-1]
+            transitions = event_transitions.get(current_event, [])
+            if not transitions or random.random() < 0.1:
+                next_event = random.choice([e for e in event_types if e != current_event])
+            else:
+                events, probs = zip(*transitions)
+                next_event = random.choices(events, weights=probs, k=1)[0]
+            seq.append(next_event)
+        if seq[-1] != terminal:
+            seq.append(terminal)
+        sequences.append(seq)
+    return sequences
+
+
+def get_sequences(event_types, event_transitions, initial, terminal, num_seq, max_seq_length, generate_new, prefix):
+    """
+    Generates and preprocesses sequences for synthetic data, or loads them from a file.
+    """
+    data_file = f'{prefix}_training_data.pkl'
+    if generate_new:
+        event_2_idx = {event: idx for idx, event in enumerate(event_types)}
+        idx_2_event = {idx: event for idx, event in enumerate(event_types)}
+        sequences = generate_sequences(event_types, event_transitions, initial, terminal, num_seq, max_seq_length)
+        processed_sequences = [torch.tensor([event_2_idx[s] for s in seq], dtype=torch.long) for seq in sequences]
+        with open(data_file, 'wb') as f:
+            pickle.dump({'sequences': sequences,
+                         'processed_sequences': processed_sequences,
+                         'event_2_idx': event_2_idx,
+                         'idx_2_event': idx_2_event}, f)
+    else:
+        with open(data_file, 'rb') as f:
+            data = pickle.load(f)
+        sequences = data['sequences']
+        processed_sequences = data['processed_sequences']
+        event_2_idx = data['event_2_idx']
+        idx_2_event = data['idx_2_event']
+    return sequences, processed_sequences, event_2_idx, idx_2_event
+

event2vector-0.1.0/event2vector/models.py

@@ -0,0 +1,120 @@
+import torch
+import torch.nn as nn
+
+EPS = 1e-5  # Small constant for numerical stability of hyperbolic space
+
+
+class EuclideanModel(nn.Module):
+    """
+    A recurrent model for learning event sequence representations in Euclidean space.
+    The model uses a simple additive update rule, where the representation of a
+    sequence is the sum of its constituent event embeddings.
+    """
+
+    def __init__(self, num_event_types, embedding_dim, dropout_p=0.2, max_norm=10.0):
+        super(EuclideanModel, self).__init__()
+        self.embedding_dim = embedding_dim
+        self.max_norm = max_norm
+        self.embedding = nn.Embedding(num_event_types, embedding_dim)
+        self.dropout = nn.Dropout(p=dropout_p)
+        self.linear_dec = nn.Linear(embedding_dim, num_event_types)
+
+    def encoder(self, x, h=None, clipping=True):
+        if h is None:
+            h = torch.zeros((x.shape[0], self.embedding_dim), device=x.device)
+        e = self.embedding(x)
+        h_next = self.dropout(e + h)
+
+        if clipping:
+            norm = torch.norm(h_next, p=2, dim=1, keepdim=True)
+            clip_coef = self.max_norm / (norm + 1e-6)
+            clip_coef = torch.min(clip_coef, torch.ones_like(clip_coef))
+            h_next = h_next * clip_coef
+
+        return h_next, e
+
+    def decoder(self, h):
+        return self.linear_dec(h)
+
+    def forward(self, x, h=None):
+        h, e = self.encoder(x, h)
+        return self.decoder(h), h, e
+
+
+class HyperbolicUtils:
+    """A collection of static methods for operations in the Poincaré Ball model."""
+
+    @staticmethod
+    def mobius_add(x, y, c):
+        x2 = torch.sum(x * x, dim=-1, keepdim=True)
+        y2 = torch.sum(y * y, dim=-1, keepdim=True)
+        xy = torch.sum(x * y, dim=-1, keepdim=True)
+        num = (1 + 2 * c * xy + c * y2) * x + (1 - c * x2) * y
+        den = 1 + 2 * c * xy + c**2 * x2 * y2
+        return num / (den + EPS)
+
+    @staticmethod
+    def log_map_origin(y, c):
+        sqrt_c = c**0.5
+        y_norm = torch.norm(y, p=2, dim=-1, keepdim=True).clamp_min(EPS)
+        artanh_arg = (sqrt_c * y_norm).clamp(max=1.0 - EPS)
+        log_map = (1. / sqrt_c) * (0.5 * torch.log((1 + artanh_arg) / (1 - artanh_arg))) * (y / y_norm)
+        return log_map
+
+    @staticmethod
+    def poincare_dist_sq(x, y, c):
+        sqrt_c = c**0.5
+        mob_add_res = HyperbolicUtils.mobius_add(-x, y, c)
+        mob_add_norm = torch.norm(mob_add_res, p=2, dim=-1, keepdim=True).clamp_min(EPS)
+        artanh_arg = (sqrt_c * mob_add_norm).clamp(max=1.0 - EPS)
+        dist = (2. / sqrt_c) * (0.5 * torch.log((1 + artanh_arg) / (1 - artanh_arg)))
+        return dist.pow(2)
+
+    @staticmethod
+    def project_to_ball(x, c):
+        max_norm = 1.0 / (c**0.5)
+        norm = torch.norm(x, p=2, dim=-1, keepdim=True)
+        cond = norm >= max_norm
+        projected_x = torch.where(cond, x / (norm + EPS) * (max_norm - EPS), x)
+        return projected_x
+
+
+class HyperbolicModel(nn.Module):
+    """
+    A recurrent model for learning event sequence representations in Hyperbolic space.
+    This model is well-suited for hierarchical data, as the geometry of hyperbolic
+    space can embed tree-like structures with low distortion.
+    """
+
+    def __init__(self, num_event_types, embedding_dim, dropout_p, c=1.0):
+        super(HyperbolicModel, self).__init__()
+        self.embedding_dim = embedding_dim
+        self.c = c
+        self.embedding = nn.Embedding(num_event_types, embedding_dim)
+        self.embedding.weight.data.uniform_(-0.001, 0.001)
+        self.dropout = nn.Dropout(p=dropout_p)
+        self.linear_dec = nn.Linear(embedding_dim, num_event_types)
+
+    def project_embeddings(self):
+        with torch.no_grad():
+            self.embedding.weight.data = HyperbolicUtils.project_to_ball(
+                self.embedding.weight.data, self.c
+            )
+
+    def encoder(self, x, h):
+        e = self.embedding(x)
+        e_dropped = self.dropout(e)
+        h_next = HyperbolicUtils.mobius_add(h, e_dropped, self.c)
+        h_next = HyperbolicUtils.project_to_ball(h_next, self.c)
+        return h_next, e
+
+    def decoder(self, h):
+        h_tangent = HyperbolicUtils.log_map_origin(h, self.c)
+        return self.linear_dec(h_tangent)
+
+    def forward(self, x, h=None):
+        if h is None:
+            h = torch.zeros((x.shape[0], self.embedding_dim), device=x.device)
+        h_next, e = self.encoder(x, h)
+        return self.decoder(h_next), h_next, e
+

event2vector-0.1.0/event2vector.egg-info/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: event2vector
+Version: 0.1.0
+Summary: A geometric approach to learning composable representations of event sequences.
+Author: Antonin Sulc
+License: MIT
+Project-URL: Homepage, https://github.com/sulcantonin/event2vec_public
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: torch
+Requires-Dist: numpy
+Requires-Dist: tqdm
+Requires-Dist: matplotlib
+Requires-Dist: scikit-learn
+Requires-Dist: openTSNE
+Requires-Dist: gensim
+Requires-Dist: seaborn
+Dynamic: requires-python
+
+<div align="center">
+
+# Event2Vector
+## A Geometric Approach to Learning Composable Representations of Event Sequences
+
+[![PyPI version](https://badge.fury.io/py/event2vector.svg)](https://badge.fury.io/py/event2vector)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.6+](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/)
+[![arXiv](https://img.shields.io/badge/arXiv-2509.12188-b31b1b.svg)](https://arxiv.org/abs/2509.12188)
+
+![Teaser](./images/teaser.png)
+
+</div>
+
+## Overview
+
+**Event2Vector** is a framework for learning representations of discrete event sequences. Inspired by the geometric structures found in neural representations, this model uses a simple, additive recurrent structure to create composable and interpretable embeddings.
+
+## Key Concepts
+* **Linear Additive Hypothesis**: The core idea behind Event2Vector is that the representation of an event sequence can be modeled as the vector sum of the embeddings of its individual events. This allows for intuitive vector arithmetic, enabling the composition and decomposition of event trajectories.
+* **Euclidean and Hyperbolic Models**: Event2Vector is offered in two geometric variants:
+    * **Euclidean model**: Uses standard vector addition, providing a straightforward, flat geometry for event trajectories.
+    * **Hyperbolic model**: Employs Möbius addition, which is better suited for hierarchical data structures, as it can embed tree-like patterns with less distortion.
+
+For more details, check *Sulc A., Event2Vector: A Geometric Approach to Learning Composable Representations of Event Sequences*
+
+## Installation
+
+Install the package directly from PyPI:
+
+```bash
+pip install event2vector
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/sulcantonin/event2vec_public.git
+cd event2vec_public
+pip install .
+```
+
+
+## Brown Example
+Afeer installation, you can try to run Brown Part-of-Speech tagging example from the paper. 
+
+```bash
+python3 -m experiments.prepare_brown_data.py
+python3 -m experiments.train_brown_data.py
+python3 -m experiments.visualize_brown_corpus.py
+```
+
+## Quickstart (tiny synthetic dataset)
+
+The snippet below trains a small `EuclideanModel` on a toy event graph for a few epochs and prints an embedding for a short sequence. It runs in seconds on CPU.
+
+We have 5 events: `START, A, B, C, END` and we test if we add `START + A + C ~ C`. The example should be self contained for educational purposes, as the main interest is the loss function. 
+
+```python
+import random
+import torch
+import numpy as np
+from sklearn.decomposition import PCA
+import matplotlib.pyplot as plt
+
+# Reproducibility: fix all relevant seeds so results are stable across runs
+SEED = 42
+random.seed(SEED)                    # Python's RNG (used by get_sequences and shuffling)
+np.random.seed(SEED)                 # NumPy RNG (used by PCA and any NumPy ops)
+torch.manual_seed(SEED)              # Torch CPU RNG
+if torch.cuda.is_available():
+    torch.cuda.manual_seed_all(SEED) # Torch CUDA RNG (all devices)
+
+# Optional: prefer deterministic behavior in cuDNN (may have performance impact)
+torch.backends.cudnn.deterministic = True
+torch.backends.cudnn.benchmark = False
+
+# Expected results (for the tiny toy graph START→A/B→C→END):
+# - Training loss should decrease over epochs (with minor wobble due to randomness/dropout).
+# - The printed sequence embedding for [START, A, C] is a single 8-D vector (shape (1, 8)).
+# - Nearest tokens by cosine similarity to that sequence embedding should rank 'C' highest
+#   (since the encoder is additive and the last token is C), with 'END' somewhat aligned.
+# - The decoder's top-1 next-event probability from that state should be 'END' with high
+#   confidence (≈0.9+) because the toy transitions force C→END.
+# Visualization (below): a 2D PCA of token embeddings plus the sequence embedding should show
+# 'SEQ(START-A-C)' lying near the point labeled 'C'.
+
+from event2vector import EuclideanModel
+from event2vector.data import get_sequences
+
+# 1) Define a tiny state-transition toy dataset
+#    We model a simple Markovian process: START → (A or B) → C → END
+#    The model will learn to predict the next token and produce a sequence embedding
+#    by additive composition of token embeddings.
+event_types = ['START', 'A', 'B', 'C', 'END']
+event_transitions = {
+    'START': [('A', 0.5), ('B', 0.5)],
+    'A': [('C', 0.6), ('B', 0.4)],
+    'B': [('C', 0.7), ('A', 0.3)],
+    'C': [('END', 1.0)],
+}
+
+# 2) Generate synthetic sequences (reproducible thanks to the fixed seeds above)
+#    get_sequences returns: raw sequences, tensorized sequences, and vocab mappings.
+_, processed_sequences, event_2_idx, _ = get_sequences(
+    event_types=event_types,
+    event_transitions=event_transitions,
+    initial='START',
+    terminal='END',
+    num_seq=200,            # generate 200 short sequences
+    max_seq_length=6,       # keep them small for speed
+    generate_new=True,
+    prefix='tiny_quickstart'
+)
+
+# 3) Initialize model and optimizer
+#    EuclideanModel composes sequence representations via additive updates.
+device = 'cuda' if torch.cuda.is_available() else 'cpu'
+embedding_dim = 8
+model = EuclideanModel(num_event_types=len(event_types), embedding_dim=embedding_dim, dropout_p=0.1).to(device)
+loss_fn = torch.nn.CrossEntropyLoss()              # prediction loss (next-token)
+optimizer = torch.optim.AdamW(model.parameters(), lr=5e-3)
+lambda_reconstruction = 0.2                        # weight for reconstruction loss (h1 - e ≈ h_old)
+lambda_consistency = 0.2                           # weight for consistency loss (h1 ≈ h2)
+mse_loss = torch.nn.MSELoss()
+
+# 4) Minimal training loop
+#    Objective: next-token prediction with cross-entropy.
+#    We iterate tokens in each sequence and accumulate loss over (t → t+1) pairs.
+model.train()
+for epoch in range(128):
+    random.shuffle(processed_sequences)  # shuffling is deterministic given the fixed Python seed
+    total_loss = 0.0
+    for seq_tensor in processed_sequences:
+        if len(seq_tensor) < 2:
+            continue
+        # h is the running sequence representation; encoder adds current token embedding
+        h = torch.zeros((1, embedding_dim), device=device)
+        seq_tensor = seq_tensor.to(device)
+
+        sequence_loss = 0.0
+        for t in range(len(seq_tensor) - 1):
+            x = seq_tensor[t].unsqueeze(0)
+            target = seq_tensor[t + 1].unsqueeze(0)
+            # Brown pipeline: two forward passes from the same h_old to compute a consistency loss
+            h_old = h.detach()
+            y1, h1, e_curr1 = model(x, h_old)
+            y2, h2, e_curr2 = model(x, h_old)
+
+            # Prediction: next-token cross-entropy on the first pass
+            prediction_loss = loss_fn(y1.view(1, -1), target)
+
+            # Reconstruction: undo the additive step (h1 - e ≈ h_old)
+            h_reconstructed = h1 - e_curr1
+            reconstruction_loss = mse_loss(h_reconstructed, h_old)
+
+            # Consistency: two identical passes should produce similar states
+            consistency_loss = mse_loss(h1, h2)
+
+            combined = (prediction_loss +
+                        lambda_reconstruction * reconstruction_loss +
+                        lambda_consistency * consistency_loss)
+            sequence_loss = sequence_loss + combined
+
+            # Advance hidden state using the first pass
+            h = h1.detach()
+
+        if (len(seq_tensor) - 1) > 0:
+            avg_seq_loss = sequence_loss / (len(seq_tensor) - 1)
+            optimizer.zero_grad()
+            avg_seq_loss.backward()
+            optimizer.step()
+            total_loss += avg_seq_loss.item()
+
+    print(f"epoch {epoch + 1}: loss={total_loss / max(1, len(processed_sequences)):.4f}")
+
+# 5) Use the learned representation for a short sequence
+#    We encode [START, A, C] step-by-step; the final h is the sequence embedding.
+model.eval()
+with torch.no_grad():
+    seq = torch.tensor([
+        event_2_idx['START'], event_2_idx['A'], event_2_idx['C']
+    ], device=device)
+    h = torch.zeros((1, embedding_dim), device=device)
+    for idx in seq:
+        _, h, _ = model(idx.unsqueeze(0), h)
+    print('Sequence embedding (START-A-C):', h.cpu().numpy())
+
+
+with torch.no_grad():
+    # 6) Qualitative check: nearest tokens to the sequence embedding by cosine similarity
+    #    Expect 'C' to be nearest (last consumed token) and 'END' reasonably aligned.
+    emb = model.embedding.weight.detach()                  # [V, 8]
+    h_norm = torch.nn.functional.normalize(h, dim=1)
+    emb_norm = torch.nn.functional.normalize(emb, dim=1)
+    sims = (emb_norm @ h_norm.squeeze(0))
+    top_sim = torch.topk(sims, k=3)
+    print('Nearest tokens by cosine:', [ (list(event_2_idx.keys())[i], float(sims[i])) for i in top_sim.indices ])
+
+with torch.no_grad():
+    # 7) Next-event distribution from the current state
+    #    Expect 'END' to be top-1 with high probability because C→END with p=1.0
+    logits = model.decoder(h)                              # [1, V]
+    probs = torch.softmax(logits, dim=-1).squeeze(0)
+    top = torch.topk(probs, k=3)
+    inv = {v:k for k,v in event_2_idx.items()}
+    print('Top-3 next events:', [ (inv[i.item()], float(probs[i])) for i in top.indices ])
+
+# 8) Visualization: PCA of token embeddings + sequence embedding
+#    Expect the red star (sequence) to lie near the point labeled 'C'.
+with torch.no_grad():
+    token_emb = model.embedding.weight.detach().cpu().numpy()   # [V, 8]
+    seq_emb = h.detach().cpu().numpy()                           # [1, 8]
+    X = np.vstack([token_emb, seq_emb])
+    pca = PCA(n_components=2, random_state=SEED)
+    X2 = pca.fit_transform(X)
+    tokens2, seq2 = X2[:-1], X2[-1]
+
+inv = {v:k for k,v in event_2_idx.items()}
+plt.figure(figsize=(6, 6))
+plt.scatter(tokens2[:, 0], tokens2[:, 1], c='gray', label='tokens')
+for i, (x, y) in enumerate(tokens2):
+    plt.text(x + 0.02, y + 0.02, inv[i], fontsize=9)
+plt.scatter([seq2[0]], [seq2[1]], c='red', marker='*', s=160, label='SEQ(START-A-C)')
+plt.title('PCA: token embeddings + sequence embedding (expect SEQ near C)')
+plt.legend(loc='best')
+plt.tight_layout()
+plt.show()
+```
+
+## References
+For citations please use following Bibtex. 
+```bibtex
+@article{sulc2025event2vec,
+  title={Event2Vector: A Geometric Approach to Learning Composable Representations of Event Sequences},
+  author={Sulc, Antonin},
+  journal={arXiv preprint arXiv:2509.12188},
+  year={2025}
+}
+```

event2vector-0.1.0/event2vector.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+event2vector/__init__.py
+event2vector/data.py
+event2vector/models.py
+event2vector.egg-info/PKG-INFO
+event2vector.egg-info/SOURCES.txt
+event2vector.egg-info/dependency_links.txt
+event2vector.egg-info/requires.txt
+event2vector.egg-info/top_level.txt

event2vector-0.1.0/event2vector.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

event2vector-0.1.0/event2vector.egg-info/requires.txt

@@ -0,0 +1,8 @@
+torch
+numpy
+tqdm
+matplotlib
+scikit-learn
+openTSNE
+gensim
+seaborn

event2vector-0.1.0/event2vector.egg-info/top_level.txt

@@ -0,0 +1 @@
+event2vector

event2vector-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "event2vector"
+
+version = "0.1.0"
+description = "A geometric approach to learning composable representations of event sequences."
+readme = "README.md"
+authors = [
+  { name = "Antonin Sulc" },
+]
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.6"
+dependencies = [
+    "torch",
+    "numpy",
+    "tqdm",
+    "matplotlib",
+    "scikit-learn",
+    "openTSNE",
+    "gensim",
+    "seaborn",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/sulcantonin/event2vec_public"

event2vector-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

event2vector-0.1.0/setup.py

@@ -0,0 +1,28 @@
+from setuptools import setup, find_packages
+
+setup(
+    name='event2vector',
+    version='0.1.0',
+    author='Antonin Sulc',
+    description='A geometric approach to learning composable representations of event sequences.',
+    long_description=open('README.md').read(),
+    long_description_content_type='text/markdown',
+    packages=find_packages(),
+    install_requires=[
+        'torch',
+        'numpy',
+        'tqdm',
+        'matplotlib',
+        'scikit-learn',
+        'openTSNE',
+        'gensim',
+        'seaborn'
+    ],
+    classifiers=[
+        'Programming Language :: Python :: 3',
+        'License :: OSI Approved :: MIT License',
+        'Operating System :: OS Independent',
+    ],
+    python_requires='>=3.6',
+)
+