publisher/tasks/highlights.py

import uuid
from datetime import datetime


# -------------------------------------------------
# UTILITIES
# -------------------------------------------------

def clamp(value, min_v=0, max_v=1):
    return max(min_v, min(max_v, value))


def safe_len(x):
    try:
        return len(x)
    except Exception:
        return 0


# -------------------------------------------------
# CORE HIGHLIGHT DETECTION ENGINE
# -------------------------------------------------

def detect_peak_density(words, window=12):
    """
    Simple sliding window density heuristic.
    Returns indices where speech intensity peaks.
    """

    if not words or len(words) < window:
        return []

    scores = []

    for i in range(len(words) - window):
        chunk = words[i:i + window]

        # heuristic: repetition + punctuation + trigger words
        unique_ratio = len(set(chunk)) / window

        trigger_words = {"why", "how", "what", "secret", "hack", "never", "stop", "crazy", "insane"}
        trigger_hits = sum(1 for w in chunk if str(w).lower() in trigger_words)

        score = (1 - unique_ratio) + (trigger_hits * 0.15)

        scores.append((i, score))

    # sort by strongest signal
    scores.sort(key=lambda x: x[1], reverse=True)

    # take top peaks (non-overlapping)
    selected = []
    used = set()

    for idx, _ in scores:
        if any(abs(idx - u) < window for u in used):
            continue
        selected.append(idx)
        used.add(idx)
        if len(selected) >= 8:  # max clips
            break

    return selected


def build_segments(words, indices, window=20):
    """
    Convert peak indices into structured segments.
    """

    segments = []

    for idx in indices:
        start = max(0, idx - window // 2)
        end = min(len(words), idx + window // 2)

        segment_words = words[start:end]

        if not segment_words:
            continue

        segments.append({
            "id": str(uuid.uuid4()),
            "start_index": start,
            "end_index": end,
            "words": segment_words,
            "length": len(segment_words),
        })

    return segments


# -------------------------------------------------
# FALLBACK MODE (NO SIGNAL DETECTED)
# -------------------------------------------------

def fallback_segments(words):
    """
    Ensures highlights always exist even for weak input.
    """

    if not words:
        return []

    chunk_size = max(25, len(words) // 5)

    segments = []

    for i in range(0, len(words), chunk_size):
        chunk = words[i:i + chunk_size]

        segments.append({
            "id": str(uuid.uuid4()),
            "start_index": i,
            "end_index": i + len(chunk),
            "words": chunk,
            "length": len(chunk),
        })

        if len(segments) >= 5:
            break

    return segments


# -------------------------------------------------
# MAIN ENTRYPOINT (REGISTRY COMPATIBLE)
# -------------------------------------------------

def run(context):
    """
    Expected input:
    {
        "words": [...]
    }
    """

    batch_id = str(uuid.uuid4())
    started_at = datetime.utcnow().isoformat()

    try:

        words = []

        if isinstance(context, dict):
            words = context.get("words", [])
        else:
            words = getattr(context, "words", []) or []

        # -------------------------------------------------
        # DETECT PEAKS
        # -------------------------------------------------

        peak_indices = detect_peak_density(words)

        if peak_indices:
            segments = build_segments(words, peak_indices)
        else:
            segments = fallback_segments(words)

        # -------------------------------------------------
        # OUTPUT CONTRACT
        # -------------------------------------------------

        return {
            "status": "success",
            "task": "highlights",
            "batch_id": batch_id,
            "started_at": started_at,
            "completed_at": datetime.utcnow().isoformat(),

            # core output for downstream clipper
            "highlights": segments,

            # UI-friendly summary
            "summary": {
                "total_words": safe_len(words),
                "segments_found": len(segments),
                "peak_detection": bool(peak_indices),
            }
        }

    except Exception as e:

        return {
            "status": "error",
            "task": "highlights",
            "batch_id": batch_id,
            "message": str(e),
            "stage": "highlight_detection_failed",
            "highlights": []
        }