Use PyPI FreshForge optional dependency

CHANGE_LOG.md

@@ -4,6 +4,9 @@ This file records completed project work in chronological order.
 
 ## 2026-07-02
 
+- Updated the optional FreshForge integration dependency now that FreshForge is published on PyPI:
+  `modelwright[freshforge]`, `dev`, and `test` install `freshforge>=0.1.0a5,<0.2` while the core
+  Modelwright package remains FreshForge-free.
 - Released Modelwright `v0.1.0a8` after PR #240 merged to `main`, post-merge Test workflow
   #28559618570 passed, post-merge Docs Pages workflow #28559618583 passed, annotated tag
   `v0.1.0a8` triggered Release workflow #28559646142, and trusted publishing uploaded

docs/guides/freshforge-provider-integration.rst

@@ -18,19 +18,24 @@ validation scenario, and artifact policy.
 Install
 -------
 
-FreshForge is currently consumed from its GitHub release rather than as a
-Modelwright package dependency. For development, install Modelwright normally
-and then install FreshForge into the same environment:
+FreshForge is optional. The Modelwright core package does not import or require
+FreshForge, but the ``freshforge`` extra installs the PyPI alpha needed for
+provider discovery, planning, and execution:
 
 .. code-block:: bash
 
-   python -m pip install -e .[dev]
-   python -m pip install "freshforge @ git+https://github.com/UBC-FRESH/freshforge.git@v0.1.0a3"
+   python -m pip install "modelwright[freshforge]"
 
-Modelwright registers a ``freshforge.providers`` entry point, but it does not
-add a GitHub direct-reference dependency in ``pyproject.toml``. This keeps
-Modelwright's published package metadata PyPI-safe while FreshForge is still
-early and moving.
+For source-checkout development, install the development extra from the
+repository root:
+
+.. code-block:: bash
+
+   python -m pip install -e ".[dev]"
+
+Modelwright registers a ``freshforge.providers`` entry point while keeping
+normal ``import modelwright`` FreshForge-free. FreshForge remains alpha
+software, so the optional dependency is constrained to the ``0.1`` alpha line.
 
 Provider Discovery
 ------------------

pyproject.toml

@@ -58,6 +58,7 @@ docs = [
 ]
 dev = [
   "build>=1.2",
+  "freshforge>=0.1.0a5,<0.2",
   "formulas",
   "pandas>=2",
   "pytest>=8",
@@ -66,6 +67,9 @@ dev = [
   "sphinx-rtd-theme>=2",
   "twine>=5"
 ]
+freshforge = [
+  "freshforge>=0.1.0a5,<0.2"
+]
 notebook = [
   "pandas>=2"
 ]
@@ -80,6 +84,7 @@ release = [
   "twine>=5"
 ]
 test = [
+  "freshforge>=0.1.0a5,<0.2",
   "formulas",
   "pandas>=2",
   "pytest>=8"

tests/test_freshforge_integration.py

@@ -127,13 +127,15 @@ def test_provider_metadata_serializes_deterministically() -> None:
     }
 
 
-def test_pyproject_declares_freshforge_entry_point_without_direct_dependency() -> None:
+def test_pyproject_declares_freshforge_entry_point_and_optional_dependency() -> None:
     pyproject = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))
 
     entry_points = pyproject["project"]["entry-points"]["freshforge.providers"]
     assert entry_points["modelwright"] == "modelwright.freshforge:provider_factory"
     optional = pyproject["project"]["optional-dependencies"]
-    assert "freshforge" not in optional
+    assert optional["freshforge"] == ["freshforge>=0.1.0a5,<0.2"]
+    assert "freshforge>=0.1.0a5,<0.2" in optional["dev"]
+    assert "freshforge>=0.1.0a5,<0.2" in optional["test"]
     assert "freshforge" not in "\n".join(pyproject["project"]["dependencies"])