144 lines
3.1 KiB
Markdown
144 lines
3.1 KiB
Markdown
# Data Contract
|
|
|
|
## 1. Machine-Readable Format
|
|
|
|
Use JSON for machine-readable data.
|
|
|
|
Model JSON files own the model asset state, including `status`, `regression_status`, and `stability_profile.stability_level`.
|
|
|
|
Main JSON objects:
|
|
|
|
- Model spec
|
|
- Source article
|
|
- Source excerpt
|
|
- Regression case
|
|
- Selector example
|
|
- Model index
|
|
|
|
## 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`
|
|
- `status`
|
|
- `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`
|
|
- `output_contract`
|
|
- `structured_output_contract`
|
|
- `productization_notes`
|
|
|
|
`structured_output_contract` is model-specific. It must not turn QPI-only or Intellectual-Archaeology-only runtime fields into global top-level required fields for every model.
|
|
|
|
Model-specific required runtime output fields are checked by `scripts/validate_model_library.py`.
|
|
|
|
## 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`
|
|
- `should_call_model`
|
|
- `expected_primary_model`
|
|
- `negative_expected_models`
|
|
- `expected_classification`
|
|
- `expected_dominant_scarcity`
|
|
- `expected_max_depth`
|
|
- `minimum_required_elements`
|
|
- `forbidden_elements`
|
|
- `evaluation_mode`
|
|
- `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`
|
|
|
|
## 8. Index Integrity
|
|
|
|
`models/model_index.json` is generated or checked from model JSON, card files, source references, and regression cases.
|
|
|
|
`cards/card_index.md` is the human-readable projection of `models/model_index.json`.
|
|
|
|
Indexes must not drift from model state, source/evidence counts, regression case counts, or card file existence.
|
|
|
|
## 9. Content Stabilization Integrity
|
|
|
|
Engineering validation does not imply content stability.
|
|
|
|
Before content stabilization review, every core model should have at least 15 regression cases and field-level evidence coverage.
|
|
|
|
Source excerpts must distinguish exact quotes from condensed or paraphrased excerpts with `quote_status`.
|