Norman SDK

https://sdk.norman-ai.com
Admin
Norman SDK allows users to capture inputs from any device and instantly run AI models, simplifying...
Tokens:59,342
Snippets:485
Trust Score:4.9
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install Norman SDK (Python)

Source: https://sdk.norman-ai.com/intro-level/quick-start/quick-start

Installs the official Norman SDK for Python using pip. This is the first step to interacting with the Norman API programmatically.

```bash
pip install norman
```

--------------------------------

### Example Workflow: Upload, Verify, and Retrieve (Python)

Source: https://sdk.norman-ai.com/api/core/overviewcore/core

An example illustrating the integration of HttpClient, SocketClient, FilePush, and Retrieve for a complete file upload and validation process. It covers encrypted upload, completion notification, and retrieval of the stored asset.

```Python
from norman_core.clients.http_client import HttpClient
from norman_core.services.retrieve.retrieve import Retrieve
from norman_core.services.file_push.file_push import FilePush
from norman_core.clients.socket_client import SocketClient
from norman_core.types import ChecksumRequest

async def upload_and_verify(token, socket_info, file_path):
    # Upload file via encrypted socket
    async with open(file_path, "rb") as f:
        checksum = await SocketClient.write_and_digest(socket_info, f)
        print("Upload complete, checksum:", checksum)

    # Notify Norman backend to finalize upload
    checksum_request = ChecksumRequest(upload_id=socket_info.upload_id, checksum=checksum)
    await FilePush().complete_file_transfer(token, checksum_request)

    # Retrieve stored version for validation
    stream = await Retrieve().get_model_asset(token, "account_id", "model_id", "asset_id")
    async for chunk in stream:
        pass # Process chunk
```

--------------------------------

### Signup and Create an API Key

Source: https://sdk.norman-ai.com/intro-level/quick-start/quick-start

Sign up for an account and create an API key to authorize your SDK to securely access the Norman API. Store this key securely as it cannot be regenerated.

```APIDOC
## POST /signup

### Description
Creates a new account and generates an API key for authentication.

### Method
POST

### Endpoint
`/signup`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **username** (string) - Required - The account's username or email address.

### Request Example
```python
from norman import Norman

response = await Norman.signup("<username>")
```

### Response
#### Success Response (200)
- **account** (dict) - Account metadata.
  - **id** (str) - Unique account identifier.
  - **creation_time** (datetime) - Account creation timestamp (UTC).
  - **name** (str) - Account display name.
- **api_key** (str) - Generated API key for SDK authentication.

#### Response Example
```json
{
  "account": {
    "id": "23846818392186611174803470025142422015",
    "creation_time": "2025-11-09T14:22:17Z",
    "name": "Alice Johnson"
  },
  "api_key": "nrm_sk_2a96b7b1a9f44b09b7c3f9f1843e93e2"
}
```
```

--------------------------------

### Run First Model with Norman SDK (Python)

Source: https://sdk.norman-ai.com/intro-level/quick-start/quick-start

Shows how to initialize the Norman SDK with an API key and invoke a model. This snippet includes defining the model to run and its input data, then processing the binary output, such as an image.

```python
from norman import Norman
from io import BytesIO
from PIL import Image

# Initialize the SDK with your API key
norman = Norman(api_key="nrm_sk_2a96b7b1a9f44b09b7c3f9f1843e93e2")

# Define the invocation configuration
invocation_config = {
    "model_name": "image_reverser_model",
    "inputs": [
        {
            "display_title": "Input",
            "data": "/Users/alice/Desktop/sample_image.png"
        }
    ]
}

# Invoke the model
response = await norman.invoke(invocation_config)

# Accessing the Output
data = response["output_image"]

# Open and display the image
img = Image.open(BytesIO(data))
img.show(title="output_image - Memory")

# Optionally save it to disk
img.save("test_memory_output_image.png")
```

--------------------------------

### Signup and Create API Key (Python)

Source: https://sdk.norman-ai.com/intro-level/quick-start/quick-start

Demonstrates how to sign up for a new account and generate an API key using the Norman SDK. The API key is crucial for authenticating all subsequent requests to the Norman API. Ensure you store the key securely as it cannot be regenerated.

```python
from norman import Norman

response = await Norman.signup("<username>")
```

--------------------------------

### Invoke a Model

Source: https://sdk.norman-ai.com/intro-level/quick-start/quick-start

Invoke a specific model with provided inputs and configuration. The response contains the output data generated by the model.

```APIDOC
## POST /invoke

### Description
Invokes a specified model with given input data and returns the model's output.

### Method
POST

### Endpoint
`/invoke`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **invocation_config** (dict) - Required - Configuration for model invocation.
  - **model_name** (string) - Required - The name of the model to invoke.
  - **inputs** (list) - Required - A list of input data for the model.
    - **display_title** (string) - Required - A display name for the input.
    - **data** (string or bytes) - Required - The input data (e.g., file path, binary data).

### Request Example
```python
from norman import Norman

