Make Rust-backed Mokume the default and introduce the Mokume Plugin

[Shen-YuFei]

Summary

This PR consolidates Mokume around a Rust-first distribution and execution model.

With this change, mokume becomes the default Rust-backed Python distribution, while the pure-Python implementation moves to the separate mokume-py distribution. The PR also introduces the installable Mokume Plugin, routes piBAQ through the runtime pyOpenMS protease catalog and native Rust core, expands differential-expression workflows, and adds streaming TissueMap loading for TMT data.

Breaking changes

• pip install mokume now installs the Rust-backed distribution.
• The pure-Python distribution is renamed to mokume-py.
• Both distributions import as mokume; they must not be installed in the same environment.
• The standalone Cargo-installed mokume-cli binary is removed.
• The pip-installed mokume console command now dispatches through the in-process PyO3 extension.
• The internal command crate is renamed to mokume-command and remains publish = false.
• The previous Python agentic loop and model-client implementation are removed in favor of a host-owned Plugin and local MCP service.
• piBAQ is the canonical absolute-quantification method name. Historical ibaq inputs remain compatibility aliases where supported.

Distribution and packaging

Rust-backed distribution

pip install mokume

The default distribution includes:

• the native Rust compute kernel;
• the mokume._mokume PyO3 extension;
• the Python API and console command;
• pyOpenMS as a base dependency for runtime FASTA digestion and protease discovery.

The extension uses an abi3-py39 build and supports Python 3.9 or newer.

Pure-Python distribution

pip install mokume-py

mokume-py preserves the pure-Python workflows and requires Python 3.10 or newer. pyOpenMS and piBAQ are included in its base dependencies rather than a separate pibaq extra.

Because both distributions provide the same mokume import package, installing both in one environment is unsupported. Import-time checks warn when the sibling distribution is detected.

Native computation and Python bindings

The Rust-backed wheel now exposes native, in-process APIs for:

• protein-expression matrix construction;
• normalization;
• imputation;
• differential expression;
• batch correction;
• piBAQ shared-peptide allocation, theoretical denominators, evidence classification, and TPA.

The Python API preserves the established DataFrame and file-oriented entry points while routing compute-heavy operations through the same Rust implementation used by the console command.

mokume-command provides the shared command parsing and dispatch library. It is an internal workspace crate and is not intended for standalone Cargo installation.

piBAQ and runtime pyOpenMS digestion

piBAQ is now a base capability of both distributions.

The Rust-backed workflow:

1. reads every protease registered by the installed pyOpenMS ProteaseDB;
2. resolves enzyme names and synonyms at runtime;
3. digests the supplied FASTA through ProteaseDigestion;
4. passes the complete protein-to-theoretical-peptide mapping into Rust;
5. performs shared-peptide allocation, family handling, theoretical-peptide denominators, evidence classification, TPA, and output generation in the native core.

This removes the self-maintained Rust cleavage-rule catalog and supports pyOpenMS rules that could not be represented by the former simplified Rust rule structure, including context-dependent, unspecific, and no-cleavage behavior.

The runtime logs the pyOpenMS version, canonical enzyme name, catalog hash, peptide-length limits, and missed-cleavage setting used for digestion.

The retained compute and file-oriented Python compatibility APIs are native-backed wrappers. They are not separate enzyme fallbacks and do not require the all extra.

Mokume Plugin and MCP service

This PR adds an installable Mokume Plugin for Codex and Claude Code.

The architecture separates responsibilities as follows:

• the agent host owns the model, authentication, and conversation;
• the Plugin supplies workflow instructions and bundled benchmark knowledge;
• the bundled local stdio MCP server profiles matrices and evaluates explicit candidates;
• the Rust kernel performs normalization, imputation, and differential-expression computation.

The service does not require a separate model API key.

Install the local Mokume service

The following release installation commands apply after this change reaches main and the corresponding Python packages are published.

Install the Rust-backed distribution with the Plugin and MCP dependencies:

pip install "mokume[agentic]"
mokume --version

The Plugin requires Python 3.10 or newer. The mokume executable must be available on the PATH inherited by Codex or Claude Code.

Do not install mokume-py in the same environment because both distributions provide the same mokume import package and console command.

Install in Codex

Add the BigBio marketplace and install the Mokume Plugin:

codex plugin marketplace add bigbio/mokume
codex plugin add mokume@bigbio

Confirm that the Plugin is installed:

codex plugin list

In the Codex app, the same setup is available under Plugins → Add marketplace. Use the following Git source:

https://github.com/bigbio/mokume

Leave the sparse path empty, install Mokume from the BigBio marketplace, and start a new task so Codex loads the bundled skill and MCP server.

Installation is complete when Codex exposes:

