Client

Overview

The Client class is the main entry point for all interactions with the Noxus AI platform. It handles authentication, request management, and provides access to all SDK resources including workflows, conversations, knowledge bases, and agents.

Basic Initialization

The simplest way to create a client:

from noxus_sdk.client import Client

client = Client(api_key="your_api_key_here")

Configuration Options

The client supports several configuration options for different use cases:

client = Client(
    api_key="your_api_key_here",
    base_url="https://backend.noxus.ai",  # Custom backend URL
    load_nodes=True,                      # Load available node types
    load_me=True,                         # Load user information
    extra_headers={"Custom-Header": "value"}  # Additional headers
)

string

required

Your Noxus API key for authentication

string

default:"https://backend.noxus.ai"

The base URL of the Noxus backend. Can also be set via NOXUS_BACKEND_URL environment variable

boolean

default:"true"

Whether to automatically load available workflow node types on initialization

boolean

default:"true"

Whether to load user information and check admin permissions

dict

default:"None"

Additional HTTP headers to include with all requests

Environment Variables

The client respects these environment variables:

NOXUS_BACKEND_URL

Override the default backend URL

export NOXUS_BACKEND_URL="https://your-custom-backend.com"

NOXUS_API_KEY

Set your API key (though passing it directly is recommended)

export NOXUS_API_KEY="your_api_key_here"

Resource Access

The client provides access to all Noxus resources through dedicated services:

# Access different services
workflows = client.workflows.list()
conversations = client.conversations.list()
knowledge_bases = client.knowledge_bases.list()
agents = client.agents.list()
runs = client.runs.list()

# Admin functions (if you have admin permissions)
if client.admin.enabled:
    users = client.admin.list_users()

Workflows

client.workflows - Create and manage AI workflows

Conversations

client.conversations - Handle chat interactions

Knowledge Bases

client.knowledge_bases - Manage document repositories

Agents

client.agents - Deploy autonomous AI agents

Runs

client.runs - Monitor workflow executions

Admin

client.admin - Administrative functions

Platform Information Methods

The client provides methods to retrieve platform capabilities:

# Get available workflow node types
nodes = client.get_nodes()
print(f"Available node types: {len(nodes)}")

# Get available AI models
models = client.get_models()
for model in models:
    print(f"Model: {model['name']} - {model['description']}")

# Get chat model presets
presets = client.get_chat_presets()
for preset in presets:
    print(f"Preset: {preset['name']} - {preset['model']}")

Asynchronous Versions

All platform information methods have async counterparts:

import asyncio

async def get_platform_info():
    nodes = await client.aget_nodes()
    models = await client.aget_models()
    presets = await client.aget_chat_presets()
    return nodes, models, presets

# Run async function
nodes, models, presets = asyncio.run(get_platform_info())

Error Handling

The client handles various types of errors that can occur during API interactions:

import httpx
from noxus_sdk.client import Client

try:
    client = Client(api_key="your_api_key")
    workflows = client.workflows.list()

except httpx.HTTPStatusError as e:
    if e.response.status_code == 401:
        print("Authentication failed - check your API key")
    elif e.response.status_code == 403:
        print("Access forbidden - check your permissions")
    elif e.response.status_code == 429:
        print("Rate limit exceeded - please wait before retrying")
    else:
        print(f"HTTP error {e.response.status_code}: {e.response.text}")

except httpx.RequestError as e:
    print(f"Network error: {e}")

except Exception as e:
    print(f"Unexpected error: {e}")

Best Practices

API Key Security

Never hardcode API keys in your source code:

import os
from noxus_sdk.client import Client

# ✅ Good - use environment variables
client = Client(api_key=os.getenv("NOXUS_API_KEY"))

# ❌ Bad - hardcoded API key
client = Client(api_key="noxus_1234567890abcdef")

Client Reuse

Create one client instance and reuse it throughout your application:

# ✅ Good - singleton pattern
class NoxusService:
    _client = None
    
    @classmethod
    def get_client(cls):
        if cls._client is None:
            cls._client = Client(api_key=os.getenv("NOXUS_API_KEY"))
        return cls._client

# Use throughout your app
client = NoxusService.get_client()

Error Handling

Always implement proper error handling:

def safe_api_call(func, *args, **kwargs):
    try:
        return func(*args, **kwargs)
    except httpx.HTTPStatusError as e:
        logger.error(f"API error {e.response.status_code}: {e.response.text}")
        raise
    except httpx.RequestError as e:
        logger.error(f"Network error: {e}")
        raise

# Usage
workflows = safe_api_call(client.workflows.list)

Resource Management

Be mindful of resource usage with large datasets:

# ✅ Good - use pagination
page = 1
while True:
    workflows = client.workflows.list(page=page, page_size=50)
    if not workflows:
        break
    process_workflows(workflows)
    page += 1

# ❌ Bad - loading everything at once
all_workflows = client.workflows.list(page_size=10000)

Advanced Configuration

Custom HTTP Client

For advanced use cases, you can customize the underlying HTTP client:

import httpx
from noxus_sdk.client import Client

# Create custom HTTP client with specific settings
http_client = httpx.Client(
    timeout=60.0,
    limits=httpx.Limits(max_connections=100, max_keepalive_connections=20)
)

# Note: This is a conceptual example - the actual SDK doesn't expose this yet
# but it shows the kind of customization that might be useful

Logging Configuration

Enable detailed logging for debugging:

import logging
from noxus_sdk.client import Client

# Configure logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("noxus_sdk")

client = Client(api_key="your_api_key")

# Now all HTTP requests will be logged
workflows = client.workflows.list()

Testing with the Client

When writing tests, consider using dependency injection:

import pytest
from unittest.mock import Mock
from noxus_sdk.client import Client

class MyService:
    def __init__(self, client: Client):
        self.client = client

    def get_workflow_count(self):
        workflows = self.client.workflows.list()
        return len(workflows)

# Test with mock client
def test_get_workflow_count():
    mock_client = Mock(spec=Client)
    mock_client.workflows.list.return_value = [Mock(), Mock(), Mock()]

    service = MyService(mock_client)
    count = service.get_workflow_count()

    assert count == 3
    mock_client.workflows.list.assert_called_once()

Next Steps

Authentication

Learn about API key management and security

Async Operations

Understand asynchronous programming with the SDK

Workflows

Start building AI workflows

API Reference

Explore the complete client API

Overview

Getting Started

Concepts

Conversations

Workflows

Guides

API Reference

Overview

Basic Initialization

Configuration Options

Environment Variables

Resource Access

Workflows

Conversations

Knowledge Bases

Agents

Runs

Admin

Platform Information Methods

Asynchronous Versions

Error Handling

Best Practices

Advanced Configuration

Custom HTTP Client

Logging Configuration

Testing with the Client

Next Steps

Authentication

Async Operations

Workflows

API Reference

​Overview

​Basic Initialization

​Configuration Options

​Environment Variables

​Resource Access

Workflows

Conversations

Knowledge Bases

Agents

Runs

Admin

​Platform Information Methods

​Asynchronous Versions

​Error Handling

​Best Practices

​Advanced Configuration

​Custom HTTP Client

​Logging Configuration

​Testing with the Client

​Next Steps

Authentication

Async Operations

Workflows

API Reference

Overview

Basic Initialization

Configuration Options

Environment Variables

Resource Access

Platform Information Methods

Asynchronous Versions

Error Handling

Best Practices

Advanced Configuration

Custom HTTP Client

Logging Configuration

Testing with the Client

Next Steps