bittensor.dendrite#

Module Contents#

Classes#

dendrite

The Dendrite class, inheriting from PyTorch's Module class, represents the abstracted implementation of a network client module.
class bittensor.dendrite.dendrite(wallet=None)#

Bases: torch.nn.Module

The Dendrite class, inheriting from PyTorch’s Module class, represents the abstracted implementation of a network client module.

In the brain analogy, dendrites receive signals from other neurons (in this case, network servers or axons), and the Dendrite class here is designed to send requests to those endpoint to recieve inputs.

This class includes a wallet or keypair used for signing messages, and methods for making HTTP requests to the network servers. It also provides functionalities such as logging network requests and processing server responses.

Parameters:

  • keypair – The wallet or keypair used for signing messages.

  • external_ip (str) – The external IP address of the local system.

  • synapse_history (list) – A list of Synapse objects representing the historical responses.

  • wallet (Optional[Union[bittensor.wallet, bittensor.keypair]]) –

__str__()#

Returns a string representation of the Dendrite object.

Return type:

str

__repr__()#

Returns a string representation of the Dendrite object, acting as a fallback for __str__().

Return type:

str

query(self, *args, **kwargs) → bittensor.Synapse | List[bittensor.Synapse]#

Makes synchronous requests to one or multiple target Axons and returns responses.

Return type:

Union[bittensor.Synapse, List[bittensor.Synapse], bittensor.StreamingSynapse, List[bittensor.StreamingSynapse]]

forward(self, axons, synapse=bittensor.Synapse(), timeout=12, deserialize=True, run_async=True, streaming=False) → bittensor.Synapse#

Asynchronously sends requests to one or multiple Axons and collates their responses.

Parameters:
Return type:

List[Union[AsyncGenerator[Any], bittenst.Synapse, bittensor.StreamingSynapse]]

call(self, target_axon, synapse=bittensor.Synapse(), timeout=12.0, deserialize=True) → bittensor.Synapse#

Asynchronously sends a request to a specified Axon and processes the response.

Parameters:
Return type:

bittensor.Synapse

call_stream(self, target_axon, synapse=bittensor.Synapse(), timeout=12.0, deserialize=True) → AsyncGenerator[bittensor.Synapse, None]#

Sends a request to a specified Axon and yields an AsyncGenerator that contains streaming response chunks before finally yielding the filled Synapse as the final element.

Parameters:
Return type:

AsyncGenerator[Any]

preprocess_synapse_for_request(self, target_axon_info, synapse, timeout=12.0) → bittensor.Synapse#

Preprocesses the synapse for making a request, including building headers and signing.

Parameters:
Return type:

bittensor.Synapse

process_server_response(self, server_response, json_response, local_synapse)#

Processes the server response, updates the local synapse state, and merges headers.

Parameters:
close_session(self)#

Synchronously closes the internal aiohttp client session.

aclose_session(self)#

Asynchronously closes the internal aiohttp client session.

Note

When working with async aiohttp client sessions, it is recommended to use a context manager.

Example with a context manager:

>>> aysnc with dendrite(wallet = bittensor.wallet()) as d:
>>>     print(d)
>>>     d( <axon> ) # ping axon
>>>     d( [<axons>] ) # ping multiple
>>>     d( bittensor.axon(), bittensor.Synapse )

However, you are able to safely call dendrite.query() without a context manager in a synchronous setting.

Example without a context manager:

>>> d = dendrite(wallet = bittensor.wallet() )
>>> print(d)
>>> d( <axon> ) # ping axon
>>> d( [<axons>] ) # ping multiple
>>> d( bittensor.axon(), bittensor.Synapse )
property session: aiohttp.ClientSession#

An asynchronous property that provides access to the internal aiohttp client session.

This property ensures the management of HTTP connections in an efficient way. It lazily initializes the aiohttp.ClientSession on its first use. The session is then reused for subsequent HTTP requests, offering performance benefits by reusing underlying connections.

