feat: Add pydantic type making other Tesseracts callable (needed for HOTs) (#343)

#### Relevant issue or PR
Extracted from: pasteurlabs/AutoPhysics#31
Needed for HOTs in optimization etc.

#### Description of changes
Joint work with @zmheiko.

Enables passing references to target Tesseracts as input, which we may
then call. Example:

```
class InputSchema(BaseModel):
    target: TesseractReference = Field(description="Tesseract to call.")

def apply(inputs: InputSchema) -> OutputSchema:
    result = inputs.target.apply({"name": "Alice"})["greeting"]
    ...
```

Corresponding payload for an apply call:

```
{"inputs": {"target": {"type": "url", "url": "http://helloworld:8000"}}}
```

Instead of a URL, we may pass a `tesseract_api.py` path to a
`tesseract_api.py` file. The TesseractArg spins up the target in that
case. We'll likely deprecate this once Autophysics workflows / P4D cover
all local development purposes.

#### TODO

- [x] Is the Generic type (`TesseractArg[lazy]` vs
`TesseractArg[eager]`) desirable? Should we separate entirely into
`TesseractArg` and `TesseractReference`, where the former always
validates to a `Tesseract` and the latter is just two strings?
- [x] Is there a better way than lazy loading the Tesseract class?
Problem is: Like all custom Pydantic types, `TesseractArg` lives in
runtime. However, it validates to `Tesseract`, which is part of the SDK,
making the SDK a dependency of the runtime. In container images, we
currently only install the runtime though. The current approach requires
adding `tesseract_core` to the requirements only in cases where the
`TesseractArg` is actually used.

#### Testing done
CI end-to-end test included.

---------

Co-authored-by: Alessandro Angioi <alessandro.angioi@simulation.science>

Author: linusseelinger

examples/tesseractreference/tesseract_api.py

@@ -0,0 +1,21 @@
+# Copyright 2025 Pasteur Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from pydantic import BaseModel, Field
+
+from tesseract_core.runtime.experimental import TesseractReference
+
+
+class InputSchema(BaseModel):
+    target: TesseractReference = Field(description="Tesseract to call.")
+
+
+class OutputSchema(BaseModel):
+    result: str = Field(description="Result of the Tesseract calls.")
+
+
+def apply(inputs: InputSchema) -> OutputSchema:
+    result = inputs.target.apply({"name": "Alice"})["greeting"]
+    result += " " + inputs.target.apply({"name": "Bob"})["greeting"]
+
+    return OutputSchema(result=result)

examples/tesseractreference/tesseract_config.yaml

@@ -0,0 +1,5 @@
+name: "tesseractreference"
+version: "1.0.0"
+description: "Demonstrates calling other Tesseracts."
+
+build_config:

examples/tesseractreference/tesseract_requirements.txt

@@ -0,0 +1 @@
+tesseract_core

tesseract_core/runtime/experimental.py

@@ -20,7 +20,7 @@
     TypeAdapter,
 )
 from pydantic.json_schema import JsonSchemaValue
-from pydantic_core import SchemaSerializer, SchemaValidator, core_schema
+from pydantic_core import CoreSchema, SchemaSerializer, SchemaValidator, core_schema
 
 from tesseract_core.runtime.file_interactions import PathLike, parent_path
 from tesseract_core.runtime.mpa import (
@@ -248,11 +248,95 @@ def require_file(file_path: PathLike) -> Path:
     return file_path
 
 
+class TesseractReference:
+    """Allows passing a reference to another Tesseract as input."""
+
+    def __init__(self, tesseract: Any) -> None:
+        self._tesseract = tesseract
+
+    def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the underlying Tesseract instance."""
+        return getattr(self._tesseract, name)
+
+    @classmethod
+    def _get_tesseract_class(cls) -> type:
+        """Lazy import of Tesseract class. Avoids hard dependency of Tesseract runtime on Tesseract SDK."""
+        try:
+            from tesseract_core import Tesseract
+
+            return Tesseract
+        except ImportError:
+            raise ImportError(
+                "Tesseract class not found. Ensure tesseract_core is installed and configured correctly."
+            ) from ImportError
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        """Generate Pydantic core schema for TesseractReference."""
+
+        def validate_tesseract_reference(v: Any) -> "TesseractReference":
+            if isinstance(v, cls):
+                return v
+
+            if not (isinstance(v, dict) and "type" in v and "ref" in v):
+                raise ValueError(
+                    f"Expected dict with 'type' and 'ref' keys, got {type(v)}"
+                )
+
+            tesseract_type = v["type"]
+            ref = v["ref"]
+
+            if tesseract_type not in ("api_path", "image", "url"):
+                raise ValueError(
+                    f"Invalid tesseract type '{tesseract_type}'. Expected 'api_path', 'image' or 'url'."
+                )
+
+            Tesseract = cls._get_tesseract_class()
+            if tesseract_type == "api_path":
+                tesseract = Tesseract.from_tesseract_api(ref)
+            elif tesseract_type == "image":
+                tesseract = Tesseract.from_image(ref)
+                tesseract.serve()
+            elif tesseract_type == "url":
+                tesseract = Tesseract.from_url(ref)
+
+            return cls(tesseract)
+
+        return core_schema.no_info_plain_validator_function(
+            validate_tesseract_reference
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
+    ) -> JsonSchemaValue:
+        """Generate JSON schema for OpenAPI."""
+        return {
+            "type": "object",
+            "properties": {
+                "type": {
+                    "type": "string",
+                    "enum": ["api_path", "image", "url"],
+                    "description": "Type of tesseract reference",
+                },
+                "ref": {
+                    "type": "string",
+                    "description": "URL or file path to the tesseract",
+                },
+            },
+            "required": ["type", "ref"],
+            "additionalProperties": False,
+        }
+
+
 __all__ = [
     "InputFileReference",
     "LazySequence",
     "OutputFileReference",
     "PydanticLazySequenceAnnotation",
+    "TesseractReference",
     "log_artifact",
     "log_metric",
     "log_parameter",

tests/endtoend_tests/test_endtoend.py

@@ -1150,3 +1150,144 @@ def test_multi_helloworld_endtoend(
     )
     assert result.exit_code == 0, result.output
     assert "The helloworld Tesseract says: Hello you!" in result.output
+
+
+def test_tesseractreference_endtoend(
+    docker_client,
+    unit_tesseracts_parent_dir,
+    dummy_image_name,
+    dummy_network_name,
+    docker_cleanup,
+):
+    """Test that tesseractreference example can be built and executed, calling helloworld tesseract."""
+    cli_runner = CliRunner(mix_stderr=False)
+
+    # Build Tesseract images
+    img_names = []
+    for tess_name in ("tesseractreference", "helloworld"):
+        img_name = build_tesseract(
+            docker_client,
+            unit_tesseracts_parent_dir / tess_name,
+            dummy_image_name + f"_{tess_name}",
+            tag="sometag",
+        )
+        img_names.append(img_name)
+        assert image_exists(docker_client, img_name)
+        docker_cleanup["images"].append(img_name)
+
+    tesseractreference_img_name, helloworld_img_name = img_names
+
+    # Create Docker network
+    config = get_config()
+    docker = config.docker_executable
+
+    result = subprocess.run(
+        [*docker, "network", "create", dummy_network_name],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert result.returncode == 0, result.stderr
+    docker_cleanup["networks"].append(dummy_network_name)
+
+    # Serve helloworld Tesseract on the shared network
+    result = cli_runner.invoke(
+        app,
+        [
+            "serve",
+            helloworld_img_name,
+            "--network",
+            dummy_network_name,
+            "--network-alias",
+            "helloworld",
+            "--port",
+            "8000",
+        ],
+        catch_exceptions=True,
+    )
+    assert result.exit_code == 0, result.output
+    serve_meta = json.loads(result.output)
+    docker_cleanup["containers"].append(serve_meta["container_name"])
+
+    # Test url type
+    url_payload = (
+        '{"inputs": {"target": {"type": "url", "ref": "http://helloworld:8000"}}}'
+    )
+    result = cli_runner.invoke(
+        app,
+        [
+            "run",
+            tesseractreference_img_name,
+            "apply",
+            url_payload,
+            "--network",
+            dummy_network_name,
+        ],
+        catch_exceptions=True,
+    )
+    assert result.exit_code == 0, result.output
+    output_data = json.loads(result.output)
+    expected_result = "Hello Alice! Hello Bob!"
+    assert output_data["result"] == expected_result
+
+    # Test image type
+    image_payload = json.dumps(
+        {
+            "inputs": {
+                "target": {
+                    "type": "image",
+                    "ref": helloworld_img_name,
+                }
+            }
+        }
+    )
+    result = subprocess.run(
+        [
+            "tesseract-runtime",
+            "apply",
+            image_payload,
+        ],
+        capture_output=True,
+        text=True,
+        env={
+            **os.environ,
+            "TESSERACT_API_PATH": str(
+                unit_tesseracts_parent_dir / "tesseractreference/tesseract_api.py"
+            ),
+        },
+    )
+    assert result.returncode == 0, result.stderr
+    output_data = json.loads(result.stdout)
+    assert output_data["result"] == expected_result
+
+    # Test api_path type
+    path_payload = json.dumps(
+        {
+            "inputs": {
+                "target": {
+                    "type": "api_path",
+                    "ref": str(
+                        unit_tesseracts_parent_dir / "helloworld/tesseract_api.py"
+                    ),
+                }
+            }
+        }
+    )
+    result = subprocess.run(
+        [
+            "tesseract-runtime",
+            "apply",
+            path_payload,
+        ],
+        capture_output=True,
+        text=True,
+        env={
+            **os.environ,
+            "TESSERACT_API_PATH": str(
+                unit_tesseracts_parent_dir / "tesseractreference/tesseract_api.py"
+            ),
+        },
+    )
+    assert result.returncode == 0, result.stderr
+    output_data = json.loads(result.stdout)
+    assert output_data["result"] == expected_result

tests/endtoend_tests/test_examples.py

@@ -760,6 +760,9 @@ class Config:
             ),
         ],
     ),
+    "tesseractreference": Config(  # Can't test requests standalone; needs target Tesseract. Covered in separate test.
+        test_with_random_inputs=False, sample_requests=[]
+    ),
 }