feat: harden O-QT evidence contracts and live validation

Author: senseibelbi

.env.example

@@ -13,3 +13,18 @@ BYPASS_AUTH=False
 
 # O-QT QSAR Toolbox WebAPI Connection
 QSAR_TOOLBOX_API_URL=http://localhost:5000
+
+# Optional QSAR Toolbox client tuning
+# These settings are useful when your Toolbox host is slow or load-sensitive.
+# The MCP favors bounded, explicit partial results over indefinite waiting.
+# QSAR_LIGHT_TIMEOUT_SECONDS=30
+# QSAR_HEAVY_TIMEOUT_SECONDS=300
+# QSAR_LIGHT_MAX_ATTEMPTS=2
+# QSAR_HEAVY_MAX_ATTEMPTS=3
+# QSAR_HEAVY_CONCURRENCY=3
+
+# Optional bounded-response safeguards for expensive discovery and hazard helpers
+# QSAR_HAZARD_PROFILING_WALLCLOCK_TIMEOUT_SECONDS=25
+# QSAR_DISCOVERY_LIST_ALL_TOTAL_WALLCLOCK_TIMEOUT_SECONDS=45
+# QSAR_DISCOVERY_LIST_ALL_PER_POSITION_TIMEOUT_SECONDS=6
+# QSAR_DISCOVERY_SEARCH_DATABASES_WALLCLOCK_TIMEOUT_SECONDS=20

README.md

@@ -63,6 +63,8 @@ The current implementation follows a layered model:
 - Final suite-level evidence synthesis, BER/WoE logic, and cross-module decisions belong above O-QT in a downstream orchestrator.
 
 See [docs/architecture.md](docs/architecture.md) for the fuller boundary and contract notes.
+See [docs/oecd_alignment_review_2025.md](docs/oecd_alignment_review_2025.md) for the OECD 2025 grouping/IUCLID gap analysis and the next contract-focused improvements.
+See [docs/cross_suite_alignment_2026.md](docs/cross_suite_alignment_2026.md) for the local AOP/CompTox contract patterns adopted into O-QT.
 
 ## What's New In v0.2.0
 
@@ -71,6 +73,7 @@ This is a maturity and contract release, not a redesign.
 - Re-aligned repository identity, package metadata, and release notes around `ToxMCP/oqt-mcp`.
 - Clarified the public surface as a primary workflow engine plus secondary expert tools.
 - Published portable O-QT handoff schemas for hazard evidence, read-across support, and workflow provenance.
+- Hardened the hazard handoff with explicit evidence blocks, applicability-domain review, and richer provenance records for audit-grade downstream review.
 - Added explicit downstream-orchestration documentation and examples for contract consumers.
 - Documented the current synchronous deployment model instead of implying an async platform that does not exist yet.
 
@@ -116,7 +119,7 @@ The O-QT MCP server turns that workflow into an **open, programmable interface**
 | --- | --- |
 | **Primary workflow engine** | Calls the OECD QSAR Toolbox WebAPI to run searches, profilers, metabolism simulators, curated QSAR models, and the flagship `run_oqt_multiagent_workflow` entrypoint. |
 | **Grouping/read-across support** | Builds OECD-style grouping dossiers through `build_grouping_justification` with structured similarity and uncertainty reporting. |
-| **Portable handoff contracts** | Publishes stable cross-suite handoff schemas for downstream orchestrators and other contract consumers. |
+| **Portable handoff contracts** | Publishes stable cross-suite handoff schemas for downstream orchestrators and other contract consumers, including evidence blocks, applicability-domain review, and attachment manifests. |
 | **Regulatory-ready reporting** | Generates a comprehensive PDF (ReportLab), Markdown narrative, and JSON provenance bundle. |
 | **Enterprise security** | OAuth2/OIDC token validation, RBAC per tool, audit logging, and Docker hardening. |
 | **Agent friendly** | Tested with Claude Code, Codex CLI, and Gemini CLI (see [integration guide](docs/integration_guides/mcp_integration.md)). |
@@ -186,6 +189,15 @@ Once running, your MCP host connects to `http://localhost:8000/mcp`.
 | Variable | Required | Default | Description |
 | --- | --- | --- | --- |
 | `QSAR_TOOLBOX_API_URL` | ✅ | `http://localhost:5000` | Base URL to the OECD QSAR Toolbox WebAPI. |
+| `QSAR_LIGHT_TIMEOUT_SECONDS` | Optional | `30` | Per-request timeout for lightweight Toolbox calls. |
+| `QSAR_HEAVY_TIMEOUT_SECONDS` | Optional | `300` | Per-request timeout for expensive Toolbox calls such as reports, workflows, and some simulations. |
+| `QSAR_LIGHT_MAX_ATTEMPTS` | Optional | `2` | Retry count for lightweight Toolbox calls. |
+| `QSAR_HEAVY_MAX_ATTEMPTS` | Optional | `3` | Retry count for expensive Toolbox calls. |
+| `QSAR_HEAVY_CONCURRENCY` | Optional | `3` | Concurrency cap for heavy Toolbox calls issued by the MCP. |
+| `QSAR_HAZARD_PROFILING_WALLCLOCK_TIMEOUT_SECONDS` | Optional | `25` | Wall-clock cap for the profiling sweep inside `analyze_chemical_hazard`; returns explicit partial evidence if exceeded. |
+| `QSAR_DISCOVERY_LIST_ALL_TOTAL_WALLCLOCK_TIMEOUT_SECONDS` | Optional | `45` | Total wall-clock budget for `list_all_qsar_models`. |
+| `QSAR_DISCOVERY_LIST_ALL_PER_POSITION_TIMEOUT_SECONDS` | Optional | `6` | Per-endpoint-tree-position timeout while enumerating the QSAR model catalog. |
+| `QSAR_DISCOVERY_SEARCH_DATABASES_WALLCLOCK_TIMEOUT_SECONDS` | Optional | `20` | Wall-clock cap for `list_search_databases`; fails fast on timeout. |
 | `AUTH_OIDC_ISSUER` | ✅ (prod) | – | OIDC issuer URL (Auth0, Keycloak, etc.). |
 | `AUTH_OIDC_AUDIENCE` | ✅ (prod) | – | Expected audience in access tokens. |
 | `AUTH_OIDC_ALGORITHMS` | ✅ (prod) | `["RS256"]` | Allowed JWT algorithms. |
@@ -200,6 +212,8 @@ Once running, your MCP host connects to `http://localhost:8000/mcp`.
 
 Compatibility note: the current client targets Toolbox WebAPI `/api/v6` routes. Newer Toolbox builds are supported as long as they keep the v6 compatibility layer enabled.
 
+Operational note: on slower Toolbox hosts, prefer tuning the wall-clock safeguards above rather than only increasing retry counts. The MCP is designed to return explicit partial evidence or timeout errors, not to block indefinitely on discovery-heavy endpoints.
+
 See [docs/auth_testing.md](docs/auth_testing.md) for token generation tips and bypass mode safety.
 
 ---
@@ -228,8 +242,8 @@ See [docs/auth_testing.md](docs/auth_testing.md) for token generation tips and b
 | `get_endpoint_tree` | Returns the endpoint taxonomy used to organise profilers and models. |
 | `get_metadata_hierarchy` | Returns the metadata hierarchy useful for filtering experimental data. |
 | `list_qsar_models` | Lists QSAR models for a specific endpoint tree position. |
-| `list_all_qsar_models` | Enumerates the full QSAR catalog across the endpoint tree (deduplicated). |
-| `list_search_databases` | Enumerates searchable inventories in the QSAR Toolbox. |
+| `list_all_qsar_models` | Enumerates the full QSAR catalog across the endpoint tree (deduplicated). Returns partial catalog metadata and warnings if enumeration exceeds the configured wall-clock budget. |
+| `list_search_databases` | Enumerates searchable inventories in the QSAR Toolbox. Fails fast on timeout rather than waiting through the full heavy retry budget. |
 | `run_qsar_model` | Runs a specific QSAR model for a chemId and reports applicability domain status. |
 | `run_profiler` | Executes a profiler for a chemId (optionally providing a simulator). |
 | `run_metabolism_simulator` | Runs a metabolism simulator using either a chemId or SMILES. |
@@ -301,8 +315,26 @@ See [docs/auth_testing.md](docs/auth_testing.md) for token generation tips and b
 - `build_grouping_justification` adds a `grouping_justification` object with target/analogue resolution, similarity assessment, endpoint conclusions, and uncertainty reporting.
 - `pdf_report_base64` – base64-encoded, publication-ready PDF.
 - `portable_handoffs` – schema-aligned handoff objects for downstream orchestration. `build_grouping_justification` returns `oqtWorkflowRecord.v1` plus `oqtReadAcrossSummary.v1`; `run_oqt_multiagent_workflow` returns `oqtWorkflowRecord.v1` plus `oqtHazardEvidenceSummary.v1`.
+- `oqtWorkflowRecord.v1` now declares `rootEntity`, `packageSemantics`, and an auditable `attachments` manifest with checksums when the inline payload is available.
+- `oqtHazardEvidenceSummary.v1` now carries request metadata, explicit assessment and decision boundaries, support claims, required external inputs, endpoint summaries, source attribution for model/profiler/simulator evidence, and a qualitative uncertainty block with `semanticCoverage` that explicitly states it is an evidence-completeness assessment rather than a probabilistic estimate.
+- `oqtReadAcrossSummary.v1` now promotes explicit assessment and decision boundaries, required external inputs, applicability-domain notes, the portable evidence matrix, and the aspect-level uncertainty table into the published handoff contract.
 - Portable downstream contracts are published separately under `schemas/`; see [schemas/README.md](schemas/README.md).
 
