paratext-cli 0.2.0__tar.gz → 0.2.2__tar.gz

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paratext-cli
-Version: 0.2.0
+Version: 0.2.2
 Summary: Modular, project-based metadata extraction from digitised library/archive collections with a multimodal model
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -159,7 +159,9 @@ prompt version, keyed on the prompt's hash:
   `-r3`, …). The UI shows the two most recent rounds side by side and highlights
   what changed. The flag is needed because a run resumes on sample id: without
   it the existing extractions are already there, so the model is never called.
-  paratext stops and says so rather than resuming into a stale file.
+  paratext stops and says so rather than resuming into a stale file. On a small
+  collection, `re-extract = true` in `paratext.toml` makes it the default and
+  the loop needs no flag.
 - **Re-run the same prompt** (a resume, or a bigger `--limit`) → the current round
   is updated in place, keeping the annotations you've already made.
 

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/README.md

@@ -134,7 +134,9 @@ prompt version, keyed on the prompt's hash:
   `-r3`, …). The UI shows the two most recent rounds side by side and highlights
   what changed. The flag is needed because a run resumes on sample id: without
   it the existing extractions are already there, so the model is never called.
-  paratext stops and says so rather than resuming into a stale file.
+  paratext stops and says so rather than resuming into a stale file. On a small
+  collection, `re-extract = true` in `paratext.toml` makes it the default and
+  the loop needs no flag.
 - **Re-run the same prompt** (a resume, or a bigger `--limit`) → the current round
   is updated in place, keeping the annotations you've already made.
 

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/paratext.example.toml

@@ -19,6 +19,11 @@ output     = "output/cards.jsonl"
 # prompt no longer opens a new round to compare against. Leave it unset unless
 # that's what you want.
 # review-out = "review/cards"
+# Editing the prompt makes existing extractions stale, and paratext stops rather
+# than resuming into them. On a small collection where a re-run is cheap, this
+# discards them and calls the model again instead — the run/edit/re-run loop
+# then needs no flag. Leave it off for anything big or metered.
+# re-extract = true
 
 # Verbatim passthrough into the request body — for provider parameters paratext
 # doesn't model. Reasoning controls live here, and every provider spells them

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/pyproject.toml

@@ -3,7 +3,7 @@
 # the plain name on PyPI belongs to an unrelated project, so the distribution
 # carries the `-cli` suffix.
 name = "paratext-cli"
-version = "0.2.0"
+version = "0.2.2"
 description = "Modular, project-based metadata extraction from digitised library/archive collections with a multimodal model"
 readme = "README.md"
 # Core is pure-Python + numpy/pillow/pydantic. The [detector] extra needs

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/src/paratext/__init__.py