norman = Norman(api_key="nrm_sk_2a96b7b1a9f44b09b7c3f9f1843e93e2")

invocation_config = {
    "model_name": "image_reverser_model",
    "inputs": [
        {
            "display_title": "Input",
            "data": "/Users/alice/Desktop/sample_image.png"
        }
    ]
}

response = await norman.invoke(invocation_config)
```

### Response
#### Success Response (200)
- **output_image** (bytes) - Binary output data returned by the model. For image models, this contains image bytes; for text or audio models, it contains the corresponding binary data.

#### Response Example
```json
{
  "output_image": <bytes>  // binary data returned by the model
}
```

#### Accessing the Output
```python
from io import BytesIO
from PIL import Image

data = response["output_image"]

# Open and display the image
img = Image.open(BytesIO(data))
img.show(title="output_image - Memory")

# Optionally save it to disk
img.save("test_memory_output_image.png")
```
```

--------------------------------

### Invoke Norman AI

Source: https://sdk.norman-ai.com/model-details/smollm2-1-7b

Example of how to invoke a model using the Norman AI SDK, including model selection and input data.

```APIDOC
## Invoke Norman AI

### Description
This endpoint allows you to invoke a selected model within the Norman AI platform. You can specify the model name and provide input data, typically in a message format for conversational models.

### Method
`POST`

### Endpoint
`/invoke` (Assumed endpoint for SDK invocation)

### Parameters
#### Request Body
- **model_name** (string) - Required - The name of the model to invoke (e.g., "qwen3-4b", "SmolLM2-1.7B").
- **inputs** (array) - Required - A list of input objects.
  - **display_title** (string) - Required - A title for the input display.
  - **data** (array) - Required - The actual input data, often a list of message objects for chat models.
    - **role** (string) - Required - The role of the message sender (e.g., "system", "user", "assistant").
    - **content** (string) - Required - The content of the message.

### Request Example
```json
{
  "model_name": "qwen3-4b",
  "inputs": [
    {
      "display_title": "Prompt",
      "data": [
        {"role": "system", "content": "You are a helpful AI assistant."}, 
        {"role": "user", "content": "Can you provide ways to eat combinations of bananas and dragonfruits?"},
        {"role": "assistant", "content": "Sure! Here are some ways to eat bananas and dragonfruits together"},
        {"role": "user", "content": "What about solving an 2x + 3 = 7 equation?"}
      ]
    }
  ]
}
```

### Response
#### Success Response (200)
- **response** (object) - The model's generated response.
  - **data** (array) - The content of the response, typically a message object.
    - **role** (string) - The role of the sender of the response.
    - **content** (string) - The generated text content.
```

--------------------------------

### Invoke Norman AI with Stable Diffusion

Source: https://sdk.norman-ai.com/model-details/flux-1-dev

Demonstrates how to invoke the Norman AI service using the 'stable-diffusion-v1-5' model with a text prompt. This is a basic example of sending an image generation request.

```python
response = await norman.invoke(
{
"model_name": "stable-diffusion-v1-5",
"inputs": [
{
"display_title": "Prompt",
"data": "A cat playing with a ball on mars"
}
]
}
)
```

--------------------------------

### Invoke Norman AI with Phi-3-mini-4k-instruct

Source: https://sdk.norman-ai.com/model-details/phi-3-mini-4k-instruct

This Python snippet demonstrates how to invoke the Norman AI SDK with a specified model ('qwen3-4b' in this example) and provides input messages. The model is suitable for instruction-following tasks, reasoning, and evaluations where efficiency is important.

```python
messages = [
{"role": "system", "content": "You are a helpful AI assistant."},
{"role": "user", "content": "Can you provide ways to eat combinations of bananas and dragonfruits?"},
{"role": "assistant",
"content": "Sure! Here are some ways to eat bananas and dragonfruits together"},
{"role": "user", "content": "What about solving an 2x + 3 = 7 equation?"},
]
  

response = await norman.invoke(
{
"model_name": "qwen3-4b",
"inputs": [
{
"display_title": "Prompt",
"data": messages
}
]
}
)

```

--------------------------------

### HTTP Client Initialization and Usage (Python)

Source: https://sdk.norman-ai.com/api/core/http-client/clients

Demonstrates how to initialize and use the HttpClient as an asynchronous context manager for making HTTP requests. This ensures proper session lifecycle management and resource cleanup. It shows an example of fetching a list of models using a bearer token.

```python
async with HttpClient() as client:
    models = await client.get("models/list", token=my_token)
```

--------------------------------

### HTTP Client Usage (Python)

Source: https://sdk.norman-ai.com/api/core/overviewcore/core

Demonstrates how to use the HttpClient for making asynchronous GET requests. It handles connection pooling, retries, and automatic token injection. Supports various response types like JSON, Text, Bytes, and Iterators.

