# Rose Python SDK
<div align="center">
<img src="./docs/assets/images/rose-logo.png" alt="Rose Python SDK" width="200" />
</div>
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
```bash
pip install rose-python-sdk
```
## 🏃♂️ Quick Start
### Basic Setup
```python
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
```python
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
```python
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
```python
# Get recommendations for a user
recommendations = client.recommendations.get(
query_id="your_query_id",
parameters={"user_id": "user1"}
)
print(f"Recommendations: {recommendations.data}")
```
## 📚 Documentation
- **[Complete Documentation](https://luli0034.github.io/rose-python-sdk/)** - Full documentation with API reference, examples, and guides
- **[GitHub Repository](https://github.com/luli0034/rose-python-sdk)** - Source code and issue tracking
- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project
## 📚 Core Modules
### 1. Client (`RoseClient`)
The main client class that provides access to all Rose services:
```python
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
```bash
python examples/01_role_management/01_basic_permissions.py
python examples/01_role_management/02_api_usage.py
```
### Dataset Management
```bash
python examples/02_dataset_management/01_basic_datasets.py
python examples/02_dataset_management/02_api_usage.py
```
### Records Management
```bash
python examples/03_records_management/01_basic_ingestion.py
python examples/03_records_management/02_records_management.py
```
### Batch Data Management
```bash
python examples/04_batch_data_management/01_batch_append.py
python examples/04_batch_data_management/02_batch_overwrite.py
```
### Pipeline Management
```bash
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
```python
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
```python
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
```python
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:
```python
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:
```python
# 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](https://luli0034.github.io/rose-python-sdk/#/api-reference/overview)
- [GitHub Repository](https://github.com/luli0034/rose-python-sdk)
- [PyPI Package](https://pypi.org/project/rose-python-sdk/)
## 🚀 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 the [Contributing Guide](CONTRIBUTING.md).
## 📊 Status
## 📞 Support
For support and questions:
- Create an issue on GitHub
- Contact: luli245683@gmail.com
Raw data
{
"_id": null,
"home_page": "https://github.com/luli0034/rose-python-sdk",
"name": "rose-python-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "recommendation, machine learning, api, sdk, rose",
"author": "luli",
"author_email": "luli245683@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1b/f4/bbd1bdc0f97a5c93ebc28badb49bbf0269977b46e1690d9e22a9c6342758/rose_python_sdk-1.2.0.tar.gz",
"platform": null,
"description": "# Rose Python SDK\n\n<div align=\"center\">\n <img src=\"./docs/assets/images/rose-logo.png\" alt=\"Rose Python SDK\" width=\"200\" />\n</div>\n\nA 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.\n\n## \ud83d\ude80 Features\n\n- **Complete API Coverage**: Full support for all Rose Recommendation Service endpoints\n- **Type Safety**: Built with Pydantic for robust data validation and type hints\n- **Comprehensive Error Handling**: Detailed exception classes for different error scenarios\n- **Batch Operations**: Efficient batch data processing and upload capabilities\n- **Schema Management**: Automatic schema inference and validation\n- **Pipeline Management**: Intuitive pipeline creation and management tools\n- **Role-Based Access Control**: Complete permission and role management system\n- **Helper Functions**: High-level utilities for common operations\n\n## \ud83d\udce6 Installation\n\n```bash\npip install rose-python-sdk\n```\n\n## \ud83c\udfc3\u200d\u2642\ufe0f Quick Start\n\n### Basic Setup\n\n```python\nfrom rose_sdk import RoseClient\n\n# Initialize the client\nclient = RoseClient(\n base_url=\"https://admin.rose.blendvision.com\",\n access_token=\"your_access_token\"\n)\n```\n\n### Create a Dataset with Data\n\n```python\nfrom rose_sdk import quick_create_dataset_with_data\n\n# Create dataset with sample data\ndataset_id = quick_create_dataset_with_data(\n client=client,\n name=\"user_interactions\",\n records=[\n {\"user_id\": \"user1\", \"item_id\": \"item1\", \"rating\": 4.5},\n {\"user_id\": \"user1\", \"item_id\": \"item2\", \"rating\": 3.0},\n {\"user_id\": \"user2\", \"item_id\": \"item1\", \"rating\": 5.0}\n ],\n identifier_fields=[\"user_id\", \"item_id\"],\n required_fields=[\"rating\"]\n)\n```\n\n### Create a Recommendation Pipeline\n\n```python\nfrom rose_sdk.utils import create_pipeline\n\n# Create a pipeline with dataset mapping\npipeline_response = create_pipeline(\n client=client,\n account_id=\"your_account\",\n pipeline_name=\"recommendation_pipeline\",\n scenario=\"realtime_leaderboard\",\n dataset_mapping={\n \"interaction\": dataset_id, # Map pipeline key to your dataset\n \"metadata\": \"your_metadata_dataset_id\"\n }\n)\n```\n\n### Get Recommendations\n\n```python\n# Get recommendations for a user\nrecommendations = client.recommendations.get(\n query_id=\"your_query_id\",\n parameters={\"user_id\": \"user1\"}\n)\n\nprint(f\"Recommendations: {recommendations.data}\")\n```\n\n## \ud83d\udcda Documentation\n\n- **[Complete Documentation](https://luli0034.github.io/rose-python-sdk/)** - Full documentation with API reference, examples, and guides\n- **[GitHub Repository](https://github.com/luli0034/rose-python-sdk)** - Source code and issue tracking\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project\n\n## \ud83d\udcda Core Modules\n\n### 1. Client (`RoseClient`)\nThe main client class that provides access to all Rose services:\n\n```python\nclient = RoseClient(base_url=\"...\", access_token=\"...\")\n\n# Access different services\nclient.datasets.create(...) # Dataset management\nclient.pipelines.create(...) # Pipeline management \nclient.roles.create(...) # Role management\nclient.recommendations.get(...) # Get recommendations\n```\n\n### 2. Services\nOrganized service classes for different API endpoints:\n\n- **`DatasetService`**: Create, manage, and query datasets\n- **`PipelineService`**: Create and manage recommendation pipelines\n- **`RoleService`**: Manage user roles and permissions\n- **`RecommendationService`**: Get recommendations and query results\n\n### 3. Models\nType-safe data models using Pydantic:\n\n- **`Dataset`**: Dataset information and metadata\n- **`Pipeline`**: Pipeline configuration and status\n- **`Role`**: User roles and permissions\n- **`Query`**: Query definitions and results\n\n### 4. Utils\nUtility functions for common operations:\n\n- **Record Conversion**: Convert between Python and Rose data formats\n- **Schema Management**: Build and validate dataset schemas\n- **Batch Processing**: Handle large data uploads efficiently\n- **Pipeline Building**: Create pipelines with minimal configuration\n\n### 5. Helpers\nHigh-level helper functions for quick operations:\n\n- **`quick_create_dataset_with_data()`**: Create dataset and add data in one call\n- **`quick_batch_upload()`**: Upload large amounts of data efficiently\n- **`quick_setup_recommendation_system()`**: Complete end-to-end setup\n\n## \ud83d\udcd6 Examples\n\nThe SDK includes comprehensive examples in the `examples/` directory:\n\n### Role Management\n```bash\npython examples/01_role_management/01_basic_permissions.py\npython examples/01_role_management/02_api_usage.py\n```\n\n### Dataset Management\n```bash\npython examples/02_dataset_management/01_basic_datasets.py\npython examples/02_dataset_management/02_api_usage.py\n```\n\n### Records Management\n```bash\npython examples/03_records_management/01_basic_ingestion.py\npython examples/03_records_management/02_records_management.py\n```\n\n### Batch Data Management\n```bash\npython examples/04_batch_data_management/01_batch_append.py\npython examples/04_batch_data_management/02_batch_overwrite.py\n```\n\n### Pipeline Management\n```bash\npython examples/05_pipeline_management/01_create_pipeline.py\npython examples/05_pipeline_management/02_update_pipeline.py\npython examples/05_pipeline_management/04_delete_pipeline.py\npython examples/05_pipeline_management/05_list_queries.py\n```\n\n## \ud83d\udd27 Advanced Usage\n\n### Schema Validation\n\n```python\nfrom rose_sdk.utils import validate_and_align_records\n\n# Validate records against dataset schema\nvalidated_records = validate_and_align_records(\n dataset_id=dataset_id,\n records=your_records,\n client=client\n)\n```\n\n### Batch Operations\n\n```python\nfrom rose_sdk.utils import prepare_batch_data, get_batch_headers\n\n# Prepare large dataset for batch upload\nbatch_data = prepare_batch_data(records)\nheaders = get_batch_headers()\n\n# Upload in batches\nclient.datasets.batch.upload_batch(dataset_id, batch_id, batch_data)\n```\n\n### Pipeline Building\n\n```python\nfrom rose_sdk.utils import PipelineBuilder\n\n# Build complex pipeline configurations\npipeline_config = (PipelineBuilder(\"account\", \"pipeline_name\", \"scenario\")\n .add_dataset(\"interaction\", dataset_id)\n .add_dataset(\"metadata\", metadata_dataset_id)\n .set_custom_property(\"custom_setting\", \"value\")\n .build())\n```\n\n## \ud83d\udee0\ufe0f Error Handling\n\nThe SDK provides detailed exception classes for different error scenarios:\n\n```python\nfrom rose_sdk import (\n RoseAPIError,\n RoseAuthenticationError,\n RosePermissionError,\n RoseNotFoundError,\n RoseValidationError,\n RoseConflictError,\n RoseServerError,\n RoseTimeoutError\n)\n\ntry:\n dataset = client.datasets.get(\"invalid_id\")\nexcept RoseNotFoundError:\n print(\"Dataset not found\")\nexcept RoseAPIError as e:\n print(f\"API error: {e}\")\n```\n\n## \ud83d\udd10 Authentication\n\nThe SDK supports multiple authentication methods:\n\n```python\n# Access token authentication\nclient = RoseClient(\n base_url=\"https://admin.rose.blendvision.com\",\n access_token=\"your_token\"\n)\n\n# Environment variables\nimport os\nclient = RoseClient(\n base_url=os.getenv('ROSE_BASE_URL'),\n access_token=os.getenv('ROSE_ACCESS_TOKEN')\n)\n```\n\n## \ud83d\udccb Requirements\n\n- Python 3.11+\n- requests\n- pydantic\n- typing-extensions\n\n## \ud83e\udd1d Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## \ud83d\udcc4 License\n\nMIT License - see LICENSE file for details.\n\n## \ud83d\udd17 Links\n\n- [API Documentation](https://luli0034.github.io/rose-python-sdk/#/api-reference/overview)\n- [GitHub Repository](https://github.com/luli0034/rose-python-sdk)\n- [PyPI Package](https://pypi.org/project/rose-python-sdk/)\n\n## \ud83d\ude80 CI/CD\n\nThis project uses GitHub Actions for automated testing and publishing:\n\n- **Tests**: Automatically run on every push and pull request\n- **Publishing**: Automatically publish to PyPI when version tags are pushed\n- **Releases**: Automatically create GitHub releases\n\nFor setup instructions, see the [Contributing Guide](CONTRIBUTING.md).\n\n## \ud83d\udcca Status\n\n\n\n\n\n\n## \ud83d\udcde Support\n\nFor support and questions:\n- Create an issue on GitHub\n- Contact: luli245683@gmail.com\n",
"bugtrack_url": null,
"license": null,
"summary": "Python SDK for Rose Recommendation Service API",
"version": "1.2.0",
"project_urls": {
"Bug Reports": "https://github.com/luli0034/rose-python-sdk/issues",
"Documentation": "https://github.com/luli0034/rose-python-sdk/tree/main/docs",
"Homepage": "https://github.com/luli0034/rose-python-sdk",
"Source": "https://github.com/luli0034/rose-python-sdk"
},
"split_keywords": [
"recommendation",
" machine learning",
" api",
" sdk",
" rose"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "95ec3962be34114d86b3b36688242f6339fc33da67fb68c6f8058d4a54f42951",
"md5": "826eab0b0dd1889505314c2dae33e254",
"sha256": "7f433a09a5d8ef734cea6d847628236a6237fc44db2481a0d7cb3a5c715a40e4"
},
"downloads": -1,
"filename": "rose_python_sdk-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "826eab0b0dd1889505314c2dae33e254",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 40868,
"upload_time": "2025-10-27T07:33:53",
"upload_time_iso_8601": "2025-10-27T07:33:53.353088Z",
"url": "https://files.pythonhosted.org/packages/95/ec/3962be34114d86b3b36688242f6339fc33da67fb68c6f8058d4a54f42951/rose_python_sdk-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1bf4bbd1bdc0f97a5c93ebc28badb49bbf0269977b46e1690d9e22a9c6342758",
"md5": "669c03baf4133c38c13303cbd797f402",
"sha256": "db31424b27d9ecd585063546c56d31034471b0a553334e053c57e8c0b8f0666f"
},
"downloads": -1,
"filename": "rose_python_sdk-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "669c03baf4133c38c13303cbd797f402",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 91193,
"upload_time": "2025-10-27T07:33:54",
"upload_time_iso_8601": "2025-10-27T07:33:54.497863Z",
"url": "https://files.pythonhosted.org/packages/1b/f4/bbd1bdc0f97a5c93ebc28badb49bbf0269977b46e1690d9e22a9c6342758/rose_python_sdk-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 07:33:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "luli0034",
"github_project": "rose-python-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.0.0"
]
]
},
{
"name": "types-requests",
"specs": [
[
">=",
"2.32.0"
]
]
}
],
"lcname": "rose-python-sdk"
}
JSON
