> This page is for version v0.25.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.

# nemoguardrails.http

Transport-neutral asynchronous HTTP clients for NeMo Guardrails integrations.

## Submodules

* **[`nemoguardrails.http.client`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/client)**
* **[`nemoguardrails.http.composition`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/composition)**
* **[`nemoguardrails.http.errors`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/errors)**
* **[`nemoguardrails.http.instrumented`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/instrumented)**
* **[`nemoguardrails.http.request`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/request)**
* **[`nemoguardrails.http.retry`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/retry)**
* **[`nemoguardrails.http.runtime`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/runtime)**
* **[`nemoguardrails.http.telemetry`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/telemetry)**
* **[`nemoguardrails.http.transport`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/transport)**
* **[`nemoguardrails.http.types`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types)**

## Package Contents

### Classes

| Name                                                                                 | Description                                                                |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| [`ClosableHTTPClient`](#nemoguardrails-http-client-ClosableHTTPClient)               | An HTTP client that exposes asynchronous resource cleanup.                 |
| [`HTTPClient`](#nemoguardrails-http-client-HTTPClient)                               | Send asynchronous HTTP requests without exposing transport-specific types. |
| [`HTTPClientError`](#nemoguardrails-http-errors-HTTPClientError)                     | Base class for outbound HTTP failures.                                     |
| [`HTTPConnectionError`](#nemoguardrails-http-errors-HTTPConnectionError)             | Raised when the transport cannot establish or maintain a connection.       |
| [`HTTPRequest`](#nemoguardrails-http-types-HTTPRequest)                              | Describe an outbound HTTP request without transport-specific objects.      |
| [`HTTPResponse`](#nemoguardrails-http-types-HTTPResponse)                            | A materialized, transport-neutral HTTP response.                           |
| [`HTTPResponseDecodeError`](#nemoguardrails-http-errors-HTTPResponseDecodeError)     | Raised when a response body cannot be decoded as JSON.                     |
| [`HTTPStatusError`](#nemoguardrails-http-errors-HTTPStatusError)                     | Raised for an unsuccessful HTTP status.                                    |
| [`HTTPTLSConfig`](#nemoguardrails-http-types-HTTPTLSConfig)                          | Configure TLS verification and optional mutual authentication.             |
| [`HTTPTimeoutError`](#nemoguardrails-http-errors-HTTPTimeoutError)                   | Raised when an outbound request exceeds its total timeout.                 |
| [`HttpxHTTPClient`](#nemoguardrails-http-transport-HttpxHTTPClient)                  | Adapt an HTTPX asynchronous client to the neutral HTTP contract.           |
| [`InstrumentedHTTPClient`](#nemoguardrails-http-instrumented-InstrumentedHTTPClient) | Decorate an HTTP client with privacy-safe tracing and metrics.             |
| [`RetryPolicy`](#nemoguardrails-http-retry-RetryPolicy)                              | Configure bounded retries for an HTTP client.                              |
| [`RetryingHTTPClient`](#nemoguardrails-http-retry-RetryingHTTPClient)                | Apply a retry policy around another transport-neutral HTTP client.         |

### Functions

| Name                                                                                 | Description                                                            |
| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| [`create_http_client`](#nemoguardrails-http-runtime-create_http_client)              | Create a transport-neutral HTTP client with optional retry behavior.   |
| [`http_call`](#nemoguardrails-http-request-http_call)                                | Execute one outbound HTTP request with deterministic client ownership. |
| [`instrument_http_client`](#nemoguardrails-http-instrumented-instrument_http_client) | Return `client` decorated with the requested HTTP telemetry.           |

### API

```python
class nemoguardrails.http.ClosableHTTPClient()
```

Protocol

**Bases:** [HTTPClient](#nemoguardrails-http-client-HTTPClient)

An HTTP client that exposes asynchronous resource cleanup.

```python
nemoguardrails.http.ClosableHTTPClient.close() -> None
```

async

Release resources owned by the client.

Implementations must make repeated calls safe.

```python
class nemoguardrails.http.HTTPClient()
```

Protocol

Send asynchronous HTTP requests without exposing transport-specific types.

```python
nemoguardrails.http.HTTPClient.request(
    method: str,
    url: str,
    headers: typing.Mapping[str, str] | None = None,
    params: typing.Mapping[str, typing.Any] | None = None,
    json: typing.Any = None,
    content: bytes | str | None = None,
    timeout: float | None = None
) -> nemoguardrails.http.types.HTTPResponse
```

async

Send one request and return a response whose content is fully owned.

**Parameters:**

**`method`** `str`

HTTP method, case-insensitive.

---

**`url`** `str`

Absolute request URL.

---

**`headers`** `Mapping[str, str] | None` — default: None

Optional request headers.

---

**`params`** `Mapping[str, Any] | None` — default: None

Optional query parameters.

---

**`json`** `Any` — default: None

Optional JSON-serializable request body.

---

**`content`** `bytes | str | None` — default: None

Optional raw request body.

---

**`timeout`** `float | None` — default: None

Optional total request timeout in seconds.

---

**Returns:** [`HTTPResponse`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types#nemoguardrails-http-types-HTTPResponse)

A transport-neutral response containing materialized body bytes.

```python
class nemoguardrails.http.HTTPClientError(
    args: object = ()
)
```

Exception

**Bases:** `Exception`

Base class for outbound HTTP failures.

`retry_count` records how many retries completed before the error was
returned to the caller.

**`retry_count`** `= 0`

---

```python
class nemoguardrails.http.HTTPConnectionError()
```

**Bases:** [HTTPClientError](#nemoguardrails-http-errors-HTTPClientError)

Raised when the transport cannot establish or maintain a connection.

```python
class nemoguardrails.http.HTTPRequest(
    method: str,
    url: str,
    headers: typing.Mapping[str, str] | None = None,
    params: typing.Mapping[str, typing.Any] | None = None,
    json: typing.Any = None,
    content: bytes | str | None = None,
    timeout: float | None = None
)
```

Dataclass

Describe an outbound HTTP request without transport-specific objects.

The value is suitable for status-error context and deterministic test
assertions. It does not perform a request itself.

**`content`** `bytes | str | None = None`

---

**`headers`** `Mapping[str, str] | None = None`

---

**`method`** `str`

---

**`params`** `Mapping[str, Any] | None = None`

---

**`timeout`** `float | None = None`

---

**`url`** `str`

---

```python
class nemoguardrails.http.HTTPResponse(
    status_code: int,
    headers: typing.Mapping[str, str] = dict(),
    content: bytes = b'',
    extensions: typing.Mapping[str, typing.Any] = dict()
)
```

Dataclass

A materialized, transport-neutral HTTP response.

`content` owns the response bytes, so callers can decode the body after
the transport or client context has closed. `extensions` carries optional
non-portable metadata without changing the core contract.

**`content`** `bytes = b''`

---

**`extensions`** `Mapping[str, Any] = field(default_factory=dict)`

---

**`headers`** `Mapping[str, str] = field(default_factory=dict)`

---

**`is_success`** `bool`

Return whether the status code is in the 2xx range.

---

**`status_code`** `int`

---

**`text`** `str`

Decode the response body using its declared charset or UTF-8.

---

```python
nemoguardrails.http.HTTPResponse.json() -> typing.Any
```

Decode the response body as JSON.

**Raises:**

* `HTTPResponseDecodeError`: If the body is not valid JSON.

```python
nemoguardrails.http.HTTPResponse.raise_for_status(
    request: nemoguardrails.http.types.HTTPRequest | None = None
) -> None
```

Raise `HTTPStatusError` for status codes of 400 or greater.

```python
class nemoguardrails.http.HTTPResponseDecodeError(
    response: nemoguardrails.http.types.HTTPResponse
)
```

**Bases:** [HTTPClientError](#nemoguardrails-http-errors-HTTPClientError)

Raised when a response body cannot be decoded as JSON.

```python
class nemoguardrails.http.HTTPStatusError(
    response: nemoguardrails.http.types.HTTPResponse,
    request: nemoguardrails.http.types.HTTPRequest | None = None
)
```

**Bases:** [HTTPClientError](#nemoguardrails-http-errors-HTTPClientError)

Raised for an unsuccessful HTTP status.

**`retry_count`** `= retry_count if isinstance(retry_count, int) else 0`

---

```python
class nemoguardrails.http.HTTPTLSConfig(
    verify: bool = True,
    ca_bundle: str | None = None,
    client_certificate: str | None = None,
    client_key: str | None = None
)
```

Dataclass

Configure TLS verification and optional mutual authentication.

A custom CA bundle applies only when verification is enabled. Client
certificate and key paths must be supplied together.

**`ca_bundle`** `str | None = None`

---

**`client_certificate`** `str | None = None`

---

**`client_key`** `str | None = None`

---

**`verify`** `bool = True`

---

```python
nemoguardrails.http.HTTPTLSConfig.__post_init__() -> None
```

```python
class nemoguardrails.http.HTTPTimeoutError()
```

**Bases:** [HTTPClientError](#nemoguardrails-http-errors-HTTPClientError)

Raised when an outbound request exceeds its total timeout.

```python
class nemoguardrails.http.HttpxHTTPClient(
    client: httpx.AsyncClient | None = None,
    timeout: float | None = _DEFAULT_TIMEOUT_SECONDS,
    limits: httpx.Limits | None = None,
    follow_redirects: bool = False,
    tls: nemoguardrails.http.types.HTTPTLSConfig | None = None
)
```

Adapt an HTTPX asynchronous client to the neutral HTTP contract.

A client created by this adapter is owned and closed by the adapter. An
injected client remains owned by its caller. The configured timeout covers
the complete request rather than each HTTPX timeout phase independently.

**`_client`**

---

**`_close_task`** `Task[None] | None = None`

---

**`_owns_client`** `= client is None`

---

**`_timeout`** `= timeout if self._owns_client else None`

---

```python
nemoguardrails.http.HttpxHTTPClient.__aenter__() -> nemoguardrails.http.transport.HttpxHTTPClient
```

async

Return this client from an asynchronous context manager.

```python
nemoguardrails.http.HttpxHTTPClient.__aexit__(
    exc_type: object,
    exc_value: object,
    traceback: object
) -> None
```

async

Close owned resources when leaving an asynchronous context.

```python
nemoguardrails.http.HttpxHTTPClient.close() -> None
```

async

Close owned resources, retaining unfinished cleanup for another call.

Caller cancellation leaves the transport close running; later calls
await the same attempt. A failed close remains failed because HTTPX may
already have discarded partially closed connection state.

```python
nemoguardrails.http.HttpxHTTPClient.request(
    method: str,
    url: str,
    headers: typing.Mapping[str, str] | None = None,
    params: typing.Mapping[str, typing.Any] | None = None,
    json: typing.Any = None,
    content: bytes | str | None = None,
    timeout: float | None = None
) -> nemoguardrails.http.types.HTTPResponse
```

async

Send one request and materialize the HTTPX response.

**Parameters:**

**`method`** `str`

HTTP method.

---

**`url`** `str`

Absolute request URL.

---

**`headers`** `Mapping[str, str] | None` — default: None

Optional request headers.

---

**`params`** `Mapping[str, Any] | None` — default: None

Optional query parameters.

---

**`json`** `Any` — default: None

Optional JSON-serializable request body.

---

**`content`** `bytes | str | None` — default: None

Optional raw request body.

---

**`timeout`** `float | None` — default: None

Optional per-request total timeout in seconds.

---

**Returns:** [`HTTPResponse`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types#nemoguardrails-http-types-HTTPResponse)

A neutral response containing copied headers and body bytes.

**Raises:**

* `HTTPTimeoutError`: If the request exceeds its total timeout.
* `HTTPConnectionError`: If HTTPX reports a request failure.
* `ValueError`: If the per-request timeout is not positive.

```python
class nemoguardrails.http.InstrumentedHTTPClient(
    client: nemoguardrails.http.client.HTTPClient,
    tracer: opentelemetry.trace.Tracer | None,
    metrics_enabled: bool = False
)
```

Decorate an HTTP client with privacy-safe tracing and metrics.

The decorator preserves request behavior and client ownership. Wrapping an
existing `InstrumentedHTTPClient` is idempotent, and tracing and metrics
can be enabled independently.

**`_close_lock`** `= asyncio.Lock()`

---

**`wrapped_client`** `HTTPClient`

Return the underlying client for direct access or re-instrumentation.

---

```python
nemoguardrails.http.InstrumentedHTTPClient.__new__(
    client: nemoguardrails.http.client.HTTPClient,
    args: typing.Any = (),
    kwargs: typing.Any = {}
)
```

Return an existing instrumented client without wrapping it again.

```python
nemoguardrails.http.InstrumentedHTTPClient._with_wrapped_client(
    client: nemoguardrails.http.client.HTTPClient
) -> nemoguardrails.http.instrumented.InstrumentedHTTPClient
```

Apply the current instrumentation settings to another client.

```python
nemoguardrails.http.InstrumentedHTTPClient.close() -> None
```

async

Close the wrapped client without taking ownership from its caller.

Repeated calls are safe. A failed or cancelled close remains retryable.

```python
nemoguardrails.http.InstrumentedHTTPClient.request(
    method: str,
    url: str,
    headers: typing.Mapping[str, str] | None = None,
    params: typing.Mapping[str, typing.Any] | None = None,
    json: typing.Any = None,
    content: bytes | str | None = None,
    timeout: float | None = None
) -> nemoguardrails.http.types.HTTPResponse
```

async

Forward one request while recording privacy-safe HTTP telemetry.

Telemetry includes the method, sanitized URL, payload sizes, response
status, and retry count. Header, query, body, and credential values are
never recorded.

```python
class nemoguardrails.http.RetryPolicy(
    max_attempts: int = 3,
    retryable_methods: frozenset[str] = (lambda: frozenset({'DELETE...,
    retryable_status_codes: frozenset[int] = (lambda: frozenset({408, 40...,
    initial_delay: float = 0.5,
    max_delay: float = 8.0,
    max_retry_after: float = 60.0,
    retry_transport_errors: bool = True,
    honor_retry_override_header: bool = False,
    clamp_retry_after: bool = False
)
```

Dataclass

Configure bounded retries for an HTTP client.

`max_attempts` includes the initial request. Methods are normalized to
uppercase, and POST is intentionally absent from the safe default set.
`Retry-After` values are honored only when they fall within
`max_retry_after` unless clamping is explicitly enabled. Vendor override
headers are ignored unless `honor_retry_override_header` is enabled.

**`clamp_retry_after`** `bool = False`

---

**`honor_retry_override_header`** `bool = False`

---

**`initial_delay`** `float = 0.5`

---

**`max_attempts`** `int = 3`

---

**`max_delay`** `float = 8.0`

---

**`max_retry_after`** `float = 60.0`

---

**`retry_transport_errors`** `bool = True`

---

**`retryable_methods`** `frozenset[str]`

---

**`retryable_status_codes`** `frozenset[int]`

---

```python
nemoguardrails.http.RetryPolicy.__post_init__() -> None
```

```python
nemoguardrails.http.RetryPolicy.can_retry_method(
    method: str
) -> bool
```

Return whether the policy permits retrying the HTTP method.

```python
nemoguardrails.http.RetryPolicy.retry_after(
    response: nemoguardrails.http.types.HTTPResponse,
    now: datetime.datetime
) -> float | None
```

Return a usable `Retry-After` delay in seconds.

Both delta-seconds and HTTP-date values are supported. Invalid or
out-of-policy values return `None` so the client uses exponential
backoff instead.

```python
nemoguardrails.http.RetryPolicy.should_retry(
    response: nemoguardrails.http.types.HTTPResponse
) -> bool
```

Return whether a response status or opted-in override requests a retry.

```python
class nemoguardrails.http.RetryingHTTPClient(
    client: nemoguardrails.http.client.HTTPClient,
    policy: nemoguardrails.http.retry.RetryPolicy | None = None,
    sleep: collections.abc.Callable[[float], collections.abc.Awaitable[None]] = asyncio.sleep,
    random_value: collections.abc.Callable[[], float] = random.random,
    now: collections.abc.Callable[[], datetime.datetime] | None = None
)
```

Apply a retry policy around another transport-neutral HTTP client.

Closing this wrapper closes the wrapped client only when it implements
`ClosableHTTPClient`.

**`_now`** `= now or (lambda: datetime.now(timezone.utc))`

---

**`_policy`** `= policy or RetryPolicy()`

---

**`wrapped_client`** `HTTPClient`

Return the underlying client.

---

```python
nemoguardrails.http.RetryingHTTPClient.__aenter__() -> nemoguardrails.http.retry.RetryingHTTPClient
```

async

Return this client from an asynchronous context manager.

```python
nemoguardrails.http.RetryingHTTPClient.__aexit__(
    exc_type: object,
    exc_value: object,
    traceback: object
) -> None
```

async

Close wrapped resources when leaving an asynchronous context.

```python
nemoguardrails.http.RetryingHTTPClient._backoff(
    retries: int
) -> float
```

```python
nemoguardrails.http.RetryingHTTPClient._with_wrapped_client(
    client: nemoguardrails.http.client.HTTPClient
) -> nemoguardrails.http.retry.RetryingHTTPClient
```

Apply the current retry settings to another client.

```python
nemoguardrails.http.RetryingHTTPClient.close() -> None
```

async

Close the wrapped closable client at most once.

```python
nemoguardrails.http.RetryingHTTPClient.request(
    method: str,
    url: str,
    headers: typing.Mapping[str, str] | None = None,
    params: typing.Mapping[str, typing.Any] | None = None,
    json: typing.Any = None,
    content: bytes | str | None = None,
    timeout: float | None = None
) -> nemoguardrails.http.types.HTTPResponse
```

async

Send a request and retry eligible failures within policy bounds.

The returned response includes `retry_count` in its extensions.
Transport errors also expose their completed retry count before being
re-raised.

```python
nemoguardrails.http.create_http_client(
    httpx_client: httpx.AsyncClient | None = None,
    timeout: float | None = 30.0,
    limits: httpx.Limits | None = None,
    retry_policy: nemoguardrails.http.retry.RetryPolicy | None = None,
    follow_redirects: bool = False,
    tls: nemoguardrails.http.types.HTTPTLSConfig | None = None
) -> nemoguardrails.http.client.ClosableHTTPClient
```

Create a transport-neutral HTTP client with optional retry behavior.

When `httpx_client` is provided, it remains caller-owned and `timeout`,
`limits`, `follow_redirects`, and `tls` must retain their defaults.
`retry_policy` is still applied when supplied.

**Parameters:**

**`httpx_client`** `httpx.AsyncClient | None` — default: None

Optional caller-owned HTTPX client.

---

**`timeout`** `float | None` — default: 30.0

Total timeout for a client created by this function.

---

**`limits`** `httpx.Limits | None` — default: None

Connection-pool limits for a client created by this function.

---

**`retry_policy`** `RetryPolicy | None` — default: None

[`RetryPolicy`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/retry#nemoguardrails-http-retry-RetryPolicy) `| None` — Optional policy applied to created or injected clients.

---

**`follow_redirects`** `bool` — default: False

Whether a client created by this function follows
redirects.

---

**`tls`** `HTTPTLSConfig | None` — default: None

[`HTTPTLSConfig`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types#nemoguardrails-http-types-HTTPTLSConfig) `| None` — TLS settings for a client created by this function.

---

**Returns:** [`ClosableHTTPClient`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/client#nemoguardrails-http-client-ClosableHTTPClient)

A closable transport-neutral HTTP client.

**Raises:**

* `ValueError`: If non-default owned-client options are supplied with an
  injected client.

```python
nemoguardrails.http.http_call(
    client: nemoguardrails.http.client.HTTPClient | None,
    method: str,
    url: str,
    headers: typing.Mapping[str, str] | None = None,
    params: typing.Mapping[str, typing.Any] | None = None,
    json: typing.Any = None,
    content: bytes | str | None = None,
    timeout: float | None = None,
    raise_for_status: bool = True,
    factory: collections.abc.Callable[[], nemoguardrails.http.client.ClosableHTTPClient] = create_http_client
) -> nemoguardrails.http.types.HTTPResponse
```

async

Execute one outbound HTTP request with deterministic client ownership.

**Parameters:**

**`client`** `HTTPClient | None`

[`HTTPClient`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/client#nemoguardrails-http-client-HTTPClient) `| None` — Optional caller-owned client. When omitted, `factory` creates
a client that is closed after the request.

---

**`method`** `str`

HTTP method.

---

**`url`** `str`

Absolute request URL.

---

**`headers`** `Mapping[str, str] | None` — default: None

Optional request headers.

---

**`params`** `Mapping[str, Any] | None` — default: None

Optional query parameters.

---

**`json`** `Any` — default: None

Optional JSON-serializable request body.

---

**`content`** `bytes | str | None` — default: None

Optional raw request body.

---

**`timeout`** `float | None` — default: None

Optional total request timeout in seconds.

---

**`raise_for_status`** `bool` — default: True

Whether responses with status 400 or greater raise.

---

**`factory`** `Callable[[], ClosableHTTPClient]` — default: create_http_client

`Callable[[],` [`ClosableHTTPClient`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/client#nemoguardrails-http-client-ClosableHTTPClient) `]` — Factory for an owned client when `client` is omitted.

---

**Returns:** [`HTTPResponse`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/http/types#nemoguardrails-http-types-HTTPResponse)

The materialized transport-neutral response.

**Raises:**

* `HTTPStatusError`: If `raise_for_status` is enabled and the response
  status is 400 or greater.
* `TypeError`: If `factory` returns a client that cannot be closed.

```python
nemoguardrails.http.instrument_http_client(
    client: nemoguardrails.http.client.HTTPClient,
    tracer: opentelemetry.trace.Tracer | None = None,
    metrics_enabled: bool = False
) -> nemoguardrails.http.client.HTTPClient
```

Return `client` decorated with the requested HTTP telemetry.

The original client is returned when telemetry is disabled or the client is
already instrumented.