proteworks 0.1.4__tar.gz → 0.1.9__tar.gz

{proteworks-0.1.4 → proteworks-0.1.9}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: proteworks
-Version: 0.1.4
+Version: 0.1.9
 Summary: Sync files with Proteworks using file-browser paths.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
-Requires-Dist: httpx>=0.27
+Requires-Dist: httpx[socks]>=0.27
 Requires-Dist: keyring>=25
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
@@ -16,37 +16,94 @@ Requires-Dist: pyarrow>=14; extra == "mcp"
 
 Command line client and local MCP server for syncing Proteworks files and submitting allowlisted workflows. The default API is production. Set `PROTEWORKS_API_URL` only when testing against staging or a local stack.
 
+## One install (CLI + Claude Science)
+
+There is a **single supported install**:
+
+| Path | Role |
+| --- | --- |
+| `/opt/proteworks` | Package + `proteworks-mcp` |
+| `/usr/local/bin/proteworks` | CLI symlink |
+| `/usr/local/bin/proteworks-mcp` | MCP symlink (Science **Command**) |
+| `~/.config/proteworks/` | Login token file + org config |
+
+Do **not** keep a second copy from `uv tool` / pipx / a repo `.venv` on your PATH for daily use. Those diverge and break Claude Science.
+
+### Bootstrap once, then use only `/usr/local/bin`
+
 ```bash
-uv tool install proteworks
+# 1) Temporary bootstrap (any machine with uv)
+uv tool install 'proteworks[mcp]'
+
+# 2) Canonical install (needs sudo). Uses distro python3.12+ under /usr (not uv under $HOME).
+sudo "$(which proteworks)" mcp install-system
+# Developers working from a git checkout before publishing:
+# sudo "$(which proteworks)" mcp install-system --package-spec "$PWD[mcp]"
+
+# 3) Remove the bootstrap copy so PATH has one binary
+uv tool uninstall proteworks
+hash -r
+which -a proteworks   # expect only /usr/local/bin/proteworks
+
+# 4) Login + Science grants
 proteworks login
-proteworks organization list
 proteworks organization set "My Org"
-proteworks pull '~/My Files/campaigns/run/' ./run
-proteworks push ./1UBQ.pdb '~/My Files/test/'
-proteworks push ./run '~/My Files/campaigns/run/'
+proteworks mcp setup-claude-science
+proteworks mcp doctor
 ```
 
-Quote wildcards so the shell does not expand them. A trailing slash on a remote path means a folder. `proteworks --help` lists every command.
+After any upgrade: run step 2 again (same `install-system` command), then `doctor`. Do not `uv tool install` again unless `/usr/local/bin/proteworks` is missing.
 
-Login returns to `http://127.0.0.1:8765/callback`. Add that exact URL to the Auth0 application's Allowed Callback URLs. The same URL is used in development and production.
+### Claude Science connector
 
-## MCP (Claude Science and other clients)
+`setup-claude-science` prints the fields. Always:
 