@@ -1,3 +1,3 @@
 """paratext — metadata extraction from digitised collections with a multimodal model."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/src/paratext/cli.py

@@ -61,6 +61,7 @@ HARDCODED_DEFAULTS: dict = {
     "review_port": DEFAULT_PORT,
     "no_structured": False,
     "skip_preflight": False,
+    "re_extract": False,
     "max_tokens": None,  # None → runner.DEFAULT_MAX_TOKENS, or the project's own
 }
 
@@ -214,7 +215,7 @@ def _do_extract(args: argparse.Namespace) -> None:
         energy=energy,
         max_tokens=getattr(args, "max_tokens", None),
         extra_body=config_extra_body(args.project),
-        re_extract=getattr(args, "re_extract", False),
+        re_extract=args.re_extract,
     )
 
 
@@ -675,9 +676,9 @@ def _add_extract_args(p: argparse.ArgumentParser) -> None:
     p.add_argument("--base-url", default=None, help="model endpoint base URL (OpenAI-compatible)")
     p.add_argument("--api-key", default=None, help="API key for the endpoint (often unused)")
     p.add_argument("--limit", type=int, default=None, help="Process at most N inputs")
-    p.add_argument("--re-extract", action="store_true",
-                   help="Discard existing extractions and call the model again "
-                        "(needed when the prompt or model has changed)")
+    p.add_argument("--re-extract", action="store_true", default=None,
+                   help="Discard existing extractions and call the model again when the "
+                        "prompt or model has changed (config re-extract, else stop and say so)")
     p.add_argument("--max-tokens", type=int, default=None, metavar="N",
                    help="Output-token ceiling per call (default: 8192; raise it for "
                         "models that reason before answering)")

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/src/paratext/config.py

@@ -62,6 +62,7 @@ RECOGNISED = (
     "limit",
     "no_structured",
     "skip_preflight",
+    "re_extract",
     "max_tokens",
 )
 
@@ -232,7 +233,7 @@ def coerce_paths(d: dict) -> dict:
     for key in ("limit", "review_port", "max_tokens"):
         if key in d and isinstance(d[key], str):
             d[key] = int(d[key])
-    for key in ("no_structured", "skip_preflight"):
+    for key in ("no_structured", "skip_preflight", "re_extract"):
         if key in d and isinstance(d[key], str):
             d[key] = d[key].lower() in ("1", "true", "yes", "on")
     return d

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/src/paratext/datasets.py

@@ -176,6 +176,55 @@ def load_view(dataset: dict, samples: list[dict]) -> dict:
     return synthesise_view(dataset, samples)
 
 
+def _model_fields(view: dict) -> list[dict]:
+    """The model-output field list from a view contract, key/label/type only."""
+    for panel in view.get("panels", []):
+        if panel.get("source") == "model_output":
+            return [
+                {k: f.get(k) for k in ("key", "label", "type")}
+                for f in panel.get("fields", [])
+            ]
+    return []
+
+
+def diff_fields(before: list[dict], after: list[dict]) -> dict:
+    """What changed between two rounds' field lists, keyed on field name."""
+    b = {f["key"]: f for f in before}
+    a = {f["key"]: f for f in after}
+    return {
+        "added": [a[k] for k in a if k not in b],
+        "removed": [b[k] for k in b if k not in a],
+        "retyped": [
+            {"key": k, "label": a[k].get("label"),
+             "from": b[k].get("type"), "to": a[k].get("type")}
+            for k in a
+            if k in b and a[k].get("type") != b[k].get("type")
+        ],
+    }
+
+
+def schema_history(datasets: list[dict]) -> list[dict]:
+    """Field list per round for one dataset family, oldest first, each carrying
+    what changed since the round before it (`changes` is None for the first)."""
+    rounds = []
+    for ds in sorted(datasets, key=lambda d: d.get("round") or 0):
+        vp = ds["dir"] / "view.json"
+        view = json.loads(vp.read_text()) if vp.is_file() else synthesise_view(
+            ds, load_samples(ds)
+        )
+        rounds.append({
+            "round": ds.get("round"),
+            "dataset": ds["name"],
+            "schema_version": view.get("schema_version"),
+            "fields": _model_fields(view),
+        })
+    prev = None
+    for r in rounds:
+        r["changes"] = diff_fields(prev["fields"], r["fields"]) if prev else None
+        prev = r
+    return rounds
+
+
 def review_stats(
     total: int, annotations: list[dict], gold_ids: set[str] | None = None
 ) -> dict:

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/src/paratext/extract.py

@@ -78,7 +78,9 @@ def _guard_stale_output(output: Path, header: dict, project: str, re_extract: bo
         f"Those records answer a different question, and resume would skip every\n"
         f"sample and call the model zero times. Either:\n"
         f"  paratext run -p {project} --re-extract           # redo them\n"
-        f"  paratext run -p {project} --output <new>.jsonl   # keep both"
+        f"  paratext run -p {project} --output <new>.jsonl   # keep both\n"
+        f"On a small, cheap collection you can make the first the default:\n"
+        f"  re-extract = true   under [project.{project}] in paratext.toml"
     )
 
 

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/src/paratext/review/server.py

@@ -29,6 +29,7 @@ from ..datasets import (
     load_view,
     resolve_dataset,
     review_stats,
+    schema_history,
 )
 from ..store import Store, default_db_path
 
@@ -126,6 +127,8 @@ class Handler(BaseHTTPRequestHandler):
                 return self._api_projects()
             if path == "/api/prompts":
                 return self._api_prompts(self._dataset(qs))
+            if path == "/api/schema":
+                return self._api_schema(self._dataset(qs))
             if path == "/api/export/fields":
                 return self._api_export_fields(self._dataset(qs), qs)
             if path in ("/api/export/marc", "/api/export/dc"):
@@ -299,6 +302,12 @@ class Handler(BaseHTTPRequestHandler):
             )
         self._json(rows)
 
+    def _api_schema(self, ds):
+        siblings = [d for d in discover_datasets(self.data_dir) if d["base"] == ds["base"]]
+        self._json(
+            {"dataset": ds["name"], "base": ds["base"], "rounds": schema_history(siblings)}
+        )
+
     def _api_prompts(self, ds):
         siblings = [d for d in discover_datasets(self.data_dir) if d["base"] == ds["base"]]
         groups: dict[str, dict] = {}

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/src/paratext/review/static/app.js

