@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.
@@ -31,7 +31,7 @@ from datetime import UTC, datetime
31
31
  from typing import Optional
32
32
  from uuid import UUID, uuid4
33
33
 
34
- from sqlmodel import Field, Session, SQLModel
34
+ from sqlmodel import Field, Session, SQLModel, select
35
35
 
36
36
  from database import engine
37
37
 
@@ -47,14 +47,15 @@ logger = logging.getLogger(__name__)
47
47
  class PipelineRunRecord(SQLModel, table=True):
48
48
  """One row per stream_deep_research_pipeline() invocation. `status` is
49
49
  'running' from creation until the wrapping try/except in the
50
- orchestrator flips it to 'complete' or 'failed'. The SIX data columns
50
+ orchestrator flips it to 'complete' or 'failed'. The SEVEN data columns
51
51
  carry the run's structured output (or the partial state available at
52
52
  failure time) so an operator can inspect what happened without a
53
53
  separate trace log.
54
54
 
55
- SIX, not the four this paragraph said until batch 154: T2 added
56
- pass_threads_json and E13 added candidates_json, and neither batch
57
- found the enumerations written about them. The count is pinned by
55
+ SEVEN, not the four this paragraph said until batch 154: T2 added
56
+ pass_threads_json, E13 added candidates_json and §98 resume_json, and
57
+ the first two batches found none of the enumerations written about
58
+ them. The count is pinned by
58
59
  test_the_documented_record_shape_matches_what_load_returns, which
59
60
  reads it out of the prose rather than out of a second list here."""
60
61
 
@@ -82,6 +83,13 @@ class PipelineRunRecord(SQLModel, table=True):
82
83
  # what it had reached.
83
84
  candidates_json: str = "[]"
84
85
  final_report: str = ""
86
+ # ROADMAP_v3 §98 (RS2): where a resume picks the run up. Written at the
87
+ # end of each STAGE, never at a trace line inside one, and never by the
88
+ # failure path, so it always describes a boundary the run reached in
89
+ # full -- claims_json beside it is written on failure too, and may hold
90
+ # a stage's work half applied. "{}" on every run recorded before §98,
91
+ # which core/reasoning/resume.py reads from the trace instead (RS9).
92
+ resume_json: str = "{}"
85
93
  started_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
86
94
  finished_at: Optional[datetime] = None
87
95
 
@@ -127,6 +135,10 @@ def update_pipeline_run(
127
135
  synthesis). If a nested-dataclass field is ever added to Claim, ALL of
128
136
  those sites migrate to asdict(c) together -- see the note on Claim in
129
137
  core/reasoning/base.py.
138
+
139
+ resume_json is NOT written here (ROADMAP_v3 §98, RS2): this runs at
140
+ every trace line and on the failure path, and the resume point must
141
+ move only at the end of a stage. save_resume_point is its one writer.
130
142
  """
131
143
  with Session(engine) as session:
132
144
  record = session.get(PipelineRunRecord, run_id)
@@ -156,10 +168,76 @@ def update_pipeline_run(
156
168
  session.commit()
157
169
 
158
170
 
171
+ def save_resume_point(run_id: UUID, point: dict) -> None:
172
+ """Record where a resume would pick this run up (ROADMAP_v3 §98, RS2).
173
+
174
+ The ONE writer of resume_json, called at the end of each stage and
175
+ nowhere else. Its own function rather than an argument to
176
+ update_pipeline_run, because that one runs at every trace line and on
177
+ the failure path, and the point has to be a boundary the run reached in
178
+ full. Self-contained -- the claims are copied into it -- so it needs no
179
+ transaction shared with the data columns: claims_json beside it may be
180
+ newer, and a resume reads this one."""
181
+ with Session(engine) as session:
182
+ record = session.get(PipelineRunRecord, run_id)
183
+ if record is None:
184
+ raise ValueError(f"No pipeline run found with id {run_id}")
185
+ record.resume_json = json.dumps(point)
186
+ session.add(record)
187
+ session.commit()
188
+
189
+
190
+ def reopen_pipeline_run(run_id: UUID) -> None:
191
+ """Put a failed or abandoned run back to 'running' for a resume
192
+ (ROADMAP_v3 §98, RS1). `finished_at` is cleared because the run is no
193
+ longer finished; the resume's own end sets it again. Raises ValueError
194
+ for an unknown id, like every writer here."""
195
+ with Session(engine) as session:
196
+ record = session.get(PipelineRunRecord, run_id)
197
+ if record is None:
198
+ raise ValueError(f"No pipeline run found with id {run_id}")
199
+ record.status = "running"
200
+ record.finished_at = None
201
+ session.add(record)
202
+ session.commit()
203
+
204
+
159
205
  # ---------------------------------------------------------------------------
160
206
  # ---- Public read API -------------------------------------------------------
161
207
  # ---------------------------------------------------------------------------
162
208
 
209
+ #: The statuses a resume is offered for (ROADMAP_v3 §98, RS1). 'running'
210
+ #: is a run that was abandoned -- a quit or a kill leaves it there, §22 --
211
+ #: or one still running in another process sharing app.db, and nothing in
212
+ #: the record can tell those apart, so the listing says both.
213
+ RESUMABLE_STATUSES = ("failed", "running")
214
+
215
+
216
+ def list_resumable_runs(limit: int = 50) -> list[dict]:
217
+ """The runs a resume can be offered for, newest first, as plain dicts:
218
+ id, user_query, status, started_at, finished_at, trace and resume (the
219
+ two fields the stage is read from). Bounded by `limit` because a
220
+ long-lived database holds every run it ever started."""
221
+ with Session(engine) as session:
222
+ statement = (
223
+ select(PipelineRunRecord)
224
+ .where(PipelineRunRecord.status.in_(RESUMABLE_STATUSES))
225
+ .order_by(PipelineRunRecord.started_at.desc())
226
+ .limit(limit)
227
+ )
228
+ return [
229
+ {
230
+ "id": record.id,
231
+ "user_query": record.user_query,
232
+ "status": record.status,
233
+ "started_at": record.started_at,
234
+ "finished_at": record.finished_at,
235
+ "trace": json.loads(record.trace_json or "[]"),
236
+ "resume": json.loads(record.resume_json or "{}"),
237
+ }
238
+ for record in session.exec(statement).all()
239
+ ]
240
+
163
241
  def load_pipeline_run(run_id: UUID) -> dict:
164
242
  """Loads a PipelineRunRecord by id and returns its state as a plain
165
243
  dict. Raises ValueError if run_id doesn't exist (matching
@@ -199,6 +277,9 @@ def load_pipeline_run(run_id: UUID) -> dict:
199
277
  # its sibling's; tests/test_storage_e2e.py pins both facts.
200
278
  "candidates": json.loads(record.candidates_json or "[]"),
201
279
  "final_report": record.final_report,
280
+ # §98 (RS2). The same floor as its two siblings: a NULL is SQL
281
+ # nobody here wrote, and json.loads(None) would raise on it.
282
+ "resume": json.loads(record.resume_json or "{}"),
202
283
  }
203
284
 
204
285