Interoperability: Veilbreak API/MCP data bridge and schema mapping

[ProhibitedTV]

Parent roadmap: #3
Related: #21, #23, #24, #25

Objective

Evaluate and support optional interoperability with Project Veilbreak as an external community research database, without assuming credentials, scraping, write access, or direct dependency on Veilbreak.

Veilbreak already provides a structured community-science setup for protocols, experiments, questionnaire data, API access, MCP access, and contributor privacy controls. LaserLab should be able to import/export compatible metadata and reference Veilbreak records where users choose to connect the two workflows.

Observed Veilbreak capabilities to account for

Public site review shows Veilbreak includes:

• dashboard with counts for protocols, experiments, and observed-code reports;
• protocol browser with wavelength, dose, substance, equipment, and experiment counts;
• experiment browser with protocol association, wavelength, observed-code status, dose, and substance fields;
• read-only API access for protocols and experiments;
• API schema endpoint;
• search/filter parameters including substance, equipment, laser class, tags, wavelength range, observed-code status, protocol ID, and content/symbol search;
• MCP server exposing approved protocols, approved experiments, and schema with contributor personal information redacted;
• Creative Commons licensing notes for protocols/experiments;
• stated privacy behavior excluding author names/emails in API responses.

Scope

This issue is for optional interoperability and schema alignment only. LaserLab remains a local-first analysis tool for footage, controls, detector outputs, reports, and review bundles.

LaserLab should not:

• scrape Veilbreak pages;
• require a Veilbreak account or API key to run;
• upload user data to Veilbreak by default;
• expose private participant data;
• treat Veilbreak community reports as detector evidence;
• import substance-use procedure details into LaserLab guidance.

Proposed data model mapping

Add a community_dataset_reference / external_dataset_reference object that can store:

• source: veilbreak, manual, other;
• record_type: protocol, experiment, symbol_corpus, questionnaire, unknown;
• record_id when known;
• record_url when user-provided;
• api_endpoint when user-provided;
• license / attribution fields;
• imported_at timestamp;
• source_hash for imported JSON/CSV;
• privacy_redaction_status;
• local_notes.

Map Veilbreak-like fields into LaserLab where available:

• laser_wavelength -> wavelength_nm;
• laser_power -> rated_power_mw or reported_power_mw;
• laser_class -> laser_class_label;
• projection_distance -> projection_distance_meters;
• equipment -> equipment_list / diffraction_optic_type when inferable;
• tags -> external_tags;
• observed / observed-code status -> subjective/context field only;
• symbols description / questionnaire fields -> subjective-report or symbol-transcription context only.

Import/export tasks

• Add optional import path for Veilbreak API JSON exports or manually downloaded JSON/CSV.
• Add export format from LaserLab review bundles that can be mapped into community databases later.
• Add schema conversion helpers that clearly label field confidence: exact, inferred, missing, user-entered.
• Add report section listing external dataset references and imported fields.
• Add privacy warning before exporting any subjective report or participant/session metadata.

MCP/API tasks

• Document how a user could use Veilbreak's read-only MCP/API as context for external analysis without bundling credentials.
• Do not call Veilbreak automatically from LaserLab unless the user explicitly configures it.
• Keep API keys out of manifests and reports.
• Include a local cache checksum if data is imported.

UI tasks

• Add optional External dataset reference section under Export or Study Context.
• Fields should include Veilbreak protocol ID, Veilbreak experiment ID, record URL, license/attribution, and imported metadata summary.
• Show badges such as local footage, external community metadata, subjective report, detector evidence.
• Make the separation obvious: Veilbreak context can inform protocol metadata, but LaserLab detector claims come only from local footage/control analysis.

Acceptance criteria

• LaserLab can store external Veilbreak-style references in manifest/report JSON.
• Reports show external dataset references without mixing them into detector evidence scores.
• Import/export helpers preserve attribution, license, privacy status, and source hashes.
• No network dependency is required for normal LaserLab operation.
• Documentation explains that Veilbreak is a community data platform and LaserLab is a local analysis/validation tool that can interoperate by user choice.

Notes

Veilbreak's setup is strong and closely aligned with the community's needs: protocols, experiments, API, MCP, schema, and privacy-redacted research data. LaserLab should complement it rather than duplicate it: use LaserLab for local video/control analysis and reproducible evidence bundles, then optionally map outputs into community databases such as Veilbreak.