trident-api 1.1.0

A client library to connect with the Trident API for Pontus-X or EDC.

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:

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:

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

trident-cli system provision --config provisioning.yaml

Config File Format (provisioning.yaml)

Here is an example configuration file outlining the structure:

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

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

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

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

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

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

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

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

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

Running from Source

To execute the CLI directly from source:

PYTHONPATH=src python3 src/trident_api/typer_cli.py system health

Testing

make test