Metadata-Version: 2.4
Name: apheris-foundry-cli
Version: 2.0.0
Summary: Command-line interface for Apheris Foundry workflows.
Author: Apheris
License-Expression: LicenseRef-Apheris-Foundry-Software-License
Project-URL: Homepage, https://github.com/apheris/apheris-foundry-cli
Project-URL: License, https://www.apheris.com/docs/hub/hub-license.html
Project-URL: Repository, https://github.com/apheris/apheris-foundry-cli
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.28
Requires-Dist: httpcore>=1.0.9
Requires-Dist: jsonschema<5,>=4
Requires-Dist: PyYAML<7,>=6.0.3
Requires-Dist: rich>=13
Requires-Dist: truststore<1,>=0.10
Requires-Dist: typer<1,>=0.12
Provides-Extra: dev
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: pytest<10,>=9; extra == "dev"
Requires-Dist: ruff<1,>=0.9; extra == "dev"
Requires-Dist: wheel<1,>=0.45; extra == "dev"
Dynamic: license-file

# Apheris Foundry CLI

Command-line interface for submitting and managing Foundry workflow runs on an Apheris Hub instance.

## Requirements

- Python 3.10 or later
- Access to an Apheris Hub instance

## Installation

### conda

Recommended if you already use conda for scientific Python work. A dedicated environment avoids dependency conflicts.

#### Linux / macOS

```bash
conda create -n apheris-foundry python=3.11 -y
conda activate apheris-foundry
pip install apheris-foundry-cli
```

#### Windows (Anaconda Prompt or PowerShell)

```powershell
conda create -n apheris-foundry python=3.11 -y
conda activate apheris-foundry
pip install apheris-foundry-cli
```

Activate the environment at the start of each session with `conda activate apheris-foundry`.

### venv (standard Python)

#### Linux / macOS (venv)

```bash
python3 -m venv ~/.venvs/apheris-foundry
source ~/.venvs/apheris-foundry/bin/activate
pip install apheris-foundry-cli
```

#### Windows (PowerShell, venv)

```powershell
python -m venv $env:USERPROFILE\.venvs\apheris-foundry
& $env:USERPROFILE\.venvs\apheris-foundry\Scripts\Activate.ps1
pip install apheris-foundry-cli
```

Activate the environment at the start of each session with the `activate` command above.

### Verify

```bash
apheris-foundry --version
apheris-foundry --help
```

### Upgrade

```bash
pip install --upgrade apheris-foundry-cli
```

## Login

Connect to your Hub using the URL provided by your team:

```bash
apheris-foundry login --url https://hub.example.com
```

Follow the sign-in instructions. The CLI saves your session for later commands.
Use `apheris-foundry logout` to sign out, or log in again to switch Hubs.

If login reports that its local ports are already in use, follow the commands
in the error message to identify the conflicting application. Close it if
appropriate, then retry login. If you cannot resolve the conflict, share the
error message with your support team.

## Install agent skills

If you use an AI agent, install the CLI guidance for your agent:

```bash
apheris-foundry skills install --agent codex
# Or: apheris-foundry skills install --agent claude
```

The CLI skill is bundled and can be installed offline. After login, install
workflow guidance directly from your Hub:

```bash
apheris-foundry workflows list
apheris-foundry skills install --workflow predict --agent codex
```

Use `--path ./.agents/skills` instead of `--agent` for another agent or a
project directory. Reload skills in your agent if needed. Installing skills
copies instructions; it does not log in or submit a job.

`skills list` shows bundled CLI skills and every workflow skill from your active
Hub together. If Hub is unavailable, bundled skills still appear; unavailable
workflow skills are quietly skipped. Display the selected skill without installing it:

```bash
apheris-foundry skills show apheris-foundry-hub
apheris-foundry skills show --workflow predict
apheris-foundry skills show apheris-workflow-predict
# Install every bundled and Hub workflow skill after login:
apheris-foundry skills install --all --agent codex
```

The default `skills install --agent codex` installs all bundled skills offline. Use `--force` when you
want to replace an installed skill, including after changing Hubs or upgrading
workflows. Replacement removes local edits and stale files in that skill only.

Older Hubs or custom workflows may not provide skills yet. In that case, the
CLI reports the API error; ask your Hub administrator to deploy workflow skills.
See [Using the CLI](docs/usage.md) for help and skill provenance details.

