# SDK

The [NetMind Python API Library](https://pypi.org/project/netmind/) is the official Python client for [NetMind](https://www.netmind.ai/)'s API platform, providing a convenient way for interacting with the REST APIs and enables easy integrations with Python 3.10+ applications with easy to use synchronous and asynchronous clients.

## Installation

To install NetMind Python Library from PyPI, simply run:

```
pip install --upgrade netmind
```

### Setting up API Key

> You will need to create an account with [NetMind.ai](https://www.netmind.ai/) to obtain a NetMind API Key.

Once logged in to the NetMind Playground, you can find available API keys in [Dashboard](https://www.netmind.ai/user/dashboard).

#### **Setting environment variable**

```
export NETMIND_API_KEY=<your_netmind_api_key>
```

#### **Using the client**

```
from netmind import NetMind


client = NetMind(api_key="your_netmind_api_key")
```

This repo contains both a Python Library and a CLI. We'll demonstrate how to use both below.

## Usage – Python Client

### Chat Completions

> **👉 Supports plain text and multi-modal messages.** **Use `content` array with `type: "text"` and `type: "image_url"` for image input.**

```
from netmind import NetMind


client = NetMind()


# Simple text message
response = client.chat.completions.create(
    model="Qwen/Qwen3-8B",
    messages=[
        {"role": "system", "content": "Act like you are a helpful assistant."},
        {"role": "user", "content": "Hi there!"},
    ],
    max_tokens = 512
)
print(response.choices[0].message.content)

# Multi-modal message with text and image
response = client.chat.completions.create(
    model="doubao/Doubao-1.5-vision-pro",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What's in this image?"
            },
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://huggingface.co/datasets/patrickvonplaten/random_img/resolve/main/yosemite.png"
                }
            }
        ]
    }]
)
print(response.choices[0].message.content)
```

The chat completions API supports three types of content:

* Plain text messages using the `content` field directly
* Multi-modal messages with images using `type: "image_url"`

When using multi-modal content, the `content` field becomes an array of content objects, each with its own type and corresponding data.

#### **Streaming**

> **👉 Use `stream=True` for incremental, real-time responses.**

```
from netmind import NetMind


client = NetMind()
stream = client.chat.completions.create(
    model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
    messages=[
        {"role": "system", "content": "Act like you are a helpful assistant."},
        {"role": "user", "content": "Hi there!"},
    ],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)
```

#### **Async usage**

> **👉 Use the `AsyncNetMind` class for asynchronous environments.** **All async methods require `await` and work well with frameworks like FastAPI.**

```
import asyncio
from netmind import AsyncNetMind


async_client = AsyncNetMind()


async def async_chat_completion():
    response = await async_client.chat.completions.create(
        model="meta-llama/Llama-4-Scout-17B-16E-Instruct",
        messages=[
            {"role": "system", "content": "Act like you are a helpful assistant."},
            {"role": "user", "content": "Hi there!"},
        ]
    )
    print(response.choices[0].message.content)


asyncio.run(async_chat_completion())
```

### Embeddings

> **👉 Supports list inputs and returns embeddings for each entry.**

```
from netmind import NetMind

client = NetMind()


response = client.embeddings.create(
    model="nvidia/NV-Embed-v2",
    input=["Hello world", "NetMind is awesome!"]
)
print(len(response.data[0].embedding))
```

#### **Async usage**

```
import asyncio
from netmind import AsyncNetMind


async_client = AsyncNetMind()


async def async_embeddings():
    response = await async_client.embeddings.create(
        model="nvidia/NV-Embed-v2",
        input=["Hello world", "NetMind is awesome!"]
    )
    print(len(response.data[0].embedding))
asyncio.run(async_embeddings())
```

### Files

> **👉 Required for async file-based operations like `aparse()`.** **Upload local files to get a downloadable URL via `client.files.create()`.**

```
from netmind import NetMind
from netmind.types.files import FilePurpose


client = NetMind()


# Upload a file
file_response = client.files.create(
    file="path/to/your/file.jsonl",
    purpose=FilePurpose.inference
)
print(f"File uploaded with ID: {file_response.id}")

# List files
files = client.files.list()
print("files found:", len(files))
print("files id:", files[0].id)


file_id = "your_file_id_here"
# Retrieve a file
file = client.files.retrieve(file_id)  
print(file)

# Retrieve download url for a file
download_url = client.files.retrieve_url(file_id)
print("Download URL:", download_url.presigned_url)


# Delete a file
client.files.delete(file_id)
```

#### **Async usag**

```
import asyncio
from netmind import AsyncNetMind
from netmind.types.files import FilePurpose


async_client = AsyncNetMind()


async def async_file_operations():
    # Upload a file
    file_response = await async_client.files.create(
        file="path/to/your/file.jsonl",
        purpose=FilePurpose.fine_tune
    )
    print(f"File uploaded with ID: {file_response.id}")

    # List files
    files = await async_client.files.list()
    print("files found:", len(files.data))

    file_id = "your_file_id_here"
    # Retrieve a file
    file = await async_client.files.retrieve(file_id)  
    print(file)

    # Retrieve download url for a file
    download_url = await async_client.files.retrieve_url(file_id)
    print("Download URL:", download_url.presigned_url)

    # Delete a file
    await async_client.files.delete(file_id)

asyncio.run(async_file_operations())
```

### ParsePro

> **✅ Sync method `parse()` supports both local files and URLs.**

```
from netmind import NetMind


client = NetMind()


result = client.parse_pro.parse('http://tmpfiles.org/dl/2267856/test.pdf', 'json')
print(result)
result = client.parse_pro.parse('/path/to/test.pdf', 'markdown')
print(result)
```

#### **Async Task usage**

> **⚠️ Async parsing requires a public URL. Local files must be uploaded first.** **Use `client.files.create()` to generate a usable URL.**

```
from netmind import NetMind
import time


client = NetMind()

# task = client.parse_pro.parse('/path/to/test.pdf', 'markdown')
task = client.parse_pro.aparse('http://tmpfiles.org/dl/2267856/test.pdf', 'json')
print(task.task_id, task.status)

time.sleep(10)

result = client.parse_pro.aresult(task.task_id)
print(result.status, result.data)
```

#### **ParsePro Async usage**

```
from netmind import AsyncNetMind
import asyncio


client = AsyncNetMind()


async def main():
    # task = client.parse_pro.parse('/path/to/test.pdf', 'json')
    task = await client.parse_pro.aparse('http://tmpfiles.org/dl/2267856/test.pdf', 'markdown')
    print(task.task_id, task.status)

    await asyncio.sleep(10)

    result = await client.parse_pro.aresult(task.task_id)
    print(result.status, result.data)


asyncio.run(main())
```

> **ℹ️ Notes**
>
> * ✅ `parse()` (sync) supports **both URLs and local files**.
> * ⚠️ `aparse()` and all **async parsing** require a **public URL** – **local files must be uploaded first**.
> * ✅ Use `client.files.create()` to upload files and get a downloadable URL.
> * 🧠 Async clients (`AsyncNetMind`) are ideal for integration into event loops or async workflows.
> * 🎯 Multi-modal chat input must use structured `content` arrays.

### Code interpreter

#### **simple usage**

```python
from netmind import NetMind
from netmind.types.code_interpreter import CodeInterpreterCodeRequest, CodeInterpreterCodeFile


client = NetMind()

SAMPLE_CODE_REQUEST = CodeInterpreterCodeRequest(
    language="python",
    files=[
        CodeInterpreterCodeFile(
            name="main.py",
            content="print('Hello, World!')\nprint(2 + 2)\nresult = 5 * 3\nprint(f'Result: {result}')"
        )
    ]
)
run_response = client.code_interpreter.run(SAMPLE_CODE_REQUEST)
print(run_response.run.stdout)
```

#### **file usage**

```python
from netmind import NetMind
from netmind.types.code_interpreter import CodeInterpreterCodeRequest, CodeInterpreterCodeFile

client = NetMind()

upload_response = client.files.create(purpose="code-interpreter", file='temp.json')

SAMPLE_CODE_REQUEST = CodeInterpreterCodeRequest(
    language="python",
    files=[
        CodeInterpreterCodeFile(
            name="main.py",
            content="import json\nimport sys\n\ndef main():\n    filename = \"temp.json\"\n    try:\n        with open(filename, \"r\", encoding=\"utf-8\") as f:\n            data = json.load(f)  # PARSE JSON\n    except FileNotFoundError:\n        print(f\"error：'{filename}'\", file=sys.stderr)\n        sys.exit(1)\n    except json.JSONDecodeError as e:\n        print(f\"error：{e}\", file=sys.stderr)\n        sys.exit(1)\n\n    # original Python object\n    print(\"READ:\")\n    print(data)\n\n    #Print JSON 文本\n    print(\"\\nJSON Content：\")\n    pretty = json.dumps(data, ensure_ascii=False, indent=2)\n    print(pretty)\n\nif __name__ == \"__main__\":\n    main()"
        )
    ],
    file_id_usage=[upload_response.id]
)
run_response = client.code_interpreter.run(SAMPLE_CODE_REQUEST)
print(run_response.run.stdout)
```

#### **generate picture**

```python
from netmind import NetMind
from netmind.types.code_interpreter import CodeInterpreterCodeRequest, CodeInterpreterCodeFile

client = NetMind()

SAMPLE_CODE_REQUEST = CodeInterpreterCodeRequest(
    language="python",
    files=[
        CodeInterpreterCodeFile(
            name="main.py",
            content="from PIL import Image, ImageDraw\n\n# Create RGB Picture，200x100 \nimg = Image.new('RGB', (200, 100), color = 'white')\nd = ImageDraw.Draw(img)\nd.text((10, 40), 'Hello, PNG!', fill=(0, 0, 0))\n\n# save as PNG\nimg.save('output.png')"
        )
    ]
)
run_response = client.code_interpreter.run(SAMPLE_CODE_REQUEST)

download_url = client.files.retrieve_url(run_response.run.data.id)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://netmind-power.gitbook.io/netmind-power-documentation/api/sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.