alphex 0.1.0a1__py3-none-any.whl

alphex/__init__.py

@@ -0,0 +1,60 @@
+"""Amino-acid alphabet orderings and letter-preserving conversions between them.
+
+This package exists because a silent data-corruption bug shipped: a token table built from the
+AlphaFold residue ordering while named for the ProteinMPNN ordering, permuting every residue
+that is not a fixed point of the permutation (only A, S and T are). Being shape-valid, it
+raised nothing.
+
+The unit of value here is the **declaration**, not the encoding. See
+`.praxia/docs/specs/260814_alphabet-contract.md` for the contract and
+`260814_alphabet-api-surface.md` for the shape.
+
+v0.1 is Phase 0 (decision D4): the `Alphabet` value type and the shipped declarations, for
+**dev-dependency-only conformance testing** in each consumer repo, plus the Phase 1 conversion
+kernel (`relation`, `perm`, `convert`, `reindex`). No asset layer and no plugin registry (D5)
+yet.
+"""
+
+from alphex import known
+from alphex.alphabet import Alphabet, SpecialKind
+from alphex.convert import MaskedPerm, Policy, PolicySpec, convert, perm, reindex
+from alphex.errors import (
+  AliasCollisionError,
+  AlphabetDeclarationError,
+  AlphabetError,
+  DegenerateSymbolError,
+  IncompatibleAlphabetError,
+  MissingSpecialError,
+  MultiCharTokenError,
+  NonStandardResidueError,
+  ReducedAlphabetError,
+  UnmappableSymbolError,
+  UnsupportedFeatureError,
+)
+from alphex.relation import Relation, RelationKind, relation
+
+__all__ = [
+  "AliasCollisionError",
+  "Alphabet",
+  "AlphabetDeclarationError",
+  "AlphabetError",
+  "DegenerateSymbolError",
+  "IncompatibleAlphabetError",
+  "MaskedPerm",
+  "MissingSpecialError",
+  "MultiCharTokenError",
+  "NonStandardResidueError",
+  "Policy",
+  "PolicySpec",
+  "ReducedAlphabetError",
+  "Relation",
+  "RelationKind",
+  "SpecialKind",
+  "UnmappableSymbolError",
+  "UnsupportedFeatureError",
+  "convert",
+  "known",
+  "perm",
+  "reindex",
+  "relation",
+]

alphex/_surface.py

