Metadata-Version: 2.4
Name: neuralhive
Version: 1.0.1
Summary: NeuralHive Python SDK for model access and inference
Author-email: Muhammad Khazq <mrkhaziq.dev@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://neuralhive.ai
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: mypy>=1.19.1; extra == "dev"
Dynamic: license-file

# NeuralHive SDK

Python SDK client for NeuralHive model access.

## Installation

```bash
pip install neuralhive
```

## Authentication Setup

### Option 1: Configure once (recommended)

```bash
neuralhive configure --api-key nh_live_your_api_key
```

Then use SDK without passing key in code.

### Option 2: Environment variable

```bash
export NEURALHIVE_API_KEY="nh_live_your_api_key"
```

### Option 3: Pass key directly in code

```python
client = Client("nh_live_your_api_key")
```

## Quick Start

```python
from neuralhive import Client

client = Client()
models = client.list_models()
print(models)
```

## Usage

### 1. List models

```python
from neuralhive import Client

client = Client("nh_live_your_api_key")
models = client.list_models()
```

### 2. Get model details

```python
model = client.get_model("your_model_id")
print(model)
```

### 3. Run model inference

```python
from neuralhive import Client

client = Client("nh_live_your_api_key")

result = client.detect(
    model_id="your_object_detection_model_id",
    image="<base64_image>",
)
```

For all other methods, see **API Reference** below.

## API Reference

### `Client(api_key: str | None = None)`

| Parameter | Type  | Required | Description             |
| --------- | ----- | -------- | ----------------------- |
| `api_key` | `str` | No       | Your NeuralHive API key |

Returns:

- `Client` instance

Notes:
- Authentication is validated automatically on first API call.
- Production recommendation: avoid hardcoded API keys in source code.

### `client.list_models()`

Parameters:

- None

Returns:

- `list[dict]` containing allowed models for this API key

### `client.get_model(model_id)`

| Parameter  | Type  | Required | Description             |
| ---------- | ----- | -------- | ----------------------- |
| `model_id` | `str` | Yes      | Target model identifier |

Returns:

- `dict` with model details

### `client.detect(model_id, image, prompt=None)`

| Parameter  | Type  | Required | Description                                 |
| ---------- | ----- | -------- | ------------------------------------------- |
| `model_id` | `str` | Yes      | Target model identifier                     |
| `image`    | `str` | Yes      | Base64 image input                          |
| `prompt`   | `str` | No       | Optional prompt (required for SAM-like IDs) |

Returns:

- `dict`

### `client.segment(model_id, image, prompt=None)`

| Parameter  | Type  | Required | Description                                 |
| ---------- | ----- | -------- | ------------------------------------------- |
| `model_id` | `str` | Yes      | Target model identifier                     |
| `image`    | `str` | Yes      | Base64 image input                          |
| `prompt`   | `str` | No       | Optional prompt (required for SAM-like IDs) |

Returns:

- `dict`

### `client.recognize(model_id, image)`

| Parameter  | Type  | Required | Description             |
| ---------- | ----- | -------- | ----------------------- |
| `model_id` | `str` | Yes      | Target model identifier |
| `image`    | `str` | Yes      | Base64 image input      |

Returns:

- `list[float]` (face embeddings)

### `client.reidentify(model_id, image)`

| Parameter  | Type  | Required | Description             |
| ---------- | ----- | -------- | ----------------------- |
| `model_id` | `str` | Yes      | Target model identifier |
| `image`    | `str` | Yes      | Base64 image input      |

Returns:

- `dict`

### `client.estimate_pose(model_id, image)`

| Parameter  | Type  | Required | Description             |
| ---------- | ----- | -------- | ----------------------- |
| `model_id` | `str` | Yes      | Target model identifier |
| `image`    | `str` | Yes      | Base64 image input      |

Returns:

- `dict`

### `client.embed(model_id, text=None, image=None)`

| Parameter  | Type  | Required | Description                                        |
| ---------- | ----- | -------- | -------------------------------------------------- |
| `model_id` | `str` | Yes      | Target model identifier                            |
| `text`     | `str` | No       | Text input                                         |
| `image`    | `str` | No       | Base64 image input                                 |

Notes:

- Exactly one input is required: `text` or `image`

Returns:

- `list[float]` or `list[list[float]]`

### `client.generate_text(model_id, prompt, image=None, images=None, videos=None)`

| Parameter  | Type                 | Required | Description                           |
| ---------- | -------------------- | -------- | ------------------------------------- |
| `model_id` | `str`                | Yes      | Target model identifier               |
| `prompt`   | `str`                | Yes      | Text prompt                           |
| `image`    | `str`                | No       | Single base64 image                   |
| `images`   | `str` or `list[str]` | No       | Base64 image(s)                       |
| `videos`   | `str` or `list[str]` | No       | Video URL(s) or base64 video input(s) |

Returns:

- `str`

### `client.analyze(model_id, text=None, images=None, videos=None)`

| Parameter  | Type                 | Required | Description                           |
| ---------- | -------------------- | -------- | ------------------------------------- |
| `model_id` | `str`                | Yes      | Target model identifier               |
| `text`     | `str`                | No       | Text input                            |
| `images`   | `str` or `list[str]` | No       | Base64 image(s)                       |
| `videos`   | `str` or `list[str]` | No       | Video URL(s) or base64 video input(s) |

Notes:

- At least one input is required: `text` or `images` or `videos`

Returns:

- `str`

### `client.generate_image(model_id, prompt)`

| Parameter  | Type  | Required | Description             |
| ---------- | ----- | -------- | ----------------------- |
| `model_id` | `str` | Yes      | Target model identifier |
| `prompt`   | `str` | Yes      | Text prompt             |

Returns:

- `str` (generated image URL, empty string if unavailable)

### `client.generate_3d(model_id, image=None, prompt=None)`

| Parameter  | Type  | Required | Description                                |
| ---------- | ----- | -------- | ------------------------------------------ |
| `model_id` | `str` | Yes      | Target model identifier                    |
| `image`    | `str` | No       | Base64 image input                         |
| `prompt`   | `str` | No       | Optional prompt input                      |

Notes:

- Provide at least one input: `image` or `prompt`

Returns:

- `str` (3D asset URL, empty string if unavailable)

## Input Validation

- `model_id` is required for all inference methods.
- `task_type` is never required from user.
- `image` and `images` must be base64-encoded strings when provided.
- Unsupported fields for selected model are rejected before request dispatch.
- Missing required fields for selected model are rejected before request dispatch.

## Contract

Frozen contract file is included in repository.