```Python
from norman_core.clients.http_client import HttpClient

async def make_request(my_token):
    async with HttpClient() as client:
        response = await client.get("persist/models/get", token=my_token)
        print(response)
```

--------------------------------

### Invoke Uploaded Model using Norman SDK

Source: https://sdk.norman-ai.com/intro-level/upload-your-first-model/quick-start

This Python code snippet shows how to invoke an uploaded model using the Norman SDK. It specifies the model name and provides the input data, which in this example is a file path to an image. This function requires the model to be already uploaded and deployed.

```python
response = await norman.invoke({
  "model_name": "image_reverser_model",
  "inputs": [
    {
      "display_title": "Input",
      "data": "/path/to/image.png"
    }
  ]
})
```

--------------------------------

### Invoke Phi-4-mini-instruct Model with Norman AI SDK

Source: https://sdk.norman-ai.com/model-details/phi-4-mini-instruct

This Python snippet shows how to use the Norman AI SDK to invoke the Phi-4-mini-instruct model. It constructs a list of messages, including system and user prompts, and then calls the `norman.invoke` method with the model name and input messages. Ensure the SDK is installed and configured before running.

```python
messages = [
{"role": "system", "content": "You are a helpful AI assistant."},
{"role": "user", "content": "Can you provide ways to eat combinations of bananas and dragonfruits?"},
{"role": "assistant",
"content": "Sure! Here are some ways to eat bananas and dragonfruits together"},
{"role": "user", "content": "What about solving an 2x + 3 = 7 equation?"},
]
  
response = await norman.invoke(
{
"model_name": "phi-4-mini-instruct",
"inputs": [
{
"display_title": "Prompt",
"data": messages
}
]
}
)

```

--------------------------------

### GET /endpoint

Source: https://sdk.norman-ai.com/api/core/http-client/clients

Sends an HTTP GET request to the specified endpoint. This method is a convenience wrapper for making GET requests and supports various response decoding options.

```APIDOC
## GET /endpoint

### Description
Send an HTTP GET request to the given endpoint. This is a convenience wrapper for `self.request("GET", endpoint, ...)`.

### Method
GET

### Endpoint
`/{endpoint}`

### Parameters
#### Path Parameters
* **endpoint** (str) - Required - API path relative to the base URL.

#### Query Parameters
* **params** (dict) - Optional - Query parameters for the request.
* **headers** (dict) - Optional - Extra headers to include in the request.
* **timeout** (float) - Optional - Request timeout in seconds.

#### Request Body
N/A

### Request Example
```python
async with HttpClient() as client:
    models = await client.get("models/list", token=my_token, params={'query': 'example'})
```

### Response
#### Success Response (200)
- **response** (dict or list or str or bytes or tuple) - Parsed response according to `response_encoding`. `Json` decodes to `dict` or `list`, `Text` to `str`, `Bytes` to `bytes`, and `Iterator` to `(headers, async iterator over bytes)`.

#### Response Example
```json
{
  "models": [
    {
      "id": "model-1",
      "name": "Example Model"
    }
  ]
}
```
```

--------------------------------

### GET /models

Source: https://sdk.norman-ai.com/api/core/http-client/clients

Send a generic HTTP GET request to retrieve a list of models.

```APIDOC
## GET /models

### Description
Send a generic HTTP GET request to retrieve a list of models or other resources.

### Method
GET

### Endpoint
`/models`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **params** (dict) - Optional - URL query parameters to filter or paginate the results.

#### Request Body
None

### Request Example
```python
# Example usage within an async context:
# async with HttpClient() as client:
#     response = await client.request("GET", "models", token=my_token)
```

### Response
#### Success Response (200)
- **response** (Any) - Decoded response object, typically a list of models if the endpoint is `/models`.

#### Response Example
```json
[
  {
    "id": "model_1",
    "name": "Model A"
  },
  {
    "id": "model_2",
    "name": "Model B"
  }
]
```
```

--------------------------------

### Get Models Request

Source: https://sdk.norman-ai.com/get-models-request/objects

Retrieves a list of models with optional filtering, sorting, and pagination.

```APIDOC
## GET /websites/sdk_norman-ai/models

### Description
Retrieves a list of models. This request allows clients to specify constraints such as filters, sorting, and pagination, as well as to optionally limit results to only models that are considered 'finished'.

### Method
GET

### Endpoint
/websites/sdk_norman-ai/models

### Parameters
#### Query Parameters
- **constraints** (QueryConstraints) - Optional - A structured query object controlling filtering, sorting, and pagination. If not provided, default retrieval behavior is applied.
- **finished_models** (boolean) - Optional - If true, limits results to models marked as fully processed or finalized. Defaults to false.

### Request Example
```json
{
  "constraints": {
    "filter": {
      "field": "status",
      "operator": "=",
      "value": "completed"
    },
    "sort": {
      "field": "created_at",
      "direction": "desc"
    },
    "pagination": {
      "page": 1,
      "pageSize": 10
    }
  },
  "finished_models": true
}
```

### Response
#### Success Response (200)
- **models** (array) - A list of model objects matching the query.
- **totalCount** (integer) - The total number of models available matching the query.

#### Response Example
```json
{
  "models": [
    {
      "id": "model_123",
      "name": "Example Model",
      "status": "completed",
      "created_at": "2023-10-27T10:00:00Z"
    }
  ],
  "totalCount": 50
}
```
```

