Nexum Framework Documentation

Table of Contents

1. Introduction
2. Installation
3. Getting Started
4. Client
5. Text Generation API
   • Available Models
   • Usage Examples
6. Image Generation API
   • Available Models
   • Image Generation Settings
   • Usage Examples
7. Tor Integration
8. Advanced Usage
9. Troubleshooting
10. API Reference

Introduction

Nexum is a Python framework providing access to multiple AI services through a unified API. It includes:

• Text Generation API: Create text using various AI models, including Gemini, GPT-4, Llama, and others
• Image Generation API: Create images from text prompts using various diffusion models
• Tor Integration: Optional proxy support for enhanced privacy

Nexum is designed for ease of use while providing access to powerful artificial intelligence capabilities.

Installation

pip install nexum

Requirements

• Python 3.9 or higher
• For Tor integration: running Tor service on your machine

Getting Started

Start by importing the Client class and creating a client instance:

from nexum import Client

# Initialize client
client = Client()

Client

The Client class is the main entry point for interacting with the Nexum API. It provides access to two main services:

• completion: For text generation
• diffusion: For image generation

Basic Usage

from nexum import Client

client = Client()

# Access text generation
completion = client.completion

# Access image generation
diffusion = client.diffusion

Text Generation API

The text generation API allows you to create text responses using various AI models.

Creating Text Responses

from nexum import Client

client = Client()

# Create a simple response
messages = [
    {"role": "user", "content": "Hello!"}
]

# Using the default model (Gemini-2.0-F-Thinking)
response = client.completion.create(messages)
print(response)

# Using a specific model by ID
response = client.completion.create(messages, model=4)  # Uses GPT-4o
print(response)

# Using a specific model by name
response = client.completion.create(messages, model="Llama-3.3")
print(response)

# Check which model is being used
response = client.completion.create(messages, model_check=True)
print(response)

# Using Tor proxy for enhanced privacy
response = client.completion.create(messages, proxy=True)
print(response)

Available Text Models

Nexum provides access to a variety of text generation models from different providers:

Google Models

• Gemini-2.0-F-Thinking (ID: 1): Deep context understanding, generating meaningful responses
• Gemini-2.0-Flash (ID: 2): High-speed text generation with excellent context understanding
• Gemini-1.5-Flash (ID: 3): Fast and efficient text generation with good understanding of user queries

OpenAI Models

• GPT-4o (ID: 4): Multimodal model supporting more than 50 languages with improved context understanding
• O1-Mini (ID: 5): Optimized for STEM tasks, especially mathematics and programming

DeepSeek Models

• Deepseek-R1-Distill (ID: 6): Compact models for reasoning and programming tasks

Meta Models

• Llama-3.3 (ID: 7): Advanced language model with 70 billion parameters
• Llama-3.1 (ID: 8): Large language model with 405 billion parameters and context up to 128k tokens

Alibaba Models

• Qwen2.5 (ID: 9): Model with 72.7 billion parameters and context up to 128k tokens, improved for coding and mathematics

xAI Models

• Grok-2 (ID: 11): Advanced language model with image generation capabilities
• Grok-Beta (ID: 12): Experimental model with improved reasoning

ToolBaz Models

• ToolBaz-v3.5-Pro (ID: 13): Advanced text generation model
• ToolBaz-v3 (ID: 14): Basic text generation model

Mixtral Models

• Mixtral (ID: 15): Powerful model with 141 billion parameters using Mixture-of-Experts architecture

Unfiltered Models

• L3-Euryale-v2.1 (ID: 16): Model with 70 billion parameters based on LLaMA-3 architecture
• Midnight-Rose (ID: 17): Unfiltered language model
• Unity (ID: 18): Unfiltered language model
• Unfiltered_X (ID: 19): Unfiltered model with 141 billion parameters

Text Usage Examples

from nexum import Client
from nexum.system.completions.utils.models import Models

