rrrrrredy/research-toolkit / plugins/research-toolkit
research-toolkit
FlaggedUse for source-backed long-form research and writing in English or Chinese across fields, including revisions and continuation. Understand requirements, develop analysis through substantive research collaboration, and deliver a complete report after independent review, audit and acceptance.
scripts/research_records.py
View on GitHub"""Save agent-provided research records without making users edit CSV/JSONL."""
from __future__ import annotations
import csv
import io
import json
import os
import uuid
import hashlib
import re
import shutil
from check_delivery import (inspect_csv_text, inspect_jsonl_text, length_constraint_errors, sha256_file,
has_evidence, REQUIREMENT_DECISION_STATUSES, READING_REQUIREMENTS)
from run_observation import now, record_event
SCHEMAS = {
"sources": ("data/source_registry.csv", "source_id", "S", "url",
["source_id", "title", "url", "source_type", "read_scope", "read_evidence", "evidence_path"]),
"claims": ("data/claims_registry.csv", "claim_id", "C", "claim",
["claim_id", "claim", "claim_type", "supporting_sources", "counter_evidence", "uncertainty"]),
"requirements": ("state/requirements.jsonl", "requirement_id", "R", "summary", []),
}
def revised_spec(original, previous, updates):
"""Replace known brief values while retaining manually added sections."""
text = original.decode("utf-8-sig").replace("\r\n", "\n").replace("\r", "\n")
for key, value in updates.items():
if previous.get(key) == value:
continue
header = f"## {key}\n\n"
if key not in previous and not re.search(r"(?m)^## " + re.escape(key) + r"\s*$", text):
text = text.rstrip() + "\n\n" + header + value + "\n"
continue
pattern = re.compile(r"(?m)^" + re.escape(header + previous.get(key, "")) + r"(?=\n|$)")
if len(list(pattern.finditer(text))) != 1:
raise ValueError(f"brief.{key}: task_spec no longer matches the saved field. Agent: reconcile that field with the actual specification before retrying; retain other sections.")
text = pattern.sub(lambda _: header + value, text, count=1)
return text.encode("utf-8")
def merge_records(root, kind, incoming, replace):
from task_storage import safe_path
name, identity, prefix, natural_key, defaults = SCHEMAS[kind]
path = safe_path(root, name)
original = path.read_bytes() if path.exists() else None
if not isinstance(incoming, list) or any(not isinstance(row, dict) for row in incoming):
raise ValueError(f"{kind}: provide a list of objects, not CSV text.")
columns, rows = list(defaults), []
if original and not replace:
text = original.decode("utf-8-sig")
if defaults:
rows, errors = inspect_csv_text(text, name, (identity,), identity)
columns = list(csv.DictReader(io.StringIO(text)).fieldnames or defaults)
else:
rows, errors = inspect_jsonl_text(text, name)
ids = [r.get(identity, r.get("id")) for r in rows]
if any(not isinstance(i, str) or not i.strip() for i in ids) or len(set(ids)) != len(ids):
errors.append("Missing or duplicate requirement IDs.")
for row in rows:
if identity not in row and "id" in row:
row[identity] = row["id"]
if errors:
raise ValueError(f"{kind}: {'; '.join(errors)} Agent: recover complete rows and resubmit with replace=['{kind}']; the tool retains the original backup.")
used = {row[identity] for row in rows}
touched, ids = set(), []
for index, patch in enumerate(incoming):
patch = dict(patch)
if any(not isinstance(key, str) or not key.strip() for key in patch):
raise ValueError(f"{kind}[{index}]: field names must be nonempty text.")
key = patch.get(identity)
if key is None:
matches = [r for r in rows if patch.get(natural_key) and r.get(natural_key) == patch[natural_key]]
if len(matches) > 1:
raise ValueError(f"{kind}[{index}]: multiple {natural_key} matches; supply {identity} from the saved records.")
if matches:
key = matches[0][identity]
else:
n = 1
while f"{prefix}{n}" in used:
n += 1
key = f"{prefix}{n}"
if not isinstance(key, str) or not key.strip() or key in touched:
raise ValueError(f"{kind}[{index}].{identity}: provide distinct nonempty IDs in this request.")
patch[identity] = key
touched.add(key)
used.add(key)
ids.append(key)
old = next((row for row in rows if row[identity] == key), None)
row = {**(old or {}), **patch}
if defaults:
if kind == "sources":
row.setdefault("read_scope", "not_read")
if not isinstance(row["read_scope"], str) or row["read_scope"] not in {"", "not_read", "partial", "abstract", "relevant_sections", "full_text"}:
raise ValueError(f"sources[{index}].read_scope: use not_read/partial/abstract/relevant_sections/full_text.")
for field, value in row.items():
if field == "supporting_sources" and isinstance(value, list) and all(isinstance(v, str) for v in value):
row[field] = ";".join(value)
elif not isinstance(value, str):
raise ValueError(f"{kind}[{index}].{field}: use text" + (" or a source-ID list." if field == "supporting_sources" else "."))
if field not in columns:
columns.append(field)
required = ("title", "url", "source_type") if kind == "sources" else ("claim", "claim_type")
for field in required:
if not row.get(field, "").strip():
raise ValueError(f"{kind}[{index}].{field}: provide the actual {field}; existing values are retained on updates.")
else:
if not isinstance(row.get("summary", row.get("description")), str):
raise ValueError(f"requirements[{index}].summary: provide the requirement in plain language.")
if "unit_ids" in row:
unit_ids = row["unit_ids"]
if (not isinstance(unit_ids, list)
or any(not isinstance(value, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]*', value) for value in unit_ids)
or len(set(unit_ids)) != len(unit_ids)):
raise ValueError(f"requirements[{index}].unit_ids: use distinct research-unit IDs, such as [\"domestic\"]; omit or use [] for a global requirement.")
row.setdefault("status", "pending")
if row["status"] not in {"pending", "open", "in_progress", "blocked", "satisfied", "waived", "out_of_scope", "accepted_limitation"}:
raise ValueError(f"requirements[{index}].status: use pending/open/in_progress/blocked/satisfied/waived/out_of_scope/accepted_limitation.")
if row["status"] == "satisfied" and not has_evidence(row.get("evidence")):
raise ValueError(f"requirements[{index}].evidence: satisfied needs a nonempty evidence string or list; keep pending until checked.")
if row["status"] in REQUIREMENT_DECISION_STATUSES:
decision = row.get("user_decision")
if not isinstance(decision, dict) or not all(isinstance(decision.get(k), str) and decision[k].strip() for k in ("source_turn", "quote")):
raise ValueError(f"requirements[{index}].user_decision: retain the user's actual source_turn and quote for this scope decision.")
if "required_source_ids" in row and (not isinstance(row["required_source_ids"], list)
or not row["required_source_ids"] or not all(isinstance(s, str) and s.strip() for s in row["required_source_ids"])):
raise ValueError(f"requirements[{index}].required_source_ids: use a nonempty list of source IDs.")
# An explicit user scope decision can retire a legacy obligation
# without inventing a corrected reading promise for that old row.
if row["status"] not in REQUIREMENT_DECISION_STATUSES and ("reading_requirement" in row or "required_source_ids" in row):
if not isinstance(row.get("reading_requirement"), str) or row["reading_requirement"] not in READING_REQUIREMENTS:
raise ValueError(f"requirements[{index}].reading_requirement: use full_text or relevant_sections.")
source_ids = row.get("required_source_ids")
if (not isinstance(source_ids, list) or not source_ids
or not all(isinstance(s, str) and s.strip() for s in source_ids)
or len(source_ids) != len(set(source_ids))):
raise ValueError(f"requirements[{index}].required_source_ids: use a nonempty list of distinct source IDs.")
if "length_constraint" in row:
errors = length_constraint_errors(row["length_constraint"])
if errors:
raise ValueError(f"requirements[{index}].length_constraint: {'; '.join(errors)}")
if old is None:
rows.append(row)
else:
rows[rows.index(old)] = row
if defaults:
stream = io.StringIO(newline="")
writer = csv.DictWriter(stream, fieldnames=columns, lineterminator="\n")
writer.writeheader()
writer.writerows(rows)
content = stream.getvalue()
else:
content = "".join(json.dumps(row, ensure_ascii=False) + "\n" for row in rows)
return name, content.encode("utf-8"), original, ids
def save_records(root, sources=None, claims=None, requirements=None, draft=None, replace=None, brief=None):
from task_storage import safe_path, load
from research_guidance import BRIEF_FIELDS
stamp, operation_id = now(), uuid.uuid4().hex
event = {"operation": "save", "operation_id": operation_id, "started_at": stamp}
plans, backups, ids, temporary, committed = [], [], {}, [], []
try:
progress = load(root, "state/progress.json")
old_progress = dict(progress)
if brief is not None:
if (not isinstance(brief, dict) or not brief or any(k not in BRIEF_FIELDS for k in brief)
or any(not isinstance(v, str) or not v.strip() for v in brief.values())):
raise ValueError("brief: provide nonempty text updates to question/audience/scope/output/depth/evidence_standard.")
previous_brief = progress.get("brief", {})
progress["brief"] = {**previous_brief, **brief}
if progress["brief"] != previous_brief:
path = safe_path(root, "state/task_spec.md")
original_spec = path.read_bytes()
plans.append(("state/task_spec.md", revised_spec(original_spec, previous_brief, brief), original_spec))
values = {"sources": sources, "claims": claims, "requirements": requirements}
replace = [] if replace is None else replace
if not isinstance(replace, list) or any(k not in SCHEMAS or values[k] is None for k in replace):
raise ValueError("replace: list only supplied record collections (sources, claims, requirements).")
for kind, incoming in values.items():
if incoming is not None:
name, content, original, ids[kind] = merge_records(root, kind, incoming, kind in replace)
plans.append((name, content, original))
if kind in replace and original is not None:
backups.append((f"logs/record-backups/{operation_id}/{name}", original, None))
if draft is not None:
allowed = {"path", "content", "complete", "main", "kind", "based_on", "host_task",
"unit_id", "depends_on", "handoff", "question"}
if not isinstance(draft, dict) or set(draft) - allowed:
raise ValueError("draft: use path and optional content/complete/main/kind/based_on/host_task/unit_id/depends_on/handoff/question; complete records draft or unit completeness, not delivery approval.")
name = draft.get("path")
path = safe_path(root, name)
target_name = path.relative_to(root.resolve()).as_posix()
protected = {"state", "data", "logs", "reviews"}
if (name.split("/")[0] in protected or target_name.split("/")[0] in protected
or path.suffix not in {".md", ".txt"}):
raise ValueError("draft.path: use a report .md/.txt path outside state/data/logs/reviews, including resolved link targets; for example, reports/draft.md.")
if type(draft.get("complete", False)) is not bool:
raise ValueError("draft.complete: use true or false.")
if type(draft.get("main", False)) is not bool:
raise ValueError("draft.main: use true or false.")
if draft.get("kind", "report") not in {"report", "comparison", "review", "analysis"}:
raise ValueError("draft.kind: use report, comparison, review or analysis (a research contribution).")
from task_context import research_outputs, prepared_work
outputs = research_outputs(root, [], progress)
previous = next((item for item in outputs if safe_path(root, item['path']) == path), {})
current = progress.get("current_artifact", {})
writes_current = bool(current.get('path') and safe_path(root, current['path']) == path)
unit_id = draft.get('unit_id', previous.get('unit_id'))
prepared = prepared_work(root, unit_id) or {}
# Bind the versions actually returned at preparation, not current
# file hashes at save time. Explicit callers retain their override.
supplied_inputs = draft.get('based_on', prepared.get('based_on', previous.get('based_on', {})))
if not isinstance(supplied_inputs, dict):
raise ValueError('draft.based_on: use the work_context.inputs reference-to-SHA256 object.')
if unit_id is not None:
if not isinstance(unit_id, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9_.-]*', unit_id):
raise ValueError('draft.unit_id: use a stable research-unit ID with letters, numbers, dots, underscores or hyphens.')
if previous.get('unit_id') not in {None, unit_id} or any(
item.get('unit_id') == unit_id and safe_path(root, item['path']) != path for item in outputs):
raise ValueError('draft.unit_id: retain the registered unit and its original artifact path; use a new ID for different work.')
if not isinstance(draft.get('host_task'), str) or not draft['host_task'].strip():
raise ValueError('draft.host_task: identify the actual producing agent task/session when saving a research unit.')
event['unit_id'] = unit_id
event['unit_complete'] = draft.get('complete', False)
if 'question' in draft:
if not isinstance(draft['question'], str) or not draft['question'].strip():
raise ValueError('draft.question: state the research question this contribution answers.')
event['question'] = draft['question']
elif prepared.get('question') or previous.get('question'):
event['question'] = prepared.get('question') or previous['question']
dependencies = draft.get('depends_on', prepared.get('depends_on', previous.get('depends_on', [])))
if (not isinstance(dependencies, list) or any(not isinstance(value, str) or not value.strip() for value in dependencies)
or len(set(dependencies)) != len(dependencies) or unit_id in dependencies):
raise ValueError('draft.depends_on: use distinct upstream research-unit IDs; a unit cannot depend on itself.')
if dependencies and unit_id is None:
raise ValueError('draft.unit_id: identify the research unit whose dependencies are being saved.')
if unit_id:
graph = {item['unit_id']: item.get('depends_on', []) for item in outputs if item.get('unit_id')}
graph[unit_id] = dependencies
def cyclic(identity, visiting):
return identity in visiting or any(cyclic(parent, visiting | {identity}) for parent in graph.get(identity, []))
if cyclic(unit_id, set()):
raise ValueError('draft.depends_on: remove the cyclic dependency; retain only actual upstream work.')
event['depends_on'] = dependencies
upstream_versions = {}
for dependency in dependencies:
upstream = next((item for item in outputs if item.get('unit_id') == dependency), None)
if upstream:
upstream_versions[dependency] = supplied_inputs.get(upstream['path'],
previous.get('dependency_versions', {}).get(dependency, upstream['sha256']))
event['dependency_versions'] = upstream_versions
if draft.get('complete'):
pending = []
for dependency in dependencies:
upstream = next((item for item in outputs if item.get('unit_id') == dependency), None)
issues = upstream.get('readiness_issues', []) if upstream else ['not_registered']
if upstream and upstream_versions[dependency] != upstream['sha256']:
issues = issues + ['dependency_version_changed']
if issues:
pending.append(f"{dependency}: {', '.join(issues)}")
if pending:
raise ValueError('draft.complete: upstream work is not ready (' + '; '.join(pending)
+ '). Save the current draft with complete=false; finish or revise and independently review the affected upstream work.')
if 'host_task' in draft:
if not isinstance(draft['host_task'], str) or not draft['host_task'].strip():
raise ValueError('draft.host_task: retain the actual agent task/session reference as text.')
event['host_task'] = draft['host_task']
handoff = draft.get('handoff')
if handoff is not None:
if (not isinstance(handoff, dict) or set(handoff) - {'summary', 'pending', 'decisions', 'to'}
or not isinstance(handoff.get('summary'), str) or not handoff['summary'].strip()):
raise ValueError('draft.handoff: use summary, optional pending/decisions lists and to (the receiving agent task/session).')
for field in ('pending', 'decisions'):
if field in handoff and (not isinstance(handoff[field], list) or any(
not isinstance(value, str) or not value.strip() for value in handoff[field])):
raise ValueError(f'draft.handoff.{field}: use a list of substantive points; retain full analysis in the artifact.')
if 'to' in handoff and (not isinstance(handoff['to'], str) or not handoff['to'].strip()):
raise ValueError('draft.handoff.to: use the receiving agent task/session reference.')
if not event.get('host_task'):
raise ValueError('draft.host_task: identify the sender of the handoff.')
event['handoff'] = handoff
# The main manuscript has one declared writer. Transfer is a saved
# handoff from that writer, not another writer silently claiming main.
main_owner = current.get('owner')
owner = main_owner if (writes_current or draft.get('main')) and main_owner else previous.get('owner') if unit_id else None
if owner and event.get('host_task') != owner:
raise ValueError(f'draft.host_task: {owner} owns this manuscript or research unit. Save an explicit handoff.to from that owner before another agent writes it.')
if 'based_on' in draft or prepared or previous.get('based_on'):
for input_name, checksum in supplied_inputs.items():
if isinstance(input_name, str) and input_name.startswith('record:'):
parts = input_name.split(':', 2)
if len(parts) != 3 or parts[1] not in SCHEMAS or not parts[2]:
raise ValueError(f'draft.based_on[{input_name}]: use a record reference returned in work_context.inputs.')
else:
safe_path(root, input_name)
if not isinstance(checksum, str) or not re.fullmatch('[a-f0-9]{64}', checksum):
raise ValueError(f'draft.based_on[{input_name}]: use the SHA256 returned in work_context.inputs.')
event['based_on'] = supplied_inputs
if unit_id:
def other_inputs(item):
return {key: value for key, value in item.get('based_on', {}).items()
if key.startswith('record:') or safe_path(root, key) != path}
if (other_inputs(event) != other_inputs(previous)
or dependencies != previous.get('depends_on', [])
or event.get('question') != previous.get('question')):
# This cached approval describes the previous input selection.
# Keep its plan and original results for the next revision.
progress['unit_reviews'] = {key: value for key, value in progress.get('unit_reviews', {}).items()
if key != unit_id}
# Preserve earlier contributions through the existing backup mechanism.
# A child contribution never implicitly replaces the registered main draft.
original = path.read_bytes() if path.exists() else None
content = draft.get("content")
if "content" not in draft:
content = path.read_text(encoding="utf-8")
if not isinstance(content, str) or not content.strip():
raise ValueError("draft.content: provide nonempty report text or an existing nonempty UTF-8 file.")
if "content" in draft:
plans.append((name, content.encode("utf-8"), original))
if original is not None and original != content.encode('utf-8'):
backup = f'logs/record-backups/{operation_id}/{name}'
backups.append((backup, original, None))
event['previous_version'] = {'path': backup, 'sha256': sha256_file(path)}
if unit_id:
# Retain the saved version even if an agent tool subsequently edits its
# working file directly. Handoff summaries never replace it.
snapshot = f'logs/record-backups/{operation_id}/saved/{name}'
backups.append((snapshot, content.encode('utf-8') if 'content' in draft else original, None))
event['artifact_snapshot'] = {'path': snapshot,
'sha256': hashlib.sha256(content.replace('\r\n', '\n').replace('\r', '\n').encode('utf-8')).hexdigest()}
event.update(artifact=name, artifact_kind=draft.get('kind', 'report'),
complete_draft=draft.get("complete", False) and draft.get('kind') != 'analysis')
if draft.get("main") or writes_current:
normalized = content.replace("\r\n", "\n").replace("\r", "\n")
progress["current_artifact"] = {"path": name,
"sha256": hashlib.sha256(normalized.encode("utf-8")).hexdigest(),
"kind": draft.get("kind", current.get("kind", "report") if current.get("path") == name else "report")}
active_owner = (handoff or {}).get('to') or event.get('host_task') or main_owner
if active_owner:
progress['current_artifact']['owner'] = active_owner
if unit_id:
progress['current_artifact']['unit_id'] = unit_id
if not plans and draft is None and brief is None:
raise ValueError("Supply sources, claims, requirements or a draft to save.")
research_changed = any(content != original for _, content, original in plans)
if draft is not None:
research_changed = research_changed or progress != old_progress or any(
key in event and event[key] != previous.get(key)
for key in ('unit_id', 'depends_on', 'handoff', 'based_on', 'host_task', 'question'))
content_hash = hashlib.sha256(content.replace('\r\n', '\n').replace('\r', '\n').encode('utf-8')).hexdigest()
research_changed = (research_changed or previous.get('sha256') != content_hash
or ('complete' in draft and draft['complete'] != previous.get('complete', False)))
if research_changed:
progress['review_contract'] = max(2, progress.get('review_contract', 1))
if progress.get('stage') in {'final', 'review'} or progress.get('status') == 'complete':
progress.update(stage='revise', status='in_progress',
next_action='Continue the affected research and independent review; historical receipts remain retained.')
if progress != old_progress:
# Keep historical receipts and reviews intact. An explicit new main
# draft or brief revision cannot retain a terminal current state.
if progress.get("stage") in {"final", "review"} or progress.get("status") == "complete":
progress.update(stage="revise", status="in_progress",
next_action="Continue the current work; reconcile affected requirements and review this version before delivery.")
path = safe_path(root, "state/progress.json")
plans.append(("state/progress.json", (json.dumps(progress, ensure_ascii=False, indent=2) + "\n").encode("utf-8"), path.read_bytes()))
# Validate and stage every payload before replacing any current record.
for name, content, original in backups + plans:
if content == original:
continue
path = safe_path(root, name)
path.parent.mkdir(parents=True, exist_ok=True)
temp = path.with_name(path.name + "." + operation_id + ".tmp")
temporary.append(temp)
with temp.open("xb") as stream:
stream.write(content)
if path.exists():
shutil.copymode(path, temp)
committed.append((path, original, False))
for i, temp in enumerate(temporary):
path, original, _ = committed[i]
os.replace(temp, path)
committed[i] = (path, original, True)
if draft is not None:
event["artifact_sha256"] = sha256_file(safe_path(root, draft["path"]))
event["outcome"] = "saved"
result = {"ok": True, "saved_ids": ids, "updated_files": [p[0] for p in plans if p[1] != p[2]],
"backups": [p[0] for p in backups], "next_action": "Continue the research; existing draft, review and delivery checks still apply."}
if ids:
from record_changes import history, summarize_save
try:
event["record_changes"] = summarize_save(root, plans, ids, history(root))
except (OSError, ValueError, TypeError, KeyError, AttributeError):
result["observation_warning"] = "Records saved; change summary unavailable. Existing checks still apply."
except (ValueError, TypeError, OSError, KeyError) as exc:
for path, original, changed in reversed(committed):
if changed:
if original is None:
path.unlink(missing_ok=True)
else:
path.write_bytes(original)
event.update(outcome="error", error=str(exc))
if isinstance(exc, OSError):
next_action = ("The save failed; prior records were retained. Resolve access or file-use restrictions at the reported path, "
"then retry the same save. Do not change research fields to work around a file error.")
else:
next_action = "Agent: correct the indicated fields and retry. Keep research decisions with the user; do not ask them to edit CSV/JSONL."
result = {"ok": False, "errors": [str(exc)], "next_action": next_action}
finally:
for temp in temporary:
temp.unlink(missing_ok=True)
event.update(finished_at=now())
try:
record_event(root, event)
except (ValueError, OSError) as exc:
result["observation_warning"] = f"Activity could not be recorded: {exc}"
if result["ok"]:
from record_changes import latest_changes
from task_context import current_work
result["changes"] = latest_changes(root)
result["current_work"] = current_work(root, load(root, "state/progress.json"))
return {**result, "observation": event}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |