synkit 1.6.5__py3-none-win_amd64.whl

synkit/IO/combinatorial/graph_to_smarts.py

@@ -0,0 +1,186 @@
+import networkx as nx
+from typing import List, Dict, Any, Set, Optional
+from rdkit import Chem
+from rdkit.Chem import AllChem
+
+
+class GraphToSMARTS:
+    """Convert NetworkX graphs (with placeholder nodes/constraints) into SMARTS or reaction SMARTS strings.
+
+    :param placeholder_labels: Set of labels recognized as placeholders (e.g., '_R', 'X', 'Y', 'Z').
+    :type placeholder_labels: Optional[Set[str]]
+    :param validate: If True, validate generated SMARTS or reaction SMARTS using RDKit.
+    :type validate: bool
+
+    .. rubric:: Examples
+
+    >>> G = nx.Graph()
+    >>> G.add_node(1, label='C', constraint=None)
+    >>> G.add_node(2, label='O', constraint=None)
+    >>> G.add_edge(1, 2, order=1)
+    >>> g2s = GraphToSMARTS()
+    >>> smarts = g2s.graph_to_smarts(G)
+    >>> isinstance(smarts, str)
+    True
+    """
+
+    def __init__(
+        self, placeholder_labels: Optional[Set[str]] = None, validate: bool = True
+    ) -> None:
+        """Initialize the GraphToSMARTS converter.
+
+        :param placeholder_labels: Labels to treat as wildcard placeholders; defaults to {'_R','X','Y','Z'}.
+        :type placeholder_labels: Optional[Set[str]]
+        :param validate: Whether to validate SMARTS with RDKit if available.
+        :type validate: bool
+        :return: None
+        :rtype: None
+        """
+        if placeholder_labels is None:
+            placeholder_labels = {"_R", "X", "Y", "Z"}
+        self.placeholder_labels: Set[str] = placeholder_labels
+        self.validate: bool = validate
+
+    def graph_to_smarts(self, G: nx.Graph) -> str:
+        """Convert a NetworkX graph into a SMARTS string representation.
+
+        :param G: NetworkX Graph with node attributes:
+                  - 'label': str atomic label or placeholder
+                  - 'constraint': Optional[List[str]] allowed element list for placeholders
+                  and edge attribute:
+                  - 'order': float bond order (1,1.5,2,3)
+        :type G: nx.Graph
+        :return: SMARTS string encoding the graph structure.
+        :rtype: str
+        :raises ValueError: If RDKit fails to parse the generated SMARTS when validate=True.
+
+        .. rubric:: Examples
+
+        >>> G = nx.Graph()
+        >>> G.add_node(1, label='C', constraint=None)
+        >>> G.add_node(2, label='O', constraint=None)
+        >>> G.add_edge(1, 2, order=1)
+        >>> smarts = GraphToSMARTS().graph_to_smarts(G)
+        >>> smarts
+        '[C:1](-[O:2])'
+        """
+        bond_sym: Dict[float, str] = {1: "-", 1.5: ":", 2: "=", 3: "#"}
+
+        def bracket(node: Any, data: Dict[str, Any]) -> str:
+            map_num = node
+            if data.get("constraint"):
+                core = ",".join(data["constraint"])
+            else:
+                core = data["label"]
+            return f"[{core}:{map_num}]"
+
+        def choose_root(sub: nx.Graph) -> Any:
+            real_nodes = [
+                n
+                for n, d in sub.nodes(data=True)
+                if d.get("label") not in self.placeholder_labels
+            ]
+            if real_nodes:
+                return max(real_nodes, key=sub.degree)
+            return min(sub.nodes)
+
+        def rec(node: Any, parent: Any, sub: nx.Graph, visited: Set[Any]) -> str:
+            visited.add(node)
+            s = bracket(node, sub.nodes[node])
+            for nbr in sub.neighbors(node):
+                if nbr == parent:
+                    continue
+                order = sub[node][nbr].get("order", 1)
+                bond = bond_sym.get(order, "-")
+                s += f"({bond}{rec(nbr, node, sub, visited)})"
+            return s
+
+        frags: List[str] = []
+        for comp in nx.connected_components(G):
+            subgraph = G.subgraph(comp)
+            root = choose_root(subgraph)
+            frags.append(rec(root, None, subgraph, set()))
+
+        smarts: str = ".".join(frags)
+
+        if self.validate:
+            try:
+                if not Chem.MolFromSmarts(smarts):
+                    raise ValueError("RDKit could not parse generated SMARTS.")
+            except ImportError:
+                pass
+
+        return smarts
+
+    def graphs_to_rxn_smarts(self, reactant: nx.Graph, product: nx.Graph) -> str:
+        """Construct a reaction SMARTS string from reactant and product graphs.
+
+        :param reactant: Reactant NetworkX graph.
+        :type reactant: nx.Graph
+        :param product: Product NetworkX graph.
+        :type product: nx.Graph
+        :return: Reaction SMARTS in the form 'reactants>>products'.
+        :rtype: str
+        :raises ValueError: If RDKit fails to parse the reaction SMARTS when validate=True.
+
+        .. rubric:: Examples
+
+        >>> G1 = nx.Graph()
+        >>> G1.add_node(1, label='C', constraint=None)
+        >>> G1.add_node(2, label='O', constraint=None)
+        >>> G1.add_edge(1, 2, order=1)
+        >>> G2 = nx.Graph()
+        >>> G2.add_node(1, label='C', constraint=None)
+        >>> G2.add_node(2, label='O', constraint=None)
+        >>> G2.add_edge(1, 2, order=2)
+        >>> rxn = GraphToSMARTS().graphs_to_rxn_smarts(G1, G2)
+        >>> rxn
+        '[C:1](-[O:2])>>[C:1]([O:2])='
+        """
+        sm_r: str = self.graph_to_smarts(reactant)
+        sm_p: str = self.graph_to_smarts(product)
+        rxn: str = f"{sm_r}>>{sm_p}"
+
+        if self.validate:
+            try:
+                if not AllChem.ReactionFromSmarts(rxn):
+                    raise ValueError("RDKit could not parse generated reaction SMARTS.")
+            except ImportError:
+                pass
+
+        return rxn
+
+    def __repr__(self) -> str:
+        """Return an unambiguous representation of the converter instance.
+
+        :return: String showing placeholder labels and validation setting.
+        :rtype: str
+        """
+        return (
+            f"<GraphToSMARTS placeholder_labels={self.placeholder_labels}, "
+            f"validate={self.validate}>"
+        )
+
+    def help(self) -> str:
+        """Provide usage information for GraphToSMARTS.
+
+        :return: Multi-line help string describing available methods.
+        :rtype: str
+
+        .. rubric:: Examples
+
+        >>> print(GraphToSMARTS().help())  # doctest:+NORMALIZE_WHITESPACE
+        GraphToSMARTS(placeholder_labels=None, validate=True)
+         - Use .graph_to_smarts(G) for a single graph
+         - Use .graphs_to_rxn_smarts(G_react, G_prod) for reaction SMARTS
+        """
+        return (
+            "GraphToSMARTS(placeholder_labels=None, validate=True)\n"
+            " - Use .graph_to_smarts(G) for a single graph\n"
+            " - Use .graphs_to_rxn_smarts(G_react, G_prod) for reaction SMARTS\n"
+            "Node attributes expected:\n"
+            "  label: str (e.g., 'C', '_R', 'H+')\n"
+            "  constraint: Optional[List[str]] for placeholders\n"
+            "Edge attribute:\n"
+            "  order: float (1, 1.5, 2, 3) mapped to '-', ':', '=', '#'\n"
+        )

