amina-cli 0.2.6__tar.gz → 0.2.8__tar.gz

{amina_cli-0.2.6 → amina_cli-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amina-cli
-Version: 0.2.6
+Version: 0.2.8
 Summary: CLI for AminoAnalytica protein engineering platform
 Project-URL: Homepage, https://aminoanalytica.com
 Project-URL: Documentation, https://docs.aminoanalytica.com
@@ -20,6 +20,7 @@ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27.0
 Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: supabase>=2.0.0
 Requires-Dist: typer>=0.9.0

{amina_cli-0.2.6 → amina_cli-0.2.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "amina-cli"
-version = "0.2.6"
+version = "0.2.8"
 description = "CLI for AminoAnalytica protein engineering platform"
 readme = "README.md"
 license = {text = "Apache-2.0"}
@@ -26,6 +26,7 @@ dependencies = [
     "rich>=13.0.0",      # Beautiful terminal output (included with typer)
     "pydantic>=2.0",     # Data validation
     "supabase>=2.0.0",   # Supabase client for file operations
+    "pyyaml>=6.0",       # YAML parsing for tool doccards
 ]
 
 [project.scripts]

{amina_cli-0.2.6 → amina_cli-0.2.8}/src/amina_cli/__init__.py

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

{amina_cli-0.2.6 → amina_cli-0.2.8}/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
@@ -895,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.6 → amina_cli-0.2.8}/src/amina_cli/commands/jobs_cmd.py

@@ -335,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(

{amina_cli-0.2.6 → amina_cli-0.2.8}/src/amina_cli/commands/tools/__init__.py

@@ -22,9 +22,15 @@ def discover_tools() -> Iterator[tuple[str, dict, callable]]:
     """
     Discover all tools in category subfolders.
 
+    For each tool, attempts to load a doccard YAML first. If a valid doccard
+    exists, it becomes the METADATA for that tool. Otherwise falls back to
+    the Python METADATA dict.
+
     Yields:
         (module_name, METADATA dict, register function)
     """
+    from amina_cli.commands.tools.doccard import load_doccard
+
     tools_dir = Path(__file__).parent
 
     for category_dir in sorted(tools_dir.iterdir()):
@@ -39,7 +45,14 @@ def discover_tools() -> Iterator[tuple[str, dict, callable]]:
             try:
                 module = importlib.import_module(module_name)
                 if hasattr(module, "METADATA") and hasattr(module, "register"):
-                    yield module_name, module.METADATA, module.register
+                    metadata = module.METADATA
+                    # Try doccard YAML override
+                    category = category_dir.name
+                    tool_name = metadata.get("name", tool_file.stem)
+                    doccard = load_doccard(category, tool_name)
+                    if doccard is not None:
+                        metadata = doccard
+                    yield module_name, metadata, module.register
             except ImportError as e:
                 console.print(f"[dim]Warning: Could not load {module_name}: {e}[/dim]")
 
@@ -339,6 +352,53 @@ def run_tool_with_progress(
         raise typer.Exit(1)
 
 
+def _get_metrics_reference(metadata: dict | None, result: dict) -> list[tuple[str, str]]:
+    """
+    Build a metrics reference from doccard output_metrics, filtered to only
+    include metrics that appear in the actual result data.
+
+    Returns list of (display_name, description) tuples.
+    """
+    if not metadata:
+        return []
+    output_metrics = metadata.get("output_metrics")
+    if not output_metrics:
+        return []
+
+    # Collect all keys present in result data (top-level and nested in data)
+    data = result.get("data", {}) or {}
+    all_keys = set(result.keys()) | set(data.keys())
+    # Also check inside nested structures (e.g., predictions[0])
+    output_display = metadata.get("output_display", {})
+    if output_display:
+        from amina_cli.commands.tools.display import _get_nested_value
+
+        data_path = output_display.get("data_path")
+        if data_path:
+            merged = {**result, **data}
+            extracted = _get_nested_value(merged, data_path)
+            if isinstance(extracted, dict):
+                all_keys |= set(extracted.keys())
+
+    references = []
+    for metric_key, metric_info in output_metrics.items():
+        if metric_key in all_keys:
+            display_name = metric_info.get("display_name", metric_key)
+            desc = metric_info.get("description", "").strip()
+            metric_range = metric_info.get("range")
+            interp = metric_info.get("interpretation", "").strip()
+
+            # Build compact reference line
+            parts = [desc]
+            if metric_range:
+                parts.append(f"Range: {metric_range[0]}–{metric_range[1]}.")
+            if interp:
+                parts.append(interp)
+            references.append((display_name, " ".join(parts)))
+
+    return references
+
+
 def _display_result(
     result: dict,
     downloaded: list[Path],
@@ -403,6 +463,13 @@ def _display_result(
                 for key, value in display_params.items():
                     console.print(f"  {key}: {value}")
 
+        # Append metrics reference from doccard (anti-hallucination)
+        metrics_ref = _get_metrics_reference(metadata, result)
+        if metrics_ref:
+            console.print("\n[bold]Metrics Reference[/bold]")
+            for display_name, description in metrics_ref:
+                console.print(f"  [cyan]{display_name}[/cyan]: {description}")
+
     else:
         # Check error_details first (from gateway), then error, then message
         error_msg = result.get("error_details") or result.get("error") or result.get("message", "Unknown error")

amina_cli-0.2.8/src/amina_cli/commands/tools/analysis/docs/hydrophobicity.yaml

@@ -0,0 +1,243 @@
+# ─── Identity & Routing ───
+name: hydrophobicity
+display_name: Hydrophobicity Analysis
+category: analysis
+status: available
+modal_app_name: hydrophobicity-analysis-api
+modal_function_name: hydrophobicity_worker
+
+# ─── Documentation ───
+description: |
+  Analyze the distribution of hydrophobic residues between a protein's core and
+  surface regions. Classifies residues using an automatically determined SASA
+  threshold and reports hydrophobic burial, surface exposure, and core contact metrics.
+
+when_to_use: |
+  - Assessing how well hydrophobic residues are buried in the protein core
+  - Comparing hydrophobic packing between wild-type and mutant structures
+  - Evaluating protein stability indicators (hydrophobic core quality)
+  - Analyzing surface hydrophobicity for aggregation risk assessment
+
+when_not_to_use: |
+  - Simple solvent exposure per residue → use **SASA**
+  - Binder-accessible surface scoring with depth/visibility → use **Residue Accessibility**
+  - Protein surface electrostatics → use **Surface Charge**
+
+tool_algorithm: |
+  1. **SASA calculation**: Per-residue solvent accessible surface area is computed
+     using the Shrake-Rupley algorithm (probe radius 1.4 Angstroms) via mdtraj.
+
+  2. **Relative SASA normalization**: Each residue's SASA is divided by the maximum
+     theoretical SASA for its amino acid type (reference values from Miller et al. 2013).
+
+  3. **Optimal threshold detection**: The relative SASA threshold that best separates
+     core from surface residues is found by scanning thresholds from 0 to 1.0 in steps
+     of `threshold_step` (default 0.001) and locating the point of maximum change in
+     core residue count (the inflection point of the sigmoidal transition curve).
+     Falls back to 0.5 if no pronounced transition is detected.
+
+  4. **Core/surface classification**: Residues with relative SASA below the optimal
+     threshold are classified as core; those at or above are classified as surface.
+
+  5. **Hydrophobic residue identification**: Residues are identified as hydrophobic
+     using the Kyte-Doolittle scale: ALA, VAL, ILE, LEU, MET, PHE, TRP, TYR.
+
+  6. **Contact analysis**: Pairwise distances between CA atoms of core hydrophobic
+     residues are computed. Pairs within the critical distance (default 5.0 Angstroms)
+     are counted as hydrophobic-hydrophobic contacts, indicating core packing quality.
+
+additional_context: |
+  - The sigmoidal transition plot (enabled by default) visualizes how core residue
+    count changes as the SASA threshold varies, with the optimal threshold marked.
+    This is useful for validating the automatic threshold selection.
+  - A well-folded protein typically has >40% of hydrophobic residues buried in the core.
+  - High hydrophobic-hydrophobic contact counts indicate tight core packing.
+  - The tool runs on CPU only (no GPU required), typically completing in under 60 seconds.
+
+# ─── Parameters ───
+# Parameter definitions are canonical here — keep in sync with hydrophobicity.py
+parameters:
+  pdb:
+    type: file
+    required: true
+    description: |
+      Path to PDB file containing the protein structure to analyze.
+
+  savecsv:
+    type: boolean
+    default: true
+    description: |
+      Save detailed results to a CSV file. Use `--no-csv` to disable.
+
+  plot:
+    type: boolean
+    default: true
+    description: |
+      Save the sigmoidal transition plot showing core residue count vs
+      SASA threshold. Use `--no-plot` to disable.
+
+  threshold-step:
+    type: float
+    default: 0.001
+    range: [0.0, 1.0]
+    description: |
+      Step size for scanning SASA thresholds when detecting the optimal
+      core/surface boundary. Smaller values give finer resolution but
+      take longer. Default 0.001 is usually sufficient.
+
+  critical-distance:
+    type: float
+    default: 5.0
+    description: |
+      Maximum distance in Angstroms between CA atoms for two core
+      hydrophobic residues to be counted as a contact. Default 5.0
+      Angstroms is standard for residue-residue contact analysis.
+
+  job-name:
+    type: string
+    required: false
+    description: |
+      Custom job name for output files. Defaults to a random 4-letter code.
+
+  background:
+    type: boolean
+    default: false
+    description: |
+      Submit job and return immediately without waiting for completion.
+
+# ─── Output Files ───
+outputs:
+  csv_filepath: Detailed hydrophobicity analysis results CSV
+  plot_filepath: Sigmoidal transition plot (if enabled)
+
+# ─── Output Metrics ───
+output_metrics:
+  optimal_threshold_pct:
+    display_name: Optimal Threshold
+    description: |
+      **Optimal Surface/Core Threshold** (%) — the relative SASA percentage that
+      best separates core from surface residues, determined automatically by finding
+      the inflection point of the sigmoidal transition curve. Residues with relative
+      SASA below this value are classified as core.
+    range: [0, 100]
+    interpretation: |
+      - Typical range: 20–50%
+      - Lower threshold = stricter core definition (fewer, more deeply buried residues)
+      - If fallback to 50% is used, the protein may lack a clear core/surface transition
+
+  total_residues:
+    display_name: Total Residues
+    description: |
+      Total number of residues in the analyzed protein structure.
+
+  core_residues:
+    display_name: Core Residues
+    description: |
+      Number of residues classified as core (relative SASA below the optimal threshold).
+    interpretation: |
+      Compare to total residues for proportion buried. Well-folded globular proteins
+      typically have 30–60% of residues in the core.
+
+  surface_residues:
+    display_name: Surface Residues
+    description: |
+      Number of residues classified as surface (relative SASA at or above the optimal threshold).
+
+  hydrophobic_core_pct:
+    display_name: Hydrophobic Core %
+    description: |
+      Percentage of total residues that are both hydrophobic (Kyte-Doolittle:
+      ALA, VAL, ILE, LEU, MET, PHE, TRP, TYR) and buried in the core.
+    range: [0, 100]
+    interpretation: |
+      - >40%: Strong hydrophobic core — typical of well-folded globular proteins
+      - 20–40%: Moderate core burial
+      - <20%: Weak hydrophobic core — may indicate poor folding or intrinsic disorder
+
+  total_sasa:
+    display_name: Total SASA
+    description: |
+      Total solvent accessible surface area of the entire protein, measured in nm^2.
+      Computed via Shrake-Rupley algorithm.
+
+  hydrophobic_sasa:
+    display_name: Hydrophobic SASA
+    description: |
+      Solvent accessible surface area contributed by hydrophobic residues only,
+      measured in nm^2.
+
+  hydrophobic_sasa_pct:
+    display_name: Hydrophobic SASA %
+    description: |
+      Percentage of total SASA contributed by hydrophobic residues.
+    range: [0, 100]
+    interpretation: |
+      - Lower values indicate better hydrophobic burial (hydrophobic residues shielded from solvent)
+      - Higher values suggest more hydrophobic surface exposure (potential aggregation risk)
+
+  hydrophobic_contacts:
+    display_name: Hydrophobic Contacts
+    description: |
+      Number of pairwise contacts between core hydrophobic residues (CA atoms
+      within the critical distance, default 5.0 Angstroms). Measures the density
+      of hydrophobic packing in the protein core.
+    interpretation: |
+      - Higher count = denser hydrophobic core packing (generally favorable for stability)
+      - Scales with protein size — compare between variants of the same protein
+
+# ─── Output Display ───
+output_display:
+  data_path: hydrophobicity_results
+  sections:
+    - title: Classification
+      fields:
+        - key: optimal_threshold_pct
+          label: Optimal Threshold (%)
+          format: "{:.1f}%"
+        - key: total_residues
+          label: Total Residues
+        - key: core_residues
+          label: Core Residues
+        - key: surface_residues
+          label: Surface Residues
+    - title: Hydrophobicity Metrics
+      fields:
+        - key: hydrophobic_core_pct
+          label: Hydrophobic Core (%)
+          format: "{:.1f}%"
+        - key: total_sasa
+          label: Total SASA (nm^2)
+          format: "{:.2f}"
+        - key: hydrophobic_sasa
+          label: Hydrophobic SASA (nm^2)
+          format: "{:.2f}"
+        - key: hydrophobic_sasa_pct
+          label: Hydrophobic SASA (%)
+          format: "{:.1f}%"
+        - key: hydrophobic_contacts
+          label: Hydrophobic-Hydrophobic Contacts
+
+# ─── Examples ───
+examples:
+  - title: Basic analysis
+    command: amina run hydrophobicity --pdb ./protein.pdb -o ./results/
+  - title: Without plot
+    command: amina run hydrophobicity --pdb ./protein.pdb --no-plot -o ./results/
+  - title: Custom threshold resolution
+    command: amina run hydrophobicity --pdb ./protein.pdb --threshold-step 0.0001 -o ./results/
+
+# ─── References ───
+references:
+  - title: "Kyte & Doolittle (1982) - Hydropathy scale"
+    url: "https://doi.org/10.1016/0022-2836(82)90515-0"
+  - title: "Miller et al. (2013) - Maximum SASA reference values"
+    url: "https://doi.org/10.1371/journal.pone.0080635"
+  - title: "Shrake & Rupley (1973) - SASA algorithm"
+    url: "https://doi.org/10.1016/0022-2836(73)90011-9"
+
+# ─── REVIEW STATUS: All definitions verified from source code and documentation ───
+# - All metric keys verified against worker.py lines 236-245
+# - Algorithm verified against analyzer.py
+# - Hydrophobic residue set verified against analyzer.py line 49 (Kyte-Doolittle)
+# - MAX_SASA references verified against analyzer.py lines 25-46 (Miller et al. 2013)
+# - Shrake-Rupley confirmed in analyzer.py SASA computation