synkit 0.0.9__tar.gz → 0.0.10__tar.gz

{synkit-0.0.9 → synkit-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synkit
-Version: 0.0.9
+Version: 0.0.10
 Summary: Utility for reaction modeling using graph grammar
 Project-URL: homepage, https://github.com/TieuLongPhan/SynKit
 Project-URL: source, https://github.com/TieuLongPhan/SynKit

synkit-0.0.10/Test/Chem/Reaction/test_radical_wildcard.py

@@ -0,0 +1,51 @@
+import unittest
+from synkit.Chem.Reaction.radical_wildcard import RadicalWildcardAdder
+
+
+class TestRadicalWildcardAdder(unittest.TestCase):
+    """
+    Unit tests for RadicalWildcardAdder using unittest.
+    """
+
+    def test_transform_given_rxn(self):
+        """
+        Ensure that transform() applies the wildcard_map correctly and preserves explicit H.
+        """
+        rxn_in = (
+            "[CH3:1][CH2:2][C:3](=[O:4])[OH:5]."
+            "[O:6][H:7]>>"
+            "[CH3:1][CH2:2][C:3](=[O:4])[O:6]."
+            "[OH:5][H:7]"
+        )
+        adder = RadicalWildcardAdder()
+        result = adder.transform(rxn_in)
+
+        expected = (
+            "[CH3:1][CH2:2][C:3](=[O:4])[OH:5]."
+            "[O:6]([H:7])[*:8]>>"
+            "[CH3:1][CH2:2][C:3](=[O:4])[O:6][*:8]."
+            "[OH:5][H:7]"
+        )
+        self.assertEqual(result, expected)
+
+    def test_auto_map_selection_and_repr_str(self):
+        """
+        Check that wildcard_map is auto-selected and repr/str methods report correctly.
+        """
+        rxn = (
+            "[CH3:1][CH2:2][C:3](=[O:4])[OH:5]."
+            "[O:6][H:7]>>"
+            "[CH3:1][CH2:2][C:3](=[O:4])[O:6]."
+            "[OH:5][H:7]"
+        )
+        adder = RadicalWildcardAdder()
+        out = adder.transform(rxn)
+
+        # The output should contain exactly one [*:8] in reactants and one in products
+        reactants, products = out.split(">>")
+        self.assertEqual(reactants.count("[*:8]"), 1)
+        self.assertEqual(products.count("[*:8]"), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

{synkit-0.0.9 → synkit-0.0.10}/Test/Graph/ITS/test_its_expand.py

@@ -12,7 +12,15 @@ class TestPartialExpand(unittest.TestCase):
             "[CH3:1][CH2:2][CH2:3][Cl:4].[NH2:5][H:6]"
             + ">>[CH3:1][CH2:2][CH2:3][NH2:5].[Cl:4][H:6]"
         )
-        print(output_rsmi)
+        self.assertTrue(AAMValidator.smiles_check(output_rsmi, expected_rsmi, "ITS"))
+
+    def test_expand_with_relabel(self):
+        input_rsmi = "CC[CH2:3][Cl:1].[NH2:2][H:4]>>CC[CH2:3][NH2:2].[Cl:1][H:4]"
+        output_rsmi = ITSExpand.expand_aam_with_its(input_rsmi, relabel=True)
+        expected_rsmi = (
+            "[CH3:1][CH2:2][CH2:3][Cl:4].[NH2:5][H:6]"
+            + ">>[CH3:1][CH2:2][CH2:3][NH2:5].[Cl:4][H:6]"
+        )
         self.assertTrue(AAMValidator.smiles_check(output_rsmi, expected_rsmi, "ITS"))
 
 

synkit-0.0.10/Test/Graph/ITS/test_its_relabel.py

@@ -0,0 +1,61 @@
+import unittest
+from rdkit import Chem
+from synkit.Graph.ITS.its_relabel import ITSRelabel
+from synkit.Graph.syn_graph import SynGraph
+from synkit.IO.chem_converter import smiles_to_graph
+
+
+class TestITSRelabel(unittest.TestCase):
+    def setUp(self):
+        self.its = ITSRelabel()
+
+    def test_get_nodes_with_atom_map(self):
+        # Build a graph from SMILES with explicit atom mapping
+        raw = smiles_to_graph(
+            "[CH3:1][CH2:2][OH:3]", use_index_as_atom_map=True, drop_non_aam=False
+        )
+        sg = SynGraph(raw)
+        nodes = ITSRelabel._get_nodes_with_atom_map(sg)
+        # Every atom should have a non-zero atom_map
+        self.assertCountEqual(nodes, list(sg.raw.nodes()))
+
+    def test_remove_internal_edges(self):
+        # Linear 3‑carbon chain; after removing internal edges none remain
+        raw = smiles_to_graph("CCC", use_index_as_atom_map=True, drop_non_aam=False)
+        sg = SynGraph(raw)
+        all_nodes = list(sg.raw.nodes())
+        pruned = ITSRelabel._remove_internal_edges(sg, all_nodes)
+        self.assertEqual(pruned.raw.number_of_edges(), 0)
+
+    def test_dict_to_tuple_list_sorting(self):
+        mapping = {3: 1, 2: 2, 1: 3}
+        # Sort by key
+        by_key = ITSRelabel._dict_to_tuple_list(mapping, sort_by_key=True)
+        self.assertEqual(by_key, [(1, 3), (2, 2), (3, 1)])
+        # Sort by value
+        by_val = ITSRelabel._dict_to_tuple_list(mapping, sort_by_value=True)
+        self.assertEqual(by_val, [(3, 1), (2, 2), (1, 3)])
+        # No sorting
+        no_sort = ITSRelabel._dict_to_tuple_list(mapping)
+        self.assertCountEqual(no_sort, [(1, 3), (2, 2), (3, 1)])
+
+    def test_fit_simple_reaction(self):
+        # CCO to CC=O, mapping preserved
+        input_rsmi = "CC[CH2:3][Cl:1].[N:2]>>CC[CH2:3][N:2].[Cl:1]"
+        out = self.its.fit(input_rsmi)
+        react, prod = out.split(">>")
+        self.assertIsNotNone(Chem.MolFromSmiles(react))
+        self.assertIsNotNone(Chem.MolFromSmiles(prod))
+
+    def test_fit_invalid_format_raises(self):
+        with self.assertRaises(ValueError):
+            self.its.fit("invalid_format")
+
+    def test_fit_non_isomorphic_raises(self):
+        # Wrong reaction format
+        with self.assertRaises(ValueError):
+            self.its.fit("C:1>CC:1")
+
+
+if __name__ == "__main__":
+    unittest.main()

synkit-0.0.10/Test/Rule/Apply/test_rule_matcher.py

@@ -0,0 +1,94 @@
+import io
+import unittest
+from contextlib import redirect_stdout
+
+import networkx as nx
+
+from synkit.IO.chem_converter import rsmi_to_its
+from synkit.Rule.Apply.rule_matcher import RuleMatcher
+from synkit.Chem.Reaction.standardize import Standardize
+from synkit.Chem.Reaction.aam_validator import AAMValidator
+from synkit.Chem.Reaction.balance_check import BalanceReactionCheck
+
+
+class TestRuleMatcher(unittest.TestCase):
+
+    def test_rule_match_balance(self):
+        """Balanced reaction should match directly and produce correct SMARTS."""
+        input_rsmi = "CC[CH2:3][Cl:1].[NH2:2][H:4]>>CC[CH2:3][NH2:2].[Cl:1][H:4]"
+        rule = rsmi_to_its(input_rsmi, core=True)
+        rsmi_std = Standardize().fit(input_rsmi)
+        expected_rsmi = (
+            "[CH3:1][CH2:2][CH2:3][Cl:4].[NH2:5][H:6]"
+            ">>[CH3:1][CH2:2][CH2:3][NH2:5].[Cl:4][H:6]"
+        )
+
+        matcher = RuleMatcher(rsmi_std, rule)
+        smarts, returned_rule = matcher.get_result()
+
+        # The returned SMARTS should regenerate the expected RSMI via AAMValidator
+        self.assertTrue(AAMValidator.smiles_check(smarts, expected_rsmi, "ITS"))
+        # The returned rule graph should be isomorphic to the input rule
+        self.assertTrue(nx.is_isomorphic(returned_rule, rule))
+
+    def test_rbl_missing_product(self):
+        """Partial (RBL) match when product fragments are missing in rule."""
+        rsmi = "CC(Br)C.CB(O)O>>CC(C)C"
+        template = "[CH3:1][Br:2].[BH2:3][CH3:4]>>[CH3:1][CH3:4].[BH2:3][Br:2]"
+        matcher = RuleMatcher(rsmi, template)
+        smarts, _ = matcher.get_result()
+        expect = "CB(O)O.CC(C)Br>>CC(C)C.OB(O)Br"
+        self.assertEqual(Standardize().fit(smarts), expect)
+
+    def test_rbl_missing_reactant(self):
+        """Partial (RBL) match when reactant fragments are missing in rule."""
+        rsmi = "CCC(=O)(O)>>CCC(=O)OC.O"
+        template = (
+            "[CH3:1][C:2](=[O:3])[OH:4].[CH3:5][O:6][H:7]"
+            ">>[CH3:1][C:2](=[O:3])[O:6][CH3:5].[H:7][OH:4]"
+        )
+        matcher = RuleMatcher(rsmi, template)
+        smarts, _ = matcher.get_result()
+        expect = "CCC(=O)O.CO>>CCC(=O)OC.O"
+        self.assertEqual(Standardize().fit(smarts), expect)
+
+    def test_no_match_raises(self):
+        """If no SMARTS reproduces the RSMI under the rule, a ValueError is raised."""
+        rsmi = "CCO>>CC=O"
+        # Use a completely unrelated template
+        bad_template = "[CH3:1][OH:2]>>[CH2:1]=O"
+        with self.assertRaises(ValueError):
+            RuleMatcher(rsmi, bad_template)
+
+    def test_str_and_repr(self):
+        """__str__ and __repr__ reflect the RSMI, balance status, and rule size."""
+        input_rsmi = "CC[CH2:3][Cl:1].[NH2:2][H:4]>>CC[CH2:3][NH2:2].[Cl:1][H:4]"
+        template = rsmi_to_its(input_rsmi, core=True)
+        rsmi = Standardize().fit(input_rsmi)
+        matcher = RuleMatcher(rsmi, template)
+        # str should mention balanced/unbalanced correctly
+        if BalanceReactionCheck(n_jobs=1).rsmi_balance_check(matcher.rsmi):
+            self.assertIn("(balanced)", str(matcher))
+        else:
+            self.assertIn("(unbalanced)", str(matcher))
+        # repr should include node/edge counts of the rule
+        rep = repr(matcher)
+        self.assertIn("RuleMatcher(rsmi=", rep)
+        self.assertIn("balanced=", rep)
+
+    def test_help_output(self):
+        """help() should print internal state and list candidate SMARTS patterns."""
+        input_rsmi = "CC[CH2:3][Cl:1].[NH2:2][H:4]>>CC[CH2:3][NH2:2].[Cl:1][H:4]"
+        template = rsmi_to_its(input_rsmi, core=True)
+        rsmi = Standardize().fit(input_rsmi)
+        matcher = RuleMatcher(rsmi, template)
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            matcher.help()
+        out = buf.getvalue()
+        self.assertIn("RuleMatcher for RSMI", out)
+        self.assertIn("Candidate SMARTS patterns:", out)
+
+
+if __name__ == "__main__":
+    unittest.main()

synkit-0.0.10/Test/Synthesis/Reactor/test_partial_engine.py

@@ -0,0 +1,48 @@
+import unittest
+from synkit.Synthesis.Reactor.partial_engine import PartialEngine
+
+
+class TestPartialEngine(unittest.TestCase):
+    def test_forward_direction_example(self):
+        """
+        Example 1:
+        PartialEngine(smi='CCC(=O)OC',
+                      template='[C:1][O:2].[O:3][H:4]>>[C:1][O:3].[O:2][H:4]')
+        .fit(invert=False)
+        should return the two forward wildcarded SMARTS.
+        """
+        smi = "CCC(=O)OC"
+        template = "[C:1][O:2].[O:3][H:4]>>[C:1][O:3].[O:2][H:4]"
+        engine = PartialEngine(smi, template)
+        result = engine.fit(invert=False)
+        expected = [
+            "[CH3:1][CH2:2][C:3](=[O:4])[O:5][CH3:6].[OH:7][*:8]>>"
+            "[CH3:1][CH2:2][C:3](=[O:4])[O:7][*:8].[OH:5][CH3:6]",
+            "[CH3:1][CH2:2][C:3](=[O:4])[O:5][CH3:6].[OH:7][*:8]>>"
+            "[CH3:1][CH2:2][C:3](=[O:4])[OH:5].[CH3:6][O:7][*:8]",
+        ]
+        self.assertEqual(result, expected)
+
+    def test_backward_direction_example(self):
+        """
+        Example 2:
+        PartialEngine(smi='CCC(=O)OCC',
+                      template='[C:1][O:2].[O:3][H:4]>>[C:1][O:3].[O:2][H:4]')
+        .fit(invert=True)
+        should return the two backward wildcarded SMARTS.
+        """
+        smi = "CCC(=O)OCC"
+        template = "[C:1][O:2].[O:3][H:4]>>[C:1][O:3].[O:2][H:4]"
+        engine = PartialEngine(smi, template)
+        result = engine.fit(invert=True)
+        expected = [
+            "[CH3:1][CH2:2][C:3](=[O:4])[O:8][*:9].[OH:5][CH2:6][CH3:7]>>"
+            "[CH3:1][CH2:2][C:3](=[O:4])[O:5][CH2:6][CH3:7].[OH:8][*:9]",
+            "[CH2:6]([CH3:7])[O:8][*:9].[CH3:1][CH2:2][C:3](=[O:4])[OH:5]>>"
+            "[CH3:1][CH2:2][C:3](=[O:4])[O:5][CH2:6][CH3:7].[OH:8][*:9]",
+        ]
+        self.assertEqual(result, expected)
+
+
+if __name__ == "__main__":
+    unittest.main()

synkit-0.0.10/Test/Synthesis/Reactor/test_rbl_reactor.py

@@ -0,0 +1,52 @@
+import unittest
+from synkit.IO import its_to_rsmi, rsmi_to_its
+from synkit.Synthesis.Reactor.rbl_engine import RBLEngine
+
+
+class TestRBLEngine(unittest.TestCase):
+    def test_example1(self):
+        # Example 1
+        rsmi = "CCC(=O)(O)>>CCC(=O)OC"
+        raw_template = (
+            "[CH3:1][C:2](=[O:3])[OH:4]."
+            "[CH3:5][O:6][H:7]>>"
+            "[CH3:1][C:2](=[O:3])[O:6][CH3:5]."
+            "[H:7][OH:4]"
+        )
+        its = rsmi_to_its(raw_template, core=True)
+        template = its_to_rsmi(its)
+
+        engine = RBLEngine(rsmi, template)
+        result = engine.fit()
+
+        expected = [
+            (
+                "[CH3:1][CH2:2][C:3](=[O:4])[OH:7]."
+                "[OH:5][CH3:6]>>"
+                "[CH3:1][CH2:2][C:3](=[O:4])[O:5][CH3:6]."
+                "[OH2:7]"
+            )
+        ]
+        self.assertEqual(result, expected)
+
+    def test_example2(self):
+        # Example 2
+        rsmi = "CCC(=O)OC>>CCC(=O)OCC"
+        template = "[C:1][O:2].[O:3][H:4]>>[C:1][O:3].[O:2][H:4]"
+
+        engine = RBLEngine(rsmi, template)
+        result = engine.fit()
+
+        expected = [
+            (
+                "[CH3:1][CH2:2][C:3](=[O:4])[O:8][CH3:9]."
+                "[OH:5][CH2:6][CH3:7]>>"
+                "[CH3:1][CH2:2][C:3](=[O:4])[O:5][CH2:6][CH3:7]."
+                "[OH:8][CH3:9]"
+            )
+        ]
+        self.assertEqual(result, expected)
+
+
+if __name__ == "__main__":
+    unittest.main()

{synkit-0.0.9 → synkit-0.0.10}/doc/api.rst

@@ -48,6 +48,7 @@ The `ITS` submodule provides tools for constructing, decomposing, and validating
 
 - **its_construction**: Functions for constructing an ITS graph.
 - **its_decompose**: Functions for decomposing an ITS graph and extracting reaction center.
+- **its_expand**: Functions for expanding partial ITS graphs into full ITS graphs. 
 
 .. automodule:: synkit.Graph.ITS.its_construction
    :members:
@@ -55,6 +56,11 @@ The `ITS` submodule provides tools for constructing, decomposing, and validating
    :show-inheritance:
 
 .. automodule:: synkit.Graph.ITS.its_decompose
+   :members: get_rc, its_decompose
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: synkit.Graph.ITS.its_expand
    :members:
    :undoc-members:
    :show-inheritance:

{synkit-0.0.9 → synkit-0.0.10}/doc/conf.py

@@ -1,13 +1,28 @@
 import os
 import sys
+from importlib.metadata import version as _get_version, PackageNotFoundError
 
+# -- Path setup --------------------------------------------------------------
+# Add project root to sys.path to import the package
 sys.path.insert(0, os.path.abspath(".."))
 
 # -- Project information -----------------------------------------------------
 project = "synkit"
 author = "Tieu-Long Phan"
-release = "0.0.8"
-version = release
+
+
+try:
+    release = _get_version("synkit")
+except PackageNotFoundError:
+    try:
+        import synkit
+
+        release = synkit.__version__
+    except (ImportError, AttributeError):
+        # Fallback default
+        release = "0.0.10"
+# Use only major.minor for short version
+version = ".".join(release.split(".")[:2])
 
 # -- General configuration ---------------------------------------------------
 extensions = [

{synkit-0.0.9 → synkit-0.0.10}/doc/getting_started.rst

@@ -66,7 +66,7 @@ After installation, verify that **synkit** is available and check its version:
 
 .. code-block:: bash
 
-   python -c "import synkit; print(synkit.__version__)"
+   python -c "import importlib.metadata as m; print(m.version('synkit'))"
    # Should print the installed synkit version
 
 Further Resources

{synkit-0.0.9 → synkit-0.0.10}/doc/graph.rst

@@ -254,6 +254,50 @@ This example builds two reaction-center ITS graphs, computes their MCS mapping,
    (C) Composite ITS graph "gluing" both transformations  
    (D) Mechanistic Transition Graph (MTG) showing step-wise mechanism  
 
+Context graph
+-------------
+
+The ``synkit.Graph.Context`` submodule provides tools for expanding reaction center graphs to include nearest neighbors, enabling context‑aware analysis of reaction networks.
+
+.. code-block:: python
+   :caption: Context graph expansion example
+   :linenos:
+
+   from synkit.IO import rsmi_to_its
+   from synkit.Graph.Context.radius_expand import RadiusExpand
+   from synkit.Vis.graph_visualizer import GraphVisualizer
+
+   smart = (
+       '[CH3:1][O:2][C:3](=[O:4])[CH:5]([CH2:6][CH2:7][CH2:8][CH2:9]'
+       '[NH:10][C:11](=[O:12])[O:13][CH2:14][c:15]1[cH:16][cH:17]'
+       '[cH:18][cH:19][cH:20]1)[NH:21][C:22](=[O:23])[NH:24][c:25]1'
+       '[cH:26][c:27]([O:28][CH3:29])[cH:30][c:31]([C:32]([CH3:33])'
+       '([CH3:34])[CH3:35])[c:36]1[OH:37].[OH:38][H:39]>>'
+       '[C:11](=[O:12])([O:13][CH2:14][c:15]1[cH:16][cH:17][cH:18]'
+       '[cH:19][cH:20]1)[OH:38].[CH3:1][O:2][C:3](=[O:4])[CH:5]'
+       '([CH2:6][CH2:7][CH2:8][CH2:9][NH:10][H:39])[NH:21][C:22]'
+       '(=[O:23])[NH:24][c:25]1[cH:26][c:27]([O:28][CH3:29])[cH:30]'
+       '[c:31]([C:32]([CH3:33])([CH3:34])[CH3:35])[c:36]1[OH:37]'
+   )
+   its = rsmi_to_its(smart)
+   rc  = rsmi_to_its(smart, core=True)
+   exp = RadiusExpand()
+   k1  = exp.extract_k(its, n_knn=1)
+
+   gv = GraphVisualizer()
+   gv.visualize_its_grid([rc, k1])
+
+.. container:: figure
+
+   .. image:: ./figures/context.png
+      :alt: Context graph expansion example
+      :align: center
+      :width: 1000px
+
+   *Figure:*  
+   (A) Minimal reaction center subgraph obtained by contracting all atoms that participate directly in bond‑order changes.  
+   Nodes are colour‑coded by element; edges in **red** indicate bonds being broken, while edges in **blue** mark bonds being formed.  
+   (B) First shell ($k=1$) context expansion: every reaction center atom is augmented with all of its immediate neighbours.
 
 
 See Also

{synkit-0.0.9 → synkit-0.0.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "synkit"
-version = "0.0.9"
+version = "0.0.10"
 authors = [
     {name="Tieu Long Phan", email="tieu@bioinf.uni-leipzig.de"}
 ]

synkit-0.0.10/synkit/Chem/Reaction/radical_wildcard.py

@@ -0,0 +1,165 @@
+from rdkit import Chem
+from rdkit.Chem import SanitizeFlags
+import re
+from typing import Tuple, List, Optional, Dict
+
+
+class RadicalWildcardAdder:
+    """
+    A utility for adding wildcard dummy atoms ([*]) to radical centers in reaction SMILES,
+    with unique incremental atom-map indices and correct propagation into products.
+
+    Each reactive radical atom in the reactant block is identified by its unpaired electron count,
+    assigned one or more wildcard map indices, and recorded. The same wildcard(s) are then appended
+    to the corresponding atom(s) in the product block, ensuring consistent mapping.
+
+    :param start_map: If provided, this integer will be the first atom-map index
+                      used for wildcard dummy atoms; subsequent radicals get incremented indices.
+                      If None, the next unused index is auto-determined from the input SMILES.
+    :type start_map: Optional[int]
+
+    Example
+    -------
+    >>> adder = RadicalWildcardAdder(start_map=8)
+    >>> rxn = "[C:2][OH:4].[O:6][H:7]>>[C:2][O:6].[OH:4][H:7]"
+    >>> print(adder.transform(rxn))
+    [C:2]([OH:4])[*:8].[O:6]([H:7])[*:9]>>[C:2]([O:6][*:9])[*:8].[OH:4][H:7]
+    """
+
+    def __init__(self, start_map: Optional[int] = None) -> None:
+        """
+        Initialize the adder with an optional starting map index.
+
+        :param start_map: Starting atom-map index for wildcards or None to auto-pick.
+        :type start_map: Optional[int]
+        """
+        self.start_map = start_map
+
+    def __repr__(self) -> str:
+        """
+        Official representation.
+        """
+        return f"<RadicalWildcardAdder(start_map={self.start_map})>"
+
+    def __str__(self) -> str:
+        """
+        User-friendly description.
+        """
+        m = self.start_map if self.start_map is not None else "auto"
+        return f"RadicalWildcardAdder(start_map={m})"
+
+    def transform(self, rxn_smiles: str) -> str:
+        """
+        Append wildcard dummy atoms to each radical center in the reactant block
+        and propagate the same wildcards to the matching atoms in the product block.
+
+        :param rxn_smiles: Reaction SMILES string, two-component or three-component.
+        :type rxn_smiles: str
+        :returns: Modified reaction SMILES with consistent wildcard attachments.
+        :rtype: str
+        :raises ValueError: If the SMILES is not valid or fragments fail to parse.
+        """
+        # Split into reactants > agents? > products
+        react_blk, agents_blk, prod_blk = self._split_reaction(rxn_smiles)
+
+        # Determine first wildcard map index
+        existing = [int(n) for n in re.findall(r":(\d+)", rxn_smiles)]
+        next_map = (
+            self.start_map
+            if self.start_map is not None
+            else max(existing, default=0) + 1
+        )
+
+        # Record mapping: original atom-map -> list of wildcard_maps
+        wildcard_map_for: Dict[int, List[int]] = {}
+
+        # Build sanitizeOps mask (skip H-adjustment)
+        keep_ops = SanitizeFlags.SANITIZE_ALL & ~SanitizeFlags.SANITIZE_ADJUSTHS
+
+        # Process one block (helper)
+        def _process(frags: List[str], propagate: bool) -> List[str]:
+            nonlocal next_map
+            out = []
+            for smi in frags:
+                if not smi:
+                    continue
+                # Load unsanitized then re-sanitize to preserve explicit H
+                mol = Chem.MolFromSmiles(smi, sanitize=False)
+                if mol is None:
+                    raise ValueError(f"Cannot parse SMILES fragment: {smi}")
+                Chem.SanitizeMol(mol, sanitizeOps=keep_ops)
+                rw = Chem.RWMol(mol)
+
+                atoms = list(rw.GetAtoms())
+                changed = False
+
+                for atom in atoms:
+                    rad = atom.GetNumRadicalElectrons()
+                    orig_map = atom.GetAtomMapNum()
+                    if rad > 0:
+                        # Initialize list for this orig_map
+                        if propagate and orig_map not in wildcard_map_for:
+                            wildcard_map_for[orig_map] = []
+                        # For each unpaired electron, attach a wildcard
+                        for _ in range(rad):
+                            if propagate:
+                                wm = next_map
+                                wildcard_map_for[orig_map].append(wm)
+                                next_map += 1
+                            else:
+                                # in products, use already-recorded wm sequentially
+                                wm_list = wildcard_map_for.get(orig_map, [])
+                                if not wm_list:
+                                    continue
+                                wm = wm_list.pop(0)
+                            # add dummy wildcard
+                            dummy = Chem.Atom(0)
+                            dummy.SetAtomMapNum(wm)
+                            dummy.SetNoImplicit(True)
+                            rw.AddAtom(dummy)
+                            rw.AddBond(
+                                atom.GetIdx(),
+                                rw.GetNumAtoms() - 1,
+                                Chem.BondType.SINGLE,
+                            )
+                            changed = True
+
+                if changed:
+                    Chem.SanitizeMol(rw.GetMol(), sanitizeOps=keep_ops)
+
+                out.append(
+                    Chem.MolToSmiles(
+                        rw.GetMol(), isomericSmiles=True, allHsExplicit=True
+                    )
+                )
+            return out
+
+        react_frags = react_blk.split(".") if react_blk else []
+        new_reacts = _process(react_frags, propagate=True)
+
+        prod_frags = prod_blk.split(".") if prod_blk else []
+        new_prods = _process(prod_frags, propagate=False)
+
+        react_str = ".".join(new_reacts)
+        prod_str = ".".join(new_prods)
+        if agents_blk is None:
+            return f"{react_str}>>{prod_str}"
+        return f"{react_str}>{agents_blk}>{prod_str}"
+
+    @staticmethod
+    def _split_reaction(rxn: str) -> Tuple[str, Optional[str], str]:
+        """
+        Split a reaction SMILES into reactants, agents (optional), and products.
+
+        :param rxn: The reaction SMILES string.
+        :type rxn: str
+        :returns: Tuple of (reactants_block, agents_block or None, products_block).
+        :rtype: Tuple[str, Optional[str], str]
+        :raises ValueError: If the SMILES does not contain 2 or 3 '>' symbols.
+        """
+        parts = rxn.split(">")
+        if len(parts) == 2:
+            return parts[0], None, parts[1]
+        if len(parts) == 3:
+            return parts[0], parts[1], parts[2]
+        raise ValueError("Reaction SMILES must contain 2 or 3 '>' symbols")