tamarind-cli 0.1.4__tar.gz → 0.2.0__tar.gz

tamarind_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  package:
+    name: Build release artifacts
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build source and wheel distributions
+        run: uv build
+      - name: Reject local caches in the source distribution
+        run: >-
+          python -c "import glob, tarfile;
+          names = tarfile.open(glob.glob('dist/*.tar.gz')[0]).getnames();
+          assert not any('/.uv-cache/' in name or '/.venv/' in name for name in names)"
+      - name: Smoke-check the built wheel
+        run: uv run --isolated --no-project --with dist/*.whl tamarind --version
+
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}
+      - name: Install project and development dependencies
+        run: uv sync --extra dev
+      - name: Test
+        run: uv run pytest
+      - name: Lint
+        run: uv run ruff check .
+
+  cross-platform:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - name: Install project and development dependencies
+        run: uv sync --extra dev
+      - name: Test
+        run: uv run pytest

{tamarind_cli-0.1.4 → tamarind_cli-0.2.0}/.github/workflows/publish.yml

@@ -22,7 +22,7 @@ jobs:
       - name: Build sdist + wheel
         run: uv build
       - name: Smoke-check the build
-        run: uv run --with dist/*.whl tamarind --version
+        run: uv run --isolated --no-project --with dist/*.whl tamarind --version
       - uses: actions/upload-artifact@v4
         with:
           name: dist

{tamarind_cli-0.1.4 → tamarind_cli-0.2.0}/.gitignore

@@ -6,6 +6,7 @@ build/
 dist/
 .pytest_cache/
 .ruff_cache/
+.uv-cache/
 .coverage
 htmlcov/
 .tamarind/

{tamarind_cli-0.1.4 → tamarind_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tamarind-cli
-Version: 0.1.4
+Version: 0.2.0
 Summary: Command-line interface for the Tamarind Bio platform — submit, monitor, and download protein/molecule jobs from your terminal or an AI agent.
 Project-URL: Homepage, https://tamarind.bio
 Project-URL: Documentation, https://app.tamarind.bio/api-docs
@@ -39,7 +39,8 @@ server](https://mcp.tamarind.bio) uses, so the two stay in lockstep. See
 uv tool install tamarind-cli      # or: pipx install tamarind-cli
 ```
 
-Or with the bootstrap installer (installs `uv` if needed):
+Or with the bootstrap installer (uses `uv`, `pipx`, or Python/pip already on
+your `PATH`):
 
 ```bash
 curl -fsSL https://app.tamarind.bio/cli/install.sh | sh
@@ -80,7 +81,8 @@ tamarind schema boltz --example > job.yaml   # most tools ship an example; some
 
 # 3. Validate, then submit
 tamarind validate boltz --input job.yaml
-tamarind submit   boltz --input job.yaml --name my-run --wait --download ./out
+tamarind submit boltz --input job.yaml --name my-run \
+  --wait --timeout 3600 --download ./out
 
 # 4. Monitor / fetch
 tamarind jobs
@@ -99,9 +101,26 @@ tamarind submit boltz \
 
 ## Output for agents
 
-Every command emits JSON when stdout is not a TTY, or with `--json`. Exit codes
-are stable: `0` ok, `3` auth, `4` not-found, `5` validation, `6` rate-limit,
-`7` timeout (a `--wait`/`--timeout` deadline elapsed).
+Every command emits JSON when stdout is not a TTY, or with `--json`. Result
+documents are written to stdout. Typed command, transport, and usage errors are
+written to stderr as
+`{"error":{"type":...,"message":...,"exitCode":...,"detail":...}}`; `detail`
+is omitted when unavailable. A domain verdict can deliberately combine a
+nonzero exit with a result document: invalid `validate` output remains on
+stdout with exit 5, and a terminal unsuccessful job remains on stdout with exit
+9 so callers can inspect its status. Exit codes are stable: `0` ok, `1`
+generic failure, `2` usage, `3` auth, `4` not-found, `5` validation, `6`
+rate-limit, `7` timeout (a bounded wait elapsed while the remote job may still
+run), `8` budget/quota exhaustion, and `9` remote job failure.
+
+For agent workflows, always put a deadline on blocking commands. `submit --wait`
+and `results --wait` accept `--timeout`; the standalone `wait` command remains
+the easiest way to reattach to a durable job name.
+
+Starting in 0.2, `results` requires `--download DIR` by default and never prints
+a presigned URL implicitly. This intentional safety boundary is why the release
+uses a new pre-1.0 minor version. The explicit `--show-url` escape hatch returns
+a credential-bearing, short-lived URL; do not use it in agent, CI, or shared logs.
 
 Not every tool ships a runnable example — `schema <tool> --example` exits non-zero
 (with a clear message) when one isn't available, so a `> job.yaml` redirect never
@@ -110,9 +129,12 @@ require `--yes`/`-y` when run non-interactively (piped or `--json`), so an agent
 never removes data without an explicit confirmation.
 
 ```bash
-tamarind jobs --json | jq '.jobs[] | select(.JobStatus=="Running")'
+tamarind --json jobs | jq '.jobs[] | select(.JobStatus=="Running")'
 ```
 
+`--json`, `--profile`, and the endpoint/auth overrides are global options, so
+place them before the command name.
+
 ## Commands
 
 | Group | Commands |

{tamarind_cli-0.1.4 → tamarind_cli-0.2.0}/README.md

@@ -18,7 +18,8 @@ server](https://mcp.tamarind.bio) uses, so the two stay in lockstep. See
 uv tool install tamarind-cli      # or: pipx install tamarind-cli
 ```
 
-Or with the bootstrap installer (installs `uv` if needed):
+Or with the bootstrap installer (uses `uv`, `pipx`, or Python/pip already on
+your `PATH`):
 
 ```bash
 curl -fsSL https://app.tamarind.bio/cli/install.sh | sh
@@ -59,7 +60,8 @@ tamarind schema boltz --example > job.yaml   # most tools ship an example; some
 
 # 3. Validate, then submit
 tamarind validate boltz --input job.yaml
-tamarind submit   boltz --input job.yaml --name my-run --wait --download ./out
+tamarind submit boltz --input job.yaml --name my-run \
+  --wait --timeout 3600 --download ./out
 
 # 4. Monitor / fetch
 tamarind jobs
@@ -78,9 +80,26 @@ tamarind submit boltz \
 
 ## Output for agents
 
-Every command emits JSON when stdout is not a TTY, or with `--json`. Exit codes
-are stable: `0` ok, `3` auth, `4` not-found, `5` validation, `6` rate-limit,
-`7` timeout (a `--wait`/`--timeout` deadline elapsed).
+Every command emits JSON when stdout is not a TTY, or with `--json`. Result
+documents are written to stdout. Typed command, transport, and usage errors are
+written to stderr as
+`{"error":{"type":...,"message":...,"exitCode":...,"detail":...}}`; `detail`
+is omitted when unavailable. A domain verdict can deliberately combine a
+nonzero exit with a result document: invalid `validate` output remains on
+stdout with exit 5, and a terminal unsuccessful job remains on stdout with exit
+9 so callers can inspect its status. Exit codes are stable: `0` ok, `1`
+generic failure, `2` usage, `3` auth, `4` not-found, `5` validation, `6`
+rate-limit, `7` timeout (a bounded wait elapsed while the remote job may still
+run), `8` budget/quota exhaustion, and `9` remote job failure.
+
+For agent workflows, always put a deadline on blocking commands. `submit --wait`
+and `results --wait` accept `--timeout`; the standalone `wait` command remains
+the easiest way to reattach to a durable job name.
+
+Starting in 0.2, `results` requires `--download DIR` by default and never prints
+a presigned URL implicitly. This intentional safety boundary is why the release
+uses a new pre-1.0 minor version. The explicit `--show-url` escape hatch returns
+a credential-bearing, short-lived URL; do not use it in agent, CI, or shared logs.
 
 Not every tool ships a runnable example — `schema <tool> --example` exits non-zero
 (with a clear message) when one isn't available, so a `> job.yaml` redirect never
@@ -89,9 +108,12 @@ require `--yes`/`-y` when run non-interactively (piped or `--json`), so an agent
 never removes data without an explicit confirmation.
 
 ```bash
-tamarind jobs --json | jq '.jobs[] | select(.JobStatus=="Running")'
+tamarind --json jobs | jq '.jobs[] | select(.JobStatus=="Running")'
 ```
 
+`--json`, `--profile`, and the endpoint/auth overrides are global options, so
+place them before the command name.
+
 ## Commands
 
 | Group | Commands |

{tamarind_cli-0.1.4 → tamarind_cli-0.2.0}/docs/architecture.md

@@ -10,11 +10,15 @@ the CLI and the MCP from drifting as the platform evolves.
 ### 1. Job/file REST surface — source of truth: the OpenAPI spec
 
 `submit`, `validate`, `batch`, `jobs`, `status`/`wait`, `results`, `files`,
-`cancel`, `delete` map 1:1 onto operations in `openapi-mcp.yaml` — the same
-spec the MCP server is generated from (`FastMCP.from_openapi`). The CLI's
-[`rest.py`](../src/tamarind/rest.py) is a literal, logic-free mapping of that
-spec. Because both clients derive from one spec, a contract test can fail CI if
-they diverge.
+`cancel`, and `delete` map onto operations in `openapi-mcp.yaml` — the same
+server contract used to generate the MCP surface. The CLI's
+[`rest.py`](../src/tamarind/rest.py) is intentionally a small mapping of those
+operations.
+
+The CLI mapping is still client code and can drift. Unit tests cover request and
+response shapes, and authenticated no-spend smoke tests should exercise auth,
+catalog lookup, schema lookup, and validation before a release. Changes to the
+server contract should update the CLI tests in the same change or release train.
 
 These calls go directly to the job API (`https://app.tamarind.bio/api/`) with
 the `x-api-key` header.
@@ -37,10 +41,9 @@ detail that can change without any client change and without drift.
 
 A from-scratch client in another language would re-encode the request shapes and
 the catalog logic — two copies that drift the moment the platform changes.
-Keeping the CLI a thin, spec-derived Python client that shares the OpenAPI
-contract (and, server-side, the catalog module) with the MCP makes drift a
-structural impossibility plus a CI-enforced check, rather than something to
-remember.
+Keeping the CLI thin and anchored to the same OpenAPI contract (and,
+server-side, the same catalog module) reduces drift and makes it testable. It
+does not eliminate the need for compatibility tests and coordinated releases.
 
 ## Configuration indirection
 

{tamarind_cli-0.1.4 → tamarind_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tamarind-cli"
-version = "0.1.4"
+version = "0.2.0"
 description = "Command-line interface for the Tamarind Bio platform — submit, monitor, and download protein/molecule jobs from your terminal or an AI agent."
 readme = "README.md"
 requires-python = ">=3.10"

{tamarind_cli-0.1.4 → tamarind_cli-0.2.0}/src/tamarind/cli/commands/auth.py

@@ -7,7 +7,7 @@ from typing import Optional
 import typer
 
 from ... import rest
-from ...config import mask_key, save_profile
+from ...config import save_profile
 from ...errors import AuthError
 from ...http import HTTPClient
 from .. import output
@@ -56,23 +56,19 @@ def login(
 
 @app.command()
 def status(ctx: typer.Context) -> None:
-    """Show the active profile, endpoints, and whether the key works."""
+    """Show the active profile and whether its key works."""
     state = ctx.obj
     cfg = state.config()
     verified = cfg.has_key and _check_key(cfg.api_base, cfg.api_key)
     result = {
         "profile": cfg.profile,
-        "apiKey": mask_key(cfg.api_key),
         "hasKey": cfg.has_key,
         "verified": verified,
-        "apiBase": cfg.api_base,
-        "catalogBase": cfg.catalog_base,
     }
     human = (
         f"profile:      {cfg.profile}\n"
-        f"api key:      {mask_key(cfg.api_key)} ({'verified' if verified else 'not verified'})\n"
-        f"job api:      {cfg.api_base}\n"
-        f"catalog api:  {cfg.catalog_base}"
+        f"api key:      {'configured' if cfg.has_key else 'not configured'} "
+        f"({'verified' if verified else 'not verified'})"
     )
     output.emit(result, state.output, human=human)
 

{tamarind_cli-0.1.4 → tamarind_cli-0.2.0}/src/tamarind/cli/commands/catalog.py

@@ -8,6 +8,40 @@ import typer
 
 from ... import catalog
 from .. import output
+from ..guidance import rewrite_legacy_guidance
+
+
+def _with_cli_tools_hint(response: object) -> object:
+    """Preserve catalog guidance and add instructions valid in this CLI."""
+    if not isinstance(response, dict):
+        return response
+    result = dict(response)
+    if "hint" in result:
+        result["hint"] = rewrite_legacy_guidance(result["hint"])
+    result["cliHint"] = (
+        "Inspect a tool with `tamarind --json schema NAME`. Pass the exact lowercase "
+        "tool name, and narrow discovery with `--modality` or `--function`."
+    )
+    return result
+
+
+def _with_cli_schema_hints(response: object, tool: str) -> object:
+    """Keep live schema data while preventing MCP-only instructions from leaking in."""
+    if not isinstance(response, dict) or response.get("error"):
+        return response
+    result = dict(response)
+    if "hint" in result:
+        result["hint"] = rewrite_legacy_guidance(result["hint"])
+    result["cliHint"] = (
+        f"Validate settings with `tamarind --json validate {tool} --input FILE`. "
+        "Upload local file inputs with `tamarind --json files upload PATH`; download "
+        "completed outputs with `tamarind --json results JOB --download DIR`."
+    )
+    if "exampleJobNote" in result:
+        result["exampleJobNote"] = rewrite_legacy_guidance(
+            result["exampleJobNote"]
+        )
+    return result
 
 
 def register(app: typer.Typer) -> None:
@@ -25,6 +59,7 @@ def register(app: typer.Typer) -> None:
             resp = catalog.list_tools(
                 client, modality=modality, function=function, search=search, custom=custom or None
             )
+        resp = _with_cli_tools_hint(resp)
         rows = [
             {
                 "name": t.get("name"),
@@ -74,6 +109,7 @@ def register(app: typer.Typer) -> None:
         state = ctx.obj
         with state.catalog_client() as client:
             resp = catalog.get_schema(client, tool)
+        resp = _with_cli_schema_hints(resp, tool)
         # The catalog returns HTTP 200 with {"error": ...} for an unknown/hidden
         # tool; turn that into a not-found exit instead of printing it as success.
         if isinstance(resp, dict) and resp.get("error"):

{tamarind_cli-0.1.4 → tamarind_cli-0.2.0}/src/tamarind/cli/commands/files.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+from collections.abc import Iterator
 from pathlib import Path
+from typing import BinaryIO
 from typing import Optional
 
 import httpx
@@ -14,6 +16,54 @@ from .. import output
 
 app = typer.Typer(no_args_is_help=True)
 
+_UPLOAD_CHUNK_SIZE = 1024 * 1024
+_UPLOAD_TIMEOUT = 300.0
+
+
+def _iter_file_chunks(fh: BinaryIO) -> Iterator[bytes]:
+    """Read an upload incrementally instead of buffering the whole file."""
+    while chunk := fh.read(_UPLOAD_CHUNK_SIZE):
+        yield chunk
+
+
+def _put_presigned_upload(url: str, path: Path, *, content_type: str, remote: str) -> int:
+    """Stream ``path`` to a presigned URL and translate transport failures.
+
+    Presigned URLs contain temporary credentials, so error messages deliberately
+    omit the URL rather than echoing ``httpx``'s exception text.
+    """
+    try:
+        size = path.stat().st_size
+        headers = {
+            "Content-Type": content_type,
+            # Supplying the size avoids chunked transfer encoding, which is not
+            # accepted by every S3-compatible presigned PUT endpoint.
+            "Content-Length": str(size),
+        }
+        with path.open("rb") as fh:
+            put = httpx.put(
+                url,
+                content=_iter_file_chunks(fh),
+                headers=headers,
+                timeout=_UPLOAD_TIMEOUT,
+            )
+        put.raise_for_status()
+    except httpx.TimeoutException as exc:
+        raise TamarindError(
+            f"Upload of '{remote}' timed out after {_UPLOAD_TIMEOUT:g} seconds."
+        ) from exc
+    except httpx.HTTPStatusError as exc:
+        raise TamarindError(
+            f"Upload of '{remote}' failed with HTTP {exc.response.status_code}."
+        ) from exc
+    except (httpx.RequestError, httpx.InvalidURL, httpx.StreamError) as exc:
+        raise TamarindError(
+            f"Upload transfer failed for '{remote}' ({type(exc).__name__})."
+        ) from exc
+    except OSError as exc:
+        raise TamarindError(f"Could not read '{path}' during upload: {exc}.") from exc
+    return size
+
 
 def _file_name(f: object) -> str:
     """A file entry is usually a bare name string, but be tolerant of dicts."""
@@ -162,16 +212,19 @@ def upload(
     # The endpoint returns {uploadUrl, headUrl, key, bucket}; PUT the bytes to
     # uploadUrl. Don't crash on a non-dict error body — surface a clean error.
     url = signed.get("uploadUrl") if isinstance(signed, dict) else None
-    if not url:
-        raise TamarindError("Upload did not return a presigned URL.", detail=signed)
+    if not isinstance(url, str) or not url:
+        # Never echo the response values here: sibling fields such as headUrl
+        # can also be credential-bearing presigned URLs.
+        detail = {"responseType": type(signed).__name__}
+        if isinstance(signed, dict):
+            detail["fields"] = sorted(str(key) for key in signed)
+        raise TamarindError("Upload did not return a presigned URL.", detail=detail)
     output.info(f"Uploading {path} → {remote}…", state.output)
     # Content-Type must match what the presigned URL was signed with, or S3
     # rejects the PUT with SignatureDoesNotMatch.
-    with path.open("rb") as fh:
-        put = httpx.put(url, content=fh.read(), headers={"Content-Type": content_type}, timeout=300.0)
-    put.raise_for_status()
+    size = _put_presigned_upload(url, path, content_type=content_type, remote=remote)
     output.emit(
-        {"ok": True, "filename": remote, "bytes": path.stat().st_size},
+        {"ok": True, "filename": remote, "bytes": size},
         state.output,
         human=f"uploaded {remote}",
     )