@yahyahammad/venastine 0.3.8 → 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 (128) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2030 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1034 -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 +528 -528
  14. package/bin/venastine.py +71 -71
  15. package/cli_commands.py +838 -835
  16. package/config.yaml +13 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +971 -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 +2715 -2715
  28. package/core/commands.py +460 -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 +234 -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 +458 -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 +108 -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 +733 -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 +295 -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 +267 -267
  102. package/tools/builtin/arxiv.py +681 -681
  103. package/tools/builtin/fetch_url.py +371 -371
  104. package/tools/builtin/file_ops.py +720 -720
  105. package/tools/builtin/geometry.py +184 -184
  106. package/tools/builtin/load_skill.py +76 -76
  107. package/tools/builtin/pin.py +227 -227
  108. package/tools/builtin/probability_stats.py +224 -224
  109. package/tools/builtin/project_docs.py +464 -464
  110. package/tools/builtin/remember.py +175 -175
  111. package/tools/builtin/shell.py +980 -980
  112. package/tools/builtin/todo.py +149 -149
  113. package/tools/builtin/web_search.py +328 -328
  114. package/tools/context.py +159 -159
  115. package/tools/isolation.py +387 -387
  116. package/tools/registry.py +1242 -1242
  117. package/tui/app.py +8318 -8307
  118. package/tui/app.tcss +747 -739
  119. package/tui/commands.py +26 -26
  120. package/tui/diffs.py +286 -286
  121. package/tui/history.py +128 -128
  122. package/tui/hosted_driver.py +102 -102
  123. package/tui/markdown.py +1329 -1329
  124. package/tui/meters.py +364 -364
  125. package/tui/ravens.py +146 -146
  126. package/tui/screens.py +1255 -1197
  127. package/tui/themes.py +599 -599
  128. package/tui/widgets.py +3813 -3796
