@yahyahammad/venastine 0.2.0 → 0.3.9

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 (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -1,286 +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 a PNG."""
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.png Tier distribution bar chart (matplotlib)
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 _write_confidence_chart(run: PipelineRun, output_dir: str) -> None:
235
- """Bar chart of confidence tier distribution. Degrades loudly, never
236
- fatally -- matplotlib is a project dependency (requirements.txt), but
237
- any failure here (missing import, backend error, rendering error)
238
- must not crash a completed pipeline run over a chart (#81). Every
239
- degrade path warns naming the helper and the cause: a chart failing
240
- on every run is exactly the signal worth shouting, not hiding."""
241
- try:
242
- import matplotlib
243
- matplotlib.use("Agg") # headless, no display needed
244
- import matplotlib.pyplot as plt
245
- except Exception as e:
246
- logger.warning(
247
- "Confidence chart skipped (matplotlib unavailable): %s", e)
248
- return
249
-
250
- # #81. `fig` is bound INSIDE the try, so a failure before the binding
251
- # used to leave `finally: plt.close(fig)` raising UnboundLocalError --
252
- # the containment guard inverting into exactly the crash it existed to
253
- # prevent. Binding None first makes "nothing to clean up" a state
254
- # instead of an exception.
255
- fig = None
256
- try:
257
- tiers, counts = _tier_counts(run)
258
- fig, ax = plt.subplots()
259
- ax.bar(tiers, counts)
260
- ax.set_ylabel("Number of claims")
261
- ax.set_title("Confidence tier distribution")
262
- fig.tight_layout()
263
- fig.savefig(os.path.join(output_dir, "confidence_chart.png"))
264
- except Exception as e:
265
- logger.warning("Confidence chart skipped (render failed): %s", e)
266
- finally:
267
- if fig is not None:
268
- plt.close(fig)
269
-
270
-
271
- def _try_write_pdf(report_markdown: str, output_dir: str) -> None:
272
- """Also degrades loudly, never fatally (#81). No markdown-to-PDF
273
- library is currently a project dependency -- install markdown +
274
- weasyprint if you want this to actually produce output; until then
275
- this warns and skips rather than failing the run."""
276
- try:
277
- import markdown
278
- import weasyprint
279
- except Exception as e:
280
- logger.warning("PDF report skipped (converters unavailable): %s", e)
281
- return
282
- try:
283
- html = markdown.markdown(report_markdown)
284
- weasyprint.HTML(string=html).write_pdf(os.path.join(output_dir, "report.pdf"))
285
- except Exception as e:
286
- 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)