synkit/IO/combinatorial/smarts_expander.py

@@ -0,0 +1,147 @@
+import re
+import itertools
+from typing import List, Dict, Tuple, Iterator, Union
+
+
+class SMARTSExpander:
+    """Efficiently enumerate all valid reaction SMARTS by expanding atom-list
+    placeholders like [C,N,O,P,S:9], ensuring that each atom-map uses the same
+    element everywhere it appears (on both sides of a reaction).
+
+    :param smarts: SMARTS string, possibly containing one or more atom-list placeholders.
+    :type smarts: str
+    :return: Expanded SMARTS strings without atom-list placeholders.
+    :rtype: List[str]
+    :raises ValueError: If no valid expansions exist due to incompatible element lists.
+
+    Example usage::
+
+        >>> rxn = (
+        ...     '[H+:6].[C:7](-[O:8](-[H:12]))(-[C,N,O,P,S:9])'
+        ...     '(-[C,N,O,P,S:10])(-[H:11]).'
+        ...     '[C:2](-[S:4](-[C,N,O,P,S:5]))(-[C,N,O,P,S:1])(=[O:3])>>'
+        ...     '[S:4](-[H:6])(-[C,N,O,P,S:5]).[H+:12].'
+        ...     '[C:7](-[O:8](-[C:2](-[C,N,O,P,S:1])(=[O:3])))(-[C,N,O,P,S:9])'
+        ...     '(-[C,N,O,P,S:10])(-[H:11])'
+        ... )
+        >>> ex = SMARTSExpander.expand(rxn)
+        >>> len(ex)
+        625
+        >>> ex[:3]  # first three expansions
+        ['[H+:6].[C:7](-[O:8](-[H:12]))(-[C:9])(-[C:10])(-[H:11]).[C:2]...'
+        '>>',
+        '...',
+        '...']
+    """
+
+    _PAT = re.compile(r"\[([A-Z][a-z]?(?:,[A-Z][a-z]?)*)(:[0-9]+)\]")
+
+    @staticmethod
+    def _extract_map_to_elements(matches: List[re.Match]) -> Dict[str, List[str]]:
+        """Build a mapping from atom-map to the intersection of allowed elements.
+
+        :param matches: List of regex match objects for placeholders.
+        :type matches: List[re.Match]
+        :return: Dictionary mapping ":map" to sorted list of shared elements.
+        :rtype: Dict[str, List[str]]
+        """
+        amap2set: Dict[str, set] = {}
+        for m in matches:
+            elems = set(m.group(1).split(","))
+            amap = m.group(2)
+            if amap not in amap2set:
+                amap2set[amap] = elems
+            else:
+                amap2set[amap] &= elems
+        for amap, s in amap2set.items():
+            if not s:
+                raise ValueError(f"No overlapping elements for atom-map {amap}")
+        return {amap: sorted(s) for amap, s in amap2set.items()}
+
+    @staticmethod
+    def _build_template(
+        smarts: str, matches: List[re.Match]
+    ) -> Tuple[List[Union[str, str]], List[str]]:
+        """Build a list of string segments and placeholders for reconstruction.
+
+        :param smarts: Original SMARTS string.
+        :type smarts: str
+        :param matches: Regex matches for placeholders.
+        :type matches: List[re.Match]
+        :return: Tuple of list of segments and placeholder order.
+        :rtype: Tuple[List[Union[str, str]], List[str]]
+        """
+        segments: List[Union[str, str]] = []
+        placeholder_order: List[str] = []
+        last = 0
+        for m in matches:
+            # fmt: off
+            segments.append(smarts[last: m.start()])
+            # fmt: on
+            amap = m.group(2)
+            segments.append(amap)
+            placeholder_order.append(amap)
+            last = m.end()
+        segments.append(smarts[last:])
+        return segments, placeholder_order
+
+    @classmethod
+    def expand_iter(cls, smarts: str) -> Iterator[str]:
+        """Yield expanded SMARTS strings lazily.
+
+        :param smarts: SMARTS string with placeholders.
+        :type smarts: str
+        :yield: One expanded SMARTS string at a time.
+        :rtype: Iterator[str]
+
+        :raises ValueError: If no valid expansions due to incompatible lists.
+        """
+        matches = list(cls._PAT.finditer(smarts))
+        if not matches:
+            yield smarts
+            return
+
+        amap2els = cls._extract_map_to_elements(matches)
+        segments, order = cls._build_template(smarts, matches)
+        unique_maps = list(dict.fromkeys(order))
+
+        pools = [amap2els[am] for am in unique_maps]
+        for combo in itertools.product(*pools):
+            mapping = dict(zip(unique_maps, combo))
+            out = []
+            for seg in segments:
+                if seg in mapping:
+                    out.append(f"[{mapping[seg]}{seg}]")
+                else:
+                    out.append(seg)
+            yield "".join(out)
+
+    @classmethod
+    def expand(cls, smarts: str) -> List[str]:
+        """Return a list of all expanded SMARTS.
+
+        :param smarts: SMARTS string with placeholders.
+        :type smarts: str
+        :return: List of expanded SMARTS strings.
+        :rtype: List[str]
+
+        :raises ValueError: If no valid expansions exist.
+        """
+        return list(cls.expand_iter(smarts))
+
+
+# # --- Example usage ---
+
+# if __name__ == "__main__":
+#     rxn = (
+#         '[H+:6].[C:7](-[O:8](-[H:12]))(-[C,N,O,P,S:9])(-[C,N,O,P,S:10])(-[H:11]).'
+#         '[C:2](-[S:4](-[C,N,O,P,S:5]))(-[C,N,O,P,S:1])(=[O:3])>>'
+#         '[S:4](-[H:6])(-[C,N,O,P,S:5]).[H+:12].'
+#         '[C:7](-[O:8](-[C:2](-[C,N,O,P,S:1])(=[O:3])))(-[C,N,O,P,S:9])(-[C,N,O,P,S:10])(-[H:11])'
+#     )
+#     n = 0
+#     for i, s in enumerate(SMARTSExpander.expand_iter(rxn)):
+#         if i < 3 or i > 621:
+#             print(f"{i+1}: {s}")
+#         n += 1
+#     print(f"Total: {n} enumerated SMARTS.")

