Metadata-Version: 2.4
Name: apheris-foundry-cli
Version: 0.3.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: 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
```

## Quick start

```bash
# Log in with your Apheris Hub URL
apheris-foundry login --url https://hub.example.com

# See available workflow definitions
apheris-foundry workflows list

# Submit a run
apheris-foundry workflows run --workflow predict --input ./request.json

# Inspect the model IDs, weights, and default parameters advertised by Hub
apheris-foundry workflows models --workflow predict

# Override prediction parameters with a Hub-schema-validated JSON object
apheris-foundry workflows run --workflow predict --input ./request.json \
  --model-params '{"seeds":[7,9],"num_diffusion_samples":3}'

# Or provide the same JSON object from a file
apheris-foundry workflows run --workflow predict --input ./request.json \
  --model-params @./model-params.json

# Select a non-default model/weight advertised by the workflow
apheris-foundry workflows run --workflow predict --input ./request.json \
  --param model=<model-id> --weight <weight-version> \
  --model-params @./model-params.json

# List submitted runs
apheris-foundry jobs list

# Filter by workflow
apheris-foundry jobs list --workflow predict

# Inspect a run
apheris-foundry jobs get --id <job-id>

# Stream logs
apheris-foundry jobs logs --id <job-id>

# Download results
apheris-foundry jobs download --id <job-id>

# Print the error for a failed run
apheris-foundry jobs error --id <job-id>
```

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

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

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

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