proteworks 0.1.3__tar.gz → 0.1.9__tar.gz

proteworks-0.1.9/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: proteworks
+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[socks]>=0.27
+Requires-Dist: keyring>=25
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Requires-Dist: pyarrow>=14; extra == "mcp"
+
+# proteworks
+
+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
+# 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 set "My Org"
+proteworks mcp setup-claude-science
+proteworks mcp doctor
+```
+
+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.
+
+### Claude Science connector
+
+`setup-claude-science` prints the fields. Always:
+
+| 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
+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/'
+```
+
+MCP also exposes `create_folder` for the same empty-directory create (returns `folder_id` for `output_folder_id` / push).
+
+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.
+
+Optional coaching skills (not required for the server):
+
+- [`skills/proteworks-files/SKILL.md`](skills/proteworks-files/SKILL.md)
+- [`skills/proteworks-workflows/SKILL.md`](skills/proteworks-workflows/SKILL.md)
+
+Import via Settings → Skills → Import from GitHub (or upload the folder). Hosts without a Skills UI still get conventions from MCP tool descriptions and this README.
+
+### Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `auth_status` | Login state, API URL, active org (never the token) |
+| `organization_list` / `organization_set` | Choose organization (`organization_set` needs `confirm=true`) |
+| `list_files` | Browse a remote path; returns `file_id` + `relative_path` |
+| `pull` / `push` | Transfer with `dry_run` (default true); real transfers need `confirm_transfer=true` |
+| `list_workflows` | Allowlisted agent workflows (`rf-diffusion3`, `proteinmpnn`, `refolding`, `structure-prediction`, `msa-generation`) |
+| `get_workflow_schema` | Full schema with UI-matching defaults |
+| `prepare_workflow_submission` | Merge defaults + overrides; **no submit** (draft body) |
+| `submit_workflow` | Same merge, then submit |
+| `inspect_studio` | Inspect supported `.studio` (proteinmpnn / refolding / rf-diffusion3 / structure_prediction); normalized rows + scores |
+| `save_selected_studio` | Same as Studio Save selected → subset `.studio` uploaded + retention finalized (not yet for structure_prediction) |
+| `inspect_proteinmpnn_studio` | Legacy ProteinMPNN flat-row inspect (prefer `inspect_studio`) |
+| `prepare_refolding_from_proteinmpnn_studio` | Build refolding payload + SA handoff from MPNN studio selection (**no submit**) |
+| `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. 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
+
+| Variable | Purpose |
+| --- | --- |
+| `PROTEWORKS_MCP_ROOT` | Local workspace root for `pull`/`push` (default: process cwd) |
+| `PROTEWORKS_MCP_READ_ONLY` | When `1`/`true`, disables submit/push/cancel/save-selected |
+| `PROTEWORKS_STORAGE_HOST_ALLOWLIST` | Comma-separated host suffixes for signed URL follow (default: GCS hosts) |
+| `PROTEWORKS_MAX_STUDIO_BYTES` | Max `.studio` download size (default 80 MiB) |
+| `PROTEWORKS_STUDIO_INSPECT_LIMIT` | Default row page size for `inspect_studio` (default 50) |
+
+**Staging smoke:** `auth_status` → `list_workflows` → `get_workflow_schema` → `prepare_workflow_submission` → `estimate_workflow_cost` → `submit_workflow` → `get_execution` → `cancel_execution` (with `confirm=true` if still running).
+
+### Workflow submit
+
+1. `list_files` → get `file_id` for any structure input.
+2. `get_workflow_schema` for the workflow (`rf-diffusion3`, `proteinmpnn`, `refolding`, `structure-prediction`, or `msa-generation`).
+3. `prepare_workflow_submission` to review the merged payload (defaults match a fresh Studio form).
+4. `submit_workflow` when ready.
+
+**Refolding** and **Structure Prediction** have no default predictor/MSA — agents must **ask the user** which methods and (when required) which MSA to use before prepare/submit. Structure Prediction also requires a user-provided complex (`structure-prediction-complex-json`). **MSA generation** has no default sequences — ask, then pass `generated-fasta-inputs` or `fasta_files`; use the run **output folder** as `msa_output_folder` downstream. From ProteinMPNN results: `inspect_studio` → ask → `prepare_refolding_from_proteinmpnn_studio` → `submit_workflow`.
+
+**`.studio` results:** `inspect_studio` → filter by scores (e.g. pLDDT / Rg) → `save_selected_studio` to write a subset bundle (structure_prediction is inspect-only for now).
+
+Payload shape matches Studio `POST /api/v1/workflows/submit` and is reserved for future shareable draft links (`/app?workflowDraft=<id>`) that open the form pre-filled without submitting.
+
+### Adding another workflow to the allowlist
+
+In **protein-studio**:
+
+1. Extract `buildXDefaultParameters` + form init from that workflow’s UI.
+2. Implement `buildXAgentSchema()`.
+3. Run `npm run export-agent-schemas` in `frontend/`; commit JSON under `backend/app/data/agent_workflow_schemas/`.
+4. Add the workflow id to allowlists (frontend export index, backend `AGENT_WORKFLOW_ALLOWLIST`, proteworks-cli `AGENT_WORKFLOW_ALLOWLIST`).
+5. Add default/parity tests; extend the workflows skill if needed.
+
+No new MCP tool names are required.

proteworks-0.1.9/README.md

@@ -0,0 +1,159 @@
+# proteworks
+
+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
+# 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 set "My Org"
+proteworks mcp setup-claude-science
+proteworks mcp doctor
+```
+
+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.
+
+### Claude Science connector
+
+`setup-claude-science` prints the fields. Always:
+
+| 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
+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/'
+```
+
+MCP also exposes `create_folder` for the same empty-directory create (returns `folder_id` for `output_folder_id` / push).
+
+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.
+
+Optional coaching skills (not required for the server):
+
+- [`skills/proteworks-files/SKILL.md`](skills/proteworks-files/SKILL.md)
+- [`skills/proteworks-workflows/SKILL.md`](skills/proteworks-workflows/SKILL.md)
+
+Import via Settings → Skills → Import from GitHub (or upload the folder). Hosts without a Skills UI still get conventions from MCP tool descriptions and this README.
+
+### Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `auth_status` | Login state, API URL, active org (never the token) |
+| `organization_list` / `organization_set` | Choose organization (`organization_set` needs `confirm=true`) |
+| `list_files` | Browse a remote path; returns `file_id` + `relative_path` |
+| `pull` / `push` | Transfer with `dry_run` (default true); real transfers need `confirm_transfer=true` |
+| `list_workflows` | Allowlisted agent workflows (`rf-diffusion3`, `proteinmpnn`, `refolding`, `structure-prediction`, `msa-generation`) |
+| `get_workflow_schema` | Full schema with UI-matching defaults |
+| `prepare_workflow_submission` | Merge defaults + overrides; **no submit** (draft body) |
+| `submit_workflow` | Same merge, then submit |
+| `inspect_studio` | Inspect supported `.studio` (proteinmpnn / refolding / rf-diffusion3 / structure_prediction); normalized rows + scores |
+| `save_selected_studio` | Same as Studio Save selected → subset `.studio` uploaded + retention finalized (not yet for structure_prediction) |
+| `inspect_proteinmpnn_studio` | Legacy ProteinMPNN flat-row inspect (prefer `inspect_studio`) |
+| `prepare_refolding_from_proteinmpnn_studio` | Build refolding payload + SA handoff from MPNN studio selection (**no submit**) |
+| `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. 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
+
+| Variable | Purpose |
+| --- | --- |
+| `PROTEWORKS_MCP_ROOT` | Local workspace root for `pull`/`push` (default: process cwd) |
+| `PROTEWORKS_MCP_READ_ONLY` | When `1`/`true`, disables submit/push/cancel/save-selected |
+| `PROTEWORKS_STORAGE_HOST_ALLOWLIST` | Comma-separated host suffixes for signed URL follow (default: GCS hosts) |
+| `PROTEWORKS_MAX_STUDIO_BYTES` | Max `.studio` download size (default 80 MiB) |
+| `PROTEWORKS_STUDIO_INSPECT_LIMIT` | Default row page size for `inspect_studio` (default 50) |
+
+**Staging smoke:** `auth_status` → `list_workflows` → `get_workflow_schema` → `prepare_workflow_submission` → `estimate_workflow_cost` → `submit_workflow` → `get_execution` → `cancel_execution` (with `confirm=true` if still running).
+
+### Workflow submit
+
+1. `list_files` → get `file_id` for any structure input.
+2. `get_workflow_schema` for the workflow (`rf-diffusion3`, `proteinmpnn`, `refolding`, `structure-prediction`, or `msa-generation`).
+3. `prepare_workflow_submission` to review the merged payload (defaults match a fresh Studio form).
+4. `submit_workflow` when ready.
+
+**Refolding** and **Structure Prediction** have no default predictor/MSA — agents must **ask the user** which methods and (when required) which MSA to use before prepare/submit. Structure Prediction also requires a user-provided complex (`structure-prediction-complex-json`). **MSA generation** has no default sequences — ask, then pass `generated-fasta-inputs` or `fasta_files`; use the run **output folder** as `msa_output_folder` downstream. From ProteinMPNN results: `inspect_studio` → ask → `prepare_refolding_from_proteinmpnn_studio` → `submit_workflow`.
+
+**`.studio` results:** `inspect_studio` → filter by scores (e.g. pLDDT / Rg) → `save_selected_studio` to write a subset bundle (structure_prediction is inspect-only for now).
+
+Payload shape matches Studio `POST /api/v1/workflows/submit` and is reserved for future shareable draft links (`/app?workflowDraft=<id>`) that open the form pre-filled without submitting.
+
+### Adding another workflow to the allowlist
+
+In **protein-studio**:
+
+1. Extract `buildXDefaultParameters` + form init from that workflow’s UI.
+2. Implement `buildXAgentSchema()`.
+3. Run `npm run export-agent-schemas` in `frontend/`; commit JSON under `backend/app/data/agent_workflow_schemas/`.
+4. Add the workflow id to allowlists (frontend export index, backend `AGENT_WORKFLOW_ALLOWLIST`, proteworks-cli `AGENT_WORKFLOW_ALLOWLIST`).
+5. Add default/parity tests; extend the workflows skill if needed.
+
+No new MCP tool names are required.

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

@@ -1,19 +1,22 @@
 [project]
 name = "proteworks"
-version = "0.1.3"
+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",
 ]
 
 [project.optional-dependencies]
 dev = ["pytest>=8"]
+mcp = ["mcp>=1.2", "pyarrow>=14"]
 
 [project.scripts]
 proteworks = "proteworks.cli:main"
+proteworks-mcp = "proteworks.mcp.server:main"
 
 [build-system]
 requires = ["setuptools>=68"]

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"