🚀 Superb AI On-premise Python SDK

Python License Version

Superb AI On-premise Python SDK is a comprehensive Python library that provides a simple and intuitive interface to interact with your on-premise Superb AI installation. Build powerful data management, annotation, and machine learning workflows with ease.

🌟 Key Features

🗂️ Dataset Management: Create, organize, and manage your datasets
📊 Data Operations: Upload, annotate, and manipulate your data with powerful filtering
🔍 Advanced Filtering: Sophisticated filtering system for precise data queries
🏷️ Annotation Management: Handle annotations and versions seamlessly
📁 Content Management: Upload and manage file content
⚡ Activity Tracking: Monitor and manage long-running tasks
🔧 Slice Management: Organize data into logical groups
🤖 Model Tracking: Register and monitor ML model performance
📈 Analytics Reports: Generate and visualize dataset analytics

모델 생성·수정과 조회 필터에는 ModelTaskType을 사용합니다. VLM은 시각·언어 이해 모델을, VISION_GENERATION은 이미지·영상 생성 모델을 나타냅니다. 생성 모델 타입으로 API를 호출하려면 서버에도 해당 타입 지원이 반영되어 있어야 합니다.

🔧 Installation

Step 1: Install the SDK

Install the SDK using pip:

pip install superb-ai-onprem

Requirements:

Python 3.7 or higher
Active Superb AI On-premise installation

⚠️ Important: The SDK will not work without this configuration file. Make sure to replace the values with your actual credentials from your Superb AI administrator.

🚀 Quick Start

Get up and running with Superb AI SDK in minutes:

Step 1: Authentication Setup

First, set up your authentication credentials:

Option A: Config file (Recommended for local development)

# Create config directory
mkdir -p ~/.spb

# Create config file
cat > ~/.spb/onprem-config << EOF
[default]
host=https://your-superb-ai-host.com
access_key=your-access-key
access_key_secret=your-access-key-secret
EOF

Step 2: Your First Workflow

from spb_onprem import DatasetService, DataService, ModelService, ReportService

# Initialize services
dataset_service = DatasetService()
data_service = DataService()
model_service = ModelService()
report_service = ReportService()

# 1. Find existing datasets
datasets, cursor, total = dataset_service.get_datasets(length=10)
print(f"📂 Found {total} datasets")

if datasets:
    # Use the first available dataset
    dataset = datasets[0]
    print(f"✅ Using dataset: {dataset.name} (ID: {dataset.id})")
    
    # 2. Get data list from the dataset
    data_list, cursor, total = data_service.get_data_list(
        dataset_id=dataset.id,
        length=10
    )
    
    print(f"📊 Dataset contains {total} data items")
    
    # 3. Display data information
    for i, data in enumerate(data_list, 1):
        print(f"  {i}. Key: {data.key}, Type: {data.type}, ID: {data.id}")
        
    if total > len(data_list):
        print(f"  ... and {total - len(data_list)} more items")
    
    # 4. Check models in the dataset
    models, _, model_count = model_service.get_models(
        dataset_id=dataset.id,
        length=5
    )
    
    if model_count > 0:
        print(f"\n🤖 Found {model_count} models")
        for model in models:
            print(f"  - {model.name} ({model.baseline_model})")
    
    # 5. Check analytics reports
    reports, _, report_count = report_service.get_analytics_reports(
        dataset_id=dataset.id,
        length=5
    )
    
    if report_count > 0:
        print(f"\n📈 Found {report_count} analytics reports")
        for report in reports:
            print(f"  - {report.title}")
else:
    print("❌ No datasets found. Please create a dataset first.")

🎉 Congratulations! You've successfully:

✅ Connected to your Superb AI instance
✅ Found existing datasets
✅ Retrieved and displayed data information
✅ Explored models and reports

Ready for more? Check out our comprehensive documentation below!

📚 Module Documentation

🏗️ Core Modules

Comprehensive guides for each SDK module with detailed examples and best practices:

Module	Purpose	Key Features	Documentation
📁 Datasets	Dataset lifecycle management	Create, organize, manage data collections	📂 Dataset Guide
📊 Data	Individual data management	CRUD operations, advanced filtering, annotations	📊 Data Guide
🔪 Slices	Data organization & filtering	Create filtered views, team collaboration	🔪 Slice Guide
⚡ Activities	Workflow & task management	Process automation, progress tracking	⚡ Activity Guide
🤖 Models	ML model management	Track models, training configs, performance metrics	🤖 Model Guide
📈 Reports	Analytics & visualization	Create reports, charts, dashboards	📈 Report Guide
📊 Charts	Chart data factory	Generate training metrics visualizations (9 chart types)	📊 Chart Guide

🎯 Getting Started Paths

Choose your learning path based on your use case:

📊 Data Management Workflow

Start with 📁 Datasets - Create and organize your data collections
Then explore 📊 Data - Manage individual items and annotations
Use 🔪 Slices - Organize data into logical groups

🚀 ML Pipeline Integration

