Webservice API extensions for SAIL demo

[MichaelRoeder]

User Story

At the moment, the web service provides the best result it found in the following form:

{
  "Prediction":"∃ P625.(∀ P159.⊥)",
  "F1":1.0,
  "saved_prediction":"Predictions.owl"
}

As a user of the web service, I would like to have the option to receive more details about the result. In older versions, I received a list of expressions together with their quality. It would also be great to get the expressions in a verbalized form. However, these results should be optional.

Suggested Solution

The user could add two parameters to the request:

• number_of_results defines the number of best expressions that the system retrieved
• verbalization if this is set to true, the service should provide a verbalized form of the result (with a default value = false)

Number of Results

Request

The parameter could be simply added to the JSON object that is sent as part of the request:

{
  "pos":["..."], 
  "neg":["..."], 
  "model":"Drill",
  "path_embeddings":"...", 
  "path_to_pretrained_drill": "pretrained_drill",  
  "num_of_training_learning_problems": 10, 
  "num_of_target_concepts": 3, 
  "max_runtime": 60000, 
  "iter_bound": 100,
  "number_of_results": 3
}

If the parameter is missing, only the best result should be reported, i.e., the service should have the behavior that is already implemented.

Response

A possible extension of the existing response could be the following:

{
  "Prediction":"∃ P625.(∀ P159.⊥)",
  "F1":1.0,
  "saved_prediction":"Predictions.owl"
  "top_predictions":[
  {
    "Prediction":"∃ P625.(∀ P159.⊥)",
    "F1":1.0,
  },
  {
    "Prediction":"∃ P859⁻.⊤",
    "F1":0.8,
  },
  {
    "Prediction":"Q44",
    "F1":0.6667,
  }]
}

Verbalization

Request

The parameter could be simply added to the JSON object that is sent as part of the request:

{
  "pos":["..."], 
  "neg":["..."], 
  "model":"Drill",
  "path_embeddings":"...", 
  "path_to_pretrained_drill": "pretrained_drill",  
  "num_of_training_learning_problems": 10, 
  "num_of_target_concepts": 3, 
  "max_runtime": 60000, 
  "iter_bound": 100,
  "verbalization": true
}

Response

A possible extension of the existing response could be the following:

{
  "Prediction":"∃ P625.(∀ P159.⊥)",
  "F1":1.0,
  "saved_prediction":"Predictions.owl"
  "verbalization":"Exists ..."
}

Both

Request

A combination of the parameters as explained above:

{
  "pos":["..."], 
  "neg":["..."], 
  "model":"Drill",
  "path_embeddings":"...", 
  "path_to_pretrained_drill": "pretrained_drill",  
  "num_of_training_learning_problems": 10, 
  "num_of_target_concepts": 3, 
  "max_runtime": 60000, 
  "iter_bound": 100,
  "number_of_results": 3,
  "verbalization": true
}

Response

The verbalization should be applied to all results:

{
  "Prediction":"∃ P625.(∀ P159.⊥)",
  "F1":1.0,
  "saved_prediction":"Predictions.owl"
  "verbalization":"Exists ..."
}

{
  "Prediction":"∃ P625.(∀ P159.⊥)",
  "F1":1.0,
  "saved_prediction":"Predictions.owl"
  "verbalization":"Exists ..."
  "top_predictions":[
  {
    "Prediction":"∃ P625.(∀ P159.⊥)",
    "F1":1.0,
    "verbalization":"Exists ..."
  },
  {
    "Prediction":"∃ P859⁻.⊤",
    "F1":0.8,
    "verbalization":"Exists ..."
  },
  {
    "Prediction":"Q44",
    "F1":0.6667,
    "verbalization":"Beer (Q44)"
  }]
}

Hint

The keys of the request or result should follow a common pattern. At the moment, some start with a capital letter while others don't. There is also no common pattern in the examples above. However, it might be good to try to already stick to such a pattern while extending the API