lorebase-cli 0.2.3__tar.gz → 0.3.0__tar.gz

{lorebase_cli-0.2.3 → lorebase_cli-0.3.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: lorebase-cli
-Version: 0.2.3
+Version: 0.3.0
 Summary: Lorebase CLI
 Requires-Python: >=3.12
-Requires-Dist: lorebase-client<0.3,>=0.2
+Requires-Dist: lorebase-client<0.4,>=0.3
 Requires-Dist: typer>=0.27
 Provides-Extra: linkml
 Requires-Dist: pyyaml>=6.0; extra == 'linkml'

{lorebase_cli-0.2.3 → lorebase_cli-0.3.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "lorebase-cli"
-version = "0.2.3"
+version = "0.3.0"
 description = "Lorebase CLI"
 requires-python = ">=3.12"
 dependencies = [
-  "lorebase-client>=0.2,<0.3",
+  "lorebase-client>=0.3,<0.4",
   # Command line framework with shell completion.
   "typer>=0.27",
 ]

{lorebase_cli-0.2.3 → lorebase_cli-0.3.0}/src/lorebase_cli/__init__.py

@@ -1,3 +1,3 @@
 """lorebase CLI: command line client of a Lorebase Keeper."""
 
-__version__ = "0.2.3"
+__version__ = "0.3.0"

{lorebase_cli-0.2.3 → lorebase_cli-0.3.0}/src/lorebase_cli/commands/agents.py

@@ -57,6 +57,20 @@ def context_command(
         list[str] | None,
         typer.Option("--relation", help="Follow only this Relation. Repeatable."),
     ] = None,
+    trait: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--trait",
+            help="Limit --search and --query seeds and neighbors to the Kinds implementing "
+            "this Trait. Repeatable.",
+        ),
+    ] = None,
+    lens: Annotated[
+        str | None,
+        typer.Option(
+            "--lens", help="Apply this lens: its Relations, depth, budget and Kinds are defaults."
+        ),
+    ] = None,
     domain: DomainOpt = None,
     branch: BranchOpt = None,
     at: AtOpt = None,
@@ -80,6 +94,8 @@ def context_command(
         budget_tokens=budget,
         depth=depth,
         relations=relation or None,
+        traits=trait or None,
+        lens=lens,
     )
     agents = app.client().agents
     name = app.domain(domain)

{lorebase_cli-0.2.3 → lorebase_cli-0.3.0}/src/lorebase_cli/commands/data.py

@@ -1,9 +1,10 @@
-"""`import`, `record`, `query` and `search`: loading and reading Records and Links."""
+"""`import`, `record`, `query`, `search` and `resolve`: loading and reading Records and Links."""
 
 from __future__ import annotations
 
 import json
 import sys
+from collections.abc import Iterator
 from pathlib import Path
 from typing import Annotated, Any
 
