Clinical Trial Safety Signal / 临床试验安全信号专家

Screen drug–event safety signals via disproportionality analysis (PRR / ROR / IC / EBGM with 95% CIs) on FDA FAERS, with Safety Signal Score (0–100, T1–T4). Sources: FDA FAERS (openFDA drug/event.json), FDA Label (drug/label.json), China NMPA PV bulletins (cdr-adr.org.cn), DailyMed SPL, RxClass MED-RT, openFDA enforcement recalls, Hong Kong ADR Alerts. Public data only; zero confidential input. / 基于 FDA FAERS 筛查药物-事件安全信号，计算 disproportionality（PRR / ROR / IC / EBGM，含 95% CI）与安全信号评分（0–100，T1–T4）。数据源：FDA FAERS（openFDA drug/event.json）、FDA 标签（drug/label.json）、中国 NMPA 药物警戒通报（cdr-adr.org.cn）、DailyMed 说明书、RxClass MED-RT、openFDA 召回执法、香港 ADR 警报。仅公开数据，零保密输入。

Language

• English guide → README.md · 中文指南 → README_zh-CN.md
• This skill responds in the user's input language and auto-switches; runtime prompts switch by locale. Bilingual walkthroughs live in the READMEs.

Cross-turn Continuity (required)

Family standard: ct-base/references/continuity.md (pattern A). Echo the block below after every analysis; on a follow-up (changed event / different comparator drug / different measure), read the most recent block in the conversation and override only the changed fields — never rely on LLM memory alone:

text

## Current retrieval settings: drug=… | event=… | comparator=… | measure=PRR | source=FAERS

Clinical Trial Safety Signal

Published Application

Item	Value
Share link	https://ct-safety.app.workbuddy.host/ (domainPrefix ct-safety)
appId	wbapp_GyOm0cdJ1qHoaQxlFZOVwl · deploy metadata: workbench/app.config.json

Re-publish rule: always overwrite with the existing appId — never createNewApp; after deploy, assert the returned shareLink equals the expected URL (ct-base §13.5 dirty-binding red line). Last republished 2026-09-26.

Safe by default: overview-first. Step 1 (overview) runs automatically; Step 2 (detailed retrieval) runs ONLY after the user explicitly confirms.

What counts as explicit confirmation. Any unambiguous go-ahead — e.g. "yes, run the detail" / "确认，跑详情", or skip preview and run / 跳过预览，直接跑. The last one is a confirmation phrasing, not a bypass: it means "the overview is enough, run Step 2 now". All Step-2 guardrails apply identically (no heavy download before confirmation, outputs confined to --out-dir, no confidential input). Conversely, a generic remark in passing conversation is not consent — the go-ahead must be an instruction that explicitly asks for the detail step to run.

Disclaimer & Intended Use

• Audience. This skill is intended for pharmacovigilance / clinical-trial methodologists and drug-safety professionals. It is a methodologic signal-screening aid, not end-user health software.
• Not a clinical or regulatory decision tool. All outputs are statistical disproportionality signals computed from spontaneous adverse-event reports (FDA FAERS), which are subject to reporting bias, under-reporting, and confounding. A signal does NOT establish causation and MUST NOT be used to start, stop, or change any medication, or to make clinical or regulatory decisions. Always corroborate with RCTs, product labels, and qualified clinical/regulatory judgment (ICH E2 family).
• Data flow (transparent). Reads ONLY public sources — FDA FAERS / openFDA, optional cdr-adr.org.cn PV bulletins, and optional corroborative sources (DailyMed SPL, RxClass MED-RT, openFDA enforcement recalls) — all public, keyless. Writes outputs SOLELY to the user-specified --out-dir (default: current working directory). No system-path or hidden logging; any operational log (e.g. safety_err.log) is written ONLY under --out-dir (e.g. out_live/), never outside it, and FAERS raw responses are not persisted unless the user explicitly saves them. Zero confidential data input; no confidential user data is transmitted — retrieval queries (drug/event public keywords) are sent to the ct-registry unified endpoint ct-search.coze.site (thin local client). No local fallback path since v0.9.9.
• Dev artifacts excluded from every publish target. The tests/ directory (regression harness) is not tracked by git and is shipped to no publish target — GitHub, ClawHub, or SkillHub (ct-base §16.8). It stays on the maintainer's local disk only; the installed package contains no test code.

Purpose

Run pharmacovigilance disproportionality analysis on FDA FAERS public adverse-event data to surface potential drug–event safety signals (PRR / ROR / IC / EBGM), supporting clinical-trial safety surveillance and label / signal screening. Optional China official PV bulletins (cdr-adr.org.cn) provide qualitative corroboration only. For published safety literature context (reviews / PV papers), chain to ct-literature --safety — it returns a qualitative CSM subset that corroborates signals but must not enter the FAERS 2×2.

Data Sources

Two categories — quantitative (2×2 disproportionality) and corroborative (qualitative labeled-vs-unlabeled judgement). The latter does not feed PRR/ROR (would distort the 2×2); it informs signal prioritization per ICH E2C / CIOMS VIII (labeled = known risk → downgrade; unlabeled = potential new signal → upgrade).

