gsppy 3.3.0__py3-none-any.whl → 3.5.0__py3-none-any.whl

gsppy/__init__.py

@@ -6,7 +6,12 @@ implementation, CLI helpers for loading transactional data, and the package vers
 
 from importlib import metadata as importlib_metadata
 
-from gsppy.cli import detect_and_read_file, read_transactions_from_csv, read_transactions_from_json, setup_logging
+from gsppy.cli import (
+    setup_logging,
+    detect_and_read_file,
+    read_transactions_from_csv,
+    read_transactions_from_json,
+)
 from gsppy.gsp import GSP
 
 try:

gsppy/accelerate.py

@@ -28,11 +28,14 @@ try:  # pragma: no cover - optional dependency path
     cp = cast(Any, _cp_mod)
 
     try:
-        _gpu_available = cp.cuda.runtime.getDeviceCount() > 0  # type: ignore[attr-defined]
+        if cp is not None:
+            _gpu_available = cp.cuda.runtime.getDeviceCount() > 0
+        else:
+            _gpu_available = False
     except Exception:
         _gpu_available = False
 except Exception:  # pragma: no cover - optional dependency path
-    cp = None  # type: ignore[assignment]
+    cp = None
     _gpu_available = False
 
 # Simple per-process cache for encoded transactions keyed by the list object's id

gsppy/cli.py

@@ -33,49 +33,123 @@ import csv
 import sys
 import json
 import logging
-from typing import Dict, List, Tuple
+from typing import Any, Dict, List, Tuple, Union, Optional, cast
 
 import click
 
 from gsppy.gsp import GSP
-
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(message)s",  # Simplified to keep CLI output clean
-    handlers=[logging.StreamHandler(sys.stdout)],
-)
-logger: logging.Logger = logging.getLogger(__name__)
+from gsppy.utils import has_timestamps
 
 
 def setup_logging(verbose: bool) -> None:
     """
-    Set the logging level based on the verbosity of the CLI output.
-    :param verbose: Whether to enable verbose logging.
+    Configure logging with standardized format based on verbosity level.
+    
+    When verbose is enabled, provides detailed structured logging with:
+    - Timestamps (ISO 8601 format)
+    - Log levels
+    - Process ID for traceability
+    - Module context
+    
+    When verbose is disabled, uses simple format with just the message.
+    
+    Parameters:
+        verbose: Whether to enable verbose logging with detailed formatting.
     """
+    # Remove any existing handlers
+    root_logger = logging.getLogger()
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+    
     if verbose:
-        logger.setLevel(logging.DEBUG)
+        # Detailed format with timestamps, levels, PID, and context for verbose mode
+        log_format = "%(asctime)s | %(levelname)-8s | PID:%(process)d | %(name)s | %(message)s"
+        date_format = "%Y-%m-%dT%H:%M:%S"
+        log_level = logging.DEBUG
     else:
-        logger.setLevel(logging.INFO)
+        # Simple format for default mode - just the message
+        log_format = "%(message)s"
+        date_format = None
+        log_level = logging.INFO
+    
+    # Configure logging with the appropriate format
+    logging.basicConfig(
+        level=log_level,
+        format=log_format,
+        datefmt=date_format,
+        handlers=[logging.StreamHandler(sys.stdout)],
+        force=True,  # Force reconfiguration even if already configured
+    )
+
+
+logger: logging.Logger = logging.getLogger(__name__)
 
 
-def read_transactions_from_json(file_path: str) -> List[List[str]]:
+def read_transactions_from_json(file_path: str) -> Union[List[List[str]], List[List[Tuple[str, float]]]]:
     """
     Read transactions from a JSON file.
 
+    Supports both simple transactions and timestamped transactions:
+    - Simple: [["A", "B", "C"], ["D", "E"]]
+    - Timestamped: [[["A", 1], ["B", 3]], [["D", 2], ["E", 5]]]
+      where the first element is the item and the second element is the timestamp
+
     Parameters:
         file_path (str): Path to the file containing transactions.
 
     Returns:
-        List[List]: Parsed transactions from the file.
+        Union[List[List[str]], List[List[Tuple[str, float]]]]:
+            Parsed transactions from the file. For timestamped data,
+            inner lists are converted to tuples (item, timestamp).
 
     Raises:
         ValueError: If the file cannot be read or does not contain valid JSON.
     """
     try:
         with open(file_path, "r", encoding="utf-8") as f:
-            transactions: List[List[str]] = json.load(f)
-        return transactions
+            raw_data: Any = json.load(f)
+
+        if not isinstance(raw_data, list):
+            raise ValueError("JSON must contain a top-level list of transactions.")
+
+        raw_transactions: List[List[Union[str, Tuple[str, float]]]] = cast(
+            List[List[Union[str, Tuple[str, float]]]], raw_data
+        )
+
+        # Check if this is timestamped data using the helper function.
+        # Use defensive checks to avoid errors on malformed data:
+        # - Find the first non-empty transaction instead of assuming index 0 is non-empty.
+        # - Normalize inner list pairs (from json.load) to tuples before calling has_timestamps.
+        first_non_empty_transaction: Optional[List[Union[str, Tuple[str, float]]]] = next(
+            (transaction for transaction in raw_transactions if transaction),
+            None,
+        )
+
+        is_timestamped = False
+        if first_non_empty_transaction is not None:
+            # Normalize to the exact input type expected by has_timestamps
+            normalized_first: List[Union[str, Tuple[str, float]]] = []
+            for item in first_non_empty_transaction:
+                if isinstance(item, list) and len(item) == 2:
+                    normalized_first.append((str(item[0]), float(item[1])))
+                elif isinstance(item, tuple):
+                    normalized_first.append(cast(Tuple[str, float], item))
+                else:
+                    normalized_first.append(str(item))
+
+            is_timestamped = has_timestamps(normalized_first)
+
+        if is_timestamped:
+            # Convert timestamped data: [[["A", 1], ["B", 2]]] -> [[("A", 1), ("B", 2)]]
+            transactions: List[List[Tuple[str, float]]] = [
+                [cast(Tuple[str, float], tuple(item) if isinstance(item, list) else item) for item in transaction]
+                for transaction in raw_transactions
+            ]
+            return transactions
+
+        # Simple transactions remain as-is (or invalid data passed through for GSP to validate)
+        simple_transactions: List[List[str]] = [[str(item) for item in transaction] for transaction in raw_transactions]
+        return simple_transactions
     except Exception as e:
         msg = f"Error reading transaction data from JSON file '{file_path}': {e}"
         logging.error(msg)
@@ -112,7 +186,7 @@ def read_transactions_from_csv(file_path: str) -> List[List[str]]:
         raise ValueError(msg) from e
 
 
