@cosla/sensemaking-report-builder

Cosla fork. Maintained by Cosla from the interactive report UI in Jigsaw sensemaking-tools (src/report_ui). Not an official Jigsaw or Google release. Cosla adds a path-configurable CLI so Consul and other jobs can pass pipeline artefacts without copying into a package input/ folder.

Builds an interactive HTML report from Python pipeline outputs: bridging-scores / opinions CSV plus report_data.json (summary).

This is not @cosla/sensemaking-report-ui, which consumes Node advanced JSON (topic-stats.json, comments.json, etc.).

Install

npm install @cosla/sensemaking-report-builder
# or
npx @cosla/sensemaking-report-builder inline --help

CLI binary: sensemaking-report-builder.

Quick start (CLI)

Inline (single self-contained HTML) — use --output

npx @cosla/sensemaking-report-builder inline \
  --bridging_scores /path/to/bridging_scores.csv \
  --summary /path/to/report_data.json \
  --output /path/to/report.html

--opinions is an alias for --bridging_scores.

Static (HTML + CSS/JS siblings) — use --outputDir

npx @cosla/sensemaking-report-builder static \
  --bridging_scores /path/to/bridging_scores.csv \
  --summary /path/to/report_data.json \
  --outputDir /path/to/out
# → /path/to/out/report.html plus assets

Using the wrong output flag for the mode fails with a clear error (inline forbids --outputDir; static forbids --output).

Directory-oriented (prepared input/)

npx @cosla/sensemaking-report-builder inline \
  --inputDir ./input \
  --output ./output/report.html

Defaults: opinions <inputDir>/opinions.csv, summary <inputDir>/summary.json, optional <inputDir>/predicted.json and <inputDir>/config.json if present.

CLI options

| Arg / flag | Purpose | Default | |------------|---------|---------| | inline | static | Build mode (required for builds) | — | | config-schema | Print config JSON Schema to stdout (no inputs) | — | | --schema-version | With config-schema: schema version to print | latest (1) | | --inputDir | Base dir for default input paths | ./input | | --opinions / --bridging_scores | Opinions / bridging scores CSV | <inputDir>/opinions.csv | | --summary | Summary JSON (report_data.json) | <inputDir>/summary.json | | --predicted | Predicted-agreement JSON | <inputDir>/predicted.json if present | | --config | Config JSON (logo, exclusions, …) | <inputDir>/config.json if present; else {} | | --output | inline only: path to HTML file | ./output/report.html | | --outputDir | static only: output directory | ./output |

Config schema

npx @cosla/sensemaking-report-builder config-schema
npx @cosla/sensemaking-report-builder config-schema --schema-version 1

Prints a JSON Schema draft 2020-12 document for supported config.json keys (schemas/config.v1.json), including application field config_schema_version. Unknown --schema-version values fail with a clear error.

npm test        # smoke (config-schema) + unit tests
npm run smoke   # config-schema only
npm run unit    # node:test suite only

Logo and translations are configured in config.json (not CLI flags). Place logo.svg / logo.png next to that config (under --inputDir when using dir mode).

Input contracts

Opinions / bridging CSV

Required columns: topic, opinion, quote, participant_id.

Optional: AVERAGE_OF_2_BRIDGING or AVERAGE_OF_3_BRIDGING (used to sort quotes; OF_2 preferred when both are present). When neither column is present, a warning is printed and quotes keep input order. Demographic columns: prefix with demo: (e.g. demo:Age). When no demographic columns have values, the participant overview and drawer demographics tab are omitted.

Summary JSON

Same shape as Python sensemaking-report-text / report_data.json: text, sub_contents[] with title and text. Optional top-level title.

Config JSON (optional)

| Key | Description | | :--- | :--- | | logo | Header image filename (e.g. "logo.svg") | | translations | Optional i18n filename under the input dir | | overview_chart | "toggle", "topics", or "opinions" | | number_of_top_opinions | Opinions overview chart size | | number_of_sample_quotes | Quote previews per opinion | | low_sample_warning_threshold | Low-sample warning threshold | | chart_colors | Overview chart colours (array of hex strings). Default: #DA3D2E, #F2A50C, #80CD57, #00885F, #11C2CE, #1233A6, #8A2FE4, #F388D2. Blank entries are ignored; an empty list falls back to the default. | | demographic_colors | Participant chart colours: a single hex string (a 6-step light-to-dark palette is generated) or an explicit array of colours. Default base: #4886f7. Generated ramps use CSS relative colour syntax (oklch(from …); Chrome 119+, Firefox 128+, Safari 18+); use an explicit hex array for older browsers. | | excluded_topics / excluded_opinions | Hide named topics/opinions (exact match to CSV columns). CamelCase aliases excludedTopics / excludedOpinions are also accepted at runtime. |

Predicted agreement (optional)

predicted.json with text and sub_contents[] containing statements[] with text and predicted_agreement.

Translations (optional)

Copy src/default-translations.json, translate values, set locale / direction (ltr or rtl). See that file for keys.

Local development (git checkout)

From this directory:

npm install
npm run inline    # → ./output/report.html
npm run static    # → ./output/report.html + assets
npm run preview   # browser-sync on ./output (after static)

Related

• Python CLIs: PyPI cosla-sensemaking-tools — see repo README.md and PACKAGING.md.
• Node report UI (different inputs): @cosla/sensemaking-report-ui.