Metadata-Version: 2.4
Name: mantatech-sdk
Version: 0.6b5.dev692
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.6b5,>=0.6b5.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.6b5-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

> **Beta.** The SDK is in beta and every published release is a pre-release (`pip install "mantatech-sdk>=0.6b5.dev0"`).
> New to the platform? Start with the **[beta quickstart](https://docs.manta-tech.io/getting-started/beta-quickstart.html)**: install, token, list your clusters, deploy a minimal module.

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

Every published release is a pre-release, so each command below carries the version specifier that lets pip select one. The extras are the ones `pyproject.toml` defines: `light`, `sdk`, `examples`, `test`, `docs`, `code-analytics` and `all`.

### API Client

```bash
pip install "mantatech-sdk>=0.6b5.dev0"
```

The base install is enough to import `manta.apis` and deploy and manage swarms from your application.

### For Task Execution

```bash
pip install "mantatech-sdk[light]>=0.6b5.dev0"
```

Adds `numpy`, used by the `manta.light` array helpers.

### For CLI Usage

```bash
pip install "mantatech-sdk[sdk]>=0.6b5.dev0"
```

Adds the TOML/YAML configuration and `cryptography` dependencies the `manta` command-line tool uses.

### Examples

```bash
pip install "mantatech-sdk[examples]>=0.6b5.dev0"
```

Adds `marimo`, `torch` and `torchvision` for the bundled examples.

### Development Installation

```bash
pip install "mantatech-sdk[all]>=0.6b5.dev0"
```

Installs `sdk`, `light`, `test`, `docs` and `code-analytics`. It does not include `examples`.

## 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]>=0.6b5.dev0"`
- Contains: Task execution runtime
- Use case: Inside task containers

**With the CLI (For Development)**:

- Install: `pip install "mantatech-sdk[sdk]>=0.6b5.dev0"`
- Contains: Client SDK + task runtime + the `manta` CLI's configuration dependencies
- Use case: Development machines, CI/CD pipelines

## Advanced Usage

### Configuration

The SDK reads no `MANTA_*` environment variables. Connection settings come
from the arguments you pass, or from a configuration saved under
`~/.manta/sdk/` by the `manta` CLI (which needs the `[sdk]` extra):

```bash
# Prompts for the host, the port and the token (masked as you type it)
manta sdk config init --interactive --name prod
```

```python
import manta
from manta.apis import AsyncUserAPI

# From a saved configuration: the active one, or one by name
api = manta.configure_from_config("prod")

# Or sign in with your email and password
api = await AsyncUserAPI.sign_in(
    "you@example.com", "your-password", host="api.manta-tech.io", port=443
)
```

### 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,
    cafile="/etc/manta/certs/ca.crt",
    certfile="/etc/manta/certs/client.crt",
    keyfile="/etc/manta/certs/client.key",
)
```

The synchronous `UserAPI` also accepts `cert_folder="/etc/manta/certs"`, and
picks up `ca.crt`, `client.crt` and `client.key` from that folder.

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