109 lines
1.7 KiB
Markdown
109 lines
1.7 KiB
Markdown
# 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`
|