+### Metadata & provenance fields
+
+The MCP exposes normalized provenance wherever the Toolbox already returns ownership or study metadata:
+
+- `get_public_qsar_model_info`, `get_profiler_info`, `get_simulator_info`, and `get_calculator_info` include a top-level `provenance` block.
+- `list_qsar_models` and `list_all_qsar_models` attach a compact `provenance_summary` to each catalog record.
+- `run_qsar_prediction`, `run_qsar_model`, `download_qmrf`, and `download_qsar_report` include `model_provenance`.
+- `run_profiler` and `group_chemicals_by_profiler` include `profiler_provenance`.
+- `generate_metabolites` and `run_metabolism_simulator` include `simulator_provenance`.
+- `analyze_chemical_hazard` now normalizes endpoint study records, endpoint summaries, evidence blocks, applicability-domain review, provenance collections, and a portable `oqtHazardEvidenceSummary.v1` handoff alongside the raw Toolbox payloads. The helper is intentionally bounded: if `profiling/all` is too slow, it returns partial endpoint evidence with explicit uncertainty and warning fields instead of waiting indefinitely.
+- Hazard and read-across handoffs now publish machine-readable boundary fields (`assessmentBoundary`, `decisionBoundary`, `decisionOwner`) plus `supports` and `requiredExternalInputs`, so downstream systems can distinguish what O-QT packaged from what still requires expert review, regulatory policy, exposure context, or cross-module synthesis.
+- High-level workflow outputs preserve the same normalized metadata inside `log_json.profiler_results[*].profiler_provenance`, `log_json.simulator_results[*].simulator_provenance`, and `log_json.qsar_results[*].model_provenance`.
+- Report-style tools (`download_qmrf`, `download_qsar_report`, `download_workflow_report`) now also declare `content_type`; when the Toolbox returns a ZIP bundle rather than a bare PDF, the MCP response includes `archive_entries` and `pdf_report_base64` when a PDF member can be extracted.
+- High-level workflows and grouping dossiers accept direct Toolbox `chemId` values as `identifier` inputs, which lets orchestrators bypass flaky search endpoints once a substance has already been resolved.
+
 ---
 
 ## Running the server

docs/cross_suite_alignment_2026.md

@@ -0,0 +1,61 @@
+# Cross-Suite Alignment Review (2026-04-08)
+
+This note records the local cross-suite contract review used to harden O-QT MCP for auditability, verifiability, and regulated downstream use.
+
+## Repos inspected locally
+
+- `AOP_MCP`
+- `comptox_mcp_clean_3568d68`
+- `PBPK_MCP`
+- `Bioactivity-PoD-MCP`
+
+## Patterns adopted into O-QT MCP
+
+### From AOP MCP
+
+- Explicit evidence blocks instead of only free-form summaries.
+- Provenance records that say which source populated which contract field and with what transformation confidence.
+- Clear separation between evidence packaging and final decision logic.
+
+### From CompTox MCP
+
+- Explicit applicability-domain framing as a first-class review object.
+- Stronger metadata and provenance packaging for downstream audit workflows.
+- Preference for machine-readable review fields over narrative-only payloads.
+
+### From PBPK MCP
+
+- Machine-readable assessment and decision boundaries rather than only prose caveats.
+- Explicit `supports` and `requiredExternalInputs` fields so downstream consumers can tell what the module does and does not claim to decide.
+- Stronger uncertainty framing that distinguishes semantic coverage from quantitative confidence.
+
+### From Bioactivity-PoD MCP
+
+- Explicit `decisionOwner` language so handoff objects make ownership boundaries visible.
+- Contract emphasis on fit-for-purpose review rather than implied finality.
+- Preference for provenance-ready, typed records over narrative-only summaries.
+
+## O-QT changes made from this review
+
+- `oqtHazardEvidenceSummary.v1` now includes:
+  - `assessmentBoundary`
+  - `decisionBoundary`
+  - `decisionOwner`
+  - `supports`
+  - `requiredExternalInputs`
+  - `uncertaintyAssessment.semanticCoverage`
+- `oqtReadAcrossSummary.v1` now includes:
+  - `assessmentBoundary`
+  - `decisionBoundary`
+  - `decisionOwner`
+  - `supports`
+  - `requiredExternalInputs`
+- Read-across provenance schemas now allow retry `attempts` in source records when Toolbox call metadata is available.
+
+## What was intentionally not copied
+
+- AOP draft-authoring semantics, because O-QT is not an authoring server.
+- CompTox-style numeric applicability-domain confidence, because O-QT does not currently produce a scientifically defensible quantitative AD confidence estimate.
+- PBPK qualification or model-trust governance objects, because O-QT should stay focused on OECD QSAR Toolbox evidence packaging rather than model-qualification workflow management.
+- Bioactivity point-of-departure decision objects, because O-QT should not claim ownership of final biological interpretation outside its module scope.
+- Suite-level evidence synthesis, because O-QT should remain a module-scoped OECD QSAR Toolbox engine.