--------------------------------

### GET /get_invocations

Source: https://sdk.norman-ai.com/api/core/invocations-service/persist

Retrieve invocation records that match the provided query constraints.

```APIDOC
## GET /get_invocations

### Description
Retrieve invocation records that match the provided query constraints.

### Method
GET

### Endpoint
/get_invocations

### Parameters
#### Query Parameters
- **token** (Sensitive[str]) - Required - Authentication token authorizing the request.
- **constraints** (Optional[QueryConstraints]) - Optional - Query object defining filters and pagination.

### Request Example
```json
{
  "token": "your_auth_token",
  "constraints": {
    "limit": 10,
    "offset": 0
  }
}
```

### Response
#### Success Response (200)
- **response** (dict[str, Invocation]) - Dictionary mapping invocation IDs to their corresponding `Invocation` objects.

#### Response Example
```json
{
  "response": {
    "inv_456": {
      "model_name": "another_model",
      "execution_count": 2,
      "invocation_id": "inv_456"
    }
  }
}
```
```

--------------------------------

### Signup and Generate Key

Source: https://sdk.norman-ai.com/api/authenticationmanager/authenticationmanager

Register a new account and generate an API key for the user. This is a static method as signup does not require an existing authenticated session.

```APIDOC
## Signup and Generate Key

### Description
Register a new account and generate an API key for the user.

### Method
POST

### Endpoint
/auth/signup

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **username** (str) - Required - Name to associate with the new account.

### Request Example
```json
{
  "username": "new_user"
}
```

### Response
#### Success Response (200)
- **SignupKeyResponse** (object) - Contains the generated API key and signup metadata.
  - **api_key** (str) - The newly generated API key.
  - **account_id** (str) - The ID of the newly created account.

#### Response Example
```json
{
  "api_key": "new_generated_api_key",
  "account_id": "acc_new_user_id"
}
```
```

--------------------------------

### Invoke Model

Source: https://sdk.norman-ai.com/model-details/flux-1-schnell

Example of how to invoke a model using the Norman AI SDK.

```APIDOC
## POST /invoke

### Description
Invokes a specified model with given inputs to generate content.

### Method
POST

### Endpoint
/invoke

### Parameters
#### Request Body
- **model_name** (string) - Required - The name of the model to invoke.
- **inputs** (array) - Required - An array of input objects for the model.
  - **display_title** (string) - Required - The display title for the input.
  - **data** (string) - Required - The actual input data.

### Request Example
```json
{
  "model_name": "stable-diffusion-v1-5",
  "inputs": [
    {
      "display_title": "Prompt",
      "data": "A cat playing with a ball on mars"
    }
  ]
}
```

### Response
#### Success Response (200)
- **response** (object) - The result of the model invocation. (Structure depends on the model)

#### Response Example
```json
{
  "response": "[...generated content...]"
}
```
```

--------------------------------

### Signup with Password

Source: https://sdk.norman-ai.com/api/core/signup1/authenticate

Registers a new account using a username and password.

```APIDOC
## POST /websites/sdk_norman-ai/signup_with_password

### Description
Register a new account using a username and password.

### Method
POST

### Endpoint
/websites/sdk_norman-ai/signup_with_password

### Parameters
#### Request Body
- **signup_request** (SignupPasswordRequest) - Required - Request object containing credentials for password-based signup.

### Request Example
```json
{
  "signup_request": {
    "username": "newuser",
    "password": "complex_password123"
  }
}
```

### Response
#### Success Response (200)
- **response** (Account) - The created account object returned upon successful signup.

#### Response Example
```json
{
  "account_id": "acc_13579",
  "username": "newuser",
  "created_at": "2025-01-01T10:10:00Z"
}
```
```

--------------------------------

### GET /get_invocation_history

Source: https://sdk.norman-ai.com/api/core/invocations-service/persist

Retrieve historical invocation records based on the provided query constraints.

```APIDOC
## GET /get_invocation_history

### Description
Retrieve historical invocation records based on the provided query constraints.

### Method
GET

### Endpoint
/get_invocation_history

### Parameters
#### Query Parameters
- **token** (Sensitive[str]) - Required - Authentication token authorizing the request.
- **constraints** (Optional[QueryConstraints]) - Optional - Query object for filtering historical invocations.

### Request Example
```json
{
  "token": "your_auth_token",
  "constraints": {
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-12-31T23:59:59Z"
  }
}
```

### Response
#### Success Response (200)
- **response** (dict[str, Invocation]) - Dictionary mapping invocation IDs to corresponding historical invocation objects.

#### Response Example
```json
{
  "response": {
    "inv_123": {
      "model_name": "example_model",
      "execution_count": 1,
      "invocation_id": "inv_123",
      "timestamp": "2024-05-15T10:30:00Z"
    }
  }
}
```
```

