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,753 @@
1
+ from __future__ import annotations
2
+
3
+ import hashlib
4
+ import json
5
+ import re
6
+ from dataclasses import asdict, dataclass, field
7
+ from pathlib import Path, PureWindowsPath
8
+ from typing import Any
9
+ from urllib.parse import urlparse
10
+
11
+ from multi_agent_brief.contracts.source_metadata import (
12
+ VALID_RETRIEVAL_SOURCE_TYPES,
13
+ VALID_SOURCE_CATEGORIES,
14
+ VALID_UNDERLYING_EVIDENCE_TYPES,
15
+ )
16
+ from multi_agent_brief.contracts.schemas.evidence_span_registry import EvidenceSpanRegistryContract
17
+ from multi_agent_brief.core.claim_ledger import ClaimLedger
18
+ from multi_agent_brief.core.schemas import Claim
19
+
20
+
21
+ _SRC_REF_RE = re.compile(r"\[src:([^\]]+)\]")
22
+ _LOCAL_PATH_MARKERS = ("/Users/", "/home/", "/private/", "/var/folders/")
23
+ _WINDOWS_USER_RE = re.compile(r"[A-Za-z]:\\Users\\")
24
+ _INTERNAL_ID_RE = re.compile(
25
+ r"\b(?:SYN_)?(?:CLAIM|SRC|SOURCE|CLM)_[A-Z0-9][A-Z0-9_-]*\b"
26
+ )
27
+ _TRACE_EXCERPT_LIMIT = 500
28
+ _SOURCE_CATEGORY_LABELS = {
29
+ "clin" + "ical_registry": "Clinical registry",
30
+ "company_press_release": "Company press release",
31
+ "industry_database": "Industry database",
32
+ "market_report": "Market report",
33
+ "news_media": "News media",
34
+ "other": "Other",
35
+ "peer_reviewed_paper": "Peer-reviewed paper",
36
+ "preprint": "Preprint",
37
+ "regulator": "Regulator",
38
+ }
39
+ _RETRIEVAL_SOURCE_TYPE_LABELS = {
40
+ "blog": "Blog",
41
+ "company_pr": "Company PR",
42
+ "dataset": "Dataset",
43
+ "filing": "Filing",
44
+ "local_file": "Local file",
45
+ "news_media": "News media",
46
+ "other": "Other",
47
+ "paper_page": "Paper page",
48
+ "podcast": "Podcast",
49
+ "social": "Social",
50
+ "video": "Video",
51
+ }
52
+ _UNDERLYING_EVIDENCE_TYPE_LABELS = {
53
+ "company_claim": "Company claim",
54
+ "conference_demo": "Conference demo",
55
+ "filing": "Filing",
56
+ "interview": "Interview",
57
+ "market_data": "Market data",
58
+ "media_report": "Media report",
59
+ "peer_reviewed_paper": "Peer-reviewed paper",
60
+ "regulator_record": "Regulator record",
61
+ "unknown": "Unknown",
62
+ }
63
+
64
+
65
+ @dataclass
66
+ class SourceAppendixRecord:
67
+ label: str
68
+ title: str
69
+ source_id: str = ""
70
+ source_ids: list[str] = field(default_factory=list)
71
+ publisher: str = ""
72
+ published_at: str = ""
73
+ retrieved_at: str = ""
74
+ url: str = ""
75
+ source_type: str = ""
76
+ source_category: str = ""
77
+ retrieval_source_type: str = ""
78
+ underlying_evidence_type: str = ""
79
+ claim_count: int = 0
80
+ claim_ids: list[str] = field(default_factory=list)
81
+ claim_ids_by_source_id: dict[str, list[str]] = field(default_factory=dict)
82
+ metadata_warnings: list[str] = field(default_factory=list)
83
+ span_count: int = 0
84
+ span_roles: list[str] = field(default_factory=list)
85
+
86
+ def to_dict(self) -> dict[str, Any]:
87
+ return asdict(self)
88
+
89
+
90
+ @dataclass
91
+ class SourceAppendixResult:
92
+ status: str
93
+ source_count: int = 0
94
+ cited_claim_count: int = 0
95
+ resolved_claim_count: int = 0
96
+ warnings: list[str] = field(default_factory=list)
97
+ markdown: str = ""
98
+ records: list[SourceAppendixRecord] = field(default_factory=list)
99
+ citation_labels: dict[str, str] = field(default_factory=dict)
100
+ claim_source_map: dict[str, dict[str, str]] = field(default_factory=dict)
101
+ trace_status: str = "not_available"
102
+ trace_markdown: str = ""
103
+ trace_source_count: int = 0
104
+ trace_span_count: int = 0
105
+ trace_warnings: list[str] = field(default_factory=list)
106
+
107
+ def to_report_fields(
108
+ self,
109
+ *,
110
+ source_appendix: str,
111
+ requested_by: str,
112
+ mode: str,
113
+ ) -> dict[str, Any]:
114
+ return {
115
+ "source_appendix": source_appendix,
116
+ "source_appendix_generation": self.status,
117
+ "source_appendix_requested_by": requested_by,
118
+ "source_appendix_mode": mode,
119
+ "source_appendix_source_count": self.source_count,
120
+ "source_appendix_cited_claim_count": self.cited_claim_count,
121
+ "source_appendix_resolved_claim_count": self.resolved_claim_count,
122
+ "source_appendix_warnings": list(self.warnings),
123
+ "source_appendix_claim_map": dict(self.claim_source_map),
124
+ "source_appendix_trace_generation": self.trace_status,
125
+ "source_appendix_trace_source_count": self.trace_source_count,
126
+ "source_appendix_trace_span_count": self.trace_span_count,
127
+ "source_appendix_trace_warnings": list(self.trace_warnings),
128
+ }
129
+
130
+
131
+ def cited_claim_ids(markdown: str) -> list[str]:
132
+ """Return [src:<claim_id>] references in first-appearance order."""
133
+ seen: set[str] = set()
134
+ claim_ids: list[str] = []
135
+ for match in _SRC_REF_RE.finditer(markdown):
136
+ claim_id = match.group(1).strip()
137
+ if not claim_id or claim_id in seen:
138
+ continue
139
+ seen.add(claim_id)
140
+ claim_ids.append(claim_id)
141
+ return claim_ids
142
+
143
+
144
+ def build_source_appendix(
145
+ *,
146
+ audited_markdown: str,
147
+ ledger_path: str | Path,
148
+ evidence_span_registry_path: str | Path | None = None,
149
+ workspace: str | Path | None = None,
150
+ ) -> SourceAppendixResult:
151
+ """Build reader-facing source appendix Markdown from cited Claim Ledger entries."""
152
+ claim_ids = cited_claim_ids(audited_markdown)
153
+ warnings: list[str] = []
154
+ ledger = ClaimLedger.import_json(ledger_path)
155
+ records_by_key: dict[str, SourceAppendixRecord] = {}
156
+ claim_source_keys: dict[str, str] = {}
157
+ source_ids_by_key: dict[str, list[str]] = {}
158
+ order: list[str] = []
159
+ resolved_claim_count = 0
160
+
161
+ for claim_id in claim_ids:
162
+ claim = ledger.get_claim(claim_id)
163
+ if claim is None:
164
+ warnings.append("A cited source reference could not be resolved.")
165
+ continue
166
+ resolved_claim_count += 1
167
+ source_record, source_warnings = _record_from_claim(claim)
168
+ warnings.extend(source_warnings)
169
+ key = _source_key(claim, source_record)
170
+ if key not in records_by_key:
171
+ order.append(key)
172
+ records_by_key[key] = source_record
173
+ record = records_by_key[key]
174
+ record.claim_count += 1
175
+ if claim_id not in record.claim_ids:
176
+ record.claim_ids.append(claim_id)
177
+ claim_source_keys[claim_id] = key
178
+ if claim.source_id:
179
+ source_id = claim.source_id.strip()
180
+ if source_id:
181
+ source_ids = source_ids_by_key.setdefault(key, [])
182
+ if source_id not in source_ids:
183
+ source_ids.append(source_id)
184
+ source_claim_ids = record.claim_ids_by_source_id.setdefault(source_id, [])
185
+ if claim_id not in source_claim_ids:
186
+ source_claim_ids.append(claim_id)
187
+
188
+ records = [records_by_key[key] for key in order]
189
+ for idx, record in enumerate(records, start=1):
190
+ record.label = f"S{idx}"
191
+ source_ids = source_ids_by_key.get(order[idx - 1], [])
192
+ record.source_ids = list(source_ids)
193
+ record.source_id = source_ids[0] if source_ids else ""
194
+ citation_labels = {
195
+ claim_id: records_by_key[key].label
196
+ for claim_id, key in claim_source_keys.items()
197
+ if key in records_by_key and records_by_key[key].label
198
+ }
199
+ claim_source_map = {
200
+ claim_id: _claim_source_map_record(records_by_key[key])
201
+ for claim_id, key in claim_source_keys.items()
202
+ if key in records_by_key and records_by_key[key].label
203
+ }
204
+ trace = _build_source_appendix_trace(
205
+ registry_path=evidence_span_registry_path,
206
+ workspace=workspace,
207
+ ledger_path=ledger_path,
208
+ records=records,
209
+ )
210
+
211
+ status = "generated_with_warnings" if warnings else "generated"
212
+ markdown = render_source_appendix(records, warnings=warnings)
213
+ return SourceAppendixResult(
214
+ status=status,
215
+ source_count=len(records),
216
+ cited_claim_count=len(claim_ids),
217
+ resolved_claim_count=resolved_claim_count,
218
+ warnings=warnings,
219
+ markdown=markdown,
220
+ records=records,
221
+ citation_labels=citation_labels,
222
+ claim_source_map=claim_source_map,
223
+ trace_status=trace["status"],
224
+ trace_markdown=trace["markdown"],
225
+ trace_source_count=trace["source_count"],
226
+ trace_span_count=trace["span_count"],
227
+ trace_warnings=trace["warnings"],
228
+ )
229
+
230
+
231
+ def replace_claim_citations_with_labels(
232
+ markdown: str,
233
+ citation_labels: dict[str, str],
234
+ ) -> str:
235
+ """Replace internal claim citations with reader-facing source labels."""
236
+
237
+ def _replace(match: re.Match[str]) -> str:
238
+ label = citation_labels.get(match.group(1).strip())
239
+ return f"[{label}]" if label else ""
240
+
241
+ text = _SRC_REF_RE.sub(_replace, markdown)
242
+ text = re.compile(r"\[src:[^\]]*\]").sub("", text)
243
+ text = re.sub(r"(\[S\d+\])(?:\s+\1)+", r"\1", text)
244
+ text = re.sub(r"\n{3,}", "\n\n", text)
245
+ return text.strip()
246
+
247
+
248
+ def render_source_appendix(
249
+ records: list[SourceAppendixRecord],
250
+ *,
251
+ warnings: list[str] | None = None,
252
+ ) -> str:
253
+ lines = [
254
+ "# Source Appendix",
255
+ "",
256
+ "This appendix lists source entries linked from the brief. It is a traceability surface, not semantic proof that every statement is correct.",
257
+ "",
258
+ "## Sources",
259
+ "",
260
+ ]
261
+ if not records:
262
+ lines.extend(["No reader-facing sources could be resolved from cited claims.", ""])
263
+ for record in records:
264
+ title = record.title or "Source record"
265
+ lines.append(f"### [{record.label}] {title}")
266
+ lines.append("")
267
+ if record.source_category:
268
+ lines.append(f"- Source category: {_source_category_label(record.source_category)}")
269
+ if record.retrieval_source_type:
270
+ lines.append(
271
+ f"- Retrieval source type: {_retrieval_source_type_label(record.retrieval_source_type)}"
272
+ )
273
+ if record.underlying_evidence_type and record.underlying_evidence_type != "unknown":
274
+ lines.append(
275
+ "- Underlying evidence type: "
276
+ f"{_underlying_evidence_type_label(record.underlying_evidence_type)}"
277
+ )
278
+ if record.publisher:
279
+ lines.append(f"- Publisher/Institution: {record.publisher}")
280
+ if record.published_at:
281
+ lines.append(f"- Published: {record.published_at}")
282
+ if record.retrieved_at:
283
+ lines.append(f"- Retrieved: {record.retrieved_at}")
284
+ if record.url:
285
+ lines.append(f"- URL: <{_markdown_autolink_url(record.url)}>")
286
+ if record.source_type:
287
+ lines.append(f"- Provider type: {record.source_type}")
288
+ lines.append(f"- Used in: {record.claim_count} claim-backed statement{'s' if record.claim_count != 1 else ''}")
289
+ if record.span_count:
290
+ role_summary = ", ".join(_reader_role_label(role) for role in record.span_roles)
291
+ lines.append(
292
+ f"- Evidence trace: {record.span_count} span{'s' if record.span_count != 1 else ''}"
293
+ + (f"; roles: {role_summary}" if role_summary else "")
294
+ )
295
+ lines.append("")
296
+ if warnings:
297
+ lines.extend([
298
+ "## Appendix Notes",
299
+ "",
300
+ "Some cited source metadata was incomplete or omitted from reader-facing output.",
301
+ "",
302
+ ])
303
+ for warning in sorted(dict.fromkeys(warnings)):
304
+ lines.append(f"- {warning}")
305
+ lines.append("")
306
+ return "\n".join(lines).rstrip() + "\n"
307
+
308
+
309
+ def _record_from_claim(claim: Claim) -> tuple[SourceAppendixRecord, list[str]]:
310
+ warnings: list[str] = []
311
+ metadata = claim.metadata or {}
312
+ raw_title = _first_text(
313
+ metadata.get("source_title"),
314
+ metadata.get("title"),
315
+ metadata.get("source_name"),
316
+ )
317
+ raw_publisher = _first_text(metadata.get("publisher"), metadata.get("source_name"))
318
+ title, title_warning = _safe_display_text(raw_title, field_name="source title")
319
+ publisher, publisher_warning = _safe_display_text(raw_publisher, field_name="publisher")
320
+ warnings.extend(item for item in (title_warning, publisher_warning) if item)
321
+
322
+ url, url_warning = _safe_url(claim.source_url or _first_text(metadata.get("url"), metadata.get("source_url")))
323
+ if url_warning:
324
+ warnings.append(url_warning)
325
+ published_at, published_warning = _safe_display_text(
326
+ _first_text(metadata.get("published_at"), metadata.get("publication_date")),
327
+ field_name="published date",
328
+ )
329
+ retrieved_at, retrieved_warning = _safe_display_text(
330
+ _first_text(metadata.get("retrieved_at"), metadata.get("accessed_at")),
331
+ field_name="retrieved date",
332
+ )
333
+ warnings.extend(item for item in (published_warning, retrieved_warning) if item)
334
+
335
+ source_type, type_warning = _safe_display_text(claim.source_type, field_name="source type")
336
+ if type_warning:
337
+ warnings.append(type_warning)
338
+
339
+ source_category, category_warning = _safe_source_category(
340
+ _first_text(metadata.get("source_category"), metadata.get("evidence_category"))
341
+ )
342
+ if category_warning:
343
+ warnings.append(category_warning)
344
+ if not source_category:
345
+ warnings.append("Source metadata missing source category.")
346
+
347
+ raw_retrieval = _first_text(metadata.get("retrieval_source_type"))
348
+ if not raw_retrieval:
349
+ provider_or_storage_type = _first_text(metadata.get("source_type"), claim.source_type)
350
+ if provider_or_storage_type in VALID_RETRIEVAL_SOURCE_TYPES:
351
+ raw_retrieval = provider_or_storage_type
352
+ retrieval_source_type, retrieval_warning = _safe_retrieval_source_type(raw_retrieval)
353
+ if retrieval_warning:
354
+ warnings.append(retrieval_warning)
355
+
356
+ underlying_raw = _first_text(metadata.get("underlying_evidence_type"))
357
+ underlying_evidence_type, underlying_warning = _safe_underlying_evidence_type(underlying_raw)
358
+ if underlying_warning:
359
+ warnings.append(underlying_warning)
360
+
361
+ if not title:
362
+ warnings.append("Source metadata missing source title/name.")
363
+ if not publisher:
364
+ warnings.append("Source metadata missing publisher/institution.")
365
+
366
+ title_for_completeness = title
367
+ if not title:
368
+ title = "Source record"
369
+
370
+ return (
371
+ SourceAppendixRecord(
372
+ label="",
373
+ title=title,
374
+ source_id=claim.source_id.strip() if claim.source_id else "",
375
+ publisher=publisher,
376
+ published_at=published_at,
377
+ retrieved_at=retrieved_at,
378
+ url=url,
379
+ source_type=source_type,
380
+ source_category=source_category,
381
+ retrieval_source_type=retrieval_source_type,
382
+ underlying_evidence_type=underlying_evidence_type,
383
+ metadata_warnings=_metadata_completeness_warnings(
384
+ title=title_for_completeness,
385
+ publisher=publisher,
386
+ source_category=source_category,
387
+ retrieval_source_type=retrieval_source_type,
388
+ underlying_evidence_type=underlying_evidence_type,
389
+ underlying_raw=underlying_raw,
390
+ ),
391
+ ),
392
+ warnings,
393
+ )
394
+
395
+
396
+ def _claim_source_map_record(record: SourceAppendixRecord) -> dict[str, str]:
397
+ payload = {
398
+ "source_label": record.label,
399
+ "source_url": record.url,
400
+ "evidence_title": record.title,
401
+ "source_title": record.title,
402
+ "source_published_at": record.published_at,
403
+ "retrieved_at": record.retrieved_at,
404
+ "source_type": record.source_type,
405
+ "source_category": record.source_category,
406
+ }
407
+ if record.retrieval_source_type:
408
+ payload["retrieval_source_type"] = record.retrieval_source_type
409
+ if record.underlying_evidence_type:
410
+ payload["underlying_evidence_type"] = record.underlying_evidence_type
411
+ return payload
412
+
413
+
414
+ def _build_source_appendix_trace(
415
+ *,
416
+ registry_path: str | Path | None,
417
+ workspace: str | Path | None,
418
+ ledger_path: str | Path,
419
+ records: list[SourceAppendixRecord],
420
+ ) -> dict[str, Any]:
421
+ empty = {
422
+ "status": "not_available",
423
+ "markdown": "",
424
+ "source_count": 0,
425
+ "span_count": 0,
426
+ "warnings": [],
427
+ }
428
+ if registry_path is None:
429
+ return empty
430
+ path = Path(registry_path)
431
+ if not path.exists():
432
+ return empty
433
+ try:
434
+ payload = json.loads(path.read_text(encoding="utf-8"))
435
+ except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
436
+ return _trace_skip(f"Evidence span trace skipped because evidence_span_registry.json is unreadable: {exc}")
437
+ if not isinstance(payload, dict):
438
+ return _trace_skip("Evidence span trace skipped because evidence_span_registry.json is not an object.")
439
+
440
+ violations = EvidenceSpanRegistryContract.validate(payload)
441
+ errors = [violation for violation in violations if violation.severity == "error"]
442
+ if errors:
443
+ return _trace_skip(
444
+ "Evidence span trace skipped because evidence_span_registry.json is invalid: "
445
+ f"evidence_span_registry_schema_error:{errors[0].field}"
446
+ )
447
+
448
+ ws = Path(workspace).expanduser().resolve() if workspace is not None else _workspace_from_ledger_path(ledger_path)
449
+ from multi_agent_brief.orchestrator.runtime_state.evidence_span_registry import (
450
+ EVIDENCE_SPAN_REGISTRY_VALIDATION_PREFIX,
451
+ validate_evidence_span_registry_against_source_pack,
452
+ )
453
+
454
+ reason = validate_evidence_span_registry_against_source_pack(
455
+ registry_payload=payload,
456
+ workspace=ws,
457
+ )
458
+ if reason:
459
+ return _trace_skip(
460
+ "Evidence span trace skipped because evidence_span_registry.json does not match source bytes: "
461
+ f"{EVIDENCE_SPAN_REGISTRY_VALIDATION_PREFIX}:{reason}"
462
+ )
463
+
464
+ records_by_source_id: dict[str, SourceAppendixRecord] = {}
465
+ trace_spans_by_label: dict[str, int] = {}
466
+ trace_roles_by_label: dict[str, set[str]] = {}
467
+ trace_sources: list[dict[str, Any]] = []
468
+ for record in records:
469
+ source_ids = record.source_ids or ([record.source_id] if record.source_id else [])
470
+ for source_id in source_ids:
471
+ normalized = str(source_id or "").strip()
472
+ if normalized:
473
+ records_by_source_id[normalized] = record
474
+ for source in sorted(
475
+ (item for item in payload.get("sources", []) if isinstance(item, dict)),
476
+ key=lambda item: str(item.get("source_id") or ""),
477
+ ):
478
+ source_id = str(source.get("source_id") or "").strip()
479
+ record = records_by_source_id.get(source_id)
480
+ if record is None:
481
+ continue
482
+ spans = [
483
+ span
484
+ for span in source.get("spans", [])
485
+ if isinstance(span, dict)
486
+ ]
487
+ if not spans:
488
+ continue
489
+ source_path = str(source.get("source_path") or "")
490
+ snapshot, snapshot_warning = _source_snapshot(ws=ws, source_path=source_path)
491
+ metadata_warnings = list(record.metadata_warnings)
492
+ if snapshot_warning:
493
+ metadata_warnings.append(snapshot_warning)
494
+ roles = sorted({
495
+ str(span.get("span_role") or "").strip()
496
+ for span in spans
497
+ if str(span.get("span_role") or "").strip()
498
+ })
499
+ trace_spans_by_label[record.label] = trace_spans_by_label.get(record.label, 0) + len(spans)
500
+ trace_roles_by_label.setdefault(record.label, set()).update(roles)
501
+ trace_sources.append({
502
+ "label": record.label,
503
+ "title": record.title,
504
+ "source_id": source_id,
505
+ "source_path": source_path,
506
+ "claim_ids": list(record.claim_ids_by_source_id.get(source_id) or record.claim_ids),
507
+ "source_sha256": snapshot.get("sha256", ""),
508
+ "source_size_bytes": snapshot.get("size_bytes", 0),
509
+ "metadata_warnings": metadata_warnings,
510
+ "spans": sorted(spans, key=lambda item: str(item.get("span_id") or "")),
511
+ })
512
+
513
+ if not trace_sources:
514
+ return _trace_skip("Evidence span trace skipped because no registry sources matched cited claims.")
515
+
516
+ for record in records:
517
+ if not record.label:
518
+ continue
519
+ record.span_count = trace_spans_by_label.get(record.label, 0)
520
+ record.span_roles = sorted(trace_roles_by_label.get(record.label, set()))
521
+
522
+ markdown = render_source_appendix_trace(trace_sources)
523
+ return {
524
+ "status": "generated",
525
+ "markdown": markdown,
526
+ "source_count": len(trace_sources),
527
+ "span_count": sum(len(source["spans"]) for source in trace_sources),
528
+ "warnings": [],
529
+ }
530
+
531
+
532
+ def _trace_skip(message: str) -> dict[str, Any]:
533
+ return {
534
+ "status": "skipped",
535
+ "markdown": "",
536
+ "source_count": 0,
537
+ "span_count": 0,
538
+ "warnings": [message],
539
+ }
540
+
541
+
542
+ def render_source_appendix_trace(trace_sources: list[dict[str, Any]]) -> str:
543
+ lines = [
544
+ "# Evidence Span Trace Audit Copy",
545
+ "",
546
+ "This audit copy lists machine-checkable Evidence Span Registry entries used by the source appendix. It is a traceability surface only, not semantic proof or support sufficiency.",
547
+ "",
548
+ ]
549
+ for source in trace_sources:
550
+ title = source.get("title") or "Local workspace source"
551
+ lines.extend([
552
+ f"## [{source.get('label')}] {title}",
553
+ "",
554
+ f"- Source ID: `{source.get('source_id')}`",
555
+ f"- Source path: `{source.get('source_path')}`",
556
+ "- Claim IDs: " + _inline_code_list(source.get("claim_ids") or []),
557
+ f"- Source SHA-256: `{source.get('source_sha256') or ''}`",
558
+ f"- Source size bytes: {source.get('source_size_bytes') or 0}",
559
+ f"- Span count: {len(source.get('spans') or [])}",
560
+ "",
561
+ ])
562
+ warnings = [str(item).strip() for item in source.get("metadata_warnings") or [] if str(item).strip()]
563
+ if warnings:
564
+ lines.extend(["Metadata warnings:", ""])
565
+ for warning in sorted(dict.fromkeys(warnings)):
566
+ lines.append(f"- {warning}")
567
+ lines.append("")
568
+ for span in source.get("spans") or []:
569
+ span_id = str(span.get("span_id") or "<unknown_span>").strip()
570
+ lines.extend([
571
+ f"### {span_id}",
572
+ "",
573
+ f"- Role: {_reader_role_label(str(span.get('span_role') or ''))}",
574
+ f"- Raw excerpt hash: `{span.get('hash') or ''}`",
575
+ ])
576
+ if isinstance(span.get("char_start"), int) and isinstance(span.get("char_end"), int):
577
+ lines.append(f"- Offsets: {span['char_start']}..{span['char_end']}")
578
+ lines.extend(["", "Raw excerpt:", ""])
579
+ lines.extend(_blockquote(_cap_excerpt(str(span.get("raw_excerpt") or ""))))
580
+ lines.append("")
581
+ return "\n".join(lines).rstrip() + "\n"
582
+
583
+
584
+ def _workspace_from_ledger_path(ledger_path: str | Path) -> Path:
585
+ path = Path(ledger_path).expanduser().resolve()
586
+ try:
587
+ return path.parents[2]
588
+ except IndexError:
589
+ return path.parent
590
+
591
+
592
+ def _reader_role_label(role: str) -> str:
593
+ return role.replace("_", " ").strip()
594
+
595
+
596
+ def _source_category_label(category: str) -> str:
597
+ return _SOURCE_CATEGORY_LABELS.get(category, category.replace("_", " ").strip().title())
598
+
599
+
600
+ def _retrieval_source_type_label(value: str) -> str:
601
+ return _RETRIEVAL_SOURCE_TYPE_LABELS.get(value, value.replace("_", " ").strip().title())
602
+
603
+
604
+ def _underlying_evidence_type_label(value: str) -> str:
605
+ return _UNDERLYING_EVIDENCE_TYPE_LABELS.get(value, value.replace("_", " ").strip().title())
606
+
607
+
608
+ def _safe_retrieval_source_type(value: str) -> tuple[str, str]:
609
+ raw = str(value or "").strip()
610
+ if not raw:
611
+ return "", ""
612
+ if raw not in VALID_RETRIEVAL_SOURCE_TYPES:
613
+ return "", "Omitted retrieval source type because it was not recognized."
614
+ return raw, ""
615
+
616
+
617
+ def _safe_underlying_evidence_type(value: str) -> tuple[str, str]:
618
+ raw = str(value or "").strip()
619
+ if not raw:
620
+ return "", ""
621
+ if raw not in VALID_UNDERLYING_EVIDENCE_TYPES:
622
+ return "", "Omitted underlying evidence type because it was not recognized."
623
+ return raw, ""
624
+
625
+
626
+ def _metadata_completeness_warnings(
627
+ *,
628
+ title: str,
629
+ publisher: str,
630
+ source_category: str,
631
+ retrieval_source_type: str,
632
+ underlying_evidence_type: str,
633
+ underlying_raw: str,
634
+ ) -> list[str]:
635
+ warnings: list[str] = []
636
+ if not title:
637
+ warnings.append("Source metadata missing source title/name.")
638
+ if not publisher:
639
+ warnings.append("Source metadata missing publisher/institution.")
640
+ if not source_category:
641
+ warnings.append("Source metadata missing source category.")
642
+ if not retrieval_source_type:
643
+ warnings.append("Source metadata missing retrieval source type.")
644
+ if not underlying_raw:
645
+ warnings.append("Source metadata missing underlying evidence type.")
646
+ elif underlying_evidence_type == "unknown":
647
+ warnings.append("Source metadata underlying evidence type is unknown.")
648
+ return warnings
649
+
650
+
651
+ def _source_snapshot(*, ws: Path, source_path: str) -> tuple[dict[str, Any], str]:
652
+ if not source_path:
653
+ return {}, "Source snapshot unavailable because source path is missing."
654
+ try:
655
+ path = (ws / source_path).resolve()
656
+ root = (ws / "input" / "sources").resolve()
657
+ path.relative_to(root)
658
+ data = path.read_bytes()
659
+ except (OSError, ValueError):
660
+ return {}, "Source snapshot unavailable because source bytes could not be read."
661
+ return {
662
+ "sha256": hashlib.sha256(data).hexdigest(),
663
+ "size_bytes": len(data),
664
+ }, ""
665
+
666
+
667
+ def _inline_code_list(values: list[Any]) -> str:
668
+ items = [f"`{str(value).strip()}`" for value in values if str(value).strip()]
669
+ return ", ".join(items) if items else "`<none>`"
670
+
671
+
672
+ def _cap_excerpt(text: str) -> str:
673
+ if len(text) <= _TRACE_EXCERPT_LIMIT:
674
+ return text
675
+ return text[:_TRACE_EXCERPT_LIMIT].rstrip() + "... [truncated]"
676
+
677
+
678
+ def _blockquote(text: str) -> list[str]:
679
+ if not text:
680
+ return [">"]
681
+ return ["> " + line for line in text.splitlines()]
682
+
683
+
684
+ def _source_key(claim: Claim, record: SourceAppendixRecord) -> str:
685
+ if record.url:
686
+ return f"url:{_normalize(record.url)}"
687
+ if claim.source_id:
688
+ return f"source_id:{_normalize(claim.source_id)}"
689
+ return f"title:{_normalize(record.title)}|publisher:{_normalize(record.publisher)}"
690
+
691
+
692
+ def _first_text(*values: Any) -> str:
693
+ for value in values:
694
+ if isinstance(value, str) and value.strip():
695
+ return value.strip()
696
+ return ""
697
+
698
+
699
+ def _safe_display_text(value: str, *, field_name: str) -> tuple[str, str]:
700
+ value = " ".join(str(value or "").split())
701
+ if not value:
702
+ return "", ""
703
+ if _contains_private_path(value):
704
+ return "", f"Omitted {field_name} because it looked like a local path."
705
+ if value.lower().startswith("file://"):
706
+ return "", f"Omitted {field_name} because it used a file:// reference."
707
+ if _contains_internal_id(value):
708
+ return "", f"Omitted {field_name} because it looked like an internal ID."
709
+ return value, ""
710
+
711
+
712
+ def _safe_url(value: str) -> tuple[str, str]:
713
+ raw = str(value or "").strip()
714
+ if not raw:
715
+ return "", ""
716
+ if _contains_private_path(raw) or raw.lower().startswith("file://"):
717
+ return "", "Omitted source URL because it was local or file-based."
718
+ parsed = urlparse(raw)
719
+ if parsed.scheme not in {"http", "https"} or not parsed.netloc:
720
+ return "", "Omitted source URL because it was not an HTTP(S) URL."
721
+ return raw, ""
722
+
723
+
724
+ def _markdown_autolink_url(value: str) -> str:
725
+ return str(value).replace("<", "%3C").replace(">", "%3E").replace(" ", "%20")
726
+
727
+
728
+ def _safe_source_category(value: str) -> tuple[str, str]:
729
+ raw = str(value or "").strip()
730
+ if not raw:
731
+ return "", ""
732
+ if raw not in VALID_SOURCE_CATEGORIES:
733
+ return "", "Omitted source category because it was not recognized."
734
+ return raw, ""
735
+
736
+
737
+ def _contains_private_path(value: str) -> bool:
738
+ if any(marker in value for marker in _LOCAL_PATH_MARKERS):
739
+ return True
740
+ if _WINDOWS_USER_RE.search(value):
741
+ return True
742
+ try:
743
+ return PureWindowsPath(value).is_absolute()
744
+ except ValueError:
745
+ return False
746
+
747
+
748
+ def _contains_internal_id(value: str) -> bool:
749
+ return bool(_INTERNAL_ID_RE.search(value))
750
+
751
+
752
+ def _normalize(value: str) -> str:
753
+ return " ".join(str(value or "").strip().lower().split())