Category	Source	Access	Status
Quantitative	FDA FAERS (drug/event.json)	Thin local client (Coze unified endpoint ct-search.coze.site). query_total / fetch_case_reports always local-direct (structured state cannot round-trip through Coze)	Required (A-tier)
Quantitative	MAUDE device adverse events (device/event.json) — --device	Same thin-client single-egress via Coze (source='maude'). Device dimension defaults to patient.device.brand_name; 2×2 & disproportionality reused unchanged	Optional (requires Coze-side maude node deployment)
Quantitative	FDA Label (drug/label.json)	Thin local client (Coze unified endpoint). check_event local-only	Optional --with-fda-label
Corroborative	DailyMed SPL · RxClass MED-RT · openFDA Enforcement	Thin local client (Coze unified endpoint)	Optional corroborative_sources.py
Qualitative	cdr-adr.org.cn	Thin local client (Coze nmpa_pv node; local keeps keyword expansion + evidence grading + cache)	Optional --with-cn-pv
Qualitative (CN add-on)	drugoffice.gov.hk (HK ADR Alerts)	Thin local client (Coze hk_pv node)	Coze node written; after deployment

RWE Extension References (v0.10.0 · OMOP CDM + HADES)

• OMOP CDM (OHDSI, github.com/OHDSI/CommonDataModel) — unified data model layer: build PostgreSQL/Snowflake from versioned DDL, ETL HIS / claims / registry data into standard tables so RWE analysis scripts stay source-agnostic.
• HADES (OHDSI, github.com/OHDSI/Hades) — RWE analysis tool stack: CohortMethod (propensity-score matching) + CohortDiagnostics (cohort quality diagnostics).
• Boundary: current focus stays FAERS signal detection; both are long-term RWE extension references, decoupled from the existing FAERS quantitative pipeline.

Key mechanism: openFDA works keyless (anonymous 240 req/min, 1,000 req/day per IP); an optional free key only raises quota. The key, when used, is stored locally only (env var / local .env) and sent only over HTTPS to the official openFDA endpoint (when using local-direct query_total / fetch_case_reports) — never to any third party. NMPA main site (nmpa.gov.cn) is WAF-blocked (HTTP 412) for local direct fetch, but is reachable via the Coze browser channel (--with-nmpa-coze, source=nmpa_pv) — verified live 2026-09-01 (drug=methotrexate → Bulletin No.75, tier=dedicated bulletin). All data are public adverse-event reports; zero confidential input. Endpoint details, indexable/non-indexable fields, and count endpoint pitfalls: references/fetch_pipeline.md.

Architecture — thin local client (default: outbound to Coze)

