MonomerLibrary¶

MonomerLibrary holds the dictionary that gives HELM symbols meaning. It starts empty; you populate it from a file, from records, or from TMR, Forge or the local cache. See Why a monomer library is mandatory for the background, and Load a monomer library for a worked example of each source.

Choosing a source¶

Constructor	Use when
`MonomerLibrary()` then `load_from_file(path)`	You have a dictionary as JSON on disk
`MonomerLibrary.from_records(records)`	You already hold the records in memory
`MonomerLibrary.from_tmr(...)`	You want the current dictionary from TMR
`MonomerLibrary.from_forge(...)`	You want it through Forge instead
`MonomerLibrary.from_cache(name, version)`	You pulled it earlier and are now offline

from_tmr and from_forge need the remote extra for httpx. A warm cache is served without it.

Record format¶

Each record is a dictionary. Only symbol is strictly required, but a record without polymerType and rgroups cannot take part in connections, and one without smiles cannot contribute to a structure or molecular weight.

{
    "symbol": "beta-Ala",
    "name": "beta-Alanine",
    "monomerType": "Backbone",        # Backbone, Branch or Terminal
    "polymerType": "PEPTIDE",         # RNA, PEPTIDE or CHEM
    "naturalAnalog": "A",
    "smiles": "[*:1]NCCC(=O)[*:2]",
    "rgroups": [
        {"label": "R1", "capGroupSmiles": "[*:1][H]"},
        {"label": "R2", "capGroupSmiles": "[*:2]O"},
    ],
    "uuid": "example-0001",
}

uuid matters more than it looks: cartoon colour maps key on it, so a record without one draws grey.

Symbols are namespaced by polymer type¶

get_definition takes an optional polymer_type because one symbol can carry two meanings. A is adenine in RNA and alanine in a peptide. Pass the polymer type when you need the unambiguous answer.

API reference¶

`MonomerLibrary` ¶

Manages loading, storing, and accessing monomer definitions.

HELMshaker ships no bundled monomers. A new MonomerLibrary() is empty; populate it via :meth:from_records, :meth:load_from_file, :meth:register_monomer, :meth:from_tmr / :meth:from_forge, or :meth:from_cache.

`get_definition(monomer_id, polymer_type=None)` ¶

Retrieves a monomer definition by its symbol, with optional context to resolve ambiguity.

Parameters:

Name	Type	Description	Default
`monomer_id`	`str`	The symbol of the monomer (e.g., 'A').	required
`polymer_type`	`Optional[str]`	The context (e.g., 'RNA', 'PEPTIDE') to help select the correct monomer if multiple definitions exist for the same symbol.	`None`

Returns:

Type	Description
`Optional[MonomerDefinition]`	Optional[MonomerDefinition]: The best-matching monomer definition, or None if not found.

`get_connection_points(symbol, polymer_type=None)` ¶

Returns the set of R-group attachment labels for a monomer symbol.

Mirrors PepRe's all_monomers.get_connection_points: an unknown symbol yields an empty set (which callers treat as "monomer not known").

Parameters:

Name	Type	Description	Default
`symbol`	`str`	The monomer symbol (e.g. `C` or `MeC`).	required
`polymer_type`	`Optional[str]`	Optional context to disambiguate symbols that exist under more than one polymer type.	`None`

Returns:

Type	Description
`set`	set[str]: The attachment-point labels (e.g. `{"R1", "R2", "R3"}`), or
`set`	an empty set if the symbol is not in the library.

`is_chem(symbol)` ¶

Returns True if a definition exists for symbol with polymer type CHEM.

Parameters:

Name	Type	Description	Default
`symbol`	`str`	The monomer symbol.	required

Returns:

Name	Type	Description
`bool`	`bool`	True if any definition for the symbol is a CHEM monomer.

`get_definition_by_uuid(uuid)` ¶

Retrieves a monomer definition by its UUID.

`register_monomer(definition)` ¶

Programmatically adds a monomer definition. If the symbol already exists, it appends the new definition.

`load_records(records, overwrite=False)` ¶

Loads and registers monomers from an iterable of record dicts.

Records use HELMshaker's schema (symbol, name, monomerType, polymerType, smiles, naturalAnalog, rgroups ...), the same shape as the bundled library files and the Forge helmshaker-library feed.

Parameters:

Name	Type	Description	Default
`records`	`Iterable[Dict[str, Any]]`	Iterable of monomer record dicts.	required
`overwrite`	`bool`	If True, clears the existing library before loading.	`False`

Returns:

Type	Description
`int`	The number of monomers registered.

`load_from_file(filepath, overwrite=False)` ¶

Loads and registers monomers from a JSON file.

Parameters:

Name	Type	Description	Default
`filepath`	`str`	The path to the JSON library file.	required
`overwrite`	`bool`	If True, clears the entire existing library before loading. If False, merges the new monomers with existing ones.	`False`

`from_records(records)` `classmethod` ¶

Creates a MonomerLibrary from an iterable of record dicts.

Parameters:

Name	Type	Description	Default
`records`	`Iterable[Dict[str, Any]]`	Iterable of monomer record dicts in HELMshaker's schema.	required

Returns:

Type	Description
`MonomerLibrary`	A new MonomerLibrary containing only those monomers.