-def detect_and_read_file(file_path: str) -> List[List[str]]:
+def detect_and_read_file(file_path: str) -> Union[List[List[str]], List[List[Tuple[str, float]]]]:
     """
     Detect file format (CSV or JSON) and read transactions.
 
@@ -120,7 +194,8 @@ def detect_and_read_file(file_path: str) -> List[List[str]]:
         file_path (str): Path to the file containing transactions.
 
     Returns:
-        List[List]: Parsed transactions from the file.
+        Union[List[List[str]], List[List[Tuple[str, float]]]]:
+            Parsed transactions from the file.
 
     Raises:
         ValueError: If the file format is unsupported or reading fails.
@@ -163,10 +238,53 @@ def detect_and_read_file(file_path: str) -> List[List[str]]:
     show_default=True,
     help="Backend to use for support counting.",
 )
+@click.option(
+    "--mingap",
+    type=float,
+    default=None,
+    help="Minimum time gap required between consecutive items in patterns (requires timestamped transactions).",
+)
+@click.option(
+    "--maxgap",
+    type=float,
+    default=None,
+    help="Maximum time gap allowed between consecutive items in patterns (requires timestamped transactions).",
+)
+@click.option(
+    "--maxspan",
+    type=float,
+    default=None,
+    help="Maximum time span from first to last item in patterns (requires timestamped transactions).",
+)
 @click.option("--verbose", is_flag=True, help="Enable verbose output for debugging purposes.")
-def main(file_path: str, min_support: float, backend: str, verbose: bool) -> None:
+def main(
+    file_path: str,
+    min_support: float,
+    backend: str,
+    mingap: Optional[float],
+    maxgap: Optional[float],
+    maxspan: Optional[float],
+    verbose: bool,
+) -> None:
     """
     Run the GSP algorithm on transactional data from a file.
+
+    Supports both simple transactions (items only) and timestamped transactions
+    (item-timestamp pairs) for temporal pattern mining.
+
+    Examples:
+        Basic usage without temporal constraints:
+
+        ```bash
+        gsppy --file transactions.json --min_support 0.3
+        ```
+
+        With temporal constraints:
+
+        ```bash
+        gsppy --file temporal_data.json --min_support 0.3 --maxgap 10
+        gsppy --file events.json --min_support 0.5 --mingap 2 --maxgap 10 --maxspan 20
+        ```
     """
     setup_logging(verbose)
 
@@ -177,10 +295,8 @@ def main(file_path: str, min_support: float, backend: str, verbose: bool) -> Non
         logger.error(f"Error: {e}")
         sys.exit(1)
 
-    # Check min_support
-    if min_support <= 0.0 or min_support > 1.0:
-        logger.error("Error: min_support must be in the range (0.0, 1.0].")
-        sys.exit(1)
+    # Validate parameters
+    _validate_parameters(min_support, mingap, maxgap, maxspan)
 
     # Select backend for acceleration layer
     if backend and backend.lower() != "auto":
@@ -188,7 +304,7 @@ def main(file_path: str, min_support: float, backend: str, verbose: bool) -> Non
 
     # Initialize and run GSP algorithm
     try:
-        gsp = GSP(transactions)
+        gsp = GSP(transactions, mingap=mingap, maxgap=maxgap, maxspan=maxspan, verbose=verbose)
         patterns: List[Dict[Tuple[str, ...], int]] = gsp.search(min_support=min_support)
         logger.info("Frequent Patterns Found:")
         for i, level in enumerate(patterns, start=1):
@@ -200,5 +316,43 @@ def main(file_path: str, min_support: float, backend: str, verbose: bool) -> Non
         sys.exit(1)
 
 
+def _validate_parameters(
+    min_support: float,
+    mingap: Optional[float],
+    maxgap: Optional[float],
+    maxspan: Optional[float],
+) -> None:
+    """
+    Validate input parameters for GSP algorithm.
+
+    Args:
+        min_support: Minimum support threshold
+        mingap: Minimum time gap constraint
+        maxgap: Maximum time gap constraint
+        maxspan: Maximum time span constraint
+
+    Raises:
+        SystemExit: If validation fails
+    """
+    # Check min_support
+    if min_support <= 0.0 or min_support > 1.0:
+        logger.error("Error: min_support must be in the range (0.0, 1.0].")
+        sys.exit(1)
+
+    # Validate temporal constraints
+    if mingap is not None and mingap < 0:
+        logger.error("Error: mingap must be non-negative.")
+        sys.exit(1)
+    if maxgap is not None and maxgap < 0:
+        logger.error("Error: maxgap must be non-negative.")
+        sys.exit(1)
+    if maxspan is not None and maxspan < 0:
+        logger.error("Error: maxspan must be non-negative.")
+        sys.exit(1)
+    if mingap is not None and maxgap is not None and mingap > maxgap:
+        logger.error("Error: mingap cannot be greater than maxgap.")
+        sys.exit(1)
+
+
 if __name__ == "__main__":
     main()

gsppy/gsp.py

@@ -88,11 +88,17 @@ Version:
 import math
 import logging
 import multiprocessing as mp
-from typing import Dict, List, Tuple, Optional
+from typing import Dict, List, Tuple, Union, Optional, cast
 from itertools import chain
 from collections import Counter
 
-from gsppy.utils import split_into_batches, is_subsequence_in_list, generate_candidates_from_previous
+from gsppy.utils import (
+    has_timestamps,
+    split_into_batches,
+    is_subsequence_in_list,
+    generate_candidates_from_previous,
+    is_subsequence_in_list_with_time_constraints,
+)
 from gsppy.accelerate import support_counts as support_counts_accel
 
 logger: logging.Logger = logging.getLogger(__name__)
@@ -117,41 +123,98 @@ class GSP:
                         k-sequence for pattern generation.
     """
 
-    def __init__(self, raw_transactions: List[List[str]]):
+    def __init__(
+        self,
+        raw_transactions: Union[List[List[str]], List[List[Tuple[str, float]]]],
+        mingap: Optional[float] = None,
+        maxgap: Optional[float] = None,
+        maxspan: Optional[float] = None,
+        verbose: bool = False,
+    ):
         """
         Initialize the GSP algorithm with raw transactional data.
 
         Parameters:
-            raw_transactions (List[List]): Input transaction dataset where each transaction
-                                           is a list of items (e.g., [['A', 'B'], ['B', 'C', 'D']]).
+            raw_transactions (Union[List[List[str]], List[List[Tuple[str, float]]]]):
+                Input transaction dataset where each transaction is either:
+                - A list of items (e.g., [['A', 'B'], ['B', 'C', 'D']])
+                - A list of (item, timestamp) tuples (e.g., [[('A', 1.0), ('B', 2.0)]])
+            mingap (Optional[float]): Minimum time gap required between consecutive items in patterns.
+            maxgap (Optional[float]): Maximum time gap allowed between consecutive items in patterns.
+            maxspan (Optional[float]): Maximum time span from first to last item in patterns.
+            verbose (bool): Enable verbose logging output with detailed progress information.
+                           Default is False (minimal output).
 
         Attributes Initialized:
             - Processes the input raw transaction dataset.
             - Computes unique singleton candidates (`unique_candidates`).
             - Extracts the maximum transaction size (`max_size`) from the dataset for limiting
               the search space.
+            - Stores temporal constraints for use during pattern mining.
 
         Raises:
             ValueError: If the input transaction dataset is empty, contains
                         fewer than two transactions, or is not properly formatted.
+                        Also raised if temporal constraints are invalid.
         """
         self.freq_patterns: List[Dict[Tuple[str, ...], int]] = []
+        self.mingap = mingap
+        self.maxgap = maxgap
+        self.maxspan = maxspan
+        self.verbose = verbose
+        self._configure_logging()
+        self._validate_temporal_constraints()
         self._pre_processing(raw_transactions)
 
-    def _pre_processing(self, raw_transactions: List[List[str]]) -> None:
+    def _configure_logging(self) -> None:
+        """
+        Configure logging for the GSP instance based on verbosity setting.
+
+        When verbose is True, sets the module logger to DEBUG level for detailed output.
+        When verbose is False, sets the module logger to WARNING level for minimal output.
+
+        This method intentionally avoids modifying the root logger to prevent
+        unexpected global logging side effects, especially in multiprocessing
+        environments.
+        """
+        if self.verbose:
+            logger.setLevel(logging.DEBUG)
+        else:
+            logger.setLevel(logging.WARNING)
+
+    def _validate_temporal_constraints(self) -> None:
+        """
+        Validate temporal constraint parameters.
+
+        Raises:
+            ValueError: If any temporal constraint is negative or if mingap > maxgap.
+        """
+        if self.mingap is not None and self.mingap < 0:
+            raise ValueError("mingap must be non-negative")
+        if self.maxgap is not None and self.maxgap < 0:
+            raise ValueError("maxgap must be non-negative")
+        if self.maxspan is not None and self.maxspan < 0:
+            raise ValueError("maxspan must be non-negative")
+        if self.mingap is not None and self.maxgap is not None and self.mingap > self.maxgap:
+            raise ValueError("mingap cannot be greater than maxgap")
+
+    def _pre_processing(self, raw_transactions: Union[List[List[str]], List[List[Tuple[str, float]]]]) -> None:
         """
         Validate and preprocess the input transactional dataset.
 
         This method ensures that the dataset is formatted correctly and converts the transactions
         into tuples while counting unique singleton candidates for initial support computation steps.
+        It handles both simple transactions (items only) and timestamped transactions.
 
         Parameters:
-            raw_transactions (List[List]): Input transactional data.
+            raw_transactions (Union[List[List[str]], List[List[Tuple[str, float]]]]):
+                Input transactional data (with or without timestamps).
 
         Attributes Set:
             - `transactions`: The preprocessed transactions converted to tuples.
             - `unique_candidates`: A list of unique singleton candidates derived from the dataset.
             - `max_size`: The length of the largest transaction in the data.
+            - `has_timestamps`: Boolean indicating if transactions include timestamps.
 
         Raises:
             ValueError: If the dataset is empty, improperly formatted, or contains fewer than 2 transactions.
@@ -171,28 +234,71 @@ class GSP:
             raise ValueError(msg)
 
         logger.info("Pre-processing transactions...")
+
+        # Detect if transactions have timestamps by checking non-empty transactions
+        self.has_timestamps = False
+        for tx in raw_transactions:
+            if tx:  # Check non-empty transactions
+                tx_sequence = cast(List[Union[str, Tuple[str, float]]], tx)
+                self.has_timestamps = has_timestamps(tx_sequence)
+                if self.has_timestamps:
+                    logger.debug("Detected timestamped transactions")
+                break
+
+        # Validate temporal constraints are only used with timestamps
+        if (self.mingap is not None or self.maxgap is not None or self.maxspan is not None) and not self.has_timestamps:
+            logger.warning(
+                "Temporal constraints specified but transactions do not have timestamps. "
+                "Constraints will be ignored."
+            )
+            # Clear temporal constraints since they cannot be applied
+            self.mingap = None
+            self.maxgap = None
+            self.maxspan = None
+
         self.max_size: int = max(len(item) for item in raw_transactions)
-        self.transactions: List[Tuple[str, ...]] = [tuple(transaction) for transaction in raw_transactions]
-        counts: Counter[str] = Counter(chain.from_iterable(raw_transactions))
+
+        if self.has_timestamps:
+            # For timestamped transactions, convert to tuples and extract items for counting
+            timestamped_txs = cast(List[List[Tuple[str, float]]], raw_transactions)
+            self.transactions = [tuple(transaction) for transaction in timestamped_txs]
+            # Extract just the items for counting unique candidates
+            all_items = chain.from_iterable([[item for item, _ in tx] for tx in timestamped_txs])
+            counts: Counter[str] = Counter(all_items)
+        else:
+            # For non-timestamped transactions, process as before
+            simple_txs = cast(List[List[str]], raw_transactions)
+            self.transactions = [tuple(transaction) for transaction in simple_txs]
+            counts: Counter[str] = Counter(chain.from_iterable(simple_txs))
+
         # Start with singleton candidates (1-sequences)
         self.unique_candidates: List[Tuple[str, ...]] = [(item,) for item in counts.keys()]
         logger.debug("Unique candidates: %s", self.unique_candidates)
 
     @staticmethod
     def _worker_batch(
-        batch: List[Tuple[str, ...]], transactions: List[Tuple[str, ...]], min_support: int
+        batch: List[Tuple[str, ...]],
+        transactions: List[Union[Tuple[str, ...], Tuple[Tuple[str, float], ...]]],
+        min_support: int,
+        mingap: Optional[float] = None,
+        maxgap: Optional[float] = None,
+        maxspan: Optional[float] = None,
     ) -> List[Tuple[Tuple[str, ...], int]]:
         """
         Evaluate a batch of candidate sequences to compute their support.
 
         This method iterates over the candidates in the given batch and checks their frequency
         of appearance across all transactions. Candidates meeting the user-defined minimum
-        support threshold are returned.
+        support threshold are returned. Supports temporal constraints when timestamps are present.
 
         Parameters:
             batch (List[Tuple]): A batch of candidate sequences, where each sequence is represented as a tuple.
-            transactions (List[Tuple]): Preprocessed transactions as tuples.
+            transactions (List[Union[Tuple[str, ...], Tuple[Tuple[str, float], ...]]]):
+                Preprocessed transactions as tuples (with or without timestamps).
             min_support (int): Absolute minimum support count required for a candidate to be considered frequent.
+            mingap (Optional[float]): Minimum time gap between consecutive items.
+            maxgap (Optional[float]): Maximum time gap between consecutive items.
+            maxspan (Optional[float]): Maximum time span from first to last item.
 
         Returns:
             List[Tuple[Tuple, int]]: A list of tuples where each tuple contains:
