Assembly Templates
==================

Assembly templates combine fragment SMILES into full molecules using
self-contained PEP 723 scripts executed by ``uv``.

.. important::

   ``uv`` must be installed and on PATH. Assembly scripts are self-contained
   `PEP 723 <https://peps.python.org/pep-0723/>`_ scripts --- ``uv`` automatically
   installs their dependencies (e.g. rdkit) on first run.

.. code-block:: python

   from lcmd_db import load_dataset

   data = load_dataset("fragflp", include=["fragments"])
   template = data.assembly_templates["default"]

   # Single assembly — returns SMILES, raises on failure
   smiles = template.assemble(
       LAr1="c1c(C)c(C)c(C)c(C)c1(C)",
       LAr2="c1c(C)c(C)c(C)c(C)c1(C)",
       LBr1="*cncc1",
       LBr2="*cncc1",
       BB="*c1c2c()cnc()c2c()",
   )

   # Batch — one subprocess, multiple results
   results = template.assemble_batch([
       {"LAr1": "c1ccccc1", "LAr2": "c1ccccc1",
        "LBr1": "*cncc1",   "LBr2": "*cncc1",
        "BB": "*c1c2c()cnc()c2c()"},
   ])
   for r in results:
       print(r.smiles if r.success else r.error)

   # Save standalone script for HPC/cluster use
   template.save_script("flp_assembler.py")

.. seealso::

   :class:`~lcmd_db.AssemblyTemplate` --- full API reference,
   :class:`~lcmd_db.AssemblyResult` --- batch result type,
   :doc:`fragments` --- loading fragment data,
   :doc:`typed-stubs` --- typed kwargs for assembly functions