--------------------------------

### HttpClient Initialization and Usage

Source: https://sdk.norman-ai.com/api/core/http-client/clients

Demonstrates how to initialize and use the HttpClient, emphasizing the recommended async context manager pattern for proper resource management.

```APIDOC
## HttpClient Usage

### Description
The `HttpClient` class provides coroutine-based convenience methods for making HTTP requests. It is recommended to use it as an async context manager to ensure proper session lifecycle management and automatic cleanup.

### Method
Asynchronous Context Manager

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
async with HttpClient() as client:
    response = await client.get("persist/models/get", token=my_token)
    print(response)
```

### Response
#### Success Response
Depends on the `response_encoding` parameter used in the request method.

#### Response Example
```json
{
  "example": "response body"
}
```

## `open()` `async`

### Description
Opens an internal `httpx.AsyncClient` session if it's not already open. This is automatically handled when using the client as an async context manager.

### Method
`async`

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Typically called automatically by the context manager
await client.open()
```

### Response
N/A

## `close()` `async`

### Description
Closes the internal `httpx.AsyncClient` session. Raises an exception if called without a matching `open()` call. This is automatically handled when exiting the async context manager.

### Method
`async`

### Endpoint
N/A

### Parameters
N/A

### Request Example
```python
# Typically called automatically by the context manager
await client.close()
```

### Response
N/A
```

--------------------------------

### GET /websites/sdk_norman-ai/model_bases

Source: https://sdk.norman-ai.com/api/core/model-bases/persist

Retrieves all model bases that match the provided filtering constraints. Defaults to fetching all completed model bases if no request is provided.

```APIDOC
## GET /websites/sdk_norman-ai/model_bases

### Description
Retrieve all model bases that match the provided filtering constraints. If no request is provided, defaults to fetching all completed (`finished_models=True`) model bases.

### Method
GET

### Endpoint
/websites/sdk_norman-ai/model_bases

### Parameters
#### Query Parameters
- **token** (Sensitive[str]) - Required - Authentication token authorizing the request.
- **request** (Optional[GetModelsRequest]) - Optional - Filtering and pagination request specifying which models to retrieve.

### Response
#### Success Response (200)
- **response** (dict[str, ModelBase]) - Dictionary mapping model base IDs to corresponding `ModelBase` objects.

#### Response Example
```json
{
  "model_base_1_id": {
    "id": "model_base_1_id",
    "name": "Base Model Alpha",
    "version": "1.0.0",
    "description": "A foundational model for text generation.",
    "created_at": "2023-01-01T10:00:00Z",
    "updated_at": "2023-01-01T10:00:00Z"
  },
  "model_base_2_id": {
    "id": "model_base_2_id",
    "name": "Base Model Beta",
    "version": "2.0.0",
    "description": "An image generation foundational model.",
    "created_at": "2023-02-15T14:30:00Z",
    "updated_at": "2023-02-15T14:30:00Z"
  }
}
```
```

--------------------------------

### Signup with Email

Source: https://sdk.norman-ai.com/api/core/signup1/authenticate

Registers a new account using an email-based signup flow.

```APIDOC
## POST /websites/sdk_norman-ai/signup_with_email

### Description
Register a new account using an email-based signup flow.

### Method
POST

### Endpoint
/websites/sdk_norman-ai/signup_with_email

### Parameters
#### Request Body
- **signup_request** (SignupEmailRequest) - Required - Request object containing the email and optional display name.

### Request Example
```json
{
  "signup_request": {
    "email": "user@example.com",
    "display_name": "Jane Doe"
  }
}
```

### Response
#### Success Response (200)
- **response** (Account) - The created account metadata returned upon signup.

#### Response Example
```json
{
  "account_id": "acc_67890",
  "email": "user@example.com",
  "created_at": "2025-01-01T10:05:00Z"
}
```
```

--------------------------------

### GET /models

Source: https://sdk.norman-ai.com/api/core/models/persist

Retrieves model records that match the provided filtering constraints. This endpoint allows for fetching specific models or all completed models if no filters are applied.

```APIDOC
## GET /models

### Description
Retrieve model records that match the provided filtering constraints.

### Method
GET

### Endpoint
/models

### Parameters
#### Query Parameters
- **token** (Sensitive[str]) - Required - Authentication token authorizing the request.
- **request** (Optional[GetModelsRequest]) - Optional - Request object specifying filters and pagination. If not provided, defaults to fetching all completed (`finished_models=True`) models.

### Request Example
(No request body for GET, parameters are typically in query string or implicitly handled)

### Response
#### Success Response (200)
- **response** (dict[str, Model]) - Dictionary mapping model IDs to corresponding `Model` objects.

#### Response Example
```json
{
  "response": {
    "model456": {
      "model_id": "model456",
      "name": "Active Model",
      "version": "2.1",
      "status": "active"
    }
  }
}
```
```

