feat: allow creating tesseract objects from python modules (#122)

#### Relevant issue or PR
n/a

#### Description of changes
- Introduce `Tesseract.from_tesseract_api` to create Tesseract objects
directly from importable `tesseract_api.py` files. (This is mainly
useful for debugging.)
- Add `from_url` classmethod (same as `Tesseract.__init__`) for
symmetry.
- Make `Tesseract.serve` and `Tesseract.teardown` public to give users
the option to avoid excessive context managers.

#### Testing done
CI, old and new

#### License

- [x] By submitting this pull request, I confirm that my contribution is
made under the terms of the [Apache 2.0
license](https://pasteurlabs.github.io/tesseract/LICENSE).
- [x] I sign the Developer Certificate of Origin below by adding my name
and email address to the `Signed-off-by` line.

<details>
<summary><b>Developer Certificate of Origin</b></summary>

```text
Developer Certificate of Origin
Version 1.1

Copyright (C) 2004, 2006 The Linux Foundation and its contributors.

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.


Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
```

</details>

Signed-off-by: Dion Häfner <dion.haefner@simulation.science>

---------

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

Author: dionhaefner

inject_runtime_pyproject.py

@@ -49,9 +49,12 @@
 
 
 class RuntimeDepenencyHook(MetadataHookInterface):
+    """Injects runtime dependencies and scripts from a separate pyproject.toml file."""
+
     PLUGIN_NAME = "runtime-deps"
 
-    def update(self, metadata):
+    def update(self, metadata: dict) -> dict:
+        """Update the metadata with runtime dependencies and scripts."""
         runtime_metadata = toml.load(Path(self.root) / RUNTIME_PYPROJECT_PATH)
         metadata["optional-dependencies"] = {
             **BASE_OPTIONAL_DEPS,

ruff.toml

@@ -46,7 +46,7 @@ ignore = [
 
 [lint.extend-per-file-ignores]
 # Ignore missing docstrings and type annotations for selected directories
-"./*.py" = ["D101", "D102", "D103", "D106", "ANN"]
+"docs/*" = ["D101", "D102", "D103", "D106", "ANN"]
 "tests/*" = ["D101", "D102", "D103", "D106", "ANN"]
 "examples/**/*" = ["D101", "D102", "D103", "D106", "ANN"]
 "tesseract_core/sdk/templates/*" = ["D101", "D102", "D103", "D106", "ANN"]

tesseract_core/runtime/cli.py

@@ -230,16 +230,16 @@ def check() -> None:
     help="Show progress bar.",
 )
 def check_gradients(
-    payload,
-    input_paths,
-    output_paths,
-    endpoints,
-    eps,
-    rtol,
-    max_evals,
-    max_failures,
-    seed,
-    show_progress,
+    payload: tuple[dict[str, Any], Optional[Path]],
+    input_paths: list[str],
+    output_paths: list[str],
+    endpoints: list[str],
+    eps: float,
+    rtol: float,
+    max_evals: int,
+    max_failures: int,
+    seed: Optional[int],
+    show_progress: bool,
 ) -> None:
     """Check gradients of endpoints against a finite difference approximation.
 

tesseract_core/runtime/finite_differences.py

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import traceback
-from collections.abc import Sequence
+from collections.abc import Iterator, Sequence
 from functools import wraps
 from pathlib import Path
 from types import ModuleType
@@ -29,6 +29,17 @@
 
 
 class GradientCheckResult(NamedTuple):
+    """Result of a gradient check (Jacobian row).
+
+    Attributes:
+        in_path: The input path of the gradient check.
+        out_path: The output path of the gradient check.
+        idx: The row index of the gradient check.
+        grad_val: The value of the gradient at the given index.
+        ref_val: The value of the reference gradient at the given index.
+        exception: The exception raised during the gradient check, if any.
+    """
+
     in_path: str
     out_path: str
     idx: tuple[int, ...]
@@ -150,7 +161,7 @@ def _jacobian_via_apply(
     apply_fn = endpoints_func["apply"]
     ApplySchema = get_input_schema(apply_fn)
 
-    def _perturbed_apply(inputs, eps):
+    def _perturbed_apply(inputs: dict[str, Any], eps: float) -> dict[str, Any]:
         input_val = get_at_path(inputs, input_path).copy()
         if input_idx:
             # array
@@ -183,7 +194,7 @@ def _jacobian_via_jacobian(
     """Compute a Jacobian row using the jacobian endpoint."""
     jac_fn = endpoints_func["jacobian"]
 
-    def _jacobian(inputs):
+    def _jacobian(inputs: dict[str, Any]) -> dict[str, Any]:
         JacSchema = get_input_schema(jac_fn)
         return jac_fn(
             JacSchema.model_validate(
@@ -406,7 +417,7 @@ def check_gradients(
     rtol: float = 0.1,
     seed: Optional[int] = None,
     show_progress: bool = True,
-):
+) -> Iterator[tuple[str, list[GradientCheckResult], int]]:
     """Check gradients of endpoints against a finite difference approximation.
 
     Args:

tesseract_core/runtime/schema_generation.py

@@ -411,6 +411,7 @@ def _is_regex_pattern(pattern: str) -> bool:
 
 
 def input_path_validator(path: str, info: ValidationInfo) -> str:
+    """Validate that the given path points to a valid input key."""
     if "[" in path or "{" in path:
         try:
             get_at_path(info.data["inputs"], path)

tesseract_core/runtime/schema_types.py

@@ -36,7 +36,7 @@
 EllipsisType = type(Ellipsis)
 
 
-def _ensure_valid_shapedtype(expected_shape, expected_dtype) -> tuple:
+def _ensure_valid_shapedtype(expected_shape: Any, expected_dtype: Any) -> tuple:
     if not isinstance(expected_shape, (tuple, EllipsisType)):
         raise ValueError(
             "Shape in Array[<shape>, <dtype>] must be a tuple or '...' (ellipsis)"
@@ -79,7 +79,8 @@ def __class_getitem__(
     ) -> AnnotatedType:
         expected_shape, expected_dtype = _ensure_valid_shapedtype(*key)
 
-        def validate(shapedtype):
+        def validate(shapedtype: ShapeDType) -> ShapeDType:
+            """Validator to check if the shape and dtype match the expected values."""
             if isinstance(shapedtype, ShapeDType):
                 shape = shapedtype.shape
                 if expected_shape is Ellipsis:
@@ -95,6 +96,7 @@ def validate(shapedtype):
 
     @classmethod
     def from_array_annotation(cls, obj: AnnotatedType) -> AnnotatedType:
+        """Create a ShapeDType from an array annotation."""
         shape = obj.__metadata__[0].expected_shape
         dtype = obj.__metadata__[0].expected_dtype
         return cls[shape, dtype]

tesseract_core/sdk/api_parse.py

@@ -74,13 +74,17 @@ def assert_relative_path(value: str) -> str:
 
 
 class PipRequirements(BaseModel):
+    """Configuration options for Python environments built via pip."""
+
     provider: Literal["python-pip"]
     _filename: Literal["tesseract_requirements.txt"] = "tesseract_requirements.txt"
     _build_script: Literal["build_pip_venv.sh"] = "build_pip_venv.sh"
     model_config: ConfigDict = ConfigDict(extra="forbid")
 
 
 class CondaRequirements(BaseModel):
+    """Configuration options for Python environments built via conda."""
+
     provider: Literal["conda"]
     _filename: Literal["tesseract_environment.yaml"] = "tesseract_environment.yaml"
     _build_script: Literal["build_conda_venv.sh"] = "build_conda_venv.sh"

tesseract_core/sdk/engine.py

@@ -243,7 +243,7 @@ def get_runtime_dir() -> Path:
     return Path(tesseract_core.__file__).parent / "runtime"
 
 
-def get_template_dir():
+def get_template_dir() -> Path:
     """Get the template directory for the Tesseract runtime."""
     import tesseract_core
 
@@ -345,7 +345,7 @@ def prepare_build_context(
             for dependency in remote_dependencies:
                 f.write(f"{dependency}\n")
 
-    def _ignore_pycache(_, names: list[str]) -> list[str]:
+    def _ignore_pycache(_: Any, names: list[str]) -> list[str]:
         ignore = []
         if "__pycache__" in names:
             ignore.append("__pycache__")