Remote Agent class

class starfish.agent.RemoteAgent(ddo: starfish.network.ddo.DDO, authentication: Optional[starfish.agent.authentication.authentication.Authentication] = None, http_client: Optional[Any] = None)

Bases: starfish.agent.agent_base.AgentBase, Generic[starfish.types.RemoteAgent]

Remote Agent class allows to register, list, purchase and consume assets.

Parameters

  • ddo – Optional ddo of the remote agent, if not provided the agent will automatically get the DDO from the network based on the DID.

  • authentication (dict) –

    authentication is a authentication object with a username/password or a token a remote agent. Currently the following values are supported:

    AuthenticationBasic AuthenticationToken

property adapter
add_collection_items(name, asset_list)
property authentication
consume_asset(listing: Any, account: Any, purchase_id: str) → bool

Consume the asset and download the data. The actual payment to the asset provider will be made at this point.

Parameters

  • listing (Listing) – Listing that was used to make the purchase.

  • purchase_id (str) – purchase id that was used to purchase the asset.

  • account (Account object to use for registration.) – Ocean account that was used to purchase the asset.

  • download_path (str) – path to store the asset data.

Returns

True if the asset has been consumed and downloaded

Type

boolean

create_listing(listing_data: starfish.types.ListingData, asset_did: str) → starfish.listing.listing.Listing

Create a listing on the market place for this asset

Parameters

  • listing_data (dict) – Listing inforamiton to give for this asset

  • asset_did (str) – asset DID to assign to this listing

Returns

A new Listing object that has been registered, if failure then return None.

Type

Listing class

For example:

asset = DataAsset.create('test data asset', 'Some test data')
agent = SurferAgent()
asset = agent.register_asset(asset, account)

listing_data = { 'price': 3.457, 'description': 'my data is for sale' }
listing = agent.create_listing(listing_data, asset)
if listing:
    print(f'registered my listing asset for sale with the did {listing.did}')
property ddo: starfish.network.ddo.DDO

Return the registered DDO for this agent

Returns

DDO registered for this agent

Type

DDO

download_asset(asset_did_id: str) → starfish.types.Asset

Download an asset

Parameters

asset_did_id (str) – Asset id or asset did to download

Returns

an Asset

Type

DataAsset class

find_asset(filter_values: dict) → List[str]

Search the metadata list for assets that match the filter dict provided.

:param dict filter Metadata filter to match for any found assets. :return a list of asset dids that match the filter

static find_supported_service_type(search_name_type: str) → Any

return the supported service record if the name or service type is found else return None

get_asset(asset_did_id: str) → starfish.types.Asset

This is for compatability for Surfer calls to get an asset directly from Surfer

Parameters

asset_did_id (str) – Asset DID or asset Id of the asset to read or did/asset_id

Returns

an asset class

Type

AssetBase class

get_asset_purchase_ids(asset: Any) → Any

Returns as list of purchase id’s that have been used for this asset

Parameters

asset (Asset object) – Asset to return purchase details.

Returns

list of purchase ids

Type

list

get_authorization_token() → str
get_collection_items(name=None)
get_endpoint(name: str, uri: Optional[str] = None) → str

return the endpoint based on the name of the service or service type

get_job(job_id: str) → starfish.job.job.Job

Get a job from the invoke service ( koi )

Parameters

job_id (str) – Id of the job to get

Returns

a job class

Type

starfish.job.Job class

get_listing(listing_id: str) → starfish.listing.listing.Listing

Return an listing on the listings id.

Parameters

listing_id (str) – Id of the listing.

Returns

a listing object

Type

Asset class

get_listings() → List[starfish.types.ListingData]

Returns all listings

Returns

List of listing objects

get_metadata_list() → Any

Return the list of asset metadata items

property http_client
invoke()

Call an operation asset with inputs to execute a remote call.

Parameters

  • asset (OperationAsset) – Operation asset to use for this invoke call

  • inputs (dict) – Inputs to send to the invoke call

Returns

Return a dict of the result.

Type

dict

is_access_granted_for_asset(asset: Any, account: Any, purchase_id: Optional[str] = None) → bool

Check to see if the account and purchase_id have access to the assed data.

Parameters

  • asset (Asset object) – Asset to check for access.

  • account (Account object to use for registration.) – Ocean account to purchase the asset.

  • purchase_id (str) – purchase id that was used to purchase the asset.

Returns

True if the asset can be accessed and consumed.

Type

boolean

static is_did_valid(did: str) → bool

Checks to see if the DID string is a valid DID for this type of address for an asset. This method only checks the syntax of the DID, it does not resolve the DID to see if it is assigned to a valid Asset.

Parameters

did (str) – DID string to check to see if it is in a valid format.

Returns

True if the DID is in the format ‘did:dep:xxxxx/yyyy’

Type

boolean

static is_metadata_match(filter_values: dict, metadata: dict) → bool
is_service(name)
job_wait_for_completion(job_id: str, timeout_seconds: int = 60, sleep_seconds: int = 1) → Union[starfish.job.job.Job, bool]

