← Files LuciaARCHIVED FILE
scripts/legal_proofreading.py
11.6 KB · Nov 21, 2026 · 00:11 UTC
"""Persist and render a model-authored forensic review with exact source checks."""
from __future__ import annotations
import argparse
import html
import json
import logging
from pathlib import Path
from typing import Any
from jsonschema import Draft202012Validator
from legal_documents import read_pack
__all__ = ["CATEGORIES", "scaffold", "validate_audit", "render_audit", "main"]
LOGGER = logging.getLogger(__name__)
CATEGORIES = (
"definitions",
"references",
"consistency",
"entities",
"numbers",
"language",
"numbering",
"formatting",
)
SEVERITIES = ("critical", "high", "medium", "low", "info")
def _load(path: Path) -> Any:
return json.loads(path.read_text(encoding="utf-8"))
def scaffold(run_dir: Path) -> Path:
"""Create an explicit unreviewed audit; existence never means inspection ran."""
pack = read_pack(run_dir)
target = run_dir / "proofreading.json"
audit = {
"context": _load(run_dir / "review.json")["context"],
"documents": {
source["id"]: {
"reviewed_anchors": [],
"limitations": source["warnings"],
"maps": {
name: {"entries": [], "note": ""}
for name in ("entities", "sections", "terms")
},
"passes": {
name: {"status": "not-reviewed", "note": ""} for name in CATEGORIES
},
"visual_review": {"status": "not-reviewed", "evidence": ""},
}
for source in pack["sources"]
},
"findings": [],
"takeaways": [],
}
with target.open("x", encoding="utf-8") as handle:
json.dump(audit, handle, ensure_ascii=False, indent=2)
handle.write("\n")
return target
def validate_audit(run_dir: Path, audit: dict[str, Any]) -> dict[str, Any]:
"""Check audit shape, declared coverage and quotes, not judgment or truth."""
pack = read_pack(run_dir)
sources = {source["id"]: source for source in pack["sources"]}
schema = _load(Path(__file__).with_name("legal_proofreading.schema.json"))
errors = [
f"{e.json_path}: {e.message}"
for e in Draft202012Validator(schema).iter_errors(audit)
]
if errors:
return {"valid": False, "complete": False, "errors": errors, "limitations": []}
context_schema = _load(
Path(__file__).with_name("legal_documents_review.schema.json")
)["properties"]["context"]
errors.extend(
f"context.{e.json_path}: {e.message}"
for e in Draft202012Validator(context_schema).iter_errors(audit["context"])
)
documents = audit["documents"]
limits: list[str] = []
if set(documents) != set(sources):
errors.append("Retain every selected document, including unreadable documents.")
units = {
(s["id"], u["anchor"]): u["text"] for s in sources.values() for u in s["units"]
}
def check_citations(citations: list[dict[str, str]], owner: str) -> None:
for citation in citations:
text = units.get((citation["source_id"], citation["anchor"]))
quote = " ".join(citation["quote"].split())
if not text or not quote or quote not in " ".join(text.split()):
errors.append(
f"{owner}: quotation not found at the cited source anchor."
)
for source_id, document in documents.items():
if source_id not in sources:
continue
source = sources[source_id]
anchors = {unit["anchor"] for unit in source["units"]}
reviewed = set(document["reviewed_anchors"])
if reviewed - anchors:
errors.append(f"{source_id}: unknown reviewed anchors.")
if anchors - reviewed or source["error"] or not anchors:
limits.append(f"{source_id}: source reading is incomplete or unavailable.")
if set(document["passes"]) != set(CATEGORIES):
errors.append(f"{source_id}: record every proofreading pass.")
for category, review_pass in document["passes"].items():
if review_pass["status"] != "complete":
limits.append(f"{source_id}/{category}: {review_pass['status']}")
if review_pass["status"] == "complete" and not review_pass["note"].strip():
errors.append(
f"{source_id}/{category}: completed pass needs its findings or no-issue rationale."
)
if document["visual_review"]["status"] != "complete":
limits.append(f"{source_id}: visual review not complete.")
elif not document["visual_review"]["evidence"].strip():
errors.append(
f"{source_id}: completed visual review needs the inspected artifact/pages."
)
for name, mapping in document["maps"].items():
if not mapping["note"].strip():
errors.append(
f"{source_id}/{name}: explain the map's scope, absence or unfinished work."
)
for entry in mapping["entries"]:
check_citations(entry["citations"], source_id + "/" + name)
limits.extend(f"{source_id}: {limit}" for limit in document["limitations"])
ids = [finding["id"] for finding in audit["findings"]]
if len(ids) != len(set(ids)):
errors.append("Finding IDs must be unique.")
for finding in audit["findings"]:
check_citations(finding["citations"], finding["id"])
return {
"valid": not errors,
"complete": not errors and not limits,
"errors": errors,
"limitations": limits,
"coverage_basis": "Declared by the reviewing model; not proof of its attention or legal accuracy.",
}
def render_audit(run_dir: Path, audit_path: Path) -> Path:
"""Deliver findings, reference maps and explicit pass coverage as local HTML."""
audit = _load(audit_path)
validation = validate_audit(run_dir, audit)
target = run_dir / "proofreading.html"
if target.exists():
number = 1
while (run_dir / f"previous-{number}-proofreading.html").exists():
number += 1
target.rename(run_dir / f"previous-{number}-proofreading.html")
(run_dir / "proofreading-validation.json").write_text(
json.dumps(validation, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
)
if not validation["valid"]:
raise ValueError("Invalid audit: " + "; ".join(validation["errors"]))
lang = audit["context"].get("language", "it")
labels = _load(Path(__file__).with_name("legal_proofreading_labels.json"))[lang]
context_labels = _load(Path(__file__).with_name("legal_documents_labels.json"))[
lang
]["context_labels"]
esc = lambda value: html.escape(str(value), quote=True)
findings = sorted(audit["findings"], key=lambda f: SEVERITIES.index(f["severity"]))
rows = []
for finding in findings:
evidence = "<br>".join(
f"{esc(c['source_id'])} · {esc(c['anchor'])}<blockquote>{esc(c['quote'])}</blockquote>"
for c in finding["citations"]
)
rows.append(
"<tr>"
+ "".join(
f"<td>{cell}</td>"
for cell in (
esc(finding["id"]),
esc(labels["severities"][finding["severity"]]),
esc(labels["categories"][finding["category"]]),
esc(labels["kinds"][finding["kind"]]),
evidence,
esc(finding["issue"]) + "<p>" + esc(finding["reason"]) + "</p>",
esc(finding["fix"]),
)
)
+ "</tr>"
)
context = "".join(
f"<dt>{esc(context_labels[key])}</dt><dd>{esc('; '.join(value) if isinstance(value, list) else value)}</dd>"
for key, value in audit["context"].items()
if key in context_labels and value
)
sections = []
for source_id, document in audit["documents"].items():
pass_rows = "".join(
f"<tr><th>{esc(labels['categories'][category])}</th><td>{esc(labels['states'][entry['status']])}</td><td>{esc(entry['note'])}</td></tr>"
for category, entry in document["passes"].items()
)
maps = []
for name, mapping in document["maps"].items():
entries = "".join(
f"<li><strong>{esc(entry['label'])}</strong> {esc(entry['note'])}<ul>"
+ "".join(
f"<li>{esc(c['anchor'])}: {esc(c['quote'])}</li>"
for c in entry["citations"]
)
+ "</ul></li>"
for entry in mapping["entries"]
)
maps.append(
f"<h4>{esc(labels['maps'][name])}</h4><p>{esc(mapping['note'])}</p><ul>{entries}</ul>"
)
sections.append(
f"<section><h3>{esc(source_id)}</h3><table>{pass_rows}</table><p>{esc(document['visual_review']['evidence'])}</p>{''.join(maps)}</section>"
)
# Translate owned diagnostic messages only; never reinterpret authored notes.
display_limits = []
for limit in validation["limitations"]:
source_id, separator, message = limit.partition(": ")
if separator and source_id in audit["documents"]:
message = labels["limit_messages"].get(message, message)
limit = source_id + separator + message
display_limits.append(limit)
limits = "".join(f"<li>{esc(limit)}</li>" for limit in display_limits)
takeaways = "".join(f"<li>{esc(item)}</li>" for item in audit["takeaways"])
body = f"""<!doctype html><html lang="{lang}"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>{esc(labels['title'])}</title>
<style>body{{font:16px/1.6 'Instrument Sans',Arial,sans-serif;color:#172b4d;margin:40px auto;padding:0 24px;max-width:1200px}}h1,h2,h3{{line-height:1.2}}h1{{font-size:36px}}h2{{margin-top:40px}}table{{border-collapse:collapse;width:100%;font-size:14px}}th,td{{border:1px solid #ccd5df;text-align:left;vertical-align:top;padding:12px}}thead{{background:#edf3f8}}blockquote{{margin:8px 0;white-space:pre-wrap}}dt{{font-weight:bold}}dd{{margin:0 0 12px}}.table{{overflow:auto}}@media print{{body{{margin:0}}thead{{display:table-header-group}}tr{{break-inside:avoid}}}}</style>
<main><h1>{esc(labels['title'])}</h1><p>{esc(labels['complete'] if validation['complete'] else labels['partial'])}</p><p>{esc(labels['meaning'])}</p><ul>{takeaways}</ul>
<h2>{esc(labels['findings'])}</h2><div class="table"><table><thead><tr>{''.join('<th>'+esc(h)+'</th>' for h in labels['columns'])}</tr></thead><tbody>{''.join(rows)}</tbody></table></div>
<h2>{esc(labels['coverage'])}</h2>{''.join(sections)}<h2>{esc(labels['context'])}</h2><dl>{context}</dl><h2>{esc(labels['limits'])}</h2><ul>{limits}</ul>
<h2>{esc(labels['privacy_title'])}</h2><p>{esc(labels['privacy'])}</p></main></html>"""
target.write_text(body, encoding="utf-8")
return target
def main(argv: list[str] | None = None) -> int:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("command", choices=("scaffold", "render"))
parser.add_argument("--run-dir", type=Path, required=True)
parser.add_argument("--audit", type=Path)
args = parser.parse_args(argv)
try:
result = (
scaffold(args.run_dir)
if args.command == "scaffold"
else render_audit(
args.run_dir, args.audit or args.run_dir / "proofreading.json"
)
)
LOGGER.info("%s", result)
return 0
except (OSError, ValueError, KeyError, TypeError) as error:
LOGGER.error("%s", error)
return 2
if __name__ == "__main__":
logging.basicConfig(level=logging.INFO, format="%(message)s")
raise SystemExit(main())
SHA-256: 969fbdaa956e6d4feb36d93cfdab88a2fc05bf20357b576541c1f71158f37b5f