From 2ec37c8fd164d0a1247385738eb8b260d676f019 Mon Sep 17 00:00:00 2001 From: OpenCode Date: Wed, 8 Jul 2026 15:17:42 +0700 Subject: [PATCH] Add 10 standards and external guides Closes #496, Closes #497, Closes #498, Closes #499, Closes #500, Closes #501, Closes #502, Closes #503, Closes #504, Closes #505 --- docs/evidence/GUIDE_ADAPTER_CAPABILITY.md | 23 +++++++++++++++++++ docs/evidence/GUIDE_ADAPTER_FAILURES.md | 22 ++++++++++++++++++ docs/evidence/GUIDE_EXTERNAL_CONSENT.md | 15 +++++++++++++ docs/evidence/GUIDE_OFFLINE_MODE.md | 22 ++++++++++++++++++ docs/evidence/GUIDE_OPTIONAL_DEPS.md | 27 +++++++++++++++++++++++ docs/evidence/GUIDE_PRIVACY_MODEL.md | 23 +++++++++++++++++++ docs/evidence/GUIDE_SECRETS_HANDLING.md | 21 ++++++++++++++++++ docs/evidence/STANDARD_ADAPTER_DOCS.md | 17 ++++++++++++++ docs/evidence/STANDARD_CSV_INPUT.md | 19 ++++++++++++++++ docs/evidence/STANDARD_JSONL_ARTIFACT.md | 18 +++++++++++++++ tests/test_standards_external_batch.py | 20 +++++++++++++++++ 11 files changed, 227 insertions(+) create mode 100644 docs/evidence/GUIDE_ADAPTER_CAPABILITY.md create mode 100644 docs/evidence/GUIDE_ADAPTER_FAILURES.md create mode 100644 docs/evidence/GUIDE_EXTERNAL_CONSENT.md create mode 100644 docs/evidence/GUIDE_OFFLINE_MODE.md create mode 100644 docs/evidence/GUIDE_OPTIONAL_DEPS.md create mode 100644 docs/evidence/GUIDE_PRIVACY_MODEL.md create mode 100644 docs/evidence/GUIDE_SECRETS_HANDLING.md create mode 100644 docs/evidence/STANDARD_ADAPTER_DOCS.md create mode 100644 docs/evidence/STANDARD_CSV_INPUT.md create mode 100644 docs/evidence/STANDARD_JSONL_ARTIFACT.md create mode 100644 tests/test_standards_external_batch.py diff --git a/docs/evidence/GUIDE_ADAPTER_CAPABILITY.md b/docs/evidence/GUIDE_ADAPTER_CAPABILITY.md new file mode 100644 index 00000000..55933be0 --- /dev/null +++ b/docs/evidence/GUIDE_ADAPTER_CAPABILITY.md @@ -0,0 +1,23 @@ +# Adapter Capability Reading Guide + +How to understand what an external adapter can and cannot do. + +## Required Documentation +Each adapter should document: +- What it models (scope) +- What it does NOT model (out of scope) +- Calibration data available +- Error handling behavior +- Resource requirements + +## Reading the SimulationResult +- `scope` — what was modeled (e.g., `bacterial_membrane_binding`) +- `scores` — the actual output values +- `uncertainty` — 0 = certain, 1 = completely uncertain +- `calibration_set` — what data was used for calibration (None = no calibration) +- `notes` — warnings, limitations, and context + +## Red Flags +- `uncertainty` > 0.5 — do not use for decision-making +- `calibration_set` is None — no evidence the adapter works +- `notes` mention `SIMULATION_THEATER_RISK` — adapter is speculative diff --git a/docs/evidence/GUIDE_ADAPTER_FAILURES.md b/docs/evidence/GUIDE_ADAPTER_FAILURES.md new file mode 100644 index 00000000..4865c14b --- /dev/null +++ b/docs/evidence/GUIDE_ADAPTER_FAILURES.md @@ -0,0 +1,22 @@ +# Adapter Failure Interpretation Guide + +How to interpret failures from external adapters. + +## Common Failure Modes +| Error | Likely Cause | Action | +|-------|-------------|--------| +| Connection refused | External service is down | Retry later, check service status | +| Timeout | Request took too long | Increase timeout or reduce request size | +| Rate limited | Too many requests | Reduce request frequency | +| Invalid response | Service returned unexpected data | Check adapter version compatibility | +| Authentication failed | Credentials are invalid | Update credentials | + +## Response Format +All adapters return a `SimulationResult` with: +- `module` — adapter name +- `version` — adapter version +- `scope` — what was modeled +- `scores` — dict of score key to value +- `uncertainty` — 0-1 scale +- `calibration_set` — reference to calibration data +- `notes` — human-readable notes about the result diff --git a/docs/evidence/GUIDE_EXTERNAL_CONSENT.md b/docs/evidence/GUIDE_EXTERNAL_CONSENT.md new file mode 100644 index 00000000..0bd238a3 --- /dev/null +++ b/docs/evidence/GUIDE_EXTERNAL_CONSENT.md @@ -0,0 +1,15 @@ +# External-Access Consent Note + +External adapters must not access network resources without explicit user consent. + +## Consent Rules +1. Adapters must declare whether they require network access. +2. Network access must be opt-in, not opt-out. +3. Users must be informed before any data is sent externally. +4. The purpose of the external access must be documented. +5. No credentials may be stored or transmitted without explicit consent. + +## Implementation +- Adapters should use `required_module` parameter in `ExternalSimulationAdapter`. +- Network-dependent adapters should document this in their class docstring. +- Local tests should not require network access. diff --git a/docs/evidence/GUIDE_OFFLINE_MODE.md b/docs/evidence/GUIDE_OFFLINE_MODE.md new file mode 100644 index 00000000..714154df --- /dev/null +++ b/docs/evidence/GUIDE_OFFLINE_MODE.md @@ -0,0 +1,22 @@ +# Offline Mode Explanation + +OpenAMP Foundry tools are designed to work offline by default. + +## What Works Offline +- All local checks: `check_doc_links.py`, `check_claims.py`, `check_pyproject.py` +- Lab result validation: `validate_lab_data_return.py`, `check_wave1_pass_fail.py` +- Negative archive validation: `validate_negative_archive.py` +- Panel CSV validation: `validate_panel_csv.py` +- Benchmark calculations +- All tests (after initial `pip install`) + +## What Requires Network +- Initial `pip install` +- Downloading reference databases for novelty checks +- External predictor submissions +- Novelty database refresh + +## Why Offline Matters +- Reproducibility — results should not depend on network availability +- Security — no data leakage through network calls +- Speed — local checks are faster than network-dependent ones diff --git a/docs/evidence/GUIDE_OPTIONAL_DEPS.md b/docs/evidence/GUIDE_OPTIONAL_DEPS.md new file mode 100644 index 00000000..3de87087 --- /dev/null +++ b/docs/evidence/GUIDE_OPTIONAL_DEPS.md @@ -0,0 +1,27 @@ +# Optional Dependency Explanation + +Some dependencies are optional and only needed for specific features. + +## Optional Extras +| Extra | Dependencies | Needed For | +|-------|-------------|------------| +| `dev` | pytest, ruff | Development and testing | +| `docs` | — | Building documentation (currently none required) | +| `external` | requests | External predictor submissions | + +## How to Install +```bash +# Core only +pip install openamp-foundry + +# With dev tools +pip install "openamp-foundry[dev]" + +# With everything +pip install "openamp-foundry[dev,external]" +``` + +## Checking What's Installed +```bash +pip list | grep openamp-foundry +``` diff --git a/docs/evidence/GUIDE_PRIVACY_MODEL.md b/docs/evidence/GUIDE_PRIVACY_MODEL.md new file mode 100644 index 00000000..8456c333 --- /dev/null +++ b/docs/evidence/GUIDE_PRIVACY_MODEL.md @@ -0,0 +1,23 @@ +# Privacy Model Overview + +How OpenAMP Foundry handles privacy and data. + +## Data Collected +- Candidate sequences (provided by the user) +- Lab result data (provided by the user) +- Pipeline output files (stored locally) + +## Data NOT Collected +- No telemetry +- No analytics +- No usage statistics +- No personal information + +## Data Sharing +- Adapters do not send data without explicit user consent. +- External predictors require user-initiated submission. +- No data is shared with third parties without user action. + +## Local-Only Guarantee +All core pipeline operations run locally. No data leaves your machine +unless you explicitly use an external adapter or predictor. diff --git a/docs/evidence/GUIDE_SECRETS_HANDLING.md b/docs/evidence/GUIDE_SECRETS_HANDLING.md new file mode 100644 index 00000000..aa68b62e --- /dev/null +++ b/docs/evidence/GUIDE_SECRETS_HANDLING.md @@ -0,0 +1,21 @@ +# Secret-Handling Warning Page + +OpenAMP Foundry does not handle secrets, credentials, or tokens. + +## What We Do NOT Store +- API keys +- Passwords +- Tokens +- Certificates +- Any authentication material + +## If You Need Secrets +Secrets for external services (e.g., predictor APIs) must be handled outside +the pipeline. Use environment variables or a secrets manager. + +## Safety Rules +1. Never commit secrets to the repository. +2. Never hard-code credentials in scripts or adapters. +3. Use environment variables for any required authentication. +4. Document which environment variables are needed in the adapter docs. +5. The `.env` file is git-ignored; use it for local development. diff --git a/docs/evidence/STANDARD_ADAPTER_DOCS.md b/docs/evidence/STANDARD_ADAPTER_DOCS.md new file mode 100644 index 00000000..1a903336 --- /dev/null +++ b/docs/evidence/STANDARD_ADAPTER_DOCS.md @@ -0,0 +1,17 @@ +# Adapter Documentation Standard + +External adapters must document: + +## Required +- What the adapter does +- What external resource it connects to +- Whether network access is required +- Required dependencies +- Version of the external resource + +## Recommended +- Example usage +- Expected output format +- Known limitations +- Error handling behavior +- Rate limiting considerations diff --git a/docs/evidence/STANDARD_CSV_INPUT.md b/docs/evidence/STANDARD_CSV_INPUT.md new file mode 100644 index 00000000..0ec4bb01 --- /dev/null +++ b/docs/evidence/STANDARD_CSV_INPUT.md @@ -0,0 +1,19 @@ +# CSV Input Documentation Standard + +CSV input files must document: + +## Required Columns +- `candidate_id` — unique identifier for each candidate +- `sequence` — amino acid sequence (standard single-letter codes) +- `source` — origin of the candidate (generated, imported, seed-derived) + +## Optional Columns +- `batch` — batch name or ID +- `family` — scaffold family name +- Any score columns that were used for selection + +## Header +CSV files must have a header row with column names. Column names should use snake_case. + +## Encoding +UTF-8 with BOM is accepted. ASCII is preferred. diff --git a/docs/evidence/STANDARD_JSONL_ARTIFACT.md b/docs/evidence/STANDARD_JSONL_ARTIFACT.md new file mode 100644 index 00000000..47432b38 --- /dev/null +++ b/docs/evidence/STANDARD_JSONL_ARTIFACT.md @@ -0,0 +1,18 @@ +# JSONL Artifact Documentation Standard + +JSONL (JSON Lines) files used by the pipeline must follow this standard. + +## Format +- One JSON object per line +- No separator between objects (newline only) +- UTF-8 encoding +- Each line must be valid JSON + +## Required Fields +- `candidate_id` +- `sequence` +- `scores` — dict of score key to value + +## Naming +- Use `.jsonl` extension +- File name should describe the content (e.g., `demo_ranked.jsonl`) diff --git a/tests/test_standards_external_batch.py b/tests/test_standards_external_batch.py new file mode 100644 index 00000000..047da84b --- /dev/null +++ b/tests/test_standards_external_batch.py @@ -0,0 +1,20 @@ +"""Tests for standards and external guides batch.""" +from pathlib import Path + +FILES = [ + "STANDARD_CSV_INPUT.md", + "STANDARD_JSONL_ARTIFACT.md", + "STANDARD_ADAPTER_DOCS.md", + "GUIDE_OFFLINE_MODE.md", + "GUIDE_OPTIONAL_DEPS.md", + "GUIDE_ADAPTER_FAILURES.md", + "GUIDE_EXTERNAL_CONSENT.md", + "GUIDE_ADAPTER_CAPABILITY.md", + "GUIDE_PRIVACY_MODEL.md", + "GUIDE_SECRETS_HANDLING.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path("docs/evidence", f).exists(), f"Missing: {f}"