neuralhive 1.0.1__tar.gz

neuralhive-1.0.1/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) Altrova
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neuralhive-1.0.1/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include src/neuralhive *.py
+prune tests
+prune docs
+prune .github
+global-exclude __pycache__ *.py[cod]

neuralhive-1.0.1/PKG-INFO

@@ -0,0 +1,270 @@
+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.

neuralhive-1.0.1/README.md

@@ -0,0 +1,253 @@
+# 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.

neuralhive-1.0.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neuralhive"
+version = "1.0.1"
+authors = [
+  { name="Muhammad Khazq", email="mrkhaziq.dev@gmail.com" },
+]
+description = "NeuralHive Python SDK for model access and inference"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+  "requests>=2.31.0",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[project.optional-dependencies]
+dev = [
+  "mypy>=1.19.1",
+]
+
+[project.urls]
+Homepage = "https://neuralhive.ai"
+
+[project.scripts]
+neuralhive = "neuralhive.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["neuralhive*"]
+
+[tool.mypy]
+python_version = "3.9"
+files = ["src"]
+pretty = true
+show_error_codes = true
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+no_implicit_optional = true
+check_untyped_defs = true
+strict_equality = true

neuralhive-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

neuralhive-1.0.1/src/neuralhive/__init__.py

@@ -0,0 +1,8 @@
+from .client import Client
+
+__all__ = ["Client"]
+
+# Keep package root surface minimal (Client-only).
+for _private_name in ("clip_embeddings", "object_detection", "person_reid", "text_embeddings", "slm", "sam3", "face_recognition", "face_detection", "three_d_asset_generation", "pose_estimation", "instance_segmentation", "vlm", "models"):
+    globals().pop(_private_name, None)
+del _private_name