-The same login and organization selection power a local MCP server. Install the MCP extra, sign in once with the CLI, then point your client at `proteworks-mcp`.
+| Field | Value |
+| --- | --- |
+| **Name** | `proteworks` |
+| **Command** | `/opt/proteworks/bin/proteworks-mcp` |
+| **Arguments** | leave empty |
+| **Env** (if shown) | `PROTEWORKS_CONFIG_DIR=$HOME/.config/proteworks` |
+
+Paste **only** that Command path. Do not use `python -m …`, `uvx`, or a path under `~/.local`. Science’s one-field UI can drop `-m` and hang for 180s; sandboxed `HOME` also cannot see a second user-level install’s credentials unless you use the system layout above.
+
+Fully quit and relaunch Claude Science after setup so it reloads `config.toml`.
+Also add each host **by name** under Science **Settings → Domain Allowlist**
+(Science rejects wildcards). `setup-claude-science` prints the list — typically
+`api.studio.proteworks.com` plus virtual-hosted GCS hosts such as
+`proteworks-production.storage.googleapis.com`. The connector’s `config.toml`
+grants are necessary but Science’s UI allowlist often gates egress separately.
+Bare `storage.googleapis.com` is hard-denylisted (path-style GCS). If pull still
+fails for a custom org bucket, add `<bucket>.storage.googleapis.com`. Science may
+set `ALL_PROXY` (SOCKS); `proteworks` depends on `httpx[socks]` so that works out
+of the box. If a direct GCS PUT is still blocked, push falls back to uploading
+through the Proteworks API host.
+
+Allow Claude to push/pull from a real project (like the CLI — no staging copy):
 
 ```bash
-uv tool install 'proteworks[mcp]'
-# or: pip install 'proteworks[mcp]'
-proteworks login
-proteworks organization set "My Org"
+proteworks mcp setup-claude-science --mcp-root ~/projects/my-campaign
+```
+
+That grants the Science sandbox **and** writes `~/.config/proteworks/mcp_roots`.
+Restart the connector afterward. Absolute paths under that project then work with
+MCP `push` / `pull`.
+
+`proteworks --version` / `proteworks-mcp --version` print the installed version.
+
+Quote wildcards so the shell does not expand them. A trailing slash on a remote path means a folder. `proteworks --help` lists every command.
+
+```bash
+proteworks pull '~/My Files/campaigns/run/' ./run
+proteworks push ./1UBQ.pdb '~/My Files/test/'
+proteworks push '*.pdb' '~/My Files/pdbs/'
+proteworks push designs.zip '~/My Files/dest/'   # auto-extracts
+proteworks mkdir '~/My Files/campaigns/round6/'
 ```
 
-### Claude Science
+MCP also exposes `create_folder` for the same empty-directory create (returns `folder_id` for `output_folder_id` / push).
 
-1. Settings → Connectors → Add connector → **Local command**
-2. Command: `proteworks-mcp`  
-   (or `uvx --from 'proteworks[mcp]' proteworks-mcp`)
-3. Approve tools as needed
+Login returns to `http://127.0.0.1:8765/callback`. Add that exact URL to the Auth0 application's Allowed Callback URLs.
 
 Example prompts: list `~/My Files/`, dry-run pull a folder, pull it, push results back.
 
@@ -76,7 +133,7 @@ Import via Settings → Skills → Import from GitHub (or upload the folder). Ho
 | `get_execution` / `list_execution_results` / `cancel_execution` | Status / results / cancel (`cancel_execution` needs `confirm=true`) |
 | `estimate_workflow_cost` | Cost estimate from merged params (same validation as prepare) |
 
-Auth is shared with the CLI (OS keychain + `~/.config/proteworks/`). There is no separate MCP login.
+Auth is shared with the CLI. The access token is stored in the OS keychain and mirrored to `~/.config/proteworks/credentials` (mode `0600`) so Claude Science’s sandbox can read it. There is no separate MCP login: run `proteworks login` in a terminal, then restart the connector.
 
 ### MCP safety env
 

{proteworks-0.1.4 → proteworks-0.1.9}/README.md

@@ -2,37 +2,94 @@
 
 Command line client and local MCP server for syncing Proteworks files and submitting allowlisted workflows. The default API is production. Set `PROTEWORKS_API_URL` only when testing against staging or a local stack.
 
