Metadata-Version: 2.4
Name: apheris-foundry-cli
Version: 0.8.0rc1
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: jsonschema<5,>=4
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.

## 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. Use `skills list --offline` for bundled skills without a Hub
connection. 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

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
```

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 and streamed unchanged; pass a ZIP alone.
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 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 \
  --param model=<model-id> --weight <weight-version> \
  --model-params @./model-params.json
```

For optional templates, see the [template prediction example](examples/smoke/templates/README.md).
For other workflows and model overrides, see [Using the CLI](docs/usage.md).

## 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>` | List models, weights, and default prediction parameters 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>] [--model-params <JSON\|@file>]` | Submit a workflow run with Hub-schema-validated model parameters |

### Run instances (`runs`)

| Command | Description |
| ------- | ----------- |
| `apheris-foundry jobs list [--workflow <id>]` | List submitted jobs |
| `apheris-foundry jobs get --id <job-id>` | Inspect a job and its artifacts |
| `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 one JSON object. Use an inline object for short overrides, or prefix a JSON 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.

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