amina-cli 0.2.5__tar.gz → 0.2.7__tar.gz

{amina_cli-0.2.5 → amina_cli-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amina-cli
-Version: 0.2.5
+Version: 0.2.7
 Summary: CLI for AminoAnalytica protein engineering platform
 Project-URL: Homepage, https://aminoanalytica.com
 Project-URL: Documentation, https://docs.aminoanalytica.com

{amina_cli-0.2.5 → amina_cli-0.2.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "amina-cli"
-version = "0.2.5"
+version = "0.2.7"
 description = "CLI for AminoAnalytica protein engineering platform"
 readme = "README.md"
 license = {text = "Apache-2.0"}

{amina_cli-0.2.5 → amina_cli-0.2.7}/src/amina_cli/__init__.py

@@ -9,4 +9,4 @@ Quick start:
     amina run esmfold --sequence "MKFLILLFNILCLFPVLAADNH"
 """
 
-__version__ = "0.2.5"
+__version__ = "0.2.7"

{amina_cli-0.2.5 → amina_cli-0.2.7}/src/amina_cli/auth.py

@@ -336,3 +336,34 @@ def update_job_status(job_id: str, status: str) -> None:
     flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
     with os.fdopen(os.open(JOBS_FILE, flags, 0o600), "w") as f:
         f.write(content)
+
+
+def update_job_info(job_id: str, updates: dict) -> None:
+    """
+    Merge fields into a saved job entry.
+
+    Used to persist a resolved call_id so subsequent polls skip the queue check.
+
+    Args:
+        job_id: Job ID to update
+        updates: Dict of fields to merge (e.g., {"call_id": "fc-xxx"})
+    """
+    import os
+
+    if not JOBS_FILE.exists():
+        return
+
+    try:
+        jobs = json.loads(JOBS_FILE.read_text())
+    except (json.JSONDecodeError, IOError):
+        return
+
+    for job in jobs:
+        if job.get("job_id") == job_id:
+            job.update(updates)
+            break
+
+    content = json.dumps(jobs, indent=2)
+    flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC
+    with os.fdopen(os.open(JOBS_FILE, flags, 0o600), "w") as f:
+        f.write(content)

{amina_cli-0.2.5 → amina_cli-0.2.7}/src/amina_cli/client.py

@@ -20,7 +20,13 @@ from typing import Any, Optional
 from uuid import uuid4
 
 from amina_cli.auth import get_api_key, AuthError
-from amina_cli.registry import get_submit_endpoint, get_status_endpoint, get_queued_status_endpoint, ToolNotFoundError
+from amina_cli.registry import (
+    get_submit_endpoint,
+    get_status_endpoint,
+    get_queued_status_endpoint,
+    get_cancel_endpoint,
+    ToolNotFoundError,
+)
 
 
 # Default polling configuration
@@ -92,10 +98,12 @@ class InsufficientCreditsError(ClientError):
 class JobLimitError(ClientError):
     """Raised when user has reached job concurrency limits."""
 
-    def __init__(self, limit_type: str, current: int, limit: int, message: str):
+    def __init__(self, limit_type: str, current: int, limit: int, message: str, **kwargs: Any):
         self.limit_type = limit_type
         self.current = current
         self.limit = limit
+        self.running = kwargs.get("running", 0)
+        self.queued = kwargs.get("queued", 0)
         super().__init__(message)
 
 
@@ -185,6 +193,7 @@ async def _poll_queued_until_submitted(
     poll_interval: float = 5.0,  # Longer interval for queue polling
     max_poll_interval: float = 30.0,
     on_position_update: Optional[QueuePositionCallback] = None,
+    headers: Optional[dict[str, str]] = None,
 ) -> tuple[str, str]:
     """
     Poll queued_job_status until job is submitted.
@@ -229,7 +238,7 @@ async def _poll_queued_until_submitted(
         status_url = f"{queued_endpoint}?job_id={job_id}"
 
         try:
-            response = await client.get(status_url)
+            response = await client.get(status_url, headers=headers or {})
         except httpx.RequestError as e:
             # Log transient error and continue polling
             print(f"Queue poll network error (will retry): {type(e).__name__}: {e}")
@@ -396,6 +405,8 @@ async def run_tool(
                     current=detail.get("current", 0),
                     limit=detail.get("limit", 0),
                     message=detail.get("message", "Job limit reached. Please wait for running jobs to complete."),
+                    running=detail.get("running", 0),
+                    queued=detail.get("queued", 0),
                 )
             except (ValueError, KeyError):
                 raise JobLimitError(
@@ -438,6 +449,7 @@ async def run_tool(
                 poll_interval=5.0,  # Slower for queue
                 max_poll_interval=30.0,
                 on_position_update=on_queue_position_update,
+                headers=auth_headers,
             )
         else:
             # Job was submitted immediately
@@ -663,6 +675,8 @@ async def submit_tool(
                     current=detail.get("current", 0),
                     limit=detail.get("limit", 0),
                     message=detail.get("message", "Job limit reached. Please wait for running jobs to complete."),
+                    running=detail.get("running", 0),
+                    queued=detail.get("queued", 0),
                 )
             except (ValueError, KeyError):
                 raise JobLimitError(
@@ -855,12 +869,16 @@ async def check_queued_job_status(job_id: str) -> dict[str, Any]:
         - {"status": "submitted", "call_id": "..."} if spawned
         - {"status": "failed", "error": "..."} if failed/expired
     """
+    from amina_cli.auth import get_api_key
+
     queued_endpoint = get_queued_status_endpoint()
     status_url = f"{queued_endpoint}?job_id={job_id}"
+    api_key = get_api_key()
+    headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
 
     async with httpx.AsyncClient(timeout=30.0) as client:
         try:
-            response = await client.get(status_url)
+            response = await client.get(status_url, headers=headers)
         except httpx.RequestError as e:
             raise ToolExecutionError(f"Network error checking queued job status: {str(e)}")
 
@@ -883,6 +901,68 @@ def check_queued_job_status_sync(job_id: str) -> dict[str, Any]:
     return asyncio.run(check_queued_job_status(job_id))
 
 
+async def cancel_job(job_id: str, api_key: Optional[str] = None) -> dict[str, Any]:
+    """
+    Cancel a queued or running job.
+
+    Args:
+        job_id: Job ID to cancel
+        api_key: Optional API key (uses stored key if not provided)
+
+    Returns:
+        Dict with status info:
+        - {"status": "cancelled"} on success
+        - {"status": "not_found"} if job doesn't exist
+        - {"status": "already_finished"} if job already completed/failed/cancelled
+
+    Raises:
+        AuthenticationError: If API key is invalid
+        ToolExecutionError: If request fails unexpectedly
+    """
+    if api_key is None:
+        try:
+            api_key = get_api_key()
+        except AuthError as e:
+            raise AuthenticationError(str(e))
+
+    cancel_endpoint = get_cancel_endpoint()
+    url = f"{cancel_endpoint}?job_id={job_id}"
+
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        try:
+            response = await client.post(url, headers={"Authorization": f"Bearer {api_key}"})
+        except httpx.RequestError as e:
+            raise ToolExecutionError(f"Network error cancelling job: {str(e)}")
+
+        if response.status_code == 401:
+            raise AuthenticationError("Invalid API key. Get a new one at: https://app.aminoanalytica.com/settings/api")
+
+        if response.status_code == 404:
+            return {"status": "not_found", "error": "Job not found"}
+
+        if response.status_code == 409:
+            return {"status": "already_finished", "error": "Job already finished"}
+
+        if response.status_code == 200:
+            return response.json()
+
+        raise ToolExecutionError(f"Cancel failed with HTTP {response.status_code}: {response.text}")
+
+
+def cancel_job_sync(job_id: str, api_key: Optional[str] = None) -> dict[str, Any]:
+    """
+    Synchronous wrapper for cancel_job.
+
+    Args:
+        job_id: Job ID to cancel
+        api_key: Optional API key
+
+    Returns:
+        Dict with status info
+    """
+    return asyncio.run(cancel_job(job_id, api_key))
+
+
 def check_endpoint_health(tool_name: str) -> bool:
     """
     Check if a tool's endpoint is reachable.

{amina_cli-0.2.5 → amina_cli-0.2.7}/src/amina_cli/commands/jobs_cmd.py

@@ -21,6 +21,65 @@ app = typer.Typer(no_args_is_help=True)
 console = Console()
 
 
+def _resolve_job_status(job_info: dict) -> dict:
+    """
+    Resolve the current status of a job, handling both spawned and queued jobs.
+
+    If call_id is present, polls Modal directly. If missing (queued job),
+    checks the queue first and resolves call_id when available.
+
+    Args:
+        job_info: Full job info dict from local history
+
+    Returns:
+        Dict with status info (same shape as check_job_status_sync)
+    """
+    from amina_cli.client import check_job_status_sync, check_queued_job_status_sync
+    from amina_cli.auth import update_job_info
+
+    call_id = job_info.get("call_id", "")
+    job_id = job_info.get("job_id", "")
+
+    if call_id:
+        # Normal path: job was spawned, poll Modal directly
+        return check_job_status_sync(
+            call_id=call_id,
+            job_id=job_id,
+            user_id=job_info.get("user_id", ""),
+            tool_name=job_info.get("tool_name", ""),
+            reserved_cost=job_info.get("reserved_cost", 0.0),
+            compute_type=job_info.get("compute_type", "cpu"),
+        )
+
+    # Queued path: no call_id yet, check queue status
+    queue_result = check_queued_job_status_sync(job_id)
+    queue_status = queue_result.get("status", "")
+
+    if queue_status in ("queued", "not_found"):
+        return queue_result
+
+    if queue_status == "failed":
+        return queue_result
+
+    # Job has been spawned (submitted/running/completed) — try to get call_id
+    resolved_call_id = queue_result.get("call_id", "")
+    if not resolved_call_id:
+        # Race condition: status changed but call_id not yet written
+        return {"status": "queued", "message": "Job is being spawned"}
+
+    # Persist call_id so future polls skip the queue check
+    update_job_info(job_id, {"call_id": resolved_call_id})
+
+    return check_job_status_sync(
+        call_id=resolved_call_id,
+        job_id=job_id,
+        user_id=job_info.get("user_id", ""),
+        tool_name=job_info.get("tool_name", ""),
+        reserved_cost=job_info.get("reserved_cost", 0.0),
+        compute_type=job_info.get("compute_type", "cpu"),
+    )
+
+
 @app.command("list")
 def list_jobs(
     limit: int = typer.Option(
@@ -101,7 +160,7 @@ def status(
         amina jobs status abc123 --json
     """
     from amina_cli.auth import get_job_info
-    from amina_cli.client import check_job_status_sync, ToolExecutionError
+    from amina_cli.client import ToolExecutionError
 
     results = []
 
@@ -121,14 +180,7 @@ def status(
 
         # Query server for current status
         try:
-            status_result = check_job_status_sync(
-                call_id=job_info.get("call_id", ""),
-                job_id=job_info.get("job_id", job_id),
-                user_id=job_info.get("user_id", ""),
-                tool_name=job_info.get("tool_name", ""),
-                reserved_cost=job_info.get("reserved_cost", 0.0),
-                compute_type=job_info.get("compute_type", "cpu"),
-            )
+            status_result = _resolve_job_status(job_info)
             results.append(
                 {
                     "job_id": job_info.get("job_id", job_id),
@@ -212,7 +264,7 @@ def wait(
         amina jobs wait abc123 --timeout 7200 --poll-interval 30
     """
     from amina_cli.auth import get_job_info
-    from amina_cli.client import check_job_status_sync, ToolExecutionError
+    from amina_cli.client import ToolExecutionError
 
     start_time = time.time()
     pending_jobs = set(job_ids)
@@ -237,14 +289,7 @@ def wait(
                 continue
 
             try:
-                status_result = check_job_status_sync(
-                    call_id=job_info.get("call_id", ""),
-                    job_id=job_info.get("job_id", job_id),
-                    user_id=job_info.get("user_id", ""),
-                    tool_name=job_info.get("tool_name", ""),
-                    reserved_cost=job_info.get("reserved_cost", 0.0),
-                    compute_type=job_info.get("compute_type", "cpu"),
-                )
+                status_result = _resolve_job_status(job_info)
 
                 if status_result.get("status") in ("completed", "failed"):
                     results[job_id] = {
@@ -290,6 +335,80 @@ def wait(
         raise typer.Exit(1)
 
 
+@app.command("cancel")
+def cancel(
+    job_ids: list[str] = typer.Argument(
+        ...,
+        help="Job ID(s) to cancel",
+    ),
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Output as JSON",
+    ),
+):
+    """
+    Cancel one or more queued or running jobs.
+
+    Sends a cancellation request to the server. Credits are fully refunded.
+
+    Examples:
+        amina jobs cancel abc123
+        amina jobs cancel abc123 def456
+        amina jobs cancel abc123 --json
+    """
+    from amina_cli.auth import get_job_info, update_job_status
+    from amina_cli.client import cancel_job_sync, ToolExecutionError
+
+    results = []
+
+    for job_id in job_ids:
+        job_info = get_job_info(job_id)
+
+        if not job_info:
+            results.append({"job_id": job_id, "status": "not_found", "error": "Job not found in local history"})
+            continue
+
+        full_job_id = job_info.get("job_id", job_id)
+
+        try:
+            cancel_result = cancel_job_sync(full_job_id)
+            status = cancel_result.get("status", "error")
+
+            if status == "cancelled":
+                update_job_status(full_job_id, "cancelled")
+
+            results.append(
+                {
+                    "job_id": full_job_id,
+                    "tool_name": job_info.get("tool_name", ""),
+                    **cancel_result,
+                }
+            )
+        except ToolExecutionError as e:
+            results.append({"job_id": full_job_id, "status": "error", "error": str(e)})
+
+    if json_output:
+        console.print(json.dumps(results, indent=2, default=str))
+        return
+
+    for result in results:
+        job_id_short = result.get("job_id", "")[:8]
+        status_str = result.get("status", "error")
+        tool_name = result.get("tool_name", "")
+        label = f" ({tool_name})" if tool_name else ""
+
+        if status_str == "cancelled":
+            console.print(f"[green]\u2713[/green] {job_id_short}...{label}: [green]cancelled[/green]")
+        elif status_str == "already_finished":
+            console.print(f"[yellow]\u2717[/yellow] {job_id_short}...{label}: [yellow]already finished[/yellow]")
+        elif status_str == "not_found":
+            console.print(f"[dim]?[/dim] {job_id_short}...: [dim]not found[/dim]")
+        else:
+            error = result.get("error", "")
+            console.print(f"[red]\u2717[/red] {job_id_short}...{label}: [red]{status_str}[/red] - {error}")
+
+
 @app.command("download")
 def download(
     job_id: str = typer.Argument(
@@ -312,7 +431,7 @@ def download(
         amina jobs download abc123 -o ./results/
     """
     from amina_cli.auth import get_job_info
-    from amina_cli.client import check_job_status_sync, ToolExecutionError
+    from amina_cli.client import ToolExecutionError
     from amina_cli.storage import download_results, StorageError
 
     # Look up job info
@@ -324,18 +443,16 @@ def download(
 
     # Check status
     try:
-        status_result = check_job_status_sync(
-            call_id=job_info.get("call_id", ""),
-            job_id=job_info.get("job_id", job_id),
-            user_id=job_info.get("user_id", ""),
-            tool_name=job_info.get("tool_name", ""),
-            reserved_cost=job_info.get("reserved_cost", 0.0),
-            compute_type=job_info.get("compute_type", "cpu"),
-        )
+        status_result = _resolve_job_status(job_info)
     except ToolExecutionError as e:
         console.print(f"[red]Error checking job status:[/red] {e}")
         raise typer.Exit(1)
 
+    if status_result.get("status") == "queued":
+        console.print("[yellow]Job is still queued.[/yellow] Wait for completion first:")
+        console.print(f"  amina jobs wait {job_id}")
+        raise typer.Exit(1)
+
     if status_result.get("status") == "running":
         console.print("[yellow]Job is still running.[/yellow] Wait for completion first:")
         console.print(f"  amina jobs wait {job_id}")

amina_cli-0.2.7/src/amina_cli/commands/tools/analysis/residue_accessibility.py

@@ -0,0 +1,121 @@
+"""Residue Accessibility analysis tool for the Amina CLI."""
+
+import typer
+from pathlib import Path
+from typing import Optional
+from rich.console import Console
+
+METADATA = {
+    "name": "residue_accessibility",
+    "display_name": "Residue Accessibility",
+    "category": "analysis",
+    "description": "Score residues for binder accessibility beyond SASA using depth, visibility, and curvature",
+    "modal_function_name": "residue_accessibility_worker",
+    "modal_app_name": "residue-accessibility-api",
+    "status": "available",
+    "outputs": {
+        "json_filepath": "Full structured results (residues, patches, recommendation)",
+        "csv_filepath": "Per-residue accessibility scores in CSV format",
+        "pdb_filepath": "PDB with B-factors set to accessibility tier scores",
+    },
+}
+
+console = Console()
+
+
+def register(app: typer.Typer):
+    """Register this tool's command with the app."""
+    from amina_cli.commands.tools import run_tool_with_progress
+
+    @app.command("residue-accessibility")
+    def run_residue_accessibility(
+        pdb: Path = typer.Option(
+            ...,
+            "--pdb",
+            "-p",
+            help="Path to PDB file containing protein structure",
+            exists=True,
+        ),
+        output: Optional[Path] = typer.Option(
+            None,
+            "--output",
+            "-o",
+            help="Output directory for results (required unless --background)",
+        ),
+        residues: Optional[str] = typer.Option(
+            None,
+            "--residues",
+            "-r",
+            help="Residues to score in CHAIN:RESNUM format (e.g., 'A:42,A:43,B:10'). "
+            "If omitted, all surface-exposed residues are scored.",
+        ),
+        rsa_threshold: float = typer.Option(
+            0.20,
+            "--rsa-threshold",
+            help="RSA cutoff for the exposure gate (0.0-1.0). Residues below this are excluded.",
+        ),
+        n_rays: int = typer.Option(
+            200,
+            "--n-rays",
+            help="Number of hemisphere rays per residue for visibility scoring (10-1000).",
+        ),
+        job_name: Optional[str] = typer.Option(
+            None,
+            "--job-name",
+            "-j",
+            help="Custom job name for output files (default: random 4-letter code)",
+        ),
+        background: bool = typer.Option(
+            False,
+            "--background",
+            "-b",
+            help="Submit job and return immediately without waiting for completion",
+        ),
+    ):
+        """
+        Score protein residues for binder accessibility.
+
+        Goes beyond SASA to measure residue depth, outward visibility (ray casting),
+        and surface curvature. Returns a ranked list of residues scored 0–1 for
+        binder accessibility.
+
+        Examples:
+            amina run residue-accessibility --pdb ./target.pdb -o ./results/
+            amina run residue-accessibility --pdb ./target.pdb -r "A:42,A:43,A:45" -o ./results/
+            amina run residue-accessibility --pdb ./target.pdb --rsa-threshold 0.15 -o ./results/
+            amina run residue-accessibility --pdb ./target.pdb -j myjob -o ./results/ --background
+        """
+        # Validate required options
+        if output is None and not background:
+            console.print("[red]Error:[/red] --output / -o is required (unless using --background)")
+            raise typer.Exit(1)
+
+        # Validate residue format if provided
+        if residues:
+            for token in residues.split(","):
+                token = token.strip()
+                if ":" not in token:
+                    console.print(
+                        f"[red]Error:[/red] Invalid residue format '{token}'. Expected CHAIN:RESNUM (e.g., 'A:42')."
+                    )
+                    raise typer.Exit(1)
+
+        # Read PDB file content
+        pdb_content = pdb.read_text()
+        console.print(f"Read PDB file: {pdb.name}")
+
+        # Build params dict matching worker's expected fields
+        params = {
+            "pdb_content": pdb_content,
+            "rsa_threshold": rsa_threshold,
+            "n_rays": n_rays,
+        }
+
+        if residues:
+            params["residues"] = residues
+
+        if job_name:
+            params["job_name"] = job_name
+
+        # Execute
+        run_tool_with_progress("residue_accessibility", params, output, background=background)

{amina_cli-0.2.5 → amina_cli-0.2.7}/src/amina_cli/registry.py

@@ -80,6 +80,17 @@ def get_queued_status_endpoint() -> str:
     return f"{base}-queued-job-status.modal.run"
 
 
+def get_cancel_endpoint() -> str:
+    """
+    Get the cancel_job endpoint URL.
+
+    Returns:
+        Cancel job endpoint URL (job_id added as query param by client)
+    """
+    base = _get_gateway_base()
+    return f"{base}-cancel-job.modal.run"
+
+
 # Legacy function for backwards compatibility
 def get_tool_endpoint(name: str) -> str:
     """