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

{tamarind_cli-0.2.0 → tamarind_cli-0.3.1}/.github/workflows/ci.yml

@@ -9,6 +9,47 @@ permissions:
   contents: read
 
 jobs:
+  generated:
+    name: Generated transport is current
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Verify backend provenance and generated client freshness
+        run: |
+          uv run --extra dev python scripts/check_custom_tools_provenance.py
+          tmp_dir=$(mktemp -d .custom-tools-generated.XXXXXX)
+          trap 'rm -rf "$tmp_dir"' EXIT
+          uv run --extra dev openapi-python-client generate --path openapi/public-v1.json \
+            --config openapi/openapi-python-client.json --meta none \
+            --output-path "$tmp_dir/generated" --overwrite
+          diff -ru --exclude=.ruff_cache src/tamarind/custom_tools/_generated "$tmp_dir/generated"
+          uv run --extra dev openapi-python-client generate --path openapi/pipelines-v1.json \
+            --config openapi/pipelines-openapi-python-client.json --meta none \
+            --output-path "$tmp_dir/pipelines-generated" --overwrite
+          diff -ru --exclude=.ruff_cache src/tamarind/pipelines/_generated "$tmp_dir/pipelines-generated"
+
+  typecheck:
+    name: SDK type check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.12"
+      - name: Check the public SDK and transport boundary
+        run: >-
+          uv run --extra dev mypy
+          src/tamarind/custom_tools
+          src/tamarind/pipelines
+          src/tamarind/http.py
+          src/tamarind/errors.py
+          scripts/sync_custom_tools_contract.py
+          scripts/sync_pipelines_contract.py
+
   package:
     name: Build release artifacts
     runs-on: ubuntu-latest

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: tamarind-cli
-Version: 0.2.0
+Version: 0.3.1
 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
@@ -10,10 +10,14 @@ License: Apache-2.0
 License-File: LICENSE
 Keywords: agents,alphafold,bioinformatics,boltz,cli,protein
 Requires-Python: >=3.10
+Requires-Dist: attrs>=23.1
 Requires-Dist: httpx>=0.27
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: typer>=0.12
+Requires-Dist: typing-extensions>=4.7
 Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: openapi-python-client==0.28.4; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: respx>=0.21; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
@@ -99,6 +103,53 @@ tamarind submit boltz \
   --name quick-fold
 ```
 
+## Python SDK
+
+The package exposes typed Pipelines and Custom Tools resources. Pipeline runs use
+the same node-run terminology as the web app and public REST API:
+
+```python
+from tamarind import Tamarind
+
+with Tamarind() as client:
+    run = client.pipelines.get_run("run-id")
+    for node_run in run.node_runs:
+        page = node_run.molecules(limit=100)
+        print(node_run.label, page.items)
+```
+
+The Custom Tools resource checks archive-local
+safety, packages a folder, uploads it directly to object storage, and submits the
+digest-checked build request. The server
+remains authoritative for source readiness, Versions, logs, and the evolving
+`config.json` contract.
+
+```python
+from tamarind import Tamarind
+from tamarind.errors import CustomToolNotFoundError
+
+with Tamarind() as client:
+    try:
+        tool = client.custom_tools.get("my-esmfold")
+    except CustomToolNotFoundError:
+        tool = client.custom_tools.create("my-esmfold", display_name="My ESMFold")
+
+    result = tool.build("./my-esmfold")
+    print(result.action)  # build, reuse_image, or unchanged
+    version = result.version
+    if not version.terminal:
+        version = version.monitor(timeout=1800, on_event=print)
+```
+
+`build()` returns a typed result describing what the request did and the durable
+Version it produced. It is convenience orchestration, not a durable request
+object. If the connection is lost during the build response, fetch the tool's
+versions before retrying. Interrupting `monitor()` stops local monitoring; it
+does not cancel the remote build.
+
+Custom Tool CLI commands are not part of this release. Existing CLI commands
+remain unchanged.
+
 ## Output for agents
 
 Every command emits JSON when stdout is not a TTY, or with `--json`. Result

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

@@ -78,6 +78,53 @@ tamarind submit boltz \
   --name quick-fold
 ```
 