+## One install (CLI + Claude Science)
+
+There is a **single supported install**:
+
+| Path | Role |
+| --- | --- |
+| `/opt/proteworks` | Package + `proteworks-mcp` |
+| `/usr/local/bin/proteworks` | CLI symlink |
+| `/usr/local/bin/proteworks-mcp` | MCP symlink (Science **Command**) |
+| `~/.config/proteworks/` | Login token file + org config |
+
+Do **not** keep a second copy from `uv tool` / pipx / a repo `.venv` on your PATH for daily use. Those diverge and break Claude Science.
+
+### Bootstrap once, then use only `/usr/local/bin`
+
 ```bash
-uv tool install proteworks
+# 1) Temporary bootstrap (any machine with uv)
+uv tool install 'proteworks[mcp]'
+
+# 2) Canonical install (needs sudo). Uses distro python3.12+ under /usr (not uv under $HOME).
+sudo "$(which proteworks)" mcp install-system
+# Developers working from a git checkout before publishing:
+# sudo "$(which proteworks)" mcp install-system --package-spec "$PWD[mcp]"
+
+# 3) Remove the bootstrap copy so PATH has one binary
+uv tool uninstall proteworks
+hash -r
+which -a proteworks   # expect only /usr/local/bin/proteworks
+
+# 4) Login + Science grants
 proteworks login
-proteworks organization list
 proteworks organization set "My Org"
-proteworks pull '~/My Files/campaigns/run/' ./run
-proteworks push ./1UBQ.pdb '~/My Files/test/'
-proteworks push ./run '~/My Files/campaigns/run/'
+proteworks mcp setup-claude-science
+proteworks mcp doctor
 ```
 
-Quote wildcards so the shell does not expand them. A trailing slash on a remote path means a folder. `proteworks --help` lists every command.
+After any upgrade: run step 2 again (same `install-system` command), then `doctor`. Do not `uv tool install` again unless `/usr/local/bin/proteworks` is missing.
 
-Login returns to `http://127.0.0.1:8765/callback`. Add that exact URL to the Auth0 application's Allowed Callback URLs. The same URL is used in development and production.
+### Claude Science connector
 
-## MCP (Claude Science and other clients)
+`setup-claude-science` prints the fields. Always:
 
-The same login and organization selection power a local MCP server. Install the MCP extra, sign in once with the CLI, then point your client at `proteworks-mcp`.
+| Field | Value |
+| --- | --- |
+| **Name** | `proteworks` |
+| **Command** | `/opt/proteworks/bin/proteworks-mcp` |
+| **Arguments** | leave empty |
+| **Env** (if shown) | `PROTEWORKS_CONFIG_DIR=$HOME/.config/proteworks` |
+
+Paste **only** that Command path. Do not use `python -m …`, `uvx`, or a path under `~/.local`. Science’s one-field UI can drop `-m` and hang for 180s; sandboxed `HOME` also cannot see a second user-level install’s credentials unless you use the system layout above.
+
+Fully quit and relaunch Claude Science after setup so it reloads `config.toml`.
+Also add each host **by name** under Science **Settings → Domain Allowlist**
+(Science rejects wildcards). `setup-claude-science` prints the list — typically
+`api.studio.proteworks.com` plus virtual-hosted GCS hosts such as
+`proteworks-production.storage.googleapis.com`. The connector’s `config.toml`
+grants are necessary but Science’s UI allowlist often gates egress separately.
+Bare `storage.googleapis.com` is hard-denylisted (path-style GCS). If pull still
+fails for a custom org bucket, add `<bucket>.storage.googleapis.com`. Science may
+set `ALL_PROXY` (SOCKS); `proteworks` depends on `httpx[socks]` so that works out
+of the box. If a direct GCS PUT is still blocked, push falls back to uploading
+through the Proteworks API host.
+
+Allow Claude to push/pull from a real project (like the CLI — no staging copy):
 
 ```bash
-uv tool install 'proteworks[mcp]'
-# or: pip install 'proteworks[mcp]'
-proteworks login
-proteworks organization set "My Org"
+proteworks mcp setup-claude-science --mcp-root ~/projects/my-campaign
+```
+
+That grants the Science sandbox **and** writes `~/.config/proteworks/mcp_roots`.
+Restart the connector afterward. Absolute paths under that project then work with
+MCP `push` / `pull`.
+
+`proteworks --version` / `proteworks-mcp --version` print the installed version.
+
+Quote wildcards so the shell does not expand them. A trailing slash on a remote path means a folder. `proteworks --help` lists every command.
+
+```bash
+proteworks pull '~/My Files/campaigns/run/' ./run
+proteworks push ./1UBQ.pdb '~/My Files/test/'
+proteworks push '*.pdb' '~/My Files/pdbs/'
+proteworks push designs.zip '~/My Files/dest/'   # auto-extracts
+proteworks mkdir '~/My Files/campaigns/round6/'
 ```
 
