Event-JEPA-Cube

A Python framework for processing long, irregular event sequences and multi-semantic entity relationships using Joint Embedding Predictive Architecture (JEPA) principles.

Event-JEPA-Cube addresses fundamental limitations of standard Transformer architectures — fixed context windows, quadratic memory scaling, and single-modality bias — by providing hierarchical temporal processing, multi-modal embedding support, and mathematically grounded regularization within a unified entity representation system.

All code lives under the sovereign namespace: https://github.com/josaum/jcube.

Project Goals

Process irregular event sequences at scale — Handle 5K-10K+ events with O(m log m) memory complexity, compared to O(n^2) in standard Transformers, using hierarchical temporal aggregation that respects irregular timestamps.
Unify multi-modal entity representations — Combine text, image, audio, sensor, and behavioral embeddings into a single entity representation (the "Embedding Cube") with cross-modal relationship discovery via cosine similarity.
Ground embeddings in theory — Implement eight regularizers from JEPA research published in 2025–2026. These target embedding shape, sparsity, covariance, scale, spectral health, temporal change, and multimodal correlation without relying on stop-gradients or EMA teachers.
Stay lightweight and extensible — Minimal runtime dependencies (PyArrow and DuckDB). PyTorch is optional (only needed for regularizers). Decorator-based plugin system for custom embeddings and models.

Installation

# Core library (PyArrow and DuckDB required)
pip install -e .

# With PyTorch for JEPA regularizers
pip install -e ".[torch]"

# Complete test and development dependencies
pip install -e ".[test]"

# Everything
pip install -e ".[all]"

Quick Start

from event_jepa_cube import EventJEPA, EventSequence

# 1. Create an event sequence with embeddings and timestamps
sequence = EventSequence(
    embeddings=[[0.1, 0.2, 0.3], [0.0, 0.1, 0.0], [0.2, 0.2, 0.2]], timestamps=[1.0, 2.0, 3.0], modality="text"
)

# 2. Process with hierarchical temporal aggregation
processor = EventJEPA(embedding_dim=3, num_levels=2, temporal_resolution="adaptive")
representation = processor.process(sequence)

# 3. Detect salient patterns (z-score thresholding)
patterns = processor.detect_patterns(representation)

# 4. Predict next events (trend-based extrapolation)
predictions = processor.predict_next(sequence, num_steps=3)

print("Representation:", representation)  # Temporally-weighted aggregate
print("Patterns:", patterns)  # Indices of salient dimensions
print("Predictions:", predictions)  # Next predicted embeddings

Run the included example:

python -m examples.basic_usage

Core Components

EventJEPA — Sequence Processor

Processes irregular event sequences through multi-level temporal windowing with exponential time-decay weighting.

from event_jepa_cube import EventJEPA, EventSequence

# Simulated user journey: browsing, idle, then purchase
sequence = EventSequence(
    embeddings=[
        [0.8, 0.1, 0.0],  # browse product A
        [0.7, 0.2, 0.1],  # browse product B
        [0.1, 0.0, 0.0],  # idle
        [0.2, 0.9, 0.8],  # add to cart
        [0.1, 0.8, 0.9],  # purchase
    ],
    timestamps=[1.0, 2.0, 50.0, 51.0, 52.0],  # note the irregular gap
    modality="behavior",
)

processor = EventJEPA(
    embedding_dim=3,
    num_levels=2,  # 2 hierarchical levels
    temporal_resolution="adaptive",  # split at natural timestamp gaps
)

# Process: groups [browse, browse] and [idle, cart, purchase] into
# separate windows based on the gap, aggregates with recency weighting,
# then merges at the next level.
representation = processor.process(sequence)

# Detect which embedding dimensions are most salient
salient_dims = processor.detect_patterns(representation)

# Predict next 3 events by exponentially-weighted trend extrapolation
next_events = processor.predict_next(sequence, num_steps=3)

How it works:

Parameter	Effect
`num_levels`	Number of hierarchical aggregation passes. Level 1 groups events into windows; level 2 merges windows; etc.
`temporal_resolution`	`"adaptive"`: splits at gaps > median inter-event interval. `"fixed"`: equal-width time bins.
Time-decay	Within each window, recent events get exponentially higher weight: `w_i = exp(-alpha * (t_max - t_i))`

EmbeddingCube — Entity Relationship Manager

Manages multi-semantic entities and discovers relationships through cosine similarity across shared embedding modalities.

from event_jepa_cube import EmbeddingCube, Entity

# Create entities with multi-modal embeddings
laptop = Entity(
    embeddings={
        "text": [0.9, 0.1, 0.0, 0.2],  # from product description
        "image": [0.3, 0.8, 0.1, 0.0],  # from product photo
        "behavior": [0.5, 0.5, 0.7, 0.1],  # from purchase patterns
    },
    hierarchy_info={"category": "electronics", "subcategory": "laptops"},
)

phone = Entity(
    embeddings={
        "text": [0.85, 0.15, 0.05, 0.18],  # similar text embedding
        "image": [0.2, 0.7, 0.2, 0.1],  # somewhat similar image
        "behavior": [0.6, 0.4, 0.8, 0.05],  # similar purchase pattern
    },
    hierarchy_info={"category": "electronics", "subcategory": "phones"},
)

headphones = Entity(
    embeddings={
        "text": [0.1, 0.0, 0.9, 0.8],  # very different text
        "audio": [0.5, 0.5, 0.5, 0.5],  # different modality entirely
    },
    hierarchy_info={"category": "electronics", "subcategory": "audio"},
)

cube = EmbeddingCube()
cube.add_entity(laptop)
cube.add_entity(phone)
cube.add_entity(headphones)

# Discover relationships (cosine similarity >= threshold)
relationships = cube.discover_relationships(entity_ids=[laptop.id], threshold=0.7)
# laptop <-> phone: high cosine similarity on shared modalities + hierarchy bonus
# laptop <-> headphones: only "text" is shared, low similarity — excluded

print(relationships)  # {laptop.id: [phone.id]}

Similarity computation:

Find shared embedding modalities between two entities
Compute cosine similarity per shared modality
Average across modalities
Add +0.1 bonus (capped at 1.0) if hierarchy_info["category"] matches
Include only if final similarity >= threshold

JEPA Regularizers

Event-JEPA-Cube implements eight regularizers from recent JEPA research that control embedding distribution, covariance, sparsity, scale, spectral health, temporal change, and multimodal correlation. These require PyTorch.

SIGReg — Sketched Isotropic Gaussian Regularization

From LeJEPA (arXiv:2511.08544). Enforces an isotropic Gaussian distribution on embeddings — proven to be the optimal distribution that minimizes worst-case downstream prediction risk.

How it works: Projects embeddings onto M random unit-norm directions, then compares each 1D projected distribution to N(0,1) using the Epps-Pulley characteristic function test via trapezoidal quadrature.

from event_jepa_cube.regularizers import SIGReg

sigreg = SIGReg(
    num_directions=64,  # M random projection directions
    sigma=1.0,  # Epps-Pulley weighting window
    num_quadrature_points=17,  # integration precision
)

# In your training loop:
embedding_batch = encoder(input_batch)  # (N, d) tensor
reg_loss = sigreg.compute_loss(embedding_batch)
total_loss = prediction_loss + 0.05 * reg_loss
total_loss.backward()

WeakSIGReg — Covariance Regularization

From Weak-SIGReg (arXiv:2603.05924). A computationally cheaper variant that targets only the covariance matrix (not the full characteristic function), suitable as a general training stabilizer for supervised settings.

from event_jepa_cube.regularizers import WeakSIGReg

weak = WeakSIGReg(sketch_dim=64)  # random sketch dimension K

# Loss = ||sketch(Cov(Z)) - sketch(I)||_F^2
reg_loss = weak.compute_loss(embedding_batch)

RDMReg — Rectified Distribution Matching

From Rectified LpJEPA (arXiv:2602.01456). Generalizes SIGReg by matching embeddings to a Rectified Generalized Gaussian (RGG) distribution, enabling explicit control over sparsity (up to 95% zero entries).

from event_jepa_cube.regularizers import RDMReg

rdmreg = RDMReg(
    p=2.0,  # distribution shape (2.0=Gaussian, 1.0=Laplacian)
    target_sparsity=0.5,  # 50% of entries will be zero
    num_projections=64,  # sliced Wasserstein projections
)

# Uses sliced 2-Wasserstein distance with ReLU rectification
reg_loss = rdmreg.compute_loss(embedding_batch)

NormReg — Representation-Norm Regularization

