Metadata-Version: 2.5
Name: hyperfluid
Version: 0.1.0
Summary: Hyperfluid API client
Project-URL: Repository, https://github.com/nudibranches-tech/sdks
Project-URL: Homepage, https://hyperfluid.cloud
Author-email: Nudibranches <contact@nudibranches.tech>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: mypy>=1.18; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff==0.14.10; extra == 'dev'
Description-Content-Type: text/markdown

# Hyperfluid Python SDK

Hyperfluid API client

## Installation

```sh
pip install hyperfluid
```

Python 3.10 or newer. The SDK depends on `httpx` only and is fully typed. Every method of the API
is listed in [api.md](api.md).

## Usage

```python
from uuid import UUID
from hyperfluid import Hyperfluid

client = Hyperfluid(api_key="your-api-key", base_url="https://api.example.com")

client.ai_agents.list(UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"))
```

Without `api_key`, the client reads `HYPERFLUID_API_KEY`, and `HYPERFLUID_BASE_URL`
overrides the default base URL (required, or `base_url=`, when the API has none). Every argument
is a keyword argument. The constructor also takes `base_url`, `timeout`,
`max_retries`, `default_headers`, `http_client` (an `httpx.Client` of yours), `middleware`, and
the credentials the API accepts (`token_provider`, `basic_auth`, `api_keys`). Close the client,
or use it as a context manager, to release its connections.

`AsyncHyperfluid` has the same resources for asyncio:

```python
from uuid import UUID
from hyperfluid import AsyncHyperfluid

async with AsyncHyperfluid() as client:
    await client.ai_agents.list(UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"))
```

## Requests

The fields of a JSON or form request body are keyword arguments, next to the query and header
parameters; path parameters come first:

```python
client.ai_agents.ask(UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"), UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"), question="question")
```

An optional argument left out is not sent; `None` sends `null` where the API accepts it. An enum
argument takes the enum or its value as a string. Other bodies (lists, unions, files) are one
`body` argument.

Every method also takes, for that request only, `extra_headers=`, `extra_query=`, `extra_body=`
(merged into the body), `timeout=` and `max_retries=`. These headers, like `default_headers`, win
over the client's credentials.

## Models

Models are keyword-only dataclasses with `from_dict`/`to_dict`. In models requests send, an
optional field that accepts `null` defaults to `UNSET` (from `hyperfluid.models`): it is
left out of the request, while `None` sends `null`; in response models it is simply `None` when
absent. A field holding a string or an object, such as an expandable id, is typed `str | Model`.
A discriminated union is the union of its variant models (`Circle | Square | UnknownVariant`),
decoded into the variant the tag names; when its variants share fields, it is a model holding the
discriminator and the variant, and passing `content=` alone fills in the tag.

Properties the API added after this SDK was generated are kept in `extra_fields` (and read
as attributes at runtime), and sent back when the model is serialized. A property named
after a model member, such as `extra_fields` or `to_dict`, gets a trailing `_`.

## Streaming

Server-sent events are iterated as they arrive. When the API documents the JSON of each
event, the stream yields models, until a `[DONE]` event; `stream.last_event` is the raw
event (`event`, `data`, `id`) of the latest one:

```python
with client.airflows.list_logs(UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"), UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6")) as stream:
    for event in stream:
        print(event)
```

Other streams yield `SseEvent`s.

Multipart bodies take `Upload(content, filename, content_type)` files, and binary bodies bytes or
file objects.

## Raw responses

Prefix a call with `with_raw_response` for the HTTP response next to the decoded result:

```python
response = client.with_raw_response.ai_agents.list(UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"))
print(response.status_code, response.headers, response.request_id)
result = response.parse()
```

## Errors

Every error derives from `HyperfluidError`. A non-2xx response raises an `APIStatusError`
subclass named after its status (`BadRequestError`, `AuthenticationError`,
`PermissionDeniedError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError`,
`RateLimitError`, `InternalServerError`), whose `body` is the error response decoded into its
schema (its JSON when the API declares none) and `request_id` the id to quote to support.

```python
from hyperfluid import APIConnectionError, APITimeoutError, NotFoundError

try:
    client.ai_agents.list(UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"))
except NotFoundError as error:
    print(error.status_code, error.request_id, error.body)
except APITimeoutError:
    ...  # the request timed out, after retries
except APIConnectionError:
    ...  # no response, after retries
```

A successful response that does not decode raises `APIResponseValidationError`.

## Retries and timeouts

Connection errors, timeouts, 408, 429 and 5xx responses are retried twice with exponential
backoff, honoring `Retry-After`, when replaying the request is safe: for idempotent methods
and requests with an `Idempotency-Key` header, which every POST gets. Requests time out after
60 seconds.

```python
client = Hyperfluid(base_url="https://api.example.com", max_retries=5, timeout=20.0)
client.with_options(max_retries=0).ai_agents.list(UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"))
client.ai_agents.list(UUID("3fa85f64-5717-4562-b3fc-2c963f66afa6"), timeout=5.0, max_retries=0)  # for one call
```

## Middleware

`middleware=[...]` wraps every HTTP attempt: a callable receiving the `httpx.Request` and
`next`, returning an `httpx.Response`, to cache, log or sign requests.

_Generated by [perseid](https://github.com/meteroid-oss/perseid)._
