Skip to content

feat(M83): Divergence Heatmap by Token Position #185

@hlin99

Description

@hlin99

Problem

When analyzing batch comparison results, it's unclear whether divergences cluster at specific token positions (early prefill vs late decode).

Solution

Add xpyd-acc heatmap --report <path> command that:

  • Analyzes divergence frequency by token position across all samples
  • Bins token positions into configurable buckets (default 10)
  • Per-bucket: divergence count, divergence rate, avg logprob gap
  • HeatmapBucket and HeatmapReport dataclasses with to_dict() serialization
  • --buckets <int> flag, --json <path> export
  • Rich terminal bar chart showing divergence frequency by position range

Acceptance Criteria

  • heatmap.py module with compute_heatmap(), HeatmapReport, format_heatmap()
  • CLI subcommand heatmap with --report, --buckets, --json flags
  • Rich bar chart output
  • 12+ tests covering bucket computation, edge cases, formatting, JSON export, CLI
  • All lint/tests pass

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions