chore: import upstream snapshot with attribution

doc/source/serve/doc_code/model_composition/chaining_example.py

@@ -0,0 +1,50 @@
+# flake8: noqa
+# __chaining_example_start__
+# File name: chain.py
+from ray import serve
+from ray.serve.handle import DeploymentHandle, DeploymentResponse
+
+
+@serve.deployment
+class Adder:
+    def __init__(self, increment: int):
+        self._increment = increment
+
+    def __call__(self, val: int) -> int:
+        return val + self._increment
+
+
+@serve.deployment
+class Multiplier:
+    def __init__(self, multiple: int):
+        self._multiple = multiple
+
+    def __call__(self, val: int) -> int:
+        return val * self._multiple
+
+
+@serve.deployment
+class Ingress:
+    def __init__(self, adder: DeploymentHandle, multiplier: DeploymentHandle):
+        self._adder = adder
+        self._multiplier = multiplier
+
+    async def __call__(self, input: int) -> int:
+        adder_response: DeploymentResponse = self._adder.remote(input)
+        # Pass the adder response directly into the multiplier (no `await` needed).
+        multiplier_response: DeploymentResponse = self._multiplier.remote(
+            adder_response
+        )
+        # `await` the final chained response.
+        return await multiplier_response
+
+
+app = Ingress.bind(
+    Adder.bind(increment=1),
+    Multiplier.bind(multiple=2),
+)
+
+handle: DeploymentHandle = serve.run(app)
+response = handle.remote(5)
+assert response.result() == 12, "(5 + 1) * 2 = 12"
+# __chaining_example_end__

doc/source/serve/doc_code/model_composition/language_example.py

@@ -0,0 +1,98 @@
+# flake8: noqa
+
+import requests
+
+# __echo_class_start__
+# File name: echo.py
+from starlette.requests import Request
+
+from ray import serve
+
+
+@serve.deployment
+class EchoClass:
+    def __init__(self, echo_str: str):
+        self.echo_str = echo_str
+
+    def __call__(self, request: Request) -> str:
+        return self.echo_str
+
+
+# You can create ClassNodes from the EchoClass deployment
+foo_node = EchoClass.bind("foo")
+bar_node = EchoClass.bind("bar")
+baz_node = EchoClass.bind("baz")
+# __echo_class_end__
+
+for node, echo in [(foo_node, "foo"), (bar_node, "bar"), (baz_node, "baz")]:
+    serve.run(node)
+    assert requests.get("http://localhost:8000/").text == echo
+
+# __echo_client_start__
+# File name: echo_client.py
+import requests
+
+response = requests.get("http://localhost:8000/")
+echo = response.text
+print(echo)
+# __echo_client_end__
+
+# __hello_start__
+# File name: hello.py
+from ray import serve
+from ray.serve.handle import DeploymentHandle
+
+
+@serve.deployment
+class LanguageClassifer:
+    def __init__(
+        self, spanish_responder: DeploymentHandle, french_responder: DeploymentHandle
+    ):
+        self.spanish_responder = spanish_responder
+        self.french_responder = french_responder
+
+    async def __call__(self, http_request):
+        request = await http_request.json()
+        language, name = request["language"], request["name"]
+
+        if language == "spanish":
+            response = self.spanish_responder.say_hello.remote(name)
+        elif language == "french":
+            response = self.french_responder.say_hello.remote(name)
+        else:
+            return "Please try again."
+
+        return await response
+
+
+@serve.deployment
+class SpanishResponder:
+    def say_hello(self, name: str):
+        return f"Hola {name}"
+
+
+@serve.deployment
+class FrenchResponder:
+    def say_hello(self, name: str):
+        return f"Bonjour {name}"
+
+
+spanish_responder = SpanishResponder.bind()
+french_responder = FrenchResponder.bind()
+language_classifier = LanguageClassifer.bind(spanish_responder, french_responder)
+# __hello_end__
+
+serve.run(language_classifier)
+
+# __hello_client_start__
+# File name: hello_client.py
+import requests
+
+response = requests.post(
+    "http://localhost:8000", json={"language": "spanish", "name": "Dora"}
+)
+greeting = response.text
+print(greeting)
+# __hello_client_end__
+
+assert greeting == "Hola Dora"

doc/source/serve/doc_code/model_composition/response_to_object_ref_example.py

@@ -0,0 +1,37 @@
+# flake8: noqa
+# __response_to_object_ref_example_start__
+# File name: response_to_object_ref.py
+import ray
+from ray import serve
+from ray.serve.handle import DeploymentHandle, DeploymentResponse
+
+
+@ray.remote
+def say_hi_task(inp: str):
+    return f"Ray task got message: '{inp}'"
+
+
+@serve.deployment
+class SayHi:
+    def __call__(self) -> str:
+        return "Hi from Serve deployment"
+
+
+@serve.deployment
+class Ingress:
+    def __init__(self, say_hi: DeploymentHandle):
+        self._say_hi = say_hi
+
+    async def __call__(self):
+        # Make a call to the SayHi deployment and pass the result ref to
+        # a downstream Ray task.
+        response: DeploymentResponse = self._say_hi.remote()
+        response_obj_ref: ray.ObjectRef = await response._to_object_ref()
+        final_obj_ref: ray.ObjectRef = say_hi_task.remote(response_obj_ref)
+        return await final_obj_ref
+
+
+app = Ingress.bind(SayHi.bind())
+handle: DeploymentHandle = serve.run(app)
+assert handle.remote().result() == "Ray task got message: 'Hi from Serve deployment'"
+# __response_to_object_ref_example_end__

doc/source/serve/doc_code/model_composition/streaming_example.py

@@ -0,0 +1,42 @@
+# flake8: noqa
+# __streaming_example_start__
+# File name: stream.py
+from typing import AsyncGenerator, Generator
+
+from ray import serve
+from ray.serve.handle import DeploymentHandle, DeploymentResponseGenerator
+
+
+@serve.deployment
+class Streamer:
+    def __call__(self, limit: int) -> Generator[int, None, None]:
+        for i in range(limit):
+            yield i
+
+
+@serve.deployment
+class Caller:
+    def __init__(self, streamer: DeploymentHandle):
+        self._streamer = streamer.options(
+            # Must set `stream=True` on the handle, then the output will be a
+            # response generator.
+            stream=True,
+        )
+
+    async def __call__(self, limit: int) -> AsyncGenerator[int, None]:
+        # Response generator can be used in an `async for` block.
+        r: DeploymentResponseGenerator = self._streamer.remote(limit)
+        async for i in r:
+            yield i
+
+
+app = Caller.bind(Streamer.bind())
+
+handle: DeploymentHandle = serve.run(app).options(
+    stream=True,
+)
+
+# Response generator can also be used as a regular generator in a sync context.
+r: DeploymentResponseGenerator = handle.remote(10)
+assert list(r) == list(range(10))
+# __streaming_example_end__