@yahyahammad/venastine 0.3.17 → 0.3.19
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.
- package/README.md +27 -4
- package/core/commands.py +3 -2
- package/core/loop.py +66 -10
- package/core/reasoning/events.py +6 -0
- package/core/reasoning/json_retry.py +12 -1
- package/core/reasoning/orchestrator.py +562 -270
- package/core/reasoning/pipeline_storage.py +86 -5
- package/core/reasoning/resume.py +557 -0
- package/core/reasoning/source_corpus.py +25 -10
- package/main.py +108 -6
- package/package.json +1 -1
- package/pyproject.toml +1 -1
- package/safety/policy_enforcement.py +55 -14
- package/storage.py +13 -0
- package/tui/app.py +114 -8
- package/tui/app.tcss +5 -1
- package/tui/screens.py +61 -0
|
@@ -0,0 +1,557 @@
|
|
|
1
|
+
"""
|
|
2
|
+
core/reasoning/resume.py
|
|
3
|
+
|
|
4
|
+
ROADMAP_v3 §98: picking a failed or abandoned research run up where it
|
|
5
|
+
stopped, instead of starting it again.
|
|
6
|
+
|
|
7
|
+
THE PROBLEM IT EXISTS FOR. A real run spent 4h53m on Pass 0 to Pass 3a and
|
|
8
|
+
then failed, because Pass 3a's last answer was a complete JSON array
|
|
9
|
+
followed by a stray closing code fence. Every pass before it had finished
|
|
10
|
+
and was recorded, and Pass 3a's own thread held 79 rows of research. The
|
|
11
|
+
only way on was `/research` again, from Pass 0.
|
|
12
|
+
|
|
13
|
+
WHAT A RESUME KEEPS (RS1-RS6):
|
|
14
|
+
|
|
15
|
+
* Every stage the run COMPLETED is not run again. The orchestrator
|
|
16
|
+
writes a resume point at the end of each stage (`snapshot` below,
|
|
17
|
+
stored by pipeline_storage.save_resume_point), holding the claims and
|
|
18
|
+
the small pass outputs as they stood at that boundary.
|
|
19
|
+
* The pass that FAILED keeps its thread. Its last stored answer is
|
|
20
|
+
checked again first, with no model call: the answer the run died on
|
|
21
|
+
may be acceptable now (RS7 made the parser take the stray fence), and
|
|
22
|
+
a JSON pass's corrective retries continue from it otherwise. A thread
|
|
23
|
+
whose last row is not an answer was cut off mid-request, so the loop
|
|
24
|
+
resends that request (RS4). Only a thread that cannot be read back
|
|
25
|
+
makes the pass start again from its beginning.
|
|
26
|
+
* The pages the run fetched are replayed from the stored tool results
|
|
27
|
+
into the run's source corpus (RS6), so sources are scored as an
|
|
28
|
+
uninterrupted run would score them.
|
|
29
|
+
|
|
30
|
+
A run recorded before §98 has no resume point. Its stage is read from the
|
|
31
|
+
trace's checkpoint lines instead (RS9), up to the 6a/6b loop: a loop round
|
|
32
|
+
changes claims a trace line does not describe, so a run that stopped inside
|
|
33
|
+
one is refused with that reason. Ensemble runs from before §98 are refused
|
|
34
|
+
too, because their records never said which thread held which candidate.
|
|
35
|
+
|
|
36
|
+
This module decides WHERE a run resumes and rebuilds what it had. The
|
|
37
|
+
orchestrator still runs every pass; nothing here calls a model.
|
|
38
|
+
"""
|
|
39
|
+
|
|
40
|
+
from __future__ import annotations
|
|
41
|
+
|
|
42
|
+
import ast
|
|
43
|
+
import logging
|
|
44
|
+
from dataclasses import dataclass, field, fields
|
|
45
|
+
from datetime import UTC, datetime
|
|
46
|
+
from typing import Optional
|
|
47
|
+
from uuid import UUID
|
|
48
|
+
|
|
49
|
+
from core.reasoning.base import Claim, PipelineRun
|
|
50
|
+
from core.reasoning.json_retry import parse_json_response
|
|
51
|
+
from core.reasoning.pipeline_storage import (
|
|
52
|
+
RESUMABLE_STATUSES,
|
|
53
|
+
list_resumable_runs,
|
|
54
|
+
load_pipeline_run,
|
|
55
|
+
)
|
|
56
|
+
from core.reasoning.source_corpus import READ_TOOLS
|
|
57
|
+
|
|
58
|
+
logger = logging.getLogger(__name__)
|
|
59
|
+
|
|
60
|
+
#: The resume point's shape. A point with another version is refused rather
|
|
61
|
+
#: than half read, because a field that moved would resume from wrong state.
|
|
62
|
+
RESUME_VERSION = 1
|
|
63
|
+
|
|
64
|
+
#: The stages before and after the 6a/6b loop, in the order the pipeline
|
|
65
|
+
#: runs them. Gate D0, Pass 5, gate D1, Pass 6c and Merge make no model call,
|
|
66
|
+
#: and they are stages here because a resume must not run them twice.
|
|
67
|
+
STAGES_BEFORE_LOOP = ("Pass 0", "Pass 1", "Pass 2", "D0", "Pass 3a",
|
|
68
|
+
"Pass 3b", "Pass 3c", "Pass 4", "Pass 5", "D1")
|
|
69
|
+
LOOP_STAGES = ("Pass 6a", "Pass 6b")
|
|
70
|
+
STAGES_AFTER_LOOP = ("Pass 6c", "Merge", "Final synthesis")
|
|
71
|
+
|
|
72
|
+
#: The passes that make model calls and so own a thread a resume can continue.
|
|
73
|
+
LLM_PASSES = frozenset({"Pass 0", "Pass 1", "Pass 2", "Pass 3a", "Pass 3b",
|
|
74
|
+
"Pass 3c", "Pass 4", "Pass 6a", "Pass 6b",
|
|
75
|
+
"Final synthesis"})
|
|
76
|
+
|
|
77
|
+
#: RS9. The checkpoint line each stage ends on, as the orchestrator writes it,
|
|
78
|
+
#: for a run recorded before resume points existed. The LAST line in the
|
|
79
|
+
#: trace that matches one is the last stage that run completed. Gate D1 maps to
|
|
80
|
+
#: Pass 5 on purpose: it is pure code, and running it again recomputes the
|
|
81
|
+
#: batch the first 6a round was given rather than this module copying its
|
|
82
|
+
#: rule. `None` marks a loop line: such a run is refused.
|
|
83
|
+
LEGACY_STAGE_LINES = (
|
|
84
|
+
("Pass 0: plan produced", "Pass 0"),
|
|
85
|
+
("Pass 1: initial generation complete.", "Pass 1"),
|
|
86
|
+
("Pass 1: ensemble mode", "Pass 1"),
|
|
87
|
+
("Pass 1: only one ensemble candidate survived", "Pass 1"),
|
|
88
|
+
("Pass 2: extracted ", "Pass 2"),
|
|
89
|
+
("D0: ", "D0"),
|
|
90
|
+
("Pass 3a: grounded ", "Pass 3a"),
|
|
91
|
+
("Pass 3b: critique applied", "Pass 3b"),
|
|
92
|
+
("Pass 3a/3b: skipped", "Pass 3b"),
|
|
93
|
+
("Pass 3c: coverage_score=", "Pass 3c"),
|
|
94
|
+
("Pass 4: assumption audit complete", "Pass 4"),
|
|
95
|
+
("Pass 5: confidence tiers assigned", "Pass 5"),
|
|
96
|
+
("D1: ", "Pass 5"),
|
|
97
|
+
("Pass 6a: revised ", None),
|
|
98
|
+
("Pass 6b: ", None),
|
|
99
|
+
("D2: claim ", None),
|
|
100
|
+
("Pass 6c: annotation complete", "Pass 6c"),
|
|
101
|
+
("Merge: final claim set assembled", "Merge"),
|
|
102
|
+
("Final synthesis complete.", "Final synthesis"),
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
#: Every field a Claim has, so a stored claim is rebuilt whole. Pass 2's
|
|
106
|
+
#: _claim_from_json takes only the INPUT fields; a resumed claim carries its
|
|
107
|
+
#: grounding, critique, flags and tier too.
|
|
108
|
+
_CLAIM_FIELDS = frozenset(f.name for f in fields(Claim))
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
class ResumeRefused(Exception):
|
|
112
|
+
"""A run that cannot be resumed, with the reason a person can act on.
|
|
113
|
+
Raised before anything about the run changes."""
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def position(stage: Optional[str], round_no: int = 0) -> tuple:
|
|
117
|
+
"""Where `stage` sits in the run, as something that orders. A loop stage
|
|
118
|
+
needs its round: 6a of round 2 comes after 6b of round 1. `None` is
|
|
119
|
+
before Pass 0."""
|
|
120
|
+
if stage is None:
|
|
121
|
+
return (-1, 0, 0)
|
|
122
|
+
if stage in STAGES_BEFORE_LOOP:
|
|
123
|
+
return (STAGES_BEFORE_LOOP.index(stage), 0, 0)
|
|
124
|
+
if stage in LOOP_STAGES:
|
|
125
|
+
return (len(STAGES_BEFORE_LOOP), round_no, LOOP_STAGES.index(stage))
|
|
126
|
+
return (len(STAGES_BEFORE_LOOP) + 1 + STAGES_AFTER_LOOP.index(stage), 0, 0)
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def describe_stage(stage: Optional[str], round_no: int = 0) -> str:
|
|
130
|
+
"""The stage a run completed, as a person reads it."""
|
|
131
|
+
if stage is None:
|
|
132
|
+
return "before Pass 0"
|
|
133
|
+
if stage in LOOP_STAGES:
|
|
134
|
+
return f"after {stage} of round {round_no}"
|
|
135
|
+
return f"after {stage}"
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
@dataclass
|
|
139
|
+
class ResumePoint:
|
|
140
|
+
"""A run rebuilt as far as it got, and what is left to do.
|
|
141
|
+
|
|
142
|
+
`stage` and `round` are the last stage it COMPLETED. `flagged` is the
|
|
143
|
+
6a/6b batch the next loop step works on (after gate D1 or a round).
|
|
144
|
+
`pending` is the pass thread a failed pass left, handed to that pass
|
|
145
|
+
once by `take_thread`. `pass1_threads` names the thread holding Pass 1's
|
|
146
|
+
text, one per ensemble candidate, and is carried into every later
|
|
147
|
+
resume point so a second resume can read it too."""
|
|
148
|
+
|
|
149
|
+
run: PipelineRun
|
|
150
|
+
stage: Optional[str] = None
|
|
151
|
+
round: int = 0
|
|
152
|
+
flagged: list = field(default_factory=list)
|
|
153
|
+
effective_n: int = 0
|
|
154
|
+
pending: Optional[dict] = None
|
|
155
|
+
pass1_threads: list = field(default_factory=list)
|
|
156
|
+
legacy: bool = False
|
|
157
|
+
trace_length: int = 0
|
|
158
|
+
notes: list = field(default_factory=list)
|
|
159
|
+
|
|
160
|
+
def done(self, stage: str, round_no: int = 0) -> bool:
|
|
161
|
+
"""Whether `stage` (of `round_no`, for a loop stage) completed
|
|
162
|
+
before the run stopped."""
|
|
163
|
+
return position(stage, round_no) <= position(self.stage, self.round)
|
|
164
|
+
|
|
165
|
+
def take_thread(self, pass_id: str) -> Optional[UUID]:
|
|
166
|
+
"""The failed pass's thread, for that pass only and only once. A
|
|
167
|
+
later pass, or the same pass id in a later round, starts fresh."""
|
|
168
|
+
if self.pending is None or self.pending.get("pass") != pass_id:
|
|
169
|
+
return None
|
|
170
|
+
thread_id, self.pending = self.pending.get("thread_id"), None
|
|
171
|
+
return _as_uuid(thread_id)
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def snapshot(run: PipelineRun, stage: str, *, round_no: int = 0,
|
|
175
|
+
flagged=(), effective_n: int = 0, pass1_threads=()) -> dict:
|
|
176
|
+
"""The resume point the orchestrator saves at the end of `stage`
|
|
177
|
+
(RS2). Everything a later stage reads that is not already in a
|
|
178
|
+
column, plus the claims themselves: claims_json is also written on the
|
|
179
|
+
failure path, so it can hold a stage's work half applied, and this copy
|
|
180
|
+
is the one that describes a boundary."""
|
|
181
|
+
return {
|
|
182
|
+
"version": RESUME_VERSION,
|
|
183
|
+
"stage": stage,
|
|
184
|
+
"round": round_no,
|
|
185
|
+
"flagged": [c.id for c in flagged],
|
|
186
|
+
"effective_n": effective_n,
|
|
187
|
+
"plan": run.plan,
|
|
188
|
+
"completeness": run.completeness,
|
|
189
|
+
"assumptions": run.assumptions,
|
|
190
|
+
"claims": [vars(c) for c in run.claims],
|
|
191
|
+
"coverage_gaps": run.coverage_gaps,
|
|
192
|
+
"granted_calls": list(run.granted_calls),
|
|
193
|
+
"threads": len(run.pass_threads),
|
|
194
|
+
"pass1_threads": [t for t in pass1_threads],
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
# ---------------------------------------------------------------------------
|
|
199
|
+
# ---- Reading a pass thread back ---------------------------------------------
|
|
200
|
+
# ---------------------------------------------------------------------------
|
|
201
|
+
|
|
202
|
+
def _as_uuid(value) -> Optional[UUID]:
|
|
203
|
+
if isinstance(value, UUID):
|
|
204
|
+
return value
|
|
205
|
+
try:
|
|
206
|
+
return UUID(str(value))
|
|
207
|
+
except (ValueError, TypeError, AttributeError):
|
|
208
|
+
return None
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def _rows(thread_id) -> list:
|
|
212
|
+
"""A thread's whole archive, or [] when it cannot be read. Through the
|
|
213
|
+
module attribute, so the suite's fake storage answers it."""
|
|
214
|
+
import storage
|
|
215
|
+
uid = _as_uuid(thread_id)
|
|
216
|
+
if uid is None:
|
|
217
|
+
return []
|
|
218
|
+
try:
|
|
219
|
+
return storage.archive_history(uid)
|
|
220
|
+
except Exception: # noqa: BLE001 -- an unreadable thread is "missing"
|
|
221
|
+
logger.warning("Could not read pass thread %s back.", thread_id,
|
|
222
|
+
exc_info=True)
|
|
223
|
+
return []
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def thread_tail(thread_id) -> tuple:
|
|
227
|
+
"""What the failed pass left in its thread (RS4):
|
|
228
|
+
|
|
229
|
+
("answer", text) its last row is an answer -- an assistant turn
|
|
230
|
+
that asked for no tool. The pass returned it, and
|
|
231
|
+
it may be checked again with no model call.
|
|
232
|
+
("pending", None) its last row is anything else: a request, a tool
|
|
233
|
+
result, a call left unanswered. The run stopped
|
|
234
|
+
before the model replied, so the loop resends.
|
|
235
|
+
("missing", None) nothing could be read back. The pass starts again.
|
|
236
|
+
"""
|
|
237
|
+
rows = _rows(thread_id)
|
|
238
|
+
if not rows:
|
|
239
|
+
return ("missing", None)
|
|
240
|
+
last = rows[-1]
|
|
241
|
+
if last.get("role") == "assistant" and not last.get("tool_calls"):
|
|
242
|
+
return ("answer", last.get("text") or "")
|
|
243
|
+
return ("pending", None)
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def last_answer(thread_id) -> Optional[str]:
|
|
247
|
+
"""The text of a completed pass, read back from its thread: its last
|
|
248
|
+
assistant turn, which is the response the pass returned."""
|
|
249
|
+
for row in reversed(_rows(thread_id)):
|
|
250
|
+
if row.get("role") == "assistant":
|
|
251
|
+
return row.get("text") or ""
|
|
252
|
+
return None
|
|
253
|
+
|
|
254
|
+
|
|
255
|
+
# ---------------------------------------------------------------------------
|
|
256
|
+
# ---- The corpus (RS6) ---------------------------------------------------------
|
|
257
|
+
# ---------------------------------------------------------------------------
|
|
258
|
+
|
|
259
|
+
def _stamp(when) -> Optional[str]:
|
|
260
|
+
"""A stored row time in the corpus's own spelling. SQLite hands back a
|
|
261
|
+
naive datetime that was written as UTC."""
|
|
262
|
+
if not isinstance(when, datetime):
|
|
263
|
+
return None
|
|
264
|
+
if when.tzinfo is None:
|
|
265
|
+
when = when.replace(tzinfo=UTC)
|
|
266
|
+
return when.isoformat(timespec="seconds")
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
def rebuild_corpus(corpus, pass_threads) -> tuple:
|
|
270
|
+
"""Replay every stored result of the corpus's own tools, from every
|
|
271
|
+
thread the run recorded, oldest thread first. Returns (added, skipped).
|
|
272
|
+
|
|
273
|
+
The stored row is `str(result)` of the very dict the live run handed the
|
|
274
|
+
corpus (core/memory.add_tool_result), so `ast.literal_eval` gives it
|
|
275
|
+
back. It parses LITERALS only and runs nothing. A row it cannot parse
|
|
276
|
+
is skipped and counted, and the trace says how many.
|
|
277
|
+
"""
|
|
278
|
+
import storage
|
|
279
|
+
added = skipped = 0
|
|
280
|
+
seen = set()
|
|
281
|
+
for entry in pass_threads or ():
|
|
282
|
+
uid = _as_uuid(entry.get("thread_id") if isinstance(entry, dict) else None)
|
|
283
|
+
if uid is None or uid in seen:
|
|
284
|
+
continue
|
|
285
|
+
seen.add(uid)
|
|
286
|
+
rows = _rows(uid)
|
|
287
|
+
try:
|
|
288
|
+
times = storage.tool_result_times(uid)
|
|
289
|
+
except Exception: # noqa: BLE001 -- a time is provenance, not content
|
|
290
|
+
times = {}
|
|
291
|
+
names = {}
|
|
292
|
+
for row in rows:
|
|
293
|
+
if row.get("role") == "assistant":
|
|
294
|
+
for call in row.get("tool_calls") or ():
|
|
295
|
+
names[call.get("id")] = call.get("name")
|
|
296
|
+
continue
|
|
297
|
+
if row.get("role") != "tool":
|
|
298
|
+
continue
|
|
299
|
+
name = names.get(row.get("tool_call_id"))
|
|
300
|
+
if name not in READ_TOOLS:
|
|
301
|
+
continue
|
|
302
|
+
try:
|
|
303
|
+
result = ast.literal_eval(row.get("content") or "")
|
|
304
|
+
except (ValueError, SyntaxError, TypeError, MemoryError,
|
|
305
|
+
RecursionError):
|
|
306
|
+
skipped += 1
|
|
307
|
+
continue
|
|
308
|
+
added += corpus.add(name, result,
|
|
309
|
+
retrieved_at=_stamp(times.get(row.get("tool_call_id"))))
|
|
310
|
+
return added, skipped
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
# ---------------------------------------------------------------------------
|
|
314
|
+
# ---- Where a run resumes -------------------------------------------------------
|
|
315
|
+
# ---------------------------------------------------------------------------
|
|
316
|
+
|
|
317
|
+
def legacy_stage(trace) -> tuple:
|
|
318
|
+
"""RS9: (stage, refusal) for a run with no resume point. `stage` is the
|
|
319
|
+
last stage whose checkpoint line the trace holds, None before Pass 0.
|
|
320
|
+
`refusal` is a reason when that line is inside the 6a/6b loop."""
|
|
321
|
+
stage = None
|
|
322
|
+
for line in trace or ():
|
|
323
|
+
if not isinstance(line, str):
|
|
324
|
+
continue
|
|
325
|
+
for prefix, mapped in LEGACY_STAGE_LINES:
|
|
326
|
+
if line.startswith(prefix):
|
|
327
|
+
if mapped is None:
|
|
328
|
+
return None, (
|
|
329
|
+
"it stopped inside the 6a/6b revision loop, and it "
|
|
330
|
+
"was recorded before resume points existed, so its "
|
|
331
|
+
"trace cannot say what that round had changed")
|
|
332
|
+
stage = mapped
|
|
333
|
+
break
|
|
334
|
+
return stage, None
|
|
335
|
+
|
|
336
|
+
|
|
337
|
+
def _claims_from(dicts) -> list:
|
|
338
|
+
return [Claim(**{k: v for k, v in d.items() if k in _CLAIM_FIELDS})
|
|
339
|
+
for d in dicts or () if isinstance(d, dict)]
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
def _answer_payload(thread_id, what: str):
|
|
343
|
+
"""A completed JSON pass's payload, parsed from its thread."""
|
|
344
|
+
text = last_answer(thread_id) if thread_id else None
|
|
345
|
+
if text is None:
|
|
346
|
+
raise ResumeRefused(f"{what}'s thread could not be read back")
|
|
347
|
+
try:
|
|
348
|
+
return parse_json_response(text)
|
|
349
|
+
except ValueError as e:
|
|
350
|
+
raise ResumeRefused(f"{what}'s stored answer does not parse "
|
|
351
|
+
f"({str(e).splitlines()[0]})") from e
|
|
352
|
+
|
|
353
|
+
|
|
354
|
+
def _last_thread_of(pass_threads, pass_id: str) -> Optional[str]:
|
|
355
|
+
return next((e.get("thread_id") for e in reversed(pass_threads or ())
|
|
356
|
+
if isinstance(e, dict) and e.get("pass") == pass_id), None)
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
def _from_point(record: dict, point: dict) -> ResumePoint:
|
|
360
|
+
if point.get("version") != RESUME_VERSION:
|
|
361
|
+
raise ResumeRefused(
|
|
362
|
+
f"its resume point has version {point.get('version')!r}, and this "
|
|
363
|
+
f"build reads version {RESUME_VERSION}")
|
|
364
|
+
stage = point.get("stage")
|
|
365
|
+
if stage is not None and stage not in (
|
|
366
|
+
STAGES_BEFORE_LOOP + LOOP_STAGES + STAGES_AFTER_LOOP):
|
|
367
|
+
raise ResumeRefused(f"its resume point names an unknown stage {stage!r}")
|
|
368
|
+
run = _run_from(record)
|
|
369
|
+
run.claims = _claims_from(point.get("claims"))
|
|
370
|
+
run.plan = point.get("plan") or {}
|
|
371
|
+
run.completeness = point.get("completeness") or {}
|
|
372
|
+
run.assumptions = point.get("assumptions") or {}
|
|
373
|
+
run.coverage_gaps = point.get("coverage_gaps") or []
|
|
374
|
+
run.granted_calls = list(point.get("granted_calls") or [])
|
|
375
|
+
recorded = int(point.get("threads") or 0)
|
|
376
|
+
after = [e for e in run.pass_threads[recorded:] if isinstance(e, dict)]
|
|
377
|
+
resume = ResumePoint(
|
|
378
|
+
run=run, stage=stage, round=int(point.get("round") or 0),
|
|
379
|
+
effective_n=int(point.get("effective_n") or 0),
|
|
380
|
+
pass1_threads=list(point.get("pass1_threads") or []),
|
|
381
|
+
# Exactly one thread opened since the boundary: the failed pass's.
|
|
382
|
+
# Several are an ensemble Pass 1 that stopped part way; its
|
|
383
|
+
# candidates run again rather than this guessing which to continue.
|
|
384
|
+
pending=after[0] if len(after) == 1 else None,
|
|
385
|
+
trace_length=len(run.trace))
|
|
386
|
+
by_id = {c.id: c for c in run.claims}
|
|
387
|
+
resume.flagged = [by_id[i] for i in point.get("flagged") or () if i in by_id]
|
|
388
|
+
_restore_pass1(resume, record)
|
|
389
|
+
if stage in ("Final synthesis",):
|
|
390
|
+
run.final_report = record.get("final_report") or ""
|
|
391
|
+
return resume
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
def _from_trace(record: dict) -> ResumePoint:
|
|
395
|
+
stage, refusal = legacy_stage(record.get("trace"))
|
|
396
|
+
if refusal:
|
|
397
|
+
raise ResumeRefused(refusal)
|
|
398
|
+
if record.get("candidates"):
|
|
399
|
+
raise ResumeRefused(
|
|
400
|
+
"it is an ensemble run recorded before resume points existed, "
|
|
401
|
+
"and its record does not say which thread holds which candidate")
|
|
402
|
+
run = _run_from(record)
|
|
403
|
+
run.claims = _claims_from(record.get("claims"))
|
|
404
|
+
run.coverage_gaps = list(record.get("coverage_gaps") or [])
|
|
405
|
+
resume = ResumePoint(run=run, stage=stage, legacy=True,
|
|
406
|
+
trace_length=len(run.trace))
|
|
407
|
+
threads = run.pass_threads
|
|
408
|
+
completed = {s for s in STAGES_BEFORE_LOOP + STAGES_AFTER_LOOP
|
|
409
|
+
if resume.done(s)}
|
|
410
|
+
if resume.done("Pass 0"):
|
|
411
|
+
run.plan = _answer_payload(_last_thread_of(threads, "Pass 0"), "Pass 0")
|
|
412
|
+
if resume.done("Pass 1"):
|
|
413
|
+
resume.pass1_threads = [_last_thread_of(threads, "Pass 1")]
|
|
414
|
+
if resume.done("Pass 3c"):
|
|
415
|
+
run.completeness = _answer_payload(_last_thread_of(threads, "Pass 3c"),
|
|
416
|
+
"Pass 3c")
|
|
417
|
+
if resume.done("Pass 4"):
|
|
418
|
+
run.assumptions = _answer_payload(_last_thread_of(threads, "Pass 4"),
|
|
419
|
+
"Pass 4")
|
|
420
|
+
if stage == "Final synthesis":
|
|
421
|
+
run.final_report = record.get("final_report") or ""
|
|
422
|
+
# Before §98 a pass's thread was recorded only once the pass RETURNED,
|
|
423
|
+
# so the in-progress pass is named only when it failed after that --
|
|
424
|
+
# bad JSON, or a pass cut off with no text. Its entry is the newest,
|
|
425
|
+
# and its pass is not one the run completed.
|
|
426
|
+
last = threads[-1] if threads and isinstance(threads[-1], dict) else None
|
|
427
|
+
if (last is not None and last.get("pass") in LLM_PASSES
|
|
428
|
+
and last.get("pass") not in completed):
|
|
429
|
+
resume.pending = last
|
|
430
|
+
_restore_pass1(resume, record)
|
|
431
|
+
return resume
|
|
432
|
+
|
|
433
|
+
|
|
434
|
+
def _run_from(record: dict) -> PipelineRun:
|
|
435
|
+
run = PipelineRun(user_query=record["user_query"])
|
|
436
|
+
run.run_id = record["id"]
|
|
437
|
+
run.trace = list(record.get("trace") or [])
|
|
438
|
+
run.pass_threads = [e for e in record.get("pass_threads") or []
|
|
439
|
+
if isinstance(e, dict)]
|
|
440
|
+
return run
|
|
441
|
+
|
|
442
|
+
|
|
443
|
+
def _restore_pass1(resume: ResumePoint, record: dict) -> None:
|
|
444
|
+
"""Pass 1's text, from its thread or its candidates' threads. Needed by
|
|
445
|
+
Pass 2 and Pass 3b; after those it only feeds the artifacts, so a thread
|
|
446
|
+
that cannot be read costs the artifact, not the resume."""
|
|
447
|
+
if not resume.done("Pass 1"):
|
|
448
|
+
return
|
|
449
|
+
run = resume.run
|
|
450
|
+
texts = [last_answer(t) if t else None for t in resume.pass1_threads]
|
|
451
|
+
needed = not resume.done("Pass 3b")
|
|
452
|
+
if not texts or any(t is None for t in texts):
|
|
453
|
+
if needed:
|
|
454
|
+
raise ResumeRefused("Pass 1's text could not be read back from "
|
|
455
|
+
"its thread, and Pass 2 or 3b still needs it")
|
|
456
|
+
resume.notes.append(
|
|
457
|
+
"Resume: Pass 1's text could not be read back, so this run's "
|
|
458
|
+
"artifacts will not include it.")
|
|
459
|
+
return
|
|
460
|
+
candidates = [dict(c) for c in record.get("candidates") or []]
|
|
461
|
+
if candidates and len(candidates) == len(texts):
|
|
462
|
+
for entry, text in zip(candidates, texts):
|
|
463
|
+
entry["text"] = text
|
|
464
|
+
run.candidates = candidates
|
|
465
|
+
run.raw_response = texts[0]
|
|
466
|
+
|
|
467
|
+
|
|
468
|
+
def prepare(run_id) -> ResumePoint:
|
|
469
|
+
"""Rebuild run `run_id` for a resume, or raise ResumeRefused with the
|
|
470
|
+
reason. Reads only: the record is reopened by the orchestrator, once
|
|
471
|
+
nothing here has refused."""
|
|
472
|
+
uid = _as_uuid(run_id)
|
|
473
|
+
if uid is None:
|
|
474
|
+
raise ResumeRefused(f"{run_id!r} is not a run id")
|
|
475
|
+
try:
|
|
476
|
+
record = load_pipeline_run(uid)
|
|
477
|
+
except ValueError as e:
|
|
478
|
+
raise ResumeRefused(f"there is no research run with id {uid}") from e
|
|
479
|
+
if record["status"] not in RESUMABLE_STATUSES:
|
|
480
|
+
raise ResumeRefused(
|
|
481
|
+
f"run {uid} is {record['status']}; only a failed or abandoned "
|
|
482
|
+
f"run can be resumed")
|
|
483
|
+
point = record.get("resume") or {}
|
|
484
|
+
if point:
|
|
485
|
+
return _from_point(record, point)
|
|
486
|
+
return _from_trace(record)
|
|
487
|
+
|
|
488
|
+
|
|
489
|
+
def describe(point: ResumePoint, provider_name: str, model: str) -> str:
|
|
490
|
+
"""The trace line a resume opens with."""
|
|
491
|
+
where = describe_stage(point.stage, point.round)
|
|
492
|
+
how = (" (read from the trace: the run was recorded before resume "
|
|
493
|
+
"points existed)" if point.legacy else "")
|
|
494
|
+
return (f"Resume: picking the run up {where}{how}, on "
|
|
495
|
+
f"{provider_name}/{model}.")
|
|
496
|
+
|
|
497
|
+
|
|
498
|
+
# ---------------------------------------------------------------------------
|
|
499
|
+
# ---- Finding a run ----------------------------------------------------------
|
|
500
|
+
# ---------------------------------------------------------------------------
|
|
501
|
+
|
|
502
|
+
def resumable_runs(limit: int = 50) -> list:
|
|
503
|
+
"""The runs a resume can be offered for, newest first, each with the
|
|
504
|
+
stage it would resume after and, for one this build cannot resume, why.
|
|
505
|
+
The full check is `prepare`'s; this reads only the record's own row."""
|
|
506
|
+
rows = []
|
|
507
|
+
for record in list_resumable_runs(limit=limit):
|
|
508
|
+
point = record.get("resume") or {}
|
|
509
|
+
note = None
|
|
510
|
+
if point:
|
|
511
|
+
stage, round_no = point.get("stage"), int(point.get("round") or 0)
|
|
512
|
+
else:
|
|
513
|
+
stage, note = legacy_stage(record.get("trace"))
|
|
514
|
+
round_no = 0
|
|
515
|
+
rows.append({
|
|
516
|
+
"id": record["id"],
|
|
517
|
+
"user_query": record["user_query"],
|
|
518
|
+
"status": record["status"],
|
|
519
|
+
"started_at": record["started_at"],
|
|
520
|
+
"stage": None if note else describe_stage(stage, round_no),
|
|
521
|
+
"note": note,
|
|
522
|
+
})
|
|
523
|
+
return rows
|
|
524
|
+
|
|
525
|
+
|
|
526
|
+
def find_run(text: str, runs=None) -> UUID:
|
|
527
|
+
"""The run `text` names: a whole id, with or without dashes, or the
|
|
528
|
+
start of one among the resumable runs (eight characters are plenty). A
|
|
529
|
+
prefix that names no run, or several, is refused with what to type."""
|
|
530
|
+
key = (text or "").strip().lower().replace("-", "")
|
|
531
|
+
if not key:
|
|
532
|
+
raise ResumeRefused("no run id given")
|
|
533
|
+
if len(key) == 32:
|
|
534
|
+
uid = _as_uuid(key)
|
|
535
|
+
if uid is None:
|
|
536
|
+
raise ResumeRefused(f"{text!r} is not a run id")
|
|
537
|
+
return uid
|
|
538
|
+
if any(ch not in "0123456789abcdef" for ch in key):
|
|
539
|
+
raise ResumeRefused(f"{text!r} is not a run id")
|
|
540
|
+
if len(key) < 4:
|
|
541
|
+
raise ResumeRefused("type at least four characters of the run id")
|
|
542
|
+
runs = resumable_runs(limit=200) if runs is None else runs
|
|
543
|
+
matches = [r["id"] for r in runs if _as_uuid(r["id"]).hex.startswith(key)]
|
|
544
|
+
if not matches:
|
|
545
|
+
raise ResumeRefused(f"no failed or abandoned run starts with {text!r}")
|
|
546
|
+
if len(matches) > 1:
|
|
547
|
+
raise ResumeRefused(f"{text!r} matches {len(matches)} runs; type more "
|
|
548
|
+
f"of the id")
|
|
549
|
+
return _as_uuid(matches[0])
|
|
550
|
+
|
|
551
|
+
|
|
552
|
+
__all__ = [
|
|
553
|
+
"RESUME_VERSION", "ResumePoint", "ResumeRefused", "describe",
|
|
554
|
+
"describe_stage", "find_run", "last_answer", "legacy_stage", "position",
|
|
555
|
+
"prepare", "rebuild_corpus", "resumable_runs", "snapshot", "thread_tail",
|
|
556
|
+
]
|
|
557
|
+
|
|
@@ -209,6 +209,12 @@ def normalize_url(url: str) -> str:
|
|
|
209
209
|
return urlunsplit((parts.scheme.lower(), host, path, parts.query, ""))
|
|
210
210
|
|
|
211
211
|
|
|
212
|
+
#: The tools whose results `SourceCorpus.add` reads. Named once for the
|
|
213
|
+
#: resume's rebuild (ROADMAP_v3 §98, RS6), which skips every other tool's
|
|
214
|
+
#: stored row before parsing it, and pinned against `add` by a test.
|
|
215
|
+
READ_TOOLS = ("fetch_url", "arxiv_search", "web_search")
|
|
216
|
+
|
|
217
|
+
|
|
212
218
|
@dataclass
|
|
213
219
|
class SourceCorpus:
|
|
214
220
|
"""Every source text one run retrieved, keyed by normalized URL.
|
|
@@ -230,7 +236,7 @@ class SourceCorpus:
|
|
|
230
236
|
|
|
231
237
|
# -- ingest ----------------------------------------------------------
|
|
232
238
|
|
|
233
|
-
def add(self, tool_name: str, result) -> int:
|
|
239
|
+
def add(self, tool_name: str, result, retrieved_at: str | None = None) -> int:
|
|
234
240
|
"""Absorb one tool result. Returns how many documents it added or
|
|
235
241
|
improved.
|
|
236
242
|
|
|
@@ -240,18 +246,23 @@ class SourceCorpus:
|
|
|
240
246
|
whose result is the error shape is also ignored -- `arxiv.py` and
|
|
241
247
|
`web_search.py` both return errors rather than raising, so an
|
|
242
248
|
error dict is an ordinary occurrence here.
|
|
249
|
+
|
|
250
|
+
`retrieved_at` is for a result replayed from its stored row, when
|
|
251
|
+
a resumed run rebuilds its corpus (ROADMAP_v3 §98, RS6): the time
|
|
252
|
+
the row was written, not the time of the replay. None, every live
|
|
253
|
+
call, stamps now.
|
|
243
254
|
"""
|
|
244
255
|
if not isinstance(result, dict) or "error" in result:
|
|
245
256
|
return 0
|
|
246
257
|
if tool_name == "fetch_url":
|
|
247
|
-
return self._add_fetch_url(result)
|
|
258
|
+
return self._add_fetch_url(result, retrieved_at)
|
|
248
259
|
if tool_name == "arxiv_search":
|
|
249
|
-
return self._add_arxiv(result)
|
|
260
|
+
return self._add_arxiv(result, retrieved_at)
|
|
250
261
|
if tool_name == "web_search":
|
|
251
|
-
return self._add_web_search(result)
|
|
262
|
+
return self._add_web_search(result, retrieved_at)
|
|
252
263
|
return 0
|
|
253
264
|
|
|
254
|
-
def _add_fetch_url(self, result: dict) -> int:
|
|
265
|
+
def _add_fetch_url(self, result: dict, retrieved_at=None) -> int:
|
|
255
266
|
# `url` is the URL that ANSWERED, after redirects -- which is what
|
|
256
267
|
# fetch_url.py:89-95 says the grounding pass attributes the text
|
|
257
268
|
# to, and therefore what the model will cite.
|
|
@@ -268,9 +279,10 @@ class SourceCorpus:
|
|
|
268
279
|
title="",
|
|
269
280
|
tool="fetch_url",
|
|
270
281
|
offset=offset,
|
|
282
|
+
retrieved_at=retrieved_at,
|
|
271
283
|
)
|
|
272
284
|
|
|
273
|
-
def _add_arxiv(self, result: dict) -> int:
|
|
285
|
+
def _add_arxiv(self, result: dict, retrieved_at=None) -> int:
|
|
274
286
|
added = 0
|
|
275
287
|
for entry in result.get("results") or ():
|
|
276
288
|
if not isinstance(entry, dict):
|
|
@@ -290,10 +302,11 @@ class SourceCorpus:
|
|
|
290
302
|
text=text,
|
|
291
303
|
title=title,
|
|
292
304
|
tool="arxiv_search",
|
|
305
|
+
retrieved_at=retrieved_at,
|
|
293
306
|
)
|
|
294
307
|
return added
|
|
295
308
|
|
|
296
|
-
def _add_web_search(self, result: dict) -> int:
|
|
309
|
+
def _add_web_search(self, result: dict, retrieved_at=None) -> int:
|
|
297
310
|
added = 0
|
|
298
311
|
for entry in result.get("results") or ():
|
|
299
312
|
if not isinstance(entry, dict):
|
|
@@ -306,10 +319,12 @@ class SourceCorpus:
|
|
|
306
319
|
text=text,
|
|
307
320
|
title=title,
|
|
308
321
|
tool="web_search",
|
|
322
|
+
retrieved_at=retrieved_at,
|
|
309
323
|
)
|
|
310
324
|
return added
|
|
311
325
|
|
|
312
|
-
def _store(self, url, text, title: str, tool: str, offset=None
|
|
326
|
+
def _store(self, url, text, title: str, tool: str, offset=None,
|
|
327
|
+
retrieved_at=None) -> int:
|
|
313
328
|
"""Absorb one document, or one PAGE of one (ROADMAP_v3 §51, PG7).
|
|
314
329
|
|
|
315
330
|
`offset` is the source position this text starts at, or None from a
|
|
@@ -374,7 +389,7 @@ class SourceCorpus:
|
|
|
374
389
|
return 0
|
|
375
390
|
self.documents[key] = SourceDocument(
|
|
376
391
|
url=key, text=merged, title=existing.title,
|
|
377
|
-
tool=tool, retrieved_at=_now(),
|
|
392
|
+
tool=tool, retrieved_at=retrieved_at or _now(),
|
|
378
393
|
next_offset=max(existing.next_offset, offset + len(text)),
|
|
379
394
|
)
|
|
380
395
|
return 1
|
|
@@ -395,7 +410,7 @@ class SourceCorpus:
|
|
|
395
410
|
|
|
396
411
|
self.documents[key] = SourceDocument(
|
|
397
412
|
url=key, text=cleaned, title=title or (existing.title if existing else ""),
|
|
398
|
-
tool=tool, retrieved_at=_now(),
|
|
413
|
+
tool=tool, retrieved_at=retrieved_at or _now(),
|
|
399
414
|
# In the SOURCE's positions, so the next page's offset can be
|
|
400
415
|
# compared against it. `len(text)` and not `len(cleaned)`:
|
|
401
416
|
# redaction and stripping change how much is HELD, never where
|