open-agent-guide 0.5.0__py3-none-any.whl

oag_client/__init__.py

@@ -0,0 +1,8 @@
+"""Submission workflows without a Django or CLI dependency at import time."""
+
+from .client import Client
+from .pacing import SharedPacer
+from .pacing import shared_pacer
+from .reads import Reader
+
+__all__ = ["Client", "Reader", "SharedPacer", "shared_pacer"]

oag_client/catalog.py

@@ -0,0 +1,15 @@
+"""Read catalog guidance through the shared client's pacing and timeout policy."""
+
+from urllib.parse import quote
+
+from .client import Client
+from .types import Response
+
+
+def coverage(client: Client, product: str, *, deadline: float) -> Response:
+    """Return the server's report unchanged using a catalog-root client."""
+    return client.request(
+        "GET",
+        f"/api/v1/catalog/products/{quote(product, safe='')}/coverage/",
+        deadline=deadline,
+    )

oag_client/cli.py

@@ -0,0 +1,425 @@
+"""Argument parsing and process exits only; workflows are in-process APIs."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+from http import HTTPStatus
+from importlib.metadata import version as distribution_version
+from pathlib import Path
+from typing import TYPE_CHECKING
+from typing import Annotated
+
+import typer
+
+from .catalog import coverage as read_coverage
+from .client import Client
+from .journal import Journal
+from .journal import fingerprint
+from .pacing import READ_SPACING
+from .pacing import shared_pacer
+from .reads import Reader
+from .recovery import reconcile as reconcile_row
+from .render import Output
+from .render import guidance_hint
+from .render import render
+from .render import render_coverage
+from .render import render_coverage_failure
+from .transport import HTTPTransport
+from .types import ClientError
+from .types import Object
+from .types import failure_detail
+from .types import http_failure
+from .types import submission_id
+from .workflows import DEFAULT_TERMINAL_WATCH_SECONDS
+from .workflows import exit_code
+from .workflows import failed_read
+from .workflows import payloads
+from .workflows import retire as retire_batch
+from .workflows import status as read_status
+from .workflows import submit as submit_batch
+from .workflows import validate as validate_batch
+from .workflows import watch as watch_batch
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+app = typer.Typer(
+    no_args_is_help=True,
+    pretty_exceptions_enable=False,
+    add_completion=False,
+)
+OutputOption = Annotated[Output, typer.Option("--output", "-o")]
+TimeoutOption = Annotated[float, typer.Option("--timeout", min=0.01)]
+JournalOption = Annotated[Path, typer.Option("--journal")]
+
+
+def version_callback(value: bool) -> None:  # noqa: FBT001  -- Typer invokes an option callback with the parsed value positionally, so the parameter cannot be keyword-only
+    if value:
+        typer.echo(f"oag {distribution_version('open-agent-guide')}")
+        raise typer.Exit(0)
+
+
+@app.callback()
+def root(
+    *,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show the version and exit.",
+            callback=version_callback,
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    """Validate, submit, and watch immutable catalog proposals."""
+
+
+def require_token(token: str) -> None:
+    if not token:
+        msg = "OAG_TOKEN is required"
+        raise ClientError(msg)
+
+
+def run(
+    operation: Callable[[Client, str], int],
+    *,
+    catalog: bool = False,
+) -> None:
+    token = os.environ.get("OAG_TOKEN", "")
+    transport: HTTPTransport | None = None
+    try:
+        if not catalog:
+            require_token(token)
+        transport = (
+            HTTPTransport(token, allow_anonymous=True)
+            if catalog
+            else HTTPTransport(token)
+        )
+        base_url = os.environ.get("OAG_BASE_URL", "https://www.openagentguide.com")
+        # Coordinate pacing with any other processes on this host sharing the token,
+        # keyed by origin and a one-way token fingerprint (issue #1166).
+        pacer = shared_pacer(
+            base_url,
+            token,
+            read_spacing=float(os.environ.get("OAG_READ_SPACING", READ_SPACING)),
+        )
+        client = Client(
+            transport,
+            base_url,
+            pacer=pacer,
+            api_root="/api/v1/catalog/" if catalog else "/api/v1/submissions/",
+        )
+        code = operation(client, hashlib.sha256(token.encode()).hexdigest())
+    except (ClientError, ValueError, OSError) as exc:
+        # Paths and input JSON may contain secrets; only ClientError is display-safe.
+        message = (
+            str(exc)
+            if isinstance(exc, ClientError)
+            else "Invalid input or inaccessible file"
+        )
+        typer.echo(message.replace(token, "[REDACTED]") if token else message, err=True)
+        code = 2
+    except KeyboardInterrupt:
+        typer.echo("Cancelled; resume with the same journal", err=True)
+        code = 130
+    finally:
+        if transport is not None:
+            transport.close()
+    raise typer.Exit(code)
+
+
+def read_input(file: str) -> list[Object]:
+    return payloads(sys.stdin.read() if file == "-" else Path(file).read_text())
+
+
+def emit(
+    records: list[Object],
+    output: Output,
+    *,
+    require_all: bool = False,
+    cancelled: bool = False,
+) -> int:
+    typer.echo(render(records, output, cancelled=cancelled))
+    return 130 if cancelled else exit_code(records, require_all_merged=require_all)
+
+
+@app.command()
+def validate(
+    file: str,
+    output: OutputOption = Output.TEXT,
+    timeout: TimeoutOption = 300,
+) -> None:
+    """Validate a JSON object/array from FILE, or '-' for stdin, on the server."""
+
+    def execute(client: Client, account: str) -> int:
+        records = validate_batch(
+            client,
+            read_input(file),
+            deadline=client.clock.monotonic() + timeout,
+        )
+        return emit(records, output)
+
+    run(execute)
+
+
+@app.command()
+def submit(
+    file: str,
+    journal: JournalOption,
+    output: OutputOption = Output.TEXT,
+    timeout: TimeoutOption = 300,
+) -> None:
+    """Submit proposals; safely retry keyed uncertain rows using the same journal."""
+
+    def execute(client: Client, account: str) -> int:
+        rows = read_input(file)
+        identity: Object = {
+            "kind": "submit",
+            "base_url": client.base_url,
+            "account": account,
+            "input": fingerprint(rows),
+        }
+        with Journal(journal, identity) as store:
+            records = submit_batch(
+                client,
+                rows,
+                store,
+                deadline=client.clock.monotonic() + timeout,
+            )
+        return emit(records, output)
+
+    run(execute)
+
+
+@app.command()
+def status(
+    identifier: str,
+    output: OutputOption = Output.TEXT,
+    timeout: TimeoutOption = 60,
+    *,
+    require_all_merged: bool = False,
+) -> None:
+    """Read one submission and all linked evidence once."""
+
+    def execute(client: Client, account: str) -> int:
+        parsed_id = submission_id(identifier)
+        try:
+            record = read_status(
+                client,
+                parsed_id,
+                deadline=client.clock.monotonic() + timeout,
+            )
+        except ClientError as exc:
+            record = failed_read(parsed_id, exc)
+        return emit([record], output, require_all=require_all_merged)
+
+    run(execute)
+
+
+@app.command()
+def watch(  # noqa: PLR0913 -- Each parameter is a separate public CLI option.
+    journal: JournalOption,
+    identifiers: Annotated[list[str] | None, typer.Argument()] = None,
+    file: Annotated[Path | None, typer.Option("--file")] = None,
+    output: OutputOption = Output.TEXT,
+    timeout: TimeoutOption = DEFAULT_TERMINAL_WATCH_SECONDS,
+    *,
+    require_all_merged: bool = False,
+) -> None:
+    """Poll up to 100 IDs per request; --file reads one UUID per line."""
+
+    def execute(client: Client, account: str) -> int:
+        values = [*(identifiers or []), *(file.read_text().split() if file else [])]
+        ids = list(dict.fromkeys(submission_id(value) for value in values))
+        if not ids:
+            msg = "Provide submission IDs or --file"
+            raise ClientError(msg)
+        identity: Object = {
+            "kind": "watch",
+            "base_url": client.base_url,
+            "account": account,
+            "ids": list(ids),
+        }
+        last_hints: dict[str, str] = {}
+
+        def report_guidance(record: Object) -> None:
+            identifier = str(record.get("id", ""))
+            hint = guidance_hint(record)
+            if hint and last_hints.get(identifier) != hint:
+                typer.echo(f"{identifier}: {hint}", err=True)
+                last_hints[identifier] = hint
+
+        with Journal(journal, identity) as store:
+            records, cancelled = watch_batch(
+                client,
+                ids,
+                store,
+                deadline=client.clock.monotonic() + timeout,
+                on_update=report_guidance,
+            )
+        return emit(
+            records,
+            output,
+            require_all=require_all_merged,
+            cancelled=cancelled,
+        )
+
+    run(execute)
+
+
+def main() -> None:
+    app()
+
+
+@app.command()
+def reconcile(
+    file: str,
+    journal: JournalOption,
+    row: Annotated[int, typer.Option(min=0)],
+    identifier: Annotated[str, typer.Option("--id")],
+    output: OutputOption = Output.TEXT,
+) -> None:
+    """Confirm a journal row's ID after manually inspecting the server submission."""
+
+    def execute(client: Client, account: str) -> int:
+        rows = read_input(file)
+        identity: Object = {
+            "kind": "submit",
+            "base_url": client.base_url,
+            "account": account,
+            "input": fingerprint(rows),
+        }
+        with Journal(journal, identity) as store:
+            record = reconcile_row(
+                client,
+                store,
+                row,
+                identifier,
+                deadline=client.clock.monotonic() + 60,
+            )
+        return emit([record], output)
+
+    run(execute)
+
+
+def emit_coverage_failure(failure: Object, output: Output) -> int:
+    """Report a coverage read failure consistently with the submission reads.
+
+    Machine output carries the shared failure envelope on stdout; text keeps the
+    diagnostic on stderr. Any read failure exits 3, matching a failed-to-read
+    submission record; input and configuration errors still exit 2 via `run`.
+    """
+    typer.echo(render_coverage_failure(failure, output), err=output == Output.TEXT)
+    return 3
+
+
+@app.command()
+def coverage(
+    product: str,
+    output: OutputOption = Output.TEXT,
+    timeout: TimeoutOption = 30,
+) -> None:
+    """Read PRODUCT's coverage gaps and evidence guidance by UUID or slug."""
+
+    def execute(client: Client, account: str) -> int:
+        try:
+            response = read_coverage(
+                client,
+                product,
+                deadline=client.clock.monotonic() + timeout,
+            )
+        except ClientError as exc:
+            return emit_coverage_failure(failure_detail(exc), output)
+        if response.status != HTTPStatus.OK:
+            return emit_coverage_failure(http_failure(response), output)
+        typer.echo(render_coverage(response.body, output, status=response.status))
+        return 0
+
+    run(execute, catalog=True)
+
+
+@app.command()
+def get(
+    path: str,
+    timeout: TimeoutOption = 60,
+) -> None:
+    """Read a catalog or submissions read-API PATH through the shared read lane.
+
+    PATH may be a relative read-API path (`/api/v1/catalog/products/?page=2`) or a
+    same-origin absolute URL, so a pagination `next` link can be passed straight
+    back without stripping its origin. An absolute PATH is accepted only when its
+    scheme and host match `OAG_BASE_URL` with no userinfo; foreign origins,
+    unsupported schemes, and disallowed paths exit 2 without a request.
+
+    The read reserves a slot on the same host-local pacing lane the write commands
+    use and honors shared Retry-After cooldowns (issue #1734), so benchmark
+    discovery and readbacks stop issuing uncoordinated direct GETs. Catalog reads
+    work anonymously; the submissions field contract needs `OAG_TOKEN`. The body is
+    printed as JSON; a failed read exits 3 with the server's sanitized envelope and
+    an input or configuration error exits 2.
+    """
+    token = os.environ.get("OAG_TOKEN", "")
+    base_url = os.environ.get("OAG_BASE_URL", "https://www.openagentguide.com")
+    reader: Reader | None = None
+    try:
+        reader = Reader(base_url, token, read_timeout=timeout)
+        typer.echo(json.dumps(reader.get(path)))
+        code = 0
+    except ClientError as exc:
+        if exc.failure is not None:
+            typer.echo(json.dumps(exc.failure), err=True)
+            code = 3
+        else:
+            message = str(exc).replace(token, "[REDACTED]") if token else str(exc)
+            typer.echo(message, err=True)
+            code = 2
+    finally:
+        if reader is not None:
+            reader.close()
+    raise typer.Exit(code)
+
+
+@app.command()
+def retire(  # noqa: PLR0913 -- Each parameter is a separate public CLI option.
+    identifier: str,
+    successor: Annotated[
+        list[str] | None,
+        typer.Option("--successor", help="Newer replacement ID; repeat to supersede."),
+    ] = None,
+    reason: Annotated[str, typer.Option("--reason")] = "",
+    output: OutputOption = Output.TEXT,
+    timeout: TimeoutOption = 60,
+    *,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Required to confirm this terminal mutation."),
+    ] = False,
+) -> None:
+    """Withdraw your own open submission, or supersede it with newer IDs."""
+
+    def execute(client: Client, account: str) -> int:
+        parsed_id = submission_id(identifier)
+        successors = [submission_id(value) for value in (successor or [])]
+        if not force:
+            # Retirement closes an open proposal for good. Gate it behind an
+            # explicit flag so the tool never withdraws or supersedes on its own.
+            msg = (
+                "retire permanently closes an open submission; pass --force to "
+                "confirm. This tool never withdraws or supersedes automatically."
+            )
+            raise ClientError(msg)
+        record = retire_batch(
+            client,
+            parsed_id,
+            successor_ids=successors,
+            reason=reason,
+            deadline=client.clock.monotonic() + timeout,
+        )
+        return emit([record], output)
+
+    run(execute)