This is used internally by the dendrite when querying axons, and should not be used directly unless absolutely necessary for your application.

Returns:

The active aiohttp client session instance. If no session exists, a new one is created and returned. This session is used for asynchronous HTTP requests within the dendrite, adhering to the async nature of the network interactions in the Bittensor framework.

Return type:

aiohttp.ClientSession

Example usage:

import bittensor as bt                    # Import bittensor
wallet = bt.wallet( ... )                 # Initialize a wallet
dendrite = bt.dendrite( wallet )          # Initialize a dendrite instance with the wallet

async with (await dendrite.session).post( # Use the session to make an HTTP POST request
    url,                                  # URL to send the request to
    headers={...},                        # Headers dict to be sent with the request
    json={...},                           # JSON body data to be sent with the request
    timeout=10,                           # Timeout duration in seconds
) as response:
    json_response = await response.json() # Extract the JSON response from the server
async __aenter__()#

Asynchronous context manager entry method.

Enables the use of the async with statement with the Dendrite instance. When entering the context, the current instance of the class is returned, making it accessible within the asynchronous context.

Returns:

The current instance of the Dendrite class.

Return type:

Dendrite

Usage:

async with Dendrite() as dendrite:
    await dendrite.some_async_method()
async __aexit__(exc_type, exc_value, traceback)#

Asynchronous context manager exit method.

Ensures proper cleanup when exiting the async with context. This method will close the aiohttp client session asynchronously, releasing any tied resources.

Parameters:

  • exc_type (Type[BaseException], optional) – The type of exception that was raised.

  • exc_value (BaseException, optional) – The instance of exception that was raised.

  • traceback (TracebackType, optional) – A traceback object encapsulating the call stack at the point where the exception was raised.

Usage:

async with bt.dendrite( wallet ) as dendrite:
    await dendrite.some_async_method()

Note

This automatically closes the session by calling __aexit__() after the context closes.

__del__()#

Dendrite destructor.

This method is invoked when the Dendrite instance is about to be destroyed. The destructor ensures that the aiohttp client session is closed before the instance is fully destroyed, releasing any remaining resources.

Note

Relying on the destructor for cleanup can be unpredictable. It is recommended to explicitly close sessions using the provided methods or the async with context manager.

Usage:

dendrite = Dendrite()
# ... some operations ...
del dendrite  # This will implicitly invoke the __del__ method and close the session.
__repr__()#

Returns a string representation of the Dendrite object, acting as a fallback for __str__().

Returns:

The string representation of the Dendrite object in the format dendrite(<user_wallet_address>)().

Return type:

str

__str__()#

Returns a string representation of the Dendrite object.

Returns:

The string representation of the Dendrite object in the format dendrite(<user_wallet_address>)().

Return type:

str

_get_endpoint_url(target_axon, request_name)#

Constructs the endpoint URL for a network request to a target axon.

This internal method generates the full HTTP URL for sending a request to the specified axon. The URL includes the IP address and port of the target axon, along with the specific request name. It differentiates between requests to the local system (using ‘0.0.0.0’) and external systems.

Parameters:

  • target_axon – The target axon object containing IP and port information.

  • request_name – The specific name of the request being made.

Returns:

A string representing the complete HTTP URL for the request.

Return type:

str

_handle_request_errors(synapse, request_name, exception)#

Handles exceptions that occur during network requests, updating the synapse with appropriate status codes and messages.

This method interprets different types of exceptions and sets the corresponding status code and message in the synapse object. It covers common network errors such as connection issues and timeouts.

Parameters:

  • synapse – The synapse object associated with the request.

  • request_name – The name of the request during which the exception occurred.

  • exception – The exception object caught during the request.

Note

This method updates the synapse object in-place.

_log_incoming_response(synapse)#

Logs information about incoming responses for debugging and monitoring.

