mantatech-sdk 0.5b0.dev74

Unified Manta SDK for distributed computing and federated learning. Provides both high-level API client and lightweight task execution runtime.

Manta SDK

The Manta SDK is a unified Python library for distributed computing and federated learning on the Manta platform. It combines the functionality of both the high-level API client and the lightweight task execution runtime into a single, flexible package.

Features

• 🚀 Unified API: Single package for both client operations and task execution
• 📦 Modular Installation: Install only what you need with optional dependencies
• 🐳 Container Optimized: Lightweight [light] mode for minimal container footprint
• 🔄 Async/Sync APIs: Full async support with sync wrappers for convenience
• 🖥️ CLI Tools: Command-line interface for cluster and swarm management
• 🔒 Secure: JWT authentication with optional mTLS support

Documentation

📚 Full documentation: docs.manta-tech.io

• Getting Started
• SDK Usage
• Node Guide
• Tutorials
• Examples — federated training notebooks (CIFAR-10, MNIST)

Source: docs/source/ (Sphinx + Furo). Build locally with cd docs && make html.

Installation Options

For Task Execution (Lightweight - Recommended for Containers)

pip install mantatech-sdk[light]

This installs only the minimal dependencies needed for task execution within containers (~50MB smaller).

For API Client Development

pip install mantatech-sdk[api]

This installs the full client SDK for deploying and managing swarms from your application.

For CLI Usage

pip install mantatech-sdk[cli]

This installs the command-line tools for interactive cluster and swarm management.

Full Installation

pip install mantatech-sdk[full]

This installs all features: API client, task execution runtime, and CLI tools.

Development Installation

pip install mantatech-sdk[all]

This installs all features plus testing, documentation, and code analysis tools.

Quick Start

API Client Usage

import manta
from manta.apis import AsyncUserAPI
import asyncio

async def main():
    # Initialize API client
    api = AsyncUserAPI(
        token="your_jwt_token",
        host="localhost",
        port=50052
    )
    
    # Check service availability
    available = await api.is_available()
    print(f"Service available: {available}")
    
    # Get cluster API for specific cluster
    cluster_api = api.get_async_cluster_api("cluster_id")
    
    # Deploy a swarm
    swarm_overview = await cluster_api.deploy_swarm(swarm_definition)
    print(f"Deployed swarm: {swarm_overview.swarm_id}")
    
    # Stream results in real-time
    async for result in cluster_api.stream_results(swarm_id, tag="metrics"):
        print(f"Result: {result.data}")

if __name__ == "__main__":
    asyncio.run(main())

Task Execution Usage (Inside Containers)

from manta.light import Local, World, Results, Task
import numpy as np

# Initialize task runtime
task = Task()
local = Local()
world = World()
results = Results()

# Load data from cluster
data = local.load_data("training_data")

# Get global parameters
global_model = world.get("model_weights")

# Perform computation
model = train_model(data, global_model)
accuracy = evaluate_model(model, data)

# Save results
results.save({"accuracy": accuracy}, tag="metrics")
world.set("model_weights", model.state_dict())

CLI Usage

# Configure connection
manta config set --host localhost --port 50052 --token your_jwt_token

# List available clusters
manta cluster list

# Deploy a swarm
manta simulation deploy --swarm-file swarm.py --cluster-id cluster_123

# Monitor swarm execution
manta simulation logs --swarm-id swarm_456

# Stop running swarm
manta simulation stop --swarm-id swarm_456

API Modules

manta.apis - High-Level Client SDK

Access via: from manta.apis import AsyncUserAPI or import manta; api = manta.api

• AsyncUserAPI / UserAPI: User operations and swarm management
• AsyncClusterAPI / ClusterAPI: Cluster-specific operations
• Swarm, Task, Module: High-level swarm definition classes

manta.light - Task Execution Runtime

Access via: from manta.light import Local or import manta; light = manta.light

• Local: Access to cluster data and local resources
• World: Global state management across tasks
• Results: Result saving and sharing
• Task: Task runtime information and utilities

Migration from Previous Packages

From manta-core

# Old import (still works - backwards compatible)
from manta import AsyncUserAPI, Swarm, Task

# New recommended import pattern
import manta
from manta.apis import AsyncUserAPI, Swarm, Task
# Or access via: api_module = manta.api

From manta-light

# Old import  
from manta_light import Local, World, Results

# New import (same functionality)
from manta.light import Local, World, Results

Container Optimization

The SDK is designed for optimal container usage:

Light Mode (Recommended for Tasks):

• Install: pip install mantatech-sdk[light]
• Size: ~50MB smaller than full installation
• Contains: Task execution runtime only
• Use case: Inside task containers

Full Mode (For Development/CLI):

• Install: pip install mantatech-sdk[full]
• Contains: Complete client SDK + task runtime
• Use case: Development machines, CI/CD pipelines

Advanced Usage

Environment Variables

Configure the SDK using environment variables:

export MANTA_HOST=localhost
export MANTA_PORT=50052
export MANTA_TOKEN=your_jwt_token
export MANTA_CERT_FOLDER=/path/to/certs  # For mTLS

Secure Connections

For production environments with mTLS:

from manta.apis import AsyncUserAPI

api = AsyncUserAPI(
    token="your_jwt_token",
    host="prod-manager.example.com", 
    port=50052,
    cert_folder="/etc/manta/certs"  # Contains ca.crt, client.crt, client.key
)

Swarm Definition

Create complex swarms with task dependencies:

from manta.apis import Swarm, Task, Module

# Define algorithm module
module = Module(
    name="federated_learning",
    python_program="fl_trainer.py",
    image="ghcr.io/mantatech/manta-light:pytorch"
)

# Define tasks with dependencies
aggregator = Task(
    name="aggregator",
    module=module,
    command="python fl_trainer.py --role aggregator",
    replicas=1
)

workers = Task(
    name="worker",
    module=module,
    command="python fl_trainer.py --role worker", 
    replicas=5
)

# Create swarm
swarm = Swarm(
    name="federated_mnist",
    tasks=[aggregator, workers],
    iteration=10,
    circular=True
)

Further reading

• User docs — getting started, SDK usage, node guide, tutorials
• SDK Architecture — modular design, async/sync patterns, configuration system (internal)
• SDK Development — developer setup, testing, code quality (internal)
• Examples — federated training notebooks (CIFAR-10, MNIST)

Contributing

1. Install development dependencies: pip install mantatech-sdk[all]
2. Run tests: python -m pytest tests/
3. Check code style: ruff check manta/
4. Format code: ruff format manta/

License

AGPL-3.0 - see LICENSE file for details.

Note: A dual AGPL-3.0 + Commercial license model is planned. Until that ADR is Accepted and the LICENSE file restructure ships, this repo remains under AGPL-3.0.