From BiJEPA (arXiv:2603.00049). Penalizes deviation of per-sample squared norms from the isotropic Gaussian expectation E[||z||^2] = d. Symmetric (bidirectional) prediction without a stop-gradient or EMA teacher admits "representation explosion" — both predictors inflate norms instead of learning structure. NormReg closes that escape (and the collapse-to-zero one) while leaving the distribution's shape to SIGReg-family regularizers.

from event_jepa_cube.regularizers import NormReg

normreg = NormReg(target_scale=1.0)  # target for ||z||^2 / d

# Loss = mean(( ||z||^2 / d - 1 )^2)
reg_loss = normreg.compute_loss(embedding_batch)

SACReg — Spectral Anti-Collapse Regularization

From λ-JEPA (arXiv:2609.35288). Applies mean, covariance-trace, and log-determinant penalties directly to the backbone representation used downstream. This addresses the projector/backbone mismatch: a healthy projected embedding does not guarantee a healthy backbone.

from event_jepa_cube.regularizers import SACReg

sacreg = SACReg(eps=1e-4)
backbone_loss = sacreg.compute_loss(backbone_embeddings)

SubSIGReg — Subspace Gaussian Regularization

From Sub-JEPA (arXiv:2605.09241). Applies SIGReg to frozen row-orthonormal subspaces rather than forcing the full latent space to be isotropic. This is useful when task-relevant structure has lower intrinsic dimensionality.

from event_jepa_cube.regularizers import SubSIGReg

subreg = SubSIGReg(num_subspaces=4, subspace_dim=16)
subspace_loss = subreg.compute_loss(embeddings)

Use effective_rank(embeddings) to compare representation geometries on training and validation data instead of assuming that higher rank is always better.

TemporalDifferenceReg — Motion-Aware Prediction

From MotionJEPA (arXiv:2609.23881). Adds an embedding-difference MSE to the usual next-state objective, so static predictions cannot look accurate when the target is changing.

from event_jepa_cube.regularizers import TemporalDifferenceReg

motion = TemporalDifferenceReg(delta_weight=1.0)
loss = motion.compute_loss(current, predicted_next, target_next)

CorrelatedSIGReg — Correlated Gaussian Targets

From MM-LeJEPA (arXiv:2610.24681). Matches full covariance to a target with cross-modal correlation rho, rather than forcing every dimension or modality to be independent.

from event_jepa_cube.regularizers import CorrelatedSIGReg

correlated = CorrelatedSIGReg(rho=0.5)
loss = correlated.compute_loss(joint_multimodal_embeddings)

Choosing a Regularizer

Regularizer	Use When	Complexity	Sparsity
SIGReg	Self-supervised pretraining, replacing stop-gradients/EMA	O(N * M)	Dense
WeakSIGReg	Supervised training stabilization, preventing collapse	O(N * K)	Dense
RDMReg	Need sparse/interpretable features (anomaly detection, efficient inference)	O(N * M * log N)	Controllable
NormReg	Symmetric/bidirectional prediction (BiJEPA); scale control alongside any of the above	O(N * d)	Dense
SACReg	Protecting the backbone used for downstream transfer	O(N * d + d³)	Spectral
SubSIGReg	Preserving low intrinsic dimensionality while preventing collapse	O(K * N * M)	Subspace
TemporalDifferenceReg	Motion-aware sequential prediction	O(N * T * D)	Dynamic
CorrelatedSIGReg	Learning correlated multimodal geometry	O(N * d²)	Correlated

Bidirectional Training — BiJEPATrainer

From BiJEPA (arXiv:2603.00049). Trains a forward predictor (context → target) and a mirrored backward predictor (target → context) jointly, with cycle-consistency losses g(f(ctx)) ≈ ctx and f(g(tgt)) ≈ tgt capturing the informative signal in the inverse relationship that uni-directional prediction discards.

from event_jepa_cube import BiJEPATrainer, MLPPredictor
from event_jepa_cube.regularizers import WeakSIGReg

forward = MLPPredictor(embedding_dim=768, context_length=5, num_steps=2)

trainer = BiJEPATrainer(
    forward,  # backward predictor auto-mirrored
    cycle_weight=1.0,  # weight of the two cycle-consistency terms
    norm_weight=0.01,  # NormReg against representation explosion
    regularizer=WeakSIGReg(),  # optional SIGReg-family term
)

