Metadata-Version: 2.4
Name: apherisfold-cli
Version: 0.3.1
Summary: Prototype ApherisFold CLI for Hub-backed customer demos.
Author: Apheris
License-Expression: LicenseRef-Apheris-Foundry-Software-License
Project-URL: License, https://www.apheris.com/docs/hub/hub-license.html
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema<5,>=4
Requires-Dist: rich>=13
Requires-Dist: truststore<1,>=0.10
Requires-Dist: typer<1,>=0.12
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.9; extra == "dev"
Dynamic: license-file

# ApherisFold CLI

Command-line interface for submitting and managing prediction, benchmark, and fine-tuning workflows 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 apherisfold python=3.11 -y
conda activate apherisfold
pip install apherisfold-cli
```

#### Windows (Anaconda Prompt or PowerShell)

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

Activate the environment at the start of each session with `conda activate apherisfold`.

### venv (standard Python)

#### Linux / macOS (venv)

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

#### Windows (PowerShell, venv)

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

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

### Verify

```bash
apherisfold --version
apherisfold --help
```

### Upgrade

```bash
pip install --upgrade apherisfold-cli
```

## Quick start

```bash
# Log in with your ApherisFold Hub URL
apherisfold login --url https://hub.example.com

# See available models and weights
apherisfold weights list

# Submit a prediction
apherisfold workflow predict run \
  --model openfold3 \
  --weight 3.0.0 \
  --input ./request.json

# By default, local artifacts are written under ./.apherisfold/runs/<workflow>/<id>
# relative to the directory where you run the command. Use --output to choose another directory.

# List submitted jobs
apherisfold workflow predict list

# Inspect a job
apherisfold workflow predict get --id job_NUlyMsnWq

# Print diagnostics, or save them under ./.apherisfold/runs/predict/<job-id>/logs
apherisfold workflow predict logs --id job_NUlyMsnWq
apherisfold workflow predict logs --id job_NUlyMsnWq --save
apherisfold workflow predict error --id job_NUlyMsnWq --output ./diagnostics
```

## Workflows

| Workflow             | Entry point                                   |
| -------------------- | --------------------------------------------- |
| Structure prediction | `apherisfold workflow predict run`            |
| Benchmarking         | `apherisfold workflow benchmark run`          |
| Fine-tuning          | `apherisfold workflow fine-tune prepare`      |

### Affinity prediction

When using weights that support affinity prediction, the CLI selects the ligand chain automatically if there is only one. For queries with multiple ligand chains, specify which one to score with `--affinity-ligand`:

```bash
apherisfold workflow predict run \
  --model openfold3 \
  --weight 3.0.0 \
  --input ./request.json \
  --affinity-ligand B
```

### Supplying MSAs

Pass precomputed alignments with `--asset`. A3Ms are matched to structure chains **by
sequence** (an `X` in the MSA sequence acts as a wildcard), so filenames need not match the
structure. Supply one A3M per chain — a single A3M matching several identical chains (for
example a homomultimer) is applied to all of them. Chains without a supplied match fall back
to automatic MSA generation, and the CLI warns which chains that affects.

```bash
# One A3M per chain, matched by sequence
apherisfold workflow predict run \
  --model openfold3 --weight 3.0.0 \
  --input ./complex.cif \
  --asset ./chain-A.a3m --asset ./chain-B.a3m
```

To disambiguate which structure an A3M belongs to, scope it with a `structureId=` prefix
(`queryId=` for predict). This narrows the candidate chains to that one structure:

```bash
apherisfold workflow benchmark run \
  --model openfold3 --weight 3.0.0 --name eval \
  --input ./structures/ \
  --asset alpha=./alpha-chain-A.a3m \
  --asset alpha=./alpha-chain-B.a3m
```

Resolved MSA-to-chain mappings are recorded in the run's `result.json`; benchmark runs also
print the mapping before submission.

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

```bash
apherisfold workflow predict run --help
apherisfold workflow benchmark run --help
apherisfold workflow fine-tune prepare --help
```

## 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.