-### Claude Science
+MCP also exposes `create_folder` for the same empty-directory create (returns `folder_id` for `output_folder_id` / push).
 
-1. Settings → Connectors → Add connector → **Local command**
-2. Command: `proteworks-mcp`  
-   (or `uvx --from 'proteworks[mcp]' proteworks-mcp`)
-3. Approve tools as needed
+Login returns to `http://127.0.0.1:8765/callback`. Add that exact URL to the Auth0 application's Allowed Callback URLs.
 
 Example prompts: list `~/My Files/`, dry-run pull a folder, pull it, push results back.
 
@@ -62,7 +119,7 @@ Import via Settings → Skills → Import from GitHub (or upload the folder). Ho
 | `get_execution` / `list_execution_results` / `cancel_execution` | Status / results / cancel (`cancel_execution` needs `confirm=true`) |
 | `estimate_workflow_cost` | Cost estimate from merged params (same validation as prepare) |
 
-Auth is shared with the CLI (OS keychain + `~/.config/proteworks/`). There is no separate MCP login.
+Auth is shared with the CLI. The access token is stored in the OS keychain and mirrored to `~/.config/proteworks/credentials` (mode `0600`) so Claude Science’s sandbox can read it. There is no separate MCP login: run `proteworks login` in a terminal, then restart the connector.
 
 ### MCP safety env
 

{proteworks-0.1.4 → proteworks-0.1.9}/pyproject.toml

@@ -1,11 +1,12 @@
 [project]
 name = "proteworks"
-version = "0.1.4"
+version = "0.1.9"
 description = "Sync files with Proteworks using file-browser paths."
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
-    "httpx>=0.27",
+    # socks: Claude Science sets ALL_PROXY; httpx needs socksio for that backend.
+    "httpx[socks]>=0.27",
     "keyring>=25",
 ]
 

proteworks-0.1.9/src/proteworks/__init__.py

@@ -0,0 +1,13 @@
+"""Proteworks sync client."""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("proteworks")
+    except PackageNotFoundError:
+        __version__ = "0.1.9"
+except Exception:  # pragma: no cover
+    __version__ = "0.1.9"

{proteworks-0.1.4 → proteworks-0.1.9}/src/proteworks/api.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
+import json
 import os
 import time
+from pathlib import Path
 from typing import Any, Optional
 from urllib.parse import urlencode, urlparse
 
@@ -199,26 +201,162 @@ class ApiClient:
             data={"name": name, "parent_id": parent_id},
         )
 
