Quick Start

Prerequisites

Before you begin, make sure you have:

Python 3.10 or later installed on your system
A Noxus account with access to a workspace
An API key from your Noxus workspace

Don’t have a Noxus account yet? Sign up here to get started.

Installation

Install the Noxus Client SDK using pip:

pip install noxus-sdk

poetry add noxus-sdk

pipenv install noxus-sdk

The SDK requires Python 3.10 or later and automatically installs all necessary dependencies.

Get Your API Key

Access Your Workspace

Open Settings

Go to Settings → Organization → Workspaces and select your workspace

Generate API Key

Navigate to the API Keys tab and create a new API key

Copy Your Key

Copy the generated API key - you’ll need it for authentication

Keep your API key secure and never commit it to version control. Consider using environment variables to store it safely.

Initialize the Client

Create your first Noxus client:

from noxus_sdk.client import Client

# Initialize with your API key
client = Client(api_key="your_api_key_here")

# Or use environment variable
import os
client = Client(api_key=os.getenv("NOXUS_API_KEY"))

# For custom backend URL (if needed)
client = Client(
    api_key="your_api_key_here",
    base_url="https://your-custom-backend.com"
)

You can also set the NOXUS_BACKEND_URL environment variable instead of passing base_url directly.

Your First Conversation

Let’s create a simple AI conversation:

from noxus_sdk.client import Client
from noxus_sdk.resources.conversations import ConversationSettings, MessageRequest

# Initialize the client
client = Client(api_key="your_api_key_here")

# Configure conversation settings
settings = ConversationSettings(
    model=["gpt-4o-mini"],
    temperature=0.7,
    max_tokens=150,
    tools=[],
    extra_instructions="Be helpful and concise."
)

# Create a new conversation
conversation = client.conversations.create(
    name="My First Conversation",
    settings=settings
)

print(f"Created conversation: {conversation.id}")

# Send a message
message = MessageRequest(content="Hello! What can you help me with?")
response = conversation.add_message(message)

print(f"AI Response: {response.message_parts}")

Your First Workflow

Now let’s create a simple workflow:

from noxus_sdk.workflows import WorkflowDefinition

# Create a workflow definition
workflow_def = WorkflowDefinition(name="Hello World Workflow")

# Add nodes
input_node = workflow_def.node("InputNode").config(
    label="User Input",
    fixed_value=True,
    value="Tell me a fun fact about space",
    type="str"
)

ai_node = workflow_def.node("TextGenerationNode").config(
    template="Answer this question: ((Input 1))",
    model=["gpt-4o-mini"]
)

output_node = workflow_def.node("OutputNode")

# Connect the nodes
workflow_def.link(input_node.output(), ai_node.input("variables", "Input 1"))
workflow_def.link(ai_node.output(), output_node.input())

# Save the workflow
workflow = client.workflows.save(workflow_def)
print(f"Created workflow: {workflow.id}")

# Run the workflow
run = workflow.run(body={})
result = run.wait(interval=2)

print(f"Workflow result: {result.output}")

Explore Platform Capabilities

Get information about available models and nodes:

# List available AI models
models = client.get_models()
print("Available models:")
for model in models[:3]:  # Show first 3
    print(f"- {model['name']}")

# List available workflow nodes
nodes = client.get_nodes()
print(f"\nAvailable node types: {len(nodes)}")
for node in nodes[:5]:  # Show first 5
    print(f"- {node['type']}")

# Get chat presets
presets = client.get_chat_presets()
print(f"\nAvailable chat presets: {len(presets)}")

Working with Knowledge Bases

Create a knowledge base for document storage and retrieval:

from noxus_sdk.resources.knowledge_bases import (
    KnowledgeBaseSettings,
    KnowledgeBaseIngestion,
    KnowledgeBaseRetrieval
)

