tamarind-cli 0.1.0__tar.gz

tamarind_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+# Publishes tamarind-cli to PyPI on a GitHub Release (or manual dispatch).
+#
+# Uses PyPI Trusted Publishing (OIDC) — no API token in the repo. One-time setup
+# on PyPI: add a trusted publisher for project `tamarind-cli` pointing at this
+# repo + this workflow (`publish.yml`). If you prefer a token instead, delete the
+# `permissions:`/OIDC bits and set a `PYPI_API_TOKEN` secret, then pass
+# `password: ${{ secrets.PYPI_API_TOKEN }}` to the publish step.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist + wheel
+        run: uv build
+      - name: Smoke-check the build
+        run: uv run --with dist/*.whl tamarind --version
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tamarind_cli-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tamarind/

tamarind_cli-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: tamarind-cli
+Version: 0.1.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
+Project-URL: Source, https://github.com/Tamarind-Bio/tamarind-cli
+Author: Tamarind Bio
+License: MIT
+Keywords: agents,alphafold,bioinformatics,boltz,cli,protein
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Tamarind CLI
+
+Command-line interface for the [Tamarind Bio](https://tamarind.bio) platform.
+Discover tools, submit and monitor protein / nucleic-acid / small-molecule jobs,
+and download results — from your terminal, a script, CI, or an AI coding agent
+(Claude Code, Codex, …).
+
+The CLI is a thin client over the same API the [Tamarind MCP
+server](https://mcp.tamarind.bio) uses, so the two stay in lockstep. See
+[`docs/architecture.md`](docs/architecture.md) for how drift is prevented.
+
+## Install
+
+Once published to PyPI:
+
+```bash
+curl -fsSL https://install.tamarind.bio/cli/install.sh | sh
+# or:
+uv tool install tamarind-cli      # or: pipx install tamarind-cli
+```
+
+Before then (or to track the repo directly), install from git:
+
+```bash
+uv tool install "git+https://github.com/Tamarind-Bio/tamarind-cli"
+# or: pipx install "git+https://github.com/Tamarind-Bio/tamarind-cli"
+```
+
+> Releasing: tag a GitHub Release and the [`publish.yml`](.github/workflows/publish.yml)
+> workflow builds and uploads to PyPI via Trusted Publishing (configure the
+> trusted publisher for `tamarind-cli` on PyPI first).
+
+## Authenticate
+
+Get an API key from the Tamarind web app (Settings → API), then either:
+
+```bash
+export TAMARIND_API_KEY="sk_..."      # best for agents / CI
+# or
+tamarind auth login                    # stores it in ~/.tamarind/config.json
+tamarind auth status
+```
+
+## Quickstart
+
+```bash
+# 1. Find a tool
+tamarind tools --function structure-prediction --modality protein
+tamarind tools --search boltz
+
+# 2. Inspect its parameters and grab a runnable example
+tamarind schema boltz
+tamarind schema boltz --example > job.yaml
+
+# 3. Validate, then submit
+tamarind validate boltz --input job.yaml
+tamarind submit   boltz --input job.yaml --name my-run --wait --download ./out
+
+# 4. Monitor / fetch
+tamarind jobs
+tamarind status my-run
+tamarind results my-run --download ./out
+```
+
+Set individual fields inline instead of a file:
+
+```bash
+tamarind submit boltz \
+  --set inputFormat=sequence \
+  --set sequence=MKTVRQERLKSIVRIL... \
+  --name quick-fold
+```
+
+## 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.
+
+```bash
+tamarind jobs --json | jq '.jobs[] | select(.JobStatus=="Running")'
+```
+
+## Commands
+
+| Group | Commands |
+|---|---|
+| Discover | `tools`, `modalities`, `functions`, `schema` |
+| Submit | `validate`, `submit`, `batch` |
+| Monitor | `jobs`, `status`, `wait`, `results`, `logs` |
+| Files | `files list`, `files upload`, `files delete`, `files folders` |
+| Lifecycle | `cancel`, `delete` |
+| Auth | `auth login`, `auth status`, `auth logout` |
+
+Run `tamarind <command> --help` for full options.
+
+## Configuration
+
+| Setting | Flag | Env var | Default |
+|---|---|---|---|
+| API key | `--api-key` | `TAMARIND_API_KEY` | — |
+| Job API base | `--api-base` | `TAMARIND_API_BASE` | `https://app.tamarind.bio/api/` |
+| Catalog base | `--catalog-base` | `TAMARIND_CATALOG_BASE` | `https://mcp.tamarind.bio` |
+| Profile | `--profile` | `TAMARIND_PROFILE` | `default` |
+
+Profiles (key + endpoints) are stored in `~/.tamarind/config.json`. Use a
+profile to point at staging:
+
+```bash
+tamarind --profile staging --api-base https://staging.tamarind.bio/api/ auth login
+TAMARIND_PROFILE=staging tamarind tools
+```

tamarind_cli-0.1.0/README.md

@@ -0,0 +1,111 @@
+# Tamarind CLI
+
+Command-line interface for the [Tamarind Bio](https://tamarind.bio) platform.
+Discover tools, submit and monitor protein / nucleic-acid / small-molecule jobs,
+and download results — from your terminal, a script, CI, or an AI coding agent
+(Claude Code, Codex, …).
+
+The CLI is a thin client over the same API the [Tamarind MCP
+server](https://mcp.tamarind.bio) uses, so the two stay in lockstep. See
+[`docs/architecture.md`](docs/architecture.md) for how drift is prevented.
+
+## Install
+
+Once published to PyPI:
+
+```bash
+curl -fsSL https://install.tamarind.bio/cli/install.sh | sh
+# or:
+uv tool install tamarind-cli      # or: pipx install tamarind-cli
+```
+
+Before then (or to track the repo directly), install from git:
+
+```bash
+uv tool install "git+https://github.com/Tamarind-Bio/tamarind-cli"
+# or: pipx install "git+https://github.com/Tamarind-Bio/tamarind-cli"
+```
+
+> Releasing: tag a GitHub Release and the [`publish.yml`](.github/workflows/publish.yml)
+> workflow builds and uploads to PyPI via Trusted Publishing (configure the
+> trusted publisher for `tamarind-cli` on PyPI first).
+
+## Authenticate
+
+Get an API key from the Tamarind web app (Settings → API), then either:
+
+```bash
+export TAMARIND_API_KEY="sk_..."      # best for agents / CI
+# or
+tamarind auth login                    # stores it in ~/.tamarind/config.json
+tamarind auth status
+```
+
+## Quickstart
+
+```bash
+# 1. Find a tool
+tamarind tools --function structure-prediction --modality protein
+tamarind tools --search boltz
+
+# 2. Inspect its parameters and grab a runnable example
+tamarind schema boltz
+tamarind schema boltz --example > job.yaml
+
+# 3. Validate, then submit
+tamarind validate boltz --input job.yaml
+tamarind submit   boltz --input job.yaml --name my-run --wait --download ./out
+
+# 4. Monitor / fetch
+tamarind jobs
+tamarind status my-run
+tamarind results my-run --download ./out
+```
+
+Set individual fields inline instead of a file:
+
+```bash
+tamarind submit boltz \
+  --set inputFormat=sequence \
+  --set sequence=MKTVRQERLKSIVRIL... \
+  --name quick-fold
+```
+
+## 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.
+
+```bash
+tamarind jobs --json | jq '.jobs[] | select(.JobStatus=="Running")'
+```
+
+## Commands
+
+| Group | Commands |
+|---|---|
+| Discover | `tools`, `modalities`, `functions`, `schema` |
+| Submit | `validate`, `submit`, `batch` |
+| Monitor | `jobs`, `status`, `wait`, `results`, `logs` |
+| Files | `files list`, `files upload`, `files delete`, `files folders` |
+| Lifecycle | `cancel`, `delete` |
+| Auth | `auth login`, `auth status`, `auth logout` |
+
+Run `tamarind <command> --help` for full options.
+
+## Configuration
+
+| Setting | Flag | Env var | Default |
+|---|---|---|---|
+| API key | `--api-key` | `TAMARIND_API_KEY` | — |
+| Job API base | `--api-base` | `TAMARIND_API_BASE` | `https://app.tamarind.bio/api/` |
+| Catalog base | `--catalog-base` | `TAMARIND_CATALOG_BASE` | `https://mcp.tamarind.bio` |
+| Profile | `--profile` | `TAMARIND_PROFILE` | `default` |
+
+Profiles (key + endpoints) are stored in `~/.tamarind/config.json`. Use a
+profile to point at staging:
+
+```bash
+tamarind --profile staging --api-base https://staging.tamarind.bio/api/ auth login
+TAMARIND_PROFILE=staging tamarind tools
+```

tamarind_cli-0.1.0/docs/architecture.md

@@ -0,0 +1,49 @@
+# Architecture & no-drift design
+
+The CLI, the [MCP server](https://mcp.tamarind.bio), and the web app are all
+**thin clients** over the same platform. The CLI never re-implements business
+logic; it only knows how to call two well-defined surfaces. This is what keeps
+the CLI and the MCP from drifting as the platform evolves.
+
+## Two surfaces, two single sources of truth
+
+### 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.
+
+These calls go directly to the job API (`https://app.tamarind.bio/api/`) with
+the `x-api-key` header.
+
+### 2. Discovery surface — source of truth: a shared catalog module
+
+`tools`, `modalities`, `functions`, and `schema` need per-org visibility logic
+(which tools an account may see, per-parameter gating, example generation) that
+must run server-side. So the CLI does **not** read the catalog database; it
+calls the `/catalog/*` HTTP routes ([`catalog.py`](../src/tamarind/catalog.py)),
+which return exactly the JSON the MCP's discovery tools return.
+
+The MCP tools and the `/catalog/*` routes are served by the **same shared
+implementation**, so a tool looks identical no matter which client you use.
+Because the logic lives in one module, *where* discovery is hosted (the MCP host
+today; potentially the main API or a dedicated service later) is a deployment
+detail that can change without any client change and without drift.
+
+## Why not a single binary that re-encodes the API?
+
+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.
+
+## Configuration indirection
+
+Endpoints are configurable (`--api-base`, `--catalog-base`, profiles), so the
+same binary points at prod or staging, and the discovery host can move later
+without a new release.

tamarind_cli-0.1.0/install.sh

@@ -0,0 +1,38 @@
+#!/bin/sh
+# Tamarind CLI installer.
+#
+#   curl -fsSL https://install.tamarind.bio/cli/install.sh | sh
+#
+# Installs the `tamarind` command into an isolated environment using whatever
+# Python tooling is available (uv > pipx > pip --user). Override the package
+# source with TAMARIND_CLI_SPEC (e.g. a local path or a git URL).
+set -eu
+
+SPEC="${TAMARIND_CLI_SPEC:-tamarind-cli}"
+
+say()  { printf '\033[0;36m%s\033[0m\n' "$*"; }
+warn() { printf '\033[0;33m%s\033[0m\n' "$*" >&2; }
+die()  { printf '\033[0;31merror: %s\033[0m\n' "$*" >&2; exit 1; }
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+if have uv; then
+  say "Installing $SPEC with uv…"
+  uv tool install --force "$SPEC"
+elif have pipx; then
+  say "Installing $SPEC with pipx…"
+  pipx install --force "$SPEC"
+elif have python3; then
+  say "Installing $SPEC with pip (--user)…"
+  python3 -m pip install --user --upgrade "$SPEC"
+else
+  die "Need uv, pipx, or python3 on PATH. Install uv: https://docs.astral.sh/uv/"
+fi
+
+if have tamarind; then
+  say "Installed: $(tamarind --version)"
+  say "Next: export TAMARIND_API_KEY=... (or run 'tamarind auth login'), then 'tamarind tools'."
+else
+  warn "Installed, but 'tamarind' is not on PATH yet."
+  warn "Add your tool bin dir to PATH (uv: 'uv tool update-shell'; pipx: 'pipx ensurepath')."
+fi

tamarind_cli-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "tamarind-cli"
+version = "0.1.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"
+license = { text = "MIT" }
+authors = [{ name = "Tamarind Bio" }]
+keywords = ["bioinformatics", "protein", "alphafold", "boltz", "cli", "agents"]
+dependencies = [
+    "httpx>=0.27",
+    "typer>=0.12",
+    "PyYAML>=6.0",
+]
+
+[project.urls]
+Homepage = "https://tamarind.bio"
+Documentation = "https://app.tamarind.bio/api-docs"
+Source = "https://github.com/Tamarind-Bio/tamarind-cli"
+
+[project.scripts]
+tamarind = "tamarind.cli.main:run"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "respx>=0.21",
+    "ruff>=0.5",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tamarind"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

tamarind_cli-0.1.0/src/tamarind/__init__.py

@@ -0,0 +1,16 @@
+"""Tamarind Bio CLI and Python client.
+
+This package is a thin client over the Tamarind platform. Two surfaces:
+
+- REST passthrough (``tamarind.rest``): submit/validate/batch, jobs, result,
+  files, cancel, delete — these hit the Tamarind API directly with an API key.
+  The request/response contract is the same OpenAPI spec the Tamarind MCP server
+  is built from, so the CLI and the MCP cannot drift on this surface.
+
+- Discovery (``tamarind.catalog``): tools, schema, modalities, functions. The
+  catalog lives behind per-org visibility logic that runs server-side, so the
+  CLI consumes it over HTTP (the ``/catalog/*`` routes) rather than reading the
+  database directly.
+"""
+
+__version__ = "0.1.0"

tamarind_cli-0.1.0/src/tamarind/catalog.py

@@ -0,0 +1,70 @@
+"""Discovery / catalog client.
+
+The tool catalog and per-tool schemas are gated by per-org visibility logic
+that runs server-side, so the CLI consumes them over HTTP from the catalog
+service (the ``/catalog/*`` routes) rather than reading the database directly.
+
+These routes return exactly the JSON the MCP's discovery tools return
+(``getAvailableTools``, ``listModalities``, ``listTags``, ``getJobSchema``),
+because both are served by the same shared implementation. So whatever a tool
+looks like in the MCP, it looks identical here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .http import HTTPClient
+
+CATALOG_PREFIX = "catalog"
+
+
+def list_tools(
+    client: HTTPClient,
+    *,
+    modality: str | None = None,
+    function: str | None = None,
+    search: str | None = None,
+    custom: bool | None = None,
+) -> dict:
+    """GET /catalog/tools — the filtered tool catalog (mirrors getAvailableTools)."""
+    params = {
+        "modality": modality,
+        "function": function,
+        "search": search,
+        "custom": "true" if custom else None,
+    }
+    return client.get_json(f"{CATALOG_PREFIX}/tools", params=params)
+
+
+def list_modalities(client: HTTPClient) -> dict:
+    """GET /catalog/modalities — molecule types you can filter by."""
+    return client.get_json(f"{CATALOG_PREFIX}/modalities")
+
+
+def list_functions(client: HTTPClient) -> dict:
+    """GET /catalog/functions — functions (tags) you can filter by."""
+    return client.get_json(f"{CATALOG_PREFIX}/functions")
+
+
+def get_schema(client: HTTPClient, job_type: str) -> dict:
+    """GET /catalog/tools/{jobType}/schema — full parameter schema + example job."""
+    return client.get_json(f"{CATALOG_PREFIX}/tools/{job_type}/schema")
+
+
+# -- helpers for rendering / example extraction ---------------------------
+
+
+def example_settings(schema: dict[str, Any]) -> dict[str, Any]:
+    """Pull a runnable ``settings`` dict out of a schema's exampleJob, if present."""
+    example = schema.get("exampleJob") or {}
+    return dict(example.get("settings") or {})
+
+
+def required_param_names(schema: dict[str, Any]) -> list[str]:
+    """Names of parameters marked required (top-level; ignores task-gated ones)."""
+    out = []
+    for p in schema.get("parameters", []):
+        if p.get("required") and p.get("name"):
+            out.append(p["name"])
+    return out

tamarind_cli-0.1.0/src/tamarind/cli/__init__.py

@@ -0,0 +1 @@
+"""Typer command-line interface for Tamarind."""

tamarind_cli-0.1.0/src/tamarind/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command groups."""

tamarind_cli-0.1.0/src/tamarind/cli/commands/auth.py

@@ -0,0 +1,90 @@
+"""`tamarind auth` — credential management."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+
+from ... import rest
+from ...config import mask_key, save_profile
+from ...errors import AuthError
+from ...http import HTTPClient
+from .. import output
+
+app = typer.Typer(no_args_is_help=True)
+
+
+def _check_key(api_base: str, api_key: str) -> bool:
+    """Return True if the key authenticates against the job API."""
+    with HTTPClient(api_base, api_key) as client:
+        try:
+            rest.get_jobs(client, limit=1)
+            return True
+        except AuthError:
+            return False
+
+
+@app.command()
+def login(
+    ctx: typer.Context,
+    api_key: Optional[str] = typer.Option(
+        None, "--api-key", help="API key. If omitted, you'll be prompted.", show_default=False
+    ),
+    no_verify: bool = typer.Option(False, "--no-verify", help="Skip verifying the key."),
+) -> None:
+    """Store an API key in the current profile (~/.tamarind/config.json).
+
+    Get a key from https://app.tamarind.bio (Settings → API), or set
+    TAMARIND_API_KEY in the environment to skip storing one.
+    """
+    state = ctx.obj
+    cfg = state.config()
+    key = api_key or typer.prompt("Tamarind API key", hide_input=True)
+    key = key.strip()
+
+    if not no_verify and not _check_key(cfg.api_base, key):
+        raise AuthError("That API key was rejected by the API. Not saved.")
+
+    save_profile(cfg.profile, api_key=key)
+    output.emit(
+        {"ok": True, "profile": cfg.profile, "verified": not no_verify},
+        state.output,
+        human=f"Saved API key to profile '{cfg.profile}'.",
+    )
+
+
+@app.command()
+def status(ctx: typer.Context) -> None:
+    """Show the active profile, endpoints, and whether the 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}"
+    )
+    output.emit(result, state.output, human=human)
+
+
+@app.command()
+def logout(ctx: typer.Context) -> None:
+    """Remove the stored API key from the current profile."""
+    state = ctx.obj
+    cfg = state.config()
+    save_profile(cfg.profile, api_key="", make_current=False)
+    output.emit(
+        {"ok": True, "profile": cfg.profile},
+        state.output,
+        human=f"Cleared API key for profile '{cfg.profile}'.",
+    )