6 minute read

Services pass entity data to a service and save the returned value in a target field of existing or newly generated items. They are used to get authority data from reconciliation services, coordinates from geocoding services or codings and summaries from LLM services.

Services for properties are configured inside the target field configuration, e.g. in the norm_data field configuration. For articles, the configuration should be added to the source item configuration. The resulting service buttons below a field or item can either be manually clicked by users or triggered by batch operations using the mutate button.

How to configure a service for properties?

Field configuration

The services configuration for properties is added to the target field. It is an object with an arbitrary key for each service and a service configuration object as value. The configuration object for property fields contains the following keys:

Key Description
caption Button caption
service Service name. At the moment only reconcile is supported.
provider An identifier for the reconciliation provider. The provider has to be configured in the app settings of Epigraf by an administrator. Examples: aat, wd.
input The field that is used to query the service, e.g. lemma. In properties, you can use path to send the full lemma path to the service.
type An additional type send to the reconciliation service, e.g. /aat or Q18783400.
score For batch reconciliation, the score threshold to be passed. From the result list, the first item either marked as match by the service or passing the threshold is inserted into the norm_data field.

Example: Geocoding of properties

In the example, geo data is stored in the content field of a property:

 "content": {
     "caption": "Geokoordinaten",
     "showcaption": false,
     "format": "geodata",
     "widgets": {
       "map": true
     },
     "keys": {
       "lat": "Latitude",
       "lng": "Longitude",
       "radius": "Radius"
     },
     "template": "list",
     "services": {
       "geo": {
         "caption": "Geocoding",
         "service": "geo",
         "provider": "nominatim",
         "input": "lemma"
       }
     }
   }

Make sure to configure the articles and items to show geo data. For example, if the geo data is contained in properties that are used in places items:

  • Set the geodata key of the articles type to {"places": "property.content"} to show locations on the articles overview map.
  • Set the geodata key of the items type to property.content to show locations within an article.

Example: Reconciliation of authority data for properties

 "services": {
        "aat": {
          "caption": "Reconcile AAT",
          "service": "reconcile",
          "provider": "aat",
          "type": "/aat",
          "input": "lemma",
          "score": 20
        },
        "wd": {
          "caption": "Reconcile WikiData",
          "service": "reconcile",
          "provider": "wd",
          "type": "Q18783400",
          "input": "lemma",
          "score": 20
        }
      }

Make sure to configure the namespaces within the property type configuration to generate links.

How to configure a service for article data?

Epigraf implements summarising, coding and annotating text using a Large Language Model. The source data is handed over to the databoard service developed by the research unit Digital Media & Computational Methods at the University of Münster.

Item configuration

The services configuration for articles is added to the item that contains the input text in the content field. It is an object with an arbitrary key for each service and a service configuration object as value.

The configuration object for items contains the following keys:

Key Description
caption Button caption
service Service name. At the moment only llm is supported. This uses the [Databoard Service](https://databoard.uni-muenster.de/) at the University of Münster.
task The task to be performed by the LLM service, one of summarize, coding or annotate. See the [databoard documentation](https://databoard.uni-muenster.de/) for details.
prompts Optional. A prompt template supported by the service. Defaults to an empty string for default prompts. See the [databoard documentation](https://databoard.uni-muenster.de/) for details.
multinomial Optional. Whether to perform the task in single or in multi mode. Coding tasks return the best matching property in single mode and a value for each property in multi mode. See the [databoard documentation](https://databoard.uni-muenster.de/) for details.
input Either the whole article is sent to the service in Markdown format (article) or the content of the item (item). Artikel data is taken from the last saved state while item content ist taken directly from the field in an open article.
target An object with the keys container, itemtype, sectiontype, fields and tagname.
  • container: The container value determines whether to update the source item (item), add or update other items in the same section (section) or other items other sections of the article (article). Item type and section type determine which items and sections are affected inside the container.
  • itemtype: The item fields where the result should be stored.
  • fields: For summarize tasks, defaults to {"content": "llm_result", "value": "state"}. For coding tasks it defaults to {"properties_id": "properties_id", "properties_label": "properties_label", 'value': "value"}. For annotate tasks, defaults to {"content": "llm_result", "value": "state"}.
  • tagname: Used for annote tasks. The name of a link type configuration. The target tag and the property type are derived from the link type configuration. Make sure the link configures a property type in its `to` field configuration. Each property must have a name in the `lemma` field and an example in the `content` field. The lemma field is used as category description, the content field should contain a short text segment (e.g. a word) that might be annotated.

Example: Generate summaries with a Large Language Model

"services": {
  "summary": {
    "caption": "Automated summary",
    "service":"llm",
    "task": "summarize",
    "input": "article",
    "target": {
      "container": "item",
      "fields": {
        "content": "llm_result",
        "value": "state"
      }
    }
  }
}

Example: Automated coding with a Large Language Model

Add the following configuration to the item that contains the source text:

"services": {
  "coding": {
    "caption": "Genre detection",
    "service": "llm",
    "task": "coding",
    "input": "item",
    "target": {
      "container": "article",
      "itemtype": "categories",
      "sectiontype": "categories"
    },
    "fields": {
      "properties_id": "properties_id",
      "properties_label": "properties_label",
      "value": "value"
    }
  }
}

In the item type used in the configuration (“categories”) configure the property field and link it to a property type. The properties are used to create the rule book.

The result will be stored in an item in another section. It is inserted into the section defined in the sectiontype value. If a section can hold multiple items (count is set to *), one item for each answer is added. Otherwise the first matching item is updated.

Example: Automated annotation with a Large Language Model

  "services": {
    "anno": {
      "caption": "Annotate figures",
      "service": "llm",
      "task": "annotate",
      "input": "item",
      "target": {
        "tagname": "anno"
      }
    }
  }

You need to configure a link type named “anno” that is configured for manual annotation. The link type must refer to a property type in its to configuration field. You need to add at least one property with the name in the lemma field and an example text in the content field.

How to make a service available in Epigraf?

Application settings

Service URLs and access tokens need to be configured in the app.php. See the developer documentation.

Permissions

Access to a services needs to be explicitly allowed. Add the following permission record for a user or role:

Field Setting
permission type Allow access.
entity name The service name (http, llm, reconcile, geo) or an asterisk as wildcard.
endpoint Select the services endpoint app/services/get.

All other permission fields remain empty.