Wait for a job to complete, with optional timeout seconds.

Parameters

  • job_id (int) – Job id to wait for completion

  • timeout_seconds (int) – optional time in seconds to wait for job to complete, defaults to 60 seconds

  • sleep_seconds (int) – optional number of seconds to sleep between polling the job status, == 0 no sleeping

Returns

Job object if finished, else False for timed out

Type

starfish.job.Job class or False

static load(agent_did_or_url: str, network: Optional[starfish.network.network_base.NetworkBase] = None, authentication: Optional[starfish.agent.authentication.authentication.Authentication] = None, http_client: Optional[Any] = None) → starfish.types.RemoteAgent

Load a remote agent using a did/url. The Agent must have a DDO service available. If a DID is passed you also need to provide a network object to resolve the did For the RemoteAgent object to resolve the type of services available.

:param str agent_did_or_url DID or URL of the agent to load. :param Authentiaciton authentication Optional Authenentication object to use to access the new agent. :param http_client: HTTP Client libray to use to make requests, this defaults to requests library.

Returns

A RemoteAgent Object or None if the agent cannot be accessed or cannot be found at the url.

purchase_asset(listing: Any, AccountBase: Any, purchase_id: Optional[str] = None, status: Optional[str] = None, info: Optional[Any] = None, agreement: Optional[Any] = None) → bool

Purchase an asset using it’s listing and an account.

Parameters

  • listing (Listing) – Listing to use for the purchase.

  • account (Account object to use for registration.) – Ocean account to purchase the asset.

  • purchase_id (str or None) – purchase id (optional)

  • status (str or None) – purchase status (optional)

  • info (dict or None) – purchase info (optional)

  • agreement (dict or None) – purchase agreement (optional)

purchase_wait_for_completion(asset: Any, account: Any, purchase_id: str, timeoutSeconds: int) → bool

Wait for completion of the purchase

TODO: issues here… + No method as yet to pass back paramaters and values during the purchase process + We assume that the following templates below will always be used.

static register(network: starfish.network.network_base.NetworkBase, register_account: starfish.network.account_base.AccountBase, ddo: starfish.network.ddo.DDO, authentication: Optional[starfish.agent.authentication.authentication.Authentication] = None, http_client: Optional[Any] = None) → starfish.types.RemoteAgent

Register the agent on the network.

Parameters

  • network – Network to use to register on the block chain

  • register_account – Account object to use to register the agent ddo

  • ddo – DDO object to use to register on the network

  • authentication – Authentication data needed to access this agent

  • http_client – HTTP Client libray to use to make requests, this defaults to requests library.

Returns

RemoteAgent object that has been registered on the network

register_asset(asset: starfish.types.Asset, create_provenance: bool = False) → starfish.types.Asset

Register an asset with Surfer

Parameters

  • asset (DataAsset object to register) – asset object to register

  • create_provenance (bool) – If set to True, then set the provenance metadata for this asset

Returns

A AssetBase object that has been registered, if failure then return None.

Type

AssetBase class

For example:

asset = DataAsset.create('test data asset', 'Some test data')
listing_data = { 'price': 3.457, 'description': 'my data is for sale' }
agent = SurferAgent(ddo)
asset = agent.register_asset(asset, True)
print(f'Asset DID is {asset.did}')
remove_collection_items(name, asset_list)
static resolve_url(url: str, authentication: Optional[starfish.agent.authentication.authentication.Authentication] = None, http_client: Optional[Any] = None) → starfish.network.ddo.DDO

Resolves the remote agent ddo using the url of the agent

Parameters

  • url (str) – url of the remote agent

  • Authenentication – Optional authentication object to access the agent

  • http_client – HTTP Client libray to use to make requests, this defaults to requests library.

Return dict

DDO or None if not found

search_listings(text: str, sort: Optional[Any] = None, offset: int = 100, page: int = 0) → List[starfish.types.ListingData]

Search the off chain storage for an asset with the givien ‘text’

Parameters

  • text (str) – Test to search all metadata items for.

  • sort (str or None) – sort the results ( defaults: None, no sort).

  • offset (int) – Return the result from with the maximum record count ( defaults: 100 ).

  • page (int) – Returns the page number based on the offset.

Returns

a list of assets objects found using the search.

Type

list of DID strings

For example:

# return the 300 -> 399 records in the search for the text 'weather' in the metadata.
my_result = agent.search_registered_assets('weather', None, 100, 3)
service_types = {'auth': 'DEP.Auth.v1', 'collection': 'DEP.Collection.v1', 'invoke': 'DEP.Invoke.v1', 'market': 'DEP.Market.v1', 'meta': 'DEP.Meta.v1', 'storage': 'DEP.Storage.v1', 'trust': 'DEP.Trust.v1'}
update_listing(listing: starfish.listing.listing.Listing) → bool

Update the listing to the agent server.

Parameters

listing (Listing class) – Listing object to update

upload_asset(asset: starfish.types.Asset) → bool
validate_asset(asset: starfish.types.Asset) → bool

Validate an asset

Parameters

asset – Asset to validate.

Returns

True if the asset is valid