synkit/IO/combinatorial/smarts_generalizer.py

@@ -0,0 +1,133 @@
+import re
+from typing import List, Set
+from rdkit import Chem
+from rdkit.Chem import rdChemReactions
+
+
+class SMARTSGeneralizer:
+    """Generalizes a list of atom-mapped (reaction) SMARTS into one combinatorial SMARTS
+    with element-list placeholders at mapped atom positions.
+    Optionally validates output using RDKit.
+
+    :param sanity_check: If True, validate the output SMARTS with RDKit.
+    :type sanity_check: bool
+
+    .. rubric:: Example
+
+    >>> input_smarts = [
+    ...     '[C:1]-[N:2]>>[N:1]-[C:2]',
+    ...     '[N:1]-[N:2]>>[N:1]-[N:2]',
+    ...     '[O:1]-[N:2]>>[N:1]-[N:2]'
+    ... ]
+    >>> gen = SMARTSGeneralizer()
+    >>> print(gen.generalize(input_smarts))
+    [C,N,O:1]-[N:2]>>[N:1]-[C,N,O:2]
+    """
+
+    _atom_pat = re.compile(r"\[([A-Z][a-z]?):(\d+)\]")
+
+    def __init__(self, sanity_check: bool = True):
+        """
+        Initialize SMARTSGeneralizer.
+
+        :param sanity_check: If True, validate the output SMARTS with RDKit.
+        :type sanity_check: bool
+        """
+        self.sanity_check = sanity_check
+
+    def generalize(self, smarts_list: List[str]) -> str:
+        """
+        Generalize a list of SMARTS/reaction SMARTS into one combinatorial SMARTS,
+        with element-list placeholders per atom-map index and position.
+
+        :param smarts_list: List of atom-mapped SMARTS strings (same topology/order).
+        :type smarts_list: list[str]
+        :return: Generalized SMARTS with atom-list placeholders.
+        :rtype: str
+        :raises ValueError: If input list is empty, topology is inconsistent, or output is invalid.
+        """
+        if not smarts_list:
+            raise ValueError("Input list is empty.")
+
+        if len(smarts_list) == 1:
+            combined = smarts_list[0]
+        else:
+            pos_list: List[List[re.Match]] = [
+                list(self._atom_pat.finditer(s)) for s in smarts_list
+            ]
+            n_atoms = len(pos_list[0])
+            for pl in pos_list:
+                if len(pl) != n_atoms:
+                    raise ValueError(
+                        "All input SMARTS must have same atom-mapped topology and order."
+                    )
+
+            pos2map: List[str] = []
+            pos2elems: List[Set[str]] = []
+            for i in range(n_atoms):
+                mapnum = pos_list[0][i].group(2)
+                elems = set(match[i].group(1) for match in pos_list)
+                pos2map.append(mapnum)
+                pos2elems.append(elems)
+
+            # Template assembly: alternate static and atom-map segments
+            first = smarts_list[0]
+            atoms = list(self._atom_pat.finditer(first))
+            segments = []
+            last = 0
+            for m in atoms:
+                # fmt: off
+                segments.append(first[last: m.start()])
+                # fmt: on
+                segments.append(m.group(2))  # mapnum as marker
+                last = m.end()
+            segments.append(first[last:])
+
+            # Reconstruct combinatorial SMARTS
+            out = []
+            idx = 0
+            for seg in segments:
+                if idx < len(pos2map) and seg == pos2map[idx]:
+                    els = sorted(pos2elems[idx])
+                    out.append(f"[{','.join(els)}:{seg}]")
+                    idx += 1
+                else:
+                    out.append(seg)
+            combined = "".join(out)
+
+        # RDKit validation
+        if self.sanity_check:
+            if ">>" in combined:
+                rxn = rdChemReactions.ReactionFromSmarts(combined)
+                if rxn is None or rxn.GetNumProductTemplates() == 0:
+                    raise ValueError(f"Invalid reaction SMARTS generated: {combined}")
+            else:
+                mol = Chem.MolFromSmarts(combined)
+                if mol is None:
+                    raise ValueError(f"Invalid molecule SMARTS generated: {combined}")
+
+        return combined
+
+    def describe(self) -> None:
+        """
+        Print usage instructions and an example.
+
+        :return: None
+        """
+        print(
+            "SMARTSGeneralizer: Generalize a list of atom-mapped (reaction) SMARTS into a single "
+            "SMARTS with element-list placeholders at each mapped atom position.\n"
+            "Usage example:\n"
+            "  >>> gen = SMARTSGeneralizer(sanity_check=True)\n"
+            "  >>> smarts_list = ['[C:1]-[N:2]', '[O:1]-[N:2]', '[N:1]-[N:2]']\n"
+            "  >>> print(gen.generalize(smarts_list))  # [C,N,O:1]-[N:2]"
+        )
+
+    def __repr__(self) -> str:
+        """
+        String representation.
+
+        :return: Description with current sanity_check setting.
+        :rtype: str
+        """
+        return f"SMARTSGeneralizer(sanity_check={self.sanity_check})"

