lql-cli 0.2.0__py3-none-any.whl

lql/commands/reports.py

@@ -0,0 +1,92 @@
+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 reports")
+
+SessionOpt = Annotated[Optional[str], typer.Option("--session", help="Target a specific review session (advanced)")]
+
+
+@app.command("list")
+def list_reports(
+    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 reports 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)}/reports").json()
+    print_table(
+        ["ID", "Title", "Rows", "Created"],
+        [
+            [
+                r.get("id") or "",
+                r.get("title") or "",
+                r.get("row_count") if r.get("row_count") is not None else "",
+                r.get("created_at") or "",
+            ]
+            for r in items
+        ],
+        json_out,
+        items,
+    )
+
+
+@app.command("show")
+def show(
+    report_id: Annotated[str, typer.Argument(help="Report ID")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Show a report."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    r = client.get(f"/v1/reports/{q(report_id)}").json()
+    if json_out:
+        print_json(r)
+    else:
+        print_table(
+            ["Field", "Value"],
+            [
+                ["ID", r.get("id") or ""],
+                ["Title", r.get("title") or ""],
+                ["Rows", r.get("row_count") if r.get("row_count") is not None else ""],
+                ["Summary", r.get("analysis_summary") or r.get("summary") or ""],
+                ["Created", r.get("created_at") or ""],
+            ],
+            False,
+            [r],
+        )
+
+
+@app.command("create")
+def create(
+    dataset_id: Annotated[str, typer.Argument(help="Dataset ID")],
+    title: Annotated[str, typer.Option("--title", help="Report title")],
+    summary: Annotated[Optional[str], typer.Option("--summary", help="Manual summary")] = None,
+    session: SessionOpt = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Publish a report for a dataset (bundles annotations + LLM analysis)."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    session_id = resolve_session_id(client, dataset_id, session)
+    body: dict = {"title": title}
+    if summary:
+        body["summary"] = summary
+    data = client.post(f"/v1/sessions/{q(session_id)}/reports", json=body).json()
+    if json_out:
+        print_json(data)
+    else:
+        sys.stdout.write(f"Created report: {data.get('id', 'ok')}\n")

lql/commands/skills.py

@@ -0,0 +1,116 @@
+import shutil
+import sys
+from pathlib import Path
+from typing import Annotated, List, Optional
+
+import typer
+
+from .._opts import JsonOpt
+from ..output import print_error, print_json
+
+app = typer.Typer(help="Install the lql agent skill into Claude Code and Codex")
+
+# Thin pointer skill. The body deliberately does NOT embed the full reference —
+# it tells the agent to run `lql instructions`, which is always in sync with the
+# installed binary.
+SKILL_MD = """---
+name: lql
+description: Use the lql CLI to work with the Liquid DataViewer platform — spec docs, datasets, evals, annotations, highlights, issues, reports, workspaces, and S3/HuggingFace storage buckets. Use whenever the user wants to read or edit a spec doc, list/inspect/upload datasets, run or review evals, annotate dataset rows, or manage DataViewer workspaces from the command line.
+---
+
+# lql — Liquid DataViewer CLI
+
+`lql` is the command-line interface for the Liquid DataViewer platform. Use it
+for spec docs, datasets, evals, annotations, highlights, issues, reports,
+workspaces, and S3 / HuggingFace storage buckets.
+
+**Before using lql, run `lql instructions`** to load the complete, up-to-date
+command reference — every command, flag, exit code, and agentic workflow. It is
+always in sync with the installed version, so prefer it over guessing flags.
+
+Quick start:
+
+  lql whoami         # confirm you're authenticated (run `lql login` if not)
+  lql instructions   # full reference — read this first
+  lql workspaces list --json
+  lql datasets list --workspace <id> --json
+
+All commands accept `--json` for stable, machine-readable output. Errors go to
+stderr as `{ "error": "...", "code": "..." }`; data goes to stdout.
+"""
+
+
+def _parse_tools(opt: Optional[str]) -> Optional[List[str]]:
+    value = (opt or "both").lower()
+    if value == "both":
+        return ["claude", "codex"]
+    if value in ("claude", "codex"):
+        return [value]
+    return None
+
+
+def _resolve_targets(tools: List[str], project: bool):
+    base = Path.cwd() if project else Path.home()
+    roots = {
+        "claude": base / ".claude" / "skills" / "lql",
+        "codex": base / ".codex" / "skills" / "lql",
+    }
+    return [{"tool": t, "dir": roots[t], "file": roots[t] / "SKILL.md"} for t in tools]
+
+
+@app.command("install")
+def install(
+    tool: Annotated[str, typer.Option("--tool", help="Which agent to target: claude, codex, or both")] = "both",
+    project: Annotated[bool, typer.Option("--project", help="Install into the current directory instead of the home dir")] = False,
+    force: Annotated[bool, typer.Option("--force", help="Overwrite an existing skill file")] = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """Install the lql skill so coding agents know how to use lql."""
+    tools = _parse_tools(tool)
+    if not tools:
+        print_error(f"Invalid --tool '{tool}'. Use claude, codex, or both.", "usage")
+        raise typer.Exit(1)
+    targets = _resolve_targets(tools, project)
+    results = []
+    for t in targets:
+        if t["file"].exists() and not force:
+            results.append({"tool": t["tool"], "path": str(t["file"]), "status": "exists"})
+            continue
+        t["dir"].mkdir(parents=True, exist_ok=True)
+        t["file"].write_text(SKILL_MD, "utf-8")
+        results.append({"tool": t["tool"], "path": str(t["file"]), "status": "installed"})
+    if json_out:
+        print_json({"results": results})
+        return
+    for r in results:
+        if r["status"] == "exists":
+            sys.stdout.write(f"{r['tool']}: already installed at {r['path']} (use --force to overwrite)\n")
+        else:
+            sys.stdout.write(f"{r['tool']}: installed → {r['path']}\n")
+
+
+@app.command("uninstall")
+def uninstall(
+    tool: Annotated[str, typer.Option("--tool", help="Which agent to target: claude, codex, or both")] = "both",
+    project: Annotated[bool, typer.Option("--project", help="Remove from the current directory instead of the home dir")] = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """Remove the lql skill from Claude Code and Codex."""
+    tools = _parse_tools(tool)
+    if not tools:
+        print_error(f"Invalid --tool '{tool}'. Use claude, codex, or both.", "usage")
+        raise typer.Exit(1)
+    targets = _resolve_targets(tools, project)
+    results = []
+    for t in targets:
+        if t["dir"].exists():
+            shutil.rmtree(t["dir"], ignore_errors=True)
+            results.append({"tool": t["tool"], "path": str(t["dir"]), "status": "removed"})
+        else:
+            results.append({"tool": t["tool"], "path": str(t["dir"]), "status": "absent"})
+    if json_out:
+        print_json({"results": results})
+        return
+    for r in results:
+        state = "removed" if r["status"] == "removed" else "not installed"
+        sys.stdout.write(f"{r['tool']}: {state} ({r['path']})\n")

lql/commands/spec.py

@@ -0,0 +1,165 @@
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from .._opts import ApiUrlOpt, JsonOpt, ProfileOpt
+from ..api import ApiClient
+from ..output import print_error, print_json
+from ..util import q
+
+app = typer.Typer(help="Manage workspace spec docs")
+
+WorkspaceOpt = Annotated[str, typer.Option("--workspace", help="Workspace ID")]
+
+
+@app.command("show")
+def show(
+    workspace: WorkspaceOpt,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Show the spec doc for a workspace."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    doc = client.get(f"/v1/workspaces/{q(workspace)}/spec-doc").json()
+    if json_out:
+        print_json(doc or None)
+        return
+    if not doc:
+        sys.stdout.write(f"Workspace: {workspace}\nNo spec doc yet.\n")
+        return
+    cv = doc.get("current_version")
+    version_str = f"{cv.get('version')} ({cv.get('id')})" if cv else "none"
+    committed = cv.get("committed_at") if cv else ""
+    sys.stdout.write(f"Workspace: {workspace}\n")
+    sys.stdout.write(f"Version: {version_str}\n")
+    sys.stdout.write(f"Committed: {committed}\n\n")
+    sys.stdout.write(doc.get("content") or "(empty)\n")
+
+
+@app.command("pull")
+def pull(
+    workspace: WorkspaceOpt,
+    output: Annotated[Optional[str], typer.Option("-o", "--output", help="Output file (defaults to SPEC.md)")] = None,
+    stdout: Annotated[bool, typer.Option("--stdout", help="Print to stdout instead of writing a file")] = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Pull the spec doc markdown to a file (defaults to SPEC.md)."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    doc = client.get(f"/v1/workspaces/{q(workspace)}/spec-doc").json()
+    if not doc:
+        print_error(f"No spec doc exists for workspace {workspace}", "not_found")
+        raise typer.Exit(3)
+    content = doc.get("content") or ""
+    if stdout:
+        sys.stdout.write(content + "\n")
+    else:
+        out_file = output or "SPEC.md"
+        Path(out_file).resolve().write_text(content, "utf-8")
+        sys.stdout.write(f"Wrote spec doc to {out_file}\n")
+
+
+@app.command("push")
+def push(
+    workspace: WorkspaceOpt,
+    message: Annotated[str, typer.Option("--message", help="Commit message describing the change")],
+    file: Annotated[str, typer.Option("--file", help="Markdown file to push")] = "SPEC.md",
+    base_version_id: Annotated[Optional[str], typer.Option("--base-version-id", help="Base version ID (for conflict detection)")] = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Push a spec doc markdown file to a workspace."""
+    file_path = Path(file).resolve()
+    if not file_path.exists():
+        print_error(f"File not found: {file_path}", "file_not_found")
+        raise typer.Exit(1)
+    content = file_path.read_text("utf-8")
+    client = ApiClient(profile=profile, api_url=api_url)
+
+    base = base_version_id
+    if not base:
+        cur = client.get(f"/v1/workspaces/{q(workspace)}/spec-doc").json()
+        base = (cur.get("current_version") or {}).get("id") if cur else None
+
+    if not base:
+        res = client.post(
+            f"/v1/workspaces/{q(workspace)}/spec-doc",
+            json={"content": content, "message": message},
+        ).json()
+    else:
+        res = client.put(
+            f"/v1/workspaces/{q(workspace)}/spec-doc",
+            json={"content": content, "base_version_id": base, "message": message},
+        ).json()
+    if json_out:
+        print_json(res)
+    else:
+        sys.stdout.write(f"Pushed spec doc. Version: {res.get('version', '?')} ({res.get('id', 'ok')})\n")
+
+
+@app.command("history")
+def history(
+    workspace: WorkspaceOpt,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Show spec doc version history."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    versions = client.get(f"/v1/workspaces/{q(workspace)}/spec-doc/versions").json()
+    if json_out:
+        print_json(versions)
+    else:
+        for v in versions:
+            sys.stdout.write(
+                f"v{v.get('version')}  {v.get('id')}  {v.get('committed_at') or ''}  "
+                f"{v.get('committed_by_name') or ''}  {v.get('message') or ''}\n"
+            )
+
+
+@app.command("diff")
+def diff(
+    workspace: WorkspaceOpt,
+    version_id: Annotated[str, typer.Option("--version-id", help="Version ID to show the diff for")],
+    compare_to: Annotated[Optional[str], typer.Option("--compare-to", help="Version to compare to (defaults to previous)")] = None,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Show diff between spec doc versions."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    params = {}
+    if compare_to:
+        params["compare_to"] = compare_to
+    res = client.get(
+        f"/v1/workspaces/{q(workspace)}/spec-doc/versions/{q(version_id)}/diff",
+        params=params,
+    ).json()
+    if json_out:
+        print_json(res)
+    else:
+        diff_text = res.get("unified_diff")
+        if isinstance(diff_text, str):
+            sys.stdout.write(diff_text + "\n")
+        else:
+            print_json(res)
+
+
+@app.command("generate")
+def generate(
+    workspace: WorkspaceOpt,
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Generate a spec doc from datasets."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    res = client.post(f"/v1/workspaces/{q(workspace)}/spec-doc/generate").json()
+    if json_out:
+        print_json(res)
+    else:
+        sys.stdout.write(f"Generation started. Run ID: {res.get('run_id') or res.get('id') or 'ok'}\n")

lql/commands/workspaces.py

@@ -0,0 +1,147 @@
+import sys
+from typing import Annotated
+
+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 workspaces")
+members_app = typer.Typer(help="Manage workspace members")
+app.add_typer(members_app, name="members")
+
+
+@app.command("list")
+def list_workspaces(json_out: JsonOpt = False, profile: ProfileOpt = None, api_url: ApiUrlOpt = None) -> None:
+    """List all accessible workspaces."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    items = client.get("/v1/workspaces").json()
+    print_table(
+        ["ID", "Name"],
+        [[w.get("id") or "", w.get("display_name") or w.get("name") or ""] for w in items],
+        json_out,
+        items,
+    )
+
+
+@app.command("create")
+def create(
+    name: Annotated[str, typer.Argument(help="Workspace name")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Create a new workspace."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    data = client.post("/v1/workspaces", json={"name": name}).json()
+    if json_out:
+        print_json(data)
+    else:
+        sys.stdout.write(f"Created workspace: {data.get('id')}\n")
+
+
+@app.command("show")
+def show(
+    id: Annotated[str, typer.Argument(help="Workspace ID")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Show workspace details."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    w = client.get(f"/v1/workspaces/{q(id)}").json()
+    if json_out:
+        print_json(w)
+    else:
+        print_table(
+            ["Field", "Value"],
+            [
+                ["ID", w.get("id") or ""],
+                ["Name", w.get("display_name") or w.get("name") or ""],
+                ["Created", w.get("created_at") or ""],
+            ],
+            False,
+            [w],
+        )
+
+
+@app.command("update")
+def update(
+    id: Annotated[str, typer.Argument(help="Workspace ID")],
+    name: Annotated[str, typer.Option("--name", help="New display name")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Update workspace properties."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    data = client.patch(f"/v1/workspaces/{q(id)}", json={"name": name}).json()
+    if json_out:
+        print_json(data)
+    else:
+        sys.stdout.write(f"Updated workspace: {id}\n")
+
+
+@app.command("delete")
+def delete(
+    id: Annotated[str, typer.Argument(help="Workspace ID")],
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Delete a workspace."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    client.delete(f"/v1/workspaces/{q(id)}")
+    sys.stdout.write(f"Deleted workspace: {id}\n")
+
+
+@members_app.command("list")
+def members_list(
+    id: Annotated[str, typer.Argument(help="Workspace ID")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """List workspace members."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    items = client.get(f"/v1/workspaces/{q(id)}/members").json()
+    print_table(
+        ["User ID", "Email", "Role"],
+        [
+            [m.get("user_id") or m.get("id") or "", m.get("email") or "", m.get("role") or ""]
+            for m in items
+        ],
+        json_out,
+        items,
+    )
+
+
+@members_app.command("add")
+def members_add(
+    id: Annotated[str, typer.Argument(help="Workspace ID")],
+    email: Annotated[str, typer.Argument(help="Member email")],
+    json_out: JsonOpt = False,
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Add a member to a workspace."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    data = client.post(f"/v1/workspaces/{q(id)}/members", json={"email": email}).json()
+    if json_out:
+        print_json(data)
+    else:
+        sys.stdout.write(f"Added {email} to workspace {id}.\n")
+
+
+@members_app.command("remove")
+def members_remove(
+    id: Annotated[str, typer.Argument(help="Workspace ID")],
+    uid: Annotated[str, typer.Argument(help="User ID")],
+    profile: ProfileOpt = None,
+    api_url: ApiUrlOpt = None,
+) -> None:
+    """Remove a member from a workspace."""
+    client = ApiClient(profile=profile, api_url=api_url)
+    client.delete(f"/v1/workspaces/{q(id)}/members/{q(uid)}")
+    sys.stdout.write(f"Removed user {uid} from workspace {id}.\n")

lql/config.py

@@ -0,0 +1,103 @@
+import ipaddress
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+from urllib.parse import urlparse
+
+CONFIG_DIR = Path.home() / ".lql"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+DEFAULT_API_URL = "https://liquid-anchor-api.fly.dev"
+
+
+def read_config() -> Optional[dict]:
+    try:
+        return json.loads(CONFIG_FILE.read_text("utf-8"))
+    except Exception:
+        return None
+
+
+def write_config(config: dict) -> None:
+    # Always enforce 0700 on the dir (even if it pre-existed with weaker perms)
+    # and 0600 on the file — the file holds the API token.
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    os.chmod(CONFIG_DIR, 0o700)
+    CONFIG_FILE.write_text(json.dumps(config, indent=2), "utf-8")
+    os.chmod(CONFIG_FILE, 0o600)
+
+
+def get_active_profile(profile_name: Optional[str] = None) -> Optional[dict]:
+    config = read_config()
+    if not config:
+        return None
+    name = profile_name or config.get("current_profile") or "default"
+    return (config.get("profiles") or {}).get(name)
+
+
+def get_token(profile_name: Optional[str] = None) -> Optional[str]:
+    env_token = os.environ.get("LQL_API_KEY")
+    if env_token:
+        return env_token
+    profile = get_active_profile(profile_name)
+    return profile.get("token") if profile else None
+
+
+_warned_hosts: set = set()
+
+
+def _is_loopback(host: str) -> bool:
+    if host == "localhost":
+        return True
+    try:
+        # Covers the whole 127.0.0.0/8 range and ::1 (not just 127.0.0.1).
+        return ipaddress.ip_address(host.strip("[]")).is_loopback
+    except ValueError:
+        return False
+
+
+def validate_api_url(raw_url: str) -> str:
+    """Validate an API base URL before it is ever used to send a bearer token.
+
+    The token is attached to every request to whatever origin is configured, so
+    an attacker-controllable URL (env var, copied --api-url, poisoned profile) is
+    a credential-exfiltration vector. We don't lock to one host (that would break
+    self-hosted/staging backends), but we enforce:
+      - only http/https (no file:, javascript:, ...)
+      - HTTPS required for non-loopback hosts, so the token never crosses the
+        network in plaintext. Opt out for trusted dev with LQL_ALLOW_INSECURE_API_URL=1.
+    A one-time stderr warning fires for non-default hosts so silent redirection
+    becomes visible.
+    """
+    parsed = urlparse(raw_url)
+    if not parsed.scheme or not parsed.netloc:
+        sys.stderr.write(f"lql: invalid API URL: {raw_url}\n")
+        raise SystemExit(2)
+
+    if parsed.scheme not in ("https", "http"):
+        sys.stderr.write(f"lql: unsupported API URL protocol '{parsed.scheme}:' (use https)\n")
+        raise SystemExit(2)
+
+    allow_insecure = os.environ.get("LQL_ALLOW_INSECURE_API_URL") == "1"
+    host = parsed.hostname or ""
+    if parsed.scheme == "http" and not _is_loopback(host) and not allow_insecure:
+        sys.stderr.write(
+            f"lql: refusing to send credentials to insecure (http) host '{parsed.netloc}'. "
+            "Use https, or set LQL_ALLOW_INSECURE_API_URL=1 to override.\n"
+        )
+        raise SystemExit(2)
+
+    default_host = urlparse(DEFAULT_API_URL).netloc
+    if parsed.netloc != default_host and parsed.netloc not in _warned_hosts:
+        _warned_hosts.add(parsed.netloc)
+        sys.stderr.write(f"lql: using non-default API host '{parsed.netloc}'\n")
+
+    return raw_url
+
+
+def get_api_url(profile_name: Optional[str] = None) -> str:
+    env_url = os.environ.get("LQL_API_URL")
+    if env_url:
+        return validate_api_url(env_url)
+    profile = get_active_profile(profile_name)
+    return validate_api_url((profile or {}).get("api_url") or DEFAULT_API_URL)

lql/output.py

@@ -0,0 +1,29 @@
+import json
+import sys
+from typing import List, Sequence
+
+from rich.console import Console
+from rich.table import Table
+
+_console = Console()
+
+
+def print_json(data: object) -> None:
+    sys.stdout.write(json.dumps(data, indent=2, default=str) + "\n")
+
+
+def print_table(headers: Sequence[str], rows: Sequence[Sequence[str]], is_json: bool, data: object) -> None:
+    if is_json:
+        print_json(data)
+        return
+    table = Table(show_header=True, header_style="bold")
+    for h in headers:
+        table.add_column(str(h))
+    for row in rows:
+        table.add_row(*[str(c) for c in row])
+    _console.print(table)
+
+
+def print_error(message: str, code: str) -> None:
+    # Compact, machine-readable; always to stderr (matches the TS contract).
+    sys.stderr.write(json.dumps({"error": message, "code": code}) + "\n")

lql/sessions.py

@@ -0,0 +1,27 @@
+from typing import Optional
+
+import typer
+
+from .api import ApiClient
+from .output import print_error
+from .util import q
+
+
+def resolve_session_id(
+    client: ApiClient,
+    dataset_id: Optional[str],
+    session_override: Optional[str] = None,
+) -> str:
+    """Resolve the review session to act on.
+
+    Annotations/highlights/reports hang off a per-dataset "active" session that
+    the API get-or-creates, so callers pass a dataset id and we resolve it.
+    `--session <id>` overrides this for the rare multi-pass case.
+    """
+    if session_override:
+        return session_override
+    if not dataset_id:
+        print_error("Dataset ID required (or pass --session <id>)", "missing_dataset")
+        raise typer.Exit(1)
+    res = client.post(f"/v1/datasets/{q(dataset_id)}/sessions/active")
+    return res.json()["id"]