Add user onboarding Jupyter notebooks for BuildCompiler

notebooks/01_install_and_setup.ipynb

@@ -0,0 +1,51 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "# BuildCompiler Notebook 1: Install and Setup\n\nThis notebook helps new users install BuildCompiler and verify imports."
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "## 1) Create an environment\nUse one of the following options."
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": "# Option A (recommended): uv\n# !uv sync --all-groups\n\n# Option B: pip\n# !python -m venv .venv\n# !source .venv/bin/activate\n# !python -m pip install -U pip\n# !python -m pip install -e ."
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "## 2) Quick import check"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": "from buildcompiler.api import BuildCompiler, full_build\nfrom buildcompiler.api import BuildOptions\n\nprint('BuildCompiler imports OK')"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "## 3) Inspect key entry points\nThese are the main pipeline stages users should know: `index_collections`, `domestication`, `assembly_lvl1`, `assembly_lvl2`, `transformation`, `plating`, and `full_build`."
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "pygments_lexer": "ipython3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

notebooks/02_planning_only_quickstart.ipynb

@@ -0,0 +1,41 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "# BuildCompiler Notebook 2: Planning-Only Quickstart\n\nUse this when you want to classify abstract designs and inspect what the compiler plans to run."
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": "from buildcompiler.api import BuildCompiler\nfrom buildcompiler.api import BuildOptions\n\ncompiler = BuildCompiler(options=BuildOptions())\n\n# Replace with real abstract_designs from your SBOL document\nabstract_designs = []"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": "plan = compiler.plan(abstract_designs)\nplan"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "## What to look for\n- Classification of designs into stage requests\n- Warnings for unsupported or invalid inputs\n- Combinatorial expansion behavior"
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "pygments_lexer": "ipython3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

notebooks/03_full_build_minimal.ipynb

@@ -0,0 +1,41 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "# BuildCompiler Notebook 3: Minimal `full_build` Flow\n\nThis notebook demonstrates the high-level `full_build` API."
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": "from buildcompiler.api import full_build\n\n# Inject real dependencies in production:\ninventory = None\nsbol_document = None\nabstract_designs = []"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": "# This call requires real inventory + SBOL document or injected executor\n# result = full_build(\n#     abstract_designs=abstract_designs,\n#     inventory=inventory,\n#     sbol_document=sbol_document,\n# )\n\n# result"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "## Notes\n- `full_build` orchestrates planning + execution.\n- For production runs, pass explicit inventory/SBOL dependencies.\n- Keep inputs and outputs explicit for reproducibility."
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "pygments_lexer": "ipython3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

notebooks/04_options_and_safety.ipynb

@@ -0,0 +1,41 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "# BuildCompiler Notebook 4: Options and Safety Controls\n\nThis notebook explains configurable behavior via `BuildOptions`."
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": "from buildcompiler.api import BuildOptions\n\noptions = BuildOptions()\noptions"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": "# Explore option groups\n# options.planning\n# options.execution\n# options.domestication\n# options.selection\n# options.protocol\n# options.reporting\n\nprint(options)"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "## Guidance\n- Start with defaults.\n- Tighten approval/reagent/pull policies for controlled environments.\n- Persist options in your own pipeline config for deterministic runs."
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "pygments_lexer": "ipython3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

notebooks/05_stage_by_stage_guide.ipynb

@@ -0,0 +1,39 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "# BuildCompiler Notebook 5: Stage-by-Stage Guide\n\nThis walkthrough maps expected stage behavior and outputs."
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "## Stage map\n1. `index_collections` \u2014 index inventory records from collections\n2. `domestication` \u2014 prepare unsupported/missing parts\n3. `assembly_lvl1` \u2014 create level-1 plasmids\n4. `assembly_lvl2` \u2014 compose higher-level constructs\n5. `transformation` \u2014 produce transformation activities/records\n6. `plating` \u2014 create plate layouts and protocol artifacts"
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {},
+      "outputs": [],
+      "source": "# Pseudocode workflow sketch\n# compiler = BuildCompiler.from_synbiohub(...)\n# plan = compiler.plan(abstract_designs)\n# result = compiler.execute(plan)\n# summary = getattr(result, 'summary', result)\n# summary"
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": "## Output contract checklist\n- SBOL entities generated where applicable\n- JSON adapter outputs for automation workflows\n- Protocol/manual files written explicitly to disk"
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "pygments_lexer": "ipython3"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

notebooks/notebooks.md

@@ -1 +1,11 @@
-Folder for notebooks.
+# Notebooks
+
+User-facing guides:
+
+- `01_install_and_setup.ipynb`: environment setup and import verification
+- `02_planning_only_quickstart.ipynb`: planning/classification-only usage
+- `03_full_build_minimal.ipynb`: minimal full-build orchestration pattern
+- `04_options_and_safety.ipynb`: configuration and safety-related options
+- `05_stage_by_stage_guide.ipynb`: stage responsibilities and output contract
+
+Legacy/internal notebooks are also present in this folder for experimentation.

pyproject.toml

@@ -8,7 +8,7 @@ version = "0.0.a1"
 description = "BuildCompiler is an open-source tool that bridges the Design and Build stages of the Synthetic Biology DBTL cycle"
 readme = "README.md"
 requires-python = ">=3.10"
-license = {file = "LICENSE.md"}
+license = {file = "LICENSE"}
 keywords = ["SBOL", "genetic", "automation", "build", "synthetic biology"]
 authors = [
   { name="Gonzalo Vidal", email="gonzalo.vidalpena@colorado.edu" },
@@ -26,7 +26,8 @@ classifiers = [
 dependencies = [
     "sbol2",
     "biopython", 
-    "pydna"
+    "pydna",
+    "regex>=2024.11.6,<2025.0.0"
 ]
 
 [project.optional-dependencies]