@@ -1,219 +1,219 @@
1
- """
2
- core/reasoning/base.py
3
-
4
- Structured claim-level data model for the deep-research pipeline. This
5
- REPLACES the earlier free-text PipelineContext/PassResult design -- Pass 5
6
- (confidence tiering), gate D0 (claim-type routing), and D1/D2 (threshold and
7
- retry-cap checks) all need to reason about individual claims, not a
8
- concatenated paragraph of prior-pass prose. Passes that produce
9
- structured output (2, 3a, 3b, 4) mutate Claim objects in place; passes
10
- that produce free text (0, 1, 3c, final synthesis) populate the
11
- corresponding PipelineRun fields directly.
12
- """
13
-
14
- from __future__ import annotations
15
-
16
- from dataclasses import dataclass, field
17
- from typing import Literal, Optional, get_args
18
- from uuid import UUID
19
-
20
- ClaimType = Literal["factual", "synthesis", "speculative"]
21
- ConfidenceTier = Literal["HIGH", "MEDIUM", "LOW", "UNVERIFIED", "UNVERIFIED_COVERAGE"]
22
- GroundingStatus = Literal["grounded", "partial", "ungrounded"]
23
-
24
- # ROADMAP_v2 §30. The Literals above are ANNOTATIONS -- dataclasses do
25
- # not enforce them, and #75 is what that costs: `"Grounded"` scored a
26
- # well-sourced claim 0.35/LOW where `"grounded"` gives 0.85/HIGH, and
27
- # `"Ungrounded"` escaped the forced-UNVERIFIED rule to land LOW. Two
28
- # modules need the vocabulary as DATA -- the payload boundary rejects a
29
- # value outside it, the scorer coerces one that got through -- and a
30
- # second hand-typed copy of a vocabulary is a second thing to keep in
31
- # step. Derived from the Literal, beside the Literal.
32
- CLAIM_TYPES = frozenset(get_args(ClaimType))
33
- GROUNDING_STATUSES = frozenset(get_args(GroundingStatus))
34
-
35
-
36
- @dataclass
37
- class Claim:
38
- """One atomic, self-contained assertion extracted from Pass 1's raw
39
- response by Pass 2. Every later pass mutates fields on this same
40
- object rather than creating parallel data structures keyed by id.
41
-
42
- SERIALIZATION NOTE: EVERY `vars(c)` IN THE TREE serializes this object
43
- shallowly. That is correct only while every field below stays
44
- JSON-native (str / list / dict / float / int / None). If a
45
- nested-dataclass field is EVER added here, ALL of those sites must
46
- migrate to `dataclasses.asdict(c)` TOGETHER, not piecemeal -- hardening
47
- just one leaves the rest exposed and creates two different
48
- serialization mechanisms for the same object in the same codebase.
49
-
50
- grep -rn 'vars(c' --include='*.py' .
51
-
52
- Deliberately a GREP rather than a list. This note used to enumerate
53
- three sites -- orchestrator.py's passes, pipeline_storage and
54
- output_writer -- and §26 added two more in tui/app.py (show_claims and
55
- /copy claims) that fell out of it, and out of AGENTS.md's copy of the
56
- same list (audit #108). The TUI's failure would have been quieter than
57
- the persistence ones, since ClaimsScreen renders a repr into a cell and
58
- `json.dumps(..., default=str)` stringifies rather than raising -- which
59
- is precisely the "two different serialization mechanisms" outcome this
60
- note exists to prevent, arriving through the door the note did not
61
- cover. An enumeration that says ALL has to be complete to mean
62
- anything, and a new consumer in a new section will keep falling out of
63
- one.
64
- """
65
-
66
- id: str
67
- text: str
68
- type: ClaimType
69
- entities: list[str] = field(default_factory=list)
70
- source_span: str = ""
71
-
72
- # Populated by Pass 3a (factual claims only -- synthesis/speculative
73
- # claims skip grounding entirely per the pipeline's gate D0 routing, so
74
- # these stay at their defaults for those claims).
75
- grounding_sources: list[dict] = field(default_factory=list)
76
- grounding_status: Optional[GroundingStatus] = None
77
-
78
- # Populated by Pass 3b (factual claims only, same reason as above).
79
- fallacies: list[str] = field(default_factory=list)
80
- contradictions: list[str] = field(default_factory=list)
81
- critic_severity: float = 0.0
82
-
83
- # Populated by Pass 4 (ALL claims, factual or not).
84
- assumption_flags: list[str] = field(default_factory=list)
85
-
86
- # Populated by Pass 2 in ensemble mode (ROADMAP §10). Lists the
87
- # 1-indexed candidate numbers that independently asserted this claim.
88
- # Empty/unused when ensemble mode is off.
89
- asserted_by_candidates: list[int] = field(default_factory=list)
90
-
91
- # Populated by Pass 5 (pure code, no LLM call) -- see confidence_scoring.py.
92
- confidence_tier: Optional[ConfidenceTier] = None
93
- score_breakdown: dict = field(default_factory=dict)
94
-
95
- # Populated by the D1/6a/6b/D2/fallback retry loop.
96
- revision_text: Optional[str] = None
97
- retry_count: int = 0
98
-
99
- # Populated by 6c (annotate) / fallback -- the actual final text and
100
- # confidence tag a claim carries into the merged output.
101
- final_text: Optional[str] = None
102
- annotation: Optional[str] = None
103
-
104
-
105
- def resolve_by_id(claims: list) -> dict:
106
- """The pipeline's ONE claim-id resolution (ROADMAP_v2 §30, B6).
107
-
108
- There used to be two, and they disagreed. `_apply_grounding` and
109
- `_apply_critic` built `{c.id: c}` -- LAST wins -- while
110
- `_apply_assumption_flags` and `claim_by_id` used
111
- `next(c for c in claims if c.id == claim_id)` -- FIRST wins. With two
112
- claims sharing an id, driven against the real pipeline, that split one
113
- claim in half:
114
-
115
- text='first' grounding=None severity=0.0 flags=['a flag']
116
- text='second' grounding='grounded' severity=0.4 flags=[]
117
-
118
- The first copy is then ungrounded-but-factual, so D1 flags it, and
119
- Pass 6a revises the copy that has no sources while the grounded one
120
- keeps them.
121
-
122
- §30 also rejects a duplicate id at Pass 2's boundary, which stops that
123
- payload arriving. This exists anyway, because the boundary only covers
124
- claims that came through Pass 2 -- §20's corrections and any future
125
- resume build claims without passing this way, and a disagreement that
126
- can only be reached by a path nobody has written yet is still a
127
- disagreement waiting.
128
-
129
- FIRST wins, matching what claim_by_id and Pass 6a's in-batch lookup
130
- already did and documented. The choice is arbitrary once ids are
131
- unique; having one is not.
132
- """
133
- resolved = {}
134
- for claim in claims:
135
- resolved.setdefault(claim.id, claim)
136
- return resolved
137
-
138
-
139
- @dataclass
140
- class PipelineRun:
141
- """
142
- Holds every pass's structured output for one query. `trace` is a
143
- running human-readable audit log -- what was flagged, why, what
144
- changed -- meant to be at least as trustworthy an artifact as the
145
- final report itself.
146
- """
147
-
148
- user_query: str
149
- # Set by stream_deep_research_pipeline() once a PipelineRunRecord is
150
- # created in storage; stays None in tests that bypass persistence.
151
- # ROADMAP §5 (pipeline persistence minimal core): the record lets a
152
- # run that fails mid-pipeline be inspected and (future) resumed.
153
- run_id: Optional[UUID] = None
154
- plan: dict = field(default_factory=dict) # Pass 0
155
- raw_response: str = "" # Pass 1
156
- # E13/#77: one entry per SURVIVOR of ensemble Pass 1, in survivor
157
- # order -- {"candidate", "provider_name", "model", "chars", "text"}.
158
- # `text` is in-memory working data: pipeline_storage strips it when
159
- # persisting (the full texts live in the output directory's
160
- # 01_candidate_N.md files and in each candidate's own pass thread),
161
- # so the database carries metadata only. Empty for every run that
162
- # did not use ensemble mode -- raw_response alone is that run's
163
- # record, exactly as before this field existed.
164
- candidates: list[dict] = field(default_factory=list)
165
- claims: list[Claim] = field(default_factory=list) # Pass 2, mutated by 3a/3b/4/5/6a/6b/6c
166
- completeness: dict = field(default_factory=dict) # Pass 3c: {"gaps": [...], "coverage_score": ...}
167
- coverage_gaps: list[dict] = field(default_factory=list) # Pass 5-derived: gaps tagged UNVERIFIED_COVERAGE
168
- assumptions: dict = field(default_factory=dict) # Pass 4
169
- trace: list[str] = field(default_factory=list)
170
- # §25: tool calls that ran on a PRE-FLIGHT grant rather than a live
171
- # approval, one dict per call ({"pass", "tool", "params"}). Empty for
172
- # every run that granted nothing, which is every run by default.
173
- #
174
- # Authorization moved up-front, so accountability moves after: an
175
- # unattended ten-pass run is precisely where "the user said yes once"
176
- # needs a record of what that yes actually covered.
177
- granted_calls: list[dict] = field(default_factory=list)
178
- # §20: one record per finding the reviewer raised, carrying what it
179
- # proposed and what the human decided. Populated only on a run that
180
- # was reviewed, which is off by default (D9).
181
- #
182
- # A dict, not a dataclass, and deliberately: a nested dataclass field
183
- # here would require migrating EVERY vars(c)/vars(run) site to
184
- # asdict() in one change (see the Claim note above). It is also why
185
- # the reviewer's tier overrides are marked inside the existing
186
- # score_breakdown dict rather than in a new Claim field.
187
- subagent_reviews: list[dict] = field(default_factory=list)
188
- # §27 (T2): one entry per pass thread, {"pass": pass_id,
189
- # "thread_id": str}. Each pass runs in its own fresh thread -- a locked
190
- # invariant, since passes share distilled JSON and never raw history --
191
- # so §27 hides those threads from the picker. This is what keeps them
192
- # REACHABLE anyway: hiding a thread must not orphan it.
193
- #
194
- # A list[dict] for the same reason granted_calls and subagent_reviews
195
- # are: a nested dataclass here forces every vars(run)/vars(c) site to
196
- # asdict() in one change.
197
- pass_threads: list[dict] = field(default_factory=list)
198
- # §45 (SQ2/SQ8): one entry per URL this run actually retrieved text
199
- # from -- {"url", "title", "tool", "retrieved_at", "sha256", "chars",
200
- # "text"}. Populated from the live SourceCorpus once grounding has
201
- # finished; the corpus object itself stays inside the pipeline
202
- # generator.
203
- #
204
- # A list[dict] for the same reason granted_calls, subagent_reviews and
205
- # pass_threads are, and here the reason is sharper: the corpus IS a
206
- # dataclass, and putting it on this object directly is exactly the
207
- # nested-dataclass field the note on Claim above forbids.
208
- #
209
- # In-memory working data, like candidates[].text: pipeline_storage
210
- # names the fields it writes and this is not among them, so a run's
211
- # fetched pages reach output/<run_id>/sources/ and never the database.
212
- source_documents: list[dict] = field(default_factory=list)
213
- final_report: str = ""
214
-
215
- def log(self, message: str) -> None:
216
- self.trace.append(message)
217
-
218
- def claim_by_id(self, claim_id: str) -> Optional[Claim]:
219
- return resolve_by_id(self.claims).get(claim_id)
1
+ """
2
+ core/reasoning/base.py
3
+
4
+ Structured claim-level data model for the deep-research pipeline. This
5
+ REPLACES the earlier free-text PipelineContext/PassResult design -- Pass 5
6
+ (confidence tiering), gate D0 (claim-type routing), and D1/D2 (threshold and
7
+ retry-cap checks) all need to reason about individual claims, not a
8
+ concatenated paragraph of prior-pass prose. Passes that produce
9
+ structured output (2, 3a, 3b, 4) mutate Claim objects in place; passes
10
+ that produce free text (0, 1, 3c, final synthesis) populate the
11
+ corresponding PipelineRun fields directly.
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ from dataclasses import dataclass, field
17
+ from typing import Literal, Optional, get_args
18
+ from uuid import UUID
19
+
20
+ ClaimType = Literal["factual", "synthesis", "speculative"]
21
+ ConfidenceTier = Literal["HIGH", "MEDIUM", "LOW", "UNVERIFIED", "UNVERIFIED_COVERAGE"]
22
+ GroundingStatus = Literal["grounded", "partial", "ungrounded"]
23
+
24
+ # ROADMAP_v2 §30. The Literals above are ANNOTATIONS -- dataclasses do
25
+ # not enforce them, and #75 is what that costs: `"Grounded"` scored a
26
+ # well-sourced claim 0.35/LOW where `"grounded"` gives 0.85/HIGH, and
27
+ # `"Ungrounded"` escaped the forced-UNVERIFIED rule to land LOW. Two
28
+ # modules need the vocabulary as DATA -- the payload boundary rejects a
29
+ # value outside it, the scorer coerces one that got through -- and a
30
+ # second hand-typed copy of a vocabulary is a second thing to keep in
31
+ # step. Derived from the Literal, beside the Literal.
32
+ CLAIM_TYPES = frozenset(get_args(ClaimType))
33
+ GROUNDING_STATUSES = frozenset(get_args(GroundingStatus))
34
+
35
+
36
+ @dataclass
37
+ class Claim:
38
+ """One atomic, self-contained assertion extracted from Pass 1's raw
39
+ response by Pass 2. Every later pass mutates fields on this same
40
+ object rather than creating parallel data structures keyed by id.
41
+
42
+ SERIALIZATION NOTE: EVERY `vars(c)` IN THE TREE serializes this object
43
+ shallowly. That is correct only while every field below stays
44
+ JSON-native (str / list / dict / float / int / None). If a
45
+ nested-dataclass field is EVER added here, ALL of those sites must
46
+ migrate to `dataclasses.asdict(c)` TOGETHER, not piecemeal -- hardening
47
+ just one leaves the rest exposed and creates two different
48
+ serialization mechanisms for the same object in the same codebase.
49
+
50
+ grep -rn 'vars(c' --include='*.py' .
51
+
52
+ Deliberately a GREP rather than a list. This note used to enumerate
53
+ three sites -- orchestrator.py's passes, pipeline_storage and
54
+ output_writer -- and §26 added two more in tui/app.py (show_claims and
55
+ /copy claims) that fell out of it, and out of AGENTS.md's copy of the
56
+ same list (audit #108). The TUI's failure would have been quieter than
57
+ the persistence ones, since ClaimsScreen renders a repr into a cell and
58
+ `json.dumps(..., default=str)` stringifies rather than raising -- which
59
+ is precisely the "two different serialization mechanisms" outcome this
60
+ note exists to prevent, arriving through the door the note did not
61
+ cover. An enumeration that says ALL has to be complete to mean
62
+ anything, and a new consumer in a new section will keep falling out of
63
+ one.
64
+ """
65
+
66
+ id: str
67
+ text: str
68
+ type: ClaimType
69
+ entities: list[str] = field(default_factory=list)
70
+ source_span: str = ""
71
+
72
+ # Populated by Pass 3a (factual claims only -- synthesis/speculative
73
+ # claims skip grounding entirely per the pipeline's gate D0 routing, so
74
+ # these stay at their defaults for those claims).
75
+ grounding_sources: list[dict] = field(default_factory=list)
76
+ grounding_status: Optional[GroundingStatus] = None
77
+
78
+ # Populated by Pass 3b (factual claims only, same reason as above).
79
+ fallacies: list[str] = field(default_factory=list)
80
+ contradictions: list[str] = field(default_factory=list)
81
+ critic_severity: float = 0.0
82
+
83
+ # Populated by Pass 4 (ALL claims, factual or not).
84
+ assumption_flags: list[str] = field(default_factory=list)
85
+
86
+ # Populated by Pass 2 in ensemble mode (ROADMAP §10). Lists the
87
+ # 1-indexed candidate numbers that independently asserted this claim.
88
+ # Empty/unused when ensemble mode is off.
89
+ asserted_by_candidates: list[int] = field(default_factory=list)
90
+
91
+ # Populated by Pass 5 (pure code, no LLM call) -- see confidence_scoring.py.
92
+ confidence_tier: Optional[ConfidenceTier] = None
93
+ score_breakdown: dict = field(default_factory=dict)
94
+
95
+ # Populated by the D1/6a/6b/D2/fallback retry loop.
96
+ revision_text: Optional[str] = None
97
+ retry_count: int = 0
98
+
99
+ # Populated by 6c (annotate) / fallback -- the actual final text and
100
+ # confidence tag a claim carries into the merged output.
101
+ final_text: Optional[str] = None
102
+ annotation: Optional[str] = None
103
+
104
+
105
+ def resolve_by_id(claims: list) -> dict:
106
+ """The pipeline's ONE claim-id resolution (ROADMAP_v2 §30, B6).
107
+
108
+ There used to be two, and they disagreed. `_apply_grounding` and
109
+ `_apply_critic` built `{c.id: c}` -- LAST wins -- while
110
+ `_apply_assumption_flags` and `claim_by_id` used
111
+ `next(c for c in claims if c.id == claim_id)` -- FIRST wins. With two
112
+ claims sharing an id, driven against the real pipeline, that split one
113
+ claim in half:
114
+
115
+ text='first' grounding=None severity=0.0 flags=['a flag']
116
+ text='second' grounding='grounded' severity=0.4 flags=[]
117
+
118
+ The first copy is then ungrounded-but-factual, so D1 flags it, and
119
+ Pass 6a revises the copy that has no sources while the grounded one
120
+ keeps them.
121
+
122
+ §30 also rejects a duplicate id at Pass 2's boundary, which stops that
123
+ payload arriving. This exists anyway, because the boundary only covers
124
+ claims that came through Pass 2 -- §20's corrections and any future
125
+ resume build claims without passing this way, and a disagreement that
126
+ can only be reached by a path nobody has written yet is still a
127
+ disagreement waiting.
128
+
129
+ FIRST wins, matching what claim_by_id and Pass 6a's in-batch lookup
130
+ already did and documented. The choice is arbitrary once ids are
131
+ unique; having one is not.
132
+ """
133
+ resolved = {}
134
+ for claim in claims:
135
+ resolved.setdefault(claim.id, claim)
136
+ return resolved
137
+
138
+
139
+ @dataclass
140
+ class PipelineRun:
141
+ """
142
+ Holds every pass's structured output for one query. `trace` is a
143
+ running human-readable audit log -- what was flagged, why, what
144
+ changed -- meant to be at least as trustworthy an artifact as the
145
+ final report itself.
146
+ """
147
+
148
+ user_query: str
149
+ # Set by stream_deep_research_pipeline() once a PipelineRunRecord is
150
+ # created in storage; stays None in tests that bypass persistence.
151
+ # ROADMAP §5 (pipeline persistence minimal core): the record lets a
152
+ # run that fails mid-pipeline be inspected and (future) resumed.
153
+ run_id: Optional[UUID] = None
154
+ plan: dict = field(default_factory=dict) # Pass 0
155
+ raw_response: str = "" # Pass 1
156
+ # E13/#77: one entry per SURVIVOR of ensemble Pass 1, in survivor
157
+ # order -- {"candidate", "provider_name", "model", "chars", "text"}.
158
+ # `text` is in-memory working data: pipeline_storage strips it when
159
+ # persisting (the full texts live in the output directory's
160
+ # 01_candidate_N.md files and in each candidate's own pass thread),
161
+ # so the database carries metadata only. Empty for every run that
162
+ # did not use ensemble mode -- raw_response alone is that run's
163
+ # record, exactly as before this field existed.
164
+ candidates: list[dict] = field(default_factory=list)
165
+ claims: list[Claim] = field(default_factory=list) # Pass 2, mutated by 3a/3b/4/5/6a/6b/6c
166
+ completeness: dict = field(default_factory=dict) # Pass 3c: {"gaps": [...], "coverage_score": ...}
167
+ coverage_gaps: list[dict] = field(default_factory=list) # Pass 5-derived: gaps tagged UNVERIFIED_COVERAGE
168
+ assumptions: dict = field(default_factory=dict) # Pass 4
169
+ trace: list[str] = field(default_factory=list)
170
+ # §25: tool calls that ran on a PRE-FLIGHT grant rather than a live
171
+ # approval, one dict per call ({"pass", "tool", "params"}). Empty for
172
+ # every run that granted nothing, which is every run by default.
173
+ #
174
+ # Authorization moved up-front, so accountability moves after: an
175
+ # unattended ten-pass run is precisely where "the user said yes once"
176
+ # needs a record of what that yes actually covered.
177
+ granted_calls: list[dict] = field(default_factory=list)
178
+ # §20: one record per finding the reviewer raised, carrying what it
179
+ # proposed and what the human decided. Populated only on a run that
180
+ # was reviewed, which is off by default (D9).
181
+ #
182
+ # A dict, not a dataclass, and deliberately: a nested dataclass field
183
+ # here would require migrating EVERY vars(c)/vars(run) site to
184
+ # asdict() in one change (see the Claim note above). It is also why
185
+ # the reviewer's tier overrides are marked inside the existing
186
+ # score_breakdown dict rather than in a new Claim field.
187
+ subagent_reviews: list[dict] = field(default_factory=list)
188
+ # §27 (T2): one entry per pass thread, {"pass": pass_id,
189
+ # "thread_id": str}. Each pass runs in its own fresh thread -- a locked
190
+ # invariant, since passes share distilled JSON and never raw history --
191
+ # so §27 hides those threads from the picker. This is what keeps them
192
+ # REACHABLE anyway: hiding a thread must not orphan it.
193
+ #
194
+ # A list[dict] for the same reason granted_calls and subagent_reviews
195
+ # are: a nested dataclass here forces every vars(run)/vars(c) site to
196
+ # asdict() in one change.
197
+ pass_threads: list[dict] = field(default_factory=list)
198
+ # §45 (SQ2/SQ8): one entry per URL this run actually retrieved text
199
+ # from -- {"url", "title", "tool", "retrieved_at", "sha256", "chars",
200
+ # "text"}. Populated from the live SourceCorpus once grounding has
201
+ # finished; the corpus object itself stays inside the pipeline
202
+ # generator.
203
+ #
204
+ # A list[dict] for the same reason granted_calls, subagent_reviews and
205
+ # pass_threads are, and here the reason is sharper: the corpus IS a
206
+ # dataclass, and putting it on this object directly is exactly the
207
+ # nested-dataclass field the note on Claim above forbids.
208
+ #
209
+ # In-memory working data, like candidates[].text: pipeline_storage
210
+ # names the fields it writes and this is not among them, so a run's
211
+ # fetched pages reach output/<run_id>/sources/ and never the database.
212
+ source_documents: list[dict] = field(default_factory=list)
213
+ final_report: str = ""
214
+
215
+ def log(self, message: str) -> None:
216
+ self.trace.append(message)
217
+
218
+ def claim_by_id(self, claim_id: str) -> Optional[Claim]:
219
+ return resolve_by_id(self.claims).get(claim_id)