Example usage¶

To use aiod in a project:

In [1]:

import aiod

import aiod

Loading metadata collections¶

We can then browse assets by type. This gives metadata for each asset such as a name and description, as well as where the original item can be found:

In [2]:

datasets = aiod.datasets.get_list(limit=2)
datasets[["identifier", "platform", "platform_resource_identifier", "name", "date_published"]]

datasets = aiod.datasets.get_list(limit=2) datasets[["identifier", "platform", "platform_resource_identifier", "name", "date_published"]]

Out[2]:

	identifier	platform	platform_resource_identifier	name	date_published
0	data_0000003G7ndn66DnJD6t8zXi	zenodo	zenodo.org:8060401	Regional estimates of gross primary production...	2023-06-20T00:00:00
1	data_0000028aWpbVkClCizqCTkMW	zenodo	zenodo.org:3949849	Becoming LTi - Dataset : Reference files and S...	2020-07-17T00:00:00

In [3]:

datasets = aiod.educational_resources.get_list(offset=10, limit=2)
datasets[["identifier", "platform", "platform_resource_identifier", "name"]]

datasets = aiod.educational_resources.get_list(offset=10, limit=2) datasets[["identifier", "platform", "platform_resource_identifier", "name"]]

Out[3]:

	identifier	platform	platform_resource_identifier	name
0	edu_27VBOR1oySNUJ5VFk1p61p3n	adra_e	543	Could Artificial Intelligence Beat Mozart At H...
1	edu_2PuIm2q73vTZQSzb1IQFvwuj	adra_e	109	Algorithmic Impact Assessment tool

Metadata for specific assets¶

You can request individual assets. Either as JSON or Pandas:

In [4]:

resource = aiod.educational_resources.get_asset(identifier="edu_27VBOR1oySNUJ5VFk1p61p3n")
resource["description"]

resource = aiod.educational_resources.get_asset(identifier="edu_27VBOR1oySNUJ5VFk1p61p3n") resource["description"]

Out[4]:

{'html': 'TEDx talk on challenges of AI in creating music'}

In [5]:

resource = aiod.educational_resources.get_asset(identifier="edu_27VBOR1oySNUJ5VFk1p61p3n", data_format="json")
resource

resource = aiod.educational_resources.get_asset(identifier="edu_27VBOR1oySNUJ5VFk1p61p3n", data_format="json") resource

Out[5]:

{'platform': 'adra_e',
 'platform_resource_identifier': '543',
 'name': 'Could Artificial Intelligence Beat Mozart At His Own Game?',
 'same_as': 'https://adra-e.eu',
 'access_mode': [],
 'ai_resource_identifier': 'edu_27VBOR1oySNUJ5VFk1p61p3n',
 'aiod_entry': {'editor': [],
  'status': 'published',
  'date_modified': '2025-02-13T10:48:50',
  'date_created': '2025-02-13T10:48:50'},
 'alternate_name': [],
 'application_area': [],
 'contact': [],
 'creator': [],
 'description': {'html': 'TEDx talk on challenges of AI in creating music'},
 'educational_level': [],
 'has_part': [],
 'in_language': [],
 'industrial_sector': [],
 'is_part_of': [],
 'keyword': [],
 'location': [],
 'media': [],
 'note': [],
 'prerequisite': [],
 'relevant_link': [],
 'relevant_resource': [],
 'relevant_to': [],
 'research_area': ['other materials'],
 'scientific_domain': [],
 'target_audience': ['teachers in secondary school'],
 'type': 'video recordings',
 'identifier': 'edu_27VBOR1oySNUJ5VFk1p61p3n'}

Managing your own metadata¶

You can manage your own metadata, though you will need an AIoD account. If you are not authenticated, you will receive an error:

In [8]:

aiod.persons.register(metadata=dict(first_name="Arthur", last_name="Dent"))

aiod.persons.register(metadata=dict(first_name="Arthur", last_name="Dent"))

---------------------------------------------------------------------------
NotAuthenticatedError                     Traceback (most recent call last)
Cell In[8], line 1
----> 1 aiod.persons.register(metadata=dict(first_name="Arthur", last_name="Dent"))

File ~/repositories/aiod-py-sdk/src/aiod/calls/calls.py:129, in post_asset(asset_type, metadata, version)
    115 """
    116 Register ASSET_TYPE in catalogue.
    117 
   (...)    126     requests.Response: error response, if it failed to register successfully
    127 """
    128 url = url_to_post_asset(asset_type, version)
--> 129 res = requests.post(url, headers=get_token().headers, json=metadata)
    130 if res.status_code == HTTPStatus.OK:
    131     return res.json()["identifier"]

File ~/repositories/aiod-py-sdk/src/aiod/authentication/authentication.py:151, in get_token()
    146 if _token is None:
    147     msg = (
    148         "No token set. Please create a new token with `aiod.create_token()`,"
    149         " or set one with `aiod.set_token('...')`."
    150     )
--> 151     raise NotAuthenticatedError(msg)
    152 return _token

NotAuthenticatedError: No token set. Please create a new token with `aiod.create_token()`, or set one with `aiod.set_token('...')`.

Authentication¶

To register, update, or delete metadata of your own assets you must first authenticate with the server. You can get a new token by using the create_token function, and if you specify write_to_file=True this token will be stored to a file (~/.aiod/token.toml) and automatically loaded next time you import aiod.

The create_token function prints instructions to the console/notebook: navigate to the website and log in. After logging in, you can return here and the token will be loaded.

In [10]:

aiod.config.auth_server = 'http://localhost/aiod-auth/'
aiod.config.api_server = 'http://localhost/'

aiod.config.auth_server = 'http://localhost/aiod-auth/' aiod.config.api_server = 'http://localhost/'

In [11]:

aiod.create_token(write_to_file=True)

aiod.create_token(write_to_file=True)

Please authenticate using one of two methods:

  1. Navigate to http://localhost/aiod-auth/realms/aiod/device?user_code=GCUX-QDQI
  2. Navigate to http://localhost/aiod-auth/realms/aiod/device and enter code GCUX-QDQI

This workflow will automatically abort after 300 seconds.

Out[11]:

<aiod.authentication.authentication.Token at 0x121ffb910>

If you ever accidentally share your personal token with someone, you can invalidate it to make sure others can not use it (comment out the code):

In [ ]:

# aiod.invalidate_token()

# aiod.invalidate_token()

Registering a resource¶

After authenticating, you can start registering resources at AI on Demand. For example, you can add metadata about yourself (see the REST API documentation for the full schema):

In [12]:

identifier = aiod.persons.register(metadata=dict(
    name="Arthur Dent", 
    relevant_link=["https://www.linkedin.com/arthur_dent", "https://en.wikipedia.org/wiki/Arthur_Dent"],
))
print(f"Your person entry has identifier {identifier}")

identifier = aiod.persons.register(metadata=dict( name="Arthur Dent", relevant_link=["https://www.linkedin.com/arthur_dent", "https://en.wikipedia.org/wiki/Arthur_Dent"], )) print(f"Your person entry has identifier {identifier}")

Your person entry has identifier prsn_UDBAHoMErgMwUo6z0hqeuLUl

The identifier is important. You will need it if you want to retrieve, update, or delete the entry.

In [13]:

aiod.persons.get_asset(identifier)

aiod.persons.get_asset(identifier)

Out[13]:

platform                                                                     aiod
platform_resource_identifier                        prsn_UDBAHoMErgMwUo6z0hqeuLUl
name                                                                  Arthur Dent
wants_to_be_contacted                                                       False
agent_identifier                                    prsn_UDBAHoMErgMwUo6z0hqeuLUl
ai_resource_identifier                              prsn_UDBAHoMErgMwUo6z0hqeuLUl
aiod_entry                      {'editor': [], 'status': 'draft', 'date_modifi...
alternate_name                                                                 []
application_area                                                               []
contact                                                                        []
contacts                                                                       []
creator                                                                        []
expertise                                                                      []
has_part                                                                       []
industrial_sector                                                              []
is_part_of                                                                     []
keyword                                                                        []
languages                                                                      []
media                                                                          []
member_of                                                                      []
note                                                                           []
relevant_link                   [https://en.wikipedia.org/wiki/arthur_dent, ht...
relevant_resource                                                              []
relevant_to                                                                    []
research_area                                                                  []
scientific_domain                                                              []
identifier                                          prsn_UDBAHoMErgMwUo6z0hqeuLUl
dtype: object

Updating or deleting an entry¶

In [ ]:

aiod.persons.update(
    identifier=identifier, 
    metadata=dict(description=dict(plain="A fictional character from the Hitchhiker's Guide to the Galaxy.")),
)

aiod.persons.update( identifier=identifier, metadata=dict(description=dict(plain="A fictional character from the Hitchhiker's Guide to the Galaxy.")), )

In [17]:

aiod.persons.delete(identifier=identifier)

aiod.persons.delete(identifier=identifier)

Out[17]:

<Response [200]>

Async methods¶

In [14]:

data = await aiod.datasets.get_list_async(offset=300, limit=5, batch_size=3)
data[["platform", "name", "identifier", "is_accessible_for_free"]]

data = await aiod.datasets.get_list_async(offset=300, limit=5, batch_size=3) data[["platform", "name", "identifier", "is_accessible_for_free"]]

Out[14]:

	platform	name	identifier	is_accessible_for_free
0	huggingface	Unso/ted2020_pairs_en_x	data_2GZENA39AwYP1kbyEGuQD8Mu	True
1	huggingface	sijunhe/thchs30	data_2h4ItF9q0Xcxi09UhX62i43j	True
2	huggingface	biu-nlp/qa_srl2018	data_2H9aO2nseNNX4nU44GAydXAm	True
3	huggingface	Nexdata/American_English_Speech_Synthesis_Corp...	data_2hd6QNsjXCfyzYVL8zfqWDEF	True
4	huggingface	rubrix/go_emotions_multi-label	data_2hJyqBcJHlnjC5FuEYspv1QD	True