@@ -200,8 +306,27 @@ class GSP:
                                      - The candidate's support count.
         """
         results: List[Tuple[Tuple[str, ...], int]] = []
+        has_temporal = mingap is not None or maxgap is not None or maxspan is not None
+
+        # Detect if transactions have timestamps using the helper function,
+        # based on the first non-empty transaction in the batch.
+        first_non_empty_tx = next((t for t in transactions if t), None)
+        has_timestamps_flag = bool(first_non_empty_tx and has_timestamps(first_non_empty_tx))
+
         for item in batch:
-            frequency = sum(1 for t in transactions if is_subsequence_in_list(item, t))
+            if has_timestamps_flag or has_temporal:
+                # Use temporal-aware checking for timestamped transactions
+                frequency = sum(
+                    1
+                    for t in transactions
+                    if is_subsequence_in_list_with_time_constraints(
+                        item, t, mingap=mingap, maxgap=maxgap, maxspan=maxspan
+                    )
+                )
+            else:
+                # Use standard non-temporal checking for simple transactions
+                frequency = sum(1 for t in transactions if is_subsequence_in_list(item, t))
+
             if frequency >= min_support:
                 results.append((item, frequency))
         return results
@@ -228,7 +353,7 @@ class GSP:
         with mp.Pool(processes=mp.cpu_count()) as pool:
             batch_results = pool.starmap(
                 self._worker_batch,  # Process a batch at a time
-                [(batch, self.transactions, min_support) for batch in batches],
+                [(batch, self.transactions, min_support, self.mingap, self.maxgap, self.maxspan) for batch in batches],
             )
 
         # Flatten the list of results and convert to a dictionary
@@ -245,9 +370,21 @@ class GSP:
         Calculate support counts for candidate sequences using the fastest available backend.
         This will try the Rust extension if available (and configured), otherwise fall back to
         the Python multiprocessing implementation.
+
+        Note: When temporal constraints are active or transactions have timestamps,
+        the Python implementation is always used as the accelerated backends do not yet
+        support temporal constraints or timestamped transactions.
         """
+        # Use Python implementation when temporal constraints are active or timestamps present
+        has_temporal = self.mingap is not None or self.maxgap is not None or self.maxspan is not None
+        if has_temporal or self.has_timestamps:
+            return self._support_python(items, min_support, batch_size)
+
+        # For non-timestamped transactions, we can use accelerated support counting
+        # Cast is safe here because we've confirmed no timestamps above
+        non_timestamped_transactions = cast(List[Tuple[str, ...]], self.transactions)
         try:
-            return support_counts_accel(self.transactions, items, min_support, batch_size, backend=backend)
+            return support_counts_accel(non_timestamped_transactions, items, min_support, batch_size, backend=backend)
         except Exception:
             # Fallback to Python implementation on any acceleration failure
             return self._support_python(items, min_support, batch_size)
@@ -270,6 +407,7 @@ class GSP:
         min_support: float = 0.2,
         max_k: Optional[int] = None,
         backend: Optional[str] = None,
+        verbose: Optional[bool] = None,
     ) -> List[Dict[Tuple[str, ...], int]]:
         """
         Execute the Generalized Sequential Pattern (GSP) mining algorithm.
@@ -278,10 +416,19 @@ class GSP:
         in the input transaction dataset. Patterns are extracted iteratively at each k-sequence level,
         starting from singleton sequences, until no further frequent patterns can be found.
 
+        When temporal constraints (mingap, maxgap, maxspan) are specified during initialization,
+        the algorithm enforces these constraints during pattern matching, allowing for time-aware
+        sequential pattern mining.
+
         Parameters:
             min_support (float): Minimum support threshold as a fraction of total transactions.
                                      For example, `0.3` means that a sequence is frequent if it
                                      appears in at least 30% of all transactions.
+            max_k (Optional[int]): Maximum length of patterns to mine. If None, mines up to max transaction length.
+            backend (Optional[str]): Backend to use for support counting ('auto', 'python', 'rust', 'gpu').
+                                    Note: temporal constraints always use Python backend.
+            verbose (Optional[bool]): Override instance verbosity setting for this search.
+                                     If None, uses the instance's verbose setting.
 
         Returns:
             List[Dict[Tuple[str, ...], int]]: A list of dictionaries containing frequent patterns
@@ -296,8 +443,8 @@ class GSP:
               and completion.
             - Status updates for each iteration until the algorithm terminates.
 
-        Example:
-            Basic usage with the default backend:
+        Examples:
+            Basic usage without temporal constraints:
 
             ```python
             from gsppy.gsp import GSP
@@ -311,11 +458,41 @@ class GSP:
             gsp = GSP(transactions)
             patterns = gsp.search(min_support=0.3)
             ```
+
+            Usage with temporal constraints (requires timestamped transactions):
+
+            ```python
+            from gsppy.gsp import GSP
+
+            # Transactions with timestamps (item, timestamp) pairs
+            # where timestamps can be in any unit (seconds, minutes, hours, days, etc.)
+            timestamped_transactions = [
+                [("A", 1), ("B", 3), ("C", 5)],  # timestamps: 1, 3, 5
+                [("A", 2), ("B", 10), ("C", 12)],  # timestamps: 2, 10, 12
+                [("A", 1), ("C", 4)],  # timestamps: 1, 4
+            ]
+
+            # Find patterns with maxgap of 5 time units between consecutive items
+            gsp = GSP(timestamped_transactions, maxgap=5)
+            patterns = gsp.search(min_support=0.5)
+            # Pattern ("A", "B", "C") won't be found in transaction 2
+            # because gap between A and B is 8 (exceeds maxgap=5)
+            ```
         """
+        # Override verbosity if specified for this search
+        original_verbose = self.verbose
+        if verbose is not None:
+            self.verbose = verbose
+            self._configure_logging()
+
         if not 0.0 < min_support <= 1.0:
             raise ValueError("Minimum support must be in the range (0.0, 1.0]")
 
         logger.info(f"Starting GSP algorithm with min_support={min_support}...")
+        if self.mingap is not None or self.maxgap is not None or self.maxspan is not None:
+            logger.info(
+                f"Using temporal constraints: mingap={self.mingap}, maxgap={self.maxgap}, maxspan={self.maxspan}"
+            )
 
         # Convert fractional support to absolute count (ceil to preserve threshold semantics)
         abs_min_support = int(math.ceil(len(self.transactions) * float(min_support)))
@@ -352,4 +529,10 @@ class GSP:
 
             self._print_status(k_items, candidates)
         logger.info("GSP algorithm completed.")
+
+        # Restore original verbosity if it was overridden
+        if verbose is not None:
+            self.verbose = original_verbose
+            self._configure_logging()
+
         return self.freq_patterns[:-1]

gsppy/utils.py

@@ -21,11 +21,48 @@ These utilities are designed to support sequence processing tasks and can be
 adapted to various domains, such as data mining, recommendation systems, and sequence analysis.
 """
 
-from typing import Dict, List, Tuple, Sequence, Generator
+from typing import Dict, List, Tuple, Union, Optional, Sequence, Generator, cast
 from functools import lru_cache
 from itertools import product
 
 
+def has_timestamps(
+    sequence: Union[
+        Tuple[Union[str, Tuple[str, Union[int, float]]], ...], List[Union[str, Tuple[str, Union[int, float]]]]
+    ],
+) -> bool:
+    """
+    Check if a sequence contains timestamped data (item-timestamp pairs).
+
+    Parameters:
+        sequence: A sequence that may contain timestamped data
+
+    Returns:
+        bool: True if the sequence contains timestamped data, False otherwise
+
+    Examples:
+        >>> has_timestamps((("A", 1), ("B", 2)))
+        True
+        >>> has_timestamps(("A", "B", "C"))
+        False
+    """
+    if not sequence or len(sequence) == 0:
+        return False
+
+    first_item = sequence[0]
+
+    # Check if first item is a tuple or list with 2 elements where second is numeric
+    if isinstance(first_item, (tuple, list)) and len(first_item) == 2:
+        try:
+            # Try to interpret second element as a number
+            float(first_item[1])
+            return True
+        except (TypeError, ValueError):
+            return False
+
+    return False
+
+
 def split_into_batches(
     items: Sequence[Tuple[str, ...]], batch_size: int
 ) -> Generator[Sequence[Tuple[str, ...]], None, None]:
@@ -59,11 +96,11 @@ def is_subsequence_in_list(subsequence: Tuple[str, ...], sequence: Tuple[str, ..
         bool: True if the subsequence is found, False otherwise.
 
     Examples:
-        >>> is_subsequence_in_list(('a', 'c'), ('a', 'b', 'c'))
+        >>> is_subsequence_in_list(("a", "c"), ("a", "b", "c"))
         True
-        >>> is_subsequence_in_list(('a', 'c'), ('c', 'a'))
+        >>> is_subsequence_in_list(("a", "c"), ("c", "a"))
         False
-        >>> is_subsequence_in_list(('a', 'b'), ('a', 'b', 'c'))
+        >>> is_subsequence_in_list(("a", "b"), ("a", "b", "c"))
         True
     """
     # Handle the case where the subsequence is empty - it should not exist in any sequence