@@ -638,15 +639,39 @@ def query_command(
         body["at"] = at
     client = app.client()
     domain_id = app.domain(domain)
+    first = client.records.query(domain_id, body)
     if body.get("aggregate"):
-        result = client.records.query(domain_id, body)
-        app.out.emit(result, lambda: _print_aggregate(app, result))
+        app.out.emit(first, lambda: _print_aggregate(app, first))
+        _print_coverage(app, first.coverage)
         return
-    items, more = app.take(client.records.iterate_query(domain_id, body), limit, everything)
+
+    def pages() -> Iterator[m.RecordItem]:
+        page = first
+        while True:
+            yield from page.items
+            if page.next_cursor is None:
+                return
+            # Only the request's own members: a Keeper older than the coverage block refuses
+            # unknown ones, so later pages repeat the first one's body with the cursor.
+            following = {**body, "cursor": page.next_cursor}
+            page = client.records.query(domain_id, following)
+
+    items, more = app.take(pages(), limit, everything)
     selected = [str(s) for s in body.get("select") or [] if s not in ("key", "title")]
     _print_records(app, items, selected)
     if more:
         app.note_truncated(len(items))
+    _print_coverage(app, first.coverage)
+
+
+def _print_coverage(app: AppContext, coverage: m.Coverage | None) -> None:
+    """The coverage notes (design 8.11), one line each, besides the results."""
+    if coverage is None:
+        return
+    for note in coverage.notes:
+        app.out.info(note)
+    if coverage.omitted:
+        app.out.info(f"coverage: {coverage.omitted}")
 
 
 def _query_body(text: str) -> dict[str, Any]:
@@ -691,6 +716,18 @@ def search_command(
     kind: Annotated[
         list[str] | None, typer.Option("--kind", help="Only this Kind. Repeatable.")
     ] = None,
+    trait: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--trait", help="Only the Kinds that implement this Trait. Repeatable; adds to --kind."
+        ),
+    ] = None,
+    lens: Annotated[
+        str | None,
+        typer.Option(
+            "--lens", help="Search the Kinds and Traits of this lens unless --kind or --trait."
+        ),
+    ] = None,
     mode: Annotated[
         str | None,
         typer.Option(
@@ -719,6 +756,8 @@ def search_command(
         {
             "q": text,
             "kinds": kind,
+            "traits": trait,
+            "lens": lens,
             "mode": mode,
             "query_vector": vector,
             "branch": app.branch(branch),
@@ -740,3 +779,78 @@ def search_command(
             ],
         ),
     )
+    if result.semantic_truncated:
+        app.out.info("the vector list is short: the index scan stopped at its bound; narrow --kind")
+
+
+def resolve_command(
+    ctx: typer.Context,
+    text: Annotated[str, typer.Argument(help="Words to ground, e.g. a question.", metavar="TEXT")],
+    kind: Annotated[
+        list[str] | None, typer.Option("--kind", help="Only look in this Kind. Repeatable.")
+    ] = None,
+    level: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--level",
+            help="exact, synonym, trigram or embedding (default: those the server enables). "
+            "Repeatable.",
+        ),
+    ] = None,
+    vector_file: Annotated[
+        str | None,
+        typer.Option(
+            "--vector-file",
+            help="Embedding of TEXT, enabling the embedding level when nothing else matched: a "
+            "JSON array, or the output of `lorebase-inference embed`; `-` reads standard input.",
+        ),
+    ] = None,
+    domain: DomainOpt = None,
+    branch: BranchOpt = None,
+    at: AtOpt = None,
+    limit: LimitOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Ground the words of a text in Kinds, Attributes and stored values (with `where` fragments
+    in --json); it never runs a query."""
+    app = app_of(ctx, json_out)
+    vector = None if vector_file is None else query_vector(vector_file)
+    request = m.ResolveRequest.model_validate(
+        {
+            "text": text,
+            "kinds": kind,
+            "levels": level,
+            "query_vector": vector,
+            "branch": app.branch(branch),
+            "at": at,
+            "limit": limit or app.settings.list_limit,
+        }
+    )
+    result = app.client().records.resolve(app.domain(domain), request)
+
+    def rows() -> list[dict[str, Any]]:
+        return [
+            {**c.model_dump(), "ref": ".".join(filter(None, [c.kind, c.attribute]))}
+            for c in result.candidates
+        ]
+
+    app.out.emit(
+        result,
+        lambda: app.out.table(
+            rows(),
+            [
+                Column("target", "target"),
+                Column("kind.attribute", "ref"),
+                Column("values", "values"),
+                Column("level", "level"),
+                Column("score", "score", lambda v: f"{v:.3f}"),
+                Column("records", "records"),
+                Column("matched", "matched"),
+            ],
+        ),
+    )
+    for skipped in result.skipped:
+        app.out.info(f"{skipped.level} skipped: {skipped.reason}")
+    if result.unmatched:
+        app.out.info("unmatched: " + ", ".join(result.unmatched))
+    _print_coverage(app, result.coverage)

{lorebase_cli-0.2.3 → lorebase_cli-0.3.0}/src/lorebase_cli/commands/documents.py

@@ -1,4 +1,6 @@
-"""`documents upload|list|get|text`: documents stored for extraction by Scribe."""
+"""`documents upload|list|versions|get|text|retire|purge`: documents stored for extraction by
+Scribe. Uploads with `--key` are versions of one source; retiring stops further extraction and
+purging irreversibly erases the content."""
 
 from __future__ import annotations
 
@@ -10,7 +12,7 @@ import typer
 from lorebase_cli.context import AppContext, app_of
 from lorebase_cli.failures import CliError
 from lorebase_cli.options import AllOpt, DomainOpt, JsonOpt, LimitOpt
-from lorebase_cli.output import Column, short_id
+from lorebase_cli.output import Column
 from lorebase_client import models as m
 
 documents_app = typer.Typer(
@@ -22,11 +24,20 @@ DOCUMENT_COLUMNS = [
     Column("filename", "filename"),
     Column("type", "media_type"),
     Column("size", "size"),
-    Column("sha256", "sha256", short_id),
+    Column("key", "source_key"),
+    Column("v", "version"),
+    Column("status", "status"),
     Column("created", "created_at"),
 ]
 
 
+KeyOpt = Annotated[
+    str | None,
+    typer.Option("--key", help="Source key (path, URL or external id): the document's identity."),
+]
+ReasonOpt = Annotated[str, typer.Option("--reason", help="Why, recorded in the audit.")]
+
+
 def _tiers(text: str | None) -> list[int] | None:
     """Extraction tiers from a comma separated list such as `0,1`."""
     if text is None:
@@ -44,9 +55,23 @@ def _document_pairs(found: m.Document) -> list[tuple[str, Any]]:
         ("media type", found.media_type),
         ("size", found.size),
         ("sha256", found.sha256),
+        ("source key", found.source_key),
+        ("version", found.version),
+        ("replaces", found.replaces),
+        ("status", found.status),
         ("text parsed", found.text_sha256 is not None),
         ("created", found.created_at),
         ("created by", found.created_by),
+        *(
+            [("retired", f"{found.retired_at} by {found.retired_by}")]
+            if found.retired_at is not None
+            else []
+        ),
+        *(
+            [("purged", f"{found.purged_at} by {found.purged_by}")]
+            if found.purged_at is not None
+            else []
+        ),
     ]
 
 
@@ -67,10 +92,14 @@ def documents_upload(
     tiers: Annotated[
         str | None, typer.Option("--tiers", help="Extraction tiers, comma separated (e.g. 0,1).")
     ] = None,
+    key: KeyOpt = None,
     domain: DomainOpt = None,
     json_out: JsonOpt = False,
 ) -> None:
-    """Upload a document (PATH, or --url) and queue its extraction."""
+    """Upload a document (PATH, or --url) and queue its extraction.
+
+    With --key, new bytes become a new version of the key's document.
+    """
     app = app_of(ctx, json_out)
     name = app.domain(domain)
     extract = False if no_extract else None
@@ -78,11 +107,11 @@ def documents_upload(
     documents = app.client().documents
     if path is not None and url is None:
         try:
-            uploaded = documents.upload(name, path, extract=extract, tiers=wanted)
+            uploaded = documents.upload(name, path, extract=extract, tiers=wanted, source_key=key)
         except OSError as error:
             raise CliError(f"cannot read {path}: {error.strerror or error}") from error
     elif url is not None and path is None:
-        uploaded = documents.upload_url(name, url, extract=extract, tiers=wanted)
+        uploaded = documents.upload_url(name, url, extract=extract, tiers=wanted, source_key=key)
     else:
         raise CliError("give PATH or --url")
     app.out.emit(
@@ -92,6 +121,7 @@ def documents_upload(
                 *_document_pairs(uploaded.document),
                 ("duplicate", uploaded.duplicate),
                 ("job", uploaded.job_id),
+                ("check job", uploaded.check_job_id),
             ]
         ),
     )
@@ -100,6 +130,9 @@ def documents_upload(
 @documents_app.command("list")
 def documents_list(
     ctx: typer.Context,
+    key: Annotated[
+        str | None, typer.Option("--key", help="Only the versions of this source key.")
+    ] = None,
     domain: DomainOpt = None,
     limit: LimitOpt = None,
     everything: AllOpt = False,
@@ -107,7 +140,26 @@ def documents_list(
 ) -> None:
     """List the documents of a Domain, newest first."""
     app = app_of(ctx, json_out)
-    items, more = app.take(app.client().documents.iterate(app.domain(domain)), limit, everything)
+    stream = app.client().documents.iterate(app.domain(domain), source_key=key)
+    items, more = app.take(stream, limit, everything)
+    app.out.emit(items, lambda: app.out.table([d.model_dump() for d in items], DOCUMENT_COLUMNS))
+    if more:
+        app.note_truncated(len(items))
+
+
+@documents_app.command("versions")
+def documents_versions(
+    ctx: typer.Context,
+    document_id: Annotated[str, typer.Argument(help="Document id.", metavar="ID")],
+    domain: DomainOpt = None,
+    limit: LimitOpt = None,
+    everything: AllOpt = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """List the versions of a document's source key, newest first."""
+    app = app_of(ctx, json_out)
+    stream = app.client().documents.iterate_versions(app.domain(domain), document_id)
+    items, more = app.take(stream, limit, everything)
     app.out.emit(items, lambda: app.out.table([d.model_dump() for d in items], DOCUMENT_COLUMNS))
     if more:
         app.note_truncated(len(items))
@@ -159,3 +211,56 @@ def documents_text(
             app.out.info(f"text cut at {len(found.text)} of {found.length} characters")
 
     app.out.emit(found, human)
+
+
+@documents_app.command("retire")
+def documents_retire(
+    ctx: typer.Context,
+    document_id: Annotated[str, typer.Argument(help="Document id.", metavar="ID")],
+    reason: ReasonOpt,
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Retire a document: it is never extracted again and its evidence is re-checked."""
+    app = app_of(ctx, json_out)
+    done = app.client().documents.retire(app.domain(domain), document_id, reason=reason)
+    app.out.emit(
+        done,
+        lambda: app.out.pairs([*_document_pairs(done.document), ("check job", done.job_id)]),
+    )
+
+
+@documents_app.command("purge")
+def documents_purge(
+    ctx: typer.Context,
+    document_id: Annotated[str, typer.Argument(help="Document id.", metavar="ID")],
+    reason: ReasonOpt,
+    confirm: Annotated[
+        str, typer.Option("--confirm", help="The document id again: the purge is irreversible.")
+    ],
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Irreversibly erase a document's bytes, text, chunks and evidence quotes."""
+    if confirm != document_id:
+        raise CliError(f"--confirm must repeat the document id {document_id!r}")
+    app = app_of(ctx, json_out)
+    done = app.client().documents.purge(
+        app.domain(domain), document_id, reason=reason, confirm=confirm
+    )
+    app.out.emit(
+        done,
+        lambda: app.out.pairs(
+            [
+                *_document_pairs(done.document),
+                ("check job", done.job_id),
+                ("blob deleted", done.blob_deleted),
+                ("text deleted", done.text_deleted),
+                ("chunks", done.chunks),
+                ("cache entries", done.cache_entries),
+                ("items erased", done.items),
+                ("candidates erased", done.candidates),
+                ("suggestions erased", done.suggestions),
+            ]
+        ),
+    )

{lorebase_cli-0.2.3 → lorebase_cli-0.3.0}/src/lorebase_cli/commands/proposals.py

@@ -9,7 +9,7 @@ import typer
 from lorebase_cli.commands.data import json_argument
 from lorebase_cli.context import AppContext, app_of
 from lorebase_cli.failures import CliError
-from lorebase_cli.options import AllOpt, DomainOpt, JsonOpt, LimitOpt
+from lorebase_cli.options import AllOpt, DomainOpt, JsonOpt, LimitOpt, MineOpt
 from lorebase_cli.output import Column, short_id
 from lorebase_client import models as m
 
@@ -26,6 +26,8 @@ PROPOSAL_COLUMNS = [
     Column("target", "target_ref"),
     Column("status", "status"),
     Column("author", "author"),
+    Column("stewards", "steward_roles"),
+    Column("assignees", "assignees"),
     Column("created", "created_at"),
 ]
 CONFLICT_COLUMNS = [
@@ -111,6 +113,7 @@ def proposal_list(
     author: Annotated[
         str | None, typer.Option("--author", help="Only Proposals by this principal.")
     ] = None,
+    mine: MineOpt = False,
     domain: DomainOpt = None,
     limit: LimitOpt = None,
     everything: AllOpt = False,
@@ -125,6 +128,7 @@ def proposal_list(
             source=source,
             target=target,
             author=author,
+            assigned="me" if mine else None,
         ),
         limit,
         everything,

lorebase_cli-0.3.0/src/lorebase_cli/commands/reconcile.py

@@ -0,0 +1,233 @@
+"""`reconcile list|show|resolve|dismiss|reopen`: the reconciliation queue."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, cast, get_args
+
+import typer
+
+from lorebase_cli.commands.data import json_argument
+from lorebase_cli.context import AppContext, app_of
+from lorebase_cli.failures import CliError
+from lorebase_cli.options import AllOpt, BranchOpt, DomainOpt, JsonOpt, LimitOpt, MineOpt
+from lorebase_cli.output import Column
+from lorebase_client import models as m
+
+reconcile_app = typer.Typer(
+    help="Review contradictions and duplicates between Sources.", no_args_is_help=True
+)
+
+CandidateArg = Annotated[str, typer.Argument(help="Candidate id.", metavar="ID")]
+ReasonOpt = Annotated[str, typer.Option("--reason", "-r", help="Why; kept in the audit log.")]
+
+CANDIDATE_COLUMNS = [
+    Column("id", "id"),
+    Column("type", "type"),
+    Column("status", "status"),
+    Column("kind", "kind"),
+    Column("keys", "keys", lambda keys: ", ".join(keys)),
+    Column("attribute", "attribute"),
+    Column("claims", "claim_count"),
+    Column("stewards", "steward_roles"),
+    Column("assignees", "assignees"),
+    Column("created", "created_at"),
+]
+
+
+def _show_candidate(app: AppContext, found: m.ReconciliationCandidate) -> None:
+    pairs: list[tuple[str, Any]] = [
+        ("candidate", found.id),
+        ("branch", found.branch),
+        ("type", found.type),
+        ("status", found.status),
+        ("kind", found.kind),
+        ("keys", found.keys),
+        ("attribute", found.attribute),
+        (
+            "claims",
+            [
+                f"{c.claim_id}: {c.value!r}" + (f" ({c.source})" if c.source else "")
+                for c in found.claims
+            ],
+        ),
+        ("claim count", found.claim_count),
+        ("proposal", found.proposal_id),
+        ("decided by", found.decided_by),
+        ("decided at", found.decided_at),
+        ("created", found.created_at),
+        ("updated", found.updated_at),
+    ]
+    app.out.pairs(pairs)
+
+
+def _show_decision(app: AppContext, decided: m.ReconciliationDecision) -> None:
+    app.out.pairs(
+        [
+            ("candidate", decided.candidate.id),
+            ("status", decided.status),
+            ("claim", decided.claim_id),
+            ("branch", decided.branch),
+            ("revision", decided.revision),
+            ("proposal", decided.proposal),
+            ("detail", decided.detail),
+        ]
+    )
+
+
+def _checked(value: str | None, allowed: Any, option: str) -> str | None:
+    """`value` checked against the members of a Literal type."""
+    if value is not None and value not in get_args(allowed):
+        raise CliError(f"{option}: unknown {value!r}, use {', '.join(get_args(allowed))}")
+    return value
+
+
+@reconcile_app.command("list")
+def reconcile_list(
+    ctx: typer.Context,
+    candidate_type: Annotated[
+        str | None,
+        typer.Option("--type", help="duplicate, contradiction, superseded or stale."),
+    ] = None,
+    status: Annotated[
+        str | None,
+        typer.Option("--status", help="open, resolved, dismissed or obsolete (default: all)."),
+    ] = None,
+    kind: Annotated[str | None, typer.Option("--kind", help="Only this Kind (api name).")] = None,
+    attribute: Annotated[
+        str | None,
+        typer.Option("--attribute", help="Only this Attribute (api name; needs --kind)."),
+    ] = None,
+    source: Annotated[
+        str | None,
+        typer.Option("--source", help="Only candidates with a claim of this Source identity."),
+    ] = None,
+    mine: MineOpt = False,
+    domain: DomainOpt = None,
+    branch: BranchOpt = None,
+    limit: LimitOpt = None,
+    everything: AllOpt = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """List the candidates of a branch, newest first."""
+    chosen_type = _checked(candidate_type, m.CandidateType, "--type")
+    chosen_status = _checked(status, m.CandidateStatus, "--status")
+    app = app_of(ctx, json_out)
+    items, more = app.take(
+        app.client().reconciliation.iterate(
+            app.domain(domain),
+            branch=app.branch(branch),
+            type=cast("m.CandidateType | None", chosen_type),
+            status=cast("m.CandidateStatus | None", chosen_status),
+            kind=kind,
+            attribute=attribute,
+            source=source,
+            assigned="me" if mine else None,
+        ),
+        limit,
+        everything,
+    )
+    app.out.emit(items, lambda: app.out.table([c.model_dump() for c in items], CANDIDATE_COLUMNS))
+    if more:
+        app.note_truncated(len(items))
+
+
+@reconcile_app.command("show")
+def reconcile_show(
+    ctx: typer.Context,
+    candidate_id: CandidateArg,
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Show a candidate with its claims and last decision."""
+    app = app_of(ctx, json_out)
+    found = app.client().reconciliation.get(app.domain(domain), candidate_id)
+    app.out.emit(found, lambda: _show_candidate(app, found))
+
+
+@reconcile_app.command("resolve")
+def reconcile_resolve(
+    ctx: typer.Context,
+    candidate_id: CandidateArg,
+    choice: Annotated[
+        str, typer.Option("--choice", help="claim, keep_current, custom, policy or merge.")
+    ],
+    reason: ReasonOpt,
+    claim: Annotated[
+        str | None, typer.Option("--claim", help="Claim id to take (choice `claim`).")
+    ] = None,
+    value: Annotated[
+        str | None,
+        typer.Option("--value", help="Value of a `custom` choice: inline JSON, @file or -."),
+    ] = None,
+    policy: Annotated[
+        str | None,
+        typer.Option(
+            "--policy",
+            help="authority, newest_wins, prefer_current or prefer_incoming (choice `policy`).",
+        ),
+    ] = None,
+    survivor: Annotated[
+        str | None, typer.Option("--survivor", help="Key of the Record that stays (`merge`).")
+    ] = None,
+    values: Annotated[
+        str | None,
+        typer.Option(
+            "--values",
+            help="Values to set on the survivor, by Attribute api name (`merge`): "
+            "a JSON object, inline, @file or -.",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool, typer.Option("--dry-run", help="Report the outcome without writing.")
+    ] = False,
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Decide a candidate; a write that needs review opens a Proposal."""
+    chosen = _checked(choice, m.ReconcileChoice, "--choice")
+    chosen_policy = _checked(policy, m.ReconcilePolicy, "--policy")
+    parsed = None if values is None else json_argument(values)
+    if parsed is not None and not isinstance(parsed, dict):
+        raise CliError("--values is a JSON object")
+    app = app_of(ctx, json_out)
+    decided = app.client().reconciliation.resolve(
+        app.domain(domain),
+        candidate_id,
+        cast("m.ReconcileChoice", chosen),
+        reason=reason,
+        claim_id=claim,
+        value=None if value is None else json_argument(value),
+        policy=cast("m.ReconcilePolicy | None", chosen_policy),
+        survivor=survivor,
+        values=parsed,
+        dry_run=dry_run,
+    )
+    app.out.emit(decided, lambda: _show_decision(app, decided))
+
+
+@reconcile_app.command("dismiss")
+def reconcile_dismiss(
+    ctx: typer.Context,
+    candidate_id: CandidateArg,
+    reason: ReasonOpt,
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Dismiss a candidate: the difference is accepted as it is."""
+    app = app_of(ctx, json_out)
+    decided = app.client().reconciliation.dismiss(app.domain(domain), candidate_id, reason=reason)
+    app.out.emit(decided, lambda: _show_decision(app, decided))
+
+
+@reconcile_app.command("reopen")
+def reconcile_reopen(
+    ctx: typer.Context,
+    candidate_id: CandidateArg,
+    reason: ReasonOpt,
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Reopen a dismissed candidate."""
+    app = app_of(ctx, json_out)
+    decided = app.client().reconciliation.reopen(app.domain(domain), candidate_id, reason=reason)
+    app.out.emit(decided, lambda: _show_decision(app, decided))

{lorebase_cli-0.2.3 → lorebase_cli-0.3.0}/src/lorebase_cli/main.py

@@ -20,6 +20,7 @@ from lorebase_cli.commands import (
     domains,
     history,
     proposals,
+    reconcile,
     schema,
     sources,
     trace,
@@ -139,11 +140,13 @@ app.add_typer(admin.admin_app, name="admin")
 app.add_typer(audit.audit_app, name="audit")
 app.add_typer(trace.trace_app, name="trace")
 app.add_typer(proposals.proposal_app, name="proposal")
+app.add_typer(reconcile.reconcile_app, name="reconcile")
 app.add_typer(sources.sources_app, name="sources")
 app.add_typer(documents.documents_app, name="documents")
 app.command("whoami")(domains.whoami)
 app.command("query")(data.query_command)
 app.command("search")(data.search_command)
+app.command("resolve")(data.resolve_command)
 app.command("log")(history.log_command)
 app.command("diff")(history.diff_command)
 app.command("context")(agents.context_command)

{lorebase_cli-0.2.3 → lorebase_cli-0.3.0}/src/lorebase_cli/options.py

@@ -54,3 +54,6 @@ LimitOpt = Annotated[
     typer.Option("--limit", "-n", min=1, help="Most items to print (default: list_limit setting)."),
 ]
 AllOpt = Annotated[bool, typer.Option("--all", help="Print every item, however many.")]
+MineOpt = Annotated[
+    bool, typer.Option("--mine", help="Only items assigned to you through a steward role.")
+]

{lorebase_cli-0.2.3 → lorebase_cli-0.3.0}/tests/test_commands.py

@@ -160,7 +160,7 @@ def test_no_arguments_prints_help() -> None:
 def test_version() -> None:
     result = run("--version")
     assert result.exit_code == 0
-    assert result.stdout.startswith("lorebase 0.2.3")
+    assert result.stdout.startswith("lorebase 0.3.0")
 
 
 @pytest.mark.parametrize(
@@ -1046,6 +1046,66 @@ def test_search_with_a_query_vector(http: respx.MockRouter, tmp_path: Path) -> N
     assert "JSON array of numbers" in result.output
 
 
+def test_resolve(http: respx.MockRouter, tmp_path: Path) -> None:
+    route = http.post("/domains/supply/resolve").respond(
+        200,
+        json={
+            "revision": REV,
+            "served_from": "materialized",
+            "candidates": [
+                {
+                    "target": "value",
+                    "kind": "Part",
+                    "attribute": "category",
+                    "values": ["bearing", "cuscinetto"],
+                    "predicate": {"attr": "category", "op": "in", "value": ["bearing"]},
+                    "score": 0.875,
+                    "level": "synonym",
+                    "matched": "bearings",
+                    "records": 12,
+                },
+                {"target": "kind", "kind": "Part", "score": 1, "level": "exact", "matched": "part"},
+            ],
+            "unmatched": ["the"],
+            "skipped": [{"level": "embedding", "reason": "no query vector"}],
+        },
+    )
+    result = run("resolve", "the bearings", "--kind", "Part", "--level", "exact", "-d", "supply")
+    assert result.exit_code == 0
+    assert result.stdout.splitlines()[0].split() == [
+        "target",
+        "kind.attribute",
+        "values",
+        "level",
+        "score",
+        "records",
+        "matched",
+    ]
+    assert "Part.category" in result.stdout
+    assert "bearing, cuscinetto" in result.stdout
+    assert "0.875" in result.stdout
+    assert "embedding skipped: no query vector" in result.output
+    assert "unmatched: the" in result.output
+    plain = tmp_path / "plain.json"
+    plain.write_text("[1, 2]")
+    as_json = json.loads(
+        run("resolve", "bearings", "--vector-file", str(plain), "-d", "supply", "--json").stdout
+    )
+    assert as_json["candidates"][0]["predicate"] == {
+        "attr": "category",
+        "op": "in",
+        "value": ["bearing"],
+    }
+    bodies = request_bodies(route)
+    assert bodies[0] == {
+        "text": "the bearings",
+        "kinds": ["Part"],
+        "levels": ["exact"],
+        "limit": 50,
+    }
+    assert bodies[1]["query_vector"] == [1.0, 2.0]
+
+
 # History ------------------------------------------------------------------------------------
 
 
@@ -1484,6 +1544,14 @@ DOCUMENT_ROW = {
     "metadata": {},
     "created_at": NOW,
     "created_by": "usr_1",
+    "source_key": None,
+    "version": 1,
+    "replaces": None,
+    "status": "active",
+    "retired_at": None,
+    "retired_by": None,
+    "purged_at": None,
+    "purged_by": None,
 }
 ITEM_ROW = {
     "id": "itm_1",
@@ -1565,7 +1633,7 @@ def test_documents_list_and_get(http: respx.MockRouter) -> None:
         "error": None,
     }
     http.get("/domains/supply/documents/doc_1").respond(
-        200, json={**DOCUMENT_ROW, "extraction_jobs": [job]}
+        200, json={**DOCUMENT_ROW, "extraction_jobs": [job], "open_stale_candidates": 0}
     )
     listed = run("documents", "list", "-d", "supply")
     assert listed.exit_code == 0, listed.output
@@ -1578,6 +1646,74 @@ def test_documents_list_and_get(http: respx.MockRouter) -> None:
     assert as_json["extraction_jobs"][0]["id"] == "ext_1"
 
 
+def test_documents_keys_versions_retire_and_purge(http: respx.MockRouter, tmp_path: Path) -> None:
+    v2 = {**DOCUMENT_ROW, "id": "doc_2", "source_key": "k", "version": 2, "replaces": "doc_1"}
+    upload = http.post("/domains/supply/documents").respond(
+        201, json={"document": v2, "duplicate": False, "job_id": None, "check_job_id": 9}
+    )
+    listing = http.get("/domains/supply/documents").respond(
+        200, json={"items": [v2], "next_cursor": None}
+    )
+    http.get("/domains/supply/documents/doc_2/versions").respond(
+        200, json={"items": [v2, DOCUMENT_ROW], "next_cursor": None}
+    )
+    retired = {**v2, "status": "retired", "retired_at": NOW, "retired_by": "usr_1"}
+    retire = http.post("/domains/supply/documents/doc_2/retirement").respond(
+        200, json={"document": retired, "job_id": 11}
+    )
+    purge = http.post("/domains/supply/documents/doc_2/purge").respond(
+        200,
+        json={
+            "document": {**retired, "status": "purged"},
+            "job_id": None,
+            "blob_deleted": True,
+            "text_deleted": True,
+            "chunks": 3,
+            "cache_entries": 2,
+            "items": 1,
+            "candidates": 0,
+            "suggestions": 0,
+        },
+    )
+    spec = tmp_path / "spec.txt"
+    spec.write_bytes(b"hello")
+    sent = run("documents", "upload", str(spec), "--key", "k", "-d", "supply")
+    assert sent.exit_code == 0, sent.output
+    assert b'name="source_key"\r\n\r\nk' in upload.calls.last.request.content
+    assert "check job" in sent.stdout
+    by_url = run(
+        "documents", "upload", "--url", "https://example.test/a", "--key", "k", "-d", "supply"
+    )
+    assert by_url.exit_code == 0, by_url.output
+    assert json.loads(upload.calls.last.request.content)["source_key"] == "k"
+    listed = run("documents", "list", "--key", "k", "-d", "supply")
+    assert listed.exit_code == 0, listed.output
+    assert listing.calls.last.request.url.params["source_key"] == "k"
+    assert "retired" not in listed.stdout
+    versions = run("documents", "versions", "doc_2", "-d", "supply")
+    assert versions.exit_code == 0, versions.output
+    assert "doc_1" in versions.stdout
+    done = run("documents", "retire", "doc_2", "--reason", "obsolete", "-d", "supply")
+    assert done.exit_code == 0, done.output
+    assert "retired" in done.stdout
+    assert request_bodies(retire) == [{"reason": "obsolete"}]
+    erased = run(
+        "documents", "purge", "doc_2", "--reason", "gdpr", "--confirm", "doc_2", "-d", "supply"
+    )
+    assert erased.exit_code == 0, erased.output
+    assert request_bodies(purge) == [{"reason": "gdpr", "confirm": "doc_2"}]
+    assert "chunks" in erased.stdout
+
+
+def test_documents_purge_refuses_a_wrong_confirmation(http: respx.MockRouter) -> None:
+    route = http.post("/domains/supply/documents/doc_2/purge")
+    result = run(
+        "documents", "purge", "doc_2", "--reason", "x", "--confirm", "doc_3", "-d", "supply"
+    )
+    assert result.exit_code == 1
+    assert not route.called
+
+
 def test_documents_text_prints_the_parsed_text(http: respx.MockRouter) -> None:
     body = {
         "document_id": "doc_1",
@@ -1730,7 +1866,7 @@ def test_module_entry_point_runs() -> None:
         check=False,
     )
     assert done.returncode == 0
-    assert done.stdout.startswith("lorebase 0.2.3")
+    assert done.stdout.startswith("lorebase 0.3.0")
 
 
 # Proposals, context and explain --------------------------------------------------------------
@@ -1868,6 +2004,8 @@ def test_proposal_list_filters_and_renders(http: respx.MockRouter) -> None:
         "target",
         "status",
         "author",
+        "stewards",
+        "assignees",
         "created",
     ]
     assert "prp_2" in result.stdout
@@ -1880,6 +2018,10 @@ def test_proposal_list_filters_and_renders(http: respx.MockRouter) -> None:
     )
     as_json = json.loads(run("proposal", "list", "-d", "supply", "-n", "1", "--json").stdout)
     assert [p["id"] for p in as_json] == ["prp_1"]
+    assert "assigned" not in params
+    mine = run("proposal", "list", "--mine", "-d", "supply")
+    assert mine.exit_code == 0, mine.output
+    assert route.calls.last.request.url.params["assigned"] == "me"
 
 
 def test_proposal_get_shows_review_state(http: respx.MockRouter) -> None:
@@ -2381,3 +2523,132 @@ def test_schema_suggestions_merge_reports_counts(http: respx.MockRouter) -> None
     assert route.called
     as_json = run("schema", "suggestions", "merge", "-d", "supply", "--json")
     assert json.loads(as_json.stdout) == {"merged": 3, "kept": 2}
+
+
+# Reconciliation -----------------------------------------------------------------------------
+
+
+def candidate_row(**extra: Any) -> dict[str, Any]:
+    return {
+        "id": "rcc_1",
+        "branch": "main",
+        "type": "contradiction",
+        "status": "open",
+        "kind": "Supplier",
+        "kind_id": "knd_1",
+        "keys": ["S-1"],
+        "attribute": "city",
+        "attribute_id": "att_1",
+        "claims": [
+            {"claim_id": "c1", "value": "Turin", "source": "source:src_1"},
+            {"claim_id": "c2", "value": "Milan"},
+        ],
+        "claim_count": 2,
+        "signals": {},
+        "proposal_id": None,
+        "decision": None,
+        "decided_by": None,
+        "decided_at": None,
+        "created_at": NOW,
+        "updated_at": NOW,
+        **extra,
+    }
+
+
+def test_reconcile_list_and_show(http: respx.MockRouter) -> None:
+    listing = http.get("/domains/supply/reconciliation").respond(
+        200, json={"items": [candidate_row()], "next_cursor": None}
+    )
+    http.get("/domains/supply/reconciliation/rcc_1").respond(200, json=candidate_row())
+    listed = run(
+        "reconcile",
+        "list",
+        "--type",
+        "contradiction",
+        "--status",
+        "open",
+        "--kind",
+        "Supplier",
+        "--attribute",
+        "city",
+        "--source",
+        "source:src_1",
+        "-b",
+        "work",
+        "-d",
+        "supply",
+    )
+    assert listed.exit_code == 0, listed.output
+    assert "rcc_1" in listed.stdout
+    assert "S-1" in listed.stdout
+    params = listing.calls.last.request.url.params
+    assert {k: params[k] for k in ("branch", "type", "status", "kind", "attribute", "source")} == {
+        "branch": "work",
+        "type": "contradiction",
+        "status": "open",
+        "kind": "Supplier",
+        "attribute": "city",
+        "source": "source:src_1",
+    }
+    assert "assigned" not in params
+    mine = run("reconcile", "list", "--mine", "-d", "supply")
+    assert mine.exit_code == 0, mine.output
+    assert listing.calls.last.request.url.params["assigned"] == "me"
+    shown = run("reconcile", "show", "rcc_1", "-d", "supply")
+    assert shown.exit_code == 0, shown.output
+    assert "Turin" in shown.stdout
+    as_json = json.loads(run("reconcile", "show", "rcc_1", "-d", "supply", "--json").stdout)
+    assert as_json["claim_count"] == 2
+    bad = run("reconcile", "list", "--type", "other", "-d", "supply")
+    assert bad.exit_code == 1
+
+
+def test_reconcile_resolve_dismiss_and_reopen(http: respx.MockRouter) -> None:
+    decision = {"status": "dry_run", "candidate": candidate_row(), "claim_id": "c1"}
+    resolution = http.post("/domains/supply/reconciliation/rcc_1/resolution").respond(
+        200, json=decision
+    )
+    dismissal = http.post("/domains/supply/reconciliation/rcc_1/dismissal").respond(
+        200, json={**decision, "status": "dismissed"}
+    )
+    reopen = http.post("/domains/supply/reconciliation/rcc_1/reopen").respond(
+        200, json={**decision, "status": "reopened"}
+    )
+    resolved = run(
+        "reconcile",
+        "resolve",
+        "rcc_1",
+        "--choice",
+        "merge",
+        "--survivor",
+        "S-1",
+        "--values",
+        '{"city": "Turin"}',
+        "--value",
+        '"Turin"',
+        "--reason",
+        "checked",
+        "--dry-run",
+        "-d",
+        "supply",
+    )
+    assert resolved.exit_code == 0, resolved.output
+    assert "dry_run" in resolved.stdout
+    assert request_bodies(resolution) == [
+        {
+            "choice": "merge",
+            "value": "Turin",
+            "survivor": "S-1",
+            "values": {"city": "Turin"},
+            "reason": "checked",
+            "dry_run": True,
+        }
+    ]
+    assert run(
+        "reconcile", "resolve", "rcc_1", "--choice", "x", "-r", "r", "-d", "supply"
+    ).exit_code
+    assert run("reconcile", "resolve", "rcc_1", "--choice", "claim", "-d", "supply").exit_code == 1
+    assert run("reconcile", "dismiss", "rcc_1", "-r", "same city", "-d", "supply").exit_code == 0
+    assert request_bodies(dismissal) == [{"reason": "same city"}]
+    assert run("reconcile", "reopen", "rcc_1", "-r", "wrong", "-d", "supply").exit_code == 0
+    assert request_bodies(reopen) == [{"reason": "wrong"}]