# Sessions

## Session & SessionManager

In subnets that support **client access** (e.g., for inference or external applications), the `Session` and `SessionManager` classes form the foundation of **client-to-node communication**.

They abstract away routing, retries, and authorization logic — allowing external users or services to interact with the subnet as a consumer.

***

#### `Session`: Stateful Interaction with a Peer Node

The `Session` class represents a **single communication session with a remote subnet node**, typically a hoster that performs inference or another application-level task.

**Key Responsibilities:**

* Selects a node from the routing manager
* Authenticates and connects via the selected protocol (e.g., `MockProtocol`)
* Calls `rpc_*` methods, like `rpc_inference_stream`
* Handles retries, failures, and fallback logic
* Yields responses asynchronously (e.g., streaming outputs)

**Highlights:**

```python
session = Session(remote_manager, authorizer)

async for tensor in session.run_protocol_task(prompt, tensor):
    # use streamed inference output
```

* Automatically retries on failure
* Uses `RemoteManager` to keep a dynamic list of available nodes
* Allows custom authorization via `AuthorizerBase`
* Streams data using `AsyncIterator` (e.g., token-by-token inference)

***

#### `SessionManager`: Lightweight Factory

The `SessionManager` is a **stateless factory** that produces `Session` objects on demand via a context manager.

**Why It Exists:**

* Cleanly manages the lifecycle of a session
* Automatically handles session closure (`await session.close()`)
* Supports `async with` syntax for resource management

**Example Usage:**

```python
session_manager = SessionManager(remote_manager, authorizer)

async with session_manager.session() as session:
    async for tensor in session.run_protocol_task(prompt, tensor):
        # process inference stream
```

> 🔒 The `SessionManager` does **not** track session history or state across sessions — it simply builds isolated `Session` objects as needed.

***

#### 🔐 Built-in Features

| Feature           | Session                     | SessionManager           |
| ----------------- | --------------------------- | ------------------------ |
| Node routing      | ✅ via `RemoteManager`       | 🔁 passed in             |
| Retry logic       | ✅ automatic retries         | –                        |
| Auth integration  | ✅ optional `AuthorizerBase` | passed down              |
| Streaming support | ✅ async tensor stream       | –                        |
| Resource cleanup  | ✅ `close()` method          | ✅ via context manager    |
| Stateless reuse   | –                           | ✅ creates fresh sessions |

***

#### Summary

| Class            | Purpose                                           |
| ---------------- | ------------------------------------------------- |
| `Session`        | A single, stateful interaction with a chosen node |
| `SessionManager` | A lightweight factory that spawns new sessions    |

Together, they allow clients to interact with the subnet in a clean, secure, and fault-tolerant way — ideal for inference requests, chat interfaces, or real-time applications.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hypertensor.org/subnet-template/client/sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.