Similar to _log_outgoing_request(), this method logs essential details of the incoming responses, including the size of the response, synapse name, axon details, status code, and status message. This logging is vital for troubleshooting and understanding the network interactions in Bittensor.

Parameters:

synapse – The synapse object representing the received response.

_log_outgoing_request(synapse)#

Logs information about outgoing requests for debugging purposes.

This internal method logs key details about each outgoing request, including the size of the request, the name of the synapse, the axon’s details, and a success indicator. This information is crucial for monitoring and debugging network activity within the Bittensor network.

To turn on debug messages, set the environment variable BITTENSOR_DEBUG to 1, or call the bittensor debug method like so:

import bittensor
bittensor.debug()
Parameters:

synapse – The synapse object representing the request being sent.

async aclose_session()#

Asynchronously closes the internal aiohttp client session.

This method is the asynchronous counterpart to the close_session() method. It should be used in asynchronous contexts to ensure that the aiohttp client session is closed properly. The method releases resources associated with the session, such as open connections and internal buffers, which is essential for resource management in asynchronous applications.

Usage:

When finished with dendrite in an asynchronous context await dendrite_instance.aclose_session().

Example:

async with dendrite_instance:
    # Operations using dendrite
    pass
# The session will be closed automatically after the above block
async call(target_axon, synapse=bittensor.Synapse(), timeout=12.0, deserialize=True)#

Asynchronously sends a request to a specified Axon and processes the response.

This function establishes a connection with a specified Axon, sends the encapsulated data through the Synapse object, waits for a response, processes it, and then returns the updated Synapse object.

Parameters:

  • target_axon (Union['bittensor.AxonInfo', 'bittensor.axon']) – The target Axon to send the request to.

  • synapse (bittensor.Synapse, optional) – The Synapse object encapsulating the data. Defaults to a new bittensor.Synapse() instance.

  • timeout (float, optional) – Maximum duration to wait for a response from the Axon in seconds. Defaults to 12.0.

  • deserialize (bool, optional) – Determines if the received response should be deserialized. Defaults to True.

Returns:

The Synapse object, updated with the response data from the Axon.

Return type:

bittensor.Synapse

async call_stream(target_axon, synapse=bittensor.Synapse(), timeout=12.0, deserialize=True)#

Sends a request to a specified Axon and yields streaming responses.

Similar to call, but designed for scenarios where the Axon sends back data in multiple chunks or streams. The function yields each chunk as it is received. This is useful for processing large responses piece by piece without waiting for the entire data to be transmitted.

Parameters:

  • target_axon (Union['bittensor.AxonInfo', 'bittensor.axon']) – The target Axon to send the request to.

  • synapse (bittensor.Synapse, optional) – The Synapse object encapsulating the data. Defaults to a new bittensor.Synapse() instance.

  • timeout (float, optional) – Maximum duration to wait for a response (or a chunk of the response) from the Axon in seconds. Defaults to 12.0.

  • deserialize (bool, optional) – Determines if each received chunk should be deserialized. Defaults to True.

Yields:

object – Each yielded object contains a chunk of the arbitrary response data from the Axon. bittensor.Synapse: After the AsyncGenerator has been exhausted, yields the final filled Synapse.

Return type:

AsyncGenerator[Any]

close_session()#

Closes the internal aiohttp client session synchronously.

This method ensures the proper closure and cleanup of the aiohttp client session, releasing any resources like open connections and internal buffers. It is crucial for preventing resource leakage and should be called when the dendrite instance is no longer in use, especially in synchronous contexts.

Note

This method utilizes asyncio’s event loop to close the session asynchronously from a synchronous context. It is advisable to use this method only when asynchronous context management is not feasible.

Usage:

When finished with dendrite in a synchronous context dendrite_instance.close_session().

async forward(axons, synapse=bittensor.Synapse(), timeout=12, deserialize=True, run_async=True, streaming=False)#

Asynchronously sends requests to one or multiple Axons and collates their responses.

This function acts as a bridge for sending multiple requests concurrently or sequentially based on the provided parameters. It checks the type of the target Axons, preprocesses the requests, and then sends them off. After getting the responses, it processes and collates them into a unified format.

When querying an Axon that sends a single response, this function returns a Synapse object containing the response data. If multiple Axons are queried, a list of Synapse objects is returned, each containing the response from the corresponding Axon.

For example:

>>> ...
>>> wallet = bittensor.wallet()                   # Initialize a wallet
>>> synapse = bittensor.Synapse(...)              # Create a synapse object that contains query data
>>> dendrte = bittensor.dendrite(wallet = wallet) # Initialize a dendrite instance
>>> axons = metagraph.axons                       # Create a list of axons to query
>>> responses = await dendrite(axons, synapse)    # Send the query to all axons and await the responses

When querying an Axon that sends back data in chunks using the Dendrite, this function returns an AsyncGenerator that yields each chunk as it is received. The generator can be iterated over to process each chunk individually.

For example:

>>> ...
>>> dendrte = bittensor.dendrite(wallet = wallet)
>>> async for chunk in dendrite.forward(axons, synapse, timeout, deserialize, run_async, streaming):
>>>     # Process each chunk here
>>>     print(chunk)
Parameters:

  • axons (Union[List[Union['bittensor.AxonInfo', 'bittensor.axon']], Union['bittensor.AxonInfo', 'bittensor.axon']]) – The target Axons to send requests to. Can be a single Axon or a list of Axons.

  • synapse (bittensor.Synapse, optional) – The Synapse object encapsulating the data. Defaults to a new bittensor.Synapse() instance.

  • timeout (float, optional) – Maximum duration to wait for a response from an Axon in seconds. Defaults to 12.0.

  • deserialize (bool, optional) – Determines if the received response should be deserialized. Defaults to True.

  • run_async (bool, optional) – If True, sends requests concurrently. Otherwise, sends requests sequentially. Defaults to True.

  • streaming (bool, optional) – Indicates if the response is expected to be in streaming format. Defaults to False.

Returns:

If a single Axon is targeted, returns its response. If multiple Axons are targeted, returns a list of their responses.

Return type:

Union[AsyncGenerator, bittensor.Synapse, List[bittensor.Synapse]]

preprocess_synapse_for_request(target_axon_info, synapse, timeout=12.0)#

Preprocesses the synapse for making a request. This includes building headers for Dendrite and Axon and signing the request.

Parameters:

  • target_axon_info (bittensor.AxonInfo) – The target axon information.

  • synapse (bittensor.Synapse) – The synapse object to be preprocessed.

  • timeout (float, optional) – The request timeout duration in seconds. Defaults to 12.0 seconds.

Returns:

The preprocessed synapse.

Return type:

bittensor.Synapse

process_server_response(server_response, json_response, local_synapse)#

Processes the server response, updates the local synapse state with the server’s state and merges headers set by the server.

Parameters:

  • server_response (object) –

    The aiohttp response object from the server.

  • json_response (dict) – The parsed JSON response from the server.

  • local_synapse (bittensor.Synapse) – The local synapse object to be updated.

Raises:

None – But errors in attribute setting are silently ignored.

query(*args, **kwargs)#

Makes a synchronous request to multiple target Axons and returns the server responses.

Cleanup is automatically handled and sessions are closed upon completed requests.

Parameters:

  • axons (Union[List[Union['bittensor.AxonInfo', 'bittensor.axon']], Union['bittensor.AxonInfo', 'bittensor.axon']]) – The list of target Axon information.

  • synapse (bittensor.Synapse, optional) – The Synapse object. Defaults to bittensor.Synapse().

  • timeout (float, optional) – The request timeout duration in seconds. Defaults to 12.0 seconds.

Returns:

If a single target axon is provided, returns the response from that axon. If multiple target axons are provided, returns a list of responses from all target axons.

Return type:

Union[bittensor.Synapse, List[bittensor.Synapse]]