lorebase-cli 0.2.3__py3-none-any.whl

lorebase_cli/commands/documents.py

@@ -0,0 +1,161 @@
+"""`documents upload|list|get|text`: documents stored for extraction by Scribe."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Any
+
+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_client import models as m
+
+documents_app = typer.Typer(
+    help="Upload documents and follow their extraction.", no_args_is_help=True
+)
+
+DOCUMENT_COLUMNS = [
+    Column("id", "id"),
+    Column("filename", "filename"),
+    Column("type", "media_type"),
+    Column("size", "size"),
+    Column("sha256", "sha256", short_id),
+    Column("created", "created_at"),
+]
+
+
+def _tiers(text: str | None) -> list[int] | None:
+    """Extraction tiers from a comma separated list such as `0,1`."""
+    if text is None:
+        return None
+    try:
+        return [int(part) for part in text.split(",")]
+    except ValueError:
+        raise CliError(f"--tiers is a comma separated list of integers, got {text!r}") from None
+
+
+def _document_pairs(found: m.Document) -> list[tuple[str, Any]]:
+    return [
+        ("document", found.id),
+        ("filename", found.filename),
+        ("media type", found.media_type),
+        ("size", found.size),
+        ("sha256", found.sha256),
+        ("text parsed", found.text_sha256 is not None),
+        ("created", found.created_at),
+        ("created by", found.created_by),
+    ]
+
+
+@documents_app.command("upload")
+def documents_upload(
+    ctx: typer.Context,
+    path: Annotated[
+        Path | None,
+        typer.Argument(help="File to upload.", metavar="[PATH]", show_default=False),
+    ] = None,
+    url: Annotated[
+        str | None,
+        typer.Option("--url", help="Have the server fetch the document from this URL instead."),
+    ] = None,
+    no_extract: Annotated[
+        bool, typer.Option("--no-extract", help="Store the document without queueing extraction.")
+    ] = False,
+    tiers: Annotated[
+        str | None, typer.Option("--tiers", help="Extraction tiers, comma separated (e.g. 0,1).")
+    ] = None,
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Upload a document (PATH, or --url) and queue its extraction."""
+    app = app_of(ctx, json_out)
+    name = app.domain(domain)
+    extract = False if no_extract else None
+    wanted = _tiers(tiers)
+    documents = app.client().documents
+    if path is not None and url is None:
+        try:
+            uploaded = documents.upload(name, path, extract=extract, tiers=wanted)
+        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)
+    else:
+        raise CliError("give PATH or --url")
+    app.out.emit(
+        uploaded,
+        lambda: app.out.pairs(
+            [
+                *_document_pairs(uploaded.document),
+                ("duplicate", uploaded.duplicate),
+                ("job", uploaded.job_id),
+            ]
+        ),
+    )
+
+
+@documents_app.command("list")
+def documents_list(
+    ctx: typer.Context,
+    domain: DomainOpt = None,
+    limit: LimitOpt = None,
+    everything: AllOpt = False,
+    json_out: JsonOpt = False,
+) -> 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)
+    app.out.emit(items, lambda: app.out.table([d.model_dump() for d in items], DOCUMENT_COLUMNS))
+    if more:
+        app.note_truncated(len(items))
+
+
+def _show_document(app: AppContext, found: m.DocumentDetail) -> None:
+    app.out.pairs(
+        [
+            *_document_pairs(found),
+            *(
+                (
+                    f"job {job.id}",
+                    f"{job.status} ({job.model}, prompt {job.prompt_version})"
+                    + (f", proposal {job.proposal_id}" if job.proposal_id else ""),
+                )
+                for job in found.extraction_jobs
+            ),
+        ]
+    )
+
+
+@documents_app.command("get")
+def documents_get(
+    ctx: typer.Context,
+    document_id: Annotated[str, typer.Argument(help="Document id.", metavar="ID")],
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Show a document with its extraction jobs."""
+    app = app_of(ctx, json_out)
+    found = app.client().documents.get(app.domain(domain), document_id)
+    app.out.emit(found, lambda: _show_document(app, found))
+
+
+@documents_app.command("text")
+def documents_text(
+    ctx: typer.Context,
+    document_id: Annotated[str, typer.Argument(help="Document id.", metavar="ID")],
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Print the parsed text of a document (the text extraction evidence offsets index)."""
+    app = app_of(ctx, json_out)
+    found = app.client().documents.text(app.domain(domain), document_id)
+
+    def human() -> None:
+        app.out.text(found.text)
+        if found.truncated:
+            app.out.info(f"text cut at {len(found.text)} of {found.length} characters")
+
+    app.out.emit(found, human)

lorebase_cli/commands/domains.py

@@ -0,0 +1,404 @@
+"""`whoami`, `domain`, `branch` and `tag` commands."""
+
+from __future__ import annotations
+
+import sys
+import time
+from typing import Annotated, Any, cast, get_args
+
+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, complete_domain
+from lorebase_cli.output import Column, short_id
+from lorebase_client.models import Branch, BranchMode, Domain
+
+domain_app = typer.Typer(help="Create, inspect and delete Domains.", no_args_is_help=True)
+branch_app = typer.Typer(help="List, create, protect and delete branches.", no_args_is_help=True)
+tag_app = typer.Typer(
+    help="List and create tags (immutable names for Revisions).", no_args_is_help=True
+)
+
+DomainId = Annotated[
+    str, typer.Argument(help="Domain id.", metavar="DOMAIN", autocompletion=complete_domain)
+]
+
+DOMAIN_COLUMNS = [
+    Column("id", "id"),
+    Column("name", "display_name"),
+    Column("default branch", "default_branch"),
+    Column("created", "created_at"),
+]
+
+
+def whoami(ctx: typer.Context, json_out: JsonOpt = False) -> None:
+    """Show who the credentials authenticate as."""
+    app = app_of(ctx, json_out)
+    me = app.client().whoami()
+
+    def human() -> None:
+        rows: list[tuple[str, Any]] = [
+            ("id", me.id),
+            ("name", me.display_name),
+            ("type", me.type),
+            ("method", me.method),
+            ("installation admin", me.installation_admin),
+            ("subjects", me.subjects),
+        ]
+        if me.quota is not None:
+            rows.append(("quota resets", me.quota.resets_at))
+            for name, use in (
+                ("requests", me.quota.requests),
+                ("context tokens", me.quota.context_tokens),
+            ):
+                limit = "unlimited" if use.limit is None else use.limit
+                rows.append((f"{name} today", f"{use.used} of {limit}"))
+        app.out.pairs(rows)
+
+    app.out.emit(me, human)
+
+
+# Domains ----------------------------------------------------------------------------------
+
+
+@domain_app.command("create")
+def domain_create(
+    ctx: typer.Context,
+    domain_id: Annotated[
+        str, typer.Argument(help="Domain id: lowercase slug, immutable.", metavar="DOMAIN")
+    ],
+    name: Annotated[str, typer.Option("--name", help="Display name.")] = "",
+    description: Annotated[str, typer.Option("--description", help="Description.")] = "",
+    default_branch: Annotated[
+        str | None, typer.Option(help="Name of the default branch (server default: main).")
+    ] = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Create a Domain with an empty first Revision and a protected default branch."""
+    app = app_of(ctx, json_out)
+    created = app.client().domains.create(
+        domain_id, display_name=name, description=description, default_branch=default_branch
+    )
+    app.out.emit(created, lambda: _show_domain(app, created))
+
+
+@domain_app.command("list")
+def domain_list(
+    ctx: typer.Context,
+    limit: LimitOpt = None,
+    everything: AllOpt = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """List the Domains you can read."""
+    app = app_of(ctx, json_out)
+    items, more = app.take(app.client().domains.iterate(), limit, everything)
+    app.out.emit(items, lambda: app.out.table([d.model_dump() for d in items], DOMAIN_COLUMNS))
+    if more:
+        app.note_truncated(len(items))
+
+
+@domain_app.command("get")
+def domain_get(ctx: typer.Context, domain_id: DomainId, json_out: JsonOpt = False) -> None:
+    """Show a Domain and the head of its default branch."""
+    app = app_of(ctx, json_out)
+    found = app.client().domains.get(domain_id)
+    app.out.emit(found, lambda: _show_domain(app, found))
+
+
+@domain_app.command("delete")
+def domain_delete(
+    ctx: typer.Context,
+    domain_id: DomainId,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Do not ask for confirmation.")] = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """Delete a Domain with all its Revisions, branches and grants. This cannot be undone."""
+    app = app_of(ctx, json_out)
+    if not yes:
+        if not _interactive():
+            raise CliError("deleting a Domain is irreversible: pass --yes to confirm")
+        typed = typer.prompt(f"This deletes Domain {domain_id!r} for good. Type its id to confirm")
+        if typed != domain_id:
+            raise CliError("the id typed does not match; nothing was deleted")
+    app.client().domains.delete(domain_id, confirm=domain_id)
+    app.out.emit({"deleted": domain_id}, lambda: app.out.info(f"deleted Domain {domain_id}"))
+
+
+def _interactive() -> bool:
+    return sys.stdin.isatty()
+
+
+def _show_domain(app: AppContext, domain: Domain) -> None:
+    app.out.pairs(
+        [
+            ("id", domain.id),
+            ("name", domain.display_name),
+            ("description", domain.description),
+            ("default branch", domain.default_branch),
+            ("head", domain.head),
+            ("created", domain.created_at),
+            ("created by", domain.created_by),
+        ]
+    )
+
+
+# Branches ---------------------------------------------------------------------------------
+
+BRANCH_COLUMNS = [
+    Column("branch", "name"),
+    Column("head", "head", short_id),
+    Column("protected", "protected"),
+    Column("default", "default"),
+    Column("materialization", "materialization"),
+    Column("copy", "materialization_status"),
+]
+
+_sleep = time.sleep
+_clock = time.monotonic
+
+
+def _copy_note(branch: Branch) -> str | None:
+    """The background copy of a branch: status, phase and rows read."""
+    if branch.materialization_status is None:
+        return None
+    progress = branch.materialization_progress
+    if progress is None:
+        return branch.materialization_status
+    total = "?" if progress.rows_total is None else progress.rows_total
+    return f"{branch.materialization_status}: {progress.phase} {progress.rows_done}/{total}"
+
+
+@branch_app.command("list")
+def branch_list(
+    ctx: typer.Context,
+    domain: DomainOpt = None,
+    limit: LimitOpt = None,
+    everything: AllOpt = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """List the branches of a Domain."""
+    app = app_of(ctx, json_out)
+    items, more = app.take(app.client().branches.iterate(app.domain(domain)), limit, everything)
+    app.out.emit(items, lambda: app.out.table([b.model_dump() for b in items], BRANCH_COLUMNS))
+    if more:
+        app.note_truncated(len(items))
+
+
+@branch_app.command("get")
+def branch_get(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Branch name.", metavar="NAME")],
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Show a branch and how far it is from the default branch."""
+    app = app_of(ctx, json_out)
+    found = app.client().branches.get(app.domain(domain), name)
+    app.out.emit(
+        found,
+        lambda: app.out.pairs(
+            [
+                ("branch", found.name),
+                ("head", found.head),
+                ("protected", found.protected),
+                ("default", found.default),
+                ("ahead", found.ahead),
+                ("behind", found.behind),
+                ("materialization", found.materialization),
+                ("copy", _copy_note(found)),
+                ("created", found.created_at),
+            ]
+        ),
+    )
+
+
+@branch_app.command("create")
+def branch_create(
+    ctx: typer.Context,
+    name: Annotated[
+        str, typer.Argument(help="New branch name (may contain slashes).", metavar="NAME")
+    ],
+    source: Annotated[
+        str | None, typer.Option("--source", help="Branch or tag to start from (default branch).")
+    ] = None,
+    revision: Annotated[
+        str | None, typer.Option("--revision", help="Revision id to start at.")
+    ] = None,
+    mode: Annotated[
+        str | None,
+        typer.Option("--mode", help="copy (own rows) or overlay (only its changes)."),
+    ] = None,
+    wait: Annotated[
+        bool, typer.Option("--wait", help="Wait until the background copy of the branch ends.")
+    ] = False,
+    wait_timeout: Annotated[
+        float, typer.Option("--wait-timeout", min=0, help="Seconds --wait gives up after.")
+    ] = 3600.0,
+    poll_interval: Annotated[
+        float, typer.Option("--poll-interval", min=0, help="Seconds between --wait checks.")
+    ] = 2.0,
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Create a branch from a branch, a tag or a Revision. A large copy starts as an overlay
+    that a background job copies; --wait blocks until it is a full copy."""
+    app = app_of(ctx, json_out)
+    allowed = get_args(BranchMode)
+    if mode is not None and mode not in allowed:
+        raise CliError(f"--mode: unknown {mode!r}, use {', '.join(allowed)}")
+    domain_id = app.domain(domain)
+    created: Branch = app.client().branches.create(
+        domain_id, name, source=source, revision=revision, mode=cast(BranchMode, mode)
+    )
+    if wait:
+        deadline = _clock() + wait_timeout
+        last: str | None = None
+        while created.materialization_status in ("pending", "running"):
+            note = _copy_note(created)
+            if note != last:
+                app.out.info(f"copying: {note}")
+                last = note
+            if _clock() >= deadline:
+                raise CliError(f"branch {name!r} is still being copied after {wait_timeout:g}s")
+            _sleep(poll_interval)
+            created = app.client().branches.get(domain_id, name)
+        if created.materialization_status == "failed":
+            progress = created.materialization_progress
+            error = progress.error if progress is not None else None
+            raise CliError(f"copy of branch {name!r} failed: {error or 'unknown error'}")
+    app.out.emit(created, lambda: app.out.table([created.model_dump()], BRANCH_COLUMNS))
+
+
+@branch_app.command("delete")
+def branch_delete(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Branch name.", metavar="NAME")],
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Delete a branch (its Revisions stay reachable by id and tag). The default and
+    protected branches cannot be deleted."""
+    app = app_of(ctx, json_out)
+    app.client().branches.delete(app.domain(domain), name)
+    app.out.emit({"deleted": name}, lambda: app.out.info(f"deleted branch {name}"))
+
+
+@branch_app.command("protect")
+def branch_protect(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Branch name.", metavar="NAME")],
+    off: Annotated[bool, typer.Option("--off", help="Remove the protection instead.")] = False,
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Protect a branch: changes reach it through Proposals only."""
+    app = app_of(ctx, json_out)
+    updated = app.client().branches.set_protected(app.domain(domain), name, not off)
+    app.out.emit(updated, lambda: app.out.table([updated.model_dump()], BRANCH_COLUMNS))
+
+
+TAG_CHANGE_COLUMNS = [
+    Column("section", "section"),
+    Column("owner", "owner"),
+    Column("attribute", "attribute"),
+    Column("tags", "tags", lambda tags: ", ".join(tags)),
+]
+
+
+@branch_app.command("rebase-tags")
+def branch_rebase_tags(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Branch name.", metavar="BRANCH")],
+    message: Annotated[
+        str | None, typer.Option("--message", "-m", help="Revision message.")
+    ] = None,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Plan only; write nothing.")] = False,
+    rows_only: Annotated[
+        bool,
+        typer.Option(
+            "--rows-only",
+            help="Leave the schema alone: queue the rewrite of the stale titles and search "
+            "vectors only.",
+        ),
+    ] = False,
+    expected_head: Annotated[
+        str | None,
+        typer.Option("--expected-head", help="Fail unless the branch is at this Revision."),
+    ] = None,
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Give a branch forked before the default branch tagged an Attribute the tags it lacks.
+
+    One schema change adds the default branch's sensitivity tags (never removes one) and
+    recomputes the titles and search vectors the branch stored before them. Protected
+    branches refuse it; --rows-only only queues the rewrite of those rows.
+    """
+    app = app_of(ctx, json_out)
+    result = app.client().branches.rebase_tags(
+        app.domain(domain),
+        name,
+        message=message,
+        expected_head=expected_head,
+        dry_run=dry_run,
+        rows_only=rows_only,
+    )
+
+    def report() -> None:
+        app.out.pairs(
+            [
+                ("status", result.status),
+                ("branch", result.branch),
+                ("revision", result.revision),
+                ("element changes", result.change_count),
+                ("job", result.job),
+            ]
+        )
+        if result.tags:
+            app.out.table([t.model_dump() for t in result.tags], TAG_CHANGE_COLUMNS)
+
+    app.out.emit(result, report)
+
+
+# Tags -------------------------------------------------------------------------------------
+
+TAG_COLUMNS = [
+    Column("tag", "name"),
+    Column("revision", "revision", short_id),
+    Column("created", "created_at"),
+    Column("by", "created_by"),
+]
+
+
+@tag_app.command("list")
+def tag_list(
+    ctx: typer.Context,
+    domain: DomainOpt = None,
+    limit: LimitOpt = None,
+    everything: AllOpt = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """List the tags of a Domain."""
+    app = app_of(ctx, json_out)
+    items, more = app.take(app.client().tags.iterate(app.domain(domain)), limit, everything)
+    app.out.emit(items, lambda: app.out.table([t.model_dump() for t in items], TAG_COLUMNS))
+    if more:
+        app.note_truncated(len(items))
+
+
+@tag_app.command("create")
+def tag_create(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Tag name.", metavar="NAME")],
+    source: Annotated[
+        str | None, typer.Option("--source", help="Branch whose head to tag.")
+    ] = None,
+    revision: Annotated[str | None, typer.Option("--revision", help="Revision id to tag.")] = None,
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Tag a Revision (default: the head of the default branch). Tags never move."""
+    app = app_of(ctx, json_out)
+    created = app.client().tags.create(app.domain(domain), name, source=source, revision=revision)
+    app.out.emit(created, lambda: app.out.table([created.model_dump()], TAG_COLUMNS))