Metadata-Version: 2.4
Name: trident_api
Version: 1.1.0
Summary: A client library to connect with the Trident API for Pontus-X or EDC.
Project-URL: source, https://git.ift.tuwien.ac.at/lab/pub/pypi/trident-client
Author-email: Thomas Trautner <thomas.f.trautner@tuwien.ac.at>
License: MIT
License-File: LICENSE
Keywords: edc,pontus-x,trident
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: coloredlogs>=15.0.1
Requires-Dist: docker>=7.1.0
Requires-Dist: h5py>=3.0.0
Requires-Dist: jsonargparse>=4.42
Requires-Dist: python-dotenv>=0.9.9
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.33.1
Requires-Dist: rich>=15.0.0
Requires-Dist: tabulate>=0.10.0
Requires-Dist: typer[all]>=0.12.5
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: responses>=0.25.0; extra == 'dev'
Description-Content-Type: text/markdown

# Trident Client v1.1.0

This is a client library and CLI for the Trident service, focusing on asset management and Ocean Protocol (Nautilus) integration.

To configure your credentials, create a `.env` file containing:

```sh
TRIDENT_SERVICE='https://your-trident-instance/v1'
TRIDENT_USERNAME='your_username'
TRIDENT_PASSWORD='your_password'
```

## Features

- **Master Data Management**: Manage participants, templates, trust lists, algorithm lists, datatokens, and Docker images.
- **Service & Asset Management**: Define datasets or compute services, upload/download files, and sync folders.
- **Offering Lifecycle**: Create, publish, revoke, and delete offerings.
- **Ocean Protocol Integration**: Publish assets to the Ocean market and run decentralized compute jobs.
- **Modern CLI**: Logical command structure with automatic authentication and token refresh.

## Python Library Usage

You can also use the library programmatically in Python:

```python
from trident_api.client import TridentClient

# 1. Initialize the client
client = TridentClient(
    service="https://your-trident-instance/v1",
    username="your_username",
    password="your_password"
)

# 2. Upload a file
res = client.management.upload_file("milling.hdf5", name="Milling Experiment A")
if res.ok:
    file_id = res.json()["id"]
    print(f"File uploaded successfully! ID: {file_id}")

# 3. Create a service
service_data = {
    "name": "My Python Service",
    "type": "dataset",
    "file_id": file_id
}
service_res = client.management.create_service(service_data)
if service_res.ok:
    service_id = service_res.json()["id"]
    print(f"Service created! ID: {service_id}")

# 4. Trigger compute job via Nautilus
compute_res = client.nautilus.compute(
    asset_did="did:op:dataset-did-here",
    algorithm_did="did:op:algorithm-did-here"
)
if compute_res.ok:
    job_id = compute_res.json()["jobId"]
    print(f"Compute job started! Job ID: {job_id}")
```

## Resource Provisioning

The `trident-cli system provision` command allows you to idempotently provision entire dataspaces across multiple target servers using a single YAML configuration file.

### Command Usage
```sh
trident-cli system provision --config provisioning.yaml
```

### Config File Format (`provisioning.yaml`)

Here is an example configuration file outlining the structure:

```yaml
# 1. Global Datatokens
datatokens:
  - name: "Data Token"
    symbol: "DT"

# 2. Global Docker Images used for Compute
docker_images:
  - name: "ttrau/datascience-base"
    tag: "3.13.2-slim"
    checksum: "auto" # or specific SHA256 hash
    description: "Standard datascience execution base"
    entrypoint: "python3"

# 3. Global Trust Lists
trustlists:
  - name: "Core Trustlist"
    participants:
      - tuwien
      - ptw

# 4. Global Templates
templates:
  - name: "Default System Template"
    file: "templates/default.md" # Path to local Markdown template file

# 5. Participants & Target Server Configuration
participants:
  tuwien:
    identity:
      org: "TU Wien"
      wallet: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd"
    server:
      url: "https://ift-trident.example.com/v1"
      username: "ift-trident-user"
      password: "another-encrypted-password-or-token"
  ptw:
    identity:
      org: "PTW Darmstadt"
      wallet: "0x1234567890123456789012345678901234567890"
    server:
      url: "https://ptw-trident.example.com/v1"
      username: "ptw-trident-user"
      password: "some-encrypted-password-or-token"
    trustlists:
      - "CIRP Core Trustlist"
```

## CLI Usage

