lql-cli 0.2.0__py3-none-any.whl

lql/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

lql/_opts.py

@@ -0,0 +1,7 @@
+from typing import Annotated, Optional
+
+import typer
+
+ProfileOpt = Annotated[Optional[str], typer.Option("--profile", help="Profile to use")]
+ApiUrlOpt = Annotated[Optional[str], typer.Option("--api-url", help="Override API base URL")]
+JsonOpt = Annotated[bool, typer.Option("--json", help="Output raw JSON")]

lql/api.py

@@ -0,0 +1,69 @@
+from typing import Optional
+
+import httpx
+import typer
+
+from .config import get_api_url, get_token, validate_api_url
+from .output import print_error
+
+# Maps HTTP status -> process exit code (parity with the TS client).
+_EXIT_MAP = {401: 2, 403: 2, 404: 3, 409: 4}
+
+
+class ApiClient:
+    def __init__(self, profile: Optional[str] = None, api_url: Optional[str] = None):
+        # Validate an explicitly-passed --api-url too; get_api_url() validates
+        # the env/profile path.
+        base = validate_api_url(api_url) if api_url else get_api_url(profile)
+        token = get_token(profile)
+        if not token:
+            print_error(
+                "Not authenticated. Run `lql login` or set LQL_API_KEY environment variable.",
+                "unauthenticated",
+            )
+            raise typer.Exit(2)
+        self._client = httpx.Client(
+            base_url=base.rstrip("/"),
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=60.0,
+        )
+
+    def _request(self, method: str, path: str, *, params=None, json=None) -> httpx.Response:
+        try:
+            resp = self._client.request(method, path, params=params, json=json)
+        except httpx.RequestError as e:
+            print_error(str(e) or "Network error", "network_error")
+            raise typer.Exit(1)
+
+        if resp.status_code >= 400:
+            body = None
+            try:
+                body = resp.json()
+            except Exception:
+                body = None
+            message = None
+            if isinstance(body, dict):
+                if isinstance(body.get("detail"), str):
+                    message = body["detail"]
+                elif isinstance(body.get("message"), str):
+                    message = body["message"]
+            message = message or f"Request failed (HTTP {resp.status_code})"
+            print_error(message, f"http_{resp.status_code}")
+            code = _EXIT_MAP.get(resp.status_code, 5 if resp.status_code >= 500 else 1)
+            raise typer.Exit(code)
+        return resp
+
+    def get(self, path, *, params=None):
+        return self._request("GET", path, params=params)
+
+    def post(self, path, *, params=None, json=None):
+        return self._request("POST", path, params=params, json=json)
+
+    def put(self, path, *, params=None, json=None):
+        return self._request("PUT", path, params=params, json=json)
+
+    def patch(self, path, *, params=None, json=None):
+        return self._request("PATCH", path, params=params, json=json)
+
+    def delete(self, path, *, params=None):
+        return self._request("DELETE", path, params=params)

lql/cli.py

@@ -0,0 +1,93 @@
+import sys
+from typing import Annotated, Optional
+
+import typer
+
+from . import __version__
+from .output import print_error
+from .commands import (
+    annotations,
+    auth,
+    buckets,
+    datasets,
+    edits,
+    evals,
+    highlights,
+    instructions,
+    issues,
+    reports,
+    skills,
+    spec,
+    workspaces,
+)
+
+app = typer.Typer(
+    name="lql",
+    help=(
+        "CLI for the Liquid DataViewer platform — scriptable access for agents and humans.\n\n"
+        "If you are an AI agent: run `lql instructions` to get a full reference with all "
+        "commands, flags, examples, and common workflows in a single read."
+    ),
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        sys.stdout.write(f"{__version__}\n")
+        raise typer.Exit()
+
+
+@app.callback()
+def main_callback(
+    version: Annotated[
+        Optional[bool],
+        typer.Option("--version", callback=_version_callback, is_eager=True, help="Show version and exit"),
+    ] = None,
+) -> None:
+    pass
+
+
+# Command groups
+auth.register(app)  # adds `auth` sub-app + top-level login/logout/whoami aliases
+app.add_typer(workspaces.app, name="workspaces")
+app.add_typer(datasets.app, name="datasets")
+app.add_typer(evals.app, name="eval")
+app.add_typer(edits.app, name="edits")
+app.add_typer(spec.app, name="spec")
+app.add_typer(annotations.app, name="annotations")
+app.add_typer(highlights.app, name="highlights")
+app.add_typer(issues.app, name="issues")
+app.add_typer(reports.app, name="reports")
+app.add_typer(buckets.app, name="buckets")
+
+# Single commands
+app.command("instructions", help="Print a full reference for agents and humans")(instructions.instructions)
+app.add_typer(skills.app, name="skills")
+
+
+@app.command("update")
+def update() -> None:
+    """Show how to update lql to the latest version."""
+    sys.stdout.write(
+        "To update lql, use the tool you installed it with:\n"
+        "  uv tool upgrade lql        # if installed via `uv tool install`\n"
+        "  pipx upgrade lql           # if installed via pipx\n"
+        "  pip install --upgrade lql  # if installed via pip\n"
+    )
+
+
+def main() -> None:
+    # Mirror the TS top-level catch: unexpected errors surface as the documented
+    # machine-readable contract, not a traceback. Typer/Click exits (SystemExit)
+    # and KeyboardInterrupt are BaseException, so they pass through untouched.
+    try:
+        app()
+    except Exception as e:  # noqa: BLE001
+        print_error(str(e) or "Unexpected error", "unexpected_error")
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

lql/commands/annotations.py

@@ -0,0 +1,69 @@
+import sys
+from typing import Annotated, Optional
+
+import typer
+
+from .._opts import ApiUrlOpt, JsonOpt, ProfileOpt
+from ..api import ApiClient
+from ..output import print_json, print_table
+from ..sessions import resolve_session_id
+from ..util import q
+
+app = typer.Typer(help="Manage annotations")
+
+SessionOpt = Annotated[Optional[str], typer.Option("--session", help="Target a specific review session (advanced)")]
+
+
+@app.command("list")
+def list_annotations(
+    dataset_id: Annotated[str, typer.Argument(help="Dataset ID")],
+    session: SessionOpt = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """List annotations for a dataset."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    session_id = resolve_session_id(client, dataset_id, session)
+    items = client.get(f"/v1/sessions/{q(session_id)}/annotations").json()
+    print_table(
+        ["ID", "Row", "Rating", "Note"],
+        [
+            [
+                a.get("id") or "",
+                a.get("row_external_id") or "",
+                a.get("rating") if a.get("rating") is not None else "",
+                a.get("note") or "",
+            ]
+            for a in items
+        ],
+        json_out,
+        items,
+    )
+
+
+@app.command("add")
+def add(
+    dataset_id: Annotated[str, typer.Argument(help="Dataset ID")],
+    row: Annotated[str, typer.Option("--row", help="Row external ID")],
+    rating: Annotated[Optional[float], typer.Option("--rating", help="Rating value")] = None,
+    note: Annotated[Optional[str], typer.Option("--note", help="Note text")] = None,
+    session: SessionOpt = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Add an annotation to a dataset row."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    session_id = resolve_session_id(client, dataset_id, session)
+    body: dict = {"row_external_id": row}
+    if rating is not None:
+        # Match JS Number(): send an int when the value is integral (rating 1, not 1.0).
+        body["rating"] = int(rating) if float(rating).is_integer() else rating
+    if note is not None:
+        body["note"] = note
+    data = client.post(f"/v1/sessions/{q(session_id)}/annotations", json=body).json()
+    if json_out:
+        print_json(data)
+    else:
+        sys.stdout.write(f"Created annotation: {data.get('id', 'ok')}\n")

lql/commands/auth.py

@@ -0,0 +1,162 @@
+import os
+import sys
+import time
+import webbrowser
+from typing import Annotated, Optional
+
+import httpx
+import typer
+
+from .._opts import ApiUrlOpt, JsonOpt, ProfileOpt
+from ..api import ApiClient
+from ..config import get_api_url, read_config, validate_api_url, write_config
+from ..output import print_error, print_json, print_table
+from ..util import q
+
+BROWSER_BASE_URL = "https://dataviewer.liquid.ai"
+
+
+def _do_login(profile: Optional[str], api_url: Optional[str]) -> None:
+    api = validate_api_url(api_url) if api_url else get_api_url(profile)
+    profile_name = profile or "default"
+
+    env_token = os.environ.get("LQL_API_KEY")
+    if env_token:
+        config = read_config() or {"current_profile": "default", "profiles": {}}
+        existing = config["profiles"].get(profile_name, {})
+        config["profiles"][profile_name] = {**existing, "token": env_token, "api_url": api}
+        config["current_profile"] = profile_name
+        write_config(config)
+        sys.stdout.write(f'Stored LQL_API_KEY in profile "{profile_name}".\n')
+        return
+
+    # Create a CLI auth session
+    try:
+        res = httpx.post(f"{api}/v1/cli-auth/sessions", timeout=30.0)
+        res.raise_for_status()
+        session_data = res.json()
+    except Exception as err:
+        detail = None
+        if isinstance(err, httpx.HTTPStatusError):
+            try:
+                detail = err.response.json().get("detail")
+            except Exception:
+                detail = None
+        print_error(detail or str(err) or "Failed to start auth session", "auth_session_failed")
+        raise typer.Exit(1)
+
+    session_id = session_data["session_id"]
+    browser_code = session_data["browser_code"]
+    browser_url = f"{BROWSER_BASE_URL}/cli-auth?code={browser_code}&session={session_id}"
+
+    try:
+        webbrowser.open(browser_url)
+    except Exception:
+        pass
+    sys.stdout.write(f"Opening browser... if it didn't open, visit:\n{browser_url}\n")
+
+    deadline = time.monotonic() + 120
+    delay = 3.0
+    while time.monotonic() < deadline:
+        time.sleep(delay)
+        delay = min(delay * 1.5, 15.0)
+        try:
+            poll = httpx.get(f"{api}/v1/cli-auth/sessions/{session_id}", timeout=30.0).json()
+        except Exception:
+            continue
+
+        status = poll.get("status")
+        if status == "authorized":
+            config = read_config() or {"current_profile": "default", "profiles": {}}
+            config["profiles"][profile_name] = {
+                "token": poll.get("token"),
+                "key_id": poll.get("key_id"),
+                "api_url": api,
+            }
+            config["current_profile"] = profile_name
+            write_config(config)
+            sys.stdout.write(f'Authenticated! Profile "{profile_name}" saved.\n')
+            return
+        if status == "denied":
+            print_error("Authentication was denied.", "auth_denied")
+            raise typer.Exit(2)
+        if status == "expired":
+            print_error("Authentication session expired.", "auth_expired")
+            raise typer.Exit(2)
+
+    print_error("Authentication timed out after 120 seconds.", "auth_timeout")
+    raise typer.Exit(2)
+
+
+def login(
+    profile: Annotated[str, typer.Option("--profile", help="Profile name to store credentials in")] = "default",
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Authenticate with the DataViewer platform."""
+    _do_login(profile, api_url)
+
+
+def logout(
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Log out and revoke the current API key."""
+    config = read_config()
+    if not config:
+        print_error("No config found. Already logged out.", "no_config")
+        raise typer.Exit(2)
+    profile_name = profile or config.get("current_profile") or "default"
+    prof = config["profiles"].get(profile_name)
+
+    if prof and prof.get("key_id") and prof.get("token"):
+        try:
+            client = ApiClient(profile=profile_name, api_url=api_url)
+            client.delete(f"/v1/api-keys/{q(prof['key_id'])}")
+        except typer.Exit:
+            sys.stderr.write("Warning: could not revoke API key (already deleted or expired).\n")
+    else:
+        sys.stderr.write("Warning: no key_id in config — skipping remote key revocation.\n")
+
+    config["profiles"].pop(profile_name, None)
+    if config.get("current_profile") == profile_name:
+        remaining = list(config["profiles"].keys())
+        config["current_profile"] = remaining[0] if remaining else "default"
+    write_config(config)
+    sys.stdout.write(f'Logged out of profile "{profile_name}".\n')
+
+
+def whoami(
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Show the currently authenticated user."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    me = client.get("/v1/me").json()
+    if json_out:
+        print_json(me)
+    else:
+        print_table(
+            ["Field", "Value"],
+            [
+                ["ID", me.get("id") or ""],
+                ["Email", me.get("email") or ""],
+                ["Name", me.get("name") or me.get("display_name") or ""],
+            ],
+            False,
+            [me],
+        )
+
+
+auth_app = typer.Typer(help="Authentication commands")
+auth_app.command("login")(login)
+auth_app.command("logout")(logout)
+auth_app.command("whoami")(whoami)
+
+
+def register(root: typer.Typer) -> None:
+    root.add_typer(auth_app, name="auth")
+    # Top-level aliases: `lql login` / `lql logout` / `lql whoami`
+    root.command("login", help="Authenticate with the DataViewer platform")(login)
+    root.command("logout", help="Log out (alias for `lql auth logout`)")(logout)
+    root.command("whoami", help="Show the currently authenticated user")(whoami)

lql/commands/buckets.py

@@ -0,0 +1,190 @@
+import json
+import sys
+from typing import Annotated, Optional
+
+import typer
+
+from .._opts import ApiUrlOpt, JsonOpt, ProfileOpt
+from ..api import ApiClient
+from ..output import print_json, print_table
+from ..util import q
+
+app = typer.Typer(help="Manage S3 and Hugging Face buckets")
+
+
+@app.command("list")
+def list_buckets(json_out: JsonOpt = False, profile: ProfileOpt = None, api_url: ApiUrlOpt = None) -> None:
+    """List S3 buckets."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    items = client.get("/v1/s3-buckets").json()
+    print_table(
+        ["ID", "Name", "Region"],
+        [[b.get("id") or "", b.get("name") or b.get("bucket_name") or "", b.get("region") or ""] for b in items],
+        json_out,
+        items,
+    )
+
+
+@app.command("show")
+def show(
+    id: Annotated[str, typer.Argument(help="Bucket ID")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Show S3 bucket details."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    b = client.get(f"/v1/s3-buckets/{q(id)}").json()
+    if json_out:
+        print_json(b)
+    else:
+        print_table(
+            ["Field", "Value"],
+            [
+                ["ID", b.get("id") or ""],
+                ["Name", b.get("name") or b.get("bucket_name") or ""],
+                ["Region", b.get("region") or ""],
+                ["Endpoint", b.get("endpoint") or ""],
+            ],
+            False,
+            [b],
+        )
+
+
+@app.command("probe")
+def probe(
+    id: Annotated[str, typer.Argument(help="Bucket ID")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Probe an S3 bucket to test connectivity."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    data = client.post(f"/v1/s3-buckets/{q(id)}/probe").json()
+    if json_out:
+        print_json(data)
+    else:
+        sys.stdout.write(f"Probe result: {data.get('status') or json.dumps(data)}\n")
+
+
+@app.command("objects")
+def objects(
+    id: Annotated[str, typer.Argument(help="Bucket ID")],
+    prefix: Annotated[Optional[str], typer.Option("--prefix", help="Key prefix filter")] = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """List objects in an S3 bucket."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    params = {}
+    if prefix:
+        params["prefix"] = prefix
+    data = client.get(f"/v1/s3-buckets/{q(id)}/objects", params=params).json()
+    if json_out:
+        print_json(data)
+    else:
+        items = (data.get("objects") if isinstance(data, dict) else data) or []
+        print_table(
+            ["Key", "Size", "Last Modified"],
+            [
+                [
+                    o.get("key") or o.get("Key") or "",
+                    o.get("size") or o.get("Size") or "",
+                    o.get("last_modified") or o.get("LastModified") or "",
+                ]
+                for o in items
+            ],
+            False,
+            items,
+        )
+
+
+@app.command("attach")
+def attach(
+    bucket_id: Annotated[str, typer.Argument(help="Bucket ID")],
+    workspace: Annotated[str, typer.Option("--workspace", help="Workspace ID")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Attach a bucket to a workspace."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    data = client.post(f"/v1/s3-buckets/{q(bucket_id)}/attach", json={"workspace_id": workspace}).json()
+    if json_out:
+        print_json(data)
+    else:
+        sys.stdout.write(f"Attached bucket {bucket_id} to workspace {workspace}.\n")
+
+
+@app.command("detach")
+def detach(
+    bucket_id: Annotated[str, typer.Argument(help="Bucket ID")],
+    workspace: Annotated[str, typer.Option("--workspace", help="Workspace ID")],
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Detach a bucket from a workspace."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    client.post(f"/v1/s3-buckets/{q(bucket_id)}/detach", json={"workspace_id": workspace})
+    sys.stdout.write(f"Detached bucket {bucket_id} from workspace {workspace}.\n")
+
+
+@app.command("list-hf")
+def list_hf(json_out: JsonOpt = False, profile: ProfileOpt = None, api_url: ApiUrlOpt = None) -> None:
+    """List Hugging Face bucket connections."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    items = client.get("/v1/hf-buckets").json()
+    print_table(
+        ["ID", "Bucket", "Label"],
+        [[b.get("id") or "", b.get("owner_bucket") or "", b.get("label") or ""] for b in items],
+        json_out,
+        items,
+    )
+
+
+@app.command("connect-hf")
+def connect_hf(
+    bucket: Annotated[str, typer.Argument(metavar="owner/bucket", help="Hugging Face bucket")],
+    workspace: Annotated[str, typer.Option("--workspace", help="Workspace ID")],
+    label: Annotated[Optional[str], typer.Option("--label", help="Display label")] = None,
+    hf_key: Annotated[Optional[str], typer.Option("--hf-key", help="HF API key id (omit for public / server token)")] = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Connect a Hugging Face bucket and attach it to a workspace."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    body: dict = {"workspace_id": workspace, "bucket": bucket}
+    if label:
+        body["label"] = label
+    if hf_key:
+        body["hf_api_key_id"] = hf_key
+    data = client.post("/v1/hf-buckets", json=body).json()
+    if json_out:
+        print_json(data)
+    else:
+        sys.stdout.write(f"Connected HF bucket: {data.get('id')}\n")
+
+
+@app.command("create-dataset")
+def create_dataset(
+    bucket_id: Annotated[str, typer.Argument(help="HF bucket ID")],
+    workspace: Annotated[str, typer.Option("--workspace", help="Workspace ID")],
+    key: Annotated[str, typer.Option("--key", help="Path or glob within the bucket (e.g. data/*.parquet)")],
+    name: Annotated[Optional[str], typer.Option("--name", help="Display name")] = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Create a dataset from a connected HF bucket."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    body: dict = {"workspace_id": workspace, "hf_bucket_key": key}
+    if name:
+        body["display_name"] = name
+    data = client.post(f"/v1/hf-buckets/{q(bucket_id)}/datasets", json=body).json()
+    if json_out:
+        print_json(data)
+    else:
+        status = f" ({data.get('sync_status')})" if data.get("sync_status") else ""
+        sys.stdout.write(f"Created dataset: {data.get('id')}{status}\n")