DEBI

Dietary Exposure Burden Index

DEBI is an open research framework for connecting food-category exposure data to toxicokinetics, endpoint-specific toxicology, uncertainty, and reproducible reports.

It is built for scientific review, not sensational claims.

food category
  -> measured exposure agents
  -> concentration distributions
  -> preparation and transfer factors
  -> absorbed dose
  -> reference-dose comparison
  -> persistence and bioaccumulation
  -> endpoint-specific burden
  -> uncertainty and source traceability

What This Is

DEBI is a source-traceable prioritization model. It helps answer:

Given a food category and a defined exposure scenario, which exposure agents plausibly contribute the most endpoint-specific biological burden, and how confident are we?

The current repository includes:

• deterministic exposure scoring
• Monte Carlo uncertainty scoring
• source-claim and assumption schemas
• reference-point and assessment-scenario manifests
• evidence, traceability, and workflow validators
• DNP/public-language scanner
• generated Markdown reports
• multi-model workflow contracts
• an implementation PRD and research proposal

What This Is Not

DEBI is not:

• a disease prediction tool
• a consumer medical recommendation engine
• a substitute for regulatory risk assessment
• a system for assigning intent or blame to retailers, brands, or vendors
• a public claim generator from unreviewed model output

All example results are internal screening outputs until source claims are approved and reviewed.

Quick Start

Requirements:

• Python 3.11+
• make

Run the full pipeline:

make smoke

That runs:

schema validation
evidence validation
LLM workflow validation
math tests
deterministic scoring
source traceability validation
Monte Carlo scoring
report generation
DNP scan

Generate reports:

make reports

Outputs:

• outputs/debi_score_details.csv
• outputs/debi_score_summary.csv
• outputs/debi_monte_carlo_summary.csv
• outputs/reports/green_tea.md
• outputs/reports/shelf_stable_sweet_snack.md
• outputs/release_manifest.json

Repository Map

Path	Purpose
PRD.md	full product requirements document
PROPOSAL.md	academic-style research/build proposal
ONE_PAGER.md	concise project summary
model_spec.md	scoring model specification
data/	schemas, example evidence, source register, endpoint weights
scripts/	validators, scorers, report generator, tests
llm_workflow/	model-tier roster, prompt contracts, evaluation rubric
outputs/	generated example outputs and reports

Scientific Guardrails

The model is built around strict separation of:

• measured values
• modeled values
• inferred research-priority flags
• assumptions
• unreviewed model output

Public-facing outputs require:

• source-approved numeric claims or clearly labeled assumptions
• endpoint-resolved scores
• uncertainty disclosure
• DNP/public-language review
• no unsupported disease-causation claims

Current Status

This is an early research-system MVP.

The software path works. Some example values are placeholders used to exercise the pipeline. The next scientific milestone is replacing placeholder values with reviewed claims from FDA, EPA, EFSA, JMPR/WHO, PubMed-indexed primary literature, and total diet studies.

Core Commands

make validate      # validate schemas, evidence, workflow, and math
make score         # deterministic scoring + source traceability validation
make monte-carlo   # Monte Carlo scoring
make reports       # generate category reports
make dnp           # report generation + DNP scan
make smoke         # full build/test/report pipeline
make clean         # remove Python cache files

Citation

See CITATION.cff.

Security

See SECURITY.md and SECURITY_AUDIT.md.

CI Template

The GitHub Actions workflow template is in docs/github-actions-ci-template.yml. Copy it to .github/workflows/ci.yml from a GitHub token or session with the workflow scope.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.