--------------------------------

### User Signup

Source: https://sdk.norman-ai.com/api/apireference-norman

Creates a new Norman account and generates a unique API key for SDK authentication.

```APIDOC
## POST /signup

### Description
Create a new Norman account and generate a unique API key. This method registers a new user and returns their account details along with a freshly generated API key for SDK authentication.

### Method
POST

### Endpoint
/signup

### Parameters
#### Request Body
- **username** (str) - Required - The username or email address to register. Must be unique across the Norman platform.

### Response
#### Success Response (200)
- **account** (dict) - Metadata of the created account.
  - **id** (str) - Unique account identifier.
  - **creation_time** (datetime) - Account creation timestamp (UTC).
  - **name** (str) - Display name of the registered account.
- **api_key** (str) - The generated API key used for authenticating SDK requests.

#### Response Example
```json
{
    "account": {
        "id": "23846818392186611174803470025142422015",
        "creation_time": "2025-11-09T14:22:17Z",
        "name": "Alice Johnson"
    },
    "api_key": "nrm_sk_2a96b7b1a9f44b09b7c3f9f1843e93e2"
}
```

⚠️ **Important:** Store your API key securely. API keys **cannot be regenerated** - if you lose yours, you’ll need to create a new account.
```

--------------------------------

### Signup Default

Source: https://sdk.norman-ai.com/api/core/signup1/authenticate

Creates a default account and returns a LoginResponse for immediate authentication, typically used for temporary or anonymous sessions.

```APIDOC
## POST /websites/sdk_norman-ai/signup_default

### Description
Create a default account and receive a `LoginResponse` for immediate authentication.
This method is typically used for creating a temporary or anonymous account session.

### Method
POST

### Endpoint
/websites/sdk_norman-ai/signup_default

### Parameters
#### Request Body
_(none)_ - This method does not require input parameters.

### Response
#### Success Response (200)
- **response** (LoginResponse) - The authenticated session returned after successful signup.

#### Response Example
```json
{
  "session_token": "sess_xyz789",
  "expires_at": "2025-01-01T11:00:00Z"
}
```
```

--------------------------------

### Sign Up for Norman Account with Python

Source: https://sdk.norman-ai.com/api/apireference-norman

Creates a new Norman account and generates a unique API key. Requires a unique username. Returns a dictionary containing account metadata and the API key for SDK authentication. Store the API key securely as it cannot be regenerated.

```python
response = await Norman.signup("alice@example.com")
api_key = response["api_key"]
```

--------------------------------

### GET /download/metadata

Source: https://sdk.norman-ai.com/api/core/file-pull-service/file-pull

Retrieve metadata for a specific file download operation. This method returns download tracking details for inputs, outputs, or assets associated with the provided entity ID.

```APIDOC
## GET /download/metadata

### Description
Retrieve metadata for a specific file download operation. This method returns download tracking details for inputs, outputs, or assets associated with the provided entity ID.

### Method
GET

### Endpoint
/download/metadata

### Parameters
#### Query Parameters
- **token** (Sensitive[str]) - Required - Authentication token authorizing the request.
- **entity_id** (str) - Required - The unique identifier of the entity (input, output, or asset) whose download metadata should be retrieved.

### Response
#### Success Response (200)
- **response** (TrackedDownloadUnion) - Union type containing metadata for tracked downloads. Includes file size, creation time, type, and download URLs.

#### Response Example
```json
{
  "response": {
    "file_size": 1024,
    "creation_time": "2023-01-01T12:00:00Z",
    "type": "input",
    "download_urls": [
      "https://example.com/download/123"
    ]
  }
}
```
```

--------------------------------

### Signup and Generate Key

Source: https://sdk.norman-ai.com/api/core/signup1/authenticate

Registers a new account and generates an API key for authentication. The API key cannot be regenerated, so it must be stored securely.

```APIDOC
## POST /websites/sdk_norman-ai/signup_and_generate_key

### Description
Register a new account and generate an API key for authentication.

### Method
POST

### Endpoint
/websites/sdk_norman-ai/signup_and_generate_key

### Parameters
#### Request Body
- **signup_request** (SignupKeyRequest) - Required - Request object containing account details for key-based signup.

### Request Example
```json
{
  "signup_request": {
    "email": "user@example.com",
    "password": "secure_password",
    "display_name": "John Doe"
  }
}
```

### Response
#### Success Response (200)
- **response** (Account) - The created account metadata returned upon successful registration.

#### Response Example
```json
{
  "account_id": "acc_12345",
  "api_key": "sk_abcdef1234567890",
  "created_at": "2025-01-01T10:00:00Z"
}
```

> ⚠️ **Important:** Store the API key securely. API keys **cannot be regenerated** — losing it requires creating a new one.
```

