Smart Questionnaire

A config-authored, offline, single-container toolkit for instrumented, scenario-based decision studies with experts — plus a generic analysis pipeline that turns the collected logs into exploratory reports.

A participant reviews a scenario (optional data/visualizations), makes a decision, is optionally shown extra information (a model recommendation, peer data, a guideline), makes a revised decision, answers follow-up questions, and completes end-of-study surveys — while every interaction is logged (think-time, what was viewed, what changed before/after the information). Researchers author studies in config — no code. It deploys as one container and makes zero external network requests at runtime, so it runs on closed / air-gapped networks.

End-to-end: define a study (config) → deploy (one container) → collect (JSONL) → explore (reports).

See it in action

1 · Author a study in config — no code. A study is a study.json (which stages are on, the blocks per stage, the decision fields, the theme) plus CSV content. The bundled healthcare demo (early-warning — a ward-deterioration escalation vignette with synthetic patients, no real data) turns on the full flow:

{
  "title": "Clinical Deterioration — Escalation Demo",
  "stages": { "context": true, "data": true, "decision": true, "reveal": true, "questions": true, "surveys": true },
  "layout": {
    "context": [ { "type": "info", "key": "patient", "title": "Patient (synthetic)" } ],
    "data":    [ { "type": "timeseries", "key": "vitals", "title": "Vital-sign trajectory",
                   "panels": [ { "title": "Heart & respiratory rate", "series": ["hr","rr"] },
                               { "title": "Oxygen saturation",        "series": ["spo2"] } ] } ],
    "reveal":  [ { "type": "callout", "key": "rec",     "title": "Model recommendation" },
                 { "type": "bars",    "key": "signals", "title": "Top contributing signals" } ]
  },
  "decision": { "fields": [
    { "id": "escalation",     "type": "choice", "label": "Escalation",
      "options": ["Continue ward care","Increase monitoring","Escalate to ICU / MET"] },
    { "id": "reassess_hours", "type": "number", "label": "Reassess in", "unit": "hours" }
  ] }
}

python build_config.py --study studies/early-warning and you have a working study.

2 · Participants run it — review the patient → decide → see the model's risk recommendation → revise → answer → surveys, with every interaction logged:

3 · You get exploratory results — one command (analysis/run_report.py) turns the logs into a self-contained interactive HTML report (plus CSV/Excel + PNG and a Streamlit dashboard): completion funnel, before/after decision change, SUS, per-question summaries, timing, and reveal-panel engagement.

Also included: a non-clinical example (loan review)

The same mechanics in a different domain — the demo study, a synthetic loan-review vignette:

Why this exists

Existing tools each cover only part of this need: survey platforms (REDCap, Qualtrics, LimeSurvey) are no-code but can't do staged within-item information reveal with locked before/after decision capture or fine-grained behavioral logging; behavioral-experiment frameworks (jsPsych, lab.js, PsychoJS, oTree, Gorilla) offer staged flow and rich logging but require coding or are cloud-only. Teams needing the combination today build bespoke one-off apps. Smart Questionnaire packages it as reusable, config-authored infrastructure.

Repository layout

Path	What it is
platform/	The collector — FastAPI + vanilla-JS, config-driven, single container. See platform/README.md and platform/SCHEMA.md.
platform/studies/early-warning/	A synthetic healthcare full-flow example (ward-deterioration escalation vignette — synthetic patients, no real data): context → data → decision → reveal → questions → surveys.
platform/studies/demo/	A synthetic non-clinical full-flow example (loan-review vignette).
platform/studies/example-survey/	A surveys-only example (shows optional stages).
analysis/	Generic analysis pipeline → interactive HTML report, CSV/Excel + PNG, and a Streamlit dashboard. See analysis/README.md.

Quick start

# 1) Collector — preview the healthcare demo study
cd platform
python -m venv .venv && .venv/bin/pip install -r requirements.txt
python build_config.py --study studies/early-warning
CONFIG_DIR=studies/early-warning/config STUDY_FILE=studies/early-warning/study.json DATA_DIR=/tmp/sq_data \
  .venv/bin/uvicorn app.main:app --port 8000 --loop asyncio
# open http://localhost:8000  (log in with a participant from studies/early-warning/csv/participants.csv)

# 2) Analysis — turn collected logs into a report
cd ../analysis
python -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/python run_report.py --data /tmp/sq_data --config ../platform/studies/early-warning/config --out out
# open out/report.html

Authoring a study (no code)

Copy a folder under platform/studies/, edit its study.json (which stages are on, the block layout per stage, decision fields, theme) and its csv/ content, then run python build_config.py --study studies/<name>. The block catalog (context info/text/image; data timeseries/table; decision number/choice/text; reveal callout/bars/distribution/text; questions likert/choice/free_text; surveys sus/likert_battery/free_text) is documented in platform/SCHEMA.md.

Deployment & sensitive data

Builds a small multi-arch container (Debian-bullseye base, fully async, static served from memory). When deployed in a trusted, access-controlled closed/air-gapped zone, sensitive content is supported (data stays local, no external calls, salted-hashed credentials); handling is governed by the deploying institution's policy. The software does not itself assert regulatory compliance.

License

MIT.