R and Python parity

Understand the shared metasalmon contract and Python-native differences.

Compatibility target

metasalmonpy 0.4.0 aligns its core user-facing behavior with metasalmon 0.4.0. The R package remains the normative Salmon Data Package and ontology contract. Parity means equivalent workflows and safety behavior, not line-for-line implementations.

The version number is a parity claim: it names the metasalmon release whose functionality this package actually delivers, and it is bumped when the mirrored behaviour lands rather than on a calendar. Every deliberate difference is registered in PARITY.md and in the hub’s knowledge/parity-deviations.md.

Workflow	metasalmon	metasalmonpy
One-call package creation	create_sdp()	create_sdp()
Infer package artifacts	infer_salmon_datapackage_artifacts()	infer_salmon_datapackage_artifacts()
Infer a dictionary	infer_dictionary()	infer_dictionary()
Suggest semantics	suggest_semantics()	suggest_semantics()
Apply suggestions	apply_semantic_suggestions()	apply_semantic_suggestions()
Detect term gaps	detect_semantic_term_gaps()	detect_semantic_term_gaps()
Validate a package	validate_salmon_datapackage()	validate_salmon_datapackage()
Rebuild EDH XML	write_edh_xml_from_sdp()	write_edh_xml_from_sdp()
Export reviewed EML	write_eml_from_sdp()	write_eml_from_sdp()
Publish to KNB/DataONE	publish_sdp_to_knb()	publish_sdp_to_knb()
Write SSSOM mapping sets	write_sdp_sssom()	write_sdp_sssom()
Write measurement decompositions	write_sdp_measurement_decompositions()	write_sdp_measurement_decompositions()
Write observation structures	write_sdp_observation_structures()	write_sdp_observation_structures()
Migrate sdp-0.2.0 methods	migrate_sdp_methods()	migrate_sdp_methods()

Shared contracts

• LLM review is strictly opt-in.
• Context alone never triggers a provider call.
• Explicit retrieval sources form a strict allowlist.
• Measurement review uses variable, property, entity, unit, constraint, and statistical-modifier slots. sdp-0.3.0 removed the dictionary method slot; the method role survives for codes.csv term targets.
• Suggested IRIs retain the REVIEW: marker until human approval.
• Deterministic prefill applies every role the evidence allows, matching metasalmon: variable, property, entity and unit whenever a compatible candidate is found, plus a constraint or statistical modifier when the column’s own text carries the evidence for it. The LLM path stays limited to the four core roles on both sides. Everything prefilled is marked REVIEW:. (This bullet described a narrower prefill until 2026-08-24, when hub Q16 ruled the metasalmon behaviour correct and PARITY.md row 57 converged.)
• Provider failures preserve deterministic candidates.
• Term requests require curator review and explicit submission.

Not yet in Python

The honest list of what this package does not have matters as much as the table above. Everything the S10 catch-up stream covered — EML export, KNB/DataONE publication and the deterministic SDP archive, SSSOM mapping sets, measurement decompositions, observation structures, the empty-field missing-value token, declared primary-key validation and tidy-shape warnings, structural credential redaction — has landed. What remains:

• No ranking-profile override system. role_boost and the base source weights are module constants (term_search.ROLE_BOOST), not a merged profile with a ranking_profile argument (hub backlog #87).
• No live-provider evidence harness. The versioned cryptographic capture and cohort-publication machinery is a metasalmon maintainer activity, deliberately not a metasalmonpy CI job.
• Only the 30-row Fraser coho example ships here, not the 173-row starter package.
• No migration or tidy-data guide. metasalmon 0.4.0 added two vignettes (migrating-to-sdp-0-3-0, tidy-data-for-sdp) whose behaviour exists here but whose prose has no counterpart yet.
• ms_setup_github() differs by design: Python cannot create or store a PAT for you — it verifies discovery only.

Each of these carries a row in PARITY.md with the condition that would retire it.

Python-native differences

• pandas DataFrame attributes carry semantic suggestion and assessment tables.
• Interactive chat uses a Python prompt loop and persistent JSON session state.
• Excel and PDF context readers are optional dependencies.
• Routine CI uses deterministic injected provider responses and never consumes OpenAI or OpenRouter credits.
• The resource-intensive live-provider evidence publisher remains an explicit metasalmon maintainer activity rather than a metasalmonpy CI job.

Parity verification

The repository runs an R-to-Python round trip against the current metasalmon main branch in CI. That test checks the package boundary and metadata contracts. Python unit tests cover its native adapters and safety behavior.