add system_site_packages arg to tesseract config

Author: dionhaefner

examples/system_site_packages/tesseract_api.py

@@ -0,0 +1,67 @@
+# Copyright 2025 Pasteur Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Solve the Poisson equation on a unit square using Firedrake.
+
+Firedrake is NOT listed in tesseract_requirements.txt — it's only available
+because system_site_packages is enabled and Firedrake is pre-installed in the
+base image.
+"""
+
+from pydantic import BaseModel, Field
+
+
+class InputSchema(BaseModel):
+    mesh_resolution: int = Field(
+        description="Number of cells along each edge of the unit square mesh.",
+        ge=1,
+    )
+
+
+class OutputSchema(BaseModel):
+    num_dofs: int = Field(description="Number of degrees of freedom in the solution.")
+    l2_error: float = Field(
+        description="L2 norm of the error against the exact solution."
+    )
+
+
+def apply(inputs: InputSchema) -> OutputSchema:
+    """Solve -laplacian(u) = f on the unit square with known exact solution."""
+    from firedrake import (
+        DirichletBC,
+        Function,
+        FunctionSpace,
+        SpatialCoordinate,
+        TestFunction,
+        TrialFunction,
+        UnitSquareMesh,
+        dx,
+        errornorm,
+        grad,
+        inner,
+        pi,
+        sin,
+        solve,
+    )
+
+    mesh = UnitSquareMesh(inputs.mesh_resolution, inputs.mesh_resolution)
+    V = FunctionSpace(mesh, "CG", 1)
+
+    u = TrialFunction(V)
+    v = TestFunction(V)
+
+    x, y = SpatialCoordinate(mesh)
+    exact = sin(pi * x) * sin(pi * y)
+    f = 2 * pi**2 * sin(pi * x) * sin(pi * y)
+
+    a = inner(grad(u), grad(v)) * dx
+    L = f * v * dx
+
+    bc = DirichletBC(V, 0, "on_boundary")
+
+    u_h = Function(V)
+    solve(a == L, u_h, bcs=bc)
+
+    l2_err = errornorm(exact, u_h, norm_type="L2")
+
+    return OutputSchema(num_dofs=V.dof_count, l2_error=l2_err)

examples/system_site_packages/tesseract_config.yaml

@@ -0,0 +1,9 @@
+name: "system_site_packages"
+version: "0.1.0"
+description: |
+  Tesseract that uses system_site_packages to access Firedrake,
+  a finite element library pre-installed in the base image.
+
+build_config:
+  base_image: "firedrakeproject/firedrake:2026.4.0"
+  system_site_packages: true

examples/system_site_packages/tesseract_requirements.txt

@@ -0,0 +1,2 @@
+# No extra requirements — Firedrake is provided by the base image
+# via system_site_packages: true in tesseract_config.yaml.

examples/system_site_packages/test_cases/test_apply.json

@@ -0,0 +1,16 @@
+{
+  "endpoint": "apply",
+  "expected_outputs": {
+    "num_dofs": 25,
+    "l2_error": 0.07907545425172705
+  },
+  "expected_exception": null,
+  "expected_exception_regex": null,
+  "atol": 1e-4,
+  "rtol": 1e-4,
+  "payload": {
+    "inputs": {
+      "mesh_resolution": 4
+    }
+  }
+}

tesseract_core/sdk/api_parse.py

@@ -133,6 +133,15 @@ class TesseractBuildConfig(BaseModel, validate_assignment=True):
         ),
     )
 
+    system_site_packages: bool = Field(
+        False,
+        description=(
+            "If True, create the Python virtual environment with --system-site-packages. "
+            "This allows the venv to access packages pre-installed in the base image "
+            "(e.g., Firedrake, FEniCS, OpenFOAM)."
+        ),
+    )
+
     requirements: PythonRequirements = PipRequirements(provider="python-pip")
 
     model_config = ConfigDict(extra="forbid")

tesseract_core/sdk/templates/Dockerfile.base

@@ -46,6 +46,10 @@ COPY {{ tesseract_source_directory }}/{{ config.build_config.requirements._filen
 COPY {{ config.build_config.requirements._build_script }} ./
 COPY local_requirements/ ./local_requirements
 
+{% if config.build_config.system_site_packages %}
+ENV TESSERACT_SYSTEM_SITE_PACKAGES=1
+{% endif %}
+
 # Build a python venv from python provider build scripts.
 # The build script has to create a venv at /python-env
 RUN --mount=type=cache,target=/root/.cache/uv {% if use_ssh_mount %}--mount=type=ssh{% endif %} bash {{ config.build_config.requirements._build_script }}

tesseract_core/sdk/templates/build_pip_venv.sh

@@ -5,7 +5,12 @@
 
 set -e  # Exit immediately if a command exits with a non-zero status
 
-uv venv /python-env
+SYSTEM_SITE_PACKAGES_FLAG=""
+if [ "${TESSERACT_SYSTEM_SITE_PACKAGES:-0}" = "1" ]; then
+    SYSTEM_SITE_PACKAGES_FLAG="--system-site-packages"
+fi
+
+uv venv $SYSTEM_SITE_PACKAGES_FLAG /python-env
 source /python-env/bin/activate
 
 # Collect dependencies

tests/endtoend_tests/test_examples.py

@@ -108,6 +108,7 @@ class Config:
     ),
     "metrics": Config(test_with_random_inputs=True),
     "qp_solve": Config(),
+    "system_site_packages": Config(),
     "tesseractreference": Config(),  # Can't test requests standalone; needs target Tesseract. Covered in separate test.
     "userhandling": Config(),
 }