`from_forge(base_url, dictionary=None, version=None, token=None, use_cache=True, refresh=False, **kwargs)` `classmethod` ¶

Fetches a monomer library from Forge (with caching) and loads it.

Delegates to :mod:helmshaker.remote, which handles the HTTP fetch, the on-disk cache and offline fallback. Requires the [remote] extra (httpx) for the network path; a warm cache is served without it.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	Forge base URL (e.g. `https://forge.roche.com`).	required
`dictionary`	`Optional[str]`	Monomer dictionary identifier (default: Forge's default).	`None`
`version`	`Optional[str]`	Dictionary version (default: latest).	`None`
`token`	`Optional[str]`	Bearer token accepted by Forge's API.	`None`
`use_cache`	`bool`	Serve a fresh cache entry instead of refetching.	`True`
`refresh`	`bool`	Force a refetch even if a fresh cache entry exists.	`False`
`**kwargs`	`Any`	Forwarded to :func:`helmshaker.remote.pull_library`.	`{}`

Returns:

Type	Description
`MonomerLibrary`	A MonomerLibrary for the requested dictionary/version.

`from_tmr(base_url, dictionary, version=None, token=None, use_cache=True, refresh=False, **kwargs)` `classmethod` ¶

Fetches a monomer library directly from TMR (with caching) and loads it.

The TMR-direct counterpart to :meth:from_forge. Delegates to :mod:helmshaker.remote_tmr, which resolves the dictionary name to its pk through the pRED Gravitee gateway, fetches the TMR MonomerResponse objects, maps them into HELMshaker's schema and handles the on-disk cache and offline fallback. Requires the [remote] extra (httpx) for the network path; a warm cache is served without it.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	TMR gateway base URL (e.g. `https://api.core.minerva.roche.com/gateway/tmr-tst`).	required
`dictionary`	`str`	Monomer dictionary name (a pk-looking value is accepted directly).	required
`version`	`Optional[str]`	Dictionary version (default: latest).	`None`
`token`	`Optional[str]`	Janus OIDC bearer token accepted by the gateway.	`None`
`use_cache`	`bool`	Serve a fresh cache entry instead of refetching.	`True`
`refresh`	`bool`	Force a refetch even if a fresh cache entry exists.	`False`
`**kwargs`	`Any`	Forwarded to :func:`helmshaker.remote_tmr.pull_library`.	`{}`

Returns:

Type	Description
`MonomerLibrary`	A MonomerLibrary for the requested dictionary/version.

`from_cache(dictionary, version)` `classmethod` ¶

Creates a MonomerLibrary from a cached dictionary/version.

Parameters:

Name	Type	Description	Default
`dictionary`	`str`	Monomer dictionary identifier.	required
`version`	`str`	Dictionary version.	required

Returns:

Type	Description
`MonomerLibrary`	A new MonomerLibrary loaded from the cache.

Raises:

Type	Description
`FileNotFoundError`	If no cache entry exists for that dictionary/version.

`symbols()` ¶

Returns the sorted list of monomer symbols in the library.

Useful for inspecting a freshly loaded or pulled dictionary. Pass a symbol to :meth:get_definition for the full record.

Returns:

Type	Description
`List[str]`	A sorted list of the distinct monomer symbols.

`MonomerDefinition` `dataclass` ¶

Represents a complete monomer definition, aligned with the Pistoia HELM format.

`AttachmentPoint` `dataclass` ¶

Represents an R-group attachment point on a monomer.

MonomerLibrary¶

Choosing a source¶

Record format¶

Symbols are namespaced by polymer type¶

API reference¶

MonomerLibrary ¶

get_definition(monomer_id, polymer_type=None) ¶

get_connection_points(symbol, polymer_type=None) ¶

is_chem(symbol) ¶

get_definition_by_uuid(uuid) ¶

register_monomer(definition) ¶

load_records(records, overwrite=False) ¶

load_from_file(filepath, overwrite=False) ¶

from_records(records) classmethod ¶

from_forge(base_url, dictionary=None, version=None, token=None, use_cache=True, refresh=False, **kwargs) classmethod ¶

from_tmr(base_url, dictionary, version=None, token=None, use_cache=True, refresh=False, **kwargs) classmethod ¶

from_cache(dictionary, version) classmethod ¶

symbols() ¶

MonomerDefinition dataclass ¶

AttachmentPoint dataclass ¶

`MonomerLibrary` ¶

`get_definition(monomer_id, polymer_type=None)` ¶

`get_connection_points(symbol, polymer_type=None)` ¶

`is_chem(symbol)` ¶

`get_definition_by_uuid(uuid)` ¶

`register_monomer(definition)` ¶

`load_records(records, overwrite=False)` ¶

`load_from_file(filepath, overwrite=False)` ¶

`from_records(records)` `classmethod` ¶

`from_forge(base_url, dictionary=None, version=None, token=None, use_cache=True, refresh=False, **kwargs)` `classmethod` ¶

`from_tmr(base_url, dictionary, version=None, token=None, use_cache=True, refresh=False, **kwargs)` `classmethod` ¶

`from_cache(dictionary, version)` `classmethod` ¶

`symbols()` ¶

`MonomerDefinition` `dataclass` ¶

`AttachmentPoint` `dataclass` ¶