Since v0.9.9 all safety retrieval uses a thin local client: the local side computes (disproportionality / signal_score / check_event); ALL outbound retrieval goes to the Coze unified endpoint ct-search.coze.site (shared with ct-registry) via adapters/coze_dispatch.py (FaersShim / FdaLabelShim rebinding, call sites unchanged). No local fallback (--offline removed). Local-direct exceptions: query_total / fetch_case_reports (structured state can't round-trip Coze) + check_event (pure local). Publish red line + expanded: references/ADVANCED.md.

Blocked / excluded sources (verified 2026-09-01)

Not silently dropped — each tested from this machine; reasons in multi_source.COUNT_SOURCE_FEASIBILITY / corroborative_sources.BLOCKED_SOURCES; blocked table + planned T1 trio → references/blocked_sources.md.

Methods

Four disproportionality measures on the drug–event 2×2 table (plus multiple-testing and corroboration layers):

• PRR — signal if PRR ≥ 2 and χ² ≥ 4.
• ROR — signal if lower 95% CI > 1.
• IC (UMC/VigiBase Information Component) — signal if lower 95% CI > 0.
• EBGM (FDA MGPS Bayesian shrinkage) — signal if EB05 ≥ 2.
• Corroboration layers — BH-FDR q-value over top-N / benchmarks; PT→SOC MedDRA grouping; Haldane-Anscombe continuity (+0.5/cell; a==0 → conservative null); aROR (--compare-drugs); temporal anomaly CUSUM / rolling-Z / changepoint (--trend); Safety Signal Score 0–100 + T1–T4 (--with-fda-label); Naranjo (--with-causality, qualitative only — never fed into PRR/ROR/IC/EBGM).

Full formulas, thresholds, EBGM/MGPS math, FDR, aROR, trend, and score/tier weighting: references/methods.md.

Features

Capability	Flag / Source
Drug–event signal detection (PRR/ROR/IC/EBGM) + multi-method cross-judgement	FAERS
Device adverse-event signal detection (same 2×2/PRR/ROR/IC/EBGM pipeline)	MAUDE via --device (Coze source='maude', dimension patient.device.brand_name; requires maude node deployed in the Coze console first)
Statistical guards (BH-FDR · PT→SOC · sparse-2×2 --validate-controls)	—
HTML + XLSX core deliverables (JSON/MD backup)	—
China official PV bulletins (qualitative only)	--with-cn-pv
Labeled / unlabeled corroboration	corroborative_sources.py
Temporal anomaly · multi-drug aROR · score 0–100 + T1–T4	--trend · --compare-drugs · --with-fda-label
Naranjo causality · MedDRA coding · prioritization · PSUR	--with-causality · --code-verbatim · --prioritize · --psur
Case-level de-duplication (L1 collapse / L2 flag-only)	--case-level
Non-ASCII drug-name auto-translate	--drug 阿司匹林 → aspirin
Chained invocation	ct-protocol · ct-registry · ct-literature --safety

Full capability table with scenarios and boundaries: references/ADVANCED.md.

Requirements

• Python 3.10+ (Anaconda recommended). Required: requests. Optional: matplotlib (PNG charts).
• Network: read-only FAERS public API. An openFDA key is optional (raises quota only) — see below.

⚠️ Safety

• Network: retrieval (present / --out-xlsx) runs lightweight openFDA count facet queries (seconds, no case download); case-level download requires explicit --run (throttled by HARD_CAP=10000). Reads FAERS public reports ONLY — zero confidential data or information input (A-tier, network=public-retrieval).
• China PV bulletins are qualitative narrative — NO per-drug-event counts; must NOT feed disproportionality; only corroborate a FAERS signal.
• FAERS re-ingests the same case as follow-up versions and via multiple reporters. Case-level de-duplication fixes the individual-case listing only; disproportionality counts come from openFDA aggregate endpoints and therefore still carry duplicate-reporting bias. Never claim a signal is "de-duplicated".
• Signal detection is for screening, not causal conclusion; regulatory submission (DSUR / PBRER / label change) must be assessed per GCP / ICH E2 separately.

Workflow

Two-step, overview-first (present summary in context, Excel on demand):

1. Step 1 — Overview (automatic): fetch_reports.py --drug X sends 8 count facets, prints the summary to context in seconds, caches faers_summary_cache.json. No confirmation needed.
2. Step 2 — Detail (only after explicit confirm): --out-xlsx builds the summary Excel from cache; --run downloads individual case reports (HARD_CAP 10000) for age/country stats. Signal detection via ct_safety.py.

scripts/overview.py is deprecated (merged into Step 1). Full workflow, caching, --parallel, XLSX layout: references/fetch_pipeline.md.

One-shot signal report (ct_safety.py) — two core deliverables

ct_safety.py --drug X --event Y --run writes into --out-dir and prints a "Core Deliverables" block:

• faers_report.html — visual report (open in browser preview). Core ①.
• faers_report.xlsx — ALL raw data (counts, 2×2, four measures, optional Label/CN-PV/Score). Core ②; audit every number here. (faers_report.md / *.json are backups only.)

API Key (openFDA) — optional, self-configured

The skill runs without a key; a free key only raises quota. Provide via CLI --api-key, env OPENFDA_API_KEY (recommended), or skill-root .env (git-ignored; plaintext or obf: XOR+base64 per ct-base §5) — never paste keys into chat or shipped files. Details: references/openfda_api_key.md.

Errors

Brief; full table in references/errors.md.

• 429 / rate-limited — exceed openFDA quota; fix: --api-key or lower frequency.
• Persistent 404 on multi-word PT — not indexed; swap to standard PT; total() auto-downgrades 404→.exact.
• --max > 10000 — clamped to HARD_CAP 10000 (API-return-order first N, selection bias).
• Outbound Coze rejected / unreachable — endpoint not allow-listed / token invalid / safety_rest_node undeployed; check Coze deployment status and config.json auto_approve_endpoints.

Comparative Study Design Mode

For "compare X vs Y" / "within-class head-to-head" / "active-comparator" requests, switch to the comparative track (single-drug default otherwise). Steps: ① data prep (faers-data-prep.md) → ② study style + 4 workloads (faers-comparative-design.md) → ③ metrics / comparators / robustness (faers-method-library.md) → ④ evidence tiers + claim boundaries (evidence-hierarchy.md).

Hard rules: never run disproportionality on unprepared raw counts; present all four configurations then recommend one; label every result [Tier 1] signal / [Tier 2] comparative / [Tier 3] robustness; Tier-4 claims (incidence, causality, benefit–risk, prescribing) forbidden without external data; flag weak comparator indication overlap.

Pipeline

• ct-safety → ct-protocol: signals feed the safety monitoring plan.
• ct-safety → ct-registry: control-trial safety-design benchmarking (CDE trials).
• CN-PV is an in-skill qualitative add-on, not a chain target. Units: references/units.md. Changelog: CHANGELOG.md.

Regression Tests

Maintainer-only (stdlib, no pytest; not shipped): python tests/mode_b_test.py (10 hardening cases) and python tests/mode_c_test.py (F1–F11). Both offline by default. Details in references/errors.md.

Bug Reporting (ct-base §20.3, adapter: adapters/bug_report.py)

Propose at most once per session, only on a strong signal and after ≥1 retry — never on repeated tuning. Always two-stage: ① show the sanitized report → ② send only on explicit consent; never re-propose after a decline. Full rules, 11-key whitelist, and CLI: references/bug_reporting.md.