briefloop 0.11.12__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (424) hide show
  1. briefloop-0.11.12.dist-info/METADATA +473 -0
  2. briefloop-0.11.12.dist-info/RECORD +424 -0
  3. briefloop-0.11.12.dist-info/WHEEL +5 -0
  4. briefloop-0.11.12.dist-info/entry_points.txt +3 -0
  5. briefloop-0.11.12.dist-info/licenses/LICENSE +22 -0
  6. briefloop-0.11.12.dist-info/top_level.txt +1 -0
  7. multi_agent_brief/__init__.py +36 -0
  8. multi_agent_brief/analysis_blocks/__init__.py +11 -0
  9. multi_agent_brief/analysis_blocks/builder.py +206 -0
  10. multi_agent_brief/analysis_blocks/renderer.py +237 -0
  11. multi_agent_brief/analysis_blocks/schemas.py +52 -0
  12. multi_agent_brief/analysis_modules/__init__.py +8 -0
  13. multi_agent_brief/analysis_modules/base.py +87 -0
  14. multi_agent_brief/analysis_modules/market_competitor/__init__.py +68 -0
  15. multi_agent_brief/analysis_modules/market_competitor/auditor.py +290 -0
  16. multi_agent_brief/analysis_modules/market_competitor/config.py +187 -0
  17. multi_agent_brief/analysis_modules/market_competitor/event_builder.py +226 -0
  18. multi_agent_brief/analysis_modules/market_competitor/renderer.py +199 -0
  19. multi_agent_brief/analysis_modules/market_competitor/schemas.py +518 -0
  20. multi_agent_brief/analysis_modules/policy_regulatory/__init__.py +7 -0
  21. multi_agent_brief/analysis_modules/policy_regulatory/audit.py +195 -0
  22. multi_agent_brief/analysis_modules/policy_regulatory/module.py +387 -0
  23. multi_agent_brief/analysis_modules/policy_regulatory/schemas.py +129 -0
  24. multi_agent_brief/analysis_modules/registry.py +73 -0
  25. multi_agent_brief/audience/__init__.py +19 -0
  26. multi_agent_brief/audience/profiles.py +246 -0
  27. multi_agent_brief/audience_memory/__init__.py +23 -0
  28. multi_agent_brief/audience_memory/profile.py +358 -0
  29. multi_agent_brief/audit/__init__.py +36 -0
  30. multi_agent_brief/audit/case_applicability.py +181 -0
  31. multi_agent_brief/audit/deterministic.py +471 -0
  32. multi_agent_brief/audit/editorial_governance.py +404 -0
  33. multi_agent_brief/audit/final_quality.py +764 -0
  34. multi_agent_brief/audit/harness.py +242 -0
  35. multi_agent_brief/audit/interfaces.py +96 -0
  36. multi_agent_brief/audit/limitation_hygiene.py +238 -0
  37. multi_agent_brief/audit/proposal_boundary.py +34 -0
  38. multi_agent_brief/audit/redaction.py +27 -0
  39. multi_agent_brief/audit/rule_packs.py +96 -0
  40. multi_agent_brief/audit/semantic.py +435 -0
  41. multi_agent_brief/capabilities/__init__.py +22 -0
  42. multi_agent_brief/capabilities/catalog.py +215 -0
  43. multi_agent_brief/capabilities/detect.py +199 -0
  44. multi_agent_brief/capabilities/models.py +60 -0
  45. multi_agent_brief/capabilities/recommend.py +206 -0
  46. multi_agent_brief/cli/__init__.py +2 -0
  47. multi_agent_brief/cli/analysis_commands.py +140 -0
  48. multi_agent_brief/cli/approval_commands.py +107 -0
  49. multi_agent_brief/cli/audit_commands.py +59 -0
  50. multi_agent_brief/cli/capability_commands.py +548 -0
  51. multi_agent_brief/cli/claude_commands.py +159 -0
  52. multi_agent_brief/cli/competitors_commands.py +182 -0
  53. multi_agent_brief/cli/controls_commands.py +137 -0
  54. multi_agent_brief/cli/deliver_commands.py +942 -0
  55. multi_agent_brief/cli/eval_cases_commands.py +99 -0
  56. multi_agent_brief/cli/experiments_commands.py +395 -0
  57. multi_agent_brief/cli/feedback_commands.py +192 -0
  58. multi_agent_brief/cli/finalize_commands.py +153 -0
  59. multi_agent_brief/cli/gates_commands.py +174 -0
  60. multi_agent_brief/cli/hermes_commands.py +356 -0
  61. multi_agent_brief/cli/improve_commands.py +224 -0
  62. multi_agent_brief/cli/init_commands.py +564 -0
  63. multi_agent_brief/cli/init_wizard.py +1473 -0
  64. multi_agent_brief/cli/input_commands.py +237 -0
  65. multi_agent_brief/cli/main.py +288 -0
  66. multi_agent_brief/cli/onboard_commands.py +193 -0
  67. multi_agent_brief/cli/product_commands.py +1449 -0
  68. multi_agent_brief/cli/provenance_commands.py +100 -0
  69. multi_agent_brief/cli/release_commands.py +68 -0
  70. multi_agent_brief/cli/repair_commands.py +169 -0
  71. multi_agent_brief/cli/run_commands.py +292 -0
  72. multi_agent_brief/cli/runtime_commands.py +81 -0
  73. multi_agent_brief/cli/secrets_commands.py +232 -0
  74. multi_agent_brief/cli/semantic_support_commands.py +80 -0
  75. multi_agent_brief/cli/sources_commands.py +647 -0
  76. multi_agent_brief/cli/start_commands.py +8 -0
  77. multi_agent_brief/cli/state_commands.py +446 -0
  78. multi_agent_brief/cli/status_commands.py +26 -0
  79. multi_agent_brief/cli/workbuddy_commands.py +103 -0
  80. multi_agent_brief/configs/artifact_contracts.yaml +514 -0
  81. multi_agent_brief/configs/orchestrator_contract.yaml +181 -0
  82. multi_agent_brief/configs/policy_packs/default.yaml +65 -0
  83. multi_agent_brief/configs/policy_profiles/evidence_extract_default.yaml +58 -0
  84. multi_agent_brief/configs/policy_profiles/finance_default.yaml +44 -0
  85. multi_agent_brief/configs/policy_profiles/internet_default.yaml +44 -0
  86. multi_agent_brief/configs/policy_profiles/manufacturing_default.yaml +33 -0
  87. multi_agent_brief/configs/policy_profiles/solar_manufacturing_default.yaml +64 -0
  88. multi_agent_brief/configs/report_packs/evidence_extract.yaml +48 -0
  89. multi_agent_brief/configs/report_packs/management_monthly.yaml +36 -0
  90. multi_agent_brief/configs/report_packs/market_weekly.yaml +36 -0
  91. multi_agent_brief/configs/report_packs/solar_industry_periodic.yaml +50 -0
  92. multi_agent_brief/configs/report_templates/evidence_extract.yaml +55 -0
  93. multi_agent_brief/configs/report_templates/management_monthly.yaml +48 -0
  94. multi_agent_brief/configs/report_templates/market_weekly.yaml +49 -0
  95. multi_agent_brief/configs/report_templates/solar_industry_periodic.yaml +75 -0
  96. multi_agent_brief/configs/stage_specs.yaml +180 -0
  97. multi_agent_brief/contracts/__init__.py +41 -0
  98. multi_agent_brief/contracts/base.py +99 -0
  99. multi_agent_brief/contracts/errors.py +41 -0
  100. multi_agent_brief/contracts/migrations/__init__.py +5 -0
  101. multi_agent_brief/contracts/migrations/claim_v1_to_v2.py +33 -0
  102. multi_agent_brief/contracts/registry.py +159 -0
  103. multi_agent_brief/contracts/role_topology.py +25 -0
  104. multi_agent_brief/contracts/schemas/__init__.py +35 -0
  105. multi_agent_brief/contracts/schemas/analysis_pack.py +135 -0
  106. multi_agent_brief/contracts/schemas/atomic_claim_graph.py +304 -0
  107. multi_agent_brief/contracts/schemas/audit_report.py +80 -0
  108. multi_agent_brief/contracts/schemas/candidate_item.py +51 -0
  109. multi_agent_brief/contracts/schemas/claim.py +197 -0
  110. multi_agent_brief/contracts/schemas/claim_draft.py +386 -0
  111. multi_agent_brief/contracts/schemas/claim_support_matrix.py +334 -0
  112. multi_agent_brief/contracts/schemas/evidence_span_registry.py +270 -0
  113. multi_agent_brief/contracts/schemas/policy_profile.py +247 -0
  114. multi_agent_brief/contracts/schemas/report_spec.py +257 -0
  115. multi_agent_brief/contracts/schemas/semantic_assessment_report.py +480 -0
  116. multi_agent_brief/contracts/schemas/source_evidence_pack_manifest.py +233 -0
  117. multi_agent_brief/contracts/schemas/source_item.py +96 -0
  118. multi_agent_brief/contracts/semantic_assessment_status.py +12 -0
  119. multi_agent_brief/contracts/source_metadata.py +252 -0
  120. multi_agent_brief/contracts/target_contract.py +460 -0
  121. multi_agent_brief/contracts/validator.py +225 -0
  122. multi_agent_brief/controls/__init__.py +23 -0
  123. multi_agent_brief/controls/contract.py +106 -0
  124. multi_agent_brief/controls/switchboard.py +1076 -0
  125. multi_agent_brief/core/__init__.py +2 -0
  126. multi_agent_brief/core/citations.py +14 -0
  127. multi_agent_brief/core/claim_ledger.py +94 -0
  128. multi_agent_brief/core/config.py +191 -0
  129. multi_agent_brief/core/env.py +69 -0
  130. multi_agent_brief/core/previous.py +83 -0
  131. multi_agent_brief/core/schemas.py +181 -0
  132. multi_agent_brief/core/selection.py +189 -0
  133. multi_agent_brief/delivery/__init__.py +6 -0
  134. multi_agent_brief/delivery/base.py +36 -0
  135. multi_agent_brief/delivery/feishu.py +204 -0
  136. multi_agent_brief/delivery/gws.py +237 -0
  137. multi_agent_brief/evaluation_cases/__init__.py +15 -0
  138. multi_agent_brief/evaluation_cases/contract.py +429 -0
  139. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/config.yaml +18 -0
  140. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/improvement/ledger.jsonl +2 -0
  141. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/sources.yaml +2 -0
  142. multi_agent_brief/evaluation_cases/fixtures/cases/approved_guidance_materialized/workspace/user.md +4 -0
  143. multi_agent_brief/evaluation_cases/fixtures/cases/company_event_missing_latest_official_check/workspace/config.yaml +13 -0
  144. multi_agent_brief/evaluation_cases/fixtures/cases/company_event_missing_latest_official_check/workspace/sources.yaml +9 -0
  145. multi_agent_brief/evaluation_cases/fixtures/cases/company_event_missing_latest_official_check/workspace/user.md +4 -0
  146. multi_agent_brief/evaluation_cases/fixtures/cases/control_switchboard_selection_is_not_execution/workspace/config.yaml +12 -0
  147. multi_agent_brief/evaluation_cases/fixtures/cases/control_switchboard_selection_is_not_execution/workspace/sources.yaml +6 -0
  148. multi_agent_brief/evaluation_cases/fixtures/cases/control_switchboard_selection_is_not_execution/workspace/user.md +4 -0
  149. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/config.yaml +6 -0
  150. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/input/human_feedback.md +1 -0
  151. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/sources.yaml +2 -0
  152. multi_agent_brief/evaluation_cases/fixtures/cases/feedback_triage_required/workspace/user.md +3 -0
  153. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/config.yaml +8 -0
  154. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/brief.md +14 -0
  155. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/audit_report.json +1 -0
  156. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/audited_brief.md +5 -0
  157. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/candidate_claims.json +1 -0
  158. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/claim_ledger.json +1 -0
  159. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/output/intermediate/screened_candidates.json +1 -0
  160. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/sources.yaml +2 -0
  161. multi_agent_brief/evaluation_cases/fixtures/cases/final_abstract_quality_warning_surface/workspace/user.md +3 -0
  162. multi_agent_brief/evaluation_cases/fixtures/cases/formal_release_missing_human_approval/workspace/config.yaml +13 -0
  163. multi_agent_brief/evaluation_cases/fixtures/cases/formal_release_missing_human_approval/workspace/sources.yaml +9 -0
  164. multi_agent_brief/evaluation_cases/fixtures/cases/formal_release_missing_human_approval/workspace/user.md +4 -0
  165. multi_agent_brief/evaluation_cases/fixtures/cases/guidance_manifestation_not_observable/workspace/config.yaml +4 -0
  166. multi_agent_brief/evaluation_cases/fixtures/cases/guidance_manifestation_not_observable/workspace/sources.yaml +2 -0
  167. multi_agent_brief/evaluation_cases/fixtures/cases/guidance_manifestation_not_observable/workspace/user.md +3 -0
  168. multi_agent_brief/evaluation_cases/fixtures/cases/media_only_legal_policy_blocks_research_review/workspace/config.yaml +13 -0
  169. multi_agent_brief/evaluation_cases/fixtures/cases/media_only_legal_policy_blocks_research_review/workspace/sources.yaml +9 -0
  170. multi_agent_brief/evaluation_cases/fixtures/cases/media_only_legal_policy_blocks_research_review/workspace/user.md +4 -0
  171. multi_agent_brief/evaluation_cases/fixtures/cases/mixed_metric_scope_support_blocker/workspace/config.yaml +13 -0
  172. multi_agent_brief/evaluation_cases/fixtures/cases/mixed_metric_scope_support_blocker/workspace/sources.yaml +9 -0
  173. multi_agent_brief/evaluation_cases/fixtures/cases/mixed_metric_scope_support_blocker/workspace/user.md +5 -0
  174. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/config.yaml +6 -0
  175. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/audited_brief.md +3 -0
  176. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/candidate_claims.json +1 -0
  177. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/claim_ledger.json +1 -0
  178. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/feedback_issues.json +25 -0
  179. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/repair_plan.json +27 -0
  180. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/output/intermediate/screened_candidates.json +1 -0
  181. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/sources.yaml +2 -0
  182. multi_agent_brief/evaluation_cases/fixtures/cases/planned_blocking_issue_cannot_continue/workspace/user.md +3 -0
  183. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/config.yaml +8 -0
  184. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/audit_report.json +1 -0
  185. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/audited_brief.md +3 -0
  186. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/candidate_claims.json +1 -0
  187. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/claim_ledger.json +11 -0
  188. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/quality_gate_report.json +22 -0
  189. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/output/intermediate/screened_candidates.json +1 -0
  190. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/sources.yaml +2 -0
  191. multi_agent_brief/evaluation_cases/fixtures/cases/provenance_projection_minimal/workspace/user.md +3 -0
  192. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/config.yaml +13 -0
  193. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/audit_report.json +1 -0
  194. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/audited_brief.md +5 -0
  195. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/candidate_claims.json +1 -0
  196. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/claim_ledger.json +40 -0
  197. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/output/intermediate/screened_candidates.json +1 -0
  198. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/sources.yaml +3 -0
  199. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_source_appendix/workspace/user.md +3 -0
  200. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/config.yaml +8 -0
  201. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/brief.md +3 -0
  202. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/audit_report.json +1 -0
  203. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/audited_brief.md +3 -0
  204. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/candidate_claims.json +1 -0
  205. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/claim_ledger.json +13 -0
  206. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/output/intermediate/screened_candidates.json +1 -0
  207. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/sources.yaml +2 -0
  208. multi_agent_brief/evaluation_cases/fixtures/cases/reader_facing_target_relevance/workspace/user.md +3 -0
  209. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/config.yaml +13 -0
  210. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/output/intermediate/release_readiness_report.json +31 -0
  211. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/sources.yaml +9 -0
  212. multi_agent_brief/evaluation_cases/fixtures/cases/release_readiness_forged_event_blocker/workspace/user.md +4 -0
  213. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/config.yaml +18 -0
  214. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/improvement/ledger.jsonl +3 -0
  215. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/improvement/memory.md +3 -0
  216. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/output/intermediate/improvement_memory_snapshot.md +3 -0
  217. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/sources.yaml +2 -0
  218. multi_agent_brief/evaluation_cases/fixtures/cases/reverted_entry_removed_from_next_snapshot/workspace/user.md +4 -0
  219. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/config.yaml +12 -0
  220. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/input/sources/source-001.txt +1 -0
  221. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/brief.md +37 -0
  222. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/delivery/brief.md +37 -0
  223. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/atomic_claim_graph.json +17 -0
  224. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/audit_report.json +5 -0
  225. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/audited_brief.md +37 -0
  226. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/claim_ledger.json +20 -0
  227. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/evidence_span_registry.json +20 -0
  228. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/finalize_report.json +40 -0
  229. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/gates/auditor_quality_gate_report.json +42 -0
  230. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/gates/finalize_quality_gate_report.json +42 -0
  231. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/intermediate/screened_candidates.json +33 -0
  232. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/source_appendix.md +12 -0
  233. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/output/source_appendix_trace.md +10 -0
  234. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/report_spec.yaml +24 -0
  235. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/sources.yaml +4 -0
  236. multi_agent_brief/evaluation_cases/fixtures/cases/same_evidence_reader_quality_regression/workspace/user.md +3 -0
  237. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/config.yaml +13 -0
  238. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/input/sources/README.md +4 -0
  239. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/output/intermediate/source_evidence_pack_manifest.json +26 -0
  240. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/sources.yaml +9 -0
  241. multi_agent_brief/evaluation_cases/fixtures/cases/source_evidence_pack_blocks_non_evidence_file/workspace/user.md +4 -0
  242. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/config.yaml +9 -0
  243. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/audit_report.json +1 -0
  244. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/audited_brief.md +3 -0
  245. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/candidate_claims.json +1 -0
  246. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/claim_ledger.json +13 -0
  247. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/output/intermediate/screened_candidates.json +1 -0
  248. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/sources.yaml +2 -0
  249. multi_agent_brief/evaluation_cases/fixtures/cases/stale_current_claim/workspace/user.md +3 -0
  250. multi_agent_brief/evaluation_cases/fixtures/cases/third_party_price_snapshot_formal_block/workspace/config.yaml +13 -0
  251. multi_agent_brief/evaluation_cases/fixtures/cases/third_party_price_snapshot_formal_block/workspace/sources.yaml +9 -0
  252. multi_agent_brief/evaluation_cases/fixtures/cases/third_party_price_snapshot_formal_block/workspace/user.md +4 -0
  253. multi_agent_brief/evaluation_cases/fixtures/cases/trajectory_retry_budget_exhausted/workspace/config.yaml +4 -0
  254. multi_agent_brief/evaluation_cases/fixtures/cases/trajectory_retry_budget_exhausted/workspace/sources.yaml +2 -0
  255. multi_agent_brief/evaluation_cases/fixtures/cases/trajectory_retry_budget_exhausted/workspace/user.md +3 -0
  256. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/config.yaml +18 -0
  257. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/improvement/ledger.jsonl +1 -0
  258. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/sources.yaml +2 -0
  259. multi_agent_brief/evaluation_cases/fixtures/cases/unapproved_entry_not_materialized/workspace/user.md +4 -0
  260. multi_agent_brief/evaluation_cases/fixtures/cases/unauthorized_institution_branding_blocks_release/workspace/config.yaml +18 -0
  261. multi_agent_brief/evaluation_cases/fixtures/cases/unauthorized_institution_branding_blocks_release/workspace/sources.yaml +9 -0
  262. multi_agent_brief/evaluation_cases/fixtures/cases/unauthorized_institution_branding_blocks_release/workspace/user.md +5 -0
  263. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/config.yaml +8 -0
  264. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/audit_report.json +1 -0
  265. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/audited_brief.md +8 -0
  266. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/candidate_claims.json +1 -0
  267. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/claim_ledger.json +1 -0
  268. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/output/intermediate/screened_candidates.json +1 -0
  269. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/sources.yaml +2 -0
  270. multi_agent_brief/evaluation_cases/fixtures/cases/unsupported_material_fact/workspace/user.md +3 -0
  271. multi_agent_brief/evaluation_cases/fixtures/manifest.yaml +861 -0
  272. multi_agent_brief/evaluation_cases/fixtures.py +20 -0
  273. multi_agent_brief/evaluation_cases/runner.py +1603 -0
  274. multi_agent_brief/experiments/__init__.py +45 -0
  275. multi_agent_brief/experiments/experiment_080.py +5835 -0
  276. multi_agent_brief/experiments/schemas.py +63 -0
  277. multi_agent_brief/experiments/target_contract.py +10 -0
  278. multi_agent_brief/feedback/__init__.py +17 -0
  279. multi_agent_brief/feedback/feedback_contract.py +482 -0
  280. multi_agent_brief/feedback/feedback_state.py +898 -0
  281. multi_agent_brief/hermes/__init__.py +25 -0
  282. multi_agent_brief/hermes/adapter.py +832 -0
  283. multi_agent_brief/improvement/__init__.py +83 -0
  284. multi_agent_brief/improvement/contract.py +1114 -0
  285. multi_agent_brief/improvement/memory.py +451 -0
  286. multi_agent_brief/improvement/product_definition.py +228 -0
  287. multi_agent_brief/improvement/state.py +961 -0
  288. multi_agent_brief/inputs/__init__.py +2 -0
  289. multi_agent_brief/inputs/classifier.py +322 -0
  290. multi_agent_brief/inputs/contracts.py +59 -0
  291. multi_agent_brief/inputs/extractor.py +310 -0
  292. multi_agent_brief/install/__init__.py +2 -0
  293. multi_agent_brief/install/writer.py +97 -0
  294. multi_agent_brief/onboarding/__init__.py +11 -0
  295. multi_agent_brief/onboarding/io.py +103 -0
  296. multi_agent_brief/onboarding/mapper.py +484 -0
  297. multi_agent_brief/onboarding/schema.py +46 -0
  298. multi_agent_brief/orchestrator/__init__.py +2 -0
  299. multi_agent_brief/orchestrator/fact_layer_import.py +352 -0
  300. multi_agent_brief/orchestrator/handoff.py +2209 -0
  301. multi_agent_brief/orchestrator/role_topology.py +42 -0
  302. multi_agent_brief/orchestrator/run_archive.py +888 -0
  303. multi_agent_brief/orchestrator/run_integrity.py +346 -0
  304. multi_agent_brief/orchestrator/runtime_state/__init__.py +70 -0
  305. multi_agent_brief/orchestrator/runtime_state/_io.py +167 -0
  306. multi_agent_brief/orchestrator/runtime_state/_transactions.py +298 -0
  307. multi_agent_brief/orchestrator/runtime_state/artifact_registry.py +1825 -0
  308. multi_agent_brief/orchestrator/runtime_state/atomic_claim_graph.py +96 -0
  309. multi_agent_brief/orchestrator/runtime_state/claim_ledger_freeze.py +510 -0
  310. multi_agent_brief/orchestrator/runtime_state/claim_metadata_enrichment.py +836 -0
  311. multi_agent_brief/orchestrator/runtime_state/claim_support_matrix.py +582 -0
  312. multi_agent_brief/orchestrator/runtime_state/completion_gates.py +672 -0
  313. multi_agent_brief/orchestrator/runtime_state/contracts_loader.py +66 -0
  314. multi_agent_brief/orchestrator/runtime_state/decisions.py +239 -0
  315. multi_agent_brief/orchestrator/runtime_state/errors.py +61 -0
  316. multi_agent_brief/orchestrator/runtime_state/event_log.py +256 -0
  317. multi_agent_brief/orchestrator/runtime_state/evidence_span_registry.py +233 -0
  318. multi_agent_brief/orchestrator/runtime_state/fact_layer.py +755 -0
  319. multi_agent_brief/orchestrator/runtime_state/identity.py +90 -0
  320. multi_agent_brief/orchestrator/runtime_state/lifecycle.py +675 -0
  321. multi_agent_brief/orchestrator/runtime_state/manifest.py +82 -0
  322. multi_agent_brief/orchestrator/runtime_state/operations.py +224 -0
  323. multi_agent_brief/orchestrator/runtime_state/paths.py +38 -0
  324. multi_agent_brief/orchestrator/runtime_state/repair.py +984 -0
  325. multi_agent_brief/orchestrator/runtime_state/safety_surfaces.py +147 -0
  326. multi_agent_brief/orchestrator/runtime_state/semantic_assessment_report.py +692 -0
  327. multi_agent_brief/orchestrator/runtime_state/semantic_support_acceptance.py +683 -0
  328. multi_agent_brief/orchestrator/runtime_state/source_evidence_pack.py +131 -0
  329. multi_agent_brief/orchestrator/runtime_state/stage_completion.py +1320 -0
  330. multi_agent_brief/orchestrator/runtime_state/trajectory.py +200 -0
  331. multi_agent_brief/orchestrator/runtime_state/workflow.py +350 -0
  332. multi_agent_brief/orchestrator/source_evidence.py +43 -0
  333. multi_agent_brief/orchestrator/timing.py +410 -0
  334. multi_agent_brief/orchestrator_contract.py +96 -0
  335. multi_agent_brief/outputs/__init__.py +2 -0
  336. multi_agent_brief/outputs/atomic_reader_projection.py +288 -0
  337. multi_agent_brief/outputs/docx.py +32 -0
  338. multi_agent_brief/outputs/finalize.py +1036 -0
  339. multi_agent_brief/outputs/ib_docx.py +983 -0
  340. multi_agent_brief/outputs/naming.py +38 -0
  341. multi_agent_brief/outputs/pdf.py +20 -0
  342. multi_agent_brief/outputs/reader_final_gate.py +509 -0
  343. multi_agent_brief/outputs/reader_projection.py +397 -0
  344. multi_agent_brief/outputs/source_appendix.py +753 -0
  345. multi_agent_brief/outputs/templates/__init__.py +112 -0
  346. multi_agent_brief/product/__init__.py +49 -0
  347. multi_agent_brief/product/bundle_projection.py +686 -0
  348. multi_agent_brief/product/citation_profile.py +145 -0
  349. multi_agent_brief/product/guidance_manifestation.py +421 -0
  350. multi_agent_brief/product/materiality_selection.py +472 -0
  351. multi_agent_brief/product/policy_gate_adapter.py +116 -0
  352. multi_agent_brief/product/policy_profile.py +39 -0
  353. multi_agent_brief/product/policy_projection.py +161 -0
  354. multi_agent_brief/product/policy_registry.py +83 -0
  355. multi_agent_brief/product/policy_resolver.py +225 -0
  356. multi_agent_brief/product/quality_closeout.py +188 -0
  357. multi_agent_brief/product/quality_panel.py +2217 -0
  358. multi_agent_brief/product/release_approval.py +1034 -0
  359. multi_agent_brief/product/report_pack.py +130 -0
  360. multi_agent_brief/product/report_pack_aliases.py +68 -0
  361. multi_agent_brief/product/report_registry.py +101 -0
  362. multi_agent_brief/product/report_spec.py +181 -0
  363. multi_agent_brief/product/support_wording.py +525 -0
  364. multi_agent_brief/product/template_conformance.py +516 -0
  365. multi_agent_brief/product/template_projection.py +123 -0
  366. multi_agent_brief/product/template_registry.py +244 -0
  367. multi_agent_brief/product/template_render_plan.py +315 -0
  368. multi_agent_brief/product/template_renderer.py +224 -0
  369. multi_agent_brief/product/trajectory_regulation.py +441 -0
  370. multi_agent_brief/provenance/__init__.py +5 -0
  371. multi_agent_brief/provenance/builder.py +841 -0
  372. multi_agent_brief/provenance/contract.py +21 -0
  373. multi_agent_brief/provenance/io.py +144 -0
  374. multi_agent_brief/provenance/model.py +110 -0
  375. multi_agent_brief/provenance/references.py +43 -0
  376. multi_agent_brief/provenance/validator.py +135 -0
  377. multi_agent_brief/quality_gates/__init__.py +19 -0
  378. multi_agent_brief/quality_gates/contract.py +581 -0
  379. multi_agent_brief/quality_gates/state.py +2498 -0
  380. multi_agent_brief/repair/__init__.py +5 -0
  381. multi_agent_brief/repair/router.py +842 -0
  382. multi_agent_brief/runtime_assets.py +431 -0
  383. multi_agent_brief/sources/__init__.py +16 -0
  384. multi_agent_brief/sources/api_filings.py +236 -0
  385. multi_agent_brief/sources/api_news.py +174 -0
  386. multi_agent_brief/sources/base.py +142 -0
  387. multi_agent_brief/sources/cached_package.py +119 -0
  388. multi_agent_brief/sources/cli_provider.py +263 -0
  389. multi_agent_brief/sources/coverage.py +336 -0
  390. multi_agent_brief/sources/decider.py +756 -0
  391. multi_agent_brief/sources/doctor.py +373 -0
  392. multi_agent_brief/sources/evidence_pack.py +364 -0
  393. multi_agent_brief/sources/feishu_provider.py +326 -0
  394. multi_agent_brief/sources/filing_resolver.py +400 -0
  395. multi_agent_brief/sources/industry_packs.py +130 -0
  396. multi_agent_brief/sources/join.py +206 -0
  397. multi_agent_brief/sources/local_signal.py +81 -0
  398. multi_agent_brief/sources/local_signal_planner.py +636 -0
  399. multi_agent_brief/sources/manual.py +259 -0
  400. multi_agent_brief/sources/mcp_provider.py +309 -0
  401. multi_agent_brief/sources/mineru_provider.py +601 -0
  402. multi_agent_brief/sources/normalizer.py +95 -0
  403. multi_agent_brief/sources/opencli_provider.py +282 -0
  404. multi_agent_brief/sources/planner.py +178 -0
  405. multi_agent_brief/sources/registry.py +367 -0
  406. multi_agent_brief/sources/rss.py +190 -0
  407. multi_agent_brief/sources/search_backends/__init__.py +31 -0
  408. multi_agent_brief/sources/search_backends/base.py +51 -0
  409. multi_agent_brief/sources/search_backends/brave.py +192 -0
  410. multi_agent_brief/sources/search_backends/capabilities.py +94 -0
  411. multi_agent_brief/sources/search_backends/exa.py +180 -0
  412. multi_agent_brief/sources/search_backends/firecrawl.py +164 -0
  413. multi_agent_brief/sources/search_backends/serper.py +241 -0
  414. multi_agent_brief/sources/search_backends/tavily.py +124 -0
  415. multi_agent_brief/sources/sourcehub.py +505 -0
  416. multi_agent_brief/sources/web_search.py +267 -0
  417. multi_agent_brief/status.py +966 -0
  418. multi_agent_brief/tools/__init__.py +3 -0
  419. multi_agent_brief/tools/draft_cleanup.py +198 -0
  420. multi_agent_brief/workbuddy/__init__.py +1 -0
  421. multi_agent_brief/workbuddy/diagnose.py +569 -0
  422. multi_agent_brief/workbuddy/skill_pack.py +309 -0
  423. multi_agent_brief/workspace/__init__.py +1 -0
  424. multi_agent_brief/workspace/init_profile.py +45 -0
