Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 99 additions & 0 deletions .github/workflows/immunopeptidomics-reference.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
name: Immunopeptidomics Reference

on:
pull_request:
push:
branches:
- main
- 'reference/**'
workflow_dispatch:

permissions:
contents: read

jobs:
reference:
name: Synthetic scientific workflow and signed evidence
runs-on: ubuntu-24.04
timeout-minutes: 45
steps:
- name: Check out source
uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5

- name: Set up Rust
uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9
with:
toolchain: 1.91.0
targets: wasm32-unknown-unknown

- name: Set up Python
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
with:
python-version: '3.11'
cache: pip
cache-dependency-path: |
python/requirements.txt
python/requirements-immunopeptidomics.txt

- name: Cache Rust artifacts
uses: Swatinem/rust-cache@42dc69e1aa15d09112580998cf2ef0119e2e91ae # v2

- name: Install the declared Python environment
run: |
python -m pip install -r python/requirements-immunopeptidomics.txt
python -m pip check

- name: Test scientific semantics and failure handling
run: |
cargo test --locked --manifest-path examples/wasm-services/Cargo.toml -p immunopeptidomics
python -W error -m unittest python.tests.test_froglet_fl_evidence examples.test_immunopeptidomics_demo -v
python -W error integrations/openclaw/froglet/test/openshell-qualification-backend.test.py -v

- name: Build the node and scientific Wasm module
run: |
cargo build --locked --release -p froglet --bin froglet-node
cargo build --locked --release --target wasm32-unknown-unknown --manifest-path examples/wasm-services/Cargo.toml -p immunopeptidomics

- name: Run real local providers through NVIDIA FLARE components
run: >-
python examples/immunopeptidomics_demo.py
--binary target/release/froglet-node
--module examples/wasm-services/target/wasm32-unknown-unknown/release/immunopeptidomics.wasm
--output "${{ runner.temp }}/immunopeptidomics-success.json"

- name: Refuse incomplete output when a required provider is unavailable
run: |
set +e
python examples/immunopeptidomics_demo.py \
--binary target/release/froglet-node \
--module examples/wasm-services/target/wasm32-unknown-unknown/release/immunopeptidomics.wasm \
--unavailable-site site_b \
--output "$RUNNER_TEMP/immunopeptidomics-failure.json"
reference_status=$?
set -e
test "$reference_status" -eq 1
python - <<'PY'
import json, os
from pathlib import Path
report = json.loads((Path(os.environ['RUNNER_TEMP']) / 'immunopeptidomics-failure.json').read_text())
assert report['status'] == 'failed'
assert report['phase'] == 'collect_site_counts'
assert report['aggregate'] is None
assert set(report['workers']) == {'site_a'}
assert report['evidence']['missing_participants'] == ['site_b']
assert report['evidence']['output'] is None
PY

- name: Record installed dependency versions
if: always()
run: python -m pip freeze > "${{ runner.temp }}/immunopeptidomics-dependencies.txt"

- name: Retain reference evidence
if: always()
uses: actions/upload-artifact@v4
with:
name: immunopeptidomics-reference-evidence
path: |
${{ runner.temp }}/immunopeptidomics-*.json
${{ runner.temp }}/immunopeptidomics-dependencies.txt
if-no-files-found: warn
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,11 @@ Lightning rail and MCP registry distribution.

## [Unreleased]

### Added

- Synthetic immunopeptidomics reference: two provider-local SQLite datasets, NVIDIA FLARE task components, a bounded Wasm count workload, explicit denominators/missingness, signed evidence and incomplete-result rejection.
- Standalone OpenShell plugin qualification recipe and disposable local backend/probe; corrected directory-upload destinations in NemoClaw setup instructions and doctor output.

## [0.4.7-beta.1] - Prepared 2026-10-03

This section records the beta candidate at preparation, before immutable
Expand Down
135 changes: 135 additions & 0 deletions docs/IMMUNOPEPTIDOMICS_REFERENCE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,135 @@
# Synthetic immunopeptidomics with NVIDIA FLARE and Froglet

This reference asks a narrow question: among samples in a selected cohort whose
recorded HLA genotype contains the requested allele, how many accepted, available
assay results detected an exact candidate peptide?