--------------------------------

### Invoke Norman AI with a Model

Source: https://sdk.norman-ai.com/model-details/gemma-2-2b

Example of how to invoke the Norman AI service with a specified model and a list of messages.

```APIDOC
## POST /invoke

### Description
Invokes the Norman AI service with a specified model and a set of input messages to generate a response.

### Method
POST

### Endpoint
`/invoke`

### Request Body
- **model_name** (string) - Required - The name of the model to use for inference (e.g., "qwen3-4b", "gemma-2-2b").
- **inputs** (array) - Required - A list of input objects, each containing display information and data.
  - **display_title** (string) - Required - A title for the display of the input data.
  - **data** (array) - Required - The actual input data, typically a list of message objects for chat models.
    - **role** (string) - Required - The role of the message sender (e.g., "system", "user", "assistant").
    - **content** (string) - Required - The text content of the message.

### Request Example
```json
{
  "model_name": "qwen3-4b",
  "inputs": [
    {
      "display_title": "Prompt",
      "data": [
        {"role": "system", "content": "You are a helpful AI assistant.",},
        {"role": "user", "content": "Can you provide ways to eat combinations of bananas and dragonfruits?",},
        {"role": "assistant", "content": "Sure! Here are some ways to eat bananas and dragonfruits together",},
        {"role": "user", "content": "What about solving an 2x + 3 = 7 equation?",}
      ]
    }
  ]
}
```

### Response
#### Success Response (200)
- **response** (object) - The AI's generated response.
  - **...** (fields vary based on model output)

#### Response Example
```json
{
  "response": {
    "model_name": "qwen3-4b",
    "output": {
      "display_title": "Response",
      "data": [
        {"role": "assistant", "content": "To solve the equation 2x + 3 = 7, you first subtract 3 from both sides: 2x = 7 - 3, which simplifies to 2x = 4. Then, you divide both sides by 2: x = 4 / 2, so x = 2."} 
      ]
    }
  }
}
```
```

--------------------------------

### GET /status-flags

Source: https://sdk.norman-ai.com/api/core/status-flags/persist

Retrieve status flags matching the specified query constraints. This method fetches one or more collections of status flags from the persistence layer, grouped by their associated entity identifiers.

```APIDOC
## GET /status-flags

### Description
Retrieve status flags matching the specified query constraints. This method fetches one or more collections of status flags from the persistence layer, grouped by their associated entity identifiers.

### Method
GET

### Endpoint
/status-flags

### Parameters
#### Query Parameters
- **token** (Sensitive[str]) - Required - Authentication token authorizing the request.
- **constraints** (Optional[QueryConstraints]) - Optional - Optional query object for filtering or pagination.

### Response
#### Success Response (200)
- **response** (dict[str, list[StatusFlag]]) - Dictionary mapping entity IDs to a list of `StatusFlag` objects.

#### Response Example
```json
{
  "entity_id_1": [
    {
      "flag_name": "operational",
      "status": "active",
      "timestamp": "2023-10-27T10:00:00Z"
    },
    {
      "flag_name": "health",
      "status": "healthy",
      "timestamp": "2023-10-27T10:00:05Z"
    }
  ],
  "entity_id_2": [
    {
      "flag_name": "runtime",
      "status": "running",
      "timestamp": "2023-10-27T10:01:00Z"
    }
  ]
}
```
```

--------------------------------

### Signup Key Request

Source: https://sdk.norman-ai.com/signup/objects

Handles signup requests for creating an account that authenticates strictly via API key. Ideal for machine-to-machine or programmatic access.

```APIDOC
## POST /signup/key

### Description
Signup request for creating an account that will authenticate strictly via API key. This flow is typically used for machine-to-machine or programmatic access scenarios.

### Method
POST

### Endpoint
/signup/key

### Parameters
#### Request Body
- **device_id** (Optional[str]) - Optional - Inherited from SignupRequest. Device identifier.
- **name** (str) - Required - Display name or identifier for the new account.

### Request Example
```json
{
  "device_id": "optional_device_id_456",
  "name": "Machine Account"
}
```

### Response
#### Success Response (200)
- **message** (str) - Confirmation message of successful signup.
- **api_key** (str) - The generated API key for authentication.

#### Response Example
```json
{
  "message": "Signup successful. Your API key is:",
  "api_key": "sk_test_your_generated_api_key"
}
```
```

--------------------------------

### Get Notifications

Source: https://sdk.norman-ai.com/api/core/notifications/persist

Retrieve notifications that match the provided query constraints. This method fetches user, system, or model-related notifications from the Norman persistence layer, ordered and filtered according to the specified constraints.