@@ -0,0 +1,129 @@
+"""Shared logic behind the CLI and the MCP server.
+
+Both surfaces answer the same questions and must not drift, so the answers live here once and
+each surface only handles its own I/O. Everything below is plain data in, plain data out -- no
+printing, no MCP types, and nothing imported that is not already a hard dependency.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from alphex import known
+from alphex.convert import MaskedPerm, Policy, perm
+from alphex.relation import relation
+
+if TYPE_CHECKING:
+  import numpy as np
+
+  from alphex.alphabet import Alphabet
+
+POLICIES = tuple(p.value for p in Policy)
+
+
+def names() -> list[str]:
+  """Every shipped declaration name, in declaration order."""
+  return [a.name for a in known.ALL]
+
+
+def lookup(name: str) -> Alphabet:
+  """Resolve a declaration by name.
+
+  Raises `KeyError` listing the valid names rather than a bare miss: an agent or a shell user
+  who guessed a name needs the actual set, not a diagnosis.
+  """
+  for alphabet in known.ALL:
+    if alphabet.name == name:
+      return alphabet
+  msg = f"unknown alphabet {name!r}; shipped declarations are: {', '.join(names())}"
+  raise KeyError(msg)
+
+
+def describe(name: str) -> dict[str, Any]:
+  """Everything declared about one alphabet, including its provenance and any lint warnings."""
+  a = lookup(name)
+  return {
+    "name": a.name,
+    "symbols": a.symbols,
+    "n_symbols": a.n_symbols,
+    "offset": a.offset,
+    "size": a.size,
+    "padded_size": a.padded_size,
+    "specials": {kind.value: index for kind, index in sorted(a.specials.items(), key=_by_value)},
+    "unclaimed": sorted(a.unclaimed),
+    "citation": a.citation,
+    "warnings": a.lint(),
+  }
+
+
+def _by_value(item: tuple[Any, int]) -> int:
+  return item[1]
+
+
+def catalog() -> list[dict[str, Any]]:
+  """One row per shipped declaration, for a listing."""
+  return [
+    {
+      "name": a.name,
+      "symbols": a.symbols,
+      "offset": a.offset,
+      "size": a.size,
+      "specials": {kind.value: index for kind, index in sorted(a.specials.items(), key=_by_value)},
+      "warnings": len(a.lint()),
+    }
+    for a in known.ALL
+  ]
+
+
+def classify(src: str, dst: str) -> dict[str, Any]:
+  """How two declarations stand to one another. Cheap, and the right thing to ask first."""
+  rel = relation(lookup(src), lookup(dst))
+  return {
+    "src": src,
+    "dst": dst,
+    "kind": rel.kind.value,
+    "lossy": rel.lossy,
+    "moved": sorted(rel.moved),
+    "n_moved": len(rel.moved),
+  }
+
+
+def table(src: str, dst: str, policy: str) -> dict[str, Any]:
+  """Build a permutation table and report it alongside the letter-level check.
+
+  `policy` is a single uniform value here, which is a deliberate limit of these surfaces rather
+  than of the library: the per-`SpecialKind` mapping form exists so that ESM's eight specials
+  cannot be collapsed onto one index by accident, and squeezing a mapping through a CLI flag or
+  an MCP string argument would make that easy to do carelessly. Anything needing per-kind policy
+  should call `perm` directly.
+  """
+  source, destination = lookup(src), lookup(dst)
+  chosen = Policy(policy)
+  built = perm(source, destination, policy=chosen)
+
+  masked = isinstance(built, MaskedPerm)
+  raw: np.ndarray = built.table if isinstance(built, MaskedPerm) else built
+  valid = [bool(v) for v in built.valid] if isinstance(built, MaskedPerm) else None
+
+  return {
+    "src": src,
+    "dst": dst,
+    "policy": chosen.value,
+    "masked": masked,
+    "table": [int(v) for v in raw],
+    "valid": valid,
+    "letters_preserved": _letters_preserved(source, destination, raw),
+    "relation": classify(src, dst),
+  }
+
+
+def _letters_preserved(src: Alphabet, dst: Alphabet, raw: np.ndarray) -> bool:
+  """Check the invariant on the residues: same character, whatever the index."""
+  return all(dst.symbols[int(raw[src.index_of(c)]) - dst.offset] == c for c in src.symbols)
+
+
+def lint() -> list[dict[str, Any]]:
+  """Report declarations carrying warnings. Empty means every shipped declaration is clean."""
+  return [
+    {"name": a.name, "warnings": warnings} for a in known.ALL if (warnings := a.lint())
+  ]

alphex/alphabet.py

@@ -0,0 +1,182 @@
+"""The `Alphabet` value type and its declaration-time invariants.
+
+See `.praxia/docs/specs/260814_alphabet-api-surface.md` §3.2. The design in one line: an
+alphabet is a bijection between a symbol set and a contiguous integer range, plus named
+exceptions at declared indices.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from alphex.errors import AlphabetDeclarationError
+
+if TYPE_CHECKING:
+  from collections.abc import Mapping
+
+
+class SpecialKind(enum.Enum):
+  """A non-residue index, by meaning.
+
+  `UNKNOWN` and `STOP` are deliberately distinct: proteinsmc sets
+  `STOP_INT = UNKNOWN_AA_INT = PROTEINMPNN_X_INT = 21`, one index for two meanings, and the
+  point of typing them separately is that the conflation becomes reportable rather than
+  invisible.
+  """
+
+  UNKNOWN = "unknown"
+  GAP = "gap"
+  STOP = "stop"
+  MASK = "mask"
+  BOS = "bos"
+  EOS = "eos"
+  PAD = "pad"
+  CHAIN_BREAK = "chain_break"
+
+
+@dataclasses.dataclass(frozen=True)
+class Alphabet:
+  """An ordered symbol set occupying a known integer index space.
+
+  `symbols` is the contiguous run of *residue* symbols; `offset` is where that run starts in
+  the index space. ESM's 20 canonical residues sit contiguously at indices 4-23, so they are
+  expressed as `symbols=<20 chars>, offset=4` rather than as a 33-character string with
+  placeholders -- which would reintroduce the "is this position a residue?" ambiguity the
+  sentinel half of the shipped bug lived in.
+
+  Equality and hashing ignore `name` and `citation`: two declarations of the same index space
+  ARE the same alphabet however they are labelled. That is what makes the alias problem
+  detectable instead of invisible.
+  """
+
+  symbols: str
+  name: str
+  citation: str
+  offset: int = 0
+  specials: Mapping[SpecialKind, int] = dataclasses.field(default_factory=dict)
+  unclaimed: frozenset[int] = frozenset()
+
+  declared_size: int | None = None
+  """Width of the index space, when the source states one. `None` infers the smallest that fits.
+
+  Read `size` instead: it is always an `int`. The two are separate names because they are
+  separate facts -- what the source wrote, and how wide the alphabet actually is. ESM is the one
+  shipped declaration that states a width (33) exceeding what its own indices imply.
+  """
+
+  padded_size: int | None = None
+  """Width of a model's output axis when it exceeds `size`. `None` when there is no padding."""
+
+  @property
+  def size(self) -> int:
+    """Width of the index space. Always an `int`; never `None`, whatever was declared."""
+    if self.declared_size is not None:
+      return self.declared_size
+    return max([*self._residue_indices, *self.specials.values(), *self.unclaimed]) + 1
+
+  @property
+  def _residue_indices(self) -> range:
+    return range(self.offset, self.offset + len(self.symbols))
+
+  def __post_init__(self) -> None:
+    """Validate the declaration. Every failure here is a bug caught before it can propagate."""
+    if not self.symbols:
+      raise AlphabetDeclarationError("symbols must be non-empty")
+    if any(len(c) != 1 for c in self.symbols):
+      msg = f"symbols must be single characters, got {self.symbols!r}"
+      raise AlphabetDeclarationError(msg)
+    if len(set(self.symbols)) != len(self.symbols):
+      dupes = sorted({c for c in self.symbols if self.symbols.count(c) > 1})
+      msg = f"duplicate symbols in {self.symbols!r}: {dupes}"
+      raise AlphabetDeclarationError(msg)
+    if not self.citation.strip():
+      msg = f"alphabet {self.name!r} has no citation; a declaration without provenance is "
+      msg += "how an ordering loses track of where it came from"
+      raise AlphabetDeclarationError(msg)
+
+    residue_indices = frozenset(self._residue_indices)
+    special_indices = frozenset(self.specials.values())
+    resolved = self.size
+
+    if collide := residue_indices & special_indices:
+      msg = f"special index collides with a residue index: {sorted(collide)}"
+      raise AlphabetDeclarationError(msg)
+    out_of_range = {
+      i for i in residue_indices | special_indices | self.unclaimed if not 0 <= i < resolved
+    }
+    if out_of_range:
+      msg = f"index outside [0, {resolved}): {sorted(out_of_range)}"
+      raise AlphabetDeclarationError(msg)
+
+    accounted = residue_indices | special_indices | self.unclaimed
+    if unaccounted := set(range(resolved)) - accounted:
+      msg = (
+        f"alphabet {self.name!r} leaves index(es) {sorted(unaccounted)} unaccounted for. "
+        f"Every index in [0, {resolved}) must be a residue, a special, or explicitly "
+        f"unclaimed -- an index that means nothing is how a lookup table silently clamps."
+      )
+      raise AlphabetDeclarationError(msg)
+
+  # --- identity -------------------------------------------------------------------
+
+  def _identity(self) -> tuple[object, ...]:
+    return (self.symbols, self.offset, frozenset(self.specials.items()), self.size)
+
+  def __eq__(self, other: object) -> bool:
+    """Compare index spaces, not labels."""
+    if not isinstance(other, Alphabet):
+      return NotImplemented
+    return self._identity() == other._identity()
+
+  def __hash__(self) -> int:
+    """Hash the index space, so `name` cannot split one alphabet into two keys."""
+    return hash(self._identity())
+
+  # --- accessors ------------------------------------------------------------------
+
+  @property
+  def n_symbols(self) -> int:
+    """Number of residue symbols, excluding specials."""
+    return len(self.symbols)
+
+  @property
+  def conflated_specials(self) -> frozenset[frozenset[SpecialKind]]:
+    """Groups of SpecialKinds sharing one index.
+
+    Non-empty means two meanings are indistinguishable at runtime.
+    """
+    by_index: dict[int, set[SpecialKind]] = {}
+    for kind, idx in self.specials.items():
+      by_index.setdefault(idx, set()).add(kind)
+    return frozenset(frozenset(g) for g in by_index.values() if len(g) > 1)
+
+  def index_of(self, symbol: str) -> int:
+    """Absolute index of a residue symbol."""
+    return self.offset + self.symbols.index(symbol)
+
+  def encode(self, text: str) -> np.ndarray:
+    """Residue characters to absolute indices."""
+    return np.array([self.index_of(c) for c in text], dtype=np.int32)
+
+  def decode(self, codes: np.ndarray) -> str:
+    """Absolute indices to residue characters."""
+    return "".join(self.symbols[int(i) - self.offset] for i in np.asarray(codes).ravel())
+
+  def lint(self) -> list[str]:
+    """Return non-fatal warnings. Never raises: a dirty declaration must stay loadable.
+
+    Refusing to load a declaration that lints dirty would recreate the pressure to declare
+    something untrue, which is worse than declaring something imperfect.
+    """
+    warnings: list[str] = []
+    for group in sorted(self.conflated_specials, key=lambda g: sorted(k.value for k in g)):
+      kinds = ", ".join(sorted(k.value for k in group))
+      idx = self.specials[next(iter(group))]
+      warnings.append(
+        f"conflated specials at index {idx}: {kinds} are indistinguishable at runtime",
+      )
+    return warnings

alphex/cli.py

@@ -0,0 +1,125 @@
+"""`alphex` command line. Install with the `cli` extra: `uv add "alphex[cli]"`.
+
+Deliberately small. This is a library first; the CLI exists so a person or an agent can answer
+"which ordering is this?" and "what does the table look like?" without writing a script -- the
+two questions whose absence let a mislabelled table ship.
+
+Nothing here is imported by `alphex/__init__.py`, so the base install stays numpy-only.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from alphex import _surface
+
+try:
+  from cyclopts import App
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+  msg = (
+    "the alphex CLI needs the 'cli' extra: `uv add \"alphex[cli]\"` "
+    "(or `pip install 'alphex[cli]'`). The base install is numpy-only on purpose."
+  )
+  raise SystemExit(msg) from exc
+
+app = App(
+  name="alphex",
+  help="Biological sequence alphabet orderings and conversions between them.",
+)
+
+
+def _emit(payload: object, *, as_json: bool) -> None:
+  if as_json:
+    print(json.dumps(payload, indent=2))
+    return
+  print(_render(payload))
+
+
+def _render(payload: object) -> str:
+  """Plain-text rendering. No `rich` dependency -- this output is meant to be piped."""
+  if isinstance(payload, list):
+    return "\n".join(_render(row) for row in payload)
+  if isinstance(payload, dict):
+    width = max((len(k) for k in payload), default=0)
+    return "\n".join(f"{k:<{width}}  {_scalar(v)}" for k, v in payload.items())
+  return str(payload)
+
+
+def _scalar(value: object) -> str:
+  if isinstance(value, dict):
+    return ", ".join(f"{k}={v}" for k, v in value.items()) or "-"
+  if isinstance(value, list):
+    return ", ".join(str(v) for v in value) if value else "-"
+  return str(value)
+
+
+@app.command
+def list_(*, json_out: bool = False) -> None:
+  """List every shipped alphabet declaration."""
+  rows = _surface.catalog()
+  if json_out:
+    _emit(rows, as_json=True)
+    return
+  width = max(len(r["name"]) for r in rows)
+  for r in rows:
+    specials = ", ".join(f"{k}@{v}" for k, v in r["specials"].items()) or "-"
+    flag = "  (lints)" if r["warnings"] else ""
+    print(f"{r['name']:<{width}}  size={r['size']:<3} offset={r['offset']}  {specials}{flag}")
+
+
+@app.command
+def show(name: str, *, json_out: bool = False) -> None:
+  """Show one declaration in full, including its citation."""
+  _emit(_surface.describe(name), as_json=json_out)
+
+
+@app.command
+def relation(src: str, dst: str, *, json_out: bool = False) -> None:
+  """Classify the mapping between two declarations before converting anything."""
+  _emit(_surface.classify(src, dst), as_json=json_out)
+
+
+@app.command
+def perm(src: str, dst: str, *, policy: str = "raise", json_out: bool = False) -> None:
+  """Build the permutation table from `src` to `dst`.
+
+  `policy` is one of raise, unknown, gap, mask -- applied uniformly. Conversions needing a
+  different policy per special kind must call the library directly; see `alphex._surface.table`.
+  """
+  if policy not in _surface.POLICIES:
+    raise SystemExit(f"policy must be one of {', '.join(_surface.POLICIES)}, got {policy!r}")
+  _emit(_surface.table(src, dst, policy), as_json=json_out)
+
+
+@app.command
+def lint(*, strict: bool = False, json_out: bool = False) -> None:
+  """Report declarations whose conventions are worth knowing about.
+
+  Exits 0 by default even when there are findings. A warning here is not a defect to fix: two
+  shipped declarations conflate STOP and UNKNOWN because proteinsmc really does put both on
+  index 21, and declaring that is what makes it visible. Those two will warn forever, so a
+  non-zero default would be permanent noise and would train people to ignore the command.
+
+  Pass `--strict` to exit 1 on any finding -- useful in a repo that has decided its own
+  declarations must stay clean.
+  """
+  findings = _surface.lint()
+  if not findings:
+    if json_out:
+      _emit([], as_json=True)
+    else:
+      print("no warnings")
+    return
+  _emit(findings, as_json=json_out)
+  if strict:
+    sys.exit(1)
+
+
+def main() -> None:
+  """Console-script entry point."""
+  app()
+
+
+if __name__ == "__main__":
+  main()