synkit/IO/combinatorial/smarts_to_graph.py

@@ -0,0 +1,179 @@
+import re
+import networkx as nx
+from typing import Optional, Set, Tuple, List, Dict
+
+from rdkit import Chem
+
+
+class SMARTSToGraph:
+    """Convert SMARTS or reaction SMARTS strings into NetworkX graphs with full atom and constraint data.
+
+    :param placeholder_labels: Optional set of labels to treat as placeholders (e.g., wildcard atoms).
+    :type placeholder_labels: Optional[Set[str]]
+    """
+
+    def __init__(self, placeholder_labels: Optional[Set[str]] = None) -> None:
+        """Initialize a SMARTSToGraph converter.
+
+        :param placeholder_labels: Set of placeholder labels used in SMARTS to identify wildcard positions.
+                                   Defaults to {'_R', 'X', 'Y', 'Z'} if None.
+        :type placeholder_labels: Optional[Set[str]]
+        :return: None
+        :rtype: None
+        """
+        self.placeholder_labels: Set[str] = placeholder_labels or {"_R", "X", "Y", "Z"}
+
+    @staticmethod
+    def _safe_total_hs(atom: "Chem.Atom") -> int:
+        """Compute the total number of hydrogens (explicit + implicit) for an RDKit Atom safely.
+
+        :param atom: RDKit Atom instance whose hydrogen count is desired.
+        :type atom: Chem.Atom
+        :return: Total hydrogen count for the atom.
+        :rtype: int
+        :raises Exception: If RDKit property cache update fails.
+
+        .. rubric:: Examples
+
+        >>> from rdkit import Chem
+        >>> atom = Chem.MolFromSmiles('C').GetAtomWithIdx(0)
+        >>> SMARTSToGraph._safe_total_hs(atom)
+        3
+        """
+        try:
+            atom.UpdatePropertyCache(strict=False)
+            return int(atom.GetTotalNumHs(includeExplicit=True))
+        except Exception:
+            return 0
+
+    def smarts_to_graph(self, smarts: str) -> nx.Graph:
+        """Parse a SMARTS string into a NetworkX graph representation, extracting wildcard constraints.
+
+        :param smarts: SMARTS pattern to convert (e.g., '[C:1]C[O:2]').
+        :type smarts: str
+        :return: NetworkX Graph with:
+                  - node attributes: element (str), charge (int), hcount (int),
+                    label (str), constraint (Optional[List[str]]), atom_map (int)
+                  - edge attributes: order (float), standard_order (float)
+        :rtype: nx.Graph
+        :raises ImportError: If RDKit is not available.
+        :raises ValueError: If the SMARTS string is invalid or atoms lack mapping numbers.
+
+        .. rubric:: Examples
+
+        >>> stg = SMARTSToGraph()
+        >>> graph = stg.smarts_to_graph('[CH3:1]-[OH:2]')
+        >>> graph.nodes[1]['element']
+        'C'
+        >>> graph.nodes[2]['element']
+        'O'
+        """
+        if Chem is None:
+            raise ImportError("RDKit is required for SMARTS parsing.")
+
+        # Pre-scan SMARTS for wildcard constraint lists (e.g., [C,N:5])
+        constraint_map: Dict[int, List[str]] = {}
+        for match in re.finditer(r"\[([^:\]]+?):(\d+)\]", smarts):
+            atom_expr, atom_idx = match.groups()
+            idx = int(atom_idx)
+            if "," in atom_expr:
+                constraint_map[idx] = [s.strip() for s in atom_expr.split(",")]
+
+        mol = Chem.MolFromSmarts(smarts)
+        if mol is None:
+            raise ValueError(f"Invalid SMARTS string: {smarts!r}")
+
+        G = nx.Graph()
+        idx_to_map: Dict[int, int] = {}
+
+        # Add nodes with full atom data
+        for atom in mol.GetAtoms():
+            amap = atom.GetAtomMapNum()
+            if amap == 0:
+                raise ValueError(
+                    "All atoms in SMARTS must have a mapping number (atom map)."
+                )
+            idx_to_map[atom.GetIdx()] = amap
+
+            # Determine element, label, and constraints
+            raw_label = atom.GetSymbol()
+            if amap in constraint_map:
+                constraint = constraint_map[amap]
+                label = next(iter(self.placeholder_labels))
+                element = "*"
+            else:
+                constraint = None
+                label = raw_label
+                element = "*" if raw_label in self.placeholder_labels else raw_label
+
+            charge = atom.GetFormalCharge()
+            hcount = self._safe_total_hs(atom)
+
+            G.add_node(
+                amap,
+                element=element,
+                charge=charge,
+                hcount=hcount,
+                label=label,
+                constraint=constraint,
+                atom_map=amap,
+            )
+
+        # Add edges with bond order data
+        for bond in mol.GetBonds():
+            u = idx_to_map[bond.GetBeginAtomIdx()]
+            v = idx_to_map[bond.GetEndAtomIdx()]
+            order = bond.GetBondTypeAsDouble()
+            G.add_edge(u, v, order=order, standard_order=order)
+
+        return G
+
+    def rxn_smarts_to_graphs(self, rxn: str) -> Tuple[nx.Graph, nx.Graph]:
+        """Split a reaction SMARTS into separate reactant and product graphs.
+
+        :param rxn: Reaction SMARTS in the format 'reactants>>products'.
+        :type rxn: str
+        :return: Tuple of (reactant_graph, product_graph).
+        :rtype: Tuple[nx.Graph, nx.Graph]
+        :raises ValueError: If the reaction SMARTS string does not contain '>>'.
+
+        .. rubric:: Examples
+
+        >>> stg = SMARTSToGraph()
+        >>> react, prod = stg.rxn_smarts_to_graphs('[CH3:1]-[OH:2]>>[CH2:1]=[O:2]')
+        >>> react.nodes
+        [1, 2]
+        >>> prod.nodes
+        [1, 2]
+        """
+        if ">>" not in rxn:
+            raise ValueError("Reaction SMARTS must contain '>>' separator.")
+        lhs, rhs = rxn.split(">>", 1)
+        return self.smarts_to_graph(lhs), self.smarts_to_graph(rhs)
+
+    def __repr__(self) -> str:
+        """Return an unambiguous string representation of this converter.
+
+        :return: Representation of the instance showing placeholder labels.
+        :rtype: str
+        """
+        return f"<SMARTSToGraph placeholders={self.placeholder_labels}>"
+
+    def describe(self) -> str:
+        """Provide a usage summary for SMARTSToGraph.
+
+        :return: Multi-line string explaining available methods and usage.
+        :rtype: str
+
+        .. rubric:: Examples
+
+        >>> print(SMARTSToGraph().describe())
+        SMARTSToGraph(placeholder_labels=None)
+         smarts_to_graph(smarts_str) -> Graph
+         rxn_smarts_to_graphs(rxn_smarts) -> (Graph_react, Graph_prod)
+        """
+        return (
+            "SMARTSToGraph(placeholder_labels=None)\n"
+            " smarts_to_graph(smarts_str) -> Graph\n"
+            " rxn_smarts_to_graphs(rxn_smarts) -> (Graph_react, Graph_prod)\n"
+        )