history = trainer.train(sequences, epochs=100)
metrics = trainer.evaluate(sequences)  # forward_mse, backward_mse, cycle_mse, cosine_similarity

Integrated Usage

from event_jepa_cube import EventJEPA
from event_jepa_cube.regularizers import SIGReg

processor = EventJEPA(
    embedding_dim=768,
    num_levels=3,
    regularizer=SIGReg(num_directions=64),
    reg_weight=0.05,  # lambda balancing prediction vs regularization
)

# Combined loss: L = L_pred + 0.05 * L_SIGReg
total_loss = processor.compute_regularized_loss(embeddings, prediction_loss)

Extensibility

Custom Embedding Types

Register custom embedding processors via decorators:

from event_jepa_cube import register_embedding_type


@register_embedding_type("sensor")
class SensorEmbedding:
    def __init__(self, dim: int, sampling_rate: float):
        self.dim = dim
        self.sampling_rate = sampling_rate

    def encode(self, raw_signal):
        # Your encoding logic
        return embedding_vector

Custom Relationship Models

Register custom models for the EmbeddingCube:

from event_jepa_cube import register_model


@register_model("graph_attention")
class GraphAttentionModel:
    def __init__(self, input_dim, heads=4):
        self.input_dim = input_dim
        self.heads = heads

    def forward(self, entity_embeddings):
        # Your relationship modeling logic
        return attention_scores


# Load into a cube
cube.load_registered_model("graph_attention", input_dim=768, heads=4)

Architecture Overview

event_jepa_cube/
├── __init__.py          # Public API exports
├── sequence.py          # EventSequence & Entity dataclasses
├── event_jepa.py        # Hierarchical temporal processing and losses
├── embedding_cube.py    # Multi-semantic entity relationships
├── registry.py          # Decorator-based plugin registries
├── streaming.py         # Incremental processing and snapshots
├── training.py          # V-JEPA cooldown schedule
├── numpy_ops.py         # NumPy acceleration with stdlib fallbacks
├── regularizers.py      # Eight regularizers + effective-rank diagnostics
├── predictors.py        # MLP and Transformer predictors
├── bijepa.py            # Bidirectional cycle-consistent training
├── materializer.py      # DuckDB → temporal event sequences
├── digital_twin.py      # Warehouse profiling and metadata graphs
└── mycelia_store.py     # Vector storage, search, and Flight ingestion

Design Principles

Minimal runtime dependencies — The core library requires PyArrow and DuckDB. NumPy and PyTorch remain optional, keeping the API lightweight and portable.
Optional PyTorch — Regularizers live in a separate module with a graceful ImportError fallback. Install with pip install -e ".[torch]" when needed.
Dataclass-first — EventSequence and Entity are plain dataclasses with validation. No framework lock-in.
Plugin registries — @register_embedding_type and @register_model decorators allow extending the framework without modifying source code.

Theoretical Performance Characteristics

The figures below are architectural targets based on JEPA's structural advantages over token-based Transformers. They are not measured benchmarks of this library.

Metric	Token-Based Transformers	Event-JEPA-Cube	Why
Max Sequence Length	~2K-4K tokens	5K-10K+ events	Hierarchical windowing avoids full-sequence attention
Memory	O(n^2)	O(m log m)	Window-based aggregation, not pairwise attention
Modality Support	Single / forced fusion	Native multi-modal	Embedding Cube stores per-modality embeddings natively
Regularization	Stop-gradients, EMA, schedulers	Single SIGReg objective	Mathematically grounded (LeJEPA Theorem 4)

Industry Applications

Domain	Use Cases	Key Components
E-Commerce	User journey modeling, product recommendations, dynamic pricing	EventJEPA for session sequences, EmbeddingCube for product entities
Healthcare	Patient journey analysis, treatment optimization, readmission prediction	Multi-level temporal aggregation over irregular clinical events
Manufacturing / IoT	Predictive maintenance, anomaly detection, supply chain events	Sensor event sequences with adaptive temporal resolution
Security	Intrusion detection, access pattern analysis, fraud detection	RDMReg for sparse anomaly representations, pattern detection

Development

# Install complete test and development dependencies
pip install -e ".[test]"

# Run tests
pytest tests/ -v

# Lint and format
ruff check .
ruff format .

# Type check
mypy event_jepa_cube/ --ignore-missing-imports

