uqadm 2026.22.0.dev0__py3-none-any.whl

uqadm/__init__.py

@@ -0,0 +1,3 @@
+"""Unique admin CLI package (uqadm)."""
+
+__version__ = "0.1.0"

uqadm/__main__.py

@@ -0,0 +1,4 @@
+from uqadm.cli import main
+
+if __name__ == "__main__":
+    main()

uqadm/chat/__init__.py

@@ -0,0 +1,200 @@
+"""Chat sub-app — send messages and inspect history."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from uqadm.chat.history import cmd_history
+from uqadm.chat.send import cmd_send
+
+chat_app = typer.Typer(
+    name="chat",
+    help="Chat with an assistant or inspect chat history.",
+    no_args_is_help=True,
+)
+
+_STOP_ON_VALUES = {"stoppedStreamingAt", "completedAt"}
+_SLOT_HELP = (
+    "Credential slot (loads .{SLOT}.env). "
+    "Omit to use the configured default (see `uqadm env set-default`)."
+)
+
+
+def _get_cwd(ctx: typer.Context) -> Path | None:
+    return (ctx.obj or {}).get("cwd")
+
+
+@chat_app.command(
+    "send", short_help="Send a message to an assistant and print the reply."
+)
+def chat_send(
+    ctx: typer.Context,
+    assistant_id: Annotated[
+        str,
+        typer.Argument(
+            metavar="ASSISTANT_ID",
+            help="The assistant ID to send the message to.",
+        ),
+    ],
+    slot: Annotated[
+        Optional[str],
+        typer.Option("--slot", help=_SLOT_HELP),
+    ] = None,
+    text: Annotated[
+        Optional[str],
+        typer.Option("--text", help="Message text (alternative to --file or stdin)."),
+    ] = None,
+    file: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--file",
+            help="Read message from this file (alternative to --text or stdin).",
+            exists=True,
+            dir_okay=False,
+        ),
+    ] = None,
+    chat_id: Annotated[
+        Optional[str],
+        typer.Option("--chat-id", help="Continue an existing chat thread."),
+    ] = None,
+    tool_choices: Annotated[
+        Optional[list[str]],
+        typer.Option(
+            "--tool",
+            help="Force a specific tool (repeatable: --tool web_search --tool code_interpreter).",
+        ),
+    ] = None,
+    poll_interval: Annotated[
+        float,
+        typer.Option(
+            "--poll-interval",
+            help="Seconds between completion polls.",
+            show_default=True,
+        ),
+    ] = 1.0,
+    max_wait: Annotated[
+        float,
+        typer.Option(
+            "--max-wait",
+            help="Maximum seconds to wait for a response.",
+            show_default=True,
+        ),
+    ] = 300.0,
+    stop_on: Annotated[
+        str,
+        typer.Option(
+            "--stop-on",
+            help="Stop condition: stoppedStreamingAt or completedAt.",
+            show_default=True,
+        ),
+    ] = "stoppedStreamingAt",
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Print the full Space.Message as JSON."),
+    ] = False,
+) -> None:
+    """Send a prompt to an assistant and print the reply.
+
+    The chat_id of the new (or continued) thread is printed to stderr so you
+    can pass it to --chat-id in a follow-up call.
+
+    Examples:
+
+      uqadm chat send asst_abc123 --text "Hello"
+      uqadm chat send asst_abc123 --text "Follow up" --chat-id chat_xyz
+      uqadm chat send asst_abc123 --slot prod --file ./prompt.txt
+      uqadm chat send asst_abc123 --text "Search this" --tool web_search
+      uqadm chat send asst_abc123 --text "Run code" --tool code_interpreter --tool web_search
+      echo "Summarize this" | uqadm chat send asst_abc123
+    """
+    if stop_on not in _STOP_ON_VALUES:
+        typer.echo(
+            f"--stop-on must be one of: {', '.join(sorted(_STOP_ON_VALUES))}",
+            err=True,
+        )
+        raise typer.Exit(2)
+    cmd_send(
+        assistant_id,
+        slot=slot,
+        text=text,
+        file=file,
+        chat_id=chat_id,
+        tool_choices=tool_choices,
+        poll_interval=poll_interval,
+        max_wait=max_wait,
+        stop_on=stop_on,
+        as_json=as_json,
+        cwd=_get_cwd(ctx),
+    )
+
+
+@chat_app.command("history", short_help="Fetch and display chat history.")
+def chat_history(
+    ctx: typer.Context,
+    chat_id: Annotated[
+        str,
+        typer.Argument(
+            metavar="CHAT_ID",
+            help="The chat ID to fetch history for.",
+        ),
+    ],
+    slot: Annotated[
+        Optional[str],
+        typer.Option("--slot", help=_SLOT_HELP),
+    ] = None,
+    max_tokens: Annotated[
+        int,
+        typer.Option(
+            "--max-tokens",
+            help="Token budget for the history window.",
+            show_default=True,
+        ),
+    ] = 8000,
+    percent: Annotated[
+        float,
+        typer.Option(
+            "--percent",
+            help="Fraction of max_tokens allocated to history.",
+            show_default=True,
+        ),
+    ] = 0.15,
+    max_messages: Annotated[
+        int,
+        typer.Option(
+            "--max-messages",
+            help="Maximum number of messages to consider.",
+            show_default=True,
+        ),
+    ] = 4,
+    show_full: Annotated[
+        bool,
+        typer.Option(
+            "--full", help="Show the full history instead of the selected window."
+        ),
+    ] = False,
+    as_json: Annotated[
+        bool,
+        typer.Option("--json", help="Print raw message structures as JSON."),
+    ] = False,
+) -> None:
+    """Fetch chat history and display the selected token window (or full with --full).
+
+    Examples:
+
+      uqadm chat history chat_xyz
+      uqadm chat history chat_xyz --full --json
+      uqadm chat history chat_xyz --slot prod
+    """
+    cmd_history(
+        chat_id,
+        slot=slot,
+        max_tokens=max_tokens,
+        percent=percent,
+        max_messages=max_messages,
+        show_full=show_full,
+        as_json=as_json,
+        cwd=_get_cwd(ctx),
+    )

uqadm/chat/history.py

@@ -0,0 +1,77 @@
+"""Fetch and display chat history for a given chat ID."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import typer
+from unique_sdk.utils.chat_history import load_history
+
+from uqadm.chat.render import print_framed_history
+from uqadm.core.auth_debug import echo_credential_debug_if_auth_failure
+from uqadm.core.env import MissingSlotEnvFileError, config_for_slot
+from uqadm.core.slot import MissingDefaultSlotError, resolve_slot
+
+
+def cmd_history(
+    chat_id: str,
+    *,
+    slot: str | None,
+    max_tokens: int,
+    percent: float,
+    max_messages: int,
+    show_full: bool,
+    as_json: bool,
+    cwd: Path | None,
+) -> None:
+    """Load chat history and display the selected window."""
+    try:
+        resolved_slot = resolve_slot(slot)
+    except MissingDefaultSlotError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(2)
+
+    try:
+        cfg = config_for_slot(resolved_slot, cwd=cwd)
+    except MissingSlotEnvFileError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(2)
+
+    try:
+        import unique_sdk
+
+        unique_sdk.api_key = cfg.api_key
+        unique_sdk.app_id = cfg.app_id
+        unique_sdk.api_base = cfg.api_base
+
+        if show_full:
+            # Message.list returns the complete untruncated conversation.
+            # load_history always drops the last 2 messages (context-injection
+            # behaviour) so we bypass it for --full.
+            list_result = unique_sdk.Message.list(
+                user_id=cfg.user_id,
+                company_id=cfg.company_id,
+                chatId=chat_id,
+            )
+            target: list[dict[str, Any]] = [dict(m) for m in list_result.data]
+        else:
+            _, selected_history = load_history(
+                cfg.user_id,
+                cfg.company_id,
+                chat_id,
+                max_tokens,
+                percentOfMaxTokens=percent,
+                maxMessages=max_messages,
+            )
+            target = selected_history
+    except Exception as exc:
+        typer.echo(f"chat history failed: {exc}", err=True)
+        echo_credential_debug_if_auth_failure(cfg, exc, label="chat history")
+        raise typer.Exit(1)
+
+    if as_json:
+        typer.echo(json.dumps(target, indent=2, default=str))
+    else:
+        print_framed_history(target)

uqadm/chat/render.py

@@ -0,0 +1,115 @@
+"""Shared terminal rendering helpers for chat commands."""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Mapping
+from typing import Any
+
+import typer
+
+# Strips ANSI/OSC/DCS/SOS/PM/APC escape sequences and raw C0/C1 control bytes
+# from untrusted server content before it reaches the terminal.
+#
+# Preserved intentionally: \t (0x09), \n (0x0a) — legitimate text content.
+# \r (0x0d) is normalised away to prevent carriage-return overwrite attacks.
+_CONTROL_RE = re.compile(
+    r"\x1b"
+    r"(?:"
+    r"\[[0-9;:<=>?]*[ -/]*[@-~]"  # CSI  — SGR, cursor movement, etc.
+    r"|\][^\x07\x1b]*(?:\x07|\x1b\\)"  # OSC  — title, hyperlink, iTerm2, …
+    r"|[PX^_][^\x1b]*(?:\x1b\\|$)"  # DCS / SOS / PM / APC
+    r"|[@-~]"  # Fe/Fp two-byte sequences (ESC M, ESC c RIS, ESC 7/8, …)
+    r")"
+    r"|[\x00-\x08\x0b\x0c\x0e-\x1f\x7f\x80-\x9f]"  # raw C0/C1 (keep \t \n)
+)
+
+
+def _sanitize(value: str) -> str:
+    """Strip terminal control sequences from untrusted server-supplied text."""
+    cleaned = _CONTROL_RE.sub("", value)
+    # Normalise \r\n → \n and lone \r → \n to prevent carriage-return overwrite.
+    cleaned = cleaned.replace("\r\n", "\n").replace("\r", "\n")
+    return cleaned
+
+
+_ROLE_LABEL = {
+    "user": "You",
+    "assistant": "Assistant",
+    "system": "System",
+}
+
+
+def rule() -> None:
+    width = typer.get_terminal_size().columns if sys.stdout.isatty() else 60
+    typer.echo("─" * width)
+
+
+def _render_references(references: list[dict[str, Any]]) -> None:
+    rule()
+    typer.echo("References")
+    for ref in sorted(references, key=lambda r: r.get("sequenceNumber", 0)):
+        seq = ref.get("sequenceNumber", "?")
+        name = _sanitize(ref.get("name") or ref.get("source") or "(unknown)")
+        url = _sanitize(ref.get("url") or "")
+        line = f"  [{seq}] {name}"
+        if url:
+            line += f"  {url}"
+        typer.echo(line)
+
+
+def _render_assessments(assessments: list[dict[str, Any]]) -> None:
+    rule()
+    typer.echo("Evaluation")
+    for a in assessments:
+        status = _sanitize(a.get("status") or "")
+        label = _sanitize(a.get("label") or "")
+        title = _sanitize(a.get("title") or "")
+        explanation = _sanitize((a.get("explanation") or "").strip())
+        header_parts = [p for p in [status, label, title] if p]
+        typer.echo(f"  {' · '.join(header_parts)}" if header_parts else "")
+        if explanation:
+            typer.echo(f"  {explanation}")
+
+
+def print_framed_message(result: Mapping[str, Any]) -> None:
+    """Print a single assistant reply with chat_id, answer, references, evaluation."""
+    chat_id = _sanitize(result.get("chatId") or result.get("chat_id") or "")
+    reply_text = _sanitize((result.get("text") or "").strip())
+    references: list[dict[str, Any]] = result.get("references") or []
+    assessments: list[dict[str, Any]] = result.get("assessment") or []
+
+    rule()
+    typer.echo(f"chat_id: {chat_id}")
+    rule()
+    typer.echo(reply_text)
+
+    if references:
+        _render_references(references)
+    if assessments:
+        _render_assessments(assessments)
+
+    rule()
+
+
+def print_framed_history(messages: list[dict[str, Any]]) -> None:
+    """Print a sequence of chat messages, each in its own framed block."""
+    for msg in messages:
+        raw_role = _sanitize((msg.get("role") or "unknown").lower())
+        label = _ROLE_LABEL.get(raw_role, raw_role.capitalize())
+        text = _sanitize((msg.get("text") or msg.get("content") or "").strip())
+        references: list[dict[str, Any]] = msg.get("references") or []
+        assessments: list[dict[str, Any]] = msg.get("assessment") or []
+
+        rule()
+        typer.echo(label)
+        rule()
+        typer.echo(text)
+
+        if references:
+            _render_references(references)
+        if assessments:
+            _render_assessments(assessments)
+
+    rule()

