Relations¶

We distinguish three types of relations:

attribute relations: For example, good in a good pizza or the pizza is good is an attribute of pizza.
verbal relations: For example, eat in John ate a pizza is a relation between John and pizza.
parent relations: For example, beer is an alcoholic drink, which in turn is a drink (Only some accounts have access to this feature, in general it requires access to GKB.)

See the Relation object reference page for more information.

Sample call¶

You can easily try it yourself:

curl -X POST https://api.geneea.com/v3/analysis \
-H 'Authorization: user_key <YOUR USER KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "id": "1",
    "text": "The trip to London was amazing. But I would not recommend the food. Especially the pizza was terrible.",
    "analyses": ["relations"],
    "domain": "voc-hospitality"
}'

# On Windows, use \" instead of " and " instead of '

from geneeanlpclient import g3
from typing import Optional

requestBuilder = g3.Request.Builder(
    analyses=[g3.AnalysisType.ENTITIES, g3.AnalysisType.RELATIONS],
    domain='voc-hospitality',
)

def argStr(arg: Optional[g3.Relation.Argument]) -> Optional[str]:
    """ Print relation subject/object including entity reference, if any """
    if arg:
        if arg.entity:
            return f'{arg.name} ({arg.entity.gkbId} {arg.entity.stdForm})'
        else:
            return f'{arg.name}'

with g3.Client.create(userKey=GENEEA_API_KEY) as analyzer:
    result = analyzer.analyze(requestBuilder.build(
        id=str(1),
        text='The trip to London was amazing. But I would not recommend the food. Especially the pizza was terrible.'
    ))

    for r in result.relations:
        if r.type == g3.Relation.TYPE_ATTR.upper():
            print(f'{r.type} {argStr(r.subject())}: {r.name}')
        else:
            print(f'{r.type} name={r.name} ')
            print(f'   {r.textRepr}')
            print(f'   subj={argStr(r.subject())}')
            print(f'   obj={argStr(r.object())}')

        print(f'   negated={r.isNegated} modality={r.modality}')

import requests

def callGeneea(input):
    url = 'https://api.geneea.com/v3/analysis'
    headers = {
        'content-type': 'application/json',
        'Authorization': 'user_key <YOUR USER KEY>'
    }

    return requests.post(url, json=input, headers=headers).json()

responseObj = callGeneea({
    'id': '1',
    'text': 'The trip to London was amazing. But I would not recommend the food. Especially the pizza was terrible.',
    'analyses': ['relations'],
    'domain': 'voc-hospitality'
})

print(responseObj)

You should get the following response:

{
  "version": "3.2.1",
  "id": "1",
  "language": {"detected": "en"},
  "entities": [
    {"id": "e0", "gkbId": "HSP-10210", "stdForm": "food", "type": "food"},
    {"id": "e1", "gkbId": "HSP-1091", "stdForm": "pizza", "type": "food"}
  ],
  "relations": [
    {
      "id": "r0", "name": "amazing", "textRepr": "amazing(trip)", "type": "ATTR",
      "args": [{"type": "SUBJECT", "name": "trip"}],
      "feats": {"negated": "false", "modality": ""}
    },
    {
      "id": "r1", "name": "recommend", "textRepr": "would recommend-not(i,food)", "type": "VERB",
      "args": [{"type": "SUBJECT", "name": "i"}, {"type": "OBJECT", "name": "food", "entityId": "e0"}],
      "feats": {"negated": "true", "modality": "would"}
    },
    {
      "id": "r2", "name": "terrible", "textRepr": "terrible(pizza)", "type": "ATTR",
      "args": [{"type": "SUBJECT", "name": "pizza", "entityId": "e1"}],
      "feats": {"negated": "false", "modality": ""}
    }
  ],
  "usedChars": 102
}

ATTR trip: amazing
   negated=False modality=
VERB name=recommend
   would recommend-not(i,food)
   subj=i
   obj=food (HSP-10210 food)
   negated=True modality=would
ATTR pizza (HSP-1091 pizza): terrible
   negated=False modality=

{
  'version': '3.2.1',
  'id': '1',
  'language': {'detected': 'en'},
  'entities': [
    {'id': 'e0', 'gkbId': 'HSP-10210', 'stdForm': 'food', 'type': 'food'},
    {'id': 'e1', 'gkbId': 'HSP-1091', 'stdForm': 'pizza', 'type': 'food'}
  ],
  'relations': [
    {
      'id': 'r0', 'name': 'amazing', 'textRepr': 'amazing(trip)', 'type': 'ATTR',
      'args': [{'type': 'SUBJECT', 'name': 'trip'}],
      'feats': {'negated': 'false', 'modality': ''}
    },
    {
      'id': 'r1', 'name': 'recommend', 'textRepr': 'would recommend-not(i,food)', 'type': 'VERB',
      'args': [{'type': 'SUBJECT', 'name': 'i'}, {'type': 'OBJECT', 'name': 'food', 'entityId': 'e0'}],
      'feats': {'negated': 'true', 'modality': 'would'}
    },
    {
      'id': 'r2', 'name': 'terrible', 'textRepr': 'terrible(pizza)', 'type': 'ATTR',
      'args': [{'type': 'SUBJECT', 'name': 'pizza', 'entityId': 'e1'}],
      'feats': {'negated': 'false', 'modality': ''}
    }
  ],
  'usedChars': 102
}

Since relations might refer to entities, the entities are automatically returned in the response XS well.