@@ -1047,15 +1047,110 @@ function renderPromptsPanel(prompts) {
   `;
 }
 
+
+// ── Fields panel ──────────────────────────────────────────────────────
+// The schema in the terms someone meeting one for the first time can read:
+// what the model is asked to fill in, and what changed since last round.
+// A table, not a +/- diff — the audience for this is learning what a field is.
+
+const TYPE_WORDS = {
+  string: "text",
+  integer: "whole number",
+  number: "number",
+  boolean: "yes / no",
+  array: "list",
+  object: "group",
+};
+
+const typeWord = (t) => TYPE_WORDS[t] ?? (t ?? "text");
+
+function renderFieldsPanel(rounds) {
+  if (!rounds || !rounds.length) return "";
+  const latest = rounds[rounds.length - 1];
+  if (!latest.fields.length) return "";
+
+  // Where each field entered, so an unchanged row can still say "since r1".
+  const firstSeen = new Map();
+  for (const r of rounds) {
+    for (const f of r.fields) if (!firstSeen.has(f.key)) firstSeen.set(f.key, r.round);
+  }
+  const c = latest.changes ?? { added: [], removed: [], retyped: [] };
+  const addedKeys = new Set(c.added.map((f) => f.key));
+  const retyped = new Map(c.retyped.map((f) => [f.key, f]));
+
+  const multi = rounds.length > 1;
+  const status = (f) => {
+    if (!multi) return "";
+    if (addedKeys.has(f.key))
+      return `<span class="ok">new this round</span>`;
+    const rt = retyped.get(f.key);
+    if (rt)
+      return `<span class="warn">was ${escapeHtml(typeWord(rt.from))}</span>`;
+    const seen = firstSeen.get(f.key);
+    return `<span class="text-light">since round ${seen ?? 1}</span>`;
+  };
+
+  const rows = latest.fields
+    .map(
+      (f) => `<tr>
+        <td><code>${escapeHtml(f.key)}</code></td>
+        <td>${escapeHtml(f.label ?? f.key)}</td>
+        <td>${escapeHtml(typeWord(f.type))}</td>
+        <td>${status(f)}</td>
+      </tr>`,
+    )
+    .join("");
+
+  const gone = (c.removed ?? [])
+    .map(
+      (f) =>
+        `<tr class="text-light"><td><code>${escapeHtml(f.key)}</code></td>
+         <td>${escapeHtml(f.label ?? f.key)}</td>
+         <td>${escapeHtml(typeWord(f.type))}</td>
+         <td class="bad">dropped this round</td></tr>`,
+    )
+    .join("");
+
+  const changed =
+    (c.added?.length ?? 0) + (c.removed?.length ?? 0) + (c.retyped?.length ?? 0);
+  const summary =
+    rounds.length < 2
+      ? `${latest.fields.length} field${latest.fields.length === 1 ? "" : "s"}`
+      : changed === 0
+        ? `${latest.fields.length} fields · unchanged since round ${
+            rounds[rounds.length - 2].round
+          }`
+        : `${latest.fields.length} fields · ${changed} change${
+            changed === 1 ? "" : "s"
+          } this round`;
+
+  return `<details style="margin:1rem 0;" ${changed ? "open" : ""}>
+    <summary><strong>Fields</strong> <small style="color:var(--muted-foreground);">(${escapeHtml(
+      summary,
+    )})</small></summary>
+    <p class="text-light mt-2" style="font-size:.875rem;">
+      One row per piece of metadata the model is asked to produce for every card.
+      Together they are the <em>schema</em>. Change them in
+      <code>schema.py</code>; describe them in <code>prompt.md</code>.
+    </p>
+    <div class="table"><table>
+      <thead><tr><th>Field</th><th>Shown as</th><th>Holds</th><th></th></tr></thead>
+      <tbody>${rows}${gone}</tbody>
+    </table></div>
+  </details>`;
+}
+
 async function renderStats() {
-  const [statsRes, tableRes, promptsRes] = await Promise.all([
+  const [statsRes, tableRes, promptsRes, schemaRes] = await Promise.all([
     fetch(api("api/stats")),
     fetch(api("api/table")),
     fetch(api("api/prompts")),
+    fetch(api("api/schema")),
   ]);
   const s = await statsRes.json();
   const rows = await tableRes.json();
   const promptsData = await promptsRes.json();
+  const schemaData = await schemaRes.json();
   document.getElementById("progress").textContent = "";
 
   const badge = (v) => {
@@ -1104,6 +1199,8 @@ async function renderStats() {
         <a href="#/eval">build →</a>)</small></dd></div>
     </dl>
 
+    ${renderFieldsPanel(schemaData.rounds ?? [])}
+
     ${renderPromptsPanel(promptsData.prompts ?? [])}
 
     <div class="controls">

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/tests/test_config.py

@@ -162,3 +162,11 @@ def test_max_tokens_from_the_environment(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     monkeypatch.setenv("PARATEXT_MAX_TOKENS", "16384")
     assert cfg.coerce_paths(cfg.load_defaults(None))["max_tokens"] == 16384
+
+
+def test_re_extract_is_recognised_and_coerced():
+    from paratext.config import RECOGNISED, coerce_paths
+
+    assert "re_extract" in RECOGNISED
+    assert coerce_paths({"re_extract": "true"})["re_extract"] is True
+    assert coerce_paths({"re_extract": "no"})["re_extract"] is False

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/tests/test_rounds.py

@@ -130,3 +130,65 @@ def test_changed_prompt_reports_why(tmp_path, monkeypatch):
     _mk_round(review, "demo", 1, "hashA", model="m")
     _, _, reuse, reason = cli._resolve_round("demo", "hashB", None, model="m")
     assert reuse is False and reason == "the prompt changed"
+
+
+def _view(fields, version="v1"):
+    return {
+        "contract_version": 1,
+        "schema": "cards",
+        "schema_version": version,
+        "panels": [{"source": "model_output", "title": "Model output", "fields": fields}],
+    }
+
+
+def _round_dir(tmp_path, name, n, fields):
+    import json
+
+    d = tmp_path / name
+    d.mkdir()
+    (d / "view.json").write_text(json.dumps(_view(fields)))
+    (d / "samples.json").write_text("[]")
+    return {"name": name, "base": "cards", "round": n, "dir": d}
+
+
+def test_diff_fields_reports_added_removed_and_retyped():
+    from paratext.datasets import diff_fields
+
+    before = [{"key": "a", "label": "A", "type": "string"},
+              {"key": "b", "label": "B", "type": "string"}]
+    after = [{"key": "a", "label": "A", "type": "integer"},
+             {"key": "c", "label": "C", "type": "string"}]
+    d = diff_fields(before, after)
+    assert [f["key"] for f in d["added"]] == ["c"]
+    assert [f["key"] for f in d["removed"]] == ["b"]
+    assert d["retyped"] == [{"key": "a", "label": "A", "from": "string", "to": "integer"}]
+
+
+def test_diff_fields_is_empty_when_nothing_moved():
+    from paratext.datasets import diff_fields
+
+    fields = [{"key": "a", "label": "A", "type": "string"}]
+    assert diff_fields(fields, list(fields)) == {"added": [], "removed": [], "retyped": []}
+
+
+def test_schema_history_orders_rounds_and_diffs_each_against_the_last(tmp_path):
+    from paratext.datasets import schema_history
+
+    r1 = _round_dir(tmp_path, "cards-r1", 1, [{"key": "a", "label": "A", "type": "string"}])
+    r2 = _round_dir(tmp_path, "cards-r2", 2, [
+        {"key": "a", "label": "A", "type": "string"},
+        {"key": "b", "label": "B", "type": "integer"},
+    ])
+    # Out of order in, oldest first out.
+    hist = schema_history([r2, r1])
+    assert [r["round"] for r in hist] == [1, 2]
+    assert hist[0]["changes"] is None  # nothing to compare the first round to
+    assert [f["key"] for f in hist[1]["changes"]["added"]] == ["b"]
+
+
+def test_schema_history_of_a_single_round(tmp_path):
+    from paratext.datasets import schema_history
+
+    r1 = _round_dir(tmp_path, "cards-r1", 1, [{"key": "a", "label": "A", "type": "string"}])
+    hist = schema_history([r1])
+    assert len(hist) == 1 and hist[0]["changes"] is None

{paratext_cli-0.2.0 → paratext_cli-0.2.2}/uv.lock

@@ -803,7 +803,7 @@ wheels = [
 
 [[package]]
 name = "paratext-cli"
-version = "0.2.0"
+version = "0.2.2"
 source = { editable = "." }
 dependencies = [
     { name = "huggingface-hub" },