# Initialize client
client = Client()

# Create a request with model display
messages = [{'role': 'user', 'content': 'Hello!'}]
response = client.completion.create(messages, model_check=True, model=2)
print(response)

# View all available models
all_models = Models().get_models()
print(all_models)

# Find model by ID
model = Models().get_model_by_id(1)
print(model)

# Find model by name
model = Models().get_model_by_name('Gemini-2.0-F-Thinking')
print(model)

# Universal model search (by ID or name)
model = Models().get_model(1)  # By ID
print(model)
model = Models().get_model('Gemini-2.0-F-Thinking')  # By name
print(model)

Image Generation API

The image generation API allows you to create images from text prompts using various diffusion models.

Creating Images

from nexum import Client
from nexum.system.diffusion.utils.settings import Settings

client = Client()

# Generate image with default settings
prompt = "cute anime cat"
client.diffusion.create(prompt)  # Saves to ./media/image.jpg

# Using specific model and save path
client.diffusion.create("beautiful mountain landscape", path="./output/landscape.jpg", model="flux-2")

# Custom settings (only for sdxl-flash model)
settings = Settings(model=2)  # Initialize settings for sdxl-flash
settings.set_resolution((768, 512))  # Set custom resolution
settings.set_steps(20)  # Set the number of output steps
settings.negative_prompt("blurry, low quality")  # Set custom negative prompt

client.diffusion.create(
    "cute anime girl", 
    path="./output/custom_anime.jpg", 
    settings=settings,
    model=2
)

# Using Tor proxy
client.diffusion.create("cute anime cat", path="./output/proxy_cat.jpg", proxy=True)

Available Image Models

Nexum currently supports the following image generation models:

1. flux-2 (ID: 1)

   • Styles: Realistic and Anime
   • NSFW content: Not supported
   • Settings: Not customizable

2. sdxl-flash (ID: 2)

   • Styles: Realistic and Anime
   • NSFW content: Supported
   • Settings: Fully customizable

Image Generation Settings

For models that support custom settings (currently only sdxl-flash), you can configure the following parameters:

from nexum.system.diffusion.utils.settings import Settings

settings = Settings(model=2)  # Initialize settings for sdxl-flash

# Set custom negative prompt
settings.negative_prompt("low quality, blurry, distorted")

# Set specific seed for reproducible results (or 'random' for random seed)
settings.set_seed(42)  # Or settings.set_seed('random')

# Set custom resolution (height, width)
settings.set_resolution((768, 512))  

# Set the number of output steps (more = more details but slower)
settings.set_steps(20)

Default settings for sdxl-flash:

• Negative prompt: (deformed, distorted, disfigured:1.3), poorly drawn, bad anatomy, wrong anatomy, extra limb, missing limb, floating limbs, (mutated hands and fingers:1.4), disconnected limbs, mutation, mutated, ugly, disgusting, blurry, amputation
• Seed: random
• Resolution: 1024x1024
• Steps: 15

Image Usage Examples

from nexum import Client
from nexum.system.diffusion.utils.models import Models
from nexum.system.diffusion.utils.settings import Settings

# Initialize client
client = Client()

# Basic image generation
client.diffusion.create('cute anime cat')  # Saves to ./media/image.jpg

# Generation using specific model and save path
client.diffusion.create('cute anime girl', path='./media/girl.png', model=2)

# Generation with custom settings
settings = Settings(model=2)
settings.negative_prompt('(deformed, distorted, disfigured:1.3), poorly drawn, bad anatomy...')
settings.set_seed('random')
settings.set_resolution((1024, 1024))
settings.set_steps(15)
client.diffusion.create(
    'cute anime girl', 
    path='./media/girl_steps_15.png', 
    model=2, 
    settings=settings
)

# View all available image generation models
diffusion_models = Models().get_models()
print(diffusion_models)

