Metadata-Version: 2.4
Name: neuralhive
Version: 1.1.9
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
Requires-Dist: questionary>=2.1.0
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)
```

## Finetune

### Start finetuning

- Run `neuralhive finetune`.
- Select a task, model, and dataset.
- Review the final cost and start training.

### Dataset requirements

- For `slm`, provide a file path.
- For other finetune tasks, provide a directory path.
- You can save a local dataset for future use.

### Track progress

- Run `neuralhive trainings`.
- View active training names and progress.
- You can leave training running in the background.

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

### `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, system_prompt=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) |
| `system_prompt` | `str`              | No       | Optional system prompt for SLM models |

Notes:

- If `model_id` is not provided, SDK uses default `vlm` model from your allowed models.
- `system_prompt` is only sent when the selected model is an `slm` model.

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.read_text(file_path, export_to=None)`

| Parameter   | Type  | Required | Description                                       |
| ----------- | ----- | -------- | ------------------------------------------------- |
| `file_path` | `str` | Yes      | Local document file path                          |
| `export_to` | `str` | No       | Export directory path for the resulting text file |

Returns:

- `str`
- Without `export_to`: signed URL for the generated `.txt` file
- With `export_to`: saved local file path

### `client.detect_layout(file_path, export_to=None)`

| Parameter   | Type  | Required | Description                                         |
| ----------- | ----- | -------- | --------------------------------------------------- |
| `file_path` | `str` | Yes      | Local document file path                            |
| `export_to` | `str` | No       | Export directory path for the resulting layout file |

Returns:

- `str`
- Without `export_to`: signed URL for the generated result file
- With `export_to`: saved local file path

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