Implement a provider-neutral binding-site catalogue and reusable public API for MolSysSuite

Read the linked implementation plan, design, review, and synthetic specimens under devguide/, then inspect the existing SearchDomain/BoxRegion implementation in dockingmt/core/search_domain.py. Start by closing P0a’s minimal local data contract and the first B1/B2 declaration and replay slice, using the plan’s prerequisites and milestones. Done means a small public increment that preserves the specified distinctions and passes its declared checks; runtime implementation and receiving are still pending.

Design and implementation work plan

Detailed work plan — reviewed version 2, before runtime changes: BindingSite implementation and work plan. It records operation-specific prerequisites, explicit selection/TopoMT adapter work, structural and check/use controls, M1/M2/M3 milestones and first-profile closeout.

Maintained proposal — audited revision 2: Full design, request-by-request audit and worked handoffs, synthetic review specimens.

The three follow-up reviews are favorable at design level. Next close P0a's minimal local data contract and deliver the first B1/B2 declaration/replay slice; molecular/shared coordination and offered consumer inputs apply to their respective operations. Runtime implementation and executed receiving remain pending. The public assurance mechanism remains a proposed profile decision, not a new callable or shared schema freeze.

Reviewed work-plan checkpoint and exact-source documentation verification. Audited revision-2 delivery. Immutable comparison baselines: first design, initial second draft, audited review, initial work plan.

Request and resulting behavior

Please design and implement a provider-neutral binding-site catalogue and a reusable public BindingMT contract/API, usable directly by researchers and by MolSysMT, TopoMT, PharmacophoreMT, PeptideMT and other consumers.

A researcher should be able to declare a binding-region hypothesis using the information actually available—atoms, residues/groups, a sphere, a box or an owner-provided topographic representation—and inspect its molecular context, scientific definition, evidence and limitations. Consumers should exchange and apply these declarations without inventing incompatible meanings of “binding site” or silently turning membership into mandatory contacts.

The investigator requests this owner implementation issue. BindingMT should lead the binding-domain scientific specification and implementation; cross-component review and MolSysSuite agreement/adoption remain explicit deliverables. The entry names and detailed API below are proposals for that review, not a frozen schema or a declaration that other components have already adopted it. Resolve consequential semantics before implementation, then deliver a small, useful public increment.

Existing context and related work

• BindingMT's expanded binding domain was accepted under #108. Repository renaming alone does not qualify new scientific capabilities or installed artifacts.
• Existing search-domain provenance #55 and the published SearchDomain/BoxRegion source already preserve selection-derived geometry. Reuse that behavior; a search domain is one application of site information.
• HADDOCK3 #109 and Boltz-2 #110 are concrete future consumers. Their provider implementation/qualification remains separately owned work.
• TopoMT #59 establishes its accepted support/identity/classification/evaluation contract. Reuse it rather than introduce competing geometry semantics. Contextual contact/occupancy work is already tracked in TopoMT #62; predicted-site provider receiving includes #139.
• MolSysMT owns molecular identity, chemistry, selection, correspondence and general geometry/interactions; see its interaction-analysis contract.
• PharmacophoreMT's InteractionSite is a local pharmacophoric feature. Receptor-feature hypothesis generation and scientific workflow qualification are tracked in #87 and #103.
• PeptideMT #33 supplies a consumer question: fixed-partner MDM2–p53 preparation, with two separate structural tests, first with a declared site and later without supplied site information. It motivates requirements; it must not define a target-specific public API.

Scientific distinctions to preserve

Define the catalogue for binding sites / binding-region hypotheses, not every software object named site.

1. Binding site: a molecular region associated, or hypothesized to be associated, with recognition/association in a declared context. Evidence may be experimental, annotated, computed or hypothetical. A partner or partner class may be unknown.
2. Pocket/cavity/groove: a topographic finding with an owner-defined support and classification. A predicted pocket is not automatically evidence of biological binding; a binding patch need not be a cavity.
3. Interface: partner- and state-dependent association/contact/surface characterization, potentially involving several supports. Geometric contacts, buried surface and energetic importance are different observations.
4. Search domain: where a protocol explores; guidance: information that biases exploration; restraint/constraint: an explicit requirement or penalty. Their actual enforcement must be disclosed.
5. Pharmacophore: a chemical/steric recognition hypothesis with features, directions, tolerances and exclusions. Preserve PharmacophoreMT's existing feature semantics.

Keep structural quality, provider confidence, topographic/ligandability scores and binding-affinity evidence distinct. Do not attach a universal binding probability to a site or promote a geometric contact into an experimental energetic hotspot.

Proposed representation catalogue

Use site_by_* as working catalogue notation. Here “by” means represented by. The owner may choose consistent public factories such as binding_site.from_residues(...); exact namespaces/classes/aliases require review.

Define these entries and their capability/status clearly. Start with the smallest useful public profile: atom/residue/group membership and explicit sphere/box declarations, plus faithful references to richer owner outputs where supported. The catalogue should distinguish implemented, representable, recoverable and unsupported operations. Listing a rich representation does not require implementing every geometry algorithm or fabricating conversions before the first delivery.

Allow multiple linked views, overlapping sites, extended peptide grooves and composite/disjoint regions. A box-only hypothesis need not invent residue membership; a sequence annotation need not invent coordinates.

Separate view, defining criterion/provenance and application

The contract must preserve three independent facts:

• Representation: the available atom/residue/group or geometric view.
• Definition/origin: annotation, observed contacts, surface burial, topographic finding, predicted ligandability or manual hypothesis, with its exact evidence/criterion.
• Application: annotation, search domain, soft guidance, restraint/constraint or evaluation reference, including strength/enforcement.

These are not necessarily exclusive origin labels: a curated annotation may cite a contact calculation. Preserve that derivation chain. A residue set from a permissive contact rule and one selected as a broad search patch are not equivalent merely because they have the same container type.

For contact-derived definitions, record both participants/atom populations, atom/radius/chemical criteria, exact inequality, units, PBC and atom-to-group aggregation. Surface-burial definitions retain their method, radii/probe and per-partner versus total-area convention. Topographic/predicted sites retain their original provider definitions. There is no universal binding_site_cutoff: contact distance, selection radius, probe radius, box padding, pharmacophore tolerance, restraint distance and evaluation threshold remain distinct parameters.

Derivation names such as site_from_contacts or site_from_topography, if useful, must remain distinguishable from view names. Reuse the owning calculation instead of adding a parallel contact/pocket engine in BindingMT.

Public data, identity and lifecycle obligations

Agree a lightweight scientific contract before freezing classes or serialization:

• Preserve source annotation/feature identity separately from the contextual site occurrence and any cross-structure correspondence. Equal centers, atom sets or display IDs do not prove equivalent sites.
• Identify molecular source/snapshot, participants, assembly/symmetry, structure and chemical state. Preserve source IDs alongside computational atom/group indices, selection syntax and actual resolved coverage. Do not confuse source residue numbers with model-relative indices.
• Preserve coordinate reference/alignment, units through PyUnitWizard, original provider quantities and each available view's support/membership role.
• Retain producer/method/provider/model/version, parameters, evidence, uncertainty when supplied, and derivation history. Unknown, evaluated-empty, unsupported and failed remain distinguishable.
• Receive incomplete declarations explicitly. Missing coordinates, atoms, mapping or geometry must not become fabricated data or silently computed empty results.
• Keep molecular sources and native provider outputs unchanged. Generated/removed atoms and partial-chemistry completion require explicit correspondence; new atoms do not silently inherit native confidence or membership.
• Define safe copying, source immutability, coordinate transforms, remapping and invalidation after molecular edits. Across structures/ensembles, retain contextual occurrences and declared correspondence rather than assume constant membership.
• Provide faithful save/read or an owner-supported portable representation with an explicit version/compatibility policy. Replaying a record must not require original engines, weights, GPU or live molecular providers when its saved data suffice; unresolved capabilities remain explicit.
• Avoid a mandatory dependency cycle: TopoMT must remain able to report a pocket without importing BindingMT. Reuse owner objects/references and supported interchange; this issue does not prescribe a new shared package or universal inheritance tree.

Provider projections and consumer behavior

Expose inspectable projections/applications with the original declaration retained:

• Residues → atoms: declared expansion, map, missing/generated atoms and roles.
• Atoms/points → box: algorithm, selected structure/state, orientation/padding and extra included space.
• Topographic support → domain: exact geometry versus enclosing approximation, exclusions and unavailable capabilities.
• Region → HADDOCK information: reviewed active/passive interpretation and actual ambiguous restraints. Lining membership alone does not make every residue an obligatory contact.
• Region → Boltz pocket: chain/sequence-relative mappings, explicit contact-distance and forcing semantics. A broad region and a per-residue contact requirement may supply different priors.
• Receptor information → pharmacophore: consume PharmacophoreMT hypotheses, preserving complementary features, directions/tolerances, exclusions and omissions.

The catalogue should support these boundaries; actual HADDOCK3/Boltz-2 adapters remain #109/#110 deliverables. No selected provider is excluded solely because it supports fewer views or reduced chemistry. Offer justified explicit approximations; if a required meaning cannot be expressed, report that specific request as unsupported instead of silently dropping or strengthening it.

Ownership and harmonization deliverables

Please obtain review from the affected owners and register the shared agreement/adoption route in MolSysSuite, checking existing issues first. Keep one authoritative definition per concern and link it; avoid competing copied catalogues. Creating this issue does not itself establish suite-wide consensus or authorize unreviewed changes to sibling APIs. Component relationship labels identify the concrete dependencies/reviewers; no individual assignee or release deadline is imposed.

Staged delivery and acceptance

1. Scientific/API decision: document the vocabulary, catalogue entries, minimal profile, identity/mapping rules, partial/unknown behavior, projection semantics and unresolved decisions. Obtain owner review before freezing cross-component meanings.
2. Small public implementation: deliver the agreed data-only declaration/inspection and saved-record profile, composing existing owner tools. Preserve current search-domain and saved-result behavior; do not turn every catalogue concept into an empty framework class.
3. Consumer examples and qualification: provide public examples independent of PeptideMT and a source-pinned consumer handoff. Exercise the actual public boundary and faithful replay, with explicit supported/unsupported capabilities and no original engine requirement for data-only use.
4. Coordinated adoption: link central agreement and owner-specific migrations/tests, with published source/artifact identities and remaining limits. An owner test is not proof of adoption by every consumer.

Acceptance should include independently interpretable cases:

• A residue/group annotation with incomplete or absent 3D mapping survives inspection/replay honestly.
• Atom/residue/group views retain roles, order/correspondence, source numbering and chemical/structure context through copy/save/read without mutating inputs.
• Sphere/box declarations enforce unit/dimension/extent rules; equivalent units and compatible rigid transforms preserve the declared geometry.
• Expanding membership or enclosing a region reports its policy, derivation and information loss; no hidden binding cutoff or contact requirement appears.
• Flat/extended/composite patches are supported by declared views without invented cavities; equal lining atoms do not imply equal spatial support.
• Unknown, unsupported, failed and evaluated-empty remain distinct; unsupported requests produce actionable diagnostics and preserve the original declaration.
• Molecular/coordinate/state changes remap or invalidate dependent views explicitly; ambiguous source/model numbering is handled without guessing.
• Public saved-record reading works in a fresh process without optional engines/weights/GPU/network and preserves original provenance rather than crediting a new calculation.
• A provider projection that would strengthen a broad patch into mandatory contacts is explicit and reviewable; an unavailable capability is not silently discarded.
• Existing search-domain/result compatibility is retained, and documentation distinguishes definition, implementation, owner qualification and consumer adoption.

MDM2–p53 is a useful consumer illustration: a supplied receptor-region declaration must be separable from withheld reference peptide coordinates, and a later no-supplied-site configuration must not inherit its derived box/pocket/restraints. This issue chooses no MDM2 residue list, distance, chemical preparation or sampling/evaluation threshold. A known reference is not an independent benchmark.

Scope limits

This requests owner design and implementation of the catalogue/public contract. It does not commission engine installation, weight acquisition, neural/GPU execution, binder generation, new affinity/free-energy calculations, scientific campaigns, package releases or modification of previously accepted evidence. Full implementations of all specialized geometry methods and all future provider projections are not prerequisites for the bounded initial profile. Review important scientific/architectural changes under the owners' normal governance.

Primary terminology and software references

• IUPAC binding site B00649: functional molecular recognition region, without a universal sphere or distance cutoff.
• PDBx/mmCIF struct_site_gen and UniProtKB BINDING annotations: structural/sequence membership and evidence.
• P2Rank original paper: predicted ligandable surface-point clusters, distinct from a universal closed pocket.
• IUPAC pharmacophore 11485: chemical/steric feature hypotheses.
• HADDOCK active/passive semantics and pinned Boltz pocket/contact/template contract: different provider-specific uses of site information that need faithful translation.

All references are public. No private inventories, native receipts, attachments or host details are part of this request.