@yahyahammad/venastine 0.3.8 → 0.3.10

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 (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
@@ -1,345 +1,345 @@
1
- """
2
- core/reasoning/output_writer.py
3
-
4
- Writes every pass's output to OUTPUT_DIR/<run_id>/, matching the
5
- original pipeline spec's file layout (ROADMAP §12). NOT called
6
- automatically from the pipeline -- it stays
7
- a pure computation returning a PipelineRun; writing files (or not) is
8
- the CALLER's decision (see main.py's research mode, §1). This keeps the
9
- pipeline function's side effects minimal and makes it trivially testable
10
- without touching a filesystem.
11
-
12
- Relationship to §5's pipeline_storage.py: that module is for
13
- programmatic resume/inspection (a database row, checked by run_id).
14
- This module is for a human-browsable directory on disk -- a different
15
- artifact, for a different audience, both keyed by the same run.run_id
16
- so they correlate.
17
-
18
- Claims are serialized with vars(c), matching every other
19
- claim-serialization call site in this codebase (orchestrator.py passes
20
- 3a/3b/4/6a/6b/final synthesis, pipeline_storage.update_pipeline_run,
21
- and this module's write_run_artifacts). If a nested-dataclass field is
22
- ever added to Claim, ALL of those sites migrate to asdict(c) together
23
- -- see the note on Claim in core/reasoning/base.py.
24
- """
25
-
26
- from __future__ import annotations
27
-
28
- import json
29
- import logging
30
- import os
31
- from typing import TYPE_CHECKING
32
-
33
- import config
34
-
35
- if TYPE_CHECKING:
36
- from core.reasoning.base import PipelineRun
37
-
38
- logger = logging.getLogger(__name__)
39
-
40
-
41
- def _tier_counts(run: PipelineRun) -> tuple[list[str], list[int]]:
42
- """Returns (tier_labels, counts) for the confidence chart. Extracted
43
- as a pure function so the counting logic can be unit-tested without
44
- rendering the chart."""
45
- tiers = ["HIGH", "MEDIUM", "LOW", "UNVERIFIED"]
46
- counts = [sum(1 for c in run.claims if c.confidence_tier == t) for t in tiers]
47
- tiers.append("UNVERIFIED_COVERAGE")
48
- counts.append(len(run.coverage_gaps))
49
- return tiers, counts
50
-
51
-
52
- def write_run_artifacts(run: PipelineRun) -> str:
53
- """Writes the full artifact directory for one pipeline run and
54
- returns the output directory path.
55
-
56
- Layout under OUTPUT_DIR/<run_id>/:
57
- 00_plan.md Pass 0 plan (JSON)
58
- 01_raw_response.md Pass 1 raw generation (single-candidate runs)
59
- 01_candidate_N.md E13/#77: per-candidate generation, one file
60
- per SURVIVOR, written instead of
61
- 01_raw_response.md whenever two or more
62
- survived -- the N matches the trace's
63
- candidate-N lines and the claims'
64
- asserted_by_candidates tags, so the record
65
- can substantiate its own consistency scores.
66
- A run degraded to one survivor names its
67
- file 01_raw_response.md like any other
68
- single-candidate run.
69
- 02_claims.json Pass 2 extracted claims (full vars(c))
70
- 03_grounding.json Pass 3a grounding per claim
71
- 03_critic.json Pass 3b critic per claim
72
- 03_completeness.json Pass 3c completeness findings
73
- 04_assumptions.json Pass 4 assumption audit
74
- 05_confidence.json Pass 5 tier + score breakdown per claim
75
- 06_revisions.json 6a/6b revisions (only if any claim was revised)
76
- 07_review.json §20 review findings + decisions (only if reviewed)
77
- granted_calls.json §25 audit trail (only if a grant was spent)
78
- pass_threads.json §27 one entry per pass, {"pass", "thread_id"}
79
- confidence_chart.svg Tier distribution bar chart (batch 212)
80
- trace.md Full trace log
81
- report.md Final synthesis report
82
- report.pdf PDF rendering (only if markdown+weasyprint installed)
83
- sources/index.json §45 one entry per URL this run retrieved text
84
- from: url, title, tool, retrieved_at, sha256,
85
- chars. Always written when anything was
86
- retrieved -- provenance, not content.
87
- sources/<sha256>.txt §45 the text itself, redacted, one file per
88
- document. Only when config.PERSIST_SOURCE_TEXT
89
- is on (it is by default); index.json's
90
- `persisted_text` says which.
91
- code/ (placeholder for future code artifacts)
92
- """
93
- if run.run_id is None:
94
- raise ValueError(
95
- "Cannot write artifacts: run.run_id is None. "
96
- "Persistence must be enabled (the pipeline "
97
- "sets run_id via create_pipeline_run)."
98
- )
99
-
100
- output_dir = os.path.join(config.OUTPUT_DIR, str(run.run_id))
101
- os.makedirs(output_dir, exist_ok=True)
102
- os.makedirs(os.path.join(output_dir, "sources"), exist_ok=True)
103
- os.makedirs(os.path.join(output_dir, "code"), exist_ok=True)
104
-
105
- def write(filename, content):
106
- with open(os.path.join(output_dir, filename), "w", encoding="utf-8") as f:
107
- f.write(content)
108
-
109
- write("00_plan.md", json.dumps(run.plan, indent=2))
110
- # E13/#77. Two or more survivors: every candidate is an equal -- none
111
- # is "the" response, Pass 2 extracted claims from their union and the
112
- # report is synthesised from those claims -- so naming candidate 1's
113
- # text `01_raw_response.md` would dress a positional convention up as
114
- # a distinction the pipeline never made. One numbered file per
115
- # survivor, matching the numbering everywhere else. One survivor (or
116
- # none -- ensemble mode never ran): the historical single-candidate
117
- # shape, unchanged byte for byte.
118
- if len(getattr(run, "candidates", []) or []) >= 2:
119
- for entry in run.candidates:
120
- write(f"01_candidate_{entry['candidate']}.md",
121
- entry.get("text", ""))
122
- else:
123
- write("01_raw_response.md", run.raw_response)
124
- write("02_claims.json", json.dumps([vars(c) for c in run.claims], indent=2))
125
- write("03_grounding.json", json.dumps(
126
- [{"claim_id": c.id, "sources": c.grounding_sources, "status": c.grounding_status}
127
- for c in run.claims],
128
- indent=2,
129
- ))
130
- write("03_critic.json", json.dumps(
131
- [{"claim_id": c.id, "fallacies": c.fallacies, "contradictions": c.contradictions,
132
- "severity": c.critic_severity}
133
- for c in run.claims],
134
- indent=2,
135
- ))
136
- write("03_completeness.json", json.dumps(run.completeness, indent=2))
137
- write("04_assumptions.json", json.dumps(run.assumptions, indent=2))
138
- write("05_confidence.json", json.dumps(
139
- [{"claim_id": c.id, "tier": c.confidence_tier, "score_breakdown": c.score_breakdown}
140
- for c in run.claims],
141
- indent=2,
142
- ))
143
-
144
- revised = [c for c in run.claims if c.revision_text is not None]
145
- if revised:
146
- write("06_revisions.json", json.dumps(
147
- [{"claim_id": c.id, "revised_text": c.revision_text, "retry_count": c.retry_count}
148
- for c in revised],
149
- indent=2,
150
- ))
151
-
152
- # §25: written ONLY when the run actually spent a grant, so its
153
- # presence in an output directory is itself the signal that this run
154
- # ran with pre-flight authorization. An always-empty file next to
155
- # twelve populated ones reads as "nothing happened here" and would be
156
- # skimmed past, which is the opposite of an audit trail's job.
157
- if run.granted_calls:
158
- write("granted_calls.json", json.dumps(run.granted_calls, indent=2))
159
-
160
- # §20: same rule, same reason. Its presence in an output directory is
161
- # itself the signal that this run was reviewed -- and on a run with no
162
- # consent route it is the ONLY durable record of what the reviewer
163
- # found, since nothing was applied for the claims file to show.
164
- if run.subagent_reviews:
165
- write("07_review.json", json.dumps(run.subagent_reviews, indent=2))
166
-
167
- _write_sources(run, output_dir)
168
-
169
- # §27 AC6: which thread each pass ran in. Written unconditionally
170
- # (unlike the two above), because it is not a signal about how the run
171
- # was configured -- every run has pass threads, and an empty file here
172
- # would itself be the anomaly worth noticing.
173
- write("pass_threads.json",
174
- json.dumps(getattr(run, "pass_threads", []) or [], indent=2))
175
-
176
- # Essential human-readable artifacts first -- a supplementary-file
177
- # failure (chart, PDF) must not prevent these from being written.
178
- write("trace.md", "\n".join(f"- {line}" for line in run.trace))
179
- write("report.md", run.final_report)
180
-
181
- # Supplementary artifacts -- failure here is non-fatal.
182
- _write_confidence_chart(run, output_dir)
183
- _try_write_pdf(run.final_report, output_dir)
184
-
185
- return output_dir
186
-
187
-
188
- def _write_sources(run: PipelineRun, output_dir: str) -> None:
189
- """Populate sources/ with what each cited page actually served.
190
-
191
- ROADMAP_v2 §45 (SQ8). This directory has been created and left empty
192
- since §12, while `fetch_url.py`'s own comment described the artifact
193
- that would fill it. Without it, `03_grounding.json` is URLs and
194
- numbers: a reader cannot check a `similarity_score` against anything,
195
- and neither can anyone re-running the scoring later.
196
-
197
- ONE FILE PER DOCUMENT, named by the sha256 of its text. The hash is
198
- also carried in the index, so a source's entry and its file are
199
- linked, and two runs that fetched the same page produce the same
200
- filename -- which makes them diffable.
201
-
202
- `index.json` is written whatever `PERSIST_SOURCE_TEXT` says. Which
203
- URLs a run retrieved, when, through which tool, and how much text they
204
- gave is provenance rather than content: it is the part that says
205
- whether a score COULD have been computed, and withholding it would
206
- make an opted-out run indistinguishable from one that fetched nothing.
207
-
208
- Degrades loudly, never fatally (#81): a run that produced a report
209
- must not fail over an artifact directory.
210
- """
211
- documents = getattr(run, "source_documents", None) or []
212
- if not documents:
213
- return
214
-
215
- sources_dir = os.path.join(output_dir, "sources")
216
- keep_text = getattr(config, "PERSIST_SOURCE_TEXT", True)
217
- try:
218
- index = []
219
- for document in documents:
220
- entry = {k: v for k, v in document.items() if k != "text"}
221
- index.append(entry)
222
- if keep_text:
223
- with open(os.path.join(sources_dir, f"{document['sha256']}.txt"),
224
- "w", encoding="utf-8") as f:
225
- f.write(document.get("text", ""))
226
- index_payload = {"persisted_text": bool(keep_text), "sources": index}
227
- with open(os.path.join(sources_dir, "index.json"), "w",
228
- encoding="utf-8") as f:
229
- json.dump(index_payload, f, indent=2)
230
- except Exception as e:
231
- logger.warning("Source texts skipped (write failed): %s", e)
232
-
233
-
234
- def _axis_step(top: int) -> int:
235
- """A 1, 2 or 5 times a power of ten that puts at most ten gridlines
236
- under `top`, so the axis reads in round numbers whatever the count."""
237
- step = 1
238
- while True:
239
- for factor in (1, 2, 5):
240
- if top <= 10 * step * factor:
241
- return step * factor
242
- step *= 10
243
-
244
-
245
- def confidence_svg(tiers: list, counts: list) -> str:
246
- """The tier distribution as one standalone SVG document.
247
-
248
- BATCH 212, THE OWNER'S CHOICE. This was matplotlib, which with numpy,
249
- fonttools, pillow and seven smaller packages was 126 MB of a 367 MB
250
- install, measured, for these five bars; it also rebuilt a font cache
251
- for minutes in a fresh environment. Drawn by hand now: fixed geometry,
252
- integer gridlines, the count over each bar, and a white background so
253
- the chart reads in a dark-themed viewer too. Every label is escaped,
254
- though today they are the fixed tier names.
255
- """
256
- # html.escape, not xml.sax.saxutils.escape (batch 217): it escapes
257
- # both quotes by default, which an attribute needs, and importing
258
- # xml.sax is bandit's B406 whatever is used from it.
259
- from html import escape
260
-
261
- width, height = 640, 400
262
- left, right, top_pad, bottom = 64, 40, 56, 52
263
- plot_w = width - left - right
264
- plot_h = height - top_pad - bottom
265
- peak = max(counts, default=0)
266
- step = _axis_step(max(peak, 1))
267
- axis_top = max(step, -(-peak // step) * step)
268
- base = top_pad + plot_h
269
-
270
- def y_of(value: int) -> float:
271
- return base - plot_h * value / axis_top
272
-
273
- out = [
274
- f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" '
275
- f'height="{height}" viewBox="0 0 {width} {height}" '
276
- f'font-family="DejaVu Sans, Arial, Helvetica, sans-serif">',
277
- '<title>Confidence tier distribution</title>',
278
- f'<rect width="{width}" height="{height}" fill="#ffffff"/>',
279
- f'<text x="{width / 2:g}" y="32" font-size="18" '
280
- f'text-anchor="middle" fill="#222222">Confidence tier distribution'
281
- f'</text>',
282
- f'<text x="18" y="{top_pad + plot_h / 2:g}" font-size="13" '
283
- f'text-anchor="middle" fill="#222222" transform="rotate(-90 18 '
284
- f'{top_pad + plot_h / 2:g})">Number of claims</text>',
285
- ]
286
- for value in range(0, axis_top + 1, step):
287
- y = y_of(value)
288
- out.append(f'<line x1="{left}" y1="{y:g}" x2="{width - right}" '
289
- f'y2="{y:g}" stroke="#dddddd" stroke-width="1"/>')
290
- out.append(f'<text x="{left - 8}" y="{y + 4:g}" font-size="12" '
291
- f'text-anchor="end" fill="#444444">{value}</text>')
292
- slot = plot_w / max(len(tiers), 1)
293
- bar_w = slot * 0.6
294
- for index, (tier, count) in enumerate(zip(tiers, counts)):
295
- x = left + slot * index + (slot - bar_w) / 2
296
- y = y_of(count)
297
- centre = x + bar_w / 2
298
- label = escape(str(tier))
299
- out.append(f'<rect class="bar" data-tier="{label}" '
300
- f'data-count="{int(count)}" x="{x:g}" y="{y:g}" '
301
- f'width="{bar_w:g}" height="{base - y:g}" '
302
- f'fill="#1f77b4"/>')
303
- out.append(f'<text x="{centre:g}" y="{y - 6:g}" font-size="12" '
304
- f'text-anchor="middle" fill="#222222">{int(count)}</text>')
305
- out.append(f'<text x="{centre:g}" y="{base + 20:g}" font-size="11" '
306
- f'text-anchor="middle" fill="#222222">'
307
- f'{escape(str(tier).replace("_", " "))}</text>')
308
- out.append(f'<line x1="{left}" y1="{base:g}" x2="{width - right}" '
309
- f'y2="{base:g}" stroke="#444444" stroke-width="1"/>')
310
- out.append("</svg>")
311
- return "\n".join(out) + "\n"
312
-
313
-
314
- def _write_confidence_chart(run: PipelineRun, output_dir: str) -> None:
315
- """Bar chart of confidence tier distribution. Degrades loudly, never
316
- fatally: a failure here must not crash a completed pipeline run over a
317
- chart (#81), and every degrade path warns naming the helper and the
318
- cause, because a chart failing on every run is exactly the signal
319
- worth shouting, not hiding."""
320
- try:
321
- tiers, counts = _tier_counts(run)
322
- svg = confidence_svg(tiers, counts)
323
- with open(os.path.join(output_dir, "confidence_chart.svg"), "w",
324
- encoding="utf-8") as f:
325
- f.write(svg)
326
- except Exception as e:
327
- logger.warning("Confidence chart skipped (render failed): %s", e)
328
-
329
-
330
- def _try_write_pdf(report_markdown: str, output_dir: str) -> None:
331
- """Also degrades loudly, never fatally (#81). No markdown-to-PDF
332
- library is currently a project dependency -- install markdown +
333
- weasyprint if you want this to actually produce output; until then
334
- this warns and skips rather than failing the run."""
335
- try:
336
- import markdown
337
- import weasyprint
338
- except Exception as e:
339
- logger.warning("PDF report skipped (converters unavailable): %s", e)
340
- return
341
- try:
342
- html = markdown.markdown(report_markdown)
343
- weasyprint.HTML(string=html).write_pdf(os.path.join(output_dir, "report.pdf"))
344
- except Exception as e:
345
- logger.warning("PDF report skipped (render failed): %s", e)
1
+ """
2
+ core/reasoning/output_writer.py
3
+
4
+ Writes every pass's output to OUTPUT_DIR/<run_id>/, matching the
5
+ original pipeline spec's file layout (ROADMAP §12). NOT called
6
+ automatically from the pipeline -- it stays
7
+ a pure computation returning a PipelineRun; writing files (or not) is
8
+ the CALLER's decision (see main.py's research mode, §1). This keeps the
9
+ pipeline function's side effects minimal and makes it trivially testable
10
+ without touching a filesystem.
11
+
12
+ Relationship to §5's pipeline_storage.py: that module is for
13
+ programmatic resume/inspection (a database row, checked by run_id).
14
+ This module is for a human-browsable directory on disk -- a different
15
+ artifact, for a different audience, both keyed by the same run.run_id
16
+ so they correlate.
17
+
18
+ Claims are serialized with vars(c), matching every other
19
+ claim-serialization call site in this codebase (orchestrator.py passes
20
+ 3a/3b/4/6a/6b/final synthesis, pipeline_storage.update_pipeline_run,
21
+ and this module's write_run_artifacts). If a nested-dataclass field is
22
+ ever added to Claim, ALL of those sites migrate to asdict(c) together
23
+ -- see the note on Claim in core/reasoning/base.py.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ import json
29
+ import logging
30
+ import os
31
+ from typing import TYPE_CHECKING
32
+
33
+ import config
34
+
35
+ if TYPE_CHECKING:
36
+ from core.reasoning.base import PipelineRun
37
+
38
+ logger = logging.getLogger(__name__)
39
+
40
+
41
+ def _tier_counts(run: PipelineRun) -> tuple[list[str], list[int]]:
42
+ """Returns (tier_labels, counts) for the confidence chart. Extracted
43
+ as a pure function so the counting logic can be unit-tested without
44
+ rendering the chart."""
45
+ tiers = ["HIGH", "MEDIUM", "LOW", "UNVERIFIED"]
46
+ counts = [sum(1 for c in run.claims if c.confidence_tier == t) for t in tiers]
47
+ tiers.append("UNVERIFIED_COVERAGE")
48
+ counts.append(len(run.coverage_gaps))
49
+ return tiers, counts
50
+
51
+
52
+ def write_run_artifacts(run: PipelineRun) -> str:
53
+ """Writes the full artifact directory for one pipeline run and
54
+ returns the output directory path.
55
+
56
+ Layout under OUTPUT_DIR/<run_id>/:
57
+ 00_plan.md Pass 0 plan (JSON)
58
+ 01_raw_response.md Pass 1 raw generation (single-candidate runs)
59
+ 01_candidate_N.md E13/#77: per-candidate generation, one file
60
+ per SURVIVOR, written instead of
61
+ 01_raw_response.md whenever two or more
62
+ survived -- the N matches the trace's
63
+ candidate-N lines and the claims'
64
+ asserted_by_candidates tags, so the record
65
+ can substantiate its own consistency scores.
66
+ A run degraded to one survivor names its
67
+ file 01_raw_response.md like any other
68
+ single-candidate run.
69
+ 02_claims.json Pass 2 extracted claims (full vars(c))
70
+ 03_grounding.json Pass 3a grounding per claim
71
+ 03_critic.json Pass 3b critic per claim
72
+ 03_completeness.json Pass 3c completeness findings
73
+ 04_assumptions.json Pass 4 assumption audit
74
+ 05_confidence.json Pass 5 tier + score breakdown per claim
75
+ 06_revisions.json 6a/6b revisions (only if any claim was revised)
76
+ 07_review.json §20 review findings + decisions (only if reviewed)
77
+ granted_calls.json §25 audit trail (only if a grant was spent)
78
+ pass_threads.json §27 one entry per pass, {"pass", "thread_id"}
79
+ confidence_chart.svg Tier distribution bar chart (batch 212)
80
+ trace.md Full trace log
81
+ report.md Final synthesis report
82
+ report.pdf PDF rendering (only if markdown+weasyprint installed)
83
+ sources/index.json §45 one entry per URL this run retrieved text
84
+ from: url, title, tool, retrieved_at, sha256,
85
+ chars. Always written when anything was
86
+ retrieved -- provenance, not content.
87
+ sources/<sha256>.txt §45 the text itself, redacted, one file per
88
+ document. Only when config.PERSIST_SOURCE_TEXT
89
+ is on (it is by default); index.json's
90
+ `persisted_text` says which.
91
+ code/ (placeholder for future code artifacts)
92
+ """
93
+ if run.run_id is None:
94
+ raise ValueError(
95
+ "Cannot write artifacts: run.run_id is None. "
96
+ "Persistence must be enabled (the pipeline "
97
+ "sets run_id via create_pipeline_run)."
98
+ )
99
+
100
+ output_dir = os.path.join(config.OUTPUT_DIR, str(run.run_id))
101
+ os.makedirs(output_dir, exist_ok=True)
102
+ os.makedirs(os.path.join(output_dir, "sources"), exist_ok=True)
103
+ os.makedirs(os.path.join(output_dir, "code"), exist_ok=True)
104
+
105
+ def write(filename, content):
106
+ with open(os.path.join(output_dir, filename), "w", encoding="utf-8") as f:
107
+ f.write(content)
108
+
109
+ write("00_plan.md", json.dumps(run.plan, indent=2))
110
+ # E13/#77. Two or more survivors: every candidate is an equal -- none
111
+ # is "the" response, Pass 2 extracted claims from their union and the
112
+ # report is synthesised from those claims -- so naming candidate 1's
113
+ # text `01_raw_response.md` would dress a positional convention up as
114
+ # a distinction the pipeline never made. One numbered file per
115
+ # survivor, matching the numbering everywhere else. One survivor (or
116
+ # none -- ensemble mode never ran): the historical single-candidate
117
+ # shape, unchanged byte for byte.
118
+ if len(getattr(run, "candidates", []) or []) >= 2:
119
+ for entry in run.candidates:
120
+ write(f"01_candidate_{entry['candidate']}.md",
121
+ entry.get("text", ""))
122
+ else:
123
+ write("01_raw_response.md", run.raw_response)
124
+ write("02_claims.json", json.dumps([vars(c) for c in run.claims], indent=2))
125
+ write("03_grounding.json", json.dumps(
126
+ [{"claim_id": c.id, "sources": c.grounding_sources, "status": c.grounding_status}
127
+ for c in run.claims],
128
+ indent=2,
129
+ ))
130
+ write("03_critic.json", json.dumps(
131
+ [{"claim_id": c.id, "fallacies": c.fallacies, "contradictions": c.contradictions,
132
+ "severity": c.critic_severity}
133
+ for c in run.claims],
134
+ indent=2,
135
+ ))
136
+ write("03_completeness.json", json.dumps(run.completeness, indent=2))
137
+ write("04_assumptions.json", json.dumps(run.assumptions, indent=2))
138
+ write("05_confidence.json", json.dumps(
139
+ [{"claim_id": c.id, "tier": c.confidence_tier, "score_breakdown": c.score_breakdown}
140
+ for c in run.claims],
141
+ indent=2,
142
+ ))
143
+
144
+ revised = [c for c in run.claims if c.revision_text is not None]
145
+ if revised:
146
+ write("06_revisions.json", json.dumps(
147
+ [{"claim_id": c.id, "revised_text": c.revision_text, "retry_count": c.retry_count}
148
+ for c in revised],
149
+ indent=2,
150
+ ))
151
+
152
+ # §25: written ONLY when the run actually spent a grant, so its
153
+ # presence in an output directory is itself the signal that this run
154
+ # ran with pre-flight authorization. An always-empty file next to
155
+ # twelve populated ones reads as "nothing happened here" and would be
156
+ # skimmed past, which is the opposite of an audit trail's job.
157
+ if run.granted_calls:
158
+ write("granted_calls.json", json.dumps(run.granted_calls, indent=2))
159
+
160
+ # §20: same rule, same reason. Its presence in an output directory is
161
+ # itself the signal that this run was reviewed -- and on a run with no
162
+ # consent route it is the ONLY durable record of what the reviewer
163
+ # found, since nothing was applied for the claims file to show.
164
+ if run.subagent_reviews:
165
+ write("07_review.json", json.dumps(run.subagent_reviews, indent=2))
166
+
167
+ _write_sources(run, output_dir)
168
+
169
+ # §27 AC6: which thread each pass ran in. Written unconditionally
170
+ # (unlike the two above), because it is not a signal about how the run
171
+ # was configured -- every run has pass threads, and an empty file here
172
+ # would itself be the anomaly worth noticing.
173
+ write("pass_threads.json",
174
+ json.dumps(getattr(run, "pass_threads", []) or [], indent=2))
175
+
176
+ # Essential human-readable artifacts first -- a supplementary-file
177
+ # failure (chart, PDF) must not prevent these from being written.
178
+ write("trace.md", "\n".join(f"- {line}" for line in run.trace))
179
+ write("report.md", run.final_report)
180
+
181
+ # Supplementary artifacts -- failure here is non-fatal.
182
+ _write_confidence_chart(run, output_dir)
183
+ _try_write_pdf(run.final_report, output_dir)
184
+
185
+ return output_dir
186
+
187
+
188
+ def _write_sources(run: PipelineRun, output_dir: str) -> None:
189
+ """Populate sources/ with what each cited page actually served.
190
+
191
+ ROADMAP_v2 §45 (SQ8). This directory has been created and left empty
192
+ since §12, while `fetch_url.py`'s own comment described the artifact
193
+ that would fill it. Without it, `03_grounding.json` is URLs and
194
+ numbers: a reader cannot check a `similarity_score` against anything,
195
+ and neither can anyone re-running the scoring later.
196
+
197
+ ONE FILE PER DOCUMENT, named by the sha256 of its text. The hash is
198
+ also carried in the index, so a source's entry and its file are
199
+ linked, and two runs that fetched the same page produce the same
200
+ filename -- which makes them diffable.
201
+
202
+ `index.json` is written whatever `PERSIST_SOURCE_TEXT` says. Which
203
+ URLs a run retrieved, when, through which tool, and how much text they
204
+ gave is provenance rather than content: it is the part that says
205
+ whether a score COULD have been computed, and withholding it would
206
+ make an opted-out run indistinguishable from one that fetched nothing.
207
+
208
+ Degrades loudly, never fatally (#81): a run that produced a report
209
+ must not fail over an artifact directory.
210
+ """
211
+ documents = getattr(run, "source_documents", None) or []
212
+ if not documents:
213
+ return
214
+
215
+ sources_dir = os.path.join(output_dir, "sources")
216
+ keep_text = getattr(config, "PERSIST_SOURCE_TEXT", True)
217
+ try:
218
+ index = []
219
+ for document in documents:
220
+ entry = {k: v for k, v in document.items() if k != "text"}
221
+ index.append(entry)
222
+ if keep_text:
223
+ with open(os.path.join(sources_dir, f"{document['sha256']}.txt"),
224
+ "w", encoding="utf-8") as f:
225
+ f.write(document.get("text", ""))
226
+ index_payload = {"persisted_text": bool(keep_text), "sources": index}
227
+ with open(os.path.join(sources_dir, "index.json"), "w",
228
+ encoding="utf-8") as f:
229
+ json.dump(index_payload, f, indent=2)
230
+ except Exception as e:
231
+ logger.warning("Source texts skipped (write failed): %s", e)
232
+
233
+
234
+ def _axis_step(top: int) -> int:
235
+ """A 1, 2 or 5 times a power of ten that puts at most ten gridlines
236
+ under `top`, so the axis reads in round numbers whatever the count."""
237
+ step = 1
238
+ while True:
239
+ for factor in (1, 2, 5):
240
+ if top <= 10 * step * factor:
241
+ return step * factor
242
+ step *= 10
243
+
244
+
245
+ def confidence_svg(tiers: list, counts: list) -> str:
246
+ """The tier distribution as one standalone SVG document.
247
+
248
+ BATCH 212, THE OWNER'S CHOICE. This was matplotlib, which with numpy,
249
+ fonttools, pillow and seven smaller packages was 126 MB of a 367 MB
250
+ install, measured, for these five bars; it also rebuilt a font cache
251
+ for minutes in a fresh environment. Drawn by hand now: fixed geometry,
252
+ integer gridlines, the count over each bar, and a white background so
253
+ the chart reads in a dark-themed viewer too. Every label is escaped,
254
+ though today they are the fixed tier names.
255
+ """
256
+ # html.escape, not xml.sax.saxutils.escape (batch 217): it escapes
257
+ # both quotes by default, which an attribute needs, and importing
258
+ # xml.sax is bandit's B406 whatever is used from it.
259
+ from html import escape
260
+
261
+ width, height = 640, 400
262
+ left, right, top_pad, bottom = 64, 40, 56, 52
263
+ plot_w = width - left - right
264
+ plot_h = height - top_pad - bottom
265
+ peak = max(counts, default=0)
266
+ step = _axis_step(max(peak, 1))
267
+ axis_top = max(step, -(-peak // step) * step)
268
+ base = top_pad + plot_h
269
+
270
+ def y_of(value: int) -> float:
271
+ return base - plot_h * value / axis_top
272
+
273
+ out = [
274
+ f'<svg xmlns="http://www.w3.org/2000/svg" width="{width}" '
275
+ f'height="{height}" viewBox="0 0 {width} {height}" '
276
+ f'font-family="DejaVu Sans, Arial, Helvetica, sans-serif">',
277
+ '<title>Confidence tier distribution</title>',
278
+ f'<rect width="{width}" height="{height}" fill="#ffffff"/>',
279
+ f'<text x="{width / 2:g}" y="32" font-size="18" '
280
+ f'text-anchor="middle" fill="#222222">Confidence tier distribution'
281
+ f'</text>',
282
+ f'<text x="18" y="{top_pad + plot_h / 2:g}" font-size="13" '
283
+ f'text-anchor="middle" fill="#222222" transform="rotate(-90 18 '
284
+ f'{top_pad + plot_h / 2:g})">Number of claims</text>',
285
+ ]
286
+ for value in range(0, axis_top + 1, step):
287
+ y = y_of(value)
288
+ out.append(f'<line x1="{left}" y1="{y:g}" x2="{width - right}" '
289
+ f'y2="{y:g}" stroke="#dddddd" stroke-width="1"/>')
290
+ out.append(f'<text x="{left - 8}" y="{y + 4:g}" font-size="12" '
291
+ f'text-anchor="end" fill="#444444">{value}</text>')
292
+ slot = plot_w / max(len(tiers), 1)
293
+ bar_w = slot * 0.6
294
+ for index, (tier, count) in enumerate(zip(tiers, counts)):
295
+ x = left + slot * index + (slot - bar_w) / 2
296
+ y = y_of(count)
297
+ centre = x + bar_w / 2
298
+ label = escape(str(tier))
299
+ out.append(f'<rect class="bar" data-tier="{label}" '
300
+ f'data-count="{int(count)}" x="{x:g}" y="{y:g}" '
301
+ f'width="{bar_w:g}" height="{base - y:g}" '
302
+ f'fill="#1f77b4"/>')
303
+ out.append(f'<text x="{centre:g}" y="{y - 6:g}" font-size="12" '
304
+ f'text-anchor="middle" fill="#222222">{int(count)}</text>')
305
+ out.append(f'<text x="{centre:g}" y="{base + 20:g}" font-size="11" '
306
+ f'text-anchor="middle" fill="#222222">'
307
+ f'{escape(str(tier).replace("_", " "))}</text>')
308
+ out.append(f'<line x1="{left}" y1="{base:g}" x2="{width - right}" '
309
+ f'y2="{base:g}" stroke="#444444" stroke-width="1"/>')
310
+ out.append("</svg>")
311
+ return "\n".join(out) + "\n"
312
+
313
+
314
+ def _write_confidence_chart(run: PipelineRun, output_dir: str) -> None:
315
+ """Bar chart of confidence tier distribution. Degrades loudly, never
316
+ fatally: a failure here must not crash a completed pipeline run over a
317
+ chart (#81), and every degrade path warns naming the helper and the
318
+ cause, because a chart failing on every run is exactly the signal
319
+ worth shouting, not hiding."""
320
+ try:
321
+ tiers, counts = _tier_counts(run)
322
+ svg = confidence_svg(tiers, counts)
323
+ with open(os.path.join(output_dir, "confidence_chart.svg"), "w",
324
+ encoding="utf-8") as f:
325
+ f.write(svg)
326
+ except Exception as e:
327
+ logger.warning("Confidence chart skipped (render failed): %s", e)
328
+
329
+
330
+ def _try_write_pdf(report_markdown: str, output_dir: str) -> None:
331
+ """Also degrades loudly, never fatally (#81). No markdown-to-PDF
332
+ library is currently a project dependency -- install markdown +
333
+ weasyprint if you want this to actually produce output; until then
334
+ this warns and skips rather than failing the run."""
335
+ try:
336
+ import markdown
337
+ import weasyprint
338
+ except Exception as e:
339
+ logger.warning("PDF report skipped (converters unavailable): %s", e)
340
+ return
341
+ try:
342
+ html = markdown.markdown(report_markdown)
343
+ weasyprint.HTML(string=html).write_pdf(os.path.join(output_dir, "report.pdf"))
344
+ except Exception as e:
345
+ logger.warning("PDF report skipped (render failed): %s", e)