# Configure knowledge base settings
settings = KnowledgeBaseSettings(
    ingestion=KnowledgeBaseIngestion(
        batch_size=10,
        default_chunk_size=1000,
        default_chunk_overlap=200,
        enrich_chunks_mode="contextual"
    ),
    retrieval=KnowledgeBaseRetrieval(
        type="hybrid_reranking",
        hybrid_settings={"fts_weight": 0.3}
    )
)

# Create knowledge base
kb = client.knowledge_bases.create(
    name="My Knowledge Base",
    description="A sample knowledge base for testing",
    document_types=["pdf", "txt", "docx"],
    settings_=settings
)

print(f"Created knowledge base: {kb.id}")

Error Handling

Always include proper error handling in your applications:

from noxus_sdk.client import Client
import httpx

try:
    client = Client(api_key="your_api_key_here")
    workflows = client.workflows.list()
    print(f"Found {len(workflows)} workflows")

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 denied. Check your permissions.")
    else:
        print(f"HTTP error: {e.response.status_code}")

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

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

Next Steps

Explore Workflows

Learn to build complex AI workflows with visual programming

Build Conversations

Create intelligent chatbots with tools and context

Manage Knowledge

Set up knowledge bases for document retrieval

Deploy Agents

Create autonomous AI agents for your applications

Example Projects

Customer Support Bot

# Create a support bot with knowledge base integration
from noxus_sdk.resources.conversations import (
    ConversationSettings, 
    KnowledgeBaseQaTool
)

kb_tool = KnowledgeBaseQaTool(
    enabled=True,
    kb_id="your_kb_id",
    extra_instructions="Provide helpful support answers"
)

settings = ConversationSettings(
    model=["gpt-4o-mini"],
    tools=[kb_tool],
    extra_instructions="You are a helpful customer support agent."
)

support_bot = client.conversations.create(
    name="Support Bot",
    settings=settings
)

Document Processing Workflow

# Create a workflow that processes and summarizes documents

workflow_def = WorkflowDefinition(name="Document Processor") input_node =
workflow_def.node("InputNode").config( label="Document Input" ) summarizer =
workflow_def.node("SummaryNode").config( summary_format="Bullet Points",
summary_topic="Key insights and action items" ) output_node =
workflow_def.node("OutputNode") workflow_def.link(input_node.output(),
summarizer.input()) workflow_def.link(summarizer.output(),
output_node.input()) processor = client.workflows.save(workflow_def) ```
</Accordion>

<Accordion title="Research Assistant Agent" icon="search">
  ```python
  # Create an agent that can research topics using web search
  from noxus_sdk.resources.conversations import WebResearchTool
  
  web_tool = WebResearchTool(
      enabled=True,
      extra_instructions="Focus on recent and reliable sources"
  )
  
  agent_settings = ConversationSettings(
      model=["gpt-4o-mini"],
      tools=[web_tool],
      extra_instructions="You are a research assistant. Provide well-sourced information."
  )
  
  research_agent = client.agents.create(
      name="Research Assistant",
      settings=agent_settings
  )

Get Help

Having trouble? Check out our troubleshooting guide or reach out to [email protected].

Overview

Getting Started

Concepts

Conversations

Workflows

Guides

API Reference

Prerequisites

Installation

Get Your API Key

Initialize the Client

Your First Conversation

Your First Workflow

Explore Platform Capabilities

Working with Knowledge Bases

Error Handling

Next Steps

Explore Workflows

Build Conversations

Manage Knowledge

Deploy Agents

Example Projects

Get Help

​Prerequisites

​Installation

​Get Your API Key

​Initialize the Client

​Your First Conversation

​Your First Workflow

​Explore Platform Capabilities

​Working with Knowledge Bases

​Error Handling

​Next Steps

Explore Workflows

Build Conversations

Manage Knowledge

Deploy Agents

​Example Projects

​Get Help

Prerequisites

Installation

Get Your API Key

Initialize the Client

Your First Conversation

Your First Workflow

Explore Platform Capabilities

Working with Knowledge Bases

Error Handling

Next Steps

Example Projects

Get Help