uqadm/chat/send.py

@@ -0,0 +1,103 @@
+"""Send a message to an assistant and wait for completion."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+from typing import Literal, cast
+
+import typer
+from unique_sdk import Space
+from unique_sdk.utils.chat_in_space import send_message_and_wait_for_completion
+
+from uqadm.chat.render import print_framed_message
+from uqadm.core.auth_debug import echo_credential_debug_if_auth_failure
+from uqadm.core.env import MissingSlotEnvFileError, config_for_slot
+from uqadm.core.slot import MissingDefaultSlotError, resolve_slot
+
+StopCondition = Literal["stoppedStreamingAt", "completedAt"]
+
+
+def _read_message_text(
+    text: str | None,
+    file: Path | None,
+) -> str:
+    """Resolve message body: --text wins, then --file, then stdin."""
+    if text is not None:
+        return text
+    if file is not None:
+        return file.read_text(encoding="utf-8")
+    if not sys.stdin.isatty():
+        return sys.stdin.read()
+    typer.echo(
+        "Error: provide message via --text TEXT, --file PATH, or pipe to stdin.",
+        err=True,
+    )
+    raise typer.Exit(2)
+
+
+def cmd_send(
+    assistant_id: str,
+    *,
+    slot: str | None,
+    text: str | None,
+    file: Path | None,
+    chat_id: str | None,
+    tool_choices: list[str] | None,
+    poll_interval: float,
+    max_wait: float,
+    stop_on: str,
+    as_json: bool,
+    cwd: Path | None,
+) -> None:
+    """Send a message to an assistant and print the reply."""
+    try:
+        resolved_slot = resolve_slot(slot)
+    except MissingDefaultSlotError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(2)
+
+    message_text = _read_message_text(text, file)
+
+    try:
+        cfg = config_for_slot(resolved_slot, cwd=cwd)
+    except MissingSlotEnvFileError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(2)
+
+    try:
+        import unique_sdk
+
+        unique_sdk.api_key = cfg.api_key
+        unique_sdk.app_id = cfg.app_id
+        unique_sdk.api_base = cfg.api_base
+
+        result: Space.Message = asyncio.run(
+            send_message_and_wait_for_completion(
+                user_id=cfg.user_id,
+                company_id=cfg.company_id,
+                assistant_id=assistant_id,
+                text=message_text,
+                chat_id=chat_id,
+                tool_choices=tool_choices or None,
+                poll_interval=poll_interval,
+                max_wait=max_wait,
+                stop_condition=cast(StopCondition, stop_on),
+            )
+        )
+    except TimeoutError:
+        typer.echo(
+            f"Timed out after {max_wait}s waiting for assistant response.", err=True
+        )
+        raise typer.Exit(1)
+    except Exception as exc:
+        typer.echo(f"chat send failed: {exc}", err=True)
+        echo_credential_debug_if_auth_failure(cfg, exc, label="chat send")
+        raise typer.Exit(1)
+
+    if as_json:
+        typer.echo(json.dumps(dict(result), indent=2, default=str))
+    else:
+        print_framed_message(result)

uqadm/cli.py

@@ -0,0 +1,69 @@
+"""Typer entry point for ``uqadm``."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from uqadm import __version__
+from uqadm.chat import chat_app
+from uqadm.core.env import MissingSlotEnvFileError
+from uqadm.env import env_app
+from uqadm.install import install_command
+from uqadm.space import space_app
+
+app = typer.Typer(
+    name="uqadm",
+    help="Unique admin CLI — space admin (uses same UNIQUE_* env as unique-cli).",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+app.add_typer(space_app, name="space")
+app.add_typer(chat_app, name="chat")
+app.add_typer(env_app, name="env")
+app.command("install")(install_command)
+
+
+@app.callback(invoke_without_command=True)
+def root_callback(
+    ctx: typer.Context,
+    cwd: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--cwd",
+            help=(
+                "Directory for per-slot env files (.{slot}.env or {slot}.env). "
+                "Defaults to ~/.uqadm/envs/ then process cwd."
+            ),
+            file_okay=False,
+            dir_okay=True,
+        ),
+    ] = None,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            help="Show version and exit.",
+            is_eager=True,
+        ),
+    ] = False,
+) -> None:
+    if version:
+        typer.echo(f"uqadm {__version__}")
+        raise typer.Exit()
+    ctx.ensure_object(dict)
+    ctx.obj["cwd"] = cwd
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+
+def main() -> None:
+    try:
+        app()
+    except MissingSlotEnvFileError as exc:
+        typer.echo(str(exc), err=True)
+        sys.exit(2)

uqadm/core/__init__.py

@@ -0,0 +1 @@
+"""Shared infrastructure for uqadm (paths, env loading, slot resolution, auth debug)."""

uqadm/core/auth_debug.py

@@ -0,0 +1,85 @@
+"""Print resolved credential context when API calls fail with auth-like errors."""
+
+from __future__ import annotations
+
+import typer
+from unique_sdk import AuthenticationError
+from unique_sdk.cli.config import Config
+
+
+def is_likely_auth_failure(exc: BaseException) -> bool:
+    """Heuristic: 401, AuthenticationError, or common unauthorized wording."""
+    if isinstance(exc, AuthenticationError):
+        return True
+    status = getattr(exc, "http_status", None)
+    if status == 401:
+        return True
+    lowered = str(exc).lower()
+    if "unauthorized" in lowered or "401" in lowered:
+        return True
+    return False
+
+
+def _describe_api_key(api_key: str) -> str:
+    if not api_key:
+        return (
+            "(empty — often OK on localhost / secured cluster; otherwise set "
+            "UNIQUE_API_KEY)"
+        )
+    return f"set, length {len(api_key)} (redacted)"
+
+
+def _describe_optional(value: str, *, empty_label: str) -> str:
+    stripped = value.strip()
+    if not stripped:
+        return empty_label
+    return repr(stripped)
+
+
+def format_credential_debug_lines(
+    cfg: Config,
+    *,
+    label: str | None = None,
+    exc: BaseException | None = None,
+) -> list[str]:
+    """Human-readable lines (no full secrets); suitable for stderr."""
+    title = "Credential snapshot (values after slot env load + SDK normalization)"
+    lines: list[str] = [title + ":"]
+    if label:
+        lines.append(f"  Context: {label}")
+    lines.extend(
+        [
+            f"  UNIQUE_USER_ID:     {cfg.user_id!r}",
+            f"  UNIQUE_COMPANY_ID:  {cfg.company_id!r}",
+            f"  UNIQUE_APP_ID:      {_describe_optional(cfg.app_id, empty_label='(empty)')}",
+            f"  UNIQUE_API_BASE:    {cfg.api_base!r}",
+            f"  UNIQUE_API_KEY:     {_describe_api_key(cfg.api_key)}",
+        ]
+    )
+    if exc is not None:
+        status = getattr(exc, "http_status", None)
+        if status is not None:
+            lines.append(f"  API HTTP status:     {status!r}")
+        rid = getattr(exc, "request_id", None)
+        if rid:
+            lines.append(f"  API Request-Id:      {rid!r}")
+    lines.append(
+        "  (Toolkit-style unique_auth_*, unique_app_*, and unique_api_* names in "
+        "the env file are copied into UNIQUE_* when the latter are unset; "
+        "UNIQUE_* wins when both are set.)"
+    )
+    return lines
+
+
+def echo_credential_debug_if_auth_failure(
+    cfg: Config,
+    exc: BaseException,
+    *,
+    label: str | None = None,
+) -> None:
+    """If ``exc`` looks like an auth problem, print ``cfg`` to stderr."""
+    if not is_likely_auth_failure(exc):
+        return
+    typer.echo("", err=True)
+    for line in format_credential_debug_lines(cfg, label=label, exc=exc):
+        typer.echo(line, err=True)

uqadm/core/config_file.py

@@ -0,0 +1,38 @@
+"""Read and write ``~/.uqadm/config.toml`` (default slot and other settings)."""
+
+from __future__ import annotations
+
+import tomllib
+from typing import Any
+
+import tomli_w
+
+from uqadm.core.paths import config_path
+
+
+def load_config() -> dict[str, Any]:
+    """Return the parsed config, or an empty dict if the file does not exist."""
+    path = config_path()
+    if not path.is_file():
+        return {}
+    with path.open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def save_config(data: dict[str, Any]) -> None:
+    """Persist ``data`` to ``config.toml``, creating parent dirs as needed."""
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(tomli_w.dumps(data).encode())
+
+
+def get_default_slot() -> str | None:
+    """Return the configured default slot name, or ``None`` if unset."""
+    return load_config().get("default_slot")
+
+
+def set_default_slot(slot: str) -> None:
+    """Persist ``slot`` as the default in ``config.toml``."""
+    data = load_config()
+    data["default_slot"] = slot
+    save_config(data)