MedusClient (0.1.10)
Installation
pip install --index-url About this package
Python client library for MedusEdgeBack API with smart media upload, video processing, and flexible configuration
medusclient
medusclient is a Python client library for interacting with the MedusEdgeBack API. It provides a simple and intuitive interface for managing datasets, model weights, training jobs, and media files, making it easy to integrate machine learning workflows into your applications.
The library features smart media upload capabilities with automatic method selection, video processing with preview generation, and a flexible configuration system that supports both programmatic and command-line usage.
Features
- Smart Media Upload: Automatic method selection (direct upload vs presigned URL) based on file size and type
- Video Processing: Automatic video preview generation with FFmpeg support
- Dataset Management: Create, list, retrieve, download, and delete datasets with flexible configurations
- Weights Handling: Upload, list, and download model weights with support for presigned URLs
- Training Jobs: Initiate and monitor training jobs with customizable configurations
- Media Operations: Upload, list, retrieve, and delete media files (images, videos, labels, etc.)
- Configuration Management: Flexible configuration through JSON files and command-line arguments
- Comprehensive Examples: Ready-to-use example scripts with detailed configuration options
- Type-Safe: Fully typed with MyPy for robust development
- Well-Tested: Comprehensive unit tests with >90% coverage
- Modern Tooling: Built with Poetry, Ruff, Pytest, Sphinx, and GitHub Actions
Installation
Prerequisites
- Python: Version 3.8 or higher.
- pip or Poetry: For dependency management and installation.
Install via pip
To install medusclient from PyPI:
pip install medusclient
Install via Poetry
If you prefer Poetry for dependency management:
poetry add medusclient
Verify Installation
Confirm the package is installed correctly:
python -c "import medusclient; print(medusclient.__version__)"
This should output the installed version (e.g., 0.1.0).
Quick Start
Here's a basic example of using medusclient to authenticate and interact with the MedusEdgeBack API:
from medusclient import ApiClient
# Initialize the client
client = ApiClient(api_base_url="http://localhost/api")
# Authenticate
auth_response = client.authenticate("admin@medusai.ai", "123Qwe123")
if auth_response["success"]:
print("Authenticated successfully")
# Upload media with automatic method selection
upload_response = client.media.upload_media(
project_id="6812af855526f3a857d85810",
file_path="./my_image.jpg",
metadata={"source": "quick_start", "version": "1.0"}
)
if upload_response["success"]:
print(f"Media uploaded: {upload_response['id']}")
# List media files
media_list = client.media.list_media(project_id="6812af855526f3a857d85810")
if media_list["success"]:
for item in media_list["items"]:
print(f"Media: {item['filename']} (Type: {item['fileType']})")
# Create a dataset from media
if media_list["success"] and len(media_list["items"]) >= 5:
media_ids = [item["id"] for item in media_list["items"][:5]]
dataset_response = client.datasets.create_dataset_from_media(
project_id="6812af855526f3a857d85810",
name="My Dataset",
description="Created from media",
dataset_type="detection",
media_ids=media_ids,
split_ratio={"train": 0.7, "valid": 0.2, "test": 0.1}
)
if dataset_response["success"]:
print(f"Dataset created: {dataset_response['dataset']['id']}")
Using the Example Script
The package includes a comprehensive example script (examples/example.py) with configuration support:
# Run with default configuration
python examples/example.py --enable-media
# Run with custom configuration file
python examples/example.py --config my_config.json --enable-all
# Run with command-line overrides
python examples/example.py --api-url http://localhost:4001/api --username admin@test.com
For detailed examples and configuration options, see the Usage Documentation.
Configuration System
medusclient includes a flexible configuration system that supports multiple configuration sources with the following priority:
- Command-line arguments (highest priority)
- Environment variables
- Configuration file (JSON)
- Default values (lowest priority)
Configuration File (config.json)
The examples/config.json file provides a template for configuring the client:
{
"api": {
"url": "http://localhost/api",
"username": "admin@medusai.ai",
"password": "123Qwe123",
"project_id": "6812af855526f3a857d85810"
},
"files": {
"image_path": "/path/to/image.jpg",
"video_path": "/path/to/video.mp4",
"weights_path": "/path/to/model.pth"
},
"operations": {
"enable_dataset_operations": false,
"enable_weights_operations": false,
"enable_media_operations": true
},
"media": {
"metadata": {
"source": "example_script",
"version": "2.0"
},
"wait_for_ready": true,
"max_wait_time": 180
},
"outputs": {
"output_directory": "output"
},
"logging": {
"level": "INFO"
}
}
Example Script Usage
The examples/example.py script demonstrates comprehensive usage:
# Basic usage with configuration file
python examples/example.py --config config.json
# Enable specific operations
python examples/example.py --enable-media --enable-datasets
# Override configuration with command-line arguments
python examples/example.py --api-url http://localhost:4001/api --username admin@test.com
# Upload specific files
python examples/example.py --image-path ./my_image.jpg --video-path ./my_video.mp4
# Set logging level
python examples/example.py --log-level DEBUG --enable-media
The example script supports:
- Dynamic configuration loading from JSON files
- Smart media upload with automatic method selection
- Video processing with preview generation
- Dataset creation from uploaded media
- Weights management for model files
- Comprehensive error handling and logging
Project Architecture
The medusclient package follows a modular and maintainable structure, adhering to the cookiecutter-modern-pypackage template. Below is the project file tree and an explanation of key components:
MedusClient/
├── .github/
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.md
│ │ └── feature_request.md
│ └── workflows/
│ └─── ci.yml # GitHub Actions for CI
├── docs/
│ ├── _static/
│ │ └── logo.png # Custom logo for documentation
│ ├── conf.py # Sphinx configuration
│ ├── index.rst # Documentation homepage
│ ├── installation.rst # Installation instructions
│ ├── usage.rst # Usage examples
│ ├── examples.rst # Examples and configuration guide
│ └── api/ # API documentation
│ ├── client.rst
│ ├── datasets.rst
│ ├── weights.rst
│ ├── training.rst
│ ├── media.rst
│ └── utils.rst
├── examples/
│ ├── config.json # Configuration template
│ └── example.py # Comprehensive example script
├── src/
│ └── medusclient/
│ ├── __init__.py # Package initialization
│ ├── client.py # Main ApiClient class
│ ├── datasets.py # Dataset operations
│ ├── weights.py # Weights operations
│ ├── training.py # Training job operations
│ ├── media.py # Media operations
│ └── utils.py # Utility functions
├── tests/
│ ├── __init__.py # Tests package initialization
│ ├── test_client.py # Tests for client.py
│ ├── test_datasets.py # Tests for datasets.py
│ ├── test_weights.py # Tests for weights.py
│ ├── test_training.py # Tests for training.py
│ ├── test_media.py # Tests for media.py
│ └── test_utils.py # Tests for utils.py
├── .bumpversion.cfg # Version bump configuration
├── .gitignore # Git ignore patterns
├── .pre-commit-config.yaml # Pre-commit hooks
├── .readthedocs.yml # Read the Docs configuration
├── .safety-policy.yml # Safety dependency checks
├── CHANGELOG.md # Project changelog
├── codecov.yml # Codecov configuration
├── noxfile.py # Nox automation
├── poetry.lock # Poetry dependency lock
├── pyproject.toml # Project configuration
├── README.md # This file
├── tasks.py # Invoke tasks (optional)
└── LICENSE # MIT license
Key Components
-
Examples (
examples/):example.py: Comprehensive example script with dynamic configuration, smart media upload, and all API operationsconfig.json: Configuration template with detailed options for API, files, operations, and logging
-
Source Code (
src/medusclient/):client.py: DefinesApiClient, the main entry point for API interactions, composing operation classes.datasets.py: Handles dataset-related operations (list, create, download, etc.).weights.py: Manages model weights (upload, download, list).training.py: Controls training jobs (create, status).media.py: Manages media files with smart upload selection (upload, list, delete).utils.py: Provides utility functions (HTTP requests, MIME type detection).
-
Tests (
tests/):- Comprehensive unit tests for all modules, achieving >90% coverage.
- Uses Pytest with mocking for isolated testing.
-
Documentation (
docs/):- Built with Sphinx and hosted on Read the Docs.
- Includes installation, usage, and API documentation.
-
Configuration:
pyproject.toml: Defines project metadata, dependencies, and tool configurations (Poetry, Pytest, Ruff, MyPy).poetry.lock: Locks dependency versions for reproducibility..pre-commit-config.yaml: Enforces code quality with Ruff and MyPy hooks.noxfile.py: Automates testing, linting, type checking, and documentation builds.
-
CI/CD:
- GitHub Actions workflows (
ci.yml,release.yml) for testing, linting, and publishing. - Codecov integration for coverage reporting.
- GitHub Actions workflows (
Development Setup
To contribute to medusclient or run it locally, follow these steps:
Prerequisites
- Python: 3.8 or higher.
- Poetry: For dependency management.
curl -sSL https://install.python-poetry.org | python3 - - Git: For version control.
- Pre-commit: For code quality hooks.
pip install pre-commit
Clone the Repository
git clone https://gitea.moyskleytech.com/MedusAI/MedusClient
cd medusclient
Install Dependencies
Install project and development dependencies using Poetry:
poetry install --with dev
This creates a virtual environment and installs dependencies like requests, pytest, ruff, mypy, and sphinx.
Set Up Pre-commit Hooks
Enable pre-commit hooks to enforce code quality:
poetry run pre-commit install
Run Quality Checks
-
Run Tests: Execute unit tests with coverage:
poetry run pytest --cov=medusclient --cov-report=xml --cov-report=htmlView the coverage report in
htmlcov/index.html. -
Lint Code: Check code style with Ruff:
poetry run ruff check .Auto-fix issues:
poetry run ruff check . --fix -
Type Check: Verify type safety with MyPy:
poetry run mypy src tests -
Build Documentation: Generate documentation:
poetry run sphinx-build docs docs/_buildOpen
docs/_build/index.htmlto view. -
Run All Checks: Use Nox to run all checks:
nox
Project Structure for Developers
- Source Code: Add new features or fix bugs in
src/medusclient/. - Tests: Write corresponding unit tests in
tests/, following the existing structure. - Documentation: Update
docs/with new features or changes, using RST format. - Configuration: Modify
pyproject.tomlfor new dependencies or tool settings.
Building the Package
To generate a distributable package:
-
Update Version: Increment the version in
pyproject.toml:poetry version patch # e.g., 0.1.0 -> 0.1.1 -
Build the Package: Create source distribution and wheel:
poetry buildOutput files are in
dist/:dist/ ├── medusclient-0.1.1-py3-none-any.whl ├── medusclient-0.1.1.tar.gz -
Test the Package Locally: Create a virtual environment:
python -m venv test-env source test-env/bin/activate # On Windows: test-env\Scripts\activateInstall the wheel:
pip install dist/medusclient-0.1.1-py3-none-any.whlVerify:
from medusclient import ApiClient print(ApiClient(api_base_url="http://localhost/api").api_base_url)Deactivate:
deactivate
License
medusclient is licensed under the MIT License.
Acknowledgements
Built with the cookiecutter-modern-pypackage template, leveraging open-source tools: