update docs for AlignedSequences, positive gap penalties, kalign-py CLI

- align_from_file now returns AlignedSequences, not list[str]
- gap penalties are positive values (not negative)
- document kalign-py CLI entry point
- document kalign.compare() function
- add benchmark instructions to README.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: TimoLassmann

README-python.md

@@ -104,12 +104,12 @@ aligned = kalign.align(sequences)
 # Specify sequence type explicitly
 aligned = kalign.align(sequences, seq_type="protein")
 
-# Use custom gap penalties
+# Use custom gap penalties (positive values = penalty magnitude)
 aligned = kalign.align(
     sequences,
     seq_type="dna",
-    gap_open=-10.0,
-    gap_extend=-1.0,
+    gap_open=10.0,
+    gap_extend=1.0,
     terminal_gap_extend=0.0
 )
 
@@ -312,16 +312,21 @@ Align sequences directly from files:
 ```python
 import kalign
 
-# Read sequences from file and align
-aligned = kalign.align_from_file("sequences.fasta", seq_type="protein")
+# Read sequences from file and align — returns AlignedSequences(names, sequences)
+result = kalign.align_from_file("sequences.fasta", seq_type="protein")
+for name, seq in zip(result.names, result.sequences):
+    print(f"{name}: {seq}")
 
 # With custom parameters
-aligned = kalign.align_from_file(
+result = kalign.align_from_file(
     "sequences.fasta",
     seq_type="protein",
-    gap_open=-10.0,
+    gap_open=10.0,
     n_threads=4
 )
+
+# Tuple unpacking also works
+names, sequences = kalign.align_from_file("sequences.fasta")
 ```
 
 Supported input formats:
@@ -330,6 +335,18 @@ Supported input formats:
 - Clustal
 - Aligned FASTA
 
+### Comparing Alignments
+
+Score a test alignment against a reference using the Sum-of-Pairs (SP) score:
+
+```python
+import kalign
+
+# Returns SP score from 0 (no match) to 100 (identical)
+score = kalign.compare("reference.msf", "test_alignment.fasta")
+print(f"SP score: {score:.1f}")
+```
+
 ### Advanced Usage
 
 ```python
@@ -344,8 +361,8 @@ protein_sequences = [
 aligned = kalign.align(
     protein_sequences,
     seq_type="protein",
-    gap_open=-10.0,
-    gap_extend=-1.0,
+    gap_open=10.0,
+    gap_extend=1.0,
     terminal_gap_extend=0.0,
     n_threads=2
 )
@@ -356,31 +373,53 @@ print(f"Alignment length: {len(aligned[0])}")
 
 ## API Reference
 
-### `kalign.align(sequences, seq_type="auto", gap_open=None, gap_extend=None, terminal_gap_extend=None, n_threads=1)`
+### `kalign.align(sequences, seq_type="auto", gap_open=None, gap_extend=None, terminal_gap_extend=None, n_threads=None)`
 
 Align a list of sequences.
 
 **Parameters:**
 - `sequences` (list of str): Sequences to align
 - `seq_type` (str or int): Sequence type specification
-- `gap_open` (float, optional): Gap opening penalty
-- `gap_extend` (float, optional): Gap extension penalty  
-- `terminal_gap_extend` (float, optional): Terminal gap extension penalty
-- `n_threads` (int): Number of threads to use
+- `gap_open` (float, optional): Gap opening penalty (positive value)
+- `gap_extend` (float, optional): Gap extension penalty (positive value)
+- `terminal_gap_extend` (float, optional): Terminal gap extension penalty (positive value)
+- `n_threads` (int, optional): Number of threads (default: `get_num_threads()`)
 
 **Returns:**
 - `list of str`: Aligned sequences
 
-### `kalign.align_from_file(input_file, seq_type="auto", gap_open=None, gap_extend=None, terminal_gap_extend=None, n_threads=1)`
+### `kalign.align_from_file(input_file, seq_type="auto", gap_open=None, gap_extend=None, terminal_gap_extend=None, n_threads=None)`
 
-Align sequences from a file.
+Align sequences from a file, preserving sequence names.
 
 **Parameters:**
-- `input_file` (str): Path to input file
+- `input_file` (str): Path to input file (FASTA, MSF, Clustal)
 - Other parameters same as `align()`
 
 **Returns:**
-- `list of str`: Aligned sequences
+- `AlignedSequences`: Named tuple with `.names` (list of str) and `.sequences` (list of str)
+
+### `kalign.compare(reference_file, test_file)`
+
+Score a test alignment against a reference alignment using the Sum-of-Pairs score.
+
+**Parameters:**
+- `reference_file` (str): Path to reference alignment
+- `test_file` (str): Path to test alignment
+
+**Returns:**
+- `float`: SP score from 0.0 (no match) to 100.0 (identical)
+
+### Command-line interface
+
+Installing the Python package provides a `kalign-py` command that uses the Python bindings directly (the C binary is installed separately as `kalign`):
+
+```bash
+kalign-py -i sequences.fasta -o aligned.fasta --format fasta --type protein
+kalign-py -i sequences.fasta -o - --format clustal   # stdout
+cat input.fa | kalign-py -i - -o aligned.fasta        # stdin
+kalign-py --version
+```
 
 ## 🚀 Performance & Scalability
 
@@ -410,9 +449,9 @@ python examples/performance_benchmarks.py
 
 # Use recommended settings
 kalign.set_num_threads(8)  # Based on benchmark results
-aligned = kalign.align(sequences, 
-                      gap_open=-10.0,    # Optimized gap penalties
-                      gap_extend=-1.0)
+aligned = kalign.align(sequences,
+                      gap_open=10.0,    # Optimized gap penalties
+                      gap_extend=1.0)
 ```
 
 ## Examples

README.md

@@ -167,6 +167,12 @@ for seq in aligned:
     print(seq)
 ```
 
+The Python package also provides a `kalign-py` CLI that uses the Python bindings directly (does not require the C binary):
+
+```bash
+kalign-py -i sequences.fasta -o aligned.fasta --format fasta
+```
+
 For comprehensive Python documentation, see [README-python.md](README-python.md) and the [python-docs directory](python-docs/).
 
 ## Examples
@@ -285,9 +291,20 @@ To install from TestPyPI while resolving dependencies from PyPI:
 pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple <package-name>
 ```
 
-## Performance
+## Benchmarks
+
+The repository includes an automated benchmark suite that scores kalign against the BAliBASE reference alignments using both the C binary and the Python API. Results are tracked across commits via GitHub Actions.
+
+```bash
+# Run benchmarks locally (requires: pip install -e . and a CMake build)
+make benchmark                      # full BAliBASE suite
+make benchmark BENCH_MAX_CASES=5    # quick smoke test
+
+# Or via Python directly
+python -m benchmarks --dataset balibase --method python_api cli -v
+```
 
-### Benchmark Results
+### Historical Results
 
 Kalign performs well for both speed and accuracy:
 

python-docs/python-api.md

@@ -69,8 +69,8 @@ print(aligned)
 aligned = kalign.align(
     sequences,
     seq_type="dna",
-    gap_open=-10.0,
-    gap_extend=-1.0,
+    gap_open=10.0,
+    gap_extend=1.0,
     n_threads=4
 )
 
@@ -91,7 +91,7 @@ print(type(aln_sk))
 
 ### `kalign.align_from_file()`
 
-Align sequences directly from files.
+Align sequences from a file, preserving sequence names.
 
 ```python
 def align_from_file(
@@ -100,23 +100,47 @@ def align_from_file(
     gap_open: Optional[float] = None,
     gap_extend: Optional[float] = None,
     terminal_gap_extend: Optional[float] = None,
-    n_threads: int = 1
-) -> List[str]
+    n_threads: Optional[int] = None
+) -> AlignedSequences
 ```
 
+Returns an `AlignedSequences` named tuple with `.names` (list of str) and `.sequences` (list of str).
+
 **Supported formats:** FASTA, MSF, Clustal, aligned FASTA
 
 **Example:**
 
 ```python
 import kalign
 
-# Align from FASTA file
-aligned = kalign.align_from_file(
+# Align from FASTA file — returns AlignedSequences(names, sequences)
+result = kalign.align_from_file(
     "sequences.fasta",
     seq_type="protein",
     n_threads=4
 )
+for name, seq in zip(result.names, result.sequences):
+    print(f"{name}: {seq}")
+
+# Tuple unpacking also works
+names, sequences = kalign.align_from_file("sequences.fasta")
+```
+
+### `kalign.compare()`
+
+Score a test alignment against a reference using the Sum-of-Pairs (SP) score.
+
+```python
+def compare(reference_file: str, test_file: str) -> float
+```
+
+**Returns:** SP score from 0.0 (no match) to 100.0 (identical).
+
+**Example:**
+
+```python
+score = kalign.compare("reference.msf", "test_alignment.fasta")
+print(f"SP score: {score:.1f}")
 ```
 
 ### `kalign.write_alignment()`

python-docs/python-performance.md

@@ -454,8 +454,8 @@ def optimize_gap_penalties(sequences, penalty_ranges=None):
 
     if penalty_ranges is None:
         penalty_ranges = {
-            'gap_open': np.arange(-20, -2, 2),
-            'gap_extend': np.arange(-5, -0.5, 0.5)
+            'gap_open': np.arange(2, 20, 2),
+            'gap_extend': np.arange(0.5, 5, 0.5)
         }
 
     print("🔧 Optimizing gap penalties...")

python-docs/python-quickstart.md

@@ -266,22 +266,22 @@ import kalign
 # Conservative alignment (fewer gaps)
 aligned = kalign.align(
     sequences,
-    gap_open=-15.0,      # Higher penalty for opening gaps
-    gap_extend=-2.0      # Higher penalty for extending gaps
+    gap_open=15.0,       # Higher penalty for opening gaps
+    gap_extend=2.0       # Higher penalty for extending gaps
 )
 
 # Aggressive alignment (more gaps)
 aligned = kalign.align(
     sequences,
-    gap_open=-5.0,       # Lower penalty for opening gaps
-    gap_extend=-0.5      # Lower penalty for extending gaps
+    gap_open=5.0,        # Lower penalty for opening gaps
+    gap_extend=0.5       # Lower penalty for extending gaps
 )
 
 # Custom terminal gap handling
 aligned = kalign.align(
     sequences,
-    gap_open=-10.0,
-    gap_extend=-1.0,
+    gap_open=10.0,
+    gap_extend=1.0,
     terminal_gap_extend=0.0  # No penalty for terminal gaps
 )
 ```

python-examples/README.md

@@ -185,7 +185,7 @@ sequences = [
 aligned = kalign.align(
     sequences,
     seq_type="protein",    # Change sequence type
-    gap_open=-12.0,        # Adjust gap penalties
+    gap_open=12.0,         # Adjust gap penalties
     n_threads=8            # Set thread count
 )
 

python-examples/basic_usage.py

@@ -62,8 +62,8 @@ def example_2_protein_alignment():
     aligned = kalign.align(
         protein_sequences,
         seq_type="protein",
-        gap_open=-10.0,
-        gap_extend=-1.0
+        gap_open=10.0,
+        gap_extend=1.0
     )
 
     print("\nAligned sequences:")