sovaria-cli 0.2.0__py3-none-any.whl

apps/cli/src/commands/storage.py

@@ -0,0 +1,405 @@
+"""
+apps.cli.src.commands.storage — Vault storage management commands.
+
+Commands:
+    sov storage buckets         List all buckets
+    sov storage create-bucket   Create a new bucket
+    sov storage ls              List objects in a bucket
+    sov storage upload          Upload a file to a bucket
+    sov storage download        Download an object
+    sov storage sign-download     Mint a signed download URL
+    sov storage sign-upload       Mint a signed upload URL
+    sov storage rm              Delete an object
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import quote
+
+import httpx
+import typer
+
+from apps.cli.src.utils.api_client import CLIRequestError, build_request_context, call_api
+from apps.cli.src.utils.display import print_json, print_success
+
+app = typer.Typer(help="Object storage management")
+
+
+def _object_path(bucket: str, object_path: str) -> str:
+    encoded = "/".join(quote(part, safe="") for part in object_path.strip("/").split("/"))
+    return f"/api/v1/store/objects/{quote(bucket, safe='')}/{encoded}"
+
+
+@app.command("buckets")
+def list_buckets(
+    project_id: str | None = typer.Option(None, "--project", help="Project ID"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """List all storage buckets."""
+    try:
+        result = call_api(
+            method="GET",
+            path="/api/v1/store/buckets",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    if not isinstance(result, list):
+        print_json(result)
+        return
+    for bucket in result:
+        vis = "public" if bucket.get("public") else "private"
+        typer.echo(f"  {bucket['name']}  ({vis})  objects={bucket.get('object_count', 0)}")
+
+
+@app.command("create-bucket")
+def create_bucket(
+    name: str = typer.Argument(..., help="Bucket name"),
+    project_id: str | None = typer.Option(None, "--project", help="Project ID"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    public: bool = typer.Option(False, "--public", help="Make bucket public"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Create a new storage bucket."""
+    try:
+        call_api(
+            method="POST",
+            path="/api/v1/store/buckets",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body={"name": name, "public": public},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_success(f"Bucket '{name}' created")
+
+
+@app.command("ls")
+def list_objects(
+    bucket: str = typer.Argument(..., help="Bucket name"),
+    project_id: str | None = typer.Option(None, "--project", help="Project ID"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    prefix: str = typer.Option("", "--prefix", help="Filter by prefix"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """List objects in a bucket."""
+    params = {"prefix": prefix} if prefix else None
+    try:
+        result = call_api(
+            method="GET",
+            path=f"/api/v1/store/objects/{quote(bucket, safe='')}",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            params=params,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+    if not isinstance(result, list):
+        print_json(result)
+        return
+    for obj in result:
+        size_kb = obj.get("size", 0) / 1024
+        typer.echo(f"  {obj['name']}  {size_kb:.1f}KB  {obj.get('content_type', '-')}")
+
+
+@app.command("upload")
+def upload(
+    bucket: str = typer.Argument(..., help="Bucket name"),
+    file_path: str = typer.Argument(..., help="Local file path"),
+    project_id: str | None = typer.Option(None, "--project", help="Project ID"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    object_path: str | None = typer.Option(None, "--name", help="Remote object path (defaults to filename)"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Upload a file to a bucket."""
+    path = Path(file_path)
+    if not path.exists():
+        typer.echo(f"File not found: {file_path}", err=True)
+        raise typer.Exit(1)
+    remote_name = object_path or path.name
+    try:
+        api_url, headers = build_request_context(
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+        with open(path, "rb") as handle:
+            response = httpx.post(
+                f"{api_url}{_object_path(bucket, remote_name)}",
+                headers=headers,
+                files={"file": (remote_name, handle)},
+                timeout=120,
+            )
+        response.raise_for_status()
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Error: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+    print_success(f"Uploaded: {remote_name} -> {bucket}")
+
+
+@app.command("download")
+def download(
+    bucket: str = typer.Argument(..., help="Bucket name"),
+    object_path: str = typer.Argument(..., help="Remote object path"),
+    output: Path = typer.Option(..., "--output", "-o", help="Local output file path"),
+    project_id: str | None = typer.Option(None, "--project"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Download an object to a local file."""
+    try:
+        api_url, headers = build_request_context(
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+        response = httpx.get(
+            f"{api_url}{_object_path(bucket, object_path)}",
+            headers=headers,
+            timeout=120,
+        )
+        response.raise_for_status()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_bytes(response.content)
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    except httpx.HTTPStatusError as exc:
+        typer.echo(f"Error: {exc.response.text}", err=True)
+        raise typer.Exit(1) from exc
+    print_success(f"Downloaded to {output}")
+
+
+@app.command("sign-download")
+def sign_download(
+    bucket: str = typer.Argument(...),
+    object_path: str = typer.Argument(...),
+    expires_in: int = typer.Option(3600, "--expires-in", help="TTL seconds"),
+    project_id: str | None = typer.Option(None, "--project"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Mint a time-limited signed download URL."""
+    try:
+        result = call_api(
+            method="POST",
+            path=f"{_object_path(bucket, object_path)}/sign-download",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body={"expires_in": expires_in},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)
+
+
+@app.command("sign-upload")
+def sign_upload(
+    bucket: str = typer.Argument(...),
+    object_path: str = typer.Argument(...),
+    expires_in: int = typer.Option(3600, "--expires-in", help="TTL seconds"),
+    project_id: str | None = typer.Option(None, "--project"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Mint a time-limited signed upload URL."""
+    try:
+        result = call_api(
+            method="POST",
+            path=f"{_object_path(bucket, object_path)}/sign-upload",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body={"expires_in": expires_in},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)
+
+
+@app.command("rm")
+def delete_object(
+    bucket: str = typer.Argument(..., help="Bucket name"),
+    object_path: str = typer.Argument(..., help="Object path to delete"),
+    project_id: str | None = typer.Option(None, "--project", help="Project ID"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Delete an object from a bucket."""
+    try:
+        call_api(
+            method="DELETE",
+            path=_object_path(bucket, object_path),
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_success(f"Deleted: {bucket}/{object_path}")
+
+
+@app.command("bucket-get")
+def bucket_get(
+    name: str = typer.Argument(..., help="Bucket name"),
+    project_id: str | None = typer.Option(None, "--project"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Fetch bucket metadata."""
+    try:
+        result = call_api(
+            method="GET",
+            path=f"/api/v1/store/buckets/{quote(name, safe='')}",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)
+
+
+@app.command("bucket-update")
+def bucket_update(
+    name: str = typer.Argument(..., help="Bucket name"),
+    public: bool | None = typer.Option(None, "--public/--private"),
+    file_size_limit: int | None = typer.Option(None, "--file-size-limit"),
+    allowed_mime_types: str | None = typer.Option(
+        None, "--allowed-mime-types", help="Comma-separated MIME patterns"
+    ),
+    project_id: str | None = typer.Option(None, "--project"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Update bucket settings."""
+    body: dict[str, object] = {}
+    if public is not None:
+        body["public"] = public
+    if file_size_limit is not None:
+        body["file_size_limit"] = file_size_limit
+    if allowed_mime_types is not None:
+        body["allowed_mime_types"] = [
+            part.strip() for part in allowed_mime_types.split(",") if part.strip()
+        ]
+    if not body:
+        raise typer.BadParameter("Provide at least one field to update")
+    try:
+        result = call_api(
+            method="PATCH",
+            path=f"/api/v1/store/buckets/{quote(name, safe='')}",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body=body,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)
+
+
+@app.command("bucket-delete")
+def bucket_delete(
+    name: str = typer.Argument(..., help="Bucket name"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation"),
+    project_id: str | None = typer.Option(None, "--project"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Delete a storage bucket and all objects."""
+    if not yes and not typer.confirm(f"Delete bucket '{name}' and all objects?"):
+        raise typer.Exit(0)
+    try:
+        result = call_api(
+            method="DELETE",
+            path=f"/api/v1/store/buckets/{quote(name, safe='')}",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)
+    print_success(f"Deleted bucket '{name}'")
+
+
+@app.command("move")
+def move_object(
+    from_path: str = typer.Option(..., "--from", help="Source path bucket/object"),
+    to_path: str = typer.Option(..., "--to", help="Destination path bucket/object"),
+    project_id: str | None = typer.Option(None, "--project"),
+    org_id: str | None = typer.Option(None, "--org"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Move or rename an object within storage."""
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/store/objects/move",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body={"from_path": from_path, "to_path": to_path},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    print_json(result)
+    print_success(f"Moved {from_path} -> {to_path}")

apps/cli/src/commands/vector.py

@@ -0,0 +1,204 @@
+"""Nexus vector / embedding commands."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import typer
+
+from apps.cli.src.utils.api_client import CLIRequestError, call_api, parse_json_arg, print_json
+
+app = typer.Typer(help="Vector search and embeddings (Nexus engine)")
+
+
+@app.command("embed")
+def embed(
+    text: list[str] = typer.Argument(..., help="One or more texts to embed"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Generate embeddings for text inputs."""
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/embed",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body={"texts": text},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("upsert")
+def upsert(
+    collection: str = typer.Argument(..., help="Collection name"),
+    docs_json: str = typer.Option(..., "--docs", help='JSON array: [{"text":"...", "id":"..."}]'),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Embed and upsert documents into a vector collection."""
+    docs = parse_json_arg(docs_json, label="--docs")
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/vectors/upsert",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body={"collection": collection, "docs": docs},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("search")
+def search(
+    collection: str = typer.Argument(..., help="Collection name"),
+    query: str = typer.Argument(..., help="Search query text"),
+    top_k: int = typer.Option(5, "--top-k", min=1, max=100),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Semantic search within a vector collection."""
+    try:
+        result = call_api(
+            method="POST",
+            path="/api/v1/vectors/search",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            body={"collection": collection, "query": query, "top_k": top_k, "metadata_filter": {}},
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("collections")
+def collections(
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """List vector collections in the current project scope."""
+    try:
+        result = call_api(
+            method="GET",
+            path="/api/v1/collections",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("records")
+def records(
+    collection: str = typer.Argument(..., help="Collection name"),
+    limit: int | None = typer.Option(None, "--limit"),
+    offset: int | None = typer.Option(None, "--offset"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """List records in a vector collection."""
+    params: dict[str, str] = {}
+    if limit is not None:
+        params["limit"] = str(limit)
+    if offset is not None:
+        params["offset"] = str(offset)
+    try:
+        result = call_api(
+            method="GET",
+            path=f"/api/v1/collections/{quote(collection, safe='')}/records",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+            params=params or None,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("delete-record")
+def delete_record(
+    collection: str = typer.Argument(..., help="Collection name"),
+    record_id: str = typer.Argument(..., help="Record ID"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Delete one record from a vector collection."""
+    try:
+        result = call_api(
+            method="DELETE",
+            path=(
+                f"/api/v1/collections/{quote(collection, safe='')}/records/"
+                f"{quote(record_id, safe='')}"
+            ),
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))
+
+
+@app.command("delete-collection")
+def delete_collection(
+    collection: str = typer.Argument(..., help="Collection name"),
+    org_id: str | None = typer.Option(None, "--org"),
+    project_id: str | None = typer.Option(None, "--project"),
+    env_id: str | None = typer.Option(None, "--env"),
+    profile: str | None = typer.Option(None, "--profile"),
+) -> None:
+    """Delete an entire vector collection."""
+    try:
+        result = call_api(
+            method="DELETE",
+            path=f"/api/v1/collections/{quote(collection, safe='')}",
+            profile=profile,
+            org_id=org_id,
+            project_id=project_id,
+            env_id=env_id,
+            require_scope=True,
+        )
+    except CLIRequestError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+    typer.echo(print_json(result))