alphex 0.1.0__tar.gz

alphex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marielle Russo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alphex-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: alphex
+Version: 0.1.0
+Summary: Biological sequence alphabet orderings and letter-preserving conversions between them.
+Keywords: bioinformatics,protein,alphabet,tokenizer,esm,proteinmpnn,alphafold
+Author: Marielle Russo
+Author-email: Marielle Russo <67157875+maraxen@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Dist: numpy
+Requires-Dist: alphex[cli,mcp] ; extra == 'agent'
+Requires-Dist: cyclopts>=3 ; extra == 'cli'
+Requires-Dist: jax ; extra == 'jax'
+Requires-Dist: fastmcp>=2 ; extra == 'mcp'
+Requires-Dist: cisternal>=0.1.3 ; python_full_version >= '3.13' and extra == 'mcp'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/maraxen/alphex
+Project-URL: Repository, https://github.com/maraxen/alphex
+Project-URL: Issues, https://github.com/maraxen/alphex/issues
+Provides-Extra: agent
+Provides-Extra: cli
+Provides-Extra: jax
+Provides-Extra: mcp
+Description-Content-Type: text/markdown
+
+# alphex
+
+Biological sequence alphabet orderings, and letter-preserving conversions between them.
+
+```bash
+uv add alphex
+```
+
+## Why
+
+Three different amino-acid orderings are in common use, under at least five different names:
+
+| ordering | letters | used by |
+|---|---|---|
+| ProteinMPNN | `ACDEFGHIKLMNPQRSTVWY` | ProteinMPNN, and most "canonical" alphabets |
+| AlphaFold | `ARNDCQEGHILKMFPSTWYV` | AlphaFold `restypes`, LG/JTT substitution models, IQ-TREE |
+| ESM | `LAGVSERTIDPKQNFYMHWC` | ESM3 / ESM-C, at offset 4 |
+
+ProteinMPNN and AlphaFold order have **exactly three fixed points** — `A`, `S` and `T`. Build a
+lookup table from one and label it with the other, and 17 of 20 residues are silently permuted.
+The result is shape-valid, dtype-valid, and wrong; nothing raises. That bug has shipped.
+
+An ecosystem census that motivated this package found those three orderings declared at **30
+sites across four repositories**, in six different sentinel conventions (no sentinel; `X` at 20;
+gap at 20; gap at 0 with residues shifted to 1; gap at 20 with `X` at 21; `X` at 20 with gap at
+21). Every site was an independent opportunity to get it wrong.
+
+`alphex` holds one declaration of each, and one way to convert between them.
+
+## What it does
+
+```python
+from alphex import Policy, SpecialKind, known, perm
+
+# A table from ProteinMPNN order (gap at 20) into ESM's vocabulary.
+table = perm(known.MPNN_GAP_21, known.ESM_C, policy=Policy.RAISE)
+
+table.shape        # (21,) -- the whole source domain, never just the 20 residues
+int(table[0])      # 5     -- 'A'
+int(table[20])     # 30    -- the gap, which ESM declares
+```
+
+Four entry points, because four genuinely different things get converted and using the wrong
+one scrambles letter identity silently:
+
+| | |
+|---|---|
+| `relation(src, dst)` | classify first: `IDENTITY`, `EXTENSION`, `PERMUTATION`, `INCOMPATIBLE`, plus `lossy` and which letters moved |
+| `perm(src, dst, *, policy)` | build the lookup table |
+| `convert(codes, src, dst, *, policy)` | relabel sequence codes |
+| `reindex(data, src, dst, *, policy, axes)` | move a posterior or substitution-matrix axis |
+
+## The design commitments
+
+**Letters, not indices.** The invariant is that the amino acid at each position is unchanged and
+only its integer moves. Index equality cannot catch this bug class — the broken table and the
+correct one both round-trip perfectly within themselves.
+
+**Every index means something.** A declaration must account for every index in `[0, size)` as a
+residue, a named special, or explicitly `unclaimed`. A table shorter than its domain is how a
+JAX gather clamped a gap index onto valine.
+
+**No silent defaults.** `policy` is keyword-only and has no default, anywhere. It is keyed per
+`SpecialKind`, so ESM's eight specials cannot collapse onto one destination index without you
+writing that down.
+
+**No in-band sentinels.** `Policy.MASK` returns a `MaskedPerm`, a distinct type — because every
+in-band marker is a valid index somewhere. `-1` selects the last element of the destination
+axis; `size` is clamped rather than rejected by JAX.
+
+**Declarations carry provenance.** `citation` is required and must be non-empty. An ordering
+without a source is how one gets relabelled.
+
+**Names are not identity.** Two `Alphabet`s compare equal when their index spaces match,
+whatever they are called. That is what makes an alias collision detectable instead of invisible.
+
+## CLI and MCP
+
+Optional surfaces, for asking the two questions whose absence let a mislabelled table ship —
+"which ordering is this?" and "what does the table look like?" — without writing a script.
+
+```bash
+uv add "alphex[cli]"                  # or [mcp], or [agent] for both
+
+alphex list                           # every shipped declaration
+alphex show MPNN_GAP_21               # symbols, specials, citation, warnings
+alphex relation MPNN_20 AF_20         # classify before converting
+alphex perm MPNN_GAP_21 ESM_C         # the table, plus a letter-preservation check
+alphex lint                           # declarations with conflated sentinels
+```
+
+Every command takes `--json-out`. The MCP server (`alphex-mcp`) exposes the same five as tools —
+`list_alphabets`, `show_alphabet`, `relation`, `perm`, `lint` — registered through
+[cisternal](https://pypi.org/project/cisternal/), which also ships the `using-alphex` skill and
+project rules to Claude Code, Cursor, Copilot and Antigravity via `.praxia/manifest.toml`.
+
+Both surfaces answer from one module (`alphex._surface`) so they cannot drift, and both take a
+single uniform `policy`: the per-`SpecialKind` mapping form exists precisely so ESM's eight
+specials cannot be collapsed onto one index by accident, and squeezing that through a CLI flag
+would make doing so easy. Anything needing per-kind policy calls `perm` directly.
+
+*(The `mcp` extra pulls cisternal, which requires Python ≥3.13. alphex itself supports ≥3.11 and
+will keep doing so, so the dependency is marker-gated: below 3.13 the library and CLI work
+normally and `alphex-mcp` exits with a message saying why.)*
+
+## Dependencies
+
+`numpy`, and nothing else. That ceiling is the reason this is its own distribution rather than a
+module inside a larger library: extras can only *add* to a base install, never subtract, so the
+only way to make "just the alphabets" cheap for a consumer is for it to ship separately.
+
+JAX consumers pass the result through `jnp.asarray` — the table is a small constant.
+
+## Status
+
+Alpha. The value type, the shipped declarations and the conversion kernel are implemented and
+tested. Not yet implemented: aliases for degenerate and non-standard residues (`B`, `Z`, `J`,
+`U`, `O`), the substitution/rate-matrix asset layer, and the plugin registry for third-party
+alphabets. The entry-point group names (`alphabet_contract.v1.*`) are reserved and deliberately
+independent of this distribution's name.
+
+## Provenance
+
+The orderings are facts about published tools, cited per declaration in `known.py`: ProteinMPNN
+(Dauparas et al. 2022, MIT), AlphaFold `residue_constants` (Apache-2.0), ESM3/ESM-C
+`SEQUENCE_VOCAB` (MIT). No code from those projects is included or derived from.
+
+MIT licensed.

alphex-0.1.0/README.md

@@ -0,0 +1,128 @@
+# alphex
+
+Biological sequence alphabet orderings, and letter-preserving conversions between them.
+
+```bash
+uv add alphex
+```
+
+## Why
+
+Three different amino-acid orderings are in common use, under at least five different names:
+
+| ordering | letters | used by |
+|---|---|---|
+| ProteinMPNN | `ACDEFGHIKLMNPQRSTVWY` | ProteinMPNN, and most "canonical" alphabets |
+| AlphaFold | `ARNDCQEGHILKMFPSTWYV` | AlphaFold `restypes`, LG/JTT substitution models, IQ-TREE |
+| ESM | `LAGVSERTIDPKQNFYMHWC` | ESM3 / ESM-C, at offset 4 |
+
+ProteinMPNN and AlphaFold order have **exactly three fixed points** — `A`, `S` and `T`. Build a
+lookup table from one and label it with the other, and 17 of 20 residues are silently permuted.
+The result is shape-valid, dtype-valid, and wrong; nothing raises. That bug has shipped.
+
+An ecosystem census that motivated this package found those three orderings declared at **30
+sites across four repositories**, in six different sentinel conventions (no sentinel; `X` at 20;
+gap at 20; gap at 0 with residues shifted to 1; gap at 20 with `X` at 21; `X` at 20 with gap at
+21). Every site was an independent opportunity to get it wrong.
+
+`alphex` holds one declaration of each, and one way to convert between them.
+
+## What it does
+
+```python
+from alphex import Policy, SpecialKind, known, perm
+
+# A table from ProteinMPNN order (gap at 20) into ESM's vocabulary.
+table = perm(known.MPNN_GAP_21, known.ESM_C, policy=Policy.RAISE)
+
+table.shape        # (21,) -- the whole source domain, never just the 20 residues
+int(table[0])      # 5     -- 'A'
+int(table[20])     # 30    -- the gap, which ESM declares
+```
+
+Four entry points, because four genuinely different things get converted and using the wrong
+one scrambles letter identity silently:
+
+| | |
+|---|---|
+| `relation(src, dst)` | classify first: `IDENTITY`, `EXTENSION`, `PERMUTATION`, `INCOMPATIBLE`, plus `lossy` and which letters moved |
+| `perm(src, dst, *, policy)` | build the lookup table |
+| `convert(codes, src, dst, *, policy)` | relabel sequence codes |
+| `reindex(data, src, dst, *, policy, axes)` | move a posterior or substitution-matrix axis |
+
+## The design commitments
+
+**Letters, not indices.** The invariant is that the amino acid at each position is unchanged and
+only its integer moves. Index equality cannot catch this bug class — the broken table and the
+correct one both round-trip perfectly within themselves.
+
+**Every index means something.** A declaration must account for every index in `[0, size)` as a
+residue, a named special, or explicitly `unclaimed`. A table shorter than its domain is how a
+JAX gather clamped a gap index onto valine.
+
+**No silent defaults.** `policy` is keyword-only and has no default, anywhere. It is keyed per
+`SpecialKind`, so ESM's eight specials cannot collapse onto one destination index without you
+writing that down.
+
+**No in-band sentinels.** `Policy.MASK` returns a `MaskedPerm`, a distinct type — because every
+in-band marker is a valid index somewhere. `-1` selects the last element of the destination
+axis; `size` is clamped rather than rejected by JAX.
+
+**Declarations carry provenance.** `citation` is required and must be non-empty. An ordering
+without a source is how one gets relabelled.
+
+**Names are not identity.** Two `Alphabet`s compare equal when their index spaces match,
+whatever they are called. That is what makes an alias collision detectable instead of invisible.
+
+## CLI and MCP
+
+Optional surfaces, for asking the two questions whose absence let a mislabelled table ship —
+"which ordering is this?" and "what does the table look like?" — without writing a script.
+
+```bash
+uv add "alphex[cli]"                  # or [mcp], or [agent] for both
+
+alphex list                           # every shipped declaration
+alphex show MPNN_GAP_21               # symbols, specials, citation, warnings
+alphex relation MPNN_20 AF_20         # classify before converting
+alphex perm MPNN_GAP_21 ESM_C         # the table, plus a letter-preservation check
+alphex lint                           # declarations with conflated sentinels
+```
+
+Every command takes `--json-out`. The MCP server (`alphex-mcp`) exposes the same five as tools —
+`list_alphabets`, `show_alphabet`, `relation`, `perm`, `lint` — registered through
+[cisternal](https://pypi.org/project/cisternal/), which also ships the `using-alphex` skill and
+project rules to Claude Code, Cursor, Copilot and Antigravity via `.praxia/manifest.toml`.
+
+Both surfaces answer from one module (`alphex._surface`) so they cannot drift, and both take a
+single uniform `policy`: the per-`SpecialKind` mapping form exists precisely so ESM's eight
+specials cannot be collapsed onto one index by accident, and squeezing that through a CLI flag
+would make doing so easy. Anything needing per-kind policy calls `perm` directly.
+
+*(The `mcp` extra pulls cisternal, which requires Python ≥3.13. alphex itself supports ≥3.11 and
+will keep doing so, so the dependency is marker-gated: below 3.13 the library and CLI work
+normally and `alphex-mcp` exits with a message saying why.)*
+
+## Dependencies
+
+`numpy`, and nothing else. That ceiling is the reason this is its own distribution rather than a
+module inside a larger library: extras can only *add* to a base install, never subtract, so the
+only way to make "just the alphabets" cheap for a consumer is for it to ship separately.
+
+JAX consumers pass the result through `jnp.asarray` — the table is a small constant.
+
+## Status
+
+Alpha. The value type, the shipped declarations and the conversion kernel are implemented and
+tested. Not yet implemented: aliases for degenerate and non-standard residues (`B`, `Z`, `J`,
+`U`, `O`), the substitution/rate-matrix asset layer, and the plugin registry for third-party
+alphabets. The entry-point group names (`alphabet_contract.v1.*`) are reserved and deliberately
+independent of this distribution's name.
+
+## Provenance
+
+The orderings are facts about published tools, cited per declaration in `known.py`: ProteinMPNN
+(Dauparas et al. 2022, MIT), AlphaFold `residue_constants` (Apache-2.0), ESM3/ESM-C
+`SEQUENCE_VOCAB` (MIT). No code from those projects is included or derived from.
+
+MIT licensed.

alphex-0.1.0/pyproject.toml

@@ -0,0 +1,102 @@
+[project]
+name = "alphex"
+version = "0.1.0"
+description = "Biological sequence alphabet orderings and letter-preserving conversions between them."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "bioinformatics",
+    "protein",
+    "alphabet",
+    "tokenizer",
+    "esm",
+    "proteinmpnn",
+    "alphafold",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+dependencies = ["numpy"]
+
+[[project.authors]]
+name = "Marielle Russo"
+email = "67157875+maraxen@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/maraxen/alphex"
+Repository = "https://github.com/maraxen/alphex"
+Issues = "https://github.com/maraxen/alphex/issues"
+
+[project.optional-dependencies]
+jax = ["jax"]
+cli = ["cyclopts>=3"]
+mcp = [
+    "fastmcp>=2",
+    "cisternal>=0.1.3; python_version >= '3.13'",
+]
+agent = ["alphex[cli,mcp]"]
+
+[project.scripts]
+alphex = "alphex.cli:main"
+alphex-mcp = "alphex.mcp:mcp_server"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "hypothesis>=6",
+    "ruff>=0.14",
+    "ty>=0.0.1a21",
+]
+
+[tool.uv]
+prerelease = "allow"
+
+[tool.ruff]
+line-length = 100
+indent-width = 2
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D203",
+    "D213",
+    "COM812",
+    "TRY003",
+    "EM101",
+    "EM102",
+    "CPY001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/alphex/cli.py" = ["T201"]
+"scripts/*.py" = [
+    "T201",
+    "INP001",
+    "C901",
+]
+"tests/*.py" = [
+    "S101",
+    "PLR2004",
+    "INP001",
+    "D103",
+]
+
+[tool.ty.rules]
+call-non-callable = "ignore"
+unused-ignore-comment = "ignore"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"

alphex-0.1.0/pyproject.toml.orig

@@ -0,0 +1,144 @@
+[project]
+name = "alphex"
+# 0.1.0 is the stable contract for the kernel: `Alphabet`, the shipped declarations, and
+# `relation` / `perm` / `convert` / `reindex`. The v0.2 items -- degenerate and non-standard
+# residue aliases (B/Z/J/U/O), the asset layer, the plugin registry -- are additive and not
+# implemented in 0.1.0.
+version = "0.1.0"
+description = "Biological sequence alphabet orderings and letter-preserving conversions between them."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Marielle Russo", email = "67157875+maraxen@users.noreply.github.com" }
+]
+requires-python = ">=3.11"
+keywords = ["bioinformatics", "protein", "alphabet", "tokenizer", "esm", "proteinmpnn", "alphafold"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+
+# INTENTIONALLY MINIMAL -- see CLAUDE.md "The dependency contract".
+#
+# numpy is the only runtime dependency, and even that is a deliberate ceiling rather
+# than a starting point. This package exists because the alternative homes for it
+# (proxide, aminx, proteinsmc) all carry a base install that a consumer needing only
+# alphabet conversions cannot afford: proxide's base pulls jax, jax-md, hydride, grain
+# and array_record on top of a maturin-built Rust extension. Optional-dependency
+# extras cannot fix that -- extras only ADD to a base install, they never subtract
+# from it -- so the only way to make "just the alphabets" cheap is for it to be its
+# own distribution. That is this one.
+#
+# Do NOT add jax here. Consumers that want jnp-backed permutation tables should get
+# them by passing this package's plain integer arrays into their own jnp.asarray, or
+# via a `jax` extra that stays strictly optional and lazily imported.
+dependencies = [
+    "numpy",
+]
+
+# Keep table headers BELOW every bare `[project]` key. A `[project.urls]` block placed above
+# `dependencies` silently captures it, and the resulting error ("invalid type: sequence,
+# expected a string") points at the list rather than at the header that swallowed it.
+[project.urls]
+Homepage = "https://github.com/maraxen/alphex"
+Repository = "https://github.com/maraxen/alphex"
+Issues = "https://github.com/maraxen/alphex/issues"
+
+[project.optional-dependencies]
+# Anything here must be imported only by a module that `alphex/__init__.py` does NOT
+# import, and must fail with an actionable message naming the extra -- never with a
+# bare ImportError. `alphex.cli` and `alphex.mcp` both do this; importing `alphex`
+# itself still pulls nothing but numpy, which is the whole reason this package exists
+# as its own distribution.
+jax = ["jax"]
+cli = ["cyclopts>=3"]
+# The marker is load-bearing, and matches myxcel's precedent for the same dependency.
+# cisternal requires Python >=3.13; alphex supports >=3.11 and must keep doing so, because a
+# cheap install on the widest range of interpreters is the reason this package exists at all.
+# Narrowing `requires-python` to satisfy an optional telemetry dependency would trade the
+# package's purpose for a feature nobody needs to import the library.
+#
+# Consequence, stated rather than discovered: on 3.11/3.12 the `mcp` extra installs fastmcp
+# but NOT cisternal, so `alphex-mcp` exits with the message in alphex/mcp.py naming the 3.13
+# floor. The CLI has no such floor and works everywhere.
+mcp = ["fastmcp>=2", "cisternal>=0.1.3; python_version >= '3.13'"]
+agent = ["alphex[cli,mcp]"]
+
+[project.scripts]
+alphex = "alphex.cli:main"
+alphex-mcp = "alphex.mcp:mcp_server"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "hypothesis>=6",
+    "ruff>=0.14",
+    "ty>=0.0.1a21",
+]
+
+[tool.uv]
+# cisternal>=0.1.1a11 pins fastmcp==4.0.0a2 (a pre-release), so the 3.13+ fork of the lock
+# needs pre-releases allowed; allow here so `uv lock`/`uv sync` work without a flag. The
+# 3.11/3.12 forks carry no cisternal and stay on fastmcp 3.4.x.
+prerelease = "allow"
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+indent-width = 2
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "D203",
+  "D213",
+  "COM812",
+  "TRY003",
+  "EM101", "EM102",
+  "CPY001",  # no copyright headers anywhere in this ecosystem
+]
+
+[tool.ruff.lint.per-file-ignores]
+# T201: a command-line program's output IS print. Routing it through `logging` would send it
+# to stderr and make `alphex perm ... | jq` stop working, which is the main way this surface
+# is meant to be used.
+"src/alphex/cli.py" = ["T201"]
+# CLI scripts print to stdout by design, are not an importable package, and their
+# report-building main() is a flat sequence rather than genuinely branchy.
+"scripts/*.py" = ["T201", "INP001", "C901"]
+# Tests assert (that is their job) and compare against literal indices from the census,
+# which are the values under test -- extracting them to constants would hide the thing
+# being asserted behind a name.
+# D103: test names here are full sentences (`test_declaration_rejects_duplicate_symbols`),
+# so a docstring restating the name is noise. Tests whose *reason for existing* is
+# non-obvious -- the ones guarding a specific past defect -- carry a docstring anyway.
+"tests/*.py" = ["S101", "PLR2004", "INP001", "D103"]
+
+[tool.ty.rules]
+# Two rules disabled, both for the same underlying cause: `cisternal` is an OPTIONAL,
+# marker-gated dependency (Python >=3.13), so its presence differs across the CI matrix and
+# no single source-level state is correct on all three interpreters.
+#
+# cisternal assembles its public surface dynamically, so ty resolves `cisternal.wire` to
+# `object` and reports the call as non-callable. bathos hit the identical wall on
+# `app.run()` and demoted the same rule. Scoped by the fact that this library has exactly
+# one call into an untyped third-party object; if that stops being true, narrow this.
+call-non-callable = "ignore"
+# The `ty: ignore[unresolved-import]` on the cisternal import is REQUIRED on 3.11/3.12,
+# where the marker excludes it, and UNUSED on 3.13+, where it installs. Disabling the
+# meta-rule is the only state that holds across the matrix; the alternative is a green
+# 3.13 and a red 3.11, or vice versa.
+unused-ignore-comment = "ignore"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

alphex-0.1.0/src/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",
+]