synkit/IO/conversion.py

@@ -0,0 +1,42 @@
+"""High-level conversion entry points.
+
+This module provides I/O-facing access to conversions whose implementation
+belongs to a domain-specific SynKit package.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+def ef_smirks_to_epd(
+    ef_smirks: str,
+    orbital_class: Optional[str] = None,
+    strict_bond_lookup: bool = True,
+) -> dict[str, Any]:
+    """Complete AAM and convert EF-SMIRKS text into generic and typed EPD.
+
+    See :func:`synkit.Graph.Mech.conversion.ef_smirks_to_epd` for the
+    EF-SMIRKS input format and returned fields.
+    """
+    from synkit.Graph.Mech.conversion import ef_smirks_to_epd as _convert
+
+    return _convert(
+        ef_smirks,
+        orbital_class=orbital_class,
+        strict_bond_lookup=strict_bond_lookup,
+    )
+
+
+def epd_to_ef_smirks(complete_aam: str, epd: list[list[Any]]) -> str:
+    """Convert complete atom-mapped RSMI and EPD records into EF-SMIRKS.
+
+    See :func:`synkit.Graph.Mech.conversion.epd_to_ef_smirks` for accepted
+    generic and typed EPD records.
+    """
+    from synkit.Graph.Mech.conversion import epd_to_ef_smirks as _convert
+
+    return _convert(complete_aam, epd)
+
+
+__all__ = ["ef_smirks_to_epd", "epd_to_ef_smirks"]