tamarind-cli 0.1.0__py3-none-any.whl

tamarind/config.py

@@ -0,0 +1,152 @@
+"""Configuration and credential resolution.
+
+Settings are resolved in this order (first wins):
+
+    1. an explicit value passed on the command line (``--api-key`` etc.)
+    2. an environment variable (``TAMARIND_API_KEY`` / ``TAMARIND_API_BASE`` /
+       ``TAMARIND_CATALOG_BASE`` / ``TAMARIND_PROFILE``)
+    3. the selected profile in ``~/.tamarind/config.json``
+    4. a built-in default (base URLs only — there is no default API key)
+
+This mirrors how the AWS CLI and similar tools layer flags > env > file, so it
+is predictable for both humans and agents (an agent typically just exports
+``TAMARIND_API_KEY``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_API_BASE = "https://app.tamarind.bio/api/"
+# Discovery (tools/schema/modalities/functions) is served by the catalog
+# service. It is a separate host from the job API because the catalog runs
+# behind per-org visibility logic; see the package docstring.
+DEFAULT_CATALOG_BASE = "https://mcp.tamarind.bio"
+
+DEFAULT_PROFILE = "default"
+
+
+def config_dir() -> Path:
+    """Resolved each call so TAMARIND_CONFIG_DIR can change between invocations."""
+    return Path(os.environ.get("TAMARIND_CONFIG_DIR", Path.home() / ".tamarind"))
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+@dataclass
+class Config:
+    """Resolved settings for a single invocation."""
+
+    api_key: str | None
+    api_base: str
+    catalog_base: str
+    profile: str
+
+    @property
+    def has_key(self) -> bool:
+        return bool(self.api_key)
+
+
+def _read_store() -> dict:
+    path = config_path()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def _write_store(store: dict) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(store, indent=2) + "\n")
+    # Credentials live here — keep the file private (best effort on POSIX).
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+
+
+def _normalize_base(url: str) -> str:
+    """Trailing slash matters for httpx base_url + relative paths."""
+    return url if url.endswith("/") else url + "/"
+
+
+def resolve_profile_name(profile: str | None) -> str:
+    if profile:
+        return profile
+    if os.environ.get("TAMARIND_PROFILE"):
+        return os.environ["TAMARIND_PROFILE"]
+    store = _read_store()
+    return store.get("current_profile", DEFAULT_PROFILE)
+
+
+def load_config(
+    *,
+    api_key: str | None = None,
+    api_base: str | None = None,
+    catalog_base: str | None = None,
+    profile: str | None = None,
+) -> Config:
+    """Resolve effective settings (flags > env > profile > default)."""
+    profile_name = resolve_profile_name(profile)
+    store = _read_store()
+    prof = store.get("profiles", {}).get(profile_name, {})
+
+    resolved_key = api_key or os.environ.get("TAMARIND_API_KEY") or prof.get("api_key")
+    resolved_api_base = (
+        api_base
+        or os.environ.get("TAMARIND_API_BASE")
+        or prof.get("api_base")
+        or DEFAULT_API_BASE
+    )
+    resolved_catalog_base = (
+        catalog_base
+        or os.environ.get("TAMARIND_CATALOG_BASE")
+        or prof.get("catalog_base")
+        or DEFAULT_CATALOG_BASE
+    )
+
+    return Config(
+        api_key=resolved_key,
+        api_base=_normalize_base(resolved_api_base),
+        catalog_base=_normalize_base(resolved_catalog_base),
+        profile=profile_name,
+    )
+
+
+def save_profile(
+    profile: str,
+    *,
+    api_key: str | None = None,
+    api_base: str | None = None,
+    catalog_base: str | None = None,
+    make_current: bool = True,
+) -> None:
+    """Persist credentials/endpoints for a profile to ``~/.tamarind/config.json``."""
+    store = _read_store()
+    profiles = store.setdefault("profiles", {})
+    prof = profiles.setdefault(profile, {})
+    if api_key is not None:
+        prof["api_key"] = api_key
+    if api_base is not None:
+        prof["api_base"] = api_base
+    if catalog_base is not None:
+        prof["catalog_base"] = catalog_base
+    if make_current:
+        store["current_profile"] = profile
+    _write_store(store)
+
+
+def mask_key(key: str | None) -> str:
+    if not key:
+        return "<none>"
+    if len(key) <= 8:
+        return "*" * len(key)
+    return f"{key[:4]}…{key[-4:]}"

tamarind/errors.py

@@ -0,0 +1,59 @@
+"""Exception types and exit codes for the Tamarind client.
+
+Exit codes are stable so agents and CI can branch on them:
+
+    0  success
+    1  generic / unexpected error
+    2  usage error (bad arguments) — Typer's default
+    3  authentication error (no key, or 401)
+    4  not found (404)
+    5  validation error (a job's settings failed validate-job, or a 400)
+    6  rate limited (429)
+"""
+
+from __future__ import annotations
+
+
+class ExitCode:
+    OK = 0
+    ERROR = 1
+    USAGE = 2
+    AUTH = 3
+    NOT_FOUND = 4
+    VALIDATION = 5
+    RATE_LIMIT = 6
+
+
+class TamarindError(Exception):
+    """Base class for all client errors. Carries a stable exit code."""
+
+    exit_code: int = ExitCode.ERROR
+
+    def __init__(self, message: str, *, detail: object | None = None):
+        super().__init__(message)
+        self.message = message
+        self.detail = detail
+
+
+class AuthError(TamarindError):
+    exit_code = ExitCode.AUTH
+
+
+class NotFoundError(TamarindError):
+    exit_code = ExitCode.NOT_FOUND
+
+
+class ValidationError(TamarindError):
+    exit_code = ExitCode.VALIDATION
+
+
+class RateLimitError(TamarindError):
+    exit_code = ExitCode.RATE_LIMIT
+
+
+class APIError(TamarindError):
+    """A non-2xx response that doesn't map to a more specific error."""
+
+    def __init__(self, message: str, *, status_code: int, detail: object | None = None):
+        super().__init__(message, detail=detail)
+        self.status_code = status_code

tamarind/http.py

@@ -0,0 +1,160 @@
+"""Thin HTTP transport shared by the REST and catalog clients.
+
+Wraps ``httpx.Client`` with the ``x-api-key`` header the Tamarind API expects,
+and maps non-2xx responses onto the typed errors in :mod:`tamarind.errors` so
+callers (and the CLI's exit codes) get consistent behaviour.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from .errors import (
+    APIError,
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    TamarindError,
+    ValidationError,
+)
+
+DEFAULT_TIMEOUT = 120.0
+USER_AGENT = "tamarind-cli"
+
+
+class HTTPClient:
+    """A small wrapper around ``httpx.Client`` keyed by base URL + API key."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        self.base_url = base_url
+        self.api_key = api_key
+        headers = {
+            "Accept": "application/json",
+            # Brotli is still decoded transparently by httpx; we just don't want
+            # surprises from upstream content-encoding negotiation.
+            "Accept-Encoding": "identity",
+            "User-Agent": f"{USER_AGENT}/{_version()}",
+        }
+        if api_key:
+            headers["x-api-key"] = api_key
+        self._client = httpx.Client(base_url=base_url, headers=headers, timeout=timeout)
+
+    # -- lifecycle ---------------------------------------------------------
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HTTPClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- requests ----------------------------------------------------------
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any | None = None,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        if not self.api_key:
+            raise AuthError(
+                "No API key configured. Set TAMARIND_API_KEY, pass --api-key, "
+                "or run `tamarind auth login`."
+            )
+        # Drop None-valued query params so we don't send `?x=None`.
+        clean_params = (
+            {k: v for k, v in params.items() if v is not None} if params else None
+        )
+        try:
+            resp = self._client.request(
+                method,
+                path.lstrip("/"),
+                params=clean_params,
+                json=json,
+                timeout=timeout if timeout is not None else httpx.USE_CLIENT_DEFAULT,
+            )
+        except httpx.HTTPError as exc:
+            raise TamarindError(f"Network error talking to {self.base_url}: {exc}") from exc
+
+        if resp.is_success:
+            return resp
+        raise _map_error(resp)
+
+    def get_json(self, path: str, *, params: dict[str, Any] | None = None) -> Any:
+        return _parse_json(self.request("GET", path, params=params))
+
+    def post_json(self, path: str, *, json: Any | None = None) -> Any:
+        return _parse_json(self.request("POST", path, json=json))
+
+    def delete_json(
+        self, path: str, *, params: dict[str, Any] | None = None, json: Any | None = None
+    ) -> Any:
+        return _parse_json(self.request("DELETE", path, params=params, json=json))
+
+
+def _parse_json(resp: httpx.Response) -> Any:
+    text = resp.text.strip()
+    if not text:
+        return None
+    try:
+        return resp.json()
+    except ValueError:
+        # Some endpoints (e.g. /result) return a bare presigned URL string.
+        return text
+
+
+def _extract_message(resp: httpx.Response) -> str:
+    try:
+        body = resp.json()
+    except ValueError:
+        return resp.text.strip() or resp.reason_phrase or f"HTTP {resp.status_code}"
+    if isinstance(body, dict):
+        for key in ("error", "message", "detail"):
+            if body.get(key):
+                return str(body[key])
+    if isinstance(body, str):
+        return body
+    return resp.reason_phrase or f"HTTP {resp.status_code}"
+
+
+def _map_error(resp: httpx.Response) -> TamarindError:
+    msg = _extract_message(resp)
+    code = resp.status_code
+    ml = msg.lower()
+    auth_ish = "api key" in ml or "api-key" in ml or "apikey" in ml or "unauthorized" in ml
+    notfound_ish = "not found" in ml or "does not exist" in ml or "no such" in ml
+    if code == 401:
+        return AuthError(f"Unauthorized: {msg}")
+    if code == 403:
+        return AuthError(f"Access denied: {msg}")
+    if code == 404:
+        return NotFoundError(msg)
+    if code == 400:
+        # The API uses 400 for several distinct failures; classify by message so
+        # exit codes are consistent: bad/missing key -> auth (3), missing job/file
+        # -> not-found (4), otherwise a genuine validation error (5).
+        if auth_ish:
+            return AuthError(f"Unauthorized: {msg}")
+        if notfound_ish:
+            return NotFoundError(msg)
+        return ValidationError(msg)
+    if code == 429:
+        return RateLimitError(f"Rate limited: {msg}")
+    return APIError(msg, status_code=code)
+
+
+def _version() -> str:
+    from . import __version__
+
+    return __version__

tamarind/jobs.py

@@ -0,0 +1,106 @@
+"""Job-status helpers: normalization and polling.
+
+The REST job objects use capitalized keys (``JobName``, ``JobStatus``, ...).
+The status enum is {Complete, In Queue, Running, Stopped, Deleted}; we also
+treat Failed/Cancelled/Error as terminal defensively in case the backend grows
+new terminal states.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable
+
+from . import rest
+from .errors import NotFoundError
+from .http import HTTPClient
+
+# Compared case-insensitively.
+TERMINAL_STATUSES = {"complete", "completed", "stopped", "deleted", "failed", "cancelled", "error"}
+SUCCESS_STATUSES = {"complete", "completed"}
+
+
+def job_status(job: dict[str, Any]) -> str | None:
+    """Read a job's status regardless of which casing the API used."""
+    for key in ("JobStatus", "status", "Status"):
+        if job.get(key):
+            return str(job[key])
+    return None
+
+
+def job_name(job: dict[str, Any]) -> str | None:
+    for key in ("JobName", "jobName", "name"):
+        if job.get(key):
+            return str(job[key])
+    return None
+
+
+def is_terminal(status: str | None) -> bool:
+    return bool(status) and status.lower() in TERMINAL_STATUSES
+
+
+def is_success(status: str | None) -> bool:
+    return bool(status) and status.lower() in SUCCESS_STATUSES
+
+
+def fetch_job(client: HTTPClient, name: str) -> dict[str, Any]:
+    """Fetch a single job by name. Raises NotFoundError if it doesn't exist."""
+    resp = rest.get_jobs(client, job_name=name)
+    job = _extract_single(resp, name)
+    if job is None:
+        raise NotFoundError(f"Job '{name}' not found")
+    return job
+
+
+def _extract_single(resp: Any, name: str) -> dict[str, Any] | None:
+    if not isinstance(resp, dict):
+        return None
+
+    # Shape A: {"jobs": [...]}
+    if "jobs" in resp:
+        jobs = resp.get("jobs") or []
+        for j in jobs:
+            if job_name(j) == name:
+                return j
+        return jobs[0] if jobs else None
+
+    # Shape B: an index-keyed map {"0": {...}, "1": {...}, "statuses": {...}} —
+    # what the job API returns for a single-jobName query.
+    indexed = [v for k, v in resp.items() if k.isdigit() and isinstance(v, dict)]
+    if indexed:
+        for j in indexed:
+            if job_name(j) == name:
+                return j
+        return indexed[0]
+
+    # Shape C: a bare JobInfo object.
+    if any(k in resp for k in ("JobName", "JobStatus", "jobName", "status")):
+        return resp
+    return None
+
+
+def wait_for_job(
+    client: HTTPClient,
+    name: str,
+    *,
+    poll_interval: float = 10.0,
+    timeout: float | None = None,
+    on_poll: Callable[[dict[str, Any]], None] | None = None,
+) -> dict[str, Any]:
+    """Block until ``name`` reaches a terminal status (or ``timeout`` elapses).
+
+    Returns the final job object. Raises TimeoutError if a timeout is set and
+    the job is still running when it elapses.
+    """
+    deadline = None if timeout is None else time.monotonic() + timeout
+    while True:
+        job = fetch_job(client, name)
+        if on_poll is not None:
+            on_poll(job)
+        if is_terminal(job_status(job)):
+            return job
+        if deadline is not None and time.monotonic() >= deadline:
+            raise TimeoutError(
+                f"Job '{name}' still {job_status(job)!r} after {timeout:.0f}s"
+            )
+        time.sleep(poll_interval)

tamarind/rest.py

@@ -0,0 +1,192 @@
+"""Typed wrappers over the Tamarind REST API (the job/file surface).
+
+Every function here maps 1:1 onto an operation in ``openapi-mcp.yaml`` — the
+same spec the Tamarind MCP server is built from. Keeping this a thin, literal
+mapping (no business logic) is what keeps the CLI and the MCP from drifting on
+the REST surface. Discovery/catalog calls live in :mod:`tamarind.catalog`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import APIError
+from .http import HTTPClient
+
+# Query params that the API expects as the literal string "true" rather than a
+# JSON boolean.
+_TRUE = "true"
+
+
+def submit_job(
+    client: HTTPClient, *, job_name: str, job_type: str, settings: dict[str, Any]
+) -> Any:
+    """POST /submit-job — submit a single job. Body: {jobName, type, settings}."""
+    return client.post_json(
+        "submit-job",
+        json={"jobName": job_name, "type": job_type, "settings": settings},
+    )
+
+
+def validate_job(
+    client: HTTPClient, *, job_name: str, job_type: str, settings: dict[str, Any]
+) -> dict:
+    """POST /validate-job — returns {valid, normalized?, error?} (HTTP 200 either way)."""
+    return client.post_json(
+        "validate-job",
+        json={"jobName": job_name, "type": job_type, "settings": settings},
+    )
+
+
+def submit_batch(
+    client: HTTPClient,
+    *,
+    batch_name: str,
+    job_type: str,
+    settings: list[dict[str, Any]],
+    job_names: list[str] | None = None,
+    max_runtime_seconds: int | None = None,
+) -> Any:
+    """POST /submit-batch — submit many jobs as one batch."""
+    body: dict[str, Any] = {
+        "batchName": batch_name,
+        "type": job_type,
+        "settings": settings,
+    }
+    if job_names is not None:
+        body["jobNames"] = job_names
+    if max_runtime_seconds is not None:
+        body["maxRuntimeSeconds"] = max_runtime_seconds
+    return client.post_json("submit-batch", json=body)
+
+
+def get_jobs(
+    client: HTTPClient,
+    *,
+    job_name: str | None = None,
+    batch: str | None = None,
+    start_key: str | None = None,
+    limit: int | None = None,
+    organization: bool = False,
+    include_subjobs: bool = False,
+    job_email: str | None = None,
+) -> Any:
+    """GET /jobs — list jobs, or fetch one when ``job_name`` is given."""
+    params = {
+        "jobName": job_name,
+        "batch": batch,
+        "startKey": start_key,
+        "limit": limit,
+        "organization": _TRUE if organization else None,
+        "includeSubjobs": _TRUE if include_subjobs else None,
+        "jobEmail": job_email,
+    }
+    return client.get_json("jobs", params=params)
+
+
+def get_result(
+    client: HTTPClient,
+    *,
+    job_name: str,
+    job_email: str | None = None,
+    file_name: str | None = None,
+    pdbs_only: bool | None = None,
+) -> Any:
+    """POST /result — returns an S3 presigned URL (string) for the result bundle."""
+    body: dict[str, Any] = {"jobName": job_name}
+    if job_email is not None:
+        body["jobEmail"] = job_email
+    if file_name is not None:
+        body["fileName"] = file_name
+    if pdbs_only is not None:
+        body["pdbsOnly"] = pdbs_only
+    return client.post_json("result", json=body)
+
+
+def upload_file_url(client: HTTPClient, *, filename: str) -> dict:
+    """POST /uploadFile — returns {signedUrl, filename}; PUT the bytes to signedUrl."""
+    return client.post_json("uploadFile", json={"filename": filename})
+
+
+def cancel_job(
+    client: HTTPClient, *, job_name: str | None = None, job_id: str | None = None
+) -> dict:
+    """POST /cancelJob — soft-stop a queued/running job (preserves the row)."""
+    body: dict[str, Any] = {}
+    if job_name is not None:
+        body["jobName"] = job_name
+    if job_id is not None:
+        body["jobId"] = job_id
+    return client.post_json("cancelJob", json=body)
+
+
+def cancel_batch(client: HTTPClient, *, batch_name: str) -> dict:
+    """POST /cancelBatch — soft-stop every job in a batch or pipeline."""
+    return client.post_json("cancelBatch", json={"batchName": batch_name})
+
+
+def delete_job(client: HTTPClient, *, job_name: str) -> Any:
+    """DELETE /delete-job — permanently remove a job (and subjobs, for batches).
+
+    The endpoint may return a bare string (not JSON), so parse defensively.
+    """
+    return client.delete_json("delete-job", json={"jobName": job_name})
+
+
+def delete_file(
+    client: HTTPClient, *, file_path: str | None = None, folder: str | None = None
+) -> Any:
+    """Delete a file, or every file under a folder.
+
+    The API expects DELETE (a GET returns 405 "Use DELETE or POST"); some older
+    deployments may still want GET, so fall back on a 405.
+    """
+    params = {"filePath": file_path, "folder": folder}
+    try:
+        return client.delete_json("delete-file", params=params)
+    except APIError as exc:
+        if getattr(exc, "status_code", None) == 405:
+            return client.get_json("delete-file", params=params)
+        raise
+
+
+def get_files(
+    client: HTTPClient,
+    *,
+    limit: int | None = None,
+    offset: int | None = None,
+    types: str | None = None,
+    search: str | None = None,
+    folder: str | None = None,
+    include_folders: bool = False,
+    include_all: bool = False,
+    include_metadata: bool = False,
+) -> Any:
+    """GET /files — list files in the workspace, with filtering/pagination."""
+    params = {
+        "limit": limit,
+        "offset": offset,
+        "types": types,
+        "search": search,
+        "folder": folder,
+        "includeFolders": _TRUE if include_folders else None,
+        "includeAll": _TRUE if include_all else None,
+        "includeMetadata": _TRUE if include_metadata else None,
+    }
+    return client.get_json("files", params=params)
+
+
+def get_folders(
+    client: HTTPClient,
+    *,
+    limit: int | None = None,
+    offset: int | None = None,
+    load_all: bool = False,
+) -> Any:
+    """GET /getFolders — list folders in the workspace."""
+    params = {
+        "limit": limit,
+        "offset": offset,
+        "loadAll": _TRUE if load_all else None,
+    }
+    return client.get_json("getFolders", params=params)