```APIDOC
## GET /websites/sdk_norman-ai/notifications

### Description
Retrieve notifications that match the provided query constraints. This method fetches user, system, or model-related notifications from the Norman persistence layer, ordered and filtered according to the specified constraints.

### Method
GET

### Endpoint
/websites/sdk_norman-ai/notifications

### Parameters
#### Query Parameters
- **token** (Sensitive[str]) - Required - Authentication token authorizing the request.
- **constraints** (Optional[QueryConstraints]) - Optional - Optional query object for filtering, sorting, or limiting results.

### Response
#### Success Response (200)
- **response** (List[Notification]) - A list of `Notification` objects matching the query.

#### Response Example
{
  "response": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "timestamp": "2024-01-01T12:00:00Z",
      "type": "SYSTEM_ALERT",
      "message": "System maintenance scheduled."
    }
  ]
}
```

--------------------------------

### Initialize and Invoke Image Model with Norman SDK

Source: https://sdk.norman-ai.com/intro-level/run-your-first-model/quick-start

This Python code snippet shows how to initialize the Norman SDK with an API key, configure an image model invocation with an input file path, and then asynchronously invoke the model. The response contains the processed image as raw bytes.

```python
from norman import Norman

# Initialize the SDK with your API key
norman = Norman(api_key="nrm_sk_2a96b7b1a9f44b09b7c3f9f1843e93e2")

# Define the invocation configuration
invocation_config = {
  "model_name": "image_reverser_model",
  "inputs": [
    {
      "display_title": "Input",
      "data": "/Users/alice/Desktop/sample_image.png"
    }
  ]
}

# Invoke the model
response = await norman.invoke(invocation_config)
```

--------------------------------

### Configure and Upload Model using Python

Source: https://sdk.norman-ai.com/api/apireference-norman

This Python snippet shows how to define a model configuration, including its name, version, descriptions, assets, inputs, and outputs. It then uses the Norman SDK to upload this model configuration.

```python
model_config = {
"name": "image_reverser_model",
"version_label": "beta",
"model_class": "image",
"short_description": "A simple model that mirrors images.",
"long_description": "Demonstrates image reversal for onboarding.",
"assets": [
{"asset_name": "weights", "data": "./model.pt"}
],
"inputs": [
{
"display_title": "Input Image",
"data_modality": "image",
"data_domain": "image",
"data_encoding": "png",
"receive_format": "File",
"parameters": [{"parameter_name": "image", "data_encoding": "png"}]
}
],
"outputs": [
{
"display_title": "Output Image",
"data_modality": "image",
"data_domain": "image",
"data_encoding": "png",
"receive_format": "File",
"parameters": [{"parameter_name": "mirror_image", "data_encoding": "png"}]
}
]
}
  

norman = Norman(api_key="nrm_sk_...")
model = await norman.upload_model(model_config)
print("Model uploaded successfully:", model.name)
```

--------------------------------

### DotSyntaxResolver - get Method

Source: https://sdk.norman-ai.com/dotsyntaxresolver/utils

Retrieves a nested value from a parent object using a dot and bracket notation key. This method supports various nested structures like dictionaries, lists, tuples, and object attributes.

```APIDOC
## GET /resolve/nested

### Description
Retrieve a nested value using dot + bracket syntax such as `"a.b[2].c"`. Supports dicts, lists, tuples, and object attributes. Raises `KeyError` or `IndexError` if a segment is invalid.

### Method
GET

### Endpoint
`/resolve/nested`

#### Query Parameters
- **parent** (object) - Required - The root object from which resolution begins. May be a dictionary, list, tuple, or any object supporting attribute access.
- **key** (str) - Required - Dot + bracket–notation path used to navigate into the nested structure.

### Response
#### Success Response (200)
- **resolved_value** (object) - The resolved nested value. Type depends on the structure.

#### Response Example
```json
{
  "resolved_value": "example_value"
}
```
```

--------------------------------

### Define Image Model Configuration for Upload

Source: https://sdk.norman-ai.com/intro-level/upload-your-first-model/quick-start

This Python dictionary defines the configuration for an image reversal model to be uploaded to Norman. It includes model metadata, asset details, and input/output specifications for image files. Ensure that the asset path points to your model file (e.g., './model.pt') and the data encodings match your image format (e.g., 'png').

```python
model_config = {
  "name": "image_reverser_model",
  "version_label": "beta",
  "short_description": "A simple model that mirrors images.",
  "long_description": "Demonstrates image reversal for onboarding.",
  "assets": [
    {"asset_name": "weights", "data": "./model.pt"}
  ],
  "inputs": [
    {
      "display_title": "Input Image",
      "data_encoding": "png",
      "receive_format": "File",
      "parameters": [
        {"parameter_name": "image", "data_encoding": "png"}
      ]
    }
  ],
  "outputs": [
    {
      "display_title": "Output Image",
      "data_encoding": "png",
      "receive_format": "File",
      "parameters": [
        {"parameter_name": "mirror_image", "data_encoding": "png"}
      ]
    }
  ]
}
```
Tokens:
Raw