1.7 KiB

Raw Blame History

Data Contract

1. Machine-Readable Format

Use JSON for machine-readable data.

Main JSON objects:

Model spec
Source article
Source excerpt
Regression case
Selector example

2. Human-Readable Format

Use Markdown for:

Model cards
Project documentation
Extraction notes
Validation reports
Handoff reports

3. Model Spec Contract

Every model JSON should include:

model_id
model_name
model_type
pipeline_position
one_sentence_definition
core_question
core_mechanism
source_articles
source_evidence
input_types
output_types
call_when
do_not_call_when
common_misuses
failure_modes
selection_priority
confidence_level
stability_profile
regression_status
productization_notes

4. Source Article Contract

Every source article should include:

source_id
title
source_type
related_models
source_status

Optional:

author
date
file_path
notes

5. Source Excerpt Contract

Every source excerpt should include:

excerpt_id
source_id
related_model_id
excerpt_type
summary
used_for

Optional:

raw_excerpt
confidence
notes

6. Regression Case Contract

Every regression case should include:

case_id
model_id
case_type
input
expected_behavior
failure_signal

Optional:

expected_output_elements
notes

7. Reference Integrity

The following references must be valid:

model.source_articles -> sources/source_articles.json
model.source_evidence -> sources/source_excerpts.json
regression_case.model_id -> models/*.model.json
source_excerpt.source_id -> sources/source_articles.json
source_excerpt.related_model_id -> models/*.model.json