resontech 0.1.1__tar.gz

resontech-0.1.1/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 ResonTech
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

resontech-0.1.1/MANIFEST.in

@@ -0,0 +1,15 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+prune tests
+prune docs
+prune .pytest_cache
+prune build
+prune dist
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude *.so
+global-exclude .DS_Store
+global-exclude .git*

resontech-0.1.1/PKG-INFO

@@ -0,0 +1,468 @@
+Metadata-Version: 2.4
+Name: resontech
+Version: 0.1.1
+Summary: SDK for submitting federated learning jobs to the ResonTech platform
+Author: ResonTech
+License-Expression: Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: boto3<1.41,>=1.34
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: fastapi>=0.111; extra == "dev"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: moto[s3]>=5; extra == "dev"
+Dynamic: license-file
+
+# ResonTech SDK
+
+Python SDK for submitting federated learning jobs to the ResonTech platform.
+
+The SDK is **task-agnostic** — it does not assume a specific task (image
+classification, NLP, regression, segmentation, RL, …), dataset format, loss,
+or optimizer. You write your model and a one-round training function; the SDK
+ships them to every worker and plumbs global weights in/out of the federation.
+
+The SDK's job ends at submission. Progress, logs, output files, and the final
+model are tracked on the web dashboard — the ``Job`` returned from ``rt_submit``
+carries a ``dashboard_url`` you can open to follow along.
+
+---
+
+## Installation
+
+```bash
+pip install resontech
+# or, from source:
+pip install -e /path/to/sdk
+```
+
+**Requirements:** Python 3.11+, `httpx`, `boto3`. PyTorch is required on the
+worker side (NVFlare workflow runs on PyTorch state dicts).
+
+---
+
+## Setup — once per user
+
+1. Log in to the ResonTech web UI.
+2. Go to **Profile → Storage** and click **Provision Bucket**.
+3. Copy the ``accessKeyId`` and ``secretAccessKey`` it shows you — the secret
+   is only displayed once. These are what the SDK uses to upload directly to
+   your bucket.
+
+No SSH keys, no SFTP — everything goes over the S3 API.
+
+---
+
+## The user contract
+
+Define your model class **and** an `fl_train` function in the same module
+(or notebook cell). The SDK extracts the file/cell verbatim and ships it as
+`model_def.py`. Each round, the worker:
+
+1. Loads the latest global weights into your model.
+2. Calls `fl_train(model, env, out_dir, logger)`.
+3. Sends the returned weights back for aggregation.
+
+```python
+class Model(nn.Module):                       # any name, any signature
+    def __init__(self, **kwargs):             # gets ModelConfig.model_args
+        super().__init__()
+        ...
+    def forward(self, x): ...
+
+def fl_train(model, env, out_dir, logger=None) -> dict:
+    """
+    env contains: CURRENT_ROUND, SITE_NAME, JOB_ID, DATA_ROOT,
+                  EPOCHS, BATCH_SIZE, LR, plus every key from TrainingConfig.extra.
+    Returns: {"weights": dict[str, Tensor], "samples": int, ...}
+    """
+    # You own the dataset, loss, optimizer, training loop.
+    return {"weights": model.state_dict(), "samples": N}
+
+def fl_validate(model, env, out_dir, logger=None) -> dict:    # optional
+    ...
+```
+
+---
+
+## Quick start (image classification)
+
+```python
+import json, os
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader, Dataset
+from torchvision import models, transforms
+
+from resontech import (
+    ResonTech, ResonTechConfig,
+    TrainingConfig, FederationConfig, ModelConfig,
+)
+
+
+class MyResNet(nn.Module):
+    def __init__(self, num_classes: int = 10):
+        super().__init__()
+        self.backbone = models.resnet18(weights=None)
+        self.backbone.fc = nn.Linear(self.backbone.fc.in_features, num_classes)
+
+    def forward(self, x):
+        return self.backbone(x)
+
+
+def fl_train(model, env, out_dir, logger=None):
+    img_size = int(env.get("IMG_SIZE", 224))
+    num_classes = int(env.get("NUM_CLASSES", 10))
+    manifest = os.path.join(env["DATA_ROOT"], env.get("MANIFEST_FILE", "manifest.ndjson"))
+
+    class _Dataset(Dataset):
+        def __init__(self, path):
+            from PIL import Image, ImageFile
+            ImageFile.LOAD_TRUNCATED_IMAGES = True
+            self.records = [json.loads(l) for l in open(path) if l.strip()]
+            self.tx = transforms.Compose([
+                transforms.Resize(max(img_size, 256)),
+                transforms.CenterCrop(img_size),
+                transforms.ToTensor(),
+                transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
+            ])
+
+        def __len__(self): return len(self.records)
+
+        def __getitem__(self, i):
+            from PIL import Image
+            rec = self.records[i]
+            with Image.open(rec["uri"]) as img:
+                x = self.tx(img.convert("RGB"))
+            y = torch.zeros(num_classes)
+            for j in rec.get("y", []):
+                y[int(j)] = 1.0
+            return x, y
+
+    ds = _Dataset(manifest)
+    loader = DataLoader(ds, batch_size=env["BATCH_SIZE"], shuffle=True)
+    optimizer = torch.optim.Adam(model.parameters(), lr=env["LR"])
+    loss_fn = nn.BCEWithLogitsLoss()
+    device = next(model.parameters()).device
+
+    model.train()
+    for _ in range(int(env["EPOCHS"])):
+        for x, y in loader:
+            x, y = x.to(device), y.to(device)
+            optimizer.zero_grad(set_to_none=True)
+            loss_fn(model(x), y).backward()
+            optimizer.step()
+
+    return {
+        "weights": {k: v.detach().cpu() for k, v in model.state_dict().items()},
+        "samples": len(ds),
+    }
+
+
+config = ResonTechConfig(
+    base_url="https://api.reson.tech",
+    email="you@example.com",
+    password="your-password",
+    s3_access_key_id="AKIA...",
+    s3_secret_access_key="...",
+)
+
+sdk = ResonTech(config)
+sdk.login()
+
+job = sdk.rt_submit(
+    model=MyResNet,
+    name="my-fl-job",
+    shards_dir="./shards",
+    requirements_txt="./requirements.txt",
+    training=TrainingConfig(
+        local_epochs=2,
+        batch_size=32,
+        learning_rate=1e-3,
+        extra={"IMG_SIZE": 224, "NUM_CLASSES": 10, "MANIFEST_FILE": "manifest.ndjson"},
+    ),
+    federation=FederationConfig(num_rounds=5, min_clients=1),
+    model_config=ModelConfig(model_args={"num_classes": 10}),
+)
+
+print(f"Submitted: {job.id}")
+print(f"Track at:  {job.dashboard_url}")
+```
+
+For NLP, tabular, regression, segmentation, RL, etc., **replace `fl_train`**
+with whatever your task needs. The SDK does not change.
+
+---
+
+## Core concepts
+
+### Model requirements
+
+The user's model class can have any signature. The constructor receives
+**only** the keys you put in `ModelConfig.model_args` — the SDK injects
+nothing of its own.
+
+### Dataset shards
+
+Each worker receives one file from `shards_dir` (one shard per worker).
+Mounted under `env["DATA_ROOT"]` on the worker. The SDK does not enforce a
+file format — your `fl_train` decides how to read whatever you uploaded
+(NDJSON manifests, parquet, raw images, HDF5, anything).
+
+### What the SDK uploads for you
+
+`sdk.rt_submit(...)` writes directly to `s3://<your-bucket>/jobs/<name>/`:
+
+```
+jobs/<name>/
+├── scripts/
+│   ├── model_def.py                  ← your file/cell, verbatim
+│   ├── custom_client_executor.py     ← bundled GenericClientExecutor (or your own)
+│   └── custom_persistor.py
+├── configs/
+│   ├── config_fed_client.json
+│   ├── config_fed_server.json
+│   └── meta.json
+├── requirements/
+│   └── requirements.txt
+├── shards/
+│   ├── shard_0.zip
+│   └── …
+└── model/                            ← optional warm-start weights
+    └── checkpoint.pt
+```
+
+No local temp directories are created. Shards stream from your disk directly
+via S3 multipart (50 MB parts, 5 concurrent).
+
+---
+
+## API reference
+
+### `ResonTechConfig`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `base_url` | str | — | REST API base URL (HTTPS required for non-loopback hosts) |
+| `email` | str | — | Account email |
+| `password` | str | — | Account password |
+| `s3_access_key_id` | str | — | Garage S3 access key (from the UI) |
+| `s3_secret_access_key` | str | — | Garage S3 secret (from the UI) |
+| `s3_bucket_alias` | str | `""` | Bucket alias — auto-resolved on login if empty |
+| `s3_endpoint` | str | `https://s3.reson.tech` | S3-compatible endpoint URL |
+| `s3_region` | str | `"garage"` | AWS region label |
+| `dashboard_url` | str | `https://app.reson.tech` | Web UI base used in the tracking message |
+
+### `TrainingConfig`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `local_epochs` | int | `1` | Local epochs per round → `env["EPOCHS"]` |
+| `batch_size` | int | `32` | Mini-batch size hint → `env["BATCH_SIZE"]` |
+| `learning_rate` | float | `0.001` | Optimiser LR hint → `env["LR"]` |
+| `extra` | dict | `{}` | Free-form, task-specific knobs merged into `env` |
+
+Anything task-specific — image size, num_classes, sequence length, optimizer
+name, mixup alpha, etc. — goes into `extra` and reaches your `fl_train`
+function via the `env` dict, with no SDK interpretation.
+
+### `ModelConfig`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `model_class` | str | auto | Importable path to the model class (auto-filled by `rt_submit`) |
+| `model_args` | dict | `{}` | Kwargs forwarded to the model constructor on every site |
+| `adapter_module` | str | `"model_def"` | Module the executor imports |
+| `train_fn` | str | `"fl_train"` | Name of the user training function |
+| `validate_fn` | str | `"fl_validate"` | Name of the optional user validation function |
+
+### `FederationConfig`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `num_rounds` | int | `5` | Total training rounds |
+| `min_clients` | int | `1` | Clients required per round |
+| `wait_time_after_min_received` | int | `10` | Seconds to wait after min clients respond |
+| `heart_beat_timeout` | int | `600` | Client heartbeat timeout (seconds) |
+| `job_name` | str | `"rt_job"` | Name stored in job metadata |
+| `aggregator_path` / `aggregator_args` | str / dict | `InTimeAccumulateWeightedAggregator` w/ `expected_data_kind="WEIGHTS"` | Server-side aggregator |
+| `shareable_generator_path` / `shareable_generator_args` | str / dict | `FullModelShareableGenerator` | Wraps weights into NVFlare Shareables |
+| `workflow_path` / `workflow_extra_args` | str / dict | `ScatterAndGather` | Server workflow — swap in FedProx, FedOpt, cyclic, swarm, etc. |
+
+### `ResonTech`
+
+#### `sdk.login() → User`
+
+Authenticates and sets the JWT token. Auto-resolves `s3_bucket_alias` via
+`GET /api/users/storage/bucket` if not set. Raises `StorageError` if the
+user has not provisioned a bucket yet.
+
+#### `sdk.rt_submit(...) → Job`
+
+Render, upload, and submit a federated learning job in one call.
+
+```python
+job = sdk.rt_submit(
+    model=MyResNet,                      # nn.Module subclass (required)
+    name="my-fl-job",                    # display name (required)
+    shards_dir="./shards",               # local directory of shard files (required)
+    requirements_txt="./req.txt",        # optional
+    training=TrainingConfig(...),
+    federation=FederationConfig(...),
+    model_config=ModelConfig(...),       # optional (auto-filled from class name)
+    executor=None,                       # custom NVFlare Executor class (optional)
+    persistor=None,                      # custom NVFlare ModelPersistor class (optional)
+    model_checkpoint="./warmstart.pt",   # optional warm-start file
+    estimated_memory_mb=None,            # VRAM hint in MB (optional)
+    worker_ids=None,                     # explicit list (optional)
+    auto_select_workers=False,           # let server pick (optional)
+    only_mine_workers=False,             # restrict to your own nodes
+)
+```
+
+#### `sdk.storage`
+
+Thin boto3 wrapper pointed at the user's bucket. Exposes `put_bytes`,
+`upload_file`, `head`, `list`, `presign_get`. Useful for double-checking
+what landed in the bucket or sharing a download URL.
+
+#### `sdk.dashboard.worker_stats() → WorkerStats`
+
+Returns the current cluster availability (online workers, free VRAM).
+
+#### `sdk.jobs`
+
+`JobsResource` — low-level job submission and retrieval (`submit`, `get`,
+`list`). Prefer `rt_submit` unless you have already uploaded a workspace.
+
+### `Job`
+
+Thin handle returned by `rt_submit` and `jobs.submit`.
+
+| Attribute | Description |
+|-----------|-------------|
+| `job.id` | Unique job ID |
+| `job.name` | Job name |
+| `job.state` | Initial `JobState` returned by the API |
+| `job.dashboard_url` | URL to the job detail page on the web UI |
+
+`JobState` values: `PENDING`, `RUNNING`, `FINISHED`, `FAILED`.
+
+---
+
+## Advanced: custom executor / persistor
+
+Pass your own NVFlare subclasses to override the bundled defaults. The SDK
+extracts their source the same way it does for the model:
+
+```python
+from nvflare.apis.executor import Executor
+
+class MyExecutor(Executor): ...   # full control over the per-round flow
+
+job = sdk.rt_submit(
+    model=MyResNet,
+    name="custom-fl-job",
+    shards_dir="./shards",
+    executor=MyExecutor,
+)
+```
+
+Note: a custom executor *replaces* `GenericClientExecutor` entirely — it does
+not have to obey the `fl_train(model, env, out_dir, logger)` contract. You
+own the whole NVFlare task lifecycle.
+
+## Advanced: swap the workflow / aggregator
+
+`FederationConfig` exposes the NVFlare component paths. Replace the defaults
+with FedProx, FedOpt, cyclic, hierarchical, or any other workflow:
+
+```python
+federation = FederationConfig(
+    num_rounds=10,
+    workflow_path="nvflare.app_common.workflows.cyclic.Cyclic",
+    aggregator_path="nvflare.app_opt.pt.fedopt.PTFedOptModelShareableGenerator",
+    aggregator_args={"optimizer_args": {"lr": 0.01}},
+)
+```
+
+## Advanced: inspect generated configs
+
+`RTJobBuilder` renders configs and scripts as strings — no disk writes:
+
+```python
+from resontech.rt.builder import RTJobBuilder
+
+builder = RTJobBuilder(training_config=training, federation_config=federation)
+configs = builder.render_configs()              # {"client": "...", "server": "...", "meta": "..."}
+scripts = builder.render_scripts(MyResNet)      # {"model_def.py": "...", ...}
+
+print(configs["client"])
+```
+
+---
+
+## Troubleshooting
+
+**`StorageError: No S3 bucket configured`**
+You haven't provisioned a bucket yet. Go to the web UI's Profile → Storage
+page and click "Provision Bucket", then copy the secret key into
+`ResonTechConfig`.
+
+**`StorageError: ... AccessDenied`**
+The credentials in `s3_access_key_id` / `s3_secret_access_key` do not
+match the bucket on your account. Rotate them from Profile → Storage →
+Rotate Key and try again.
+
+**`ValidationError: shards_dir is not a directory` or empty shards list**
+Each worker needs its own shard file. Drop them into `shards_dir` as
+`shard_0.zip`, `shard_1.zip`, … (one per worker).
+
+**`name 'nn' is not defined` (server-side error)**
+Put all imports (`import torch`, `import torch.nn as nn`, …) in the
+**same notebook cell** as your model class and `fl_train`. The SDK extracts
+the whole cell verbatim — anything outside that cell does not travel.
+
+**`User module 'model_def' does not define class 'X'`** or
+**`... does not define 'fl_train'`**
+Your model class and `fl_train` function must live in the file/cell that
+the SDK extracts. If you renamed either, adjust `ModelConfig.model_class`
+and `ModelConfig.train_fn` accordingly.
+
+---
+
+## Documentation
+
+Focused guides live in [`docs/`](docs):
+
+- [Getting started](docs/getting-started.md)
+- [Configuration reference](docs/configuration.md)
+- [Training hyperparameters](docs/training-hyperparameters.md)
+- [Custom classes](docs/custom-classes.md) — model, executor, persistor
+- [Storage](docs/storage.md) — bucket layout and uploads
+- [Job lifecycle](docs/job-lifecycle.md) — states and outputs
+- [Troubleshooting](docs/troubleshooting.md)
+
+## Runnable examples
+
+Examples live outside the published package, in the project repository:
+
+- `submit_job.py` — minimal script demonstrating the `fl_train` contract.
+- `01_quickstart.ipynb` — walk-through notebook mirroring this README.
+- `02_custom_hyperparameters.ipynb` — using `TrainingConfig.extra`.
+- `03_custom_executor_persistor.ipynb` — replacing the bundled NVFlare classes.
+- `04_warmstart_and_inspection.ipynb` — pre-trained checkpoint + bucket inspection.
+
+Set the following environment variables before running any of them:
+`RT_BASE_URL`, `RT_EMAIL`, `RT_PASSWORD`,
+`RT_S3_ACCESS_KEY_ID`, `RT_S3_SECRET_ACCESS_KEY`,
+and optionally `RT_S3_ENDPOINT`.