## Quick start: predict a structure

### Choose an MSA server

MSA server preferences live under `settings`, just as in the Hub UI:

```bash
apheris-foundry settings msa list
# Select an ID shown in the list:
apheris-foundry settings msa select 2
```

The list shows the servers configured on your current Hub and marks the active
one. IDs vary by deployment; use your Hub's list. Selection is saved
on Hub and shared with the UI. Subsequent MSA-enabled Foundry runs use it without
an additional run option. If you do not change this setting, existing behavior
is preserved. Switching servers does not change jobs already submitted.

Use `apheris-foundry settings msa disable` to opt out of automatic MSA and supply
your own MSA files where required. Select a server again to re-enable it.
Each command supports `--json`. See [MSA settings](docs/usage.md#msa-settings)
for details about preference scope and scripting.

### Submit a prediction

After login, check that your Hub offers prediction:

```bash
apheris-foundry workflows get --workflow predict
apheris-foundry workflows docs --workflow predict
apheris-foundry workflows models --workflow predict
```

Save this small example as `request.json`:

```json
{
  "queries": [{
    "chains": [{
      "chain_id": "A",
      "polymer_type": "protein",
      "sequence": "GSAEYVRALFDFNGNDEEDLPFKKGDILRIRDKPEEQWWNAEDSEGKRGMIPVPYVEKYHHHHHH"
    }]
  }]
}
```

Submit it using your Hub's default model settings:

```bash
apheris-foundry workflows run --workflow predict --input request.json
```

Optionally add a name and one or more tags when submitting:

```bash
apheris-foundry workflows run --workflow predict --input request.json \
  --name "Kinase pilot" --tag kinase --tag pilot
```

Omit `--name` for an unnamed run and omit `--tag` for an untagged run. Repeat
`--tag` for multiple tags. Hub validates and normalizes tags, trimming whitespace,
removing empty tags and deduplicating them. `jobs list` shows the saved name and
tags in separate `NAME` and `TAGS` columns; `jobs get --id <job-id>` shows both
fields in detail. Missing names and tags appear as `—`.

Repeat `--input` to upload several files for one run, as AQCell inference takes
compounds, cell lines and a config together (the
[six-pair example](https://github.com/apheris/foundry-toolkit/tree/main/workflows/aqcell/examples)
matches this layout):

```bash
apheris-foundry workflows run --workflow aqcell --input ligands.csv --input cell_lines.csv --input config.json
```

Folders and ZIP files use binary archive upload on Hub versions that support
`POST /api/v1/foundry/runs/upload`:

```bash
apheris-foundry workflows run --workflow aqcell-finetune --input ./input/ --name training
apheris-foundry workflows run --workflow aqcell-finetune --input ./finetune-input.zip --strip-archive-root --name training
```

Folders are packaged automatically as an uncompressed ZIP in a temporary directory,
then streamed to Hub. The temporary archive is removed after submission, including
on failure. Existing ZIPs are validated; pass a ZIP alone. Hidden files and directories
(dot-prefixed path components) are excluded. ZIPs containing them are streamed
into a filtered temporary ZIP; other ZIPs are uploaded unchanged.
Binary contents and relative paths are preserved by default. For the supplier's
extra `input/` folder, pass `--strip-archive-root` explicitly. Folder uploads
need local temporary disk space roughly equal to the dataset size. Uploads and
expanded archives are limited to 1 GiB; the server controls the entry count; links, traversal and
conflicting paths are rejected. A failed network upload must be submitted again;
uploads are not resumable or reusable datasets. Single text-file inputs retain
the existing JSON submission path for older Hub versions.

This uploads the input and starts a job on Hub. Copy the returned job ID and use
it in the commands below:

```bash
apheris-foundry jobs get --id <job-id>
apheris-foundry jobs logs --id <job-id>
# After the job succeeds:
apheris-foundry jobs download --id <job-id> --output ./results
```

If the job fails, use `apheris-foundry jobs error --id <job-id>` to inspect the
error before retrying. Prediction requires a Hub with the model and compute
resources configured; this example uses those resources.

Override model parameters inline or from a JSON/YAML file. Select models and weights
advertised by `workflows models`:

```bash
apheris-foundry workflows run --workflow predict --input request.json \
  --model-params '{"seeds":[7,9],"num_diffusion_samples":3}'
apheris-foundry workflows run --workflow predict --input request.json \
  --model <model-id> --weight <weight-version> \
  --model-params @./model-params.yaml
```

### Submit a benchmark

The [one-structure benchmark example](examples/benchmark/README.md) includes a
public CIF, a YAML manifest, a JSON alternative, and commands for model/weight
selection, MSA setup, submission and result inspection. The runnable folder
contains exactly one manifest and its reference structure:

```bash
apheris-foundry workflows run --workflow benchmark \
  --name benchmark-1B07-yaml --input ./examples/benchmark/input
```

Check `workflows docs --workflow benchmark` and the model catalog on your Hub
before running. This performs real prediction; no model-parameter overrides are
needed for the workflow's one-sample, seed-42 defaults.

## Quick start: models and weights

```bash
# 1. Discover: one row per model and weight (* = default); --weight shows one in detail
apheris-foundry workflows models --workflow predict
apheris-foundry workflows models --workflow predict --weight of3p2
# 2. Use a listed model and weight (rejected if not listed; never substituted)
apheris-foundry workflows run --workflow predict --input request.json --model openfold3 --weight of3p2
# 3. Make a fine-tuned checkpoint available: private, or --public for everyone on this Hub
apheris-foundry weights enable --name my-kinase-ft --run-id <finetune-job-id> --path <checkpoint-path> --tag kinase
# 4. It now appears as a weight in step 1; manage it by ID
apheris-foundry weights list
apheris-foundry weights delete --id <weight-id> --yes
```

The same steps work for `structural-finetune` (pick the base weight) and
`benchmark`. Add `--json` for scripts. Deleting the source job also deletes its
weights. Details: [Model weights](#model-weights-weights).

## Edit job names and tags

Update an existing run in any status, including succeeded, failed, or cancelled:

```bash
# Rename, preserving tags
apheris-foundry jobs update --id <job-id> --name "Corrected name"
# Replace all tags, preserving the name (does not append)
apheris-foundry jobs update --id <job-id> --tag mcl1 --tag rerun
# Change both fields and return the updated run as JSON
apheris-foundry jobs update --id <job-id> --name "Corrected name" --tag mcl1 --json
# Explicitly clear either field
apheris-foundry jobs update --id <job-id> --name ""
apheris-foundry jobs update --id <job-id> --clear-tags
```

Omitted fields remain unchanged. Supply at least one metadata option;
`--tag` and `--clear-tags` cannot be combined. Hub trims names and tags,
deduplicates tags, and removes empty tags. Output uses the updated metadata
returned by Hub. Existing ownership checks apply, and open Hub views receive
the metadata change notification.

## Command reference

### Authentication

| Command | Description |
| ------- | ----------- |
| `apheris-foundry login` | Log in to a Hub instance |
| `apheris-foundry logout` | Log out of the current session |

### Workflow definitions (`workflows`)

| Command | Description |
| ------- | ----------- |
| `apheris-foundry workflows list` | List workflow definitions exposed by Hub |
| `apheris-foundry workflows get --workflow <id>` | Inspect one workflow definition and advertised model defaults |
| `apheris-foundry workflows docs --workflow <id>` | Read the workflow's documentation, as its package ships it (`--json` includes the content digest) |
| `apheris-foundry workflows models --workflow <id> [--capability <name>]` | List models, weights and defaults advertised by Hub (`--json` includes full metadata) |
| `apheris-foundry workflows graph --workflow <id>` | Show the workflow DAG |
| `apheris-foundry workflows run --workflow <id> [--name <name>] [--tag <tag> ...] [--model-params <JSON\|@file>]` | Submit a workflow run with optional name/tags and Hub-schema-validated model parameters |

### Run instances (`runs`)

| Command | Description |
| ------- | ----------- |
| `apheris-foundry jobs list [--workflow <id>]` | List submitted jobs using server-side filters and bounded hydration |
| `apheris-foundry jobs get --id <job-id>` | Inspect a job and its artifacts |
| `apheris-foundry jobs update --id <job-id> [--name <name>] [--tag <tag> ... \| --clear-tags]` | Edit metadata; omitted fields stay unchanged, tags replace all existing tags, and `--name ""` / `--clear-tags` clear fields |
| `apheris-foundry jobs logs --id <job-id>` | Print logs for a job |
| `apheris-foundry jobs error --id <job-id>` | Print the saved error for a failed job |
| `apheris-foundry jobs download --id <job-id>` | Download results for a completed job |
| `apheris-foundry jobs cancel --id <job-id>` | Cancel a pending or running job |
| `apheris-foundry jobs delete --id <job-id>` | Permanently delete a terminal job and its stored data (`--yes` skips confirmation) |

Use `--help` on any command for the full option reference and examples:

```bash
apheris-foundry workflows run --help
apheris-foundry jobs get --help
```

`--name` optionally names the run. Omitted or blank names submit an unnamed run.

`--model-params` accepts an inline JSON object or a JSON/YAML parameter file. Use an inline object for short overrides, or prefix a `.json`, `.yaml` or `.yml` filename with `@` to load the object from that file. Before submitting the run, the CLI retrieves the selected model version, weight, and capability schema from Hub and validates the object. Use `workflows models` to discover available model IDs and weights.

### YAML model parameters

For example, `model-params.yaml` can contain:

```yaml
seeds: [42]
num_diffusion_samples: 1
```

Files must be UTF-8 and no larger than 8 MiB, with fewer than 50 nesting levels.
Duplicate keys, aliases, explicit YAML tags, multiple documents and non-finite
numbers are rejected. Scalars use JSON spellings; `on` and dates stay strings.
Inline values and files without a `.yaml`/`.yml` extension must use JSON syntax.
Workflow inputs are uploaded unchanged; YAML manifest support depends on the
workflow package deployed in Hub. Released CLI 0.10.0 accepts JSON parameter
files only.

## License

This package is licensed under the [Apheris Foundry Software License](https://www.apheris.com/docs/hub/hub-license.html). The full license text is also included in every published wheel as `LICENSE`.

## Support

Contact [support@apheris.com](mailto:support@apheris.com) for access and deployment assistance.


### Model weights (`weights`)

`weights` manages weights enabled from completed jobs: enable, list, inspect,
rename or relabel, share and delete. Every command accepts `--json`, which
prints Hub's response unchanged.

```sh
# 1. Enable weights from a job artifact (private by default)
apheris-foundry weights enable --name <unique-name> --run-id <job-id> --path <run-relative-bundle-directory> --tag trial --json
# 2. Label or rename it; --tag replaces the whole tag set, --clear-tags removes it
apheris-foundry weights update --id <weight-id> --tag trial --tag benchmark --name <new-name>
# 3. Find and inspect it
apheris-foundry weights list --model aqcell --version aqcell:0.2.0 --tag benchmark
apheris-foundry weights get --id <weight-id>
# 4. Use it
apheris-foundry workflows models --workflow aqcell --json
apheris-foundry workflows run --workflow aqcell --input ./input --weight <weight-id>
# 5. Retire it (also stops sharing it)
apheris-foundry weights delete --id <weight-id> --yes
apheris-foundry weights delete --id <weight-id> --delete-files --yes
```

`weights enable` matches the UI’s “Enable weights” action and replaces
`weights deploy`. Update existing scripts to use `weights enable`; the old
command is no longer supported. The Hub API endpoint remains `/api/v1/weights/deploy`.

`weights list` lists your weights plus weights other users shared. Filter with
`--run-id`, `--model`, `--version`, `--task` or repeated `--tag` (a weight must
carry every tag). `--model` and `--version` together also include the model's
built-in vendor weights. Hub returns every match in a single response, so there
is no pagination. The table shows ID, name, model, version, tags, owner and
status: `private`, `shared`, `built-in` or `deleted`. `weights get` and `--json`
report visibility (`isPublic`) and deletion (`isDeleted`) separately.
`--include-deleted` adds your deleted records; they cannot be selected.
`weights get --id` shows one weight in full, including its producing job,
lineage and who shared it when.

`weights enable` registers a job artifact through Hub; it does not upload local
weights or start prediction. `--name` is required: use an instance-wide unique
name of 1–255 characters after trimming whitespace, without control characters.
Names are case-sensitive and must be unique among active weights; deleting a
weight frees its name. `--description`
is separate metadata and does not replace the name. Use the path shown by
`jobs get`, including the complete directory for AQCell bundles. Optional
`--task`, `--description`, `--derived-from`, repeated `--capability` and
repeated `--tag` values accompany the request; Hub derives and validates model
identity and ownership. `--dry-run true weights enable ...` prints the request
without submission. Verify selection in the target workflow's model catalog
before reuse.

**Sharing.** Enabled weights are private. `--public` shares a weight with every
authenticated user of this Hub; they can list, inspect and run with it, but only
the owner can update or delete it. Hub fixes visibility when enabling: to stop
sharing a weight, delete it, and enable under a new name if you still need a
private copy. Mutating a weight you do not own fails with "Only the owner can
update or delete a weight".

**Deletion.** `weights delete --id` asks for confirmation; pass `--yes` in
scripts. By default, deletion is a soft delete: new jobs can no longer select
the weight, jobs already using it keep running, and checkpoint files remain.
Its name can be reused. Add `--delete-files` to permanently remove managed
checkpoint files as well; the record and provenance remain. This also works
on an already soft-deleted weight, and repeating either delete is safe.
If active jobs use the weight, Hub soft-deletes it but refuses file removal
with HTTP 409. The CLI exits with precondition code 4 and explains that files
remain; retry after the jobs finish. JSON success reports `cleanup: "removed"`
when deleting files and `cleanup: "deferred"` for soft deletion; deferred
cleanup requires an explicit `--delete-files` request.

Hub copies enabled checkpoints into independent storage, so deleting the
producing job (`jobs delete`) retains its enabled weights, including shared
ones. These storage semantics and file removal require a Hub containing
[hub#3142](https://github.com/apheris/hub/pull/3142). Older Hubs may ignore the
file-removal request; upgrade Hub before using this option.
`--dry-run true` previews `update` and `delete` after reading the current
record. The delete preview includes `deleteFiles`; it does not check active
jobs or remove files.

Use a CLI release that supports `weights enable --name`. Upgrade if this
command is unavailable; adding `--description` does not replace the required
weight name.

Some workflows accept checkpoint files directly. Read the active workflow's
skill before enabling weights: `affinity-predict-from-embeddings` documents uploading
the selected affinity-head checkpoint as `checkpoint.ckpt` alongside
`test_queries.yaml` (or JSON), referenced MSAs and optional labels. That route
does not require enabling weights in the catalog or `--weight`. Its `of3Checkpoint` parameter
selects the separate OpenFold3 trunk, not the affinity head. Report prediction
submission/completion separately from weight registration.

Workflow skill responses may include shared presentation skills. Installation
validates their content digests and installs them alongside the workflow skill;
`--all` deduplicates equal versions and rejects conflicting ones. The shared
source lives in foundry-cli and travels through Hub, not in this Python package.

The optional skill `resources` field currently carries only `vocabulary.json`.
The CLI checks its name, UTF-8 byte limit, SHA-256 and JSON syntax before writing
it beside the workflow SKILL.md. A malformed resource prevents installation.
Older Hubs omit resources; updated AQCell skills state that preflight vocabulary
is then unavailable rather than claiming membership was checked.

### Public compound resolution (no Hub required)

```sh
apheris-foundry tools compounds resolve --name gemcitabine --json
apheris-foundry tools compounds resolve --cid 60750 --json
apheris-foundry tools compounds resolve --cid 60750 --offline --json
```

Resolves exact PubChem records with isomeric SMILES, InChIKey, source and timestamp.
Only public names/CIDs should be sent; supplied proprietary structures need no public lookup.
Ambiguous matches stop for clarification. No automatic parent/salt substitution.
Responses are cached locally for 30 days; offline use marks stale entries. Use
`--refresh` for fresh evidence or `--cache-dir` to isolate a project cache.
The shared chemical-identity and foundry-scientific-integrity skills also work
without Hub through documented official APIs.

`jobs download` preserves the workflow's `result.json`; the CLI's download
manifest is `cli-result.json`. A conflicting artifact with that name is rejected
rather than overwritten. `--result-view` controls that CLI manifest's detail.

### Querying jobs

Find jobs by name, ID, or tag:

```sh
apheris-foundry jobs list --search 'screen_1'
apheris-foundry jobs list --workflow predict --status succeeded --limit 10
```

Search is literal (no wildcards). Workflow and status filters can be repeated.
The default shows up to 30 jobs; use `--limit -1` only when you need all matches.
Add `--json` for scripts: `total` counts all matches, and `incomplete` indicates
that fewer rows were returned.

See [the usage guide](docs/usage.md#find-jobs)
for model, date, duration, and sorting options, which are hidden from default help.