Begin with 📊 Data - Understand data structure and filtering
Configure ⚡ Activities - Automate labeling and review workflows
Track with 🤖 Models - Register and monitor model performance
Create visualizations with 📊 Charts - Generate training metrics charts
Build dashboards with 📈 Reports - Compile analytics reports

👥 Team Collaboration

Setup 📁 Datasets - Organize team projects
Create 🔪 Slices - Assign work to team members
Implement ⚡ Activities - Track progress and quality

🔧 Advanced Features

Each module includes:

🎯 Quick Start Examples - Get running immediately
📋 Detailed Entity Documentation - Pydantic models with comprehensive field descriptions
🔍 Advanced Usage Patterns - Best practices and complex workflows
🔗 Cross-Module Integration - How modules work together
⚡ Performance Tips - Optimization recommendations

🌐 Module Relationships

📁 Datasets (containers)
├── 📊 Data (individual items) 
│   ├── 🔪 Slices (filtered views)
│   │   └── 🤖 Models (training configs)
│   └── ⚡ Activities (processing workflows)
└── 📈 Reports (analytics & visualizations)

🆕 New Modules (v2.0+)

Module	Added	Status	Description
🤖 Models	v2.0	✅ Stable	ML model lifecycle management and performance tracking
📈 Reports	v2.0	✅ Stable	Analytics reports and visualization dashboards
📊 Charts	v2.0	✅ Stable	Chart data factory with 9 chart types for training metrics visualization

⚠️ Deprecated Modules

Module	Status	Migration Path
InferService	🚫 Deprecated	Use 🤖 Models for model management and ⚡ Activities for inference workflows

⚠️ Error Handling

The SDK provides specific error types for different scenarios:

from spb_onprem.exceptions import (
    BadParameterError,
    NotFoundError,
    UnknownError
)

try:
    dataset = dataset_service.get_dataset(dataset_id="non-existent-id")
except NotFoundError:
    print("Dataset not found")
except BadParameterError as e:
    print(f"Invalid parameter: {e}")
except UnknownError as e:
    print(f"An unexpected error occurred: {e}")

🧪 Requirements

Python >= 3.7
requests >= 2.22.0
urllib3 >= 1.21.1
pydantic >= 1.8.0

🤝 Contributing

We welcome contributions to the Superb AI On-premise SDK! Here's how you can help:

Development Setup

Clone the repository:

git clone https://github.com/Superb-AI-Suite/superb-ai-onprem-python.git
cd superb-ai-onprem-python

Install development dependencies:

pip install -e ".[dev]"

Contribution Guidelines

Code Style: Follow PEP 8 guidelines
Testing: Add tests for new features
Documentation: Update docstrings and README
Pull Requests: Use descriptive titles and include test results

Reporting Issues

When reporting issues, please include:

SDK version (spb_onprem.__version__)
Python version
Error messages and stack traces
Minimal reproduction example
Expected vs actual behavior

📞 Support

Community Support

GitHub Issues: Report bugs and request features
Documentation: Official API documentation

Enterprise Support

Technical Support: Contact your Superb AI representative
Custom Integration: Professional services available
Training: SDK workshops and onboarding sessions

Quick Help

Common Issues:

Authentication errors: Check config file format and credentials
Connection issues: Verify host URL and network connectivity
Import errors: Ensure SDK is properly installed (pip install superb-ai-onprem)
Performance issues: Use appropriate pagination and filtering

Need immediate help? Check our FAQ section or contact support.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🚀 Ready to build something amazing? Start with our Quick Start Guide and explore the powerful features of Superb AI On-premise SDK!

_{Built with ❤️ by the Superb AI team}

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Metadata

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Release files for superb-ai-onprem 1.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for superb-ai-onprem 1.14.0
File	Size	Uploaded
superb_ai_onprem-1.14.0.tar.gz	152.1 kB	Oct 17, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for superb-ai-onprem 1.14.0
File	Interpreter	ABI	Platform	Reset
superb_ai_onprem-1.14.0-py3-none-any.whl 164.1 kB Oct 17, 2026	Python 3	none	any	Details

Total release size: 316.2 kB

Release files / superb_ai_onprem-1.14.0.tar.gz

Download URL	superb_ai_onprem-1.14.0.tar.gz
Size	152.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`81902bda029081c5f5e8d6fecf20e93fc5fbe085ea7f73578930cd900dc83ea5`
BLAKE2b-256 checksum How to use checksums	`2e21eb6e58cd48735797fdb74e8b78a511a7edbe0ffec9d6499fe37957046e59`
Upload date	Oct 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`

Release files / superb_ai_onprem-1.14.0-py3-none-any.whl

Download URL	superb_ai_onprem-1.14.0-py3-none-any.whl
Size	164.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`54eb6d94eb99f28773e5939ae92a8e867540467d70c6d7d0720d572006cc35e2`
BLAKE2b-256 checksum How to use checksums	`e1e36ed01601b968f232aa23a3708aafbd4a7137721fde09cdca9ac4b65bb19d`
Upload date	Oct 17, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.8`