Quickstart Guide

Get started with EdgeML in 5 minutes. This guide shows you how to run federated training across multiple devices.

Installation

pip install edgeml-sdk

Get Your API Key

1. Go to app.edgeml.io
2. Create an account or sign in
3. Copy your API key from the dashboard

Your API key starts with ek_live_...

Example: Image Classifier

Let's train an image classifier across 3 simulated devices.

Step 1: Create a Model

First, create and register a model:

import edgeml

# Initialize model registry
registry = edgeml.ModelRegistry(
    api_key="ek_live_..."
)

# Create a model in the catalog
model = registry.ensure_model(
    name="mnist-classifier",
    framework="pytorch",
    use_case="image_classification",
    description="MNIST digit classifier"
)

print(f"Model created: {model['id']}")

Step 2: Upload Initial Model

Upload a trained PyTorch model:

import torch
import torch.nn as nn

# Define a simple model
class SimpleNN(nn.Module):
    def __init__(self):
        super().__init__()
        self.fc1 = nn.Linear(784, 128)
        self.fc2 = nn.Linear(128, 10)

    def forward(self, x):
        x = torch.relu(self.fc1(x))
        return self.fc2(x)

# Create and save model
model = SimpleNN()
torch.save(model.state_dict(), "model_v0.1.0.pt")

# Upload to EdgeML
registry.upload_version_from_path(
    model_id=model['id'],
    file_path="model_v0.1.0.pt",
    version="0.1.0",
    description="Initial model",
    formats="onnx,tflite"  # Auto-convert to mobile formats
)

Step 3: Simulate Edge Devices

Create 3 devices that will participate in training:

import torch
import torch.nn as nn
from torch.utils.data import DataLoader, TensorDataset

# Simulate local data for device
def get_local_data(device_id):
    # In production, this would be real local data
    X = torch.randn(100, 784)
    y = torch.randint(0, 10, (100,))
    return DataLoader(TensorDataset(X, y), batch_size=32)

# Training function for edge device
def train_locally(base_state_dict):
    """Train on local data and return updated weights"""
    model = SimpleNN()
    model.load_state_dict(base_state_dict)

    # Get local data
    data_loader = get_local_data("device-001")

    # Train for 1 epoch
    optimizer = torch.optim.SGD(model.parameters(), lr=0.01)
    loss_fn = nn.CrossEntropyLoss()

    total_samples = 0
    total_loss = 0.0

    for X_batch, y_batch in data_loader:
        optimizer.zero_grad()
        outputs = model(X_batch)
        loss = loss_fn(outputs, y_batch)
        loss.backward()
        optimizer.step()

        total_samples += len(X_batch)
        total_loss += loss.item() * len(X_batch)

    avg_loss = total_loss / total_samples

    return model.state_dict(), total_samples, {"loss": avg_loss}

# Create federated client for each device
clients = []
for i in range(3):
    client = edgeml.FederatedClient(
        api_key="ek_live_...",
        device_identifier=f"device-{i:03d}"
    )
    client.join_federation("my-federation")
    clients.append(client)

Step 4: Run Federated Training

Now let the devices train collaboratively:

# Each device trains locally and submits updates
for round_num in range(5):
    print(f"\n🔄 Round {round_num + 1}/5")

    for i, client in enumerate(clients):
        print(f"  Device {i} training...")

        results = client.train_from_remote(
            model="mnist-classifier",
            local_train_fn=train_locally,
            rounds=1,
            update_format="delta"  # Send weight deltas (more efficient)
        )

        print(f"  Device {i} submitted: {results[0]['sample_count']} samples")

Step 5: Aggregate on Server

Run server-side aggregation (FedAvg):

# Initialize federation (server-side)
federation = edgeml.Federation(
    api_key="ek_live_...",
    name="my-federation"
)

# Run aggregation
result = federation.train(
    model="mnist-classifier",
    algorithm="fedavg",
    rounds=5,
    min_updates=3,  # Wait for all 3 devices
    base_version="0.1.0",
    new_version="0.2.0"
)

print(f"✅ New model version: {result['new_version']}")

Step 6: Deploy to Production

Deploy the new model with progressive rollout:

# Deploy with gradual rollout
deployment = federation.deploy(
    model_id=model['id'],
    version="0.2.0",
    rollout_percentage=10,      # Start with 10% of devices
    target_percentage=100,       # Eventually reach 100%
    increment_step=10,           # Increase by 10% each step
    start_immediately=True
)

print(f"🚀 Deployment created: {deployment['id']}")

Complete Example

Here's the full code in one script:

import edgeml
import torch
import torch.nn as nn
from torch.utils.data import DataLoader, TensorDataset

# 1. Setup
API_KEY = "ek_live_..."

# 2. Define model
class SimpleNN(nn.Module):
    def __init__(self):
        super().__init__()
        self.fc1 = nn.Linear(784, 128)
        self.fc2 = nn.Linear(128, 10)

    def forward(self, x):
        x = torch.relu(self.fc1(x))
        return self.fc2(x)

# 3. Training function
def train_locally(base_state_dict):
    model = SimpleNN()
    model.load_state_dict(base_state_dict)

    # Simulate local data
    X = torch.randn(100, 784)
    y = torch.randint(0, 10, (100,))
    data_loader = DataLoader(TensorDataset(X, y), batch_size=32)

    # Train
    optimizer = torch.optim.SGD(model.parameters(), lr=0.01)
    loss_fn = nn.CrossEntropyLoss()

    total_samples = 0
    for X_batch, y_batch in data_loader:
        optimizer.zero_grad()
        loss = loss_fn(model(X_batch), y_batch)
        loss.backward()
        optimizer.step()
        total_samples += len(X_batch)

    return model.state_dict(), total_samples, {"loss": loss.item()}

# 4. Create and upload initial model
registry = edgeml.ModelRegistry(api_key=API_KEY)
model_info = registry.ensure_model(
    name="mnist-classifier",
    framework="pytorch",
    use_case="image_classification"
)

initial_model = SimpleNN()
torch.save(initial_model.state_dict(), "model_v0.1.0.pt")
registry.upload_version_from_path(
    model_id=model_info['id'],
    file_path="model_v0.1.0.pt",
    version="0.1.0"
)

# 5. Simulate 3 devices training
clients = [
    edgeml.FederatedClient(api_key=API_KEY, device_identifier=f"device-{i:03d}")
    for i in range(3)
]

for client in clients:
    client.join_federation("my-federation")
    client.train_from_remote(
        model="mnist-classifier",
        local_train_fn=train_locally,
        rounds=5
    )

# 6. Aggregate (server-side)
federation = edgeml.Federation(api_key=API_KEY, name="my-federation")
result = federation.train(
    model="mnist-classifier",
    rounds=5,
    min_updates=3,
    base_version="0.1.0",
    new_version="0.2.0"
)

# 7. Deploy
federation.deploy(
    version="0.2.0",
    rollout_percentage=10,
    target_percentage=100
)

print("✅ Federated training complete!")

Next Steps

• Python SDK Reference - Complete API documentation
• Concepts - Learn how federated learning works
• Model Lifecycle - Understand model versioning

Common Issues

"Model not found"

Make sure you created the model with ModelRegistry.ensure_model() first.

"Insufficient updates"

If min_updates is set too high, aggregation will wait for more devices. Lower it for testing.

"Authentication failed"

Check that your API key is correct and starts with ek_live_...

Need Help?

• Dashboard: app.edgeml.io
• Email: bsudarshan@outlook.com