2. Create KItems with the SDK

In this tutorial we see how to create new Kitems.

2.1. Setting up

Before you run this tutorial: make sure to have access to a DSMS-instance of your interest, alongwith with installation of this package and have establised access to the DSMS through DSMS-SDK (refer to Connecting to DSMS)

Now let us import the needed classes and functions for this tutorial.

from dsms import DSMS, KItem

Now source the environmental variables from an .env file and start the DSMS-session.

dsms = DSMS(env=".env")

2.2: Create KItems

We can make new KItems by simple class-initiation: (Make sure existing KItems are not given as input). #

item = KItem(
    name="Specimen123",
    ktype_id=dsms.ktypes.Specimen,
    custom_properties = {
        "Width": 0.5,
        "Length": [0.1, 0.2],
    }
)

item

/app/dsms/knowledge/kitem.py:477: UserWarning: A flat dictionary was provided for custom properties.
                    Will be transformed into `KItemCustomPropertiesModel`.
  warnings.warn(

kitem:
  name: Specimen123
  ktype_id: specimen
  custom_properties:
    content:
      sections:
      - id: id0595fb5f1853a8
        name: Untitled Section
        entries:
        - id: idba92210e193128
          type: Number
          label: Width
          value: 0.5
          measurementUnit:
            iri: http://qudt.org/vocab/unit/MilliM
            label: Millimetre
            symbol: null
            namespace: http://qudt.org/vocab/unit
          relationMapping: null
          required: false
        - id: ida08bcc9977e388
          type: Slider
          label: Length
          value:
          - 0.1
          - 0.2
          measurementUnit:
            iri: http://qudt.org/vocab/unit/MilliM
            label: Millimetre
            symbol: null
            namespace: http://qudt.org/vocab/unit
          relationMapping: null
          required: false

Remember: changes are only syncronized with the DSMS when you call the commit-method:

dsms.add(item)
dsms.commit()
item.url

'https://bue.materials-data.space/knowledge/specimen/specimen123-8a7f158b'

As we can see, the object we created before running the commit-method has automatically been updated, e.g. with the creation- and update-timestamp. We can check this with the below command:

item

kitem:
  name: Specimen123
  id: 8a7f158b-b1c5-4508-84a5-e20fe7191fd0
  ktype_id: specimen
  slug: specimen123-8a7f158b
  annotations: []
  attachments:
  - name: subgraph.ttl
  linked_kitems: []
  affiliations: []
  authors:
  - user_id: 7f0e5a37-353b-4bbc-b1f1-b6ad575f562d
  avatar_exists: false
  contacts: []
  created_at: 2025-04-14 12:34:01.852332
  updated_at: 2025-04-14 12:34:01.852332
  external_links: []
  apps: []
  user_groups: []
  custom_properties:
    content:
      sections:
      - id: id0595fb5f1853a8
        name: Untitled Section
        entries:
        - id: idba92210e193128
          type: Number
          label: Width
          value: 0.5
          measurementUnit:
            iri: http://qudt.org/vocab/unit/MilliM
            label: Millimetre
            symbol: null
            namespace: http://qudt.org/vocab/unit
          relationMapping: null
          required: false
        - id: ida08bcc9977e388
          type: Slider
          label: Length
          value:
          - 0.1
          - 0.2
          measurementUnit:
            iri: http://qudt.org/vocab/unit/MilliM
            label: Millimetre
            symbol: null
            namespace: http://qudt.org/vocab/unit
          relationMapping: null
          required: false
  rdf_exists: true

To just get the name of the item, we can do it as follows:

item.name

'Specimen123'

As well as the id of the kitem we can do it as follows:

item.id

UUID('8a7f158b-b1c5-4508-84a5-e20fe7191fd0')

To check the KType of the item newly created we can use the following:

item.ktype

ktype:
  id: specimen
  name: Specimen
  webform:
    semanticsEnabled: true
    sectionsEnabled: false
    classMapping:
    - https://w3id.org/steel/ProcessOntology/TestPiece
    sections:
    - id: id0595fb5f1853a8
      name: Untitled Section
      inputs:
      - id: idba92210e193128
        label: Width
        widget: Number
        required: false
        value: null
        hint: null
        hidden: false
        ignore: false
        selectOptions: []
        measurementUnit:
          label: Millimetre
          iri: http://qudt.org/vocab/unit/MilliM
          symbol: null
          namespace: http://qudt.org/vocab/unit
        relationMapping:
          iri: https://w3id.org/steel/ProcessOntology/hasWidth_Object
          type: object_property
          classIri: https://w3id.org/emmo#EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0
        relationMappingExtra: null
        multipleSelection: false
        knowledgeType:
        - null
        rangeOptions:
          min: 0
          max: 1
          step: 0.1
          range: false
        placeholder: null
      - id: ida08bcc9977e388
        label: Length
        widget: Slider
        required: false
        value: null
        hint: null
        hidden: false
        ignore: false
        selectOptions: []
        measurementUnit:
          label: Millimetre
          iri: http://qudt.org/vocab/unit/MilliM
          symbol: null
          namespace: http://qudt.org/vocab/unit
        relationMapping:
          iri: https://w3id.org/steel/ProcessOntology/hasTotalLength_Object
          type: object_property
          classIri: https://w3id.org/emmo#EMMO_cd2cd0de_e0cc_4ef1_b27e_2e88db027bac
        relationMappingExtra:
          iri: https://w3id.org/steel/ProcessOntology/hasTotalLength_Object
          type: object_property
          classIri: https://w3id.org/emmo#EMMO_cd2cd0de_e0cc_4ef1_b27e_2e88db027bac
        multipleSelection: false
        knowledgeType: null
        rangeOptions:
          min: 0
          max: 1
          step: 0.1
          range: true
        placeholder: null
      hidden: false
  json_schema:
    iri:
    - https://w3id.org/steel/ProcessOntology/TestPiece
    suffix: slug
    source: specimen[*]
    suffix_from_location: true
    custom_relations:
    - object_location: width
      relation: https://w3id.org/steel/ProcessOntology/hasWidth_Object
      relation_type: object_property
      object_type:
        iri: https://w3id.org/emmo#EMMO_e4de48b1_dabb_4490_ac2b_040f926c64f0
        unit: http://qudt.org/vocab/unit/MilliM
    - object_location: length[0]
      relation: https://w3id.org/steel/ProcessOntology/hasTotalLength_Object
      relation_type: object_property
      object_type:
        suffix: min
        iri: https://w3id.org/emmo#EMMO_cd2cd0de_e0cc_4ef1_b27e_2e88db027bac
        unit: http://qudt.org/vocab/unit/MilliM
    - object_location: length[1]
      relation: https://w3id.org/steel/ProcessOntology/hasTotalLength_Object
      relation_type: object_property
      object_type:
        suffix: max
        iri: https://w3id.org/emmo#EMMO_cd2cd0de_e0cc_4ef1_b27e_2e88db027bac
        unit: http://qudt.org/vocab/unit/MilliM
    - object_location: Name
      relation: http://www.w3.org/2000/01/rdf-schema#label
      relation_type: annotation_property
      object_data_type: string
  created_at: '2025-01-22T10:25:24.336663'
  updated_at: '2025-04-09T09:15:36.822065'

… and also check the KType:

item.is_a(dsms.ktypes.Specimen)

True

And we can convert the units:

item.custom_properties.Width.convert_to("m")

0.0005

item.custom_properties.Length.convert_to("m")

[0.0001, 0.0002]

You can also convert the custom_properties to a flat dict by passing the flat-parameter to the model_dump-method of the pydantic model:

item.custom_properties.model_dump(flat=True)

{'Width': 0.5, 'Length': [0.1, 0.2]}

Now you can check if the particular kitem is in the list of KItems. This can be done either by using the command: dsms.kitems or by logging into the frontend dsms instance.