@yahyahammad/venastine 0.3.18 → 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.
@@ -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) -> int:
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