+## Python SDK
+
+The package exposes typed Pipelines and Custom Tools resources. Pipeline runs use
+the same node-run terminology as the web app and public REST API:
+
+```python
+from tamarind import Tamarind
+
+with Tamarind() as client:
+    run = client.pipelines.get_run("run-id")
+    for node_run in run.node_runs:
+        page = node_run.molecules(limit=100)
+        print(node_run.label, page.items)
+```
+
+The Custom Tools resource checks archive-local
+safety, packages a folder, uploads it directly to object storage, and submits the
+digest-checked build request. The server
+remains authoritative for source readiness, Versions, logs, and the evolving
+`config.json` contract.
+
+```python
+from tamarind import Tamarind
+from tamarind.errors import CustomToolNotFoundError
+
+with Tamarind() as client:
+    try:
+        tool = client.custom_tools.get("my-esmfold")
+    except CustomToolNotFoundError:
+        tool = client.custom_tools.create("my-esmfold", display_name="My ESMFold")
+
+    result = tool.build("./my-esmfold")
+    print(result.action)  # build, reuse_image, or unchanged
+    version = result.version
+    if not version.terminal:
+        version = version.monitor(timeout=1800, on_event=print)
+```
+
+`build()` returns a typed result describing what the request did and the durable
+Version it produced. It is convenience orchestration, not a durable request
+object. If the connection is lost during the build response, fetch the tool's
+versions before retrying. Interrupting `monitor()` stops local monitoring; it
+does not cancel the remote build.
+
+Custom Tool CLI commands are not part of this release. Existing CLI commands
+remain unchanged.
+
 ## Output for agents
 
 Every command emits JSON when stdout is not a TTY, or with `--json`. Result

tamarind_cli-0.3.1/docs/architecture.md

@@ -0,0 +1,102 @@
+# 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 four well-defined surfaces. This is what keeps
+the CLI and the MCP from drifting as the platform evolves.
+
+## Four surfaces, four single sources of truth
+
+### 1. Job/file REST surface — source of truth: the OpenAPI spec
+
+`submit`, `validate`, `batch`, `jobs`, `status`/`wait`, `results`, `files`,
+`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.
+
+### 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.
+
+### 3. Custom Tools surface — source of truth: the public OpenAPI artifact
+
+Custom Tool creation, source upload, build, Versions, logs, and cancellation
+are generated from the website backend's dedicated public OpenAPI artifact:
+
+```text
+backend-owned custom-tools-v1.generated.json
+  -> Git-object provenance verification
+  -> vendored spec + lock
+  -> openapi-python-client==0.28.4
+  -> generated models/endpoints
+  -> thin Tamarind transport and resource adapters
+```
+
+The Website owns the projection and its referenced-component closure. The CLI sync
+verifies the exact producer repository, commit, path, and bytes before atomically
+installing the spec, provenance lock, generated server metadata, and generated package.
+CI regenerates with the pinned mature generator and rejects drift. The handwritten
+layer contains only HTTP/error normalization and ergonomic resource composition; it
+does not parse OpenAPI or maintain a second schema IR/compiler.
+
+The SDK owns archive-local concerns that only the client can decide safely:
+deterministic ZIP construction, symlink and junction rejection, upload limits,
+JSON parseability and top-level object shape, and warnings about the networkless
+runtime. Archives use stored ZIP entries so source digests do not depend on a
+platform zlib build. Modes are also platform-stable: `run.sh` and files beginning
+with a shebang are executable, while all other files are regular. The backend owns
+the evolving `config.json` business contract and
+validates it before accepting a build. The SDK deliberately does not maintain a
+second list of configuration fields, enums, or cross-field rules.
+
+`CustomTool.build()` composes the existing requests: create upload, PUT the archive,
+submit the digest-checked build request, and return a typed result containing the server's
+action plus its durable Version. It adds no server-side
+BuildRequest, queue, lease, claim, or repair state. An ambiguous build response
+is therefore handled honestly by listing Versions before a manual retry.
+
+### 4. Pipelines read surface — source of truth: the public OpenAPI artifact
+
+`Tamarind().pipelines` reads a run and pages through the molecules produced by one
+of its node runs. The sync script selects only those operations and their referenced
+schemas from the website backend's frozen public OpenAPI artifact, verifies the exact
+producer Git object, and records that commit in a dedicated lock. Keeping this
+projection separate prevents Pipelines changes from broadening or perturbing the
+Custom Tools contract.
+
+Generated endpoint code owns URL encoding and wire-model parsing. A small resource
+adapter adds strict runtime checks and composes `PipelineRun` → `NodeRun` → molecule
+pages without introducing another public vocabulary.
+
+## 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 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
+
+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.3.1/openapi/openapi-python-client.json

@@ -0,0 +1,4 @@
+{
+  "package_name_override": "_generated",
+  "project_name_override": "tamarind-custom-tools-generated"
+}

tamarind_cli-0.3.1/openapi/pipelines-openapi-python-client.json

@@ -0,0 +1,4 @@
+{
+  "package_name_override": "_generated",
+  "project_name_override": "tamarind-pipelines-generated"
+}