The CLI is organized into the following command groups:

### 1. System (`system`)
Manage login state and provision resources.
```sh
# Check if the Trident server is healthy
trident-cli system health

# Login and cache credentials locally (~/.trident/credentials)
trident-cli system login --service <url> --username <user> --password <pass>

# Clear cached credentials
trident-cli system logout

# Show active user info
trident-cli system user

# Provision resources defined in a YAML configuration file
trident-cli system provision --config provisioning.yaml
```

### 2. Master Data (`masterdata`)
Manage baseline dataspace participants, templates, trust lists, datatokens, and policies.
```sh
# Participants
trident-cli masterdata participants list
trident-cli masterdata participants create --tag "tag" --name "Name" --description "Desc"
trident-cli masterdata participants ensure --tag "tag" --name "Name"
trident-cli masterdata participants delete <id>

# Templates
trident-cli masterdata templates list
trident-cli masterdata templates create --name "Template A" --file template.md
trident-cli masterdata templates ensure --name "Template A" --file template.md

# Trust Lists
trident-cli masterdata trust-lists list
trident-cli masterdata trust-lists create --name "Trust List Name"
trident-cli masterdata trust-lists ensure --name "Trust List Name"

# Algorithm Lists
trident-cli masterdata algorithm-lists list

# Datatokens
trident-cli masterdata datatokens list

# Docker Images
trident-cli masterdata docker-images list

# Automation Rules
trident-cli masterdata automation list
```

### 3. Services (`services`)
Manage technical services (datasets/algorithms) that can be packaged into offerings.
```sh
# List all services
trident-cli services list

# Show detailed service metadata
trident-cli services show <id>

# Create a service (dataset or algorithm type)
trident-cli services create --name "My Service" --type "dataset" --file-id 1

# Ensure a service exists (Idempotent)
trident-cli services ensure --name "My Service" --type "dataset" --file-id 1

# Delete a service
trident-cli services delete <id>
```

### 4. Files (`files`)
Manage raw files uploaded to storage.
```sh
# List files currently available in Trident
trident-cli files list

# Show details of a specific file entry
trident-cli files show <id>

# Upload a local file to Trident storage
trident-cli files upload ./milling.hdf5 --name "Milling Experiment A"

# Download a file from Trident storage
trident-cli files download --bucket my-bucket --filepath path/to/file.hdf5

# Preview metadata extraction for a local file (e.g. HDF5)
trident-cli files inspect path/to/file.hdf5

# Sync a local directory to Trident
trident-cli files sync --folder ./data/my_archive --recursive

# Delete a file entry
trident-cli files delete <id>
```

### 5. Offerings (`offerings`)
Manage business contracts / terms of usage.
```sh
# List all offerings
trident-cli offerings list

# Show details of an offering
trident-cli offerings show <id>

# Create an offering
trident-cli offerings create --name "My Offering" --service-id 1 --type access

# Publish offering to Ocean Protocol (Aquarius)
trident-cli offerings publish <id>

# Revoke an active offering
trident-cli offerings revoke <id>

# Delete an offering
trident-cli offerings delete <id>
```

### 6. Dataspace Operations (`dataspace`)
Interact directly with published assets in the dataspace (Ocean Protocol/Aquarius catalogue).
```sh
# List assets published in the dataspace catalogue
trident-cli dataspace list --query '{"metadata.type": "dataset"}'

# Access / download a published asset by its DID
trident-cli dataspace access did:op:example-did-string

# Publish an asset via Nautilus (Ocean Protocol) using a metadata JSON file
trident-cli dataspace publish --file algorithm.json

# Delete an asset from the dataspace catalogue by its DID
trident-cli dataspace delete did:op:example-did-string
```

#### Dataspace Compute Jobs (`dataspace compute`)
Execute and monitor compute jobs on assets.
```sh
# Start a compute job
trident-cli dataspace compute start --asset-did did:op:dataset-did --algorithm-did did:op:algo-did --wait

# Check status of a compute job
trident-cli dataspace compute status <job_id>
```

## Quickstart (Development & Testing)

### Setup
First, create a virtual environment and install the package:

```sh
make create
source .venv/bin/activate
pip install -r requirements.txt
```

### Running from Source
To execute the CLI directly from source:
```sh
PYTHONPATH=src python3 src/trident_api/typer_cli.py system health
```

### Testing
```sh
make test
```
