Metadata-Version: 2.4
Name: refua-regulatory
Version: 0.7.2
Summary: Regulatory and audit evidence packaging for Refua campaign decisions.
Author-email: JJ Ben-Joseph <jj@tensorspace.ai>
License-Expression: MIT
Project-URL: Homepage, https://agentcures.com/
Project-URL: Repository, https://github.com/agentcures/refua
Project-URL: Documentation, https://github.com/agentcures/refua#readme
Project-URL: Issues, https://github.com/agentcures/refua/issues
Keywords: drug discovery,audit,lineage,provenance,regulatory,refua
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: mypy>=1.11.0; extra == "dev"
Requires-Dist: pre-commit>=4.5.1; extra == "dev"
Dynamic: license-file

# refua-regulatory

`refua-regulatory` is the Refua regulatory workflow and audit package.
It helps teams follow drug regulation processes by turning campaign decisions and execution outputs into verifiable evidence bundles with end-to-end lineage across plans, tool calls, models, datasets, and generated artifacts.

## What it provides

- Campaign decision extraction from campaign run outputs.
- Structured decision records (`decisions.jsonl`) with deterministic decision IDs.
- Model and data provenance capture per campaign decision.
- Lineage graph materialization (`lineage.json`) for traceability.
- Evidence bundle packaging with checksums (`checksums.sha256`).
- Integrity verification for audit handoff and compliance workflows.
- Regulatory checklist evaluation with strict and manual-review gates.
- Automatic comprehensive checklist generation during bundle build.
- Structured outputs that support internal regulatory readiness reviews before agency submission.

## Install

```bash
cd refua-regulatory
pip install -e ".[dev,test]"
```

## CLI

```bash
refua-regulatory --help
```

### Build a bundle

```bash
refua-regulatory build \
  --campaign-run artifacts/kras_campaign_run.json \
  --output-dir artifacts/evidence/kras_run_001 \
  --data-manifest ~/.cache/refua-data/_meta/parquet/chembl_activity_ki_human/latest/manifest.json \
  --extra-artifact artifacts/candidate_run.json
```

Output bundle layout:

```text
evidence/
  manifest.json
  decisions.jsonl
  lineage.json
  checksums.sha256
  artifacts/
    campaign_run.json
    data_manifests/
    extras/
  checklists/
    drug_discovery_comprehensive.json
    drug_discovery_comprehensive.md
```

By default, `build` auto-generates the `drug_discovery_comprehensive` checklist.

Build-time checklist controls:

```bash
refua-regulatory build \
  --campaign-run artifacts/kras_campaign_run.json \
  --output-dir artifacts/evidence/kras_run_001 \
  --checklist-template core \
  --checklist-template fda_cder_ai_ml \
  --checklist-strict
```

Disable checklist generation:

```bash
refua-regulatory build \
  --campaign-run artifacts/kras_campaign_run.json \
  --output-dir artifacts/evidence/kras_run_001 \
  --no-checklist
```

Include machine-identifying provenance fields only when you need them:

```bash
refua-regulatory build \
  --campaign-run artifacts/kras_campaign_run.json \
  --output-dir artifacts/evidence/kras_run_001 \
  --include-sensitive-provenance
```

### Verify a bundle

```bash
refua-regulatory verify --bundle-dir artifacts/evidence/kras_run_001
```

JSON mode:

```bash
refua-regulatory verify --bundle-dir artifacts/evidence/kras_run_001 --json
```

### Show bundle summary

```bash
refua-regulatory summary --bundle-dir artifacts/evidence/kras_run_001
```

### Run a regulatory checklist

Core automated checklist:

```bash
refua-regulatory checklist \
  --bundle-dir artifacts/evidence/kras_run_001 \
  --template drug_discovery_comprehensive \
  --strict
```

FDA/CDER-oriented template (includes manual-review items):

```bash
refua-regulatory checklist \
  --bundle-dir artifacts/evidence/kras_run_001 \
  --template fda_cder_ai_ml \
  --output-json artifacts/evidence/kras_run_001/checklist.json \
  --output-markdown artifacts/evidence/kras_run_001/checklist.md
```

## Python API

```python
from pathlib import Path

from refua_regulatory import build_evidence_bundle, verify_evidence_bundle

manifest = build_evidence_bundle(
    campaign_run_path=Path("artifacts/kras_campaign_run.json"),
    output_dir=Path("artifacts/evidence/kras_run_001"),
)

verification = verify_evidence_bundle(Path("artifacts/evidence/kras_run_001"))
print(manifest["bundle_id"], verification.ok)
```

## Data and model provenance behavior

- Data provenance is loaded from explicit manifest paths (`--data-manifest`).
- `refua-data` parquet manifests are parsed directly for dataset IDs, versions, source URLs, and SHA256 checksums.
- Model provenance is inferred from executed tool outputs and optional CLI overrides (`--model-name`, `--model-version`).
- Campaign run IDs are derived deterministically from payload content unless the run payload provides an explicit `campaign_run_id` or `run_id`.
- Hostname and absolute git root are omitted from execution provenance by default; enable them with `--include-sensitive-provenance` when required for internal audits.

## Test

```bash
cd refua-regulatory
python -m pytest -q
python -Im build
```

## Notes

- This package records reproducibility evidence; it does not claim biological efficacy.
- Regulatory submission requirements vary by jurisdiction and program type.
