feat: introduce Sequence abstraction for typed pattern representation

Author: jacksonpradolima

README.md

@@ -486,6 +486,82 @@ Verbose mode provides:
 
 For complete documentation on logging, see [docs/logging.md](docs/logging.md).
 
+### Using Sequence Objects for Rich Pattern Representation
+
+GSP-Py 4.0+ introduces a **Sequence abstraction class** that provides a richer, more maintainable way to work with sequential patterns. The Sequence class encapsulates pattern items, support counts, and optional metadata in an immutable, hashable object.
+
+#### Traditional Dict-based Output (Default)
+
+```python
+from gsppy import GSP
+
+transactions = [
+    ['Bread', 'Milk'],
+    ['Bread', 'Diaper', 'Beer', 'Eggs'],
+    ['Milk', 'Diaper', 'Beer', 'Coke']
+]
+
+gsp = GSP(transactions)
+result = gsp.search(min_support=0.3)
+
+# Returns: [{('Bread',): 4, ('Milk',): 4, ...}, {('Bread', 'Milk'): 3, ...}, ...]
+for level_patterns in result:
+    for pattern, support in level_patterns.items():
+        print(f"Pattern: {pattern}, Support: {support}")
+```
+
+#### Sequence Objects (New Feature)
+
+```python
+from gsppy import GSP
+
+transactions = [
+    ['Bread', 'Milk'],
+    ['Bread', 'Diaper', 'Beer', 'Eggs'],
+    ['Milk', 'Diaper', 'Beer', 'Coke']
+]
+
+gsp = GSP(transactions)
+result = gsp.search(min_support=0.3, return_sequences=True)
+
+# Returns: [[Sequence(('Bread',), support=4), ...], [Sequence(('Bread', 'Milk'), support=3), ...], ...]
+for level_patterns in result:
+    for seq in level_patterns:
+        print(f"Pattern: {seq.items}, Support: {seq.support}, Length: {seq.length}")
+        # Access sequence properties
+        print(f"  First item: {seq.first_item}, Last item: {seq.last_item}")
+        # Check if item is in sequence
+        if "Milk" in seq:
+            print(f"  Contains Milk!")
+```
+
+#### Key Benefits of Sequence Objects
+
+1. **Rich API**: Access pattern properties like `length`, `first_item`, `last_item`
+2. **Type Safety**: IDE autocomplete and better type hints
+3. **Immutable & Hashable**: Can be used as dictionary keys
+4. **Extensible**: Add metadata for confidence, lift, or custom properties
+5. **Backward Compatible**: Convert to/from dict format as needed
+
+```python
+from gsppy import Sequence, sequences_to_dict, dict_to_sequences
+
+# Create custom sequences
+seq = Sequence.from_tuple(("A", "B", "C"), support=5)
+
+# Extend sequences
+extended = seq.extend("D")  # Creates Sequence(("A", "B", "C", "D"))
+
+# Add metadata
+seq_with_meta = seq.with_metadata(confidence=0.85, lift=1.5)
+
+# Convert between formats for compatibility
+seq_result = gsp.search(min_support=0.3, return_sequences=True)
+dict_format = sequences_to_dict(seq_result[0])  # Convert to dict
+```
+
+For a complete example, see [examples/sequence_example.py](examples/sequence_example.py).
+
 ### Loading SPM/GSP Format Files
 
 GSP-Py supports loading datasets in the classical SPM/GSP delimiter format, which is widely used in sequential pattern mining research. This format uses:

docs/api.md

@@ -9,6 +9,30 @@
         - search
       show_submodules: false
 
+## Sequence
+
+::: gsppy.sequence.Sequence
+    options:
+      members:
+        - from_tuple
+        - from_item
+        - extend
+        - with_support
+        - with_metadata
+        - as_tuple
+        - length
+        - first_item
+        - last_item
+      show_submodules: false
+
+## Sequence Utilities
+
+::: gsppy.sequence.sequences_to_dict
+
+::: gsppy.sequence.dict_to_sequences
+
+::: gsppy.sequence.to_sequence
+
 ## Acceleration utilities
 
 ::: gsppy.accelerate.support_counts

docs/index.md

@@ -6,6 +6,7 @@ Pattern (GSP) algorithm. Use this site to install the library, explore the CLI,
 ## Highlights
 
 - **Sequence mining** with support-based pruning and candidate generation.
+- **Sequence abstraction** for typed pattern representation with rich metadata support.
 - **Multiple data formats** including JSON, CSV, SPM/GSP, Parquet, and Arrow.
 - **Token mapping utilities** for transparent string ↔ integer conversion.
 - **Optional acceleration** via Rust and GPU backends.
@@ -33,6 +34,29 @@ for level, freq_patterns in enumerate(patterns, start=1):
     print(f"Level {level}: {freq_patterns}")
 ```
 
+### Using Sequence Objects (New in 4.0+)
+
+Get richer pattern representation with typed Sequence objects:
+
+```python
+from gsppy import GSP
+
+transactions = [
+    ["Bread", "Milk"],
+    ["Bread", "Diaper", "Beer", "Eggs"],
+    ["Milk", "Diaper", "Beer", "Coke"],
+]
+
+# Enable Sequence objects
+patterns = GSP(transactions).search(min_support=0.3, return_sequences=True)
+
+for level_patterns in patterns:
+    for seq in level_patterns:
+        print(f"{seq.items} (support={seq.support}, length={seq.length})")
+        if "Milk" in seq:
+            enriched = seq.with_metadata(confidence=0.85)
+```
+
 ### Loading from SPM/GSP Format
 
 ```python

docs/usage.md

@@ -138,6 +138,115 @@ model = GSP(transactions)
 frequent = model.search(min_support=0.5)
 ```
 
+## Using Sequence Objects
+
+GSP-Py 4.0+ introduces a **Sequence abstraction** that provides a richer, more maintainable way to work with sequential patterns. The Sequence class encapsulates pattern items, support counts, and optional metadata.
+
+### Traditional Dict-based Output (Default)
+
+By default, GSP returns patterns as dictionaries mapping tuples to support counts:
+
+```python
+from gsppy import GSP
+
+transactions = [
+    ["Bread", "Milk"],
+    ["Bread", "Diaper", "Beer", "Eggs"],
+    ["Milk", "Diaper", "Beer", "Coke"],
+]
+
+gsp = GSP(transactions)
+result = gsp.search(min_support=0.3)
+
+# Returns: [{('Bread',): 4, ('Milk',): 4, ...}, ...]
+for level_patterns in result:
+    for pattern, support in level_patterns.items():
+        print(f"Pattern: {pattern}, Support: {support}")
+```
+
+### Sequence Objects (New Feature)
+
+Enable the new Sequence objects by setting `return_sequences=True`:
+
+```python
+from gsppy import GSP
+
+transactions = [
+    ["Bread", "Milk"],
+    ["Bread", "Diaper", "Beer", "Eggs"],
+    ["Milk", "Diaper", "Beer", "Coke"],
+]
+
+gsp = GSP(transactions)
+result = gsp.search(min_support=0.3, return_sequences=True)
+
+# Returns: [[Sequence(('Bread',), support=4), ...], ...]
+for level_patterns in result:
+    for seq in level_patterns:
+        print(f"Pattern: {seq.items}")
+        print(f"Support: {seq.support}")
+        print(f"Length: {seq.length}")
+        
+        # Rich API
+        if "Milk" in seq:
+            print("Contains Milk!")
+```
+
+### Sequence Properties and Methods
+
+The Sequence class provides a rich API:
+
+```python
+from gsppy import Sequence
+
+# Create sequences
+seq = Sequence.from_tuple(("A", "B", "C"), support=5)
+
+# Access properties
+print(seq.items)        # ('A', 'B', 'C')
+print(seq.support)      # 5
+print(seq.length)       # 3
+print(seq.first_item)   # 'A'
+print(seq.last_item)    # 'C'
+
+# Operations
+extended = seq.extend("D")  # Sequence(('A', 'B', 'C', 'D'))
+updated = seq.with_support(10)
+enriched = seq.with_metadata(confidence=0.85, lift=1.5)
+
+# Check membership
+if "B" in seq:
+    print("Sequence contains B")
+
+# Iterate over items
+for item in seq:
+    print(item)
+
+# Convert to tuple for compatibility
+tuple_form = seq.as_tuple()  # ('A', 'B', 'C')
+```
+
+### Converting Between Formats
+
+Use utility functions to convert between Sequence objects and dict format:
+
+```python
+from gsppy import sequences_to_dict, dict_to_sequences
+
+# Get results as Sequences
+result = gsp.search(min_support=0.3, return_sequences=True)
+
+# Convert to dict format for compatibility
+dict_format = sequences_to_dict(result[0])
+# {('Bread',): 4, ('Milk',): 4, ...}
+
+# Convert back to Sequences
+sequences = dict_to_sequences(dict_format)
+# [Sequence(('Bread',), support=4), ...]
+```
+
+For a complete example demonstrating all Sequence features, see `examples/sequence_example.py` in the repository.
+
 ## Verbose Mode
 
 Enable detailed logging to track algorithm progress and debug issues: