rose-python-sdk 1.1.0

Python SDK for Rose Recommendation Service API

Rose Python SDK

A comprehensive Python SDK for interacting with the Rose Recommendation Service API. This SDK provides a clean, type-safe interface for managing datasets, pipelines, roles, and recommendations.

🚀 Features

• Complete API Coverage: Full support for all Rose Recommendation Service endpoints
• Type Safety: Built with Pydantic for robust data validation and type hints
• Comprehensive Error Handling: Detailed exception classes for different error scenarios
• Batch Operations: Efficient batch data processing and upload capabilities
• Schema Management: Automatic schema inference and validation
• Pipeline Management: Intuitive pipeline creation and management tools
• Role-Based Access Control: Complete permission and role management system
• Helper Functions: High-level utilities for common operations

📦 Installation

pip install rose-python-sdk

🏃‍♂️ Quick Start

Basic Setup

from rose_sdk import RoseClient

# Initialize the client
client = RoseClient(
    base_url="https://admin.rose.blendvision.com",
    access_token="your_access_token"
)

Create a Dataset with Data

from rose_sdk import quick_create_dataset_with_data

# Create dataset with sample data
dataset_id = quick_create_dataset_with_data(
    client=client,
    name="user_interactions",
    records=[
        {"user_id": "user1", "item_id": "item1", "rating": 4.5},
        {"user_id": "user1", "item_id": "item2", "rating": 3.0},
        {"user_id": "user2", "item_id": "item1", "rating": 5.0}
    ],
    identifier_fields=["user_id", "item_id"],
    required_fields=["rating"]
)

Create a Recommendation Pipeline

from rose_sdk.utils import create_pipeline

# Create a pipeline with dataset mapping
pipeline_response = create_pipeline(
    client=client,
    account_id="your_account",
    pipeline_name="recommendation_pipeline",
    scenario="realtime_leaderboard",
    dataset_mapping={
        "interaction": dataset_id,  # Map pipeline key to your dataset
        "metadata": "your_metadata_dataset_id"
    }
)

Get Recommendations

# Get recommendations for a user
recommendations = client.recommendations.get(
    query_id="your_query_id",
    parameters={"user_id": "user1"}
)

print(f"Recommendations: {recommendations.data}")

📚 Documentation

• Getting Started Guide - Quick start guide for new users
• API Reference - Complete API documentation
• Examples Guide - Comprehensive examples and use cases
• Contributing Guide - How to contribute to the project

📚 Core Modules

1. Client (RoseClient)

The main client class that provides access to all Rose services:

client = RoseClient(base_url="...", access_token="...")

# Access different services
client.datasets.create(...)      # Dataset management
client.pipelines.create(...)     # Pipeline management  
client.roles.create(...)         # Role management
client.recommendations.get(...)  # Get recommendations

2. Services

Organized service classes for different API endpoints:

• DatasetService: Create, manage, and query datasets
• PipelineService: Create and manage recommendation pipelines
• RoleService: Manage user roles and permissions
• RecommendationService: Get recommendations and query results

3. Models

Type-safe data models using Pydantic:

• Dataset: Dataset information and metadata
• Pipeline: Pipeline configuration and status
• Role: User roles and permissions
• Query: Query definitions and results

4. Utils

Utility functions for common operations:

• Record Conversion: Convert between Python and Rose data formats
• Schema Management: Build and validate dataset schemas
• Batch Processing: Handle large data uploads efficiently
• Pipeline Building: Create pipelines with minimal configuration

5. Helpers

High-level helper functions for quick operations:

• quick_create_dataset_with_data(): Create dataset and add data in one call
• quick_batch_upload(): Upload large amounts of data efficiently
• quick_setup_recommendation_system(): Complete end-to-end setup

📖 Examples

The SDK includes comprehensive examples in the examples/ directory:

Role Management

python examples/01_role_management/01_basic_permissions.py
python examples/01_role_management/02_api_usage.py

Dataset Management

python examples/02_dataset_management/01_basic_datasets.py
python examples/02_dataset_management/02_api_usage.py

Records Management

python examples/03_records_management/01_basic_ingestion.py
python examples/03_records_management/02_records_management.py

Batch Data Management

python examples/04_batch_data_management/01_batch_append.py
python examples/04_batch_data_management/02_batch_overwrite.py

Pipeline Management

python examples/05_pipeline_management/01_create_pipeline.py
python examples/05_pipeline_management/02_update_pipeline.py
python examples/05_pipeline_management/04_delete_pipeline.py
python examples/05_pipeline_management/05_list_queries.py

🔧 Advanced Usage

Schema Validation

from rose_sdk.utils import validate_and_align_records

# Validate records against dataset schema
validated_records = validate_and_align_records(
    dataset_id=dataset_id,
    records=your_records,
    client=client
)

Batch Operations

from rose_sdk.utils import prepare_batch_data, get_batch_headers

# Prepare large dataset for batch upload
batch_data = prepare_batch_data(records)
headers = get_batch_headers()

# Upload in batches
client.datasets.batch.upload_batch(dataset_id, batch_id, batch_data)

Pipeline Building

from rose_sdk.utils import PipelineBuilder

# Build complex pipeline configurations
pipeline_config = (PipelineBuilder("account", "pipeline_name", "scenario")
    .add_dataset("interaction", dataset_id)
    .add_dataset("metadata", metadata_dataset_id)
    .set_custom_property("custom_setting", "value")
    .build())

🛠️ Error Handling

The SDK provides detailed exception classes for different error scenarios:

from rose_sdk import (
    RoseAPIError,
    RoseAuthenticationError,
    RosePermissionError,
    RoseNotFoundError,
    RoseValidationError,
    RoseConflictError,
    RoseServerError,
    RoseTimeoutError
)

try:
    dataset = client.datasets.get("invalid_id")
except RoseNotFoundError:
    print("Dataset not found")
except RoseAPIError as e:
    print(f"API error: {e}")

🔐 Authentication

The SDK supports multiple authentication methods:

# Access token authentication
client = RoseClient(
    base_url="https://admin.rose.blendvision.com",
    access_token="your_token"
)

# Environment variables
import os
client = RoseClient(
    base_url=os.getenv('ROSE_BASE_URL'),
    access_token=os.getenv('ROSE_ACCESS_TOKEN')
)

📋 Requirements

• Python 3.11+
• requests
• pydantic
• typing-extensions

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• API Documentation
• GitHub Repository
• PyPI Package

🚀 CI/CD

This project uses GitHub Actions for automated testing and publishing:

• Tests: Automatically run on every push and pull request
• Publishing: Automatically publish to PyPI when version tags are pushed
• Releases: Automatically create GitHub releases

For setup instructions, see GitHub Actions Setup Guide.

📊 Status

📞 Support

For support and questions:

• Create an issue on GitHub
• Contact: [e-mail]