lorebase-cli 0.2.3__py3-none-any.whl

lorebase_cli/commands/trace.py

@@ -0,0 +1,140 @@
+"""`trace list`, `trace show`, `trace note`: agent trace sessions of a Keeper."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import typer
+
+from lorebase_cli.context import app_of
+from lorebase_cli.options import DomainOpt, JsonOpt, LimitOpt
+from lorebase_cli.output import Column
+from lorebase_client import models as m
+
+trace_app = typer.Typer(help="Inspect what agents did in a session.", no_args_is_help=True)
+
+SessionArg = Annotated[str, typer.Argument(help="Session id.", metavar="SESSION_ID")]
+ActorOpt = Annotated[str | None, typer.Option("--actor", help="Only the calls of this principal.")]
+
+SESSION_COLUMNS = [
+    Column("session", "session_id"),
+    Column("actor", "actor"),
+    Column("last activity", "last_at"),
+    Column("calls", "calls"),
+    Column("notes", "notes"),
+    Column("domains", "domains"),
+    Column("tools", "tools"),
+    Column("proposals", "proposals"),
+    Column("inferred", "inferred"),
+]
+STEP_COLUMNS = [
+    Column("step", "step"),
+    Column("time", "at"),
+    Column("type", "type"),
+    Column("tool", "tool"),
+    Column("endpoint", "endpoint"),
+    Column("status", "status"),
+    Column("ms", "latency_ms"),
+    Column("cache", "cache"),
+    Column("counts", "counts"),
+    Column("refs", "refs"),
+    Column("note", "note"),
+]
+
+
+def plain(text: str | None) -> str | None:
+    """Opaque text for a terminal: control characters (escape sequences) are replaced."""
+    if text is None:
+        return None
+    return "".join(c if c.isprintable() else "?" for c in text)
+
+
+def counts_of(result: dict[str, Any] | None) -> str:
+    """`items=3 edges=2` from the result counts of a call."""
+    counts = (result or {}).get("counts")
+    if not isinstance(counts, dict):
+        return ""
+    return " ".join(f"{name}={value}" for name, value in counts.items())
+
+
+def step_row(step: m.TraceStep) -> dict[str, Any]:
+    """A timeline step as table cells."""
+    row = step.model_dump()
+    row["endpoint"] = " ".join(part for part in (step.method, step.route) if part)
+    row["counts"] = counts_of(step.result)
+    refs = step.refs
+    row["refs"] = (
+        ""
+        if refs is None
+        else f"{len(refs.records)}r {len(refs.links)}l" + ("+" if refs.truncated else "")
+    )
+    row["latency_ms"] = None if step.latency_ms is None else f"{step.latency_ms:.0f}"
+    row["note"] = plain(step.note)
+    return row
+
+
+@trace_app.command("list")
+def trace_list(
+    ctx: typer.Context,
+    actor: ActorOpt = None,
+    domain: DomainOpt = None,
+    limit: LimitOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """List the sessions you may see, most recent activity first."""
+    app = app_of(ctx, json_out)
+    page = app.client().trace.sessions(
+        actor=actor, domain_id=domain, limit=limit or app.settings.list_limit
+    )
+
+    def human() -> None:
+        if not page.enabled:
+            app.out.info("tracing is off on this server; showing recorded sessions only")
+        app.out.table([s.model_dump() for s in page.items], SESSION_COLUMNS)
+
+    app.out.emit(page, human)
+    if page.next_cursor is not None:
+        app.note_truncated(len(page.items))
+
+
+@trace_app.command("show")
+def trace_show(
+    ctx: typer.Context,
+    session_id: SessionArg,
+    actor: ActorOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Print the timeline of a session: calls with their outcome, and notes."""
+    app = app_of(ctx, json_out)
+    timeline = app.client().trace.session(session_id, actor=actor)
+
+    def human() -> None:
+        if any(s.inferred for s in timeline.steps):
+            app.out.info("inferred session: calls without a session id, grouped heuristically")
+        app.out.table([step_row(s) for s in timeline.steps], STEP_COLUMNS)
+        if timeline.truncated:
+            app.out.info("the session has more steps than shown")
+
+    app.out.emit(timeline, human)
+
+
+@trace_app.command("note")
+def trace_note(
+    ctx: typer.Context,
+    session_id: SessionArg,
+    text: Annotated[str, typer.Argument(help="Text of the note.", metavar="TEXT")],
+    domain: DomainOpt = None,
+    step: Annotated[
+        int | None, typer.Option("--step", min=0, help="Step counter of the agent.")
+    ] = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Attach a note to a session (written off the request path)."""
+    app = app_of(ctx, json_out)
+    result = app.client().trace.add_note(session_id, text, domain_id=domain, step=step)
+    app.out.emit(
+        result,
+        lambda: app.out.info(
+            "note recorded" if result.recorded else "note dropped: tracing is off"
+        ),
+    )

lorebase_cli/context.py

@@ -0,0 +1,93 @@
+"""State shared by the commands of one invocation: settings, output and the client."""
+
+from __future__ import annotations
+
+import itertools
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+
+import typer
+
+from lorebase_cli.failures import CliError
+from lorebase_cli.output import Output
+from lorebase_cli.settings import ENV_DOMAIN, CliSettings
+from lorebase_client import LorebaseClient
+
+ClientFactory = Callable[[CliSettings], LorebaseClient]
+
+
+def default_client(settings: CliSettings) -> LorebaseClient:
+    """A client for the configured server. (Imports send idempotency keys themselves; creating
+    things does not, so that creating what exists is reported as a conflict.)"""
+    return LorebaseClient(
+        settings.url,
+        api_prefix=settings.api_prefix,
+        api_key=settings.api_key,
+        token=settings.token,
+        timeout=settings.timeout,
+        env={},
+    )
+
+
+@dataclass
+class AppContext:
+    """Per-invocation state, stored in the Typer context."""
+
+    settings: CliSettings
+    client_factory: ClientFactory = default_client
+    json_mode: bool = False
+    quiet: bool = False
+    _client: LorebaseClient | None = field(default=None, repr=False)
+
+    @property
+    def out(self) -> Output:
+        return Output(json_mode=self.json_mode, max_cell_width=self.settings.max_cell_width)
+
+    def client(self) -> LorebaseClient:
+        if self._client is None:
+            self._client = self.client_factory(self.settings)
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+
+    def domain(self, given: str | None) -> str:
+        """The Domain to work in: `--domain`, `LOREBASE_DOMAIN`, then the config file."""
+        chosen = given or self.settings.domain
+        if not chosen:
+            raise CliError(
+                f"no Domain: pass --domain, set {ENV_DOMAIN} or `domain` in the config file"
+            )
+        return chosen
+
+    def branch(self, given: str | None) -> str | None:
+        """The branch named by `--branch`, `LOREBASE_BRANCH` or the config file; none means
+        the Domain's default branch."""
+        return given or self.settings.branch
+
+    def take[T](
+        self, items: Iterable[T], limit: int | None, everything: bool
+    ) -> tuple[list[T], bool]:
+        """The first items of a listing and whether more exist: `--all` takes all, `--limit`
+        that many, else the `list_limit` setting."""
+        if everything:
+            return list(items), False
+        cap = limit or self.settings.list_limit
+        taken = list(itertools.islice(items, cap + 1))
+        return taken[:cap], len(taken) > cap
+
+    def note_truncated(self, shown: int) -> None:
+        """Tell the person a listing was cut (standard error, human output only)."""
+        if not self.json_mode and not self.quiet:
+            self.out.info(f"showing the first {shown} items; use --all or --limit for more")
+
+
+def app_of(ctx: typer.Context, json_flag: bool = False) -> AppContext:
+    """The invocation state; a `--json` flag given after the command turns JSON output on."""
+    app = ctx.find_object(AppContext)
+    if app is None:  # pragma: no cover - the root callback always sets it
+        raise CliError("the command ran without its settings")
+    if json_flag:
+        app.json_mode = True
+    return app

lorebase_cli/failures.py

@@ -0,0 +1,195 @@
+"""Exit codes and the text of failures.
+
+| Code | Meaning |
+|------|---------|
+| 0 | success |
+| 1 | usage or configuration error, a thing that does not exist (404), any other refused request |
+| 2 | validation failure (422) or conflict (409): the request is well formed but cannot apply |
+| 3 | authentication or permission failure (401, 403) |
+| 4 | server error (5xx) or server unreachable |
+
+Failures go to standard error; with `--json` they are a JSON document there, so that standard
+output only ever holds results.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from lorebase_client import (
+    AuthenticationError,
+    ConflictError,
+    LorebaseConnectionError,
+    LorebaseError,
+    PermissionDeniedError,
+    ServerError,
+    ValidationFailedError,
+)
+
+EXIT_OK = 0
+EXIT_USAGE = 1
+EXIT_INVALID = 2
+EXIT_AUTH = 3
+EXIT_SERVER = 4
+
+
+class CliError(Exception):
+    """A failure with a message for the user and an exit code (default: usage error)."""
+
+    def __init__(self, message: str, *, exit_code: int = EXIT_USAGE) -> None:
+        super().__init__(message)
+        self.message = message
+        self.exit_code = exit_code
+
+
+Locator = Callable[[Sequence[Any]], str | None]
+
+
+class ImportAbortedError(CliError):
+    """An import stopped at a rejected batch; earlier batches stay committed.
+
+    `locate` turns the path of an issue into a place in the input files, for imports that read
+    several (the default numbers the rows of the one file); `scope` words which rows were rejected.
+    """
+
+    def __init__(
+        self,
+        cause: LorebaseError,
+        *,
+        first_row: int,
+        last_row: int,
+        committed_rows: int,
+        committed_revisions: list[str],
+        scope: str | None = None,
+        locate: Locator | None = None,
+    ) -> None:
+        super().__init__(
+            f"{scope or f'rows {first_row}-{last_row} were rejected'}; {committed_rows} earlier "
+            "rows are committed",
+            exit_code=exit_code_for(cause),
+        )
+        self.cause = cause
+        self.locate = locate
+        self.first_row = first_row
+        self.last_row = last_row
+        self.committed_rows = committed_rows
+        self.committed_revisions = committed_revisions
+
+
+def exit_code_for(error: LorebaseError) -> int:
+    """The exit code of a client error."""
+    if isinstance(error, ValidationFailedError | ConflictError):
+        return EXIT_INVALID
+    if isinstance(error, AuthenticationError | PermissionDeniedError):
+        return EXIT_AUTH
+    if isinstance(error, ServerError | LorebaseConnectionError):
+        return EXIT_SERVER
+    return EXIT_USAGE
+
+
+def _location(path: list[Any], row_offset: int) -> str:
+    """`rows[12].supplier_code`-style text for an issue path; row indexes are shifted by
+    `row_offset` (the number of the first row sent, for imports)."""
+    text = ""
+    previous: Any = None
+    for part in path:
+        if isinstance(part, int):
+            number = part + row_offset if previous == "rows" else part
+            text += f"[{number}]"
+        else:
+            text += f".{part}" if text else str(part)
+        previous = part
+    return text
+
+
+def issue_lines(
+    error: LorebaseError,
+    *,
+    row_offset: int = 0,
+    limit: int = 20,
+    locate: Locator | None = None,
+) -> list[str]:
+    """One line per validation finding or invalid request member."""
+    lines: list[str] = []
+    for issue in error.issues[:limit]:
+        path = list(issue.get("path") or [])
+        where = (locate(path) if locate else None) or _location(path, row_offset)
+        subject = " ".join(
+            str(issue[name]) for name in ("kind", "relation", "key", "attribute") if issue.get(name)
+        )
+        prefix = f"{where}: " if where else ""
+        suffix = f" [{issue['code']}]" if issue.get("code") else ""
+        lines.append(
+            f"  {prefix}{issue.get('message', '')}{suffix}" + (f" ({subject})" if subject else "")
+        )
+    for member in error.errors[:limit]:
+        lines.append(f"  {member.get('pointer', '')}: {member.get('message', '')}")
+    total = len(error.issues) + len(error.errors)
+    if total > limit:
+        lines.append(f"  ... and {total - limit} more")
+    return lines
+
+
+def describe(
+    error: LorebaseError, *, row_offset: int = 0, locate: Locator | None = None
+) -> list[str]:
+    """Lines to print for an error: the problem detail, what it carries and a hint."""
+    lines = [f"error: {error.message}"]
+    lines.extend(issue_lines(error, row_offset=row_offset, locate=locate))
+    if error.current_head:
+        lines.append(f"  the branch is now at {error.current_head}; read it again and retry")
+    if error.extra.get("proposals"):
+        lines.append(f"  open a Proposal at {error.extra['proposals']} instead")
+    if error.extra.get("permission"):
+        lines.append(f"  missing permission: {error.extra['permission']}")
+    if error.retry_after:
+        lines.append(f"  retry after {error.retry_after:g} s")
+    if error.request_id:
+        lines.append(f"  request id: {error.request_id}")
+    return lines
+
+
+def render_failure(error: Exception, *, json_mode: bool) -> tuple[str, int]:
+    """The text for standard error and the exit code of a failure."""
+    row_offset = 0
+    locate: Locator | None = None
+    committed: dict[str, Any] = {}
+    api_error: LorebaseError | None = None
+    notes: list[str] = []
+    if isinstance(error, ImportAbortedError):
+        api_error = error.cause
+        row_offset = error.first_row  # 1-based row numbers of the input file
+        locate = error.locate
+        committed = {
+            "committed_rows": error.committed_rows,
+            "committed_revisions": error.committed_revisions,
+            "first_row": error.first_row,
+            "last_row": error.last_row,
+        }
+        notes = [error.message]
+        code = error.exit_code
+    elif isinstance(error, LorebaseError):
+        api_error = error
+        code = exit_code_for(error)
+    elif isinstance(error, CliError):
+        code = error.exit_code
+    else:
+        raise error
+    if json_mode:
+        body: dict[str, Any] = {"message": str(error), **committed}
+        if api_error is not None:
+            body.update(
+                status=api_error.status,
+                code=api_error.code,
+                type=api_error.type,
+                detail=api_error.detail,
+                request_id=api_error.request_id,
+                extra=api_error.extra,
+            )
+        return json.dumps({"error": body}, indent=2), code
+    if api_error is None:
+        return f"error: {error}", code
+    lines = describe(api_error, row_offset=row_offset, locate=locate)
+    return "\n".join([*lines, *(f"  {note}" for note in notes)]), code

lorebase_cli/importing.py

@@ -0,0 +1,277 @@
+"""Importing rows from a file through the `import_records` and `import_links` Operations
+(`import_batch` is in `batch_import`).
+
+Rows are coerced against the schema of the target branch, grouped in batches (one request and
+one Revision each; the server commits very large requests in batches of its own) and sent in
+order. Progress goes to standard error. A rejected batch stops the import: earlier batches stay
+committed, the error says which rows were rejected, and re-running the same import is safe
+because imports upsert.
+"""
+
+from __future__ import annotations
+
+import itertools
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from lorebase_cli.coercion import (
+    KEY_COLUMN,
+    LINK_COLUMNS,
+    LINK_ENDS,
+    CoercionError,
+    attribute_types,
+    coerce_row,
+    is_missing,
+)
+from lorebase_cli.failures import CliError, ImportAbortedError
+from lorebase_client import LorebaseClient, LorebaseError
+
+Target = Literal["records", "links", "batch"]
+LINKS_MEMBER = "links"  # the member of a Record row that holds its Links
+Progress = Callable[["BatchResult"], None]
+
+
+@dataclass(frozen=True)
+class BatchResult:
+    """The outcome of one request."""
+
+    number: int
+    first_row: int
+    rows: int
+    edits: int
+    revisions: list[str]
+    status: str
+
+
+@dataclass
+class ImportReport:
+    """What an import did."""
+
+    target: Target
+    name: str
+    domain: str
+    branch: str | None
+    dry_run: bool
+    batches: list[BatchResult] = field(default_factory=list)
+
+    @property
+    def rows(self) -> int:
+        return sum(b.rows for b in self.batches)
+
+    @property
+    def edits(self) -> int:
+        return sum(b.edits for b in self.batches)
+
+    @property
+    def revisions(self) -> list[str]:
+        return [r for b in self.batches for r in b.revisions]
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "target": self.target,
+            "name": self.name,
+            "domain": self.domain,
+            "branch": self.branch,
+            "dry_run": self.dry_run,
+            "batches": len(self.batches),
+            "rows": self.rows,
+            "edits": self.edits,
+            "revisions": self.revisions,
+        }
+
+
+@dataclass(frozen=True)
+class Prepared:
+    """How rows of one target are coerced."""
+
+    types: Mapping[str, str]
+    extra_columns: tuple[str, ...]
+    renames: Mapping[str, str]
+    link_columns: Mapping[str, str] = field(default_factory=dict)  # Relation -> file column
+
+
+def prepare(
+    schema: Mapping[str, Any],
+    target: Target,
+    name: str,
+    *,
+    renames: Mapping[str, str] | None = None,
+    link_columns: Mapping[str, str] | None = None,
+) -> Prepared:
+    """Look the Kind or Relation up in the schema document and fix its column rules.
+
+    `link_columns` (Records only) names the file column that holds the key at the other end of
+    each Relation; those cells are sent as the `links` of the row.
+    """
+    if target == "records":
+        types = attribute_types(schema, "kinds", name)
+        kind_id, kind = next((i, k) for i, k in schema["kinds"].items() if k["api_name"] == name)
+        extra = () if kind.get("primary_key") else (KEY_COLUMN,)
+        if link_columns:
+            _check_link_relations(schema, kind_id, name, types, link_columns)
+        return Prepared(types, extra, dict(renames or {}), dict(link_columns or {}))
+    types = attribute_types(schema, "relations", name)
+    return Prepared(types, LINK_COLUMNS, {**LINK_ENDS, **(renames or {})})
+
+
+def _check_link_relations(
+    schema: Mapping[str, Any],
+    kind_id: str,
+    kind_name: str,
+    types: Mapping[str, str],
+    link_columns: Mapping[str, str],
+) -> None:
+    """Every `--link` Relation must be a stored Relation that starts at the Kind."""
+    if LINKS_MEMBER in types:
+        raise CliError(
+            f"{kind_name} has an Attribute named {LINKS_MEMBER!r}; --link cannot be used"
+        )
+    usable: set[str] = set()
+    for relation in schema.get("relations", {}).values():
+        if relation.get("backing", "explicit") != "explicit":
+            continue
+        if relation.get("from_kind") == kind_id:
+            usable.add(relation["api_name"])
+        if relation.get("to_kind") == kind_id and relation.get("inverse_api_name"):
+            usable.add(relation["inverse_api_name"])
+    for relation_name in link_columns:
+        if relation_name not in usable:
+            known = ", ".join(sorted(usable)) or "none"
+            raise CliError(
+                f"{relation_name!r} is not a stored Relation of {kind_name} (--link); "
+                f"it has: {known}"
+            )
+
+
+def _parse_pairs(pairs: Iterable[str], option: str, shape: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for pair in pairs:
+        left, separator, right = pair.partition("=")
+        if not separator or not left or not right:
+            raise CliError(f"{option} expects {shape}, got {pair!r}")
+        out[left] = right
+    return out
+
+
+def parse_renames(pairs: Iterable[str]) -> dict[str, str]:
+    """`--map file_column=attribute` options as a dict."""
+    return _parse_pairs(pairs, "--map", "column=attribute")
+
+
+def parse_link_columns(pairs: Iterable[str]) -> dict[str, str]:
+    """`--link relation=file_column` options as a dict."""
+    return _parse_pairs(pairs, "--link", "relation=column")
+
+
+def _link_targets(value: Any) -> Any:
+    """What a link cell holds: a key, a list of keys or an object with `key` and Attributes."""
+    if isinstance(value, list):
+        return [
+            item if isinstance(item, dict) else str(item) for item in value if not is_missing(item)
+        ]
+    return value if isinstance(value, dict) else str(value)
+
+
+def _split_links(
+    row: Mapping[str, Any], link_columns: Mapping[str, str]
+) -> tuple[Mapping[str, Any], dict[str, Any]]:
+    """The row without its link columns, and the `links` they make."""
+    if not link_columns:
+        return row, {}
+    rest = dict(row)
+    links: dict[str, Any] = {}
+    for relation, column in link_columns.items():
+        value = rest.pop(column, None)
+        if is_missing(value) or value == []:
+            continue
+        targets = _link_targets(value)
+        if targets != []:
+            links[relation] = targets
+    return rest, links
+
+
+def coerced_rows(
+    rows: Iterable[Mapping[str, Any]],
+    prepared: Prepared,
+    *,
+    ignore_unknown: bool,
+    source: str | None = None,
+) -> Iterator[dict[str, Any]]:
+    """Rows coerced one by one; a bad value names its row (1-based, header excluded) and, when
+    several files are read, `source`."""
+    where = f"{source}: " if source else ""
+    for number, row in enumerate(rows, start=1):
+        row, links = _split_links(row, prepared.link_columns)
+        try:
+            coerced = coerce_row(
+                prepared.types,
+                row,
+                renames=prepared.renames,
+                ignore_unknown=ignore_unknown,
+                extra_columns=prepared.extra_columns,
+            )
+        except CoercionError as error:
+            raise CliError(f"{where}row {number}: {error}") from None
+        if links:
+            coerced[LINKS_MEMBER] = links
+        yield coerced
+
+
+def run_import(
+    client: LorebaseClient,
+    *,
+    domain: str,
+    branch: str | None,
+    target: Target,
+    name: str,
+    rows: Iterable[dict[str, Any]],
+    batch_size: int,
+    dry_run: bool = False,
+    message: str | None = None,
+    progress: Progress | None = None,
+) -> ImportReport:
+    """Send `rows` in batches of `batch_size`; returns what was done."""
+    report = ImportReport(target, name, domain, branch, dry_run)
+    first_row = 1
+    for number, batch in enumerate(itertools.batched(rows, batch_size), start=1):
+        last_row = first_row + len(batch) - 1
+        note = f"{message} (rows {first_row}-{last_row})" if message else None
+        key = client.idempotency_key("import")  # a retry of this request cannot apply it twice
+        try:
+            if target == "records":
+                result = client.operations.import_records(
+                    domain,
+                    name,
+                    batch,
+                    branch=branch,
+                    dry_run=dry_run,
+                    message=note,
+                    idempotency_key=key,
+                )
+            else:
+                result = client.operations.import_links(
+                    domain,
+                    name,
+                    batch,
+                    branch=branch,
+                    dry_run=dry_run,
+                    message=note,
+                    idempotency_key=key,
+                )
+        except LorebaseError as error:
+            raise ImportAbortedError(
+                error,
+                first_row=first_row,
+                last_row=last_row,
+                committed_rows=report.rows,
+                committed_revisions=report.revisions,
+            ) from error
+        outcome = BatchResult(
+            number, first_row, len(batch), result.edit_count, result.revisions, result.status
+        )
+        report.batches.append(outcome)
+        if progress is not None:
+            progress(outcome)
+        first_row = last_row + 1
+    return report