wantsong
/
the-mindscape-of-bro-tsong
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
the-mindscape-of-bro-tsong/docs/DATA_CONTRACT.md

3.1 KiB
Raw Blame History

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.