lql-cli 0.2.0__py3-none-any.whl

lql/commands/evals.py

@@ -0,0 +1,285 @@
+import json
+import math
+import os
+import sys
+from typing import Annotated, List, Optional
+
+import typer
+
+from .._opts import ApiUrlOpt, JsonOpt, ProfileOpt
+from ..api import ApiClient
+from ..output import print_error, print_json, print_table
+from ..util import q
+
+app = typer.Typer(help="Inspect and analyze eval datasets (accuracy, failure modes, samples)")
+
+# Mirrors front/src/lib/eval-dataset.ts so `eval samples --search` searches the
+# same prompt/response columns the eval views do.
+PROMPT_KEYS = ["prompt", "messages", "conversation", "input"]
+RESPONSE_KEYS = ["response", "output", "completion", "generation"]
+
+
+def _eval_search_columns(keys: List[str]) -> List[str]:
+    s = set(keys)
+    prompt = next((k for k in PROMPT_KEYS if k in s), None)
+    response = next((k for k in RESPONSE_KEYS if k in s), None)
+    return [k for k in (prompt, response) if k]
+
+
+def _truncate(v: object) -> str:
+    s = json.dumps(v) if isinstance(v, (dict, list)) else ("" if v is None else str(v))
+    return s[:77] + "..." if len(s) > 80 else s
+
+
+def _fmt_accuracy(acc: object) -> str:
+    try:
+        n = float(acc)
+    except (TypeError, ValueError):
+        return "—"
+    if acc is None or not math.isfinite(n):
+        return "—"
+    return f"{n * 100:.1f}%"
+
+
+@app.command("list")
+def list_evals(
+    workspace: Annotated[Optional[str], typer.Option("--workspace", help="Workspace (defaults to LQL_EVAL_WORKSPACE)")] = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """List eval datasets (those detected as evaluation-run output)."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    ws = workspace or os.environ.get("LQL_EVAL_WORKSPACE")
+    params = {"is_eval": "true"}
+    if ws:
+        params["workspace_id"] = ws
+    else:
+        sys.stderr.write(
+            "Note: listing only evals you own — set LQL_EVAL_WORKSPACE or pass --workspace "
+            "to list the shared eval workspace.\n"
+        )
+    items = client.get("/v1/datasets", params=params).json()
+    print_table(
+        ["ID", "Name", "Rows", "Source"],
+        [
+            [
+                d.get("id") or "",
+                d.get("display_name") or d.get("name") or "",
+                d.get("row_count") if d.get("row_count") is not None else "",
+                d.get("source_type") or "",
+            ]
+            for d in items
+        ],
+        json_out,
+        items,
+    )
+
+
+@app.command("stats")
+def stats(
+    id: Annotated[str, typer.Argument(help="Dataset ID")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Distribution stats: accuracy, error-type distribution, token stats."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    s = client.get(f"/v1/datasets/{q(id)}/eval-stats").json()
+    if json_out:
+        print_json(s)
+        return
+    if s.get("skip_reason"):
+        sys.stdout.write(f"Stats unavailable: {s['skip_reason']}\n")
+        return
+    print_table(
+        ["Field", "Value"],
+        [
+            ["Accuracy", _fmt_accuracy(s.get("accuracy"))],
+            ["Total", s.get("total") if s.get("total") is not None else ""],
+            ["Correct", s.get("correct") if s.get("correct") is not None else ""],
+            ["Incorrect", s.get("incorrect") if s.get("incorrect") is not None else ""],
+            ["Missing", s.get("missing") if s.get("missing") is not None else ""],
+        ],
+        False,
+        [s],
+    )
+    dist = s.get("error_distribution") or []
+    if dist:
+        field = f" ({s['error_field']})" if s.get("error_field") else ""
+        sys.stdout.write(f"\nError distribution{field}:\n")
+        print_table(
+            ["Value", "Count"],
+            [[d.get("value") if d.get("value") is not None else "—", d.get("count") if d.get("count") is not None else ""] for d in dist],
+            False,
+            dist,
+        )
+        if s.get("error_distribution_truncated"):
+            sys.stdout.write("(distribution truncated — more values exist)\n")
+    dist_bad = s.get("error_distribution_incorrect") or []
+    if dist_bad:
+        sys.stdout.write("\nErrors among incorrect samples (the misses):\n")
+        print_table(
+            ["Value", "Count"],
+            [[d.get("value") if d.get("value") is not None else "—", d.get("count") if d.get("count") is not None else ""] for d in dist_bad],
+            False,
+            dist_bad,
+        )
+        if s.get("error_distribution_incorrect_truncated"):
+            sys.stdout.write("(distribution truncated — more values exist)\n")
+    tokens = s.get("token_stats") or []
+    if tokens:
+        sys.stdout.write("\nToken stats:\n")
+        print_table(
+            ["Field", "Min", "Mean", "P50", "P95", "Max"],
+            [
+                [
+                    t.get("label") or t.get("field") or "",
+                    t.get("min") if t.get("min") is not None else "",
+                    t.get("mean") if t.get("mean") is not None else "",
+                    t.get("p50") if t.get("p50") is not None else "",
+                    t.get("p95") if t.get("p95") is not None else "",
+                    t.get("max") if t.get("max") is not None else "",
+                ]
+                for t in tokens
+            ],
+            False,
+            tokens,
+        )
+
+
+@app.command("correctness")
+def correctness(
+    id: Annotated[str, typer.Argument(help="Dataset ID")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Fast correctness counts + accuracy."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    c = client.get(f"/v1/datasets/{q(id)}/eval-correctness").json()
+    if json_out:
+        print_json(c)
+        return
+    print_table(
+        ["Field", "Value"],
+        [
+            ["Accuracy", _fmt_accuracy(c.get("accuracy"))],
+            ["Total", c.get("total") if c.get("total") is not None else ""],
+            ["Correct", c.get("correct") if c.get("correct") is not None else ""],
+            ["Incorrect", c.get("incorrect") if c.get("incorrect") is not None else ""],
+            ["Missing", c.get("missing") if c.get("missing") is not None else ""],
+        ],
+        False,
+        [c],
+    )
+
+
+@app.command("samples")
+def samples(
+    id: Annotated[str, typer.Argument(help="Dataset ID")],
+    filter_: Annotated[str, typer.Option("--filter", help="correct | incorrect | missing | all")] = "all",
+    search: Annotated[Optional[str], typer.Option("--search", help="Substring match on prompt OR response column")] = None,
+    search_columns: Annotated[Optional[str], typer.Option("--search-columns", help="Override which columns --search matches (comma-separated)")] = None,
+    error_type: Annotated[Optional[str], typer.Option("--error-type", help="Filter to samples whose error field equals <value>")] = None,
+    columns: Annotated[Optional[str], typer.Option("--columns", help="Comma-separated columns to project")] = None,
+    limit: Annotated[str, typer.Option("--limit", help="Number of rows")] = "20",
+    offset: Annotated[str, typer.Option("--offset", help="Row offset")] = "0",
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """List samples filtered by correctness / search / error type (for error analysis)."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    filters: List[dict] = []
+
+    kind = str(filter_ or "all").lower()
+    if kind not in ("all", "correct", "incorrect", "missing"):
+        print_error("--filter must be one of: correct, incorrect, missing, all", "bad_filter")
+        raise typer.Exit(1)
+
+    if search:
+        if search_columns:
+            search_cols = [c.strip() for c in str(search_columns).split(",") if c.strip()]
+        else:
+            schema = client.get(f"/v1/datasets/{q(id)}/schema").json()
+            names = [str(c.get("name") or "") for c in (schema.get("columns") or [])]
+            search_cols = _eval_search_columns(names)
+        if not search_cols:
+            print_error(
+                "No searchable prompt/response columns — pass --search-columns to choose which to search.",
+                "no_search_columns",
+            )
+            raise typer.Exit(1)
+        filters.append({"columns": search_cols, "operator": "contains", "value": str(search)})
+
+    if error_type:
+        stats_data = client.get(f"/v1/datasets/{q(id)}/eval-stats").json()
+        error_field = stats_data.get("error_field")
+        if stats_data.get("skip_reason") or not error_field:
+            print_error(
+                f"error-type filtering unavailable: {stats_data.get('skip_reason') or 'no error field discovered'}",
+                "no_error_field",
+            )
+            raise typer.Exit(1)
+        filters.append({"column": error_field, "operator": "eq", "value": str(error_type)})
+
+    params = {"limit": limit, "offset": offset}
+    if columns:
+        params["columns"] = str(columns)
+    if kind != "all":
+        params["correctness"] = kind
+
+    data = client.post(f"/v1/datasets/{q(id)}/rows/filter", json={"filters": filters}, params=params).json()
+    if json_out:
+        print_json(data)
+        return
+    rows_data = data.get("rows") or []
+    indices = data.get("matched_indices") or []
+    sys.stdout.write(f"{data.get('total_matched', len(rows_data))} matched\n")
+    if not rows_data:
+        sys.stdout.write("No rows.\n")
+        return
+    keys = list(rows_data[0].keys())
+    print_table(
+        ["index", *keys],
+        [
+            [str(indices[i]) if i < len(indices) else "", *[_truncate(r.get(k)) for k in keys]]
+            for i, r in enumerate(rows_data)
+        ],
+        False,
+        rows_data,
+    )
+
+
+@app.command("sample")
+def sample(
+    id: Annotated[str, typer.Argument(help="Dataset ID")],
+    row: Annotated[str, typer.Option("--row", help="Dataset row index")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Read one full sample by its dataset row index (from `eval samples`)."""
+    try:
+        row_idx = int(row)
+        bad = row_idx < 0
+    except ValueError:
+        bad = True
+    if bad:
+        print_error("--row must be a non-negative integer (a dataset row index).", "bad_row")
+        raise typer.Exit(1)
+
+    client = ApiClient(profile=profile, api_url=api_url)
+    data = client.get(f"/v1/datasets/{q(id)}/rows", params={"offset": row_idx, "limit": 1}).json()
+    rows_data = data.get("rows") or []
+    row_obj = rows_data[0] if rows_data else None
+    if not row_obj:
+        print_error(f"No row at index {row}.", "not_found")
+        raise typer.Exit(3)
+    if json_out:
+        print_json(row_obj)
+        return
+    for k, v in row_obj.items():
+        s = json.dumps(v, indent=2) if isinstance(v, (dict, list)) else ("" if v is None else str(v))
+        sys.stdout.write(f"## {k}\n{s}\n\n")

lql/commands/highlights.py

@@ -0,0 +1,89 @@
+import sys
+from typing import Annotated, Optional
+
+import typer
+
+from .._opts import ApiUrlOpt, JsonOpt, ProfileOpt
+from ..api import ApiClient
+from ..output import print_error, print_json, print_table
+from ..sessions import resolve_session_id
+from ..util import q
+
+app = typer.Typer(help="Manage highlights")
+
+SessionOpt = Annotated[Optional[str], typer.Option("--session", help="Target a specific review session (advanced)")]
+
+
+@app.command("list")
+def list_highlights(
+    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 highlights 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)}/highlights").json()
+    print_table(
+        ["ID", "Row", "Column", "Span", "Text", "Issue"],
+        [
+            [
+                h.get("id") or "",
+                h.get("row_external_id") or "",
+                h.get("source_column") or "",
+                f"{h.get('start_offset', '?')}-{h.get('end_offset', '?')}",
+                str(h.get("highlighted_text") or "")[:40],
+                h.get("issue_id") or "",
+            ]
+            for h 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")],
+    column: Annotated[str, typer.Option("--column", help="Source column the span lives in")],
+    start: Annotated[str, typer.Option("--start", help="Start character offset")],
+    end: Annotated[str, typer.Option("--end", help="End character offset")],
+    text: Annotated[str, typer.Option("--text", help="The highlighted text span")],
+    issue: Annotated[Optional[str], typer.Option("--issue", help="Issue taxonomy ID to link")] = None,
+    color: Annotated[Optional[str], typer.Option("--color", help="Highlight color")] = None,
+    note: Annotated[Optional[str], typer.Option("--note", help="Note attached to the highlight")] = None,
+    session: SessionOpt = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Add a text-span highlight to a dataset row."""
+    try:
+        start_i = int(start)
+        end_i = int(end)
+    except ValueError:
+        print_error("--start and --end must be integers", "invalid_offset")
+        raise typer.Exit(1)
+    client = ApiClient(profile=profile, api_url=api_url)
+    session_id = resolve_session_id(client, dataset_id, session)
+    body: dict = {
+        "row_external_id": row,
+        "source_column": column,
+        "start_offset": start_i,
+        "end_offset": end_i,
+        "highlighted_text": text,
+    }
+    if issue:
+        body["issue_id"] = issue
+    if color:
+        body["color"] = color
+    if note:
+        body["note"] = note
+    data = client.post(f"/v1/sessions/{q(session_id)}/highlights", json=body).json()
+    if json_out:
+        print_json(data)
+    else:
+        sys.stdout.write(f"Created highlight: {data.get('id', 'ok')}\n")

lql/commands/instructions.py

@@ -0,0 +1,248 @@
+import sys
+
+import typer
+
+INSTRUCTIONS = r"""
+# lql — Liquid Query Language CLI
+
+CLI for the DataViewer platform. Gives agents and humans complete scriptable
+control over workspaces, datasets, spec docs, annotations, and S3.
+
+## Authentication
+
+  lql login                   # Open browser → click Authorize → token stored automatically
+  lql logout                  # Revoke token and clear local config
+  lql whoami                  # Confirm current identity
+
+Non-interactive (CI/agents): set LQL_API_KEY=<token> before any command.
+Token is read from env first, then ~/.lql/config.json.
+
+Config file: ~/.lql/config.json (mode 0600)
+  { "current_profile": "default", "profiles": { "default": { "token", "key_id", "api_url" } } }
+
+Override API base URL: --api-url <url> or LQL_API_URL env var.
+Use --profile <name> to switch between named credential sets.
+
+## Output
+
+All commands accept --json for stable JSON output to stdout.
+Errors always go to stderr as: { "error": "message", "code": "slug" }
+Data always goes to stdout.
+
+Exit codes:
+  0  success
+  1  usage / validation error
+  2  auth error (no token, 401, 403)
+  3  not found (404)
+  4  conflict (409) — e.g. spec push version conflict
+  5  server error (5xx)
+
+Pagination: --limit N --offset N on list commands.
+
+## Workspaces
+
+A workspace is the top-level container for datasets, spec docs, and members.
+
+  lql workspaces list
+  lql workspaces create <name>
+  lql workspaces show <id>
+  lql workspaces update <id> --name <new-name>
+  lql workspaces delete <id>
+  lql workspaces members list <workspace-id>
+  lql workspaces members add <workspace-id> <email>
+  lql workspaces members remove <workspace-id> <user-id>
+
+## Datasets
+
+  lql datasets list [--workspace <id>]
+  lql datasets show <id>
+  lql datasets create --workspace <id> --hf-repo <org/repo> [--name <display>] [--split <split>]
+  lql datasets create --workspace <id> --hf-bucket <org/bucket> --key <path-or-glob> [--name <display>]
+                                       # From an HF storage bucket (e.g. --key 'data/*.parquet'); syncs in background
+  lql datasets sync <id>               # Re-fetch from HuggingFace, S3, or HF bucket
+  lql datasets schema <id>             # Column names + types
+  lql datasets profile <id>            # Per-column nulls/cardinality/numeric stats/top values + content token stats
+                                       #   [--full-content] exact content scan (slow)  [--skip-content] omit it
+  lql datasets rows <id> [--limit N] [--offset N]
+  lql datasets delete <id>
+  lql datasets push <id>               # Push edits back to HuggingFace
+  lql datasets push-status <id> [--job <job-id>]
+
+Upload a local file (uploads to HuggingFace liquid-ai org, then syncs):
+  LQL_HF_TOKEN=<token> lql datasets upload <file.parquet> --workspace <id> --name <repo-name>
+
+## Evals
+
+Eval datasets (evaluation-run output: each row a sample with a model 'response'
++ a 'correct' verdict) are detected automatically. These commands are the data
+primitives for error analysis — YOU do the reasoning over what they return.
+
+  lql eval list [--workspace <id>]     # Eval datasets only. Defaults to LQL_EVAL_WORKSPACE;
+                                       # without a workspace it lists only evals you own.
+  lql eval stats <id>                  # Accuracy + correctness counts + error-type
+                                       # distribution + token stats (the distribution view)
+  lql eval correctness <id>            # Fast accuracy + correct/incorrect/missing counts
+  lql eval samples <id> [--filter correct|incorrect|missing|all] [--search <text>]
+                       [--error-type <value>] [--columns a,b] [--limit N] [--offset N]
+                                       # Slice the dataset for error analysis. Filters AND
+                                       # together. Prints an 'index' column per row.
+  lql eval sample <id> --row <index>   # Read one full sample (the conversation) by the
+                                       # 'index' from `eval samples`
+
+Notes:
+  - --search matches a substring on the prompt OR response column (either one matching is a hit).
+  - --error-type values come from the `error_field` / `error_distribution` in `eval stats`.
+  - Use the 'index' from `eval samples` directly as `eval sample --row <index>`.
+
+## Row Edits
+
+Edits are cell-level overrides layered on top of the source dataset.
+
+  lql edits list <dataset-id> [--limit N]
+  lql edits count <dataset-id>
+  lql edits add <dataset-id> --row <row-external-id> --column <col> --value <json>
+  lql edits delete <dataset-id> <edit-id>
+
+Example: lql edits add abc123 --row row_0 --column label --value '"positive"'
+
+## Spec Docs
+
+Each workspace has one spec doc (versioned markdown). Use pull/push to edit
+it like a file. Conflicts are detected via base-version-id (exit code 4).
+
+  lql spec show [--workspace <id>]                 # print current doc to stdout
+  lql spec pull [--workspace <id>] [-o FILE] [--stdout]   # writes SPEC.md by default
+  lql spec push [--workspace <id>] [--file SPEC.md] --message <msg> [--base-version-id <id>]
+  lql spec history [--workspace <id>]
+  lql spec diff [--workspace <id>] --version-id <id> [--compare-to <id>]
+  lql spec generate [--workspace <id>]             # AI-generate from datasets
+
+push auto-detects create-vs-update: with no existing doc it creates v1; otherwise
+it commits on top of the current HEAD (auto-resolved unless --base-version-id is
+given). --message is required. pull writes SPEC.md unless -o or --stdout is set.
+
+Agentic edit loop:
+  lql spec pull --workspace <id>                   # writes ./SPEC.md
+  # modify SPEC.md
+  lql spec push --workspace <id> --message "Refine numeric rules"
+  # exit 4 means a conflict — pull again and re-apply
+
+## Annotations, highlights, issues, reports — all scoped to a dataset
+
+These act directly on a dataset; the CLI resolves the dataset's review session
+for you, so you never manage sessions by hand. (Advanced: pass --session <id>
+to target a specific session for multi-pass review — a session id is returned in
+the JSON of any annotation/highlight/report.)
+
+## Annotations
+
+  lql annotations list <dataset-id>
+  lql annotations add <dataset-id> --row <row-external-id> [--rating <number>] [--note <text>]
+
+## Highlights
+
+Highlights mark specific text spans within a row.
+
+  lql highlights list <dataset-id>
+  lql highlights add <dataset-id> --row <id> --column <col> --start <n> --end <n> --text <span> [--issue <issue-id>] [--color <hex>] [--note <text>]
+
+start/end are character offsets into the row's <column> value. Link a highlight to
+an issue taxonomy entry with --issue (see "lql issues create <dataset-id>").
+
+## Issues
+
+Issues are a per-dataset taxonomy (name/color) used to tag highlights.
+
+  lql issues list <dataset-id>
+  lql issues create <dataset-id> --name <str> [--description <str>] [--color <hex>]
+
+## Reports
+
+  lql reports list <dataset-id>
+  lql reports show <report-id>
+  lql reports create <dataset-id> --title <title> [--summary <text>]
+
+## Buckets
+
+S3-compatible:
+  lql buckets list
+  lql buckets show <id>
+  lql buckets probe <id>                           # Verify connectivity + credentials
+  lql buckets objects <id> [--prefix <prefix>]
+  lql buckets attach <bucket-id> --workspace <id>
+  lql buckets detach <bucket-id> --workspace <id>
+
+Hugging Face buckets (connect → add datasets; auth = your HF token):
+  lql buckets list-hf
+  lql buckets connect-hf <owner/bucket> --workspace <id> [--label <l>] [--hf-key <id>]
+  lql buckets create-dataset <bucket-id> --workspace <id> --key <path-or-glob> [--name <display>]
+
+## Skills (agent setup)
+
+Install the lql skill so coding agents (Claude Code, Codex) know how to use lql.
+The skill is a thin pointer that tells the agent to run `lql instructions`, so it
+never goes stale.
+
+  lql skills install                  # both Claude Code + Codex, user-level (~/.claude, ~/.codex)
+  lql skills install --tool claude    # or --tool codex
+  lql skills install --project        # install into ./.claude and ./.codex instead
+  lql skills install --force          # overwrite an existing skill file
+  lql skills uninstall                # remove it
+
+## Common Agentic Workflows
+
+### Discover workspaces and datasets
+  lql workspaces list --json
+  lql datasets list --workspace <id> --json
+
+### Read dataset contents
+  lql datasets schema <id> --json
+  lql datasets rows <id> --limit 10 --json
+
+### Analyze a dataset (token distribution + quality)
+  lql datasets profile <id> --json                  # nulls/cardinality/numeric stats/top values per column
+                                                    #   + content_stats: char & ~token length p50/p95/max per text column
+  # content_stats is SAMPLED from the first shard by default (sampled=true; max_chars is sample-bound).
+  # For exact token counts over every row: lql datasets profile <id> --full-content --json
+  # Use this to judge context-window/truncation risk, spot all-null or single-value columns,
+  # and ground any narrative analysis in real numbers (don't eyeball a few rows).
+
+### Analyze an eval's failure modes
+  lql eval list --json                              # find the eval dataset
+  lql eval stats <id> --json                        # accuracy + error_distribution_incorrect
+                                                    #   = the common errors AMONG the misses
+  lql eval samples <id> --filter incorrect --json   # pull the misses
+  lql eval samples <id> --filter incorrect --error-type <value> --json   # focus one failure mode
+  lql eval sample <id> --row <index> --json         # read the full conversation of a miss
+  # Then synthesize the common pattern across the misses yourself — the commands give you
+  # the data (counts, slices, conversations); the analysis is your job.
+
+### Edit a spec doc without conflicts
+  lql spec pull --workspace <id> -o /tmp/SPEC.md
+  # edit /tmp/SPEC.md
+  lql spec push --workspace <id> --file /tmp/SPEC.md --message "Refine rules"
+  # base version is auto-resolved; exit 4 means conflict — pull again and re-apply
+
+### Annotate dataset rows
+  lql annotations add <dataset-id> --row row_0 --rating 1 --note "correct"
+  lql annotations add <dataset-id> --row row_1 --rating 0 --note "wrong label"
+
+### Upload a new dataset from a local file
+  LQL_HF_TOKEN=hf_... lql datasets upload ./data.parquet \
+    --workspace <id> --name my-eval-run --json
+
+### Push edits to HuggingFace
+  lql datasets push <id> --json
+  lql datasets push-status <id> --json   # poll until status != pending
+""".strip()
+
+
+def instructions() -> None:
+    sys.stdout.write(INSTRUCTIONS + "\n")
+
+
+app = typer.Typer()
+app.command(
+    "instructions",
+    help="Print a full reference for agents and humans (all commands, examples, workflows)",
+)(instructions)

lql/commands/issues.py

@@ -0,0 +1,56 @@
+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 issues")
+
+
+@app.command("list")
+def list_issues(
+    dataset_id: Annotated[str, typer.Argument(help="Dataset ID")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """List issues in a dataset's taxonomy."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    items = client.get(f"/v1/datasets/{q(dataset_id)}/issues").json()
+    print_table(
+        ["ID", "Name", "Description", "Color"],
+        [
+            [i.get("id") or "", i.get("name") or "", i.get("description") or "", i.get("color") or ""]
+            for i in items
+        ],
+        json_out,
+        items,
+    )
+
+
+@app.command("create")
+def create(
+    dataset_id: Annotated[str, typer.Argument(help="Dataset ID")],
+    name: Annotated[str, typer.Option("--name", help="Issue name")],
+    description: Annotated[Optional[str], typer.Option("--description", help="Issue description")] = None,
+    color: Annotated[Optional[str], typer.Option("--color", help="Issue color (hex)")] = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Create an issue in a dataset's taxonomy."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    body: dict = {"name": name}
+    if description:
+        body["description"] = description
+    if color:
+        body["color"] = color
+    data = client.post(f"/v1/datasets/{q(dataset_id)}/issues", json=body).json()
+    if json_out:
+        print_json(data)
+    else:
+        sys.stdout.write(f"Created issue: {data.get('id', 'ok')}\n")