Metadata-Version: 2.4
Name: neuralhive
Version: 1.1.5
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.33.1
Requires-Dist: Pillow>=12.2.0
Requires-Dist: typing_extensions>=4.12.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. Get model details

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

### 2. Run model inference

```python
from neuralhive import Client

client = Client()

result = client.detect(
    image_path="/absolute/path/to/image.jpg",
)
```

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(image_path, model_id=None, prompt=None, export_to=None)`

| Parameter  | Type  | Required | Description                                 |
| ---------- | ----- | -------- | ------------------------------------------- |
| `image_path`    | `str` | Yes      | Local image file path                          |
| `model_id` | `str` | No       | Target model identifier                     |
| `prompt`   | `str` | No       | Optional prompt (required for SAM-like IDs) |
| `export_to` | `str` | No       | Export directory path for box-rendered image |

Notes:

- If `model_id` is not provided, SDK uses default `object_detection` model from your allowed models.

Returns:

- `dict`

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

| Parameter  | Type  | Required | Description                                 |
| ---------- | ----- | -------- | ------------------------------------------- |
| `image_path`    | `str` | Yes      | Local image file path                          |
| `model_id` | `str` | No       | Target model identifier                     |
| `prompt`   | `str` | No       | Optional prompt (required for SAM-like IDs) |
| `export_to` | `str` | No       | Export directory path for mask-rendered image |

Returns:

- `dict`

Notes:

- If `model_id` is not provided, SDK uses default `instance_segmentation` model from your allowed models.

### `client.detect_and_segment(image_path, prompt, export_to=None)`

| Parameter | Type  | Required | Description        |
| --------- | ----- | -------- | ------------------ |
| `image_path`   | `str` | Yes      | Local image file path |
| `prompt`  | `str` | Yes      | Segmentation prompt |
| `export_to` | `str` | No       | Export directory path for mask+box-rendered image |

Notes:

- Uses SAM3 / prompt-based segmentation models.

Returns:

- `dict`

### `client.recognize(image_path)`

| Parameter  | Type  | Required | Description             |
| ---------- | ----- | -------- | ----------------------- |
| `image_path`    | `str` | Yes      | Local image file path      |

Returns:

- `list[list[float]]` (face embeddings per detected face)

### `client.reidentify(image_path, model_id=None)`

| Parameter  | Type  | Required | Description             |
| ---------- | ----- | -------- | ----------------------- |
| `image_path`    | `str` | Yes      | Local image file path      |
| `model_id` | `str` | No       | Target model identifier |

Returns:

- `dict`

### `client.estimate_pose(image_path, export_to=None)`

| Parameter   | Type  | Required | Description                                |
| ----------- | ----- | -------- | ------------------------------------------ |
| `image_path`     | `str` | Yes      | Local image file path                         |
| `export_to` | `str` | No       | Export directory path for pose-rendered image |

Returns:

- `dict` with:
- `keypoints`: `list[object]`
- `scores`: `list[object]`
- `saved_path`: `str | None`

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

| Parameter  | Type  | Required | Description             |
| ---------- | ----- | -------- | ----------------------- |
| `text`     | `str` | No       | Text input              |
| `image_path`    | `str` | No       | Local image file path      |
| `model_id` | `str` | No       | Target model identifier |

Notes:

- Exactly one input is required: `text` or `image_path`
- If `model_id` is not provided, SDK uses the default `clip` model from your allowed models.

Returns:

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

### `client.generate_text(prompt, model_id=None, image_paths=None, video_paths=None)`

| Parameter  | Type                 | Required | Description                           |
| ---------- | -------------------- | -------- | ------------------------------------- |
| `prompt`   | `str`                | Yes      | Text prompt                           |
| `model_id` | `str`                | No       | Target model identifier               |
| `image_paths`   | `str` or `list[str]` | No       | Local image file path(s)                |
| `video_paths`   | `str` or `list[str]` | No       | Local video path(s) or public URL(s) |

Notes:

- If `model_id` is not provided, SDK uses default `vlm` model from your allowed models.

Returns:

- `str`

### `client.analyze(text=None, image_paths=None, video_paths=None)`

| Parameter  | Type                 | Required | Description                           |
| ---------- | -------------------- | -------- | ------------------------------------- |
| `text`     | `str`                | No       | Text input                            |
| `image_paths`   | `str` or `list[str]` | No       | Local image file path(s)                |
| `video_paths`   | `str` or `list[str]` | No       | Local video path(s) or public URL(s) |

Notes:

- At least one input is required: `text` or `image_paths` or `video_paths`

Returns:

- `str`

### `client.generate_image(prompt, export_to=None)`

| Parameter   | Type  | Required | Description                                              |
| ----------- | ----- | -------- | -------------------------------------------------------- |
| `prompt`    | `str` | Yes      | Text prompt                                              |
| `export_to` | `str` | No       | Export directory path (filename comes from response URL) |

Returns:

- `dict` with:
- `download_url`: `str`
- `saved_path`: `str | None`

### `client.edit_image(image_path, prompt, export_to=None)`

| Parameter   | Type  | Required | Description                                              |
| ----------- | ----- | -------- | -------------------------------------------------------- |
| `image_path` | `str` | Yes      | Local image file path                                    |
| `prompt`    | `str` | Yes      | Text instruction for the edit                            |
| `export_to` | `str` | No       | Export directory path (filename comes from response URL) |

Returns:

- `dict` with:
- `download_url`: `str`
- `saved_path`: `str | None`

### `client.transcribe_audio(audio_path)`

| Parameter    | Type  | Required | Description           |
| ------------ | ----- | -------- | --------------------- |
| `audio_path` | `str` | Yes      | Local audio file path |

Returns:

- `str`

### `client.generate_3d(image_path, export_to=None)`

| Parameter   | Type  | Required | Description                                              |
| ----------- | ----- | -------- | -------------------------------------------------------- |
| `image_path`     | `str` | Yes      | Local image file path                                       |
| `export_to` | `str` | No       | Export directory path (filename comes from response URL) |

Returns:

- `dict` with:
- `download_url`: `str`
- `saved_path`: `str | None`