mokume.inspect_dataset
mokume.evaluate_recommendation

The bundled workflow can then be invoked as:

$mokume:analyze-proteomics

Install in Claude Code

Add the same repository as a Claude Code marketplace and install the Plugin:

claude plugin marketplace add bigbio/mokume
claude plugin install mokume@bigbio

If Claude Code is already running, reload its installed plugins:

/reload-plugins

Alternatively, start a new Claude Code session.

The bundled workflow can then be invoked as:

/mokume:analyze-proteomics

Test this draft PR

To test the exact PR checkout before it reaches main, install the wheel and marketplace from the local checkout:

gh repo clone bigbio/mokume
cd mokume
gh pr checkout 81
pip install "./rust[agentic]"

Install the local marketplace in Codex:

codex plugin marketplace add .
codex plugin add mokume@bigbio

Or install the same local marketplace in Claude Code:

claude plugin marketplace add .
claude plugin install mokume@bigbio

Start a new Codex task or run /reload-plugins in Claude Code after installation.

MCP startup

Both Plugin manifests start the bundled local stdio MCP server automatically.

No separate MCP registration is required, and users should not manually run:

mokume mcp serve

The Plugin includes:

• Codex and Claude Code manifests;
• the analyze-proteomics skill;
• a versioned knowledge bundle;
• spike-in Score A benchmark summaries;
• preset and pairwise evidence;
• policy checks for candidate construction;
• contrast-scoped matrix profiling;
• candidate evaluation with explicit ground-truth and no-ground-truth modes;
• peptide-count sidecar support for methods such as DEqMS.

The former Python package-owned LLM client, proposer, reflector, optimizer, and reporting loop are removed.

Differential expression

The differential-expression workflow is expanded and aligned across the Rust and Python implementations.

Changes include:

• adaptive FDR support;
• effect-size gating;
• stable extreme-tail probability handling;
• ensemble differential-expression updates;
• explicit handling of rows that are not eligible for testing;
• peptide-count sidecar support;
• matrix-level native bindings for direct evaluation by the Plugin;
• stricter validation of contrasts, group sizes, thresholds, and candidate options.

These changes preserve missing or ineligible results as explicit non-tested outcomes instead of silently treating them as significant or coercing them into ordinary p-values.

TissueMap

The TissueMap TMT loader now streams reporter-ion intensities through DuckDB rather than materializing and exploding the complete feature table in pandas.

The loader adds:

• canonical and positional reporter-channel mapping;
• deterministic conflict detection;
• GIS/reference-channel detection from QPX metadata;
• exclusion of non-reference pooled-sample sentinel values;
• per-run GIS normalization;
• raw aggregation when no usable GIS channel exists;
• compatibility with LFQ routing;
• configurable loading options.

Regression tests compare the streaming implementation with the previous in-memory behavior and cover canonical, numeric, conflicting, GIS, and LFQ cases.

Pipeline and API consolidation

Additional changes include:

• consolidated protein-quantification workflows;
• aligned TopN, MaxLFQ, DirectLFQ, Sum, Ratio, and piBAQ configuration;
• removal of the obsolete Python-to-Rust subprocess flow;
• shared matrix conversion and thread handling in the native pipeline;
• updated batch-correction and output contracts;
• synchronized Python and Rust periphery modules;
• updated public API exports and lazy optional-dependency loading.

Documentation

The documentation is updated to cover:

• the new mokume and mokume-py distribution model;
• migration from the previous pure-Python mokume distribution;
• the pip-installed console command;
• removal of standalone Cargo installation;
• piBAQ terminology and runtime digestion;
• the Rust wheel architecture;
• Plugin installation and use;
• differential-expression and effect-size behavior;
• updated examples, API references, and maintenance boundaries.

Python requirements are distribution-specific:

• Rust-backed mokume: Python 3.9 or newer;
• mokume-py: Python 3.10 or newer;
• Mokume Plugin and mokume[agentic]: Python 3.10 or newer.

CI and publishing

The CI and release workflows now build and test the two distributions independently.

Validation includes:

• pre-commit checks;
• Cargo tests and cargo audit;
• pure-Python tests on supported Python versions;
• pure-Python wheel and metadata builds;
• Rust-backed abi3 wheels for Linux x86_64/aarch64, macOS x86_64/arm64, and Windows x64;
• Rust sdist generation;
• installed-wheel integration tests;
• pyOpenMS runtime catalog and piBAQ parity tests;
• Plugin and MCP contract tests;
• sidecar drift checks;
• Codacy static analysis.

The release workflows publish:

• mokume from the Rust/maturin project;
• mokume-py from the hatchling project.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 1580 complexity · 79 duplication

Metric	Results
Complexity	1580
Duplication	79

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}