Metadata-Version: 2.4
Name: mantatech-sdk
Version: 0.6b0.dev565
Summary: Unified Manta SDK for distributed computing and federated learning. Provides both high-level API client and lightweight task execution runtime.
Author-email: Benjamin BOURBON <benjaminbourbon@manta-tech.io>, Hugo Miralles <hugo.miralles@manta-tech.io>, Matthew Thompson <matthew.thompson@manta-tech.io>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/mantatech/manta-sdk
Project-URL: Repository, https://github.com/mantatech/manta-sdk
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Embedded Systems
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: betterproto[compiler]==2.0.0b7
Requires-Dist: msgpack
Requires-Dist: blake3
Requires-Dist: grpclib>=0.4.9
Requires-Dist: pydantic<3.0.0,>=2.13.4
Requires-Dist: rich
Requires-Dist: manta-common-core<=0.6b0,>=0.6b0.dev0
Provides-Extra: light
Requires-Dist: numpy; extra == "light"
Provides-Extra: sdk
Requires-Dist: toml; extra == "sdk"
Requires-Dist: tomli; python_version < "3.11" and extra == "sdk"
Requires-Dist: tomli-w; extra == "sdk"
Requires-Dist: cryptography>=50.0.0; extra == "sdk"
Requires-Dist: PyYAML>=6.0; extra == "sdk"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: torch; extra == "test"
Requires-Dist: grpcio-tools; extra == "test"
Provides-Extra: docs
Requires-Dist: furo; extra == "docs"
Requires-Dist: enum-tools[sphinx]; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Provides-Extra: code-analytics
Requires-Dist: ruff; extra == "code-analytics"
Requires-Dist: pytest-cov; extra == "code-analytics"
Requires-Dist: coverage-badge; extra == "code-analytics"
Provides-Extra: examples
Requires-Dist: marimo>=0.9; extra == "examples"
Requires-Dist: torch; extra == "examples"
Requires-Dist: torchvision; extra == "examples"
Provides-Extra: all
Requires-Dist: mantatech-sdk[code-analytics,docs,light,sdk,test]; extra == "all"
Dynamic: license-file

![Version](https://img.shields.io/badge/version-0.6b0-orange)
![Python version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20-blue)
![Coverage Badge](.github/coverage/coverage.svg)
![Ruff](https://img.shields.io/badge/code_style-ruff-2a1833)

# 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](https://docs.manta-tech.io/)**

- [Getting Started](https://docs.manta-tech.io/getting-started/)
- [SDK Usage](https://docs.manta-tech.io/sdk-usage/)
- [Node Guide](https://docs.manta-tech.io/node-guide/)
- [Tutorials](https://docs.manta-tech.io/tutorials/)
- [Examples](examples/) — four runnable scripts: federated learning and its non-federated control, on MNIST and CIFAR-10

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

## Installation Options

### For Task Execution (Lightweight - Recommended for Containers)

```bash
pip install mantatech-sdk[light]
```

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

### For API Client Development

```bash
pip install mantatech-sdk[api]
```

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

### For CLI Usage

```bash
pip install mantatech-sdk[cli]
```

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

### Full Installation

```bash
pip install mantatech-sdk[full]
```

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

### Development Installation

```bash
pip install mantatech-sdk[all]
```

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

## Quick Start

### API Client Usage

```python
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)

```python
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

```bash
# 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`

```python
# 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`

```python
# 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:

```bash
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:

```python
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:

```python
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](https://docs.manta-tech.io/) — getting started, SDK usage, node guide, tutorials
- [SDK Architecture](https://github.com/mantatech/manta-deploy/blob/main/docs/components/sdk/ARCHITECTURE.md) — modular design, async/sync patterns, configuration system (internal)
- [SDK Development](https://github.com/mantatech/manta-deploy/blob/main/docs/components/sdk/DEVELOPMENT.md) — developer setup, testing, code quality (internal)
- [Examples](examples/) — four runnable scripts: federated learning and its non-federated control, on MNIST and CIFAR-10

## 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 with a linking exception for `manta.light` (ADR-0027) — see [LICENSE](LICENSE) file for details.

Importing `manta.light` from your own code does not make your program a derivative work; the copyleft terms of the AGPL continue to apply to `manta.apis` and `manta.cli`.
