"""
Position-Based Sequence Encoding
================================

Topics: PositionBindingEncoder, order sensitivity, sequence similarity
Time: 15 minutes
Prerequisites: 00_quickstart.py, 01_basic_operations.py
Related: 14_encoders_ngram.py, 15_encoders_trajectory.py

This example demonstrates the PositionBindingEncoder, which encodes sequences
by binding each element to a unique position vector. This creates order-sensitive
representations where different arrangements of the same elements produce distinct
hypervectors.

Key concepts:
- Position binding: bind(symbol_i, position_i) for each element
- Order sensitivity: permutations are distinguishable
- Sequence similarity: shared prefixes increase similarity
- Reversible encoding: can decode to recover symbols

The PositionBindingEncoder is fundamental for text processing, time series,
and any ordered data where position matters.
"""

from holovec import VSA
from holovec.encoders import PositionBindingEncoder

print("=" * 70)
print("Position-Based Sequence Encoding")
print("=" * 70)
print()

# ============================================================================
# Demo 1: Basic Usage
# ============================================================================
print("=" * 70)
print("Demo 1: Basic PositionBindingEncoder Usage")
print("=" * 70)

# Create model
model = VSA.create('MAP', dim=5000, seed=42)

# Create encoder
encoder = PositionBindingEncoder(model, seed=42)

print(f"\nEncoder: {encoder}")
print(f"Reversible: {encoder.is_reversible}")
print(f"Compatible models: {encoder.compatible_models}")

# Encode some sequences
sequences = [
    ['hello', 'world'],
    ['hello', 'world', '!'],
    ['goodbye', 'world'],
    ['world', 'hello']  # Reversed order
]

print("\nEncoding sequences:")
encoded = []
for seq in sequences:
    hv = encoder.encode(seq)
    encoded.append(hv)
    print(f"  {seq} → HV shape: {hv.shape}")

# Check similarities
print("\nSimilarity Matrix:")
for i, seq1 in enumerate(sequences):
    similarities = []
    for j, seq2 in enumerate(sequences):
        sim = float(model.similarity(encoded[i], encoded[j]))
        similarities.append(sim)
    seq_str = str(seq1)[:30].ljust(30)
    sims_str = "  ".join(f"{s:5.3f}" for s in similarities)
    print(f"{seq_str} | {sims_str}")

# Test decoding
print("\nDecoding test (first 3 positions):")
for i, seq in enumerate(sequences[:2]):  # Only decode first 2
    decoded = encoder.decode(encoded[i], max_positions=5, threshold=0.2)
    print(f"  Original: {seq}")
    print(f"  Decoded:  {decoded}\n")

print("Key observations:")
print("  - Identical sequences have similarity ≈ 1.0")
print("  - Shared prefix increases similarity")
print("  - Different order creates different encodings")
print("  - Decoding recovers first few symbols accurately")

# ============================================================================
# Demo 2: Order Sensitivity
# ============================================================================
print("\n" + "=" * 70)
print("Demo 2: Order Sensitivity")
print("=" * 70)

# Test order sensitivity
original = ['a', 'b', 'c', 'd']
permutations = [
    (['a', 'b', 'c', 'd'], "Original"),
    (['d', 'c', 'b', 'a'], "Reversed"),
    (['b', 'c', 'd', 'a'], "Rotated 1"),
    (['c', 'd', 'a', 'b'], "Rotated 2"),
]

print("\nTesting order sensitivity:")
ref_hv = encoder.encode(original)

print(f"Reference: {original}")
print("\nSequence              | Similarity | Description")
print("-" * 60)

for seq, desc in permutations:
    hv = encoder.encode(seq)
    sim = float(model.similarity(ref_hv, hv))
    seq_str = str(seq).ljust(20)
    print(f"{seq_str} | {sim:10.3f} | {desc}")

print("\nKey observation:")
print("  - Different orders produce distinct encodings")
print("  - Even rotations are clearly distinguishable")

# ============================================================================
# Demo 3: Sequence Similarity
# ============================================================================
print("\n" + "=" * 70)
print("Demo 3: Sequence Similarity and Prefix Matching")
print("=" * 70)

# Test prefix matching
reference = ['the', 'quick', 'brown', 'fox', 'jumps']
variants = [
    (['the', 'quick', 'brown', 'fox', 'jumps'], "Identical"),
    (['the', 'quick', 'brown', 'fox'], "Prefix (4/5)"),
    (['the', 'quick', 'brown'], "Prefix (3/5)"),
    (['the', 'quick'], "Prefix (2/5)"),
    (['the'], "Prefix (1/5)"),
    (['the', 'slow', 'brown', 'fox', 'walks'], "1 match only"),
    (['a', 'completely', 'different', 'sentence'], "No match"),
]

print(f"\nReference: {reference}")
print("\nSequence                                | Similarity | Shared")
print("-" * 70)

ref_hv = encoder.encode(reference)

for seq, desc in variants:
    hv = encoder.encode(seq)
    sim = float(model.similarity(ref_hv, hv))
    seq_str = str(seq)[:40].ljust(40)
    print(f"{seq_str} | {sim:10.3f} | {desc}")

print("\nKey observations:")
print("  - Longer shared prefix → higher similarity")
print("  - Similarity degrades gracefully with differences")
print("  - Enables approximate sequence matching")

# ============================================================================
# Summary
# ============================================================================
print("\n" + "=" * 70)
print("Summary: PositionBindingEncoder Key Takeaways")
print("=" * 70)
print()
print("✓ Order-sensitive: Different arrangements are distinguishable")
print("✓ Prefix similarity: Shared prefixes increase similarity")
print("✓ Reversible: Can decode to recover original symbols")
print("✓ Foundation for text: Used in n-gram and language models")
print("✓ Works with all models: Compatible with MAP, FHRR, HRR, BSC, BSDC")
print()
print("Use cases:")
print("  - Text processing: words in sentences")
print("  - Time series: events in temporal order")
print("  - Structured data: ordered records")
print("  - Sequences: any data where position matters")
print()
print("Next steps:")
print("  → 14_encoders_ngram.py - N-gram text encoding")
print("  → 15_encoders_trajectory.py - Continuous sequences")
print("  → 20_app_text_classification.py - Apply to real text data")
print()
print("=" * 70)