@@ -0,0 +1,197 @@
1
+ """Contract for Claim (v1 + v2)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, ClassVar
6
+
7
+ from multi_agent_brief.contracts.base import Contract, SchemaRegistry
8
+ from multi_agent_brief.contracts.errors import FieldViolation
9
+ from multi_agent_brief.contracts.source_metadata import (
10
+ SOURCE_CATEGORY_FIELD,
11
+ local_file_without_url_missing_identity,
12
+ retrieval_source_type_error,
13
+ source_category_error,
14
+ source_category_missing,
15
+ source_url_error,
16
+ underlying_evidence_type_error,
17
+ )
18
+
19
+ REQUIRED_FIELDS = {"claim_id", "statement", "source_id", "evidence_text"}
20
+ KNOWN_FIELDS = REQUIRED_FIELDS | {
21
+ "source_url", "source_type", "claim_type", "confidence",
22
+ "requires_audit", "created_by", "used_in_sections", "metadata",
23
+ "schema_version", "epistemic_type", "evidence_relation",
24
+ "applicability_reason", "limitations",
25
+ }
26
+
27
+ VALID_CLAIM_TYPES = {"fact", "number", "date", "interpretation", "forecast", "risk"}
28
+ VALID_CONFIDENCE = {"low", "medium", "high"}
29
+ VALID_EPISTEMIC = {"observed", "interpreted", "hypothesis", "action", "analogy"}
30
+ VALID_EVIDENCE_RELATION = {"direct", "indirect", "inferred", "analogous"}
31
+
32
+
33
+ @SchemaRegistry.register
34
+ class ClaimContract(Contract):
35
+ schema_id: ClassVar[str] = "claim"
36
+ schema_version: ClassVar[str] = "v2"
37
+
38
+ @classmethod
39
+ def json_schema(cls) -> dict[str, Any]:
40
+ return {
41
+ "type": "object",
42
+ "required": sorted(REQUIRED_FIELDS),
43
+ "properties": {
44
+ "claim_id": {"type": "string"},
45
+ "statement": {"type": "string"},
46
+ "source_id": {"type": "string"},
47
+ "evidence_text": {"type": "string"},
48
+ "source_url": {"type": "string"},
49
+ "source_type": {"type": "string"},
50
+ "claim_type": {"type": "string", "enum": sorted(VALID_CLAIM_TYPES)},
51
+ "confidence": {"type": "string", "enum": sorted(VALID_CONFIDENCE)},
52
+ "requires_audit": {"type": "boolean"},
53
+ "created_by": {"type": "string"},
54
+ "used_in_sections": {"type": "array", "items": {"type": "string"}},
55
+ "metadata": {"type": "object"},
56
+ "schema_version": {"type": "string", "enum": ["v1", "v2"]},
57
+ "epistemic_type": {"type": "string", "enum": sorted(VALID_EPISTEMIC)},
58
+ "evidence_relation": {"type": "string", "enum": sorted(VALID_EVIDENCE_RELATION)},
59
+ "applicability_reason": {"type": "string"},
60
+ "limitations": {"type": "array", "items": {"type": "string"}},
61
+ },
62
+ "additionalProperties": True,
63
+ }
64
+
65
+ @classmethod
66
+ def validate(cls, data: dict[str, Any]) -> list[FieldViolation]:
67
+ violations: list[FieldViolation] = []
68
+
69
+ # Required fields
70
+ for fld in REQUIRED_FIELDS:
71
+ val = data.get(fld)
72
+ if val is None or (isinstance(val, str) and not val.strip()):
73
+ violations.append(FieldViolation(field=fld, error="required field is missing or blank"))
74
+
75
+ # Enum validation
76
+ claim_type = data.get("claim_type", "fact")
77
+ if claim_type not in VALID_CLAIM_TYPES:
78
+ violations.append(FieldViolation(
79
+ field="claim_type",
80
+ error=f"invalid claim_type '{claim_type}', must be one of {sorted(VALID_CLAIM_TYPES)}",
81
+ ))
82
+
83
+ confidence = data.get("confidence", "medium")
84
+ if confidence not in VALID_CONFIDENCE:
85
+ violations.append(FieldViolation(
86
+ field="confidence",
87
+ error=f"invalid confidence '{confidence}', must be one of {sorted(VALID_CONFIDENCE)}",
88
+ ))
89
+
90
+ # v2 required fields: when schema_version is "v2", epistemic fields must be present
91
+ schema_version = data.get("schema_version", "v1")
92
+ if schema_version == "v2":
93
+ for fld in ("epistemic_type", "evidence_relation"):
94
+ if fld not in data:
95
+ violations.append(FieldViolation(
96
+ field=fld,
97
+ error=f"required in v2 claim but missing",
98
+ ))
99
+
100
+ epistemic = data.get("epistemic_type")
101
+ if epistemic is not None and epistemic not in VALID_EPISTEMIC:
102
+ violations.append(FieldViolation(
103
+ field="epistemic_type",
104
+ error=f"invalid epistemic_type '{epistemic}', must be one of {sorted(VALID_EPISTEMIC)}",
105
+ ))
106
+
107
+ evidence_rel = data.get("evidence_relation")
108
+ if evidence_rel is not None and evidence_rel not in VALID_EVIDENCE_RELATION:
109
+ violations.append(FieldViolation(
110
+ field="evidence_relation",
111
+ error=f"invalid evidence_relation '{evidence_rel}', must be one of {sorted(VALID_EVIDENCE_RELATION)}",
112
+ ))
113
+
114
+ url_error = source_url_error(data.get("source_url"))
115
+ if url_error:
116
+ violations.append(FieldViolation(field="source_url", error=url_error))
117
+
118
+ metadata = data.get("metadata")
119
+ if metadata is not None and not isinstance(metadata, dict):
120
+ violations.append(FieldViolation(field="metadata", error="must be an object"))
121
+ metadata = {}
122
+ metadata = metadata or {}
123
+ metadata_url_error = source_url_error(metadata.get("source_url"))
124
+ if metadata_url_error:
125
+ violations.append(FieldViolation(field="metadata.source_url", error=metadata_url_error))
126
+ metadata_category_error = source_category_error(metadata.get(SOURCE_CATEGORY_FIELD))
127
+ if metadata_category_error:
128
+ violations.append(
129
+ FieldViolation(field=f"metadata.{SOURCE_CATEGORY_FIELD}", error=metadata_category_error)
130
+ )
131
+ elif source_category_missing(metadata):
132
+ violations.append(
133
+ FieldViolation(
134
+ field=f"metadata.{SOURCE_CATEGORY_FIELD}",
135
+ error="recommended reader-facing source category is missing",
136
+ severity="warning",
137
+ )
138
+ )
139
+ metadata_retrieval_error = retrieval_source_type_error(metadata.get("retrieval_source_type"))
140
+ if metadata_retrieval_error:
141
+ violations.append(
142
+ FieldViolation(field="metadata.retrieval_source_type", error=metadata_retrieval_error)
143
+ )
144
+ metadata_underlying_error = underlying_evidence_type_error(
145
+ metadata.get("underlying_evidence_type")
146
+ )
147
+ if metadata_underlying_error:
148
+ violations.append(
149
+ FieldViolation(
150
+ field="metadata.underlying_evidence_type",
151
+ error=metadata_underlying_error,
152
+ )
153
+ )
154
+ metadata_record = {
155
+ **metadata,
156
+ "source_type": data.get("source_type") or metadata.get("source_type"),
157
+ "source_url": data.get("source_url") or metadata.get("source_url"),
158
+ }
159
+ missing_local_identity = local_file_without_url_missing_identity(metadata_record)
160
+ if missing_local_identity:
161
+ violations.append(
162
+ FieldViolation(
163
+ field=f"metadata.{missing_local_identity}",
164
+ error="local_file sources without a URL should carry source title/name and source_category",
165
+ severity="warning",
166
+ )
167
+ )
168
+
169
+ # Unknown fields as warnings
170
+ unknown = set(data.keys()) - KNOWN_FIELDS
171
+ for field in sorted(unknown):
172
+ violations.append(FieldViolation(field=field, error="unknown field", severity="warning"))
173
+
174
+ return violations
175
+
176
+ @classmethod
177
+ def migrate(cls, data: dict[str, Any], from_version: str) -> dict[str, Any]:
178
+ if from_version == "v1":
179
+ return cls._migrate_v1_to_v2(data)
180
+ return dict(data)
181
+
182
+ @staticmethod
183
+ def _migrate_v1_to_v2(data: dict[str, Any]) -> dict[str, Any]:
184
+ result = dict(data)
185
+ # Map claim_type → epistemic_type
186
+ claim_type = result.get("claim_type", "fact")
187
+ epistemic_map = {
188
+ "interpretation": "interpreted",
189
+ "forecast": "hypothesis",
190
+ "risk": "hypothesis",
191
+ }
192
+ result["epistemic_type"] = epistemic_map.get(claim_type, "observed")
193
+ result["evidence_relation"] = result.get("evidence_relation", "direct")
194
+ result["applicability_reason"] = result.get("applicability_reason", "")
195
+ result["limitations"] = result.get("limitations", [])
196
+ result["schema_version"] = "v2"
197
+ return result
@@ -0,0 +1,386 @@
1
+ """Contract for Claim Draft collections."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, ClassVar
6
+
7
+ from multi_agent_brief.contracts.base import Contract, SchemaRegistry
8
+ from multi_agent_brief.contracts.errors import FieldViolation
9
+ from multi_agent_brief.contracts.source_metadata import (
10
+ SOURCE_CATEGORY_FIELD,
11
+ VALID_RETRIEVAL_SOURCE_TYPES,
12
+ VALID_SOURCE_CATEGORIES,
13
+ VALID_UNDERLYING_EVIDENCE_TYPES,
14
+ local_file_without_url_missing_identity,
15
+ retrieval_source_type_error,
16
+ source_category_error,
17
+ source_category_missing,
18
+ source_url_error,
19
+ underlying_evidence_type_error,
20
+ )
21
+ from multi_agent_brief.contracts.schemas.claim import (
22
+ VALID_CLAIM_TYPES,
23
+ VALID_CONFIDENCE,
24
+ VALID_EPISTEMIC,
25
+ VALID_EVIDENCE_RELATION,
26
+ )
27
+
28
+ TOP_LEVEL_REQUIRED_FIELDS = {"drafts"}
29
+ TOP_LEVEL_KNOWN_FIELDS = TOP_LEVEL_REQUIRED_FIELDS | {"schema_version", "metadata"}
30
+
31
+ DRAFT_REQUIRED_FIELD_ORDER = ("statement", "source_id", "evidence_text")
32
+ DRAFT_REQUIRED_FIELDS = set(DRAFT_REQUIRED_FIELD_ORDER)
33
+ DRAFT_KNOWN_FIELDS = DRAFT_REQUIRED_FIELDS | {
34
+ "draft_id",
35
+ "candidate_id",
36
+ "published_at",
37
+ "retrieved_at",
38
+ "source_path",
39
+ "source_title",
40
+ "source_name",
41
+ "publisher",
42
+ "source_category",
43
+ "topic",
44
+ "source_url",
45
+ "source_type",
46
+ "retrieval_source_type",
47
+ "underlying_evidence_type",
48
+ "raw_underlying_evidence_type",
49
+ "claim_type",
50
+ "confidence",
51
+ "requires_audit",
52
+ "created_by",
53
+ "used_in_sections",
54
+ "metadata",
55
+ "epistemic_type",
56
+ "evidence_relation",
57
+ "applicability_reason",
58
+ "limitations",
59
+ }
60
+ DRAFT_OPTIONAL_STRING_FIELDS = {
61
+ "draft_id",
62
+ "candidate_id",
63
+ "published_at",
64
+ "retrieved_at",
65
+ "source_path",
66
+ "source_title",
67
+ "source_name",
68
+ "publisher",
69
+ "source_category",
70
+ "topic",
71
+ "source_url",
72
+ "source_type",
73
+ "retrieval_source_type",
74
+ "underlying_evidence_type",
75
+ "raw_underlying_evidence_type",
76
+ "claim_type",
77
+ "confidence",
78
+ "created_by",
79
+ "epistemic_type",
80
+ "evidence_relation",
81
+ "applicability_reason",
82
+ }
83
+ DRAFT_OPTIONAL_STRING_LIST_FIELDS = {"used_in_sections", "limitations"}
84
+ RESERVED_ID_KEYS = {"claim_id"}
85
+ CLAIM_DRAFT_ALLOWED_VALUES = {
86
+ "claim_type": sorted(VALID_CLAIM_TYPES),
87
+ "confidence": sorted(VALID_CONFIDENCE),
88
+ "epistemic_type": sorted(VALID_EPISTEMIC),
89
+ "evidence_relation": sorted(VALID_EVIDENCE_RELATION),
90
+ "retrieval_source_type": sorted(VALID_RETRIEVAL_SOURCE_TYPES),
91
+ SOURCE_CATEGORY_FIELD: sorted(VALID_SOURCE_CATEGORIES),
92
+ "underlying_evidence_type": sorted(VALID_UNDERLYING_EVIDENCE_TYPES),
93
+ }
94
+ CLAIM_DRAFT_FORBIDDEN_FIELDS = sorted(RESERVED_ID_KEYS)
95
+
96
+
97
+ def claim_draft_diagnostics(violations: list[FieldViolation]) -> list[dict[str, Any]]:
98
+ """Return agent-facing diagnostics for claim draft validation failures."""
99
+
100
+ diagnostics: list[dict[str, Any]] = []
101
+ for violation in violations:
102
+ item: dict[str, Any] = {
103
+ "field": violation.field,
104
+ "error": violation.error,
105
+ "severity": violation.severity,
106
+ }
107
+ field_name = violation.field.rsplit(".", 1)[-1]
108
+ if field_name in CLAIM_DRAFT_ALLOWED_VALUES:
109
+ item["allowed_values"] = CLAIM_DRAFT_ALLOWED_VALUES[field_name]
110
+ if field_name in DRAFT_REQUIRED_FIELDS or violation.field == "drafts":
111
+ item["required_fields"] = list(DRAFT_REQUIRED_FIELD_ORDER)
112
+ if field_name in RESERVED_ID_KEYS:
113
+ item["forbidden_fields"] = CLAIM_DRAFT_FORBIDDEN_FIELDS
114
+ item["hint"] = "Remove claim_id; Python assigns CL-#### during freeze."
115
+ diagnostics.append(item)
116
+ return diagnostics
117
+
118
+
119
+ @SchemaRegistry.register
120
+ class ClaimDraftContract(Contract):
121
+ """Validate claim drafts before any future ID-allocation freeze step.
122
+
123
+ Claim drafts are pre-freeze inputs. They may carry source-grounded claim text,
124
+ but they must not carry stable Claim Ledger IDs.
125
+ """
126
+
127
+ schema_id: ClassVar[str] = "claim_drafts"
128
+ schema_version: ClassVar[str] = "v1"
129
+
130
+ @classmethod
131
+ def json_schema(cls) -> dict[str, Any]:
132
+ return {
133
+ "type": "object",
134
+ "required": sorted(TOP_LEVEL_REQUIRED_FIELDS),
135
+ "properties": {
136
+ "schema_version": {"type": "string", "enum": ["mabw.claim_drafts.v1"]},
137
+ "drafts": {
138
+ "type": "array",
139
+ "items": {
140
+ "type": "object",
141
+ "required": sorted(DRAFT_REQUIRED_FIELDS),
142
+ "properties": {
143
+ "draft_id": {"type": "string"},
144
+ "candidate_id": {"type": "string"},
145
+ "statement": {"type": "string"},
146
+ "source_id": {"type": "string"},
147
+ "evidence_text": {"type": "string"},
148
+ "published_at": {"type": "string"},
149
+ "retrieved_at": {"type": "string"},
150
+ "source_path": {"type": "string"},
151
+ "source_title": {"type": "string"},
152
+ "source_name": {"type": "string"},
153
+ "publisher": {"type": "string"},
154
+ "source_category": {
155
+ "type": "string",
156
+ "enum": sorted(VALID_SOURCE_CATEGORIES),
157
+ },
158
+ "topic": {"type": "string"},
159
+ "source_url": {"type": "string"},
160
+ "source_type": {"type": "string"},
161
+ "retrieval_source_type": {
162
+ "type": "string",
163
+ "enum": sorted(VALID_RETRIEVAL_SOURCE_TYPES),
164
+ },
165
+ "underlying_evidence_type": {
166
+ "type": "string",
167
+ "enum": sorted(VALID_UNDERLYING_EVIDENCE_TYPES),
168
+ },
169
+ "raw_underlying_evidence_type": {"type": "string"},
170
+ "claim_type": {"type": "string", "enum": sorted(VALID_CLAIM_TYPES)},
171
+ "confidence": {"type": "string", "enum": sorted(VALID_CONFIDENCE)},
172
+ "requires_audit": {"type": "boolean"},
173
+ "created_by": {"type": "string"},
174
+ "used_in_sections": {"type": "array", "items": {"type": "string"}},
175
+ "metadata": {"type": "object"},
176
+ "epistemic_type": {"type": "string", "enum": sorted(VALID_EPISTEMIC)},
177
+ "evidence_relation": {
178
+ "type": "string",
179
+ "enum": sorted(VALID_EVIDENCE_RELATION),
180
+ },
181
+ "applicability_reason": {"type": "string"},
182
+ "limitations": {"type": "array", "items": {"type": "string"}},
183
+ },
184
+ "not": {"required": ["claim_id"]},
185
+ "additionalProperties": True,
186
+ },
187
+ },
188
+ "metadata": {"type": "object"},
189
+ },
190
+ "additionalProperties": True,
191
+ }
192
+
193
+ @classmethod
194
+ def validate(cls, data: dict[str, Any]) -> list[FieldViolation]:
195
+ violations: list[FieldViolation] = []
196
+ if not isinstance(data, dict):
197
+ return [FieldViolation(field="<root>", error="must be an object")]
198
+
199
+ for field in TOP_LEVEL_REQUIRED_FIELDS:
200
+ if field not in data:
201
+ violations.append(FieldViolation(field=field, error="required field is missing"))
202
+
203
+ schema_version = data.get("schema_version")
204
+ if schema_version is not None and not isinstance(schema_version, str):
205
+ violations.append(FieldViolation(field="schema_version", error="must be a string"))
206
+ elif schema_version is not None and schema_version != "mabw.claim_drafts.v1":
207
+ violations.append(
208
+ FieldViolation(
209
+ field="schema_version",
210
+ error="must be mabw.claim_drafts.v1",
211
+ )
212
+ )
213
+ metadata = data.get("metadata")
214
+ if metadata is not None and not isinstance(metadata, dict):
215
+ violations.append(FieldViolation(field="metadata", error="must be an object"))
216
+
217
+ drafts = data.get("drafts")
218
+ if drafts is None:
219
+ drafts = []
220
+ elif not isinstance(drafts, list):
221
+ violations.append(FieldViolation(field="drafts", error="must be a list"))
222
+ drafts = []
223
+
224
+ for idx, draft in enumerate(drafts):
225
+ violations.extend(_validate_draft_entry(draft, idx))
226
+
227
+ unknown = set(data.keys()) - TOP_LEVEL_KNOWN_FIELDS
228
+ for field in sorted(unknown):
229
+ violations.append(FieldViolation(field=field, error="unknown field", severity="warning"))
230
+
231
+ return violations
232
+
233
+ @classmethod
234
+ def migrate(cls, data: dict[str, Any], from_version: str) -> dict[str, Any]:
235
+ return dict(data)
236
+
237
+
238
+ def _validate_draft_entry(data: Any, idx: int) -> list[FieldViolation]:
239
+ prefix = f"drafts[{idx}]"
240
+ violations: list[FieldViolation] = []
241
+ if not isinstance(data, dict):
242
+ return [FieldViolation(field=prefix, error="must be an object")]
243
+
244
+ if "claim_id" in data:
245
+ violations.append(
246
+ FieldViolation(
247
+ field=f"{prefix}.claim_id",
248
+ error="claim drafts must not contain claim_id; Python assigns IDs during freeze",
249
+ )
250
+ )
251
+ for path in _reserved_id_paths(data, prefix):
252
+ if path == f"{prefix}.claim_id":
253
+ continue
254
+ violations.append(
255
+ FieldViolation(
256
+ field=path,
257
+ error="claim drafts must not contain claim_id; Python assigns IDs during freeze",
258
+ )
259
+ )
260
+
261
+ for field in DRAFT_REQUIRED_FIELD_ORDER:
262
+ value = data.get(field)
263
+ if not isinstance(value, str) or not value.strip():
264
+ violations.append(
265
+ FieldViolation(field=f"{prefix}.{field}", error="must be a non-empty string")
266
+ )
267
+
268
+ for field in sorted(DRAFT_OPTIONAL_STRING_FIELDS):
269
+ value = data.get(field)
270
+ if value is not None and not isinstance(value, str):
271
+ violations.append(FieldViolation(field=f"{prefix}.{field}", error="must be a string"))
272
+
273
+ url_error = source_url_error(data.get("source_url"))
274
+ if url_error:
275
+ violations.append(FieldViolation(field=f"{prefix}.source_url", error=url_error))
276
+ category_error = source_category_error(data.get(SOURCE_CATEGORY_FIELD))
277
+ if category_error:
278
+ violations.append(FieldViolation(field=f"{prefix}.{SOURCE_CATEGORY_FIELD}", error=category_error))
279
+ elif source_category_missing(data):
280
+ violations.append(
281
+ FieldViolation(
282
+ field=f"{prefix}.{SOURCE_CATEGORY_FIELD}",
283
+ error="recommended reader-facing source category is missing",
284
+ severity="warning",
285
+ )
286
+ )
287
+ retrieval_error = retrieval_source_type_error(data.get("retrieval_source_type"))
288
+ if retrieval_error:
289
+ violations.append(FieldViolation(field=f"{prefix}.retrieval_source_type", error=retrieval_error))
290
+ underlying_error = underlying_evidence_type_error(data.get("underlying_evidence_type"))
291
+ if underlying_error:
292
+ violations.append(
293
+ FieldViolation(field=f"{prefix}.underlying_evidence_type", error=underlying_error)
294
+ )
295
+ missing_local_identity = local_file_without_url_missing_identity(
296
+ data,
297
+ default_source_type="local_file",
298
+ )
299
+ if missing_local_identity:
300
+ violations.append(
301
+ FieldViolation(
302
+ field=f"{prefix}.{missing_local_identity}",
303
+ error="local_file sources without a URL must carry source title/name and source_category",
304
+ )
305
+ )
306
+
307
+ for field in sorted(DRAFT_OPTIONAL_STRING_LIST_FIELDS):
308
+ value = data.get(field)
309
+ if value is None:
310
+ continue
311
+ if not isinstance(value, list):
312
+ violations.append(FieldViolation(field=f"{prefix}.{field}", error="must be a list"))
313
+ continue
314
+ for item_idx, item in enumerate(value):
315
+ if not isinstance(item, str):
316
+ violations.append(
317
+ FieldViolation(field=f"{prefix}.{field}[{item_idx}]", error="must be a string")
318
+ )
319
+
320
+ metadata = data.get("metadata")
321
+ if metadata is not None and not isinstance(metadata, dict):
322
+ violations.append(FieldViolation(field=f"{prefix}.metadata", error="must be an object"))
323
+
324
+ requires_audit = data.get("requires_audit")
325
+ if requires_audit is not None and not isinstance(requires_audit, bool):
326
+ violations.append(FieldViolation(field=f"{prefix}.requires_audit", error="must be a boolean"))
327
+
328
+ claim_type = data.get("claim_type")
329
+ if isinstance(claim_type, str) and claim_type not in VALID_CLAIM_TYPES:
330
+ violations.append(
331
+ FieldViolation(
332
+ field=f"{prefix}.claim_type",
333
+ error=f"invalid claim_type '{claim_type}', must be one of {sorted(VALID_CLAIM_TYPES)}",
334
+ )
335
+ )
336
+
337
+ confidence = data.get("confidence")
338
+ if isinstance(confidence, str) and confidence not in VALID_CONFIDENCE:
339
+ violations.append(
340
+ FieldViolation(
341
+ field=f"{prefix}.confidence",
342
+ error=f"invalid confidence '{confidence}', must be one of {sorted(VALID_CONFIDENCE)}",
343
+ )
344
+ )
345
+
346
+ epistemic = data.get("epistemic_type")
347
+ if isinstance(epistemic, str) and epistemic not in VALID_EPISTEMIC:
348
+ violations.append(
349
+ FieldViolation(
350
+ field=f"{prefix}.epistemic_type",
351
+ error=f"invalid epistemic_type '{epistemic}', must be one of {sorted(VALID_EPISTEMIC)}",
352
+ )
353
+ )
354
+
355
+ evidence_rel = data.get("evidence_relation")
356
+ if isinstance(evidence_rel, str) and evidence_rel not in VALID_EVIDENCE_RELATION:
357
+ violations.append(
358
+ FieldViolation(
359
+ field=f"{prefix}.evidence_relation",
360
+ error=(
361
+ f"invalid evidence_relation '{evidence_rel}', "
362
+ f"must be one of {sorted(VALID_EVIDENCE_RELATION)}"
363
+ ),
364
+ )
365
+ )
366
+
367
+ unknown = set(data.keys()) - DRAFT_KNOWN_FIELDS - {"claim_id"}
368
+ for field in sorted(unknown):
369
+ violations.append(
370
+ FieldViolation(field=f"{prefix}.{field}", error="unknown field", severity="warning")
371
+ )
372
+ return violations
373
+
374
+
375
+ def _reserved_id_paths(value: Any, prefix: str) -> list[str]:
376
+ paths: list[str] = []
377
+ if isinstance(value, dict):
378
+ for key, item in value.items():
379
+ path = f"{prefix}.{key}"
380
+ if key in RESERVED_ID_KEYS:
381
+ paths.append(path)
382
+ paths.extend(_reserved_id_paths(item, path))
383
+ elif isinstance(value, list):
384
+ for idx, item in enumerate(value):
385
+ paths.extend(_reserved_id_paths(item, f"{prefix}[{idx}]"))
386
+ return paths