feat: k-mer-seeded top-k ungapped local alignment (0.6.0)

[folded]

Summary

New entry point top_k_ungapped_local_align_kmer — a BLAST-style seed-and-extend alternative to top_k_ungapped_local_align for callers working on long inputs over moderate-sized alphabets. Same Alignment shape and overlap semantics; drop-in replacement at the seed step.

Builds on three commits:

1. 3be4d56 (Leo): introduces the function with a per-diagonal positive-segment scan as the extension. Behaviour-preserving refactor of _top_k_ungapped_local_align_core into process_diagonal_into_candidates + select_top_k_with_overlap_filter so both functions share the same extension and overlap logic.

2. 51207a0: adds min_kmer_hits_per_diagonal threshold — a per-diagonal hit-count floor that acts as an O(1) score-floor pre-filter (a match-run of length L deposits L - kmer_size + 1 hits, so thresholding "hits >= T" filters out diagonals whose best possible HSP score is bounded). Defaults to 1. Setting to 0 falls back to the exhaustive all-diagonals scan.

3. 7b8e7d2: replaces per-diagonal hit-count + full-diagonal scan with per-span emission + X-drop-bounded backward extension. Within the seeded regime, the function now reports exact full-scan-equivalent scores (not an approximation). Renames min_kmer_hits_per_diagonal -> min_kmer_hits_per_span; adds max_hit_gap parameter.

Performance

End-to-end on a 39-pair markdown / PDF-extracted-text corpus (kmer_size=5, max_hits_per_kmer=16, max_hit_gap=20, min_kmer_hits_per_span=1, k=500), full-scan vs new k-mer-seeded:

pair (n x m)	full-scan	k-mer-seeded	speedup	recall (score >= 50)
17K x 17K	2410 ms	4.2 ms	580x	1.000
11K x 11K	955 ms	2.5 ms	381x	1.000
73K x 72K	12712 ms	17.5 ms	728x	1.000
50K x 55K	4367 ms	12.0 ms	365x	1.000

Top-band recall is 100% on every pair tested. Mid-band (10 <= score < 50) recall is 0.88-0.96 at the default threshold.

API surface

seq_smith.top_k_ungapped_local_align_kmer(
    seqa, seqb, score_matrix, k,
    kmer_size, max_hits_per_kmer,
    max_hit_gap=20,            # span-merge distance + X-drop budget
    min_kmer_hits_per_span=1,  # 0 = fall back to exhaustive scan
    filter_overlap_a=True, filter_overlap_b=True,
) -> list[Alignment]

kmer_size must be in [1, 8]. Defaults are calibrated for +1 / -1 over text-like alphabets; tune max_hit_gap for other scoring schemes.

Correctness caveat

An HSP is found iff at least one window of kmer_size consecutive exact-match bytes lies on its diagonal between the two sequences. HSPs whose match runs are all strictly shorter than kmer_size are missed. For text alphabets and kmer_size <= 5, this only occurs at very small HSP scores. Callers that need exhaustive coverage at the boundary should keep using top_k_ungapped_local_align or set min_kmer_hits_per_span=0 to fall through to the exhaustive scan.

Version

Bumps to 0.6.0. No breaking changes to existing public APIs.

Test plan

• pytest tests/test_seq_smith.py — 45 tests pass (43 prior + 2 new for the threshold and exhaustive-fallback semantics)
• Existing test_top_k_ungapped_kmer_matches_full_scan_random_dna continues to assert exact equivalence with the full-diagonals scan
• Manual validation against the 39-pair markdown/PDF corpus: 100% recall of HSPs with score >= 50 at default settings, 365-728x speedup
• Cut GitHub release v0.6.0 after merge -> CI publishes wheels (ubuntu/windows/macos) + sdist to PyPI via trusted publishing