> For the complete documentation index, see [llms.txt](https://docs.hypertensor.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hypertensor.org/subnet-template/client/sessions.md).

# 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.