It uses two synthetic sites, separate provider-local SQLite databases, and a
small Wasm computation. Installed NVIDIA FLARE Executor/DXO components dispatch
tasks from one Python process to real local Froglet nodes. It does not provision
a FLARE server/client network or connect to HLA-Compass production.

## Reproduce the reference

Use Python 3.11 and Rust 1.91.0 with `wasm32-unknown-unknown`. Install the optional
Python environment separately from your other applications:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r python/requirements-immunopeptidomics.txt
python -m pip check
rustup target add wasm32-unknown-unknown
cargo build --locked --release -p froglet --bin froglet-node
cargo build --locked --release --target wasm32-unknown-unknown \
--manifest-path examples/wasm-services/Cargo.toml -p immunopeptidomics
python examples/immunopeptidomics_demo.py \
--binary target/release/froglet-node \
--module examples/wasm-services/target/wasm32-unknown-unknown/release/immunopeptidomics.wasm \
--output /tmp/immunopeptidomics-success.json
```

Use an exact published commit for repeatable source selection and record
`git rev-parse HEAD`. The report includes source, binary, module, fixture and
provider database hashes, plus the installed FLARE version. The direct framework
dependencies are pinned; retain `python -m pip freeze` alongside the report to
record the complete installed environment. Execution requires FLARE 2.9.0 and
does not silently substitute another framework or an arithmetic-only path.

The default provider execution allowance is 30 seconds, including cold Wasm
compilation; `--execution-timeout-secs` accepts 1–300. Providers retain bounded
admission and execution limits. Successful runs remove temporary node state;
use `--keep-state` to retain it. Execution failures retain state and write a
failure report when `--output` is supplied. Invalid preflight arguments and
missing dependencies fail before node startup.

## Scientific contract and expected result

The [fixture contract](../examples/fixtures/immunopeptidomics/README.md),
[schema](../examples/fixtures/immunopeptidomics/schema.sql), and
[hand-labelled expectations](../examples/fixtures/immunopeptidomics/expected.json)
are part of the example. All samples, labels and detection calls are invented.

The query is an exact unmodified peptide sequence, an exact two-field class-I
HLA allele, a sample-class token and an organ token. HLA selection describes the
sample genotype; it does not identify the presenting allele or prove binding.
Known target alleles establish eligibility. If the target is absent, only
complete typing at the requested locus establishes nonmatching; incomplete or
missing typing remains unknown.

Only eligible samples with accepted, completed and available assay results form
the detection denominator. A sample with an explicitly empty accepted detection
set is measured but not detected. Failed or unavailable assays remain missing,
even if partial observation rows exist. Duplicate observations count once.

| Synthetic count | Site A | Site B | Pooled |
|---|---:|---:|---:|
| Selected cohort | 8 | 8 | 16 |
| Genotype eligible | 5 | 6 | 11 |
| Measured eligible | 3 | 5 | 8 |
| Candidate detected | 2 | 3 | 5 |
| Candidate not detected | 1 | 2 | 3 |
| Eligible assay missing | 2 | 1 | 3 |
| Genotype unknown | 2 | 1 | 3 |
| Genotype nonmatching | 1 | 1 | 2 |

The expected detection fraction is **5/8**, obtained by summing counts, not
averaging site percentages. When no eligible sample is measured, the fraction
is null rather than zero. The unit is a specimen; real integrations must address
duplicate specimens and technical replicates before pooling. This example does
not deduplicate donors across sites or establish population prevalence.

## Execution and evidence

1. The coordinator declares the required provider identities, module and exact
request/workload hashes.
2. FLARE components pass each query to a site executor, which requests a signed
Froglet computation under the provider's granted host-compute offer.
3. The Wasm module uses fixed parameterized read-only SQL through the local
`cohort` handle. Only counts, query metadata and interpretation labels are
returned; no sample rows, genotype lists or observation lists are returned.
4. The requester verifies each five-artifact chain and the result's canonical
JSON hash, validates the query/count contract, and compares the synthetic
output with an independent Python oracle.
5. A repeated submission must recover the same signed deal and result.
6. The aggregate is promoted only after every declared site has contributed and
the pooled result matches the independent oracle.

Each worker's report retains its signed artifacts and result for offline
rechecking. A valid signature establishes a recorded commitment and its chain;
it does not prove physical dataset identity or scientific correctness. The
completeness state is in memory, with no durable restart protocol or distributed
rollback.

## Failure and regression checks

```bash
cargo test --locked --manifest-path examples/wasm-services/Cargo.toml \
-p immunopeptidomics
python -W error -m unittest python.tests.test_froglet_fl_evidence \
examples.test_immunopeptidomics_demo -v
python examples/immunopeptidomics_demo.py \
--binary target/release/froglet-node \
--module examples/wasm-services/target/wasm32-unknown-unknown/release/immunopeptidomics.wasm \
--unavailable-site site_b --output /tmp/immunopeptidomics-failure.json
```

The last command intentionally exits with failure. Its JSON must retain Site A's
verified contribution, mark Site B missing, and contain no promoted aggregate.
An unavailable site is not interpreted as a site with zero detections. The
dedicated `Immunopeptidomics Reference` CI workflow runs both live paths and
retains the reports and dependency inventory.

## Interpretation and deployment boundary

Non-detection is not biological absence. This example consumes accepted peptide
calls; it does not reprocess spectra, validate false-discovery thresholds,
harmonize intensities, establish assay comparability, predict immunogenicity, or
assess clinical safety. It has no GPU requirement or GPU performance claim.

Aggregate counts can disclose information. The example has no small-cell
suppression, differential privacy, secure aggregation, or independently enforced
query budget. Use only the synthetic fixtures for this reference. A real data
deployment needs a defined scientific/export contract and disclosure policy.

Agent runtime qualification is separate; see [OpenShell/NemoClaw](NEMOCLAW.md).
35 changes: 28 additions & 7 deletions docs/NEMOCLAW.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,15 +46,23 @@ Supported plugin keys are the same as OpenClaw:

Use documented OpenShell/NemoClaw commands only.

Stage the plugin:
Stage the plugin and its shared library, preserving the repository's relative
directory layout. The plugin imports `integrations/shared/froglet-lib`; uploading
only the plugin directory leaves those imports unresolved. For a directory
upload, OpenShell retains the source directory's basename inside the destination,
so pass its parent directory as the destination:

```bash
openshell sandbox upload my-node \
/absolute/path/to/froglet/integrations/openclaw/froglet \
/sandbox/froglet/integrations/openclaw/froglet
/sandbox/froglet/integrations/openclaw
openshell sandbox upload my-node \
/absolute/path/to/froglet/integrations/shared/froglet-lib \
/sandbox/froglet/integrations/shared
```

Stage the Froglet control token:
Stage the Froglet control token. Unlike a directory upload, this unfiltered
single-file upload names the destination file:

```bash
openshell sandbox upload my-node \
Expand All @@ -64,11 +72,21 @@ openshell sandbox upload my-node \

If the host uses a private CA, stage that CA as well.

The token in this example is readable inside the sandbox. This staging flow
does not implement credential substitution outside the agent workload.

## Verification

Current status: source-level shared OpenClaw/NemoClaw plugin checks pass, but
real NemoClaw verification is not complete until a live NemoClaw/OpenShell
sandbox runs the plugin and calls one Froglet action.
Full NemoClaw-managed onboarding and plugin execution are not yet verified.
The [standalone OpenShell qualification](OPENSHELL_QUALIFICATION.md) is a separate
target: it uses OpenShell 0.1.7, while
[NemoClaw 0.0.142 pins OpenShell 0.0.116](https://github.com/NVIDIA/NemoClaw/blob/v0.0.142/nemoclaw-blueprint/blueprint.yaml#L7).
Do not treat a standalone OpenShell result as verification of that NemoClaw stack.

The plugin doctor checks the staged entrypoint, manifest and shared dependency
files without executing plugin code. An error produces a nonzero exit status;
a skipped runtime check remains a warning. Passing these checks does not verify
OpenShell policy enforcement or replace a real tool invocation in the sandbox.

```bash
nemoclaw my-node status
Expand All @@ -89,7 +107,10 @@ Minimum completion evidence:
```bash
openshell sandbox upload my-node \
/absolute/path/to/froglet/integrations/openclaw/froglet \
/sandbox/froglet/integrations/openclaw/froglet
/sandbox/froglet/integrations/openclaw
openshell sandbox upload my-node \
/absolute/path/to/froglet/integrations/shared/froglet-lib \
/sandbox/froglet/integrations/shared
openshell sandbox upload my-node \
/absolute/path/to/froglet-control.token \
/sandbox/.openclaw/froglet-control.token
Expand Down
Loading
Loading