feat: add human_gem Python package with load_model()

[edkerk]

Main improvements in this PR:

First increment towards a pip-installable Python interface to Human-GEM (dual-language support). human_gem.load_model() loads Human-GEM as a fully annotated cobra model — reading the YAML via raven-toolbox and merging the cross-references + SBO terms from the annotation tables, which a bare cobra.io.load_yaml_model does not do:

import human_gem
model = human_gem.load_model()   # annotated cobra.Model

• pyproject.toml — package human-gem (deps: cobra, pandas, raven-toolbox)
• human_gem/io.py — load_model(model_dir=None, annotate=True)
• human_gem/annotation.py — the TSV → MIRIAM/SBO merge (packaged home of the logic currently in code/annotateGEM.py)

Verified locally (raven-toolbox 0.3.0): load_model() attaches cross-references to 12698/12877 reactions, 8449/8460 metabolites and all 2848 genes; annotate=False returns the bare model.

This increment is deliberately small and non-disruptive — it adds new files and imports nothing existing, so it does not touch the current MATLAB or Python CI. Planned next increments:

1. reduce code/annotateGEM.py to a thin shim importing from human_gem.annotation (single source of truth) + install the package in the Python CI;
2. promote the ftINIT gene-essentiality and metabolic-task helpers into the package;
3. bundle/resolve the model files for a true pip install distribution.

No model changes.

I hereby confirm that I have:

• Any removed reactions and metabolites have been moved to the corresponding deprecated identifier lists in data/deprecatedIdentifiers/.
• This PR has develop as target branch, and will be resolved with a squash-merge.
• This PR has main as target branch, and will be resolved with a merge commit.

[github-actions]

Model quality report

⚠️ 6 pre-existing finding(s), no regressions vs develop. Non-blocking.

Each check name links to its explanation in the testResults README.

Model checks

Duplicate keys (model unloadable) and no growth block the merge; every other row is a non-blocking report.

Check	Result	Δ vs develop
Duplicate !!omap keys	0	0	✅
Growth (biomass producible)	125	0	✅
Reactions with no metabolites	0	0	✅
Model / annotation-table inconsistencies	0	0	✅
Removed reactions or metabolites not deprecated	0	0	✅
Metabolites missing formula	0	0	✅
Metabolites missing charge	0	0	✅
Reaction bound / GPR issues	0	0	✅
Exact-duplicate reaction groups	0	0	✅
Unused metabolites	0	0	✅
Unused genes	0	0	✅
Malformed cross-references	0	0	✅
Cross-refs inconsistent across compartments	3	0	⚠️

MACAW and mass/charge balance

Check	Result	Δ vs develop
Reactions flagged by MACAW dead-end test	2510	0	⚠️
Reactions flagged as MACAW duplicates	377	0	⚠️
Mass-imbalanced reactions	87	0	⚠️
Charge-imbalanced reactions	234	0	⚠️
Structure vs formula/charge inconsistencies	397	0	⚠️

Model file and metabolic tasks

Check	Result
YAML round-trip (cobrapy)	pass	✅
YAML round-trip (RAVEN)	pass	✅
YAML lint	pass	✅
Essential metabolic tasks	57 passed	✅
Verification metabolic tasks	21 passed	✅

MEMOTE

Total score: 63.2% (core subset)   0

Section	Score	Δ vs base
consistency	42.4%	0
annotation_met	73.0%	0
annotation_rxn	72.7%	0
annotation_gene	46.7%	0
annotation_sbo	81.7%	0

Per-test scores

Section	Test	Score
Consistency	Stoichiometric Consistency	100.0%
Consistency	Mass Balance	0.8%
Consistency	Charge Balance	2.1%
Consistency	Metabolite Connectivity	0.0%
Consistency	Unbounded Flux In Default Medium	100.0%
Annotation - Metabolites	Presence of Metabolite Annotation	0.0%
Annotation - Metabolites	Metabolite Annotations Per Database	62.3%
Annotation - Metabolites	Metabolite Annotation Conformity Per Database	45.8%
Annotation - Metabolites	Uniform Metabolite Identifier Namespace	0.0%
Annotation - Reactions	Presence of Reaction Annotation	0.0%
Annotation - Reactions	Reaction Annotations Per Database	75.9%
Annotation - Reactions	Reaction Annotation Conformity Per Database	33.3%
Annotation - Reactions	Uniform Reaction Identifier Namespace	0.0%
Annotation - Genes	Presence of Gene Annotation	0.0%
Annotation - Genes	Gene Annotations Per Database	80.0%
Annotation - Genes	Gene Annotation Conformity Per Database	80.0%
Annotation - SBO Terms	Metabolite General SBO Presence	0.0%
Annotation - SBO Terms	Metabolite SBO:0000247 Presence	0.1%
Annotation - SBO Terms	Reaction General SBO Presence	0.0%
Annotation - SBO Terms	Metabolic Reaction SBO:0000176 Presence	0.0%
Annotation - SBO Terms	Transport Reaction SBO:0000185 Presence	0.7%
Annotation - SBO Terms	Exchange Reaction SBO:0000627 Presence	0.0%
Annotation - SBO Terms	Demand Reaction SBO:0000628 Presence	100.0%
Annotation - SBO Terms	Sink Reactions SBO:0000632 Presence	100.0%
Annotation - SBO Terms	Gene General SBO Presence	0.0%
Annotation - SBO Terms	Gene SBO:0000243 Presence	0.0%
Annotation - SBO Terms	Biomass Reactions SBO:0000629 Presence	0.0%

Full suite: 64.2%   0 · from the last /run memote.

The score above is the fast core subset. Comment /run memote to run the full suite on this pull request; the score updates here when it finishes.

Gene essentiality (Hart 2015)

Not run automatically (it takes hours). Comment /run gene-essentiality to run it on this pull request; the result posts as its own comment.

❌ = a count rose vs the target branch (regression) · ⚠️ = a pre-existing non-zero finding (non-blocking) · ⏳ = still running. Counts link to the CSV listing the exact entries.

Full workflow run · this comment is edited as results come in