# Find model by ID or name
model = Models().get_model(1)  # By ID
print(model)
model = Models().get_model('flux-2')  # By name
print(model)

Tor Integration

Nexum provides optional Tor proxy integration for enhanced privacy. This feature requires a running Tor service on your machine.

Using Tor Proxy

Add the proxy=True parameter to any API call:

# Generate text with Tor proxy
response = client.completion.create(messages, proxy=True)

# Generate image with Tor proxy
client.diffusion.create(prompt, path="./output/image.jpg", proxy=True)

Tor Utilities

from nexum.utils.webtor import Interfice_Tor

# Install Tor if not installed
# Interfice_Tor.install_tor()

# Get a new Tor IP address
Interfice_Tor.new_ip()

# Check your current Tor IP address
current_ip = Interfice_Tor.check_ip()
print(current_ip)

# Complete example using Tor
Interfice_Tor.new_ip()
nexus = Client()

messages = [{'role': 'user', 'content': 'Hello!'}]
print(nexus.completion.create(messages, model_check=True, model=2, proxy=True))
print(nexus.diffusion.create('cute anime cat', proxy=True))

install_tor - works only on Windows, automatic installation on macOS and Linux is not available, but you can download it manually from the official website.

Advanced Usage

Multi-Turn Conversations

from nexum import Client

client = Client()

messages = [
    {"role": "user", "content": "Hi, can you help me with a Python task?"},
    {"role": "ai", "content": "Of course! I'd be happy to help with your Python task. What are you working on?"},
    {"role": "user", "content": "How do I sort a dictionary by value in Python?"}
]

response = client.completion.create(messages)
print(response)

# Add the response to continue the conversation
messages.append({"role": "ai", "content": response})
messages.append({"role": "user", "content": "Can you show me another example?"})

response = client.completion.create(messages)
print(response)

Checking Available Models

from nexum.system.completions.utils.models import Models

models = Models()
all_models = models.get_models()

# Output all available models
for provider, provider_models in all_models.items():
    print(f"\n{provider} Models:")
    for model in provider_models:
        print(f"  - {model['model_name']} (ID: {model['model_id']})")
        if model['description']:
            print(f"    Description: {model['description']}")

Troubleshooting

Common Issues

1. Connection Errors

   • Ensure your internet connection is stable
   • When using Tor, check that the Tor service is running on your machine

2. Model Not Found

   • Double-check the model ID or name
   • Use the Models class to get a list of available models

3. Image Generation Failure

   • Ensure the directory for saving images exists or use os.makedirs() to create it
   • Try a different model or a simpler prompt

Getting Help

If you encounter issues not described in this documentation, please:

• Check the updated documentation
• Look for similar issues in the project repository
• Submit a detailed bug report with your code and error messages

API Reference

Client

Client()

Properties:

• completion: Access to the text generation API
• diffusion: Access to the image generation API

Completion

client.completion.create(messages, model=1, model_check=False, proxy=False)

Parameters:

• messages: List of message dictionaries with 'role' and 'content' keys
• model: Model ID (int) or name (str), default 1 (Gemini-2.0-F-Thinking)
• model_check: Whether to include model information in the response, default False
• proxy: Whether to use Tor proxy, default False

Returns:

• Generated text response as a string

Diffusion

client.diffusion.create(prompt, path='./media/image.jpg', settings=None, model=1, proxy=False)

Parameters:

• prompt: Text prompt for image generation
• path: Output file path, default './media/image.jpg'
• settings: Optional Settings object for customizable models
• model: Model ID (int) or name (str), default 1 (flux-2)
• proxy: Whether to use Tor proxy, default False

Returns:

• Boolean indicating success or failure

Settings

Settings(model=2)

Methods:

• negative_prompt(prompt): Set negative prompt
• set_seed(seed): Set generator seed (int or 'random')
• set_resolution(res=(height, width)): Set output resolution
• set_steps(steps): Set output steps

Property:

• setting: Get current settings dictionary