-    def upload_init(self, filename: str, folder_id: str, size_bytes: int, content_type: str) -> dict:
-        return self.request(
+    def upload_init(
+        self,
+        filename: str,
+        folder_id: str,
+        size_bytes: int,
+        content_type: str,
+        *,
+        upload_purpose: str = "default",
+        extraction_job_id: Optional[str] = None,
+        skip_existing: bool = False,
+    ) -> dict:
+        """Initialize a direct upload. Retries on HTTP 429 (shared upload rate limit)."""
+        body: dict[str, Any] = {
+            "filename": filename,
+            "folder_id": folder_id,
+            "content_type": content_type,
+            "size_bytes": size_bytes,
+            "upload_purpose": upload_purpose,
+            "skip_existing": skip_existing,
+        }
+        if extraction_job_id:
+            body["extraction_job_id"] = extraction_job_id
+        return self._request_with_backoff(
             "POST",
             "/api/v1/files/upload-init",
-            json_body={
-                "filename": filename,
-                "folder_id": folder_id,
-                "content_type": content_type,
-                "size_bytes": size_bytes,
-                "skip_existing": False,
-            },
+            json_body=body,
         )
 
     def upload_complete(self, session_id: str, size_bytes: int) -> dict:
-        return self.request(
+        """Finalize a direct upload. Retries on HTTP 429."""
+        return self._request_with_backoff(
             "POST",
             "/api/v1/files/upload-complete",
             json_body={"session_id": session_id, "size_bytes": size_bytes},
         )
 
+    def upload_batch(
+        self,
+        files: list[tuple[str, Path, str]],
+        folder_ids: list[str],
+        *,
+        skip_existing: bool = False,
+    ) -> dict:
+        """POST /files/upload-batch (multipart). Each file is (filename, path, content_type)."""
+        if len(files) != len(folder_ids):
+            raise ApiError("folder_ids length must match files length", 400)
+        if len(files) > 1000:
+            raise ApiError("Maximum 1000 files per upload-batch request", 400)
+        query: dict[str, str] = {}
+        if self.organization_id:
+            query["organization_id"] = self.organization_id
+        url = self.base_url + "/api/v1/files/upload-batch"
+        if query:
+            url = url + "?" + urlencode(query)
+        data = {"folder_ids": json.dumps(list(folder_ids))}
+        if skip_existing:
+            data["skip_existing"] = "true"
+        delay_seconds = 1.0
+        last_error: Optional[ApiError] = None
+        for attempt in range(6):
+            handles = []
+            try:
+                multipart = []
+                for filename, path, content_type in files:
+                    handle = Path(path).open("rb")
+                    handles.append(handle)
+                    multipart.append(
+                        (
+                            "files",
+                            (
+                                filename,
+                                handle,
+                                content_type or "application/octet-stream",
+                            ),
+                        )
+                    )
+                response = self._client.post(
+                    url,
+                    headers=self._headers(),
+                    data=data,
+                    files=multipart,
+                    timeout=600.0,
+                )
+                if response.status_code == 429 and attempt < 5:
+                    last_error = ApiError(public_detail(response), 429)
+                    time.sleep(delay_seconds)
+                    delay_seconds = min(delay_seconds * 2, 30.0)
+                    continue
+                if response.status_code >= 400:
+                    raise ApiError(public_detail(response), response.status_code)
+                if not response.content:
+                    return {"successful": [], "failed": [], "skipped": []}
+                return response.json()
+            except ApiError as exc:
+                if exc.status_code != 429 or attempt == 5:
+                    raise
+                last_error = exc
+                time.sleep(delay_seconds)
+                delay_seconds = min(delay_seconds * 2, 30.0)
+            finally:
+                for handle in handles:
+                    handle.close()
+        raise last_error or ApiError("upload-batch failed", 500)
+
+    def exists_batch(self, items: list[dict[str, str]]) -> dict:
+        """POST /files/exists-batch. Each item is {folder_id, name}. Chunks to 2000."""
+        merged: list[dict] = []
+        chunk_size = 2000
+        for start in range(0, len(items), chunk_size):
+            chunk = items[start : start + chunk_size]
+            payload = self._request_with_backoff(
+                "POST",
+                "/api/v1/files/exists-batch",
+                json_body={"items": chunk},
+            )
+            merged.extend(list((payload or {}).get("existing") or []))
+        return {"existing": merged, "existing_count": len(merged), "requested_count": len(items)}
+
+    def create_archive_extraction_job(
+        self,
+        zip_filename: str,
+        zip_size: int,
+        extract_to_folder_id: str,
+    ) -> dict:
+        return self._request_with_backoff(
+            "POST",
+            "/api/v1/files/archive-extraction-jobs",
+            json_body={
+                "zip_filename": zip_filename,
+                "zip_size": zip_size,
+                "extract_to_folder_id": extract_to_folder_id,
+            },
+        )
+
+    def start_archive_extraction(
+        self,
+        file_id: str,
+        extract_to_folder_id: str,
+        *,
+        job_id: Optional[str] = None,
+    ) -> dict:
+        body: dict[str, Any] = {
+            "file_id": file_id,
+            "extract_to_folder_id": extract_to_folder_id,
+        }
+        if job_id:
+            body["job_id"] = job_id
+        return self._request_with_backoff(
+            "POST",
+            "/api/v1/files/archive-extraction",
+            json_body=body,
+        )
+
+    def get_zip_extraction_job(self, job_id: str) -> dict:
+        return self.request("GET", f"/api/v1/files/zip-extraction-jobs/{job_id}")
+
     def download_to(self, url: str, path) -> None:
         """Stream bytes to a file. The URL is not logged."""
         assert_allowed_storage_url(url)
@@ -236,6 +374,32 @@ class ApiClient:
         if response.status_code >= 400:
             raise ApiError(f"Upload to storage failed ({response.status_code})", response.status_code)
 
+    def upload_multipart(self, filename: str, folder_id: str, path, content_type: str) -> dict:
+        """Upload via POST /api/v1/files/upload (API proxy; avoids direct GCS egress).
+
+        Used when the sandbox blocks path-style ``storage.googleapis.com`` (Claude Science
+        denylist) so bytes can still reach Studio through the allowlisted API host.
+        """
+        query: dict[str, str] = {}
+        if self.organization_id:
+            query["organization_id"] = self.organization_id
+        url = self.base_url + "/api/v1/files/upload"
+        if query:
+            url = url + "?" + urlencode(query)
+        headers = self._headers()
+        with open(path, "rb") as handle:
+            response = self._client.post(
+                url,
+                headers=headers,
+                data={"folder_id": folder_id},
+                files={"file": (filename, handle, content_type or "application/octet-stream")},
+            )
+        if response.status_code >= 400:
+            raise ApiError(public_detail(response), response.status_code)
+        if not response.content:
+            return {}
+        return response.json()
+
     def list_agent_schemas(self) -> dict:
         return self.request("GET", "/api/v1/workflows/agent-schemas")
 
@@ -248,6 +412,36 @@ class ApiClient:
     def get_execution(self, execution_id: str) -> dict:
         return self.request("GET", f"/api/v1/workflows/executions/{execution_id}")
 
+    def get_execution_detailed_status(
+        self,
+        execution_id: str,
+        *,
+        steps_limit: Optional[int] = None,
+    ) -> dict:
+        """GET detailed Pod-step status (Argo) for an execution."""
+        params: dict[str, Any] = {}
+        if steps_limit is not None:
+            params["steps_limit"] = int(steps_limit)
+        return self.request(
+            "GET",
+            f"/api/v1/workflows/executions/{execution_id}/status/detailed",
+            params=params or None,
+        )
+
+    def get_execution_step_logs(
+        self,
+        execution_id: str,
+        step_name: str,
+        *,
+        tail_lines: int = 500,
+    ) -> dict:
+        """GET logs for one workflow step (Pod node)."""
+        return self.request(
+            "GET",
+            f"/api/v1/workflows/executions/{execution_id}/steps/{step_name}/logs",
+            params={"tail_lines": int(tail_lines)},
+        )
+
     def list_execution_results(self, execution_id: str) -> list:
         payload = self.request("GET", f"/api/v1/workflows/executions/{execution_id}/results")
         return list(payload or [])

{proteworks-0.1.4 → proteworks-0.1.9}/src/proteworks/browse.py

@@ -12,12 +12,13 @@ def list_remote(api: ApiClient, path: str, *, limit: int = 200) -> dict[str, Any
     List files under a file-browser path.
 
     Returns agent-safe fields only (includes file_id for future cloud submit).
-    Caps the item list at ``limit`` and sets truncated=true when more remain.
+    Fetches a single manifest page of ``limit`` items (does not walk the whole
+    tree). Sets truncated=true when the API reports more remain.
     """
     if limit < 1:
         raise ValueError("limit must be at least 1")
     try:
-        page = api.manifest_all(path)
+        page = api.manifest(path, 0, limit=limit)
     except ApiError as exc:
         return {
             "ok": False,
@@ -29,8 +30,8 @@ def list_remote(api: ApiClient, path: str, *, limit: int = 200) -> dict[str, Any
         }
     raw_items = list(page.get("items") or [])
     total = int(page.get("total") or len(raw_items))
-    truncated = len(raw_items) > limit
-    items = [_normalize_item(item) for item in raw_items[:limit]]
+    truncated = total > len(raw_items)
+    items = [_normalize_item(item) for item in raw_items]
     return {
         "ok": True,
         "items": items,