@@ -86,6 +123,249 @@ def is_subsequence_in_list(subsequence: Tuple[str, ...], sequence: Tuple[str, ..
     return False
 
 
+def is_subsequence_in_list_with_time_constraints(
+    subsequence: Tuple[str, ...],
+    sequence: Union[Tuple[str, ...], Tuple[Tuple[str, float], ...]],
+    mingap: Optional[float] = None,
+    maxgap: Optional[float] = None,
+    maxspan: Optional[float] = None,
+) -> bool:
+    """
+    Check if a subsequence exists within a sequence with optional temporal constraints.
+
+    This function extends the standard subsequence check to support temporal constraints
+    for time-constrained sequential pattern mining. It handles both simple sequences
+    (items only) and timestamped sequences (item-timestamp pairs).
+
+    Temporal Constraints:
+        - mingap: Minimum time gap required between consecutive items in the pattern.
+        - maxgap: Maximum time gap allowed between consecutive items in the pattern.
+        - maxspan: Maximum time span from the first to last item in the pattern.
+
+    Parameters:
+        subsequence (Tuple[str, ...]): The pattern to search for (items only, no timestamps).
+        sequence (Union[Tuple[str, ...], Tuple[Tuple[str, float], ...]]):
+            The sequence to search within. Can be:
+            - Simple: Tuple of items (e.g., ('A', 'B', 'C'))
+            - Timestamped: Tuple of (item, timestamp) pairs (e.g., (('A', 1.0), ('B', 3.0)))
+        mingap (Optional[float]): Minimum time between consecutive pattern elements.
+        maxgap (Optional[float]): Maximum time between consecutive pattern elements.
+        maxspan (Optional[float]): Maximum time from first to last pattern element.
+
+    Returns:
+        bool: True if the subsequence is found respecting temporal constraints, False otherwise.
+
+    Examples:
+        >>> # Without timestamps (backward compatible)
+        >>> is_subsequence_in_list_with_time_constraints(("A", "C"), ("A", "B", "C"))
+        True
+
+        >>> # With timestamps and maxgap constraint
+        >>> seq = (("A", 1), ("B", 3), ("C", 10))
+        >>> is_subsequence_in_list_with_time_constraints(("A", "C"), seq, maxgap=5)
+        False  # Gap between A and C is 9, exceeds maxgap=5
+
+        >>> # With timestamps and mingap constraint
+        >>> seq = (("A", 1), ("B", 2), ("C", 3))
+        >>> is_subsequence_in_list_with_time_constraints(("A", "C"), seq, mingap=3)
+        False  # Gap between A and C is 2, less than mingap=3
+
+        >>> # With timestamps and maxspan constraint
+        >>> seq = (("A", 1), ("B", 5), ("C", 12))
+        >>> is_subsequence_in_list_with_time_constraints(("A", "C"), seq, maxspan=10)
+        False  # Span from A to C is 11, exceeds maxspan=10
+    """
+    # Handle empty subsequence
+    if not subsequence:
+        return False
+
+    # Return False if the subsequence is longer than the sequence
+    if len(subsequence) > len(sequence):
+        return False
+
+    # Determine if sequence has timestamps
+    has_timestamps_flag = has_timestamps(sequence)
+
+    # If no temporal constraints and no timestamps, use the optimized cached version
+    if not has_timestamps_flag and mingap is None and maxgap is None and maxspan is None:
+        return is_subsequence_in_list(subsequence, sequence)
+
+    # Extract items and timestamps from sequence
+    seq_items, seq_times = _extract_items_and_timestamps(sequence, has_timestamps_flag)
+
+    # Try to find a match starting from each position
+    return _find_temporal_match(subsequence, seq_items, seq_times, mingap, maxgap, maxspan)
+
+
+def _extract_items_and_timestamps(
+    sequence: Union[Tuple[str, ...], Tuple[Tuple[str, float], ...]],
+    has_timestamps_flag: bool,
+) -> Tuple[Tuple[str, ...], Optional[Tuple[float, ...]]]:
+    """
+    Extract items and timestamps from a sequence.
+
+    Args:
+        sequence: The sequence to extract from
+        has_timestamps_flag: Whether the sequence has timestamps
+
+    Returns:
+        Tuple of (items, timestamps) where timestamps is None if not present
+    """
+    if has_timestamps_flag:
+        # For timestamped sequences, extract items and timestamps separately
+        timestamped_seq = cast(Tuple[Tuple[str, float], ...], sequence)
+        seq_items = tuple(item for item, _ in timestamped_seq)
+        seq_times = tuple(time for _, time in timestamped_seq)
+        return seq_items, seq_times
+    else:
+        # For non-timestamped sequences, return items directly with None for timestamps
+        simple_seq = cast(Tuple[str, ...], sequence)
+        return simple_seq, None
+
+
+def _find_temporal_match(
+    subsequence: Tuple[str, ...],
+    seq_items: Tuple[str, ...],
+    seq_times: Optional[Tuple[float, ...]],
+    mingap: Optional[float],
+    maxgap: Optional[float],
+    maxspan: Optional[float],
+) -> bool:
+    """
+    Find if subsequence matches with temporal constraints.
+
+    Args:
+        subsequence: Pattern to search for
+        seq_items: Items in the sequence
+        seq_times: Timestamps (None if not present)
+        mingap: Minimum gap constraint
+        maxgap: Maximum gap constraint
+        maxspan: Maximum span constraint
+
+    Returns:
+        True if match found, False otherwise
+    """
+    len_sub = len(subsequence)
+    len_seq = len(seq_items)
+
+    # Try starting from each position
+    for start_idx in range(len_seq - len_sub + 1):
+        if _try_match_from_position(start_idx, subsequence, seq_items, seq_times, mingap, maxgap, maxspan):
+            return True
+
+    return False
+
+
+def _try_match_from_position(
+    start_idx: int,
+    subsequence: Tuple[str, ...],
+    seq_items: Tuple[str, ...],
+    seq_times: Optional[Tuple[float, ...]],
+    mingap: Optional[float],
+    maxgap: Optional[float],
+    maxspan: Optional[float],
+) -> bool:
+    """
+    Try to match subsequence starting from a given position.
+
+    Args:
+        start_idx: Starting position in sequence
+        subsequence: Pattern to match
+        seq_items: Items in sequence
+        seq_times: Timestamps (None if not present)
+        mingap: Minimum gap constraint
+        maxgap: Maximum gap constraint
+        maxspan: Maximum span constraint
+
+    Returns:
+        True if match found, False otherwise
+    """
+    sub_idx = 0
+    matched_indices: List[int] = []
+    len_sub = len(subsequence)
+    len_seq = len(seq_items)
+
+    for seq_idx in range(start_idx, len_seq):
+        if seq_items[seq_idx] == subsequence[sub_idx]:
+            # Check temporal constraints if we have timestamps and have previous matches
+            if (
+                seq_times is not None
+                and matched_indices
+                and not _check_temporal_constraints(seq_idx, matched_indices, seq_times, mingap, maxgap)
+            ):
+                # Skip this occurrence and continue searching for a valid one
+                continue
+
+            matched_indices.append(seq_idx)
+            sub_idx += 1
+
+            # If we've matched the entire subsequence, check maxspan
+            if sub_idx == len_sub:
+                return _check_maxspan(matched_indices, seq_times, maxspan)
+
+    return False
+
+
+def _check_temporal_constraints(
+    seq_idx: int,
+    matched_indices: List[int],
+    seq_times: Tuple[float, ...],
+    mingap: Optional[float],
+    maxgap: Optional[float],
+) -> bool:
+    """
+    Check if temporal constraints are satisfied for a new match.
+
+    Args:
+        seq_idx: Current sequence index
+        matched_indices: Previously matched indices
+        seq_times: Timestamps
+        mingap: Minimum gap constraint
+        maxgap: Maximum gap constraint
+
+    Returns:
+        True if constraints satisfied, False otherwise
+    """
+    prev_idx = matched_indices[-1]
+    time_gap = seq_times[seq_idx] - seq_times[prev_idx]
+
+    # Check mingap constraint
+    if mingap is not None and time_gap < mingap:
+        return False
+
+    # Check maxgap constraint
+    if maxgap is not None and time_gap > maxgap:
+        return False
+
+    return True
+
+
+def _check_maxspan(
+    matched_indices: List[int],
+    seq_times: Optional[Tuple[float, ...]],
+    maxspan: Optional[float],
+) -> bool:
+    """
+    Check if maxspan constraint is satisfied.
+
+    Args:
+        matched_indices: Matched sequence indices
+        seq_times: Timestamps (None if not present)
+        maxspan: Maximum span constraint
+
+    Returns:
+        True if constraint satisfied or not applicable, False otherwise
+    """
+    if seq_times is not None and maxspan is not None:
+        first_idx = matched_indices[0]
+        last_idx = matched_indices[-1]
+        span = seq_times[last_idx] - seq_times[first_idx]
+        if span > maxspan:
+            return False
+
+    return True
+
+
 def generate_candidates_from_previous(prev_patterns: Dict[Tuple[str, ...], int]) -> List[Tuple[str, ...]]:
     """
     Generate joined candidates from the previous level's frequent patterns.
@@ -96,7 +376,7 @@ def generate_candidates_from_previous(prev_patterns: Dict[Tuple[str, ...], int])
     Returns:
         List[Tuple]: Candidate patterns for the next level.
     """
-    keys = list(prev_patterns.keys())
+    keys: List[Tuple[str, ...]] = list(prev_patterns.keys())
     return [
         pattern1 + (pattern2[-1],)
         for pattern1, pattern2 in product(keys, repeat=2)

{gsppy-3.3.0.dist-info → gsppy-3.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gsppy
-Version: 3.3.0
+Version: 3.5.0
 Summary: GSP (Generalized Sequence Pattern) algorithm in Python
 Project-URL: Homepage, https://github.com/jacksonpradolima/gsp-py
 Author-email: Jackson Antonio do Prado Lima <jacksonpradolima@gmail.com>
@@ -41,27 +41,28 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0.0
 Provides-Extra: dev
-Requires-Dist: cython==3.2.3; extra == 'dev'
-Requires-Dist: hatch==1.16.2; extra == 'dev'
+Requires-Dist: cython==3.2.4; extra == 'dev'
+Requires-Dist: hatch==1.16.3; extra == 'dev'
 Requires-Dist: hatchling==1.28.0; extra == 'dev'
+Requires-Dist: hypothesis<7.0.0,>=6.0.0; extra == 'dev'
 Requires-Dist: pylint==4.0.4; extra == 'dev'
-Requires-Dist: pyright==1.1.407; extra == 'dev'
+Requires-Dist: pyright==1.1.408; extra == 'dev'
 Requires-Dist: pytest-benchmark==5.2.3; extra == 'dev'
 Requires-Dist: pytest-cov==7.0.0; extra == 'dev'
 Requires-Dist: pytest==9.0.2; extra == 'dev'
-Requires-Dist: ruff==0.14.10; extra == 'dev'
-Requires-Dist: tox==4.32.0; extra == 'dev'
-Requires-Dist: ty==0.0.8; extra == 'dev'
+Requires-Dist: ruff==0.14.13; extra == 'dev'
+Requires-Dist: tox==4.34.1; extra == 'dev'
+Requires-Dist: ty==0.0.12; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-gen-files<1,>=0.5; extra == 'docs'
 Requires-Dist: mkdocs-literate-nav<1,>=0.6; extra == 'docs'
 Requires-Dist: mkdocs-material<10,>=9.5; extra == 'docs'
 Requires-Dist: mkdocs<2,>=1.6; extra == 'docs'
-Requires-Dist: mkdocstrings[python]<0.27,>=0.26; extra == 'docs'
+Requires-Dist: mkdocstrings[python]<1.1,>=0.26; extra == 'docs'
 Provides-Extra: gpu
 Requires-Dist: cupy<14,>=11; extra == 'gpu'
 Provides-Extra: rust
-Requires-Dist: maturin==1.10.2; extra == 'rust'
+Requires-Dist: maturin==1.11.5; extra == 'rust'
 Description-Content-Type: text/markdown
 
 [![Docs](https://img.shields.io/badge/Docs-GSP--Py%20Site-3D9970?style=flat-square)](https://jacksonpradolima.github.io/gsp-py/)
@@ -104,6 +105,7 @@ Sequence Pattern (GSP)** algorithm. Ideal for market basket analysis, temporal m
 6. [💡 Usage](#usage)
     - [✅ Example: Analyzing Sales Data](#example-analyzing-sales-data)
     - [📊 Explanation: Support and Results](#explanation-support-and-results)
+    - [⏱️ Temporal Constraints](#temporal-constraints)
 7. [⌨️ Typing](#typing)
 8. [🌟 Planned Features](#planned-features)
 9. [🤝 Contributing](#contributing)
@@ -122,6 +124,7 @@ principles**. Using support thresholds, GSP identifies frequent sequences of ite
 - **Ordered (non-contiguous) matching**: Detects patterns where items appear in order but not necessarily adjacent, following standard GSP semantics. For example, the pattern `('A', 'C')` is found in the sequence `['A', 'B', 'C']`.
 - **Support-based pruning**: Only retains sequences that meet the minimum support threshold.
 - **Candidate generation**: Iteratively generates candidate sequences of increasing length.
+- **Temporal constraints**: Support for time-constrained pattern mining with `mingap`, `maxgap`, and `maxspan` parameters to find patterns within specific time windows.
 - **General-purpose**: Useful in retail, web analytics, social networks, temporal sequence mining, and more.
 
 For example:
@@ -372,7 +375,28 @@ gsppy --file path/to/transactions.csv --min_support 0.3 --backend rust
 - `--file`: Path to your input file (JSON or CSV). **Required**.
 - `--min_support`: Minimum support threshold as a fraction (e.g., `0.3` for 30%). Default is `0.2`.
 - `--backend`: Backend to use for support counting. One of `auto` (default), `python`, `rust`, or `gpu`.
-- `--verbose`: (Optional) Enable detailed output for debugging.
+- `--verbose`: Enable detailed logging with timestamps, log levels, and process IDs for debugging and traceability.
+- `--mingap`, `--maxgap`, `--maxspan`: Temporal constraints for time-aware pattern mining (requires timestamped transactions).
+
+#### Verbose Mode
+
+For debugging or to track execution in CI/CD pipelines, use the `--verbose` flag:
+
+```bash
+gsppy --file transactions.json --min_support 0.3 --verbose
+```
+
+This produces structured logging output with timestamps, log levels, and process information:
+
+```
+YYYY-MM-DDTHH:MM:SS | INFO     | PID:4179 | gsppy.gsp | Pre-processing transactions...
+YYYY-MM-DDTHH:MM:SS | DEBUG    | PID:4179 | gsppy.gsp | Unique candidates: [('Bread',), ('Milk',), ...]
+YYYY-MM-DDTHH:MM:SS | INFO     | PID:4179 | gsppy.gsp | Starting GSP algorithm with min_support=0.3...
+YYYY-MM-DDTHH:MM:SS | INFO     | PID:4179 | gsppy.gsp | Run 1: 6 candidates filtered to 5.
+...
+```
+
+For complete logging documentation, see [docs/logging.md](docs/logging.md).
 
 #### Example
 
@@ -469,6 +493,30 @@ result = GSP(transactions).search(min_support)
 print(result)
 ```
 
+### Verbose Mode for Debugging
+
+Enable detailed logging to track algorithm progress and debug issues:
+
+```python
+from gsppy.gsp import GSP
+
+# Enable verbose logging for the entire instance
+gsp = GSP(transactions, verbose=True)
+result = gsp.search(min_support=0.3)
+
+# Or enable verbose for a specific search only
+gsp = GSP(transactions)
+result = gsp.search(min_support=0.3, verbose=True)
+```
+
+Verbose mode provides:
+- Detailed progress information during execution
+- Candidate generation and filtering statistics
+- Preprocessing and validation details
+- Useful for debugging, research, and CI/CD integration
+
+For complete documentation on logging, see [docs/logging.md](docs/logging.md).
+
 ### Output
 
 The algorithm will return a list of patterns with their corresponding support.
@@ -535,6 +583,128 @@ result = gsp.search(min_support=0.5)  # Need at least 2/4 sequences
 
 ---
 
+## ⏱️ Temporal Constraints
+
+GSP-Py supports **time-constrained sequential pattern mining** with three powerful temporal constraints: `mingap`, `maxgap`, and `maxspan`. These constraints enable domain-specific applications such as medical event mining, retail analytics, and temporal user journey discovery.
+
+### Temporal Constraint Parameters
+
+- **`mingap`**: Minimum time gap required between consecutive items in a pattern
+- **`maxgap`**: Maximum time gap allowed between consecutive items in a pattern  
+- **`maxspan`**: Maximum time span from the first to the last item in a pattern
+
+### Using Temporal Constraints
+
+To use temporal constraints, your transactions must include timestamps as (item, timestamp) tuples:
+
+```python
+from gsppy.gsp import GSP
+
+# Transactions with timestamps (e.g., in seconds, hours, days, etc.)
+timestamped_transactions = [
+    [("Login", 0), ("Browse", 2), ("AddToCart", 5), ("Purchase", 7)],
+    [("Login", 0), ("Browse", 1), ("AddToCart", 15), ("Purchase", 20)],
+    [("Login", 0), ("Browse", 3), ("AddToCart", 6), ("Purchase", 8)],
+]
+
+# Find patterns where consecutive events occur within 10 time units
+gsp = GSP(timestamped_transactions, maxgap=10)
+patterns = gsp.search(min_support=0.6)
+
+# The pattern ("Browse", "AddToCart", "Purchase") will:
+# - Be found in transaction 1: gaps are 3 and 2 (both ≤ 10) ✅
+# - NOT be found in transaction 2: gap between Browse→AddToCart is 14 (exceeds maxgap) ❌
+# - Be found in transaction 3: gaps are 3 and 2 (both ≤ 10) ✅
+# Result: Support = 2/3 = 67% (above threshold of 60%)
+```
+
+### CLI Usage with Temporal Constraints
+
+```bash
+# Find patterns with maximum gap of 5 time units
+gsppy --file temporal_data.json --min_support 0.3 --maxgap 5
+
+# Find patterns with minimum gap of 2 time units
+gsppy --file temporal_data.json --min_support 0.3 --mingap 2
+
+# Find patterns that complete within 10 time units
+gsppy --file temporal_data.json --min_support 0.3 --maxspan 10
+
+# Combine multiple constraints
+gsppy --file temporal_data.json --min_support 0.3 --mingap 1 --maxgap 5 --maxspan 10
+```
+
+### Real-World Examples
+
+#### Medical Event Mining
+
+```python
+from gsppy.gsp import GSP
+
+# Medical events with timestamps in days
+medical_sequences = [
+    [("Symptom", 0), ("Diagnosis", 2), ("Treatment", 5), ("Recovery", 15)],
+    [("Symptom", 0), ("Diagnosis", 1), ("Treatment", 20), ("Recovery", 30)],
+    [("Symptom", 0), ("Diagnosis", 3), ("Treatment", 6), ("Recovery", 18)],
+]
+
+# Find patterns where treatment follows diagnosis within 10 days
+gsp = GSP(medical_sequences, maxgap=10)
+result = gsp.search(min_support=0.5)
+
+# Pattern ("Diagnosis", "Treatment") found in sequences 1 & 3 only
+# (sequence 2 has gap of 19 days, exceeding maxgap)
+```
+
+#### Retail Analytics
+
+```python
+from gsppy.gsp import GSP
+
+# Customer purchases with timestamps in hours
+purchase_sequences = [
+    [("Browse", 0), ("AddToCart", 0.5), ("Purchase", 1)],
+    [("Browse", 0), ("AddToCart", 1), ("Purchase", 25)],  # Long delay
+    [("Browse", 0), ("AddToCart", 0.3), ("Purchase", 0.8)],
+]
+
+# Find purchase journeys that complete within 2 hours
+gsp = GSP(purchase_sequences, maxspan=2)
+result = gsp.search(min_support=0.5)
+
+# Full sequence found in 2 out of 3 transactions
+# (sequence 2 has span of 25 hours, exceeding maxspan)
+```
+
+#### User Journey Discovery
+
+```python
+from gsppy.gsp import GSP
+
+# Website navigation with timestamps in seconds
+navigation_sequences = [
+    [("Home", 0), ("Search", 5), ("Product", 10), ("Checkout", 15)],
+    [("Home", 0), ("Search", 3), ("Product", 8), ("Checkout", 180)],
+    [("Home", 0), ("Search", 4), ("Product", 9), ("Checkout", 14)],
+]
+
+# Find navigation patterns with:
+# - Minimum 2 seconds between steps (mingap)
+# - Maximum 20 seconds between steps (maxgap)
+# - Complete within 30 seconds total (maxspan)
+gsp = GSP(navigation_sequences, mingap=2, maxgap=20, maxspan=30)
+result = gsp.search(min_support=0.5)
+```
+
+### Important Notes
+
+- Temporal constraints require timestamped transactions (item-timestamp tuples)
+- If temporal constraints are specified but transactions don't have timestamps, a warning is logged and constraints are ignored
+- When using temporal constraints, the Python backend is automatically used (accelerated backends don't yet support temporal constraints)
+- Timestamps can be in any unit (seconds, minutes, hours, days) as long as they're consistent within your dataset
+
+---
+
 ## ⌨️ Typing
 
 `gsppy` ships inline type information (PEP 561) via a bundled `py.typed` marker. The public API is re-exported from
@@ -554,11 +724,6 @@ We are actively working to improve GSP-Py. Here are some exciting features plann
 2. **Support for Preprocessing and Postprocessing**:
     - Add hooks to allow users to transform datasets before mining and customize the output results.
 
-3. **Support for Time-Constrained Pattern Mining**:
-    - Extend GSP-Py to handle temporal datasets by allowing users to define time constraints (e.g., maximum time gaps
-      between events, time windows) during the sequence mining process.
-    - Enable candidate pruning and support calculations based on these temporal constraints.
-
 Want to contribute or suggest an
 improvement? [Open a discussion or issue!](https://github.com/jacksonpradolima/gsp-py/issues)
 
@@ -583,16 +748,34 @@ uv run ruff check .
 uv run pyright
 ```
 
+### Testing & Fuzzing
+
+GSP-Py includes comprehensive test coverage, including property-based fuzzing tests using [Hypothesis](https://hypothesis.readthedocs.io/). These fuzzing tests automatically generate random inputs to verify algorithm invariants and discover edge cases. Run the fuzzing tests with:
+
+```bash
+uv run pytest tests/test_gsp_fuzzing.py -v
+```
+
 ### General Steps:
 
 1. Fork the repository.
 2. Create a feature branch: `git checkout -b feature/my-feature`.
-3. Commit your changes: `git commit -m "Add my feature."`
+3. Commit your changes using [Conventional Commits](https://www.conventionalcommits.org/) format: `git commit -m "feat: add my feature"`.
 4. Push to your branch: `git push origin feature/my-feature`.
 5. Submit a pull request to the main repository!
 
 Looking for ideas? Check out our [Planned Features](#planned-features) section.
 
+### Release Management
+
+GSP-Py uses automated release management with [Conventional Commits](https://www.conventionalcommits.org/). When commits are merged to `main`:
+- **Releases are triggered** by: `fix:` (patch), `feat:` (minor), `perf:` (patch), or `BREAKING CHANGE:` (major)
+- **No release** for: `docs:`, `style:`, `refactor:`, `test:`, `build:`, `ci:`, `chore:`
+- CHANGELOG.md is automatically updated with structured release notes
+- Git tags and GitHub releases are created automatically
+
+See [Release Management Guide](docs/RELEASE_MANAGEMENT.md) for details on commit message format and release process.
+
 ---
 
 ## 📝 License

gsppy-3.5.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+gsppy/__init__.py,sha256=NMVa-ZWT449wuxZMF9Ym7p-DChOxOibaaqlpPxksfuo,805
+gsppy/accelerate.py,sha256=rDho3ysADETpuhT2SF9voBjd3XRaQUzuA5k_baNACF8,11020
+gsppy/cli.py,sha256=-viXa8VFIF-QvrHYy1vtDxtMm50sM_tZq5B5DMZ1Jtw,12516
+gsppy/gsp.py,sha256=k72pvdmD6jU4AId2rrHQrJ4FBUgtkuC0ntEY8QHGi5c,24486
+gsppy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gsppy/utils.py,sha256=dAEq1hEZMN0ZjoocKs_ZIgOI9j_Y6rJEAKneul3zNRo,13501
+gsppy-3.5.0.dist-info/METADATA,sha256=ix2X_VEUTved_DaTsSJMERT-CZ34TUYF0XMC2KeNeuE,29747
+gsppy-3.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+gsppy-3.5.0.dist-info/entry_points.txt,sha256=smvmcIWk424ARIGKOC_BM42hpT_SptKPcIeqs-8u8lM,41
+gsppy-3.5.0.dist-info/licenses/LICENSE,sha256=AlXanKSqFzo_o-87gp3Qw3XzbmnfxYy7O0xJOcQGWJo,1086
+gsppy-3.5.0.dist-info/RECORD,,

gsppy-3.3.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-gsppy/__init__.py,sha256=FcWEYkzMCiqIBmc4yhgIXFKzvSNjJA7LX7juUabvoJ4,784
-gsppy/accelerate.py,sha256=2I3IA42FyPZvfwc0-f0bovZ8YgbdvJXj0qDlYWSWiXI,10998
-gsppy/cli.py,sha256=W5udAPKOjlxi-c-RKcz5HW-sDgoap4ojHD87bd-X498,6583
-gsppy/gsp.py,sha256=aCtPrldVNCkwj6wwytrZzbayYKkXi9Om-3xzrHUMkLQ,15293
-gsppy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-gsppy/utils.py,sha256=KtjfDgsTwvwxIyA2KCQmgu8cFkBqQvMZN8Ct5NB60Tc,3952
-gsppy-3.3.0.dist-info/METADATA,sha256=VQtJqYCs9I4HnO5EpEeI9SijBxxgaNir_mw1HMmWKlw,22727
-gsppy-3.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-gsppy-3.3.0.dist-info/entry_points.txt,sha256=smvmcIWk424ARIGKOC_BM42hpT_SptKPcIeqs-8u8lM,41
-gsppy-3.3.0.dist-info/licenses/LICENSE,sha256=AlXanKSqFzo_o-87gp3Qw3XzbmnfxYy7O0xJOcQGWJo,1086
-gsppy-3.3.0.dist-info/RECORD,,