CI runs these checks plus the test suite on Python 3.10, 3.11, and 3.12. A separate job installs .[all] and runs the complete PyTorch suite.

For a reproducible containerized test environment:

docker build -t event-jepa-cube .
docker run --rm event-jepa-cube

Run the five synthetic research-gap experiments (leakage-free probes, shared graph memory, regularizer A/B, temporal-difference A/B, and correlated multimodal masking):

python -m examples.representation_gap_experiments

See CONTRIBUTING.md for the full development guide and CHANGELOG.md for recent fixes.

References

The regularizer implementations are based on the following papers:

LeJEPA — Provable and Scalable Self-Supervised Learning Without the Heuristics. Introduces SIGReg and proves the isotropic Gaussian is the optimal JEPA embedding distribution. arXiv:2511.08544
Weak-SIGReg — Covariance Regularization for Stable Deep Learning. Adapts SIGReg as a general optimization stabilizer for supervised training. arXiv:2603.05924
Rectified LpJEPA — Joint-Embedding Predictive Architectures with Sparse and Maximum-Entropy Representations. Generalizes Gaussian JEPAs via RDMReg for controllable sparsity. arXiv:2602.01456
BiJEPA — Bi-directional Joint Embedding Predictive Architecture for Symmetric Representation Learning. Adds cycle-consistent bidirectional prediction with representation-norm regularization. arXiv:2603.00049
λ-JEPA — Spectral Anti-Collapse Regularization for Self-Supervised Learning. Protects the backbone representation used for downstream transfer. arXiv:2609.35288
Sub-JEPA — Subspace Gaussian Regularization for Stable End-to-End World Models. Relaxes full-space isotropy using multiple lower-dimensional Gaussian views. arXiv:2605.09241
MotionJEPA — Preventing Temporal Feature Collapse by Capturing Visual Changes in Latent Space. Motivates temporal-difference prediction objectives. arXiv:2609.23881
MM-LeJEPA — Correlated Gaussian Regularization for Multimodal Joint-Embedding Predictive Architectures. Motivates correlated covariance targets across modalities. arXiv:2610.24681

Citation

@software{event_jepa_cube2026,
  author = {Agourakis, Dionisio Chiuratto},
  title = {Event-JEPA-Cube: Event Sequence Processing and Entity Relationships},
  year = {2026},
  publisher = {GitHub},
  url = {https://github.com/josaum/jcube}
}

License

MIT License — see LICENSE for details.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
deploy		deploy
docs		docs
event_jepa_cube		event_jepa_cube
examples		examples
reports		reports
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Navigation Menu

Repository navigation

About

Repository files navigation

Event-JEPA-Cube

Project Goals

Installation

Quick Start

Core Components

EventJEPA — Sequence Processor

EmbeddingCube — Entity Relationship Manager

JEPA Regularizers

SIGReg — Sketched Isotropic Gaussian Regularization

WeakSIGReg — Covariance Regularization

RDMReg — Rectified Distribution Matching

NormReg — Representation-Norm Regularization

SACReg — Spectral Anti-Collapse Regularization

SubSIGReg — Subspace Gaussian Regularization

TemporalDifferenceReg — Motion-Aware Prediction

CorrelatedSIGReg — Correlated Gaussian Targets

Choosing a Regularizer

Bidirectional Training — BiJEPATrainer

Integrated Usage

Extensibility

Custom Embedding Types

Custom Relationship Models

Architecture Overview

Design Principles

Theoretical Performance Characteristics

Industry Applications

Development

References

Citation

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Event-JEPA-Cube

Project Goals

Installation

Quick Start

Core Components

EventJEPA — Sequence Processor

EmbeddingCube — Entity Relationship Manager

JEPA Regularizers

SIGReg — Sketched Isotropic Gaussian Regularization

WeakSIGReg — Covariance Regularization

RDMReg — Rectified Distribution Matching

NormReg — Representation-Norm Regularization

SACReg — Spectral Anti-Collapse Regularization

SubSIGReg — Subspace Gaussian Regularization

TemporalDifferenceReg — Motion-Aware Prediction

CorrelatedSIGReg — Correlated Gaussian Targets

Choosing a Regularizer

Bidirectional Training — BiJEPATrainer

Integrated Usage

Extensibility

Custom Embedding Types

Custom Relationship Models

Architecture Overview

Design Principles

Theoretical Performance Characteristics

Industry Applications

Development

References

Citation

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages