bittensor.core.stream
=====================

.. py:module:: bittensor.core.stream


Classes
-------

.. autoapisummary::

   bittensor.core.stream.BTStreamingResponseModel
   bittensor.core.stream.StreamingSynapse


Module Contents
---------------

.. py:class:: BTStreamingResponseModel

   Bases: :py:obj:`pydantic.BaseModel`


   :func:`BTStreamingResponseModel` is a Pydantic model that encapsulates the token streamer callable for Pydantic
   validation.
   It is used within the :func:`StreamingSynapse` class to create a :func:`BTStreamingResponse` object, which is
   responsible for handling the streaming of tokens.

   The token streamer is a callable that takes a send function and returns an awaitable. It is responsible for generating
   the content of the streaming response, typically by processing tokens and sending them to the client.

   This model ensures that the token streamer conforms to the expected signature and provides a clear interface for
   passing the token streamer to the BTStreamingResponse class.

   :ivar token_streamer: Callable[[Send], Awaitable[None]] The token streamer callable, which takes a send function
                         (provided by the ASGI server) and returns an awaitable. It is responsible for generating the content of the
                         streaming response.



   .. py:attribute:: token_streamer
      :type:  Callable[[starlette.types.Send], Awaitable[None]]


.. py:class:: StreamingSynapse

   Bases: :py:obj:`bittensor.core.synapse.Synapse`, :py:obj:`abc.ABC`


   The :func:`StreamingSynapse` class is designed to be subclassed for handling streaming responses in the Bittensor network.
   It provides abstract methods that must be implemented by the subclass to deserialize, process streaming responses,
   and extract JSON data. It also includes a method to create a streaming response object.


   .. py:class:: BTStreamingResponse(model, *, synapse = None, **kwargs)

      Bases: :py:obj:`starlette.responses.StreamingResponse`


      :func:`BTStreamingResponse` is a specialized subclass of the Starlette StreamingResponse designed to handle the
      streaming of tokens within the Bittensor network. It is used internally by the StreamingSynapse class to manage
      the response streaming process, including sending headers and calling the token streamer provided by the subclass.

      This class is not intended to be directly instantiated or modified by developers subclassing StreamingSynapse.
      Instead, it is used by the :func:`create_streaming_response` method to create a response object based on the
      token streamer provided by the subclass.

      Initializes the BTStreamingResponse with the given token streamer model.

      :param model: A BTStreamingResponseModel instance containing the token streamer callable, which is responsible
                    for generating the content of the response.
      :param synapse: The response Synapse to be used to update the response headers etc.
      :param \*\*kwargs: Additional keyword arguments passed to the parent StreamingResponse class.


      .. py:method:: stream_response(send)
         :async:


         Asynchronously streams the response by sending headers and calling the token streamer.

         This method is responsible for initiating the response by sending the appropriate headers, including the
         content type for event-streaming. It then calls the token streamer to generate the content and sends the
         response body to the client.

         :param send: A callable to send the response, provided by the ASGI server.



      .. py:attribute:: synapse
         :value: None



      .. py:attribute:: token_streamer



   .. py:method:: create_streaming_response(token_streamer)

      Creates a streaming response using the provided token streamer.
      This method can be used by the subclass to create a response object that can be sent back to the client.
      The token streamer should be implemented to generate the content of the response according to the specific
      requirements of the subclass.

      :param token_streamer: A callable that takes a send function and returns an awaitable. It's responsible for
                             generating the content of the response.

      :returns: The streaming response object, ready to be sent to the client.



   .. py:method:: extract_response_json(response)
      :abstractmethod:


      Abstract method that must be implemented by the subclass.
      This method should provide logic to extract JSON data from the response, including headers and content.
      It is called after the response has been processed and is responsible for retrieving structured data that can be
      used by the application.

      :param The response object from which to extract JSON data.:



   .. py:attribute:: model_config


   .. py:method:: process_streaming_response(response)
      :abstractmethod:

      :async:


      Abstract method that must be implemented by the subclass.
      This method should provide logic to handle the streaming response, such as parsing and accumulating data. It is
      called as the response is being streamed from the network, and should be implemented to handle the specific
      streaming data format and requirements of the subclass.

      :param The response object to be processed:
      :param typically containing chunks of data.: