Add TrussChainlet and TrussHandle to the chains SDK reference

.pre-commit-config.yaml

@@ -7,6 +7,7 @@ repos:
       - id: check-added-large-files
         args: ["--maxkb=500"]
       - id: trailing-whitespace
+        exclude: "docs/chains/doc_gen/reference.patch"
       - id: end-of-file-fixer
       - id: check-yaml
       - id: fix-byte-order-marker

docs/chains/doc_gen/API-reference.mdx

@@ -20,6 +20,24 @@ Refer to [the docs](/development/chain/getting-started) and this
 for more guidance on how to create subclasses.
 
 
+### *class* `truss_chains.TrussChainlet`
+
+Declares an existing Truss directory as a chain member that only receives calls.
+
+Unlike `ChainletBase`, the framework does not generate a `model.py` or a typed
+`StubBase` for this declaration — the Truss directory (a `model.py`
+implementation or a `docker_server` Truss) is deployed as-is.
+
+TrussChainlets cannot be entrypoints and cannot declare deps — they are only
+depended on by `ChainletBase` chainlets via `chains.depends(...)`, which yields
+a [`TrussHandle`](#class-truss-chains-remote-chainlet-truss-chainlet-trusshandle) to the caller.
+
+#### truss_dir *: ClassVar[str]*
+
+The Truss directory to wrap. Relative paths resolve against the file that
+declares the class.
+
+
 ### *class* `truss_chains.ModelBase`
 
 Base class for all standalone models.
@@ -644,6 +662,54 @@ Deprecated synchronous methods:
 * `predict_sync(inputs: JSON) → JSON`
 
 
+### *class* `truss_chains.remote_chainlet.truss_chainlet.TrussHandle`
+
+Handle for calling a [`TrussChainlet`](#class-truss-chains-trusschainlet) sibling. Returned by
+`chains.depends()` on a `TrussChainlet`. Build once (e.g. in `__init__`), then
+get call arguments per request and pass them to your own HTTP or WebSocket
+client.
+
+**Parameters:**
+
+| Name     | Type                     | Description                                    |
+|----------|--------------------------|------------------------------------------------|
+| `target` | *str\|Type[ABCChainlet]* | The `TrussChainlet` class or its display name. |
+
+#### http_call_args(\*, prefer_internal=False, sync_path=None, api_key=None)
+
+Returns the URL and headers for an HTTP call to the sibling.
+
+`prefer_internal` uses the internal cluster URL with the matching `Host` header
+if available. `sync_path` rewrites the URL to the `/sync/<sync_path>`
+passthrough. `api_key` overrides the platform-injected chain API key.
+
+**Parameters:**
+
+| Name              | Type        | Default |
+|-------------------|-------------|---------|
+| `prefer_internal` | *bool*      | `False` |
+| `sync_path`       | *str\|None* | `None`  |
+| `api_key`         | *str\|None* | `None`  |
+
+* **Return type:**
+  *CallArgs*, a named tuple of `(url, headers)`.
+
+#### ws_call_args(\*, sync_path=None, api_key=None)
+
+Returns a `wss://` URL and auth-only headers for a WebSocket call to the
+sibling. WebSocket clients reject Host-header overrides, so this has no
+`prefer_internal` kwarg.
+
+**Parameters:**
+
+| Name        | Type        | Default |
+|-------------|-------------|---------|
+| `sync_path` | *str\|None* | `None`  |
+| `api_key`   | *str\|None* | `None`  |
+
+* **Return type:**
+  *CallArgs*, a named tuple of `(url, headers)`.
+
 ### *class* `truss_chains.RemoteErrorDetail`
 
 Bases: `pydantic.BaseModel`

docs/chains/doc_gen/README.md

@@ -2,8 +2,9 @@ This generation process of the documentation is *extremely* scrappy and just
 an interim solution. It requires significant manual oversight and the code
 quality in this directory is non-existent.
 
-Extra deps required:
-`pip install sphinx sphinx_rtd_theme sphinx_markdown_builder sphinx-pydantic`
+Extra deps required (newer sphinx/sphinx-markdown-builder versions silently
+fall back to `.md` output and drop types from parameter tables):
+`pip install "sphinx==7.4.7" sphinx_rtd_theme "sphinx-markdown-builder==0.6.6" sphinx-pydantic`
 
 
 The general process is:

docs/chains/doc_gen/generate_reference.py

@@ -5,6 +5,7 @@
 import pathlib
 import shutil
 import subprocess
+import sys
 import tempfile
 from pathlib import Path
 
@@ -27,14 +28,18 @@
 
 
 BUILDER = "mdx_adapter"  # "mdx_adapter" "html" "markdown"
-NON_PUBLIC_SYMBOLS = ["truss_chains.deployment.deployment_client.ChainService"]
+NON_PUBLIC_SYMBOLS = [
+    "truss_chains.deployment.deployment_client.ChainService",
+    "truss_chains.remote_chainlet.truss_chainlet.TrussHandle",
+]
 
 
 SECTION_CHAINLET = (
     "Chainlet classes",
     "APIs for creating user-defined Chainlets.",
     [
         "truss_chains.ChainletBase",
+        "truss_chains.TrussChainlet",
         "truss_chains.ModelBase",
         "truss_chains.EngineBuilderLLMChainlet",
         "truss_chains.depends",
@@ -71,12 +76,17 @@
         "truss_chains.run_local",
         "truss_chains.DeployedServiceDescriptor",
         "truss_chains.StubBase",
+        "truss_chains.remote_chainlet.truss_chainlet.TrussHandle",
         "truss_chains.RemoteErrorDetail",
         "truss_chains.GenericRemoteException",
     ],
 )
 
-UNDOCUMENTED = ["truss_chains.WebSocketProtocol", "truss_chains.EngineBuilderLLMInput"]
+UNDOCUMENTED = [
+    "truss_chains.WebSocketProtocol",
+    "truss_chains.EngineBuilderLLMInput",
+    "truss_chains.WeightsSource",
+]
 
 SECTIONS = [SECTION_CHAINLET, SECTION_CONFIG, SECTION_UTILITIES]
 
@@ -212,4 +222,7 @@ def generate_sphinx_docs(output_dir: pathlib.Path) -> None:
 
 
 if __name__ == "__main__":
+    # The mdx_adapter sphinx extension lives next to this script; make it
+    # importable regardless of the CWD the script is invoked from.
+    sys.path.insert(0, str(pathlib.Path(__file__).parent))
     generate_sphinx_docs(output_dir=pathlib.Path("/tmp/doc_gen"))

docs/chains/doc_gen/generated-reference.mdx

@@ -20,6 +20,22 @@ Refer to [the docs](https://docs.baseten.co/chains/getting-started) and this
 for more guidance on how to create subclasses.
 
 
+### *class* `truss_chains.TrussChainlet`
+
+Declares an existing Truss directory as a chain member that only receives calls.
+
+Unlike `ChainletBase`, the framework does not generate a `model.py` or
+a typed `StubBase` for this declaration — the user’s Truss directory
+(`model.py`-flavored or `docker_server`) is archived as-is.
+
+TrussChainlets cannot be entrypoints and cannot declare deps — they’re
+only depended on by `ChainletBase` chainlets via `chains.depends(...)`,
+which yields a
+[`truss_chains.remote_chainlet.truss_chainlet.TrussHandle`](#truss_chains.remote_chainlet.truss_chainlet.TrussHandle) to the caller.
+
+#### truss_dir *: ClassVar[str]*
+
+
 ### *class* `truss_chains.ModelBase`
 
 Base class for all standalone models.
@@ -785,6 +801,54 @@ Factory method, convenient to be used in chainlet’s `__init__`-method.
 #### predict_sync(inputs: InputT, output_model: None = None) → Any
 
 
+### *class* `truss_chains.remote_chainlet.truss_chainlet.TrussHandle`
+
+Sibling chainlet handle; build once (e.g. in `__init__`), then call args.
+
+* **Parameters:**
+  **target** (*str* *|* *Type* *[**ABCChainlet* *]*)
+
+#### http_call_args(\*, prefer_internal=False, sync_path=None, api_key=None)
+
+Default `predict_url` + `Authorization`; `prefer_internal` uses workload-plane URL + `Host`.
+
+`sync_path` rewrites the URL to `/sync/<sync_path>`.
+`api_key` overrides `get_baseten_chain_api_key()`.
+`prefer_internal` uses the internal url if it exists.
+
+
+**Parameters:**
+
+| Name              | Type        |
+|-------------------|-------------|
+| `prefer_internal` | *bool*      |
+| `sync_path`       | *str\|None* |
+| `api_key`         | *str\|None* |
+
+* **Return type:**
+  *CallArgs*
+
+#### urls *: ServiceDescriptorUrls*
+
+#### ws_call_args(\*, sync_path=None, api_key=None)
+
+Returns a `wss://` URL + auth-only headers for a WebSocket sibling call.
+
+`websockets.connect` rejects Host-header overrides (api-gateway
+returns 400), so this has no `prefer_internal` kwarg
+
+
+**Parameters:**
+
+| Name        | Type        |
+|-------------|-------------|
+| `sync_path` | *str\|None* |
+| `api_key`   | *str\|None* |
+
+* **Return type:**
+  *CallArgs*
+
+
 ### *class* `truss_chains.RemoteErrorDetail`
 
 Bases: `pydantic.BaseModel`