amor-segb

AMOR - Semantic Ethical Glass Box

Launch the SEGB

To start the Semantic Ethical Glass Box (SEGB), you should use the compose.yaml file provided in this repo.

Tutorial

Then, you can execute the tutorial code provided in segb_tutorial.py that log a set of triples (full ontologies and individuals stored in example-data/) into the SEGB and download all the triples stored in the SEGB to a local file.

1. Overview

The Semantic Ethical Glass Box (SEGB) is global log storage, which keeps a semantic registry (graph) of logs generated within different systems. It is comprised of two parts:

1. A REST API Flask-based server, whose functions are 1) to add new triples to the global graph and 2) retrieve the global graph;

2. A MongoDB-based database, where the global graph is storaged in JSON-LD format

Important

Since the SEGB is in a testing stage, the MongoDB database is stored in a local Docker-managed volume on the local computer where the SEGB is deployed. In the future, during the deployment stage, the database will be migrated to a centralized server to store all the records in a safe, consistent manner.

API Description

🔹 POST /log

Description:
Stores the received Turtle (TTL) data, converts it to JSON-LD, and saves it in the database. The TTL data could contain one or several triples.

✅ Request

• URL: /log
• Method: POST
• Required Headers: Content-Type: text/turtle
• Request Body:
  A document in Turtle (TTL) format (text/turtle).

📤 Responses

Status Code	Description
200 OK	Data successfully stored.
400 Bad Request	Error processing data or missing data.

---

🔹 GET /get_graph

Description:
Retrieves the stored JSON-LD data, processes it, and returns it in Turtle (TTL) format.

✅ Request

• URL: /get_graph
• Method: GET

📤 Responses

Status Code	Description
200 OK	Returns the data in Turtle (TTL) format.
404 Not Found	No data available in the database.

3. Launching the Semantic Ethical Glass Box (SEGB)

Use the docker-compose file available in this repository. This action requires access to the image used in the docker compose file. This consists on several steps:

1. Get a personal access token to enable console login in ghcr.io (Follow these instructions https://docs.github.com/es/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)

Caution

A classic personal access token is preferred, given that fine-grained access token may cause problems.

3. In your console, export your token with:

export CR_PAT=<YOUR_TOKEN>

4. Now, login in ghcr.io with:

echo $CR_PAT | docker login ghcr.io -u <YOUR_USER_NAME> --password-stdin

5. Finally, execute docker compose in the directory you have your docker-compose.yaml file:

docker compose up -d

6. The URL of the SEGB is http://127.0.0.1:5000

4. Sending data to and retrieving data from the SEGB.

To update a new TTL file containing one or several triples, we makes a POST request to the /log route. Given that we have a Turtle file "data.ttl".

Important

We strongly recommend to do NOT use blank nodes in any triples you want to log in the SEGB. They will not break the SEGB, but it can generate duplicated blank nodes (in the global graph) if they are sent several times to the SEGB due to external limitatios.

We can make it through the curl tool if using bash:

curl -X POST \
     -H "Content-Type: text/turtle" \
     --data-binary "@data.ttl" \
     http://127.0.0.1:5000/log

or by using Python:

import requests

url = "http://127.0.0.1:5000/log"

headers = {"Content-Type": "text/turtle"}

with open("./data.ttl", "rb") as file:
    ttl_data = file.read()

response = requests.post(url, headers=headers, data=ttl_data)

Similarly, for retrieving the data we makes a GET request to the /get_graph route.

Using curl over bash:

curl -X GET http://127.0.0.1:5000/get_graph -o global_graph.ttl

or Python:

import requests

url = "http://127.0.0.1:5000/get_graph"

response = requests.get(url)

with open("output.ttl", "wb") as file:
    file.write(response.content)

5. Using the SEGB in the AMOR context

We have defined a Python script, segb_tutorial.py which defines an SEGB's use case within the AMOR context.

It first defines two functions, both of them including console logs and some errors verification logic, and being appropiately described by using Docstring:

• log_ttl: function who receives as input the server's URL and the TTL file path and makes a POST to the SEGB.

• get_graph: function who receives as input the server's URL and the output TTL file path and makes a GET to the SEGB.

The workflow defined within the script defines the use case as follows:

1. First, the server's URL and the TTL files' routes with the different ontologies used (stored in the example_data directory in this repo) are defined:

    server = "http://127.0.0.1:5000"
    
    models = [
        "example-data/amor.ttl",
        "example-data/mft.ttl",
        "example-data/bhv.ttl",
        "example-data/amor-mft.ttl",
        "example-data/amor-bhv.ttl"
    ]

2. The ontologies TTL files are mapped to the SEGB's global graph via the log_ttl function:

    for model in models:
        log_ttl(server, model)

3. A new ontology can be uptated whenever we need it, so we upload a new ontology (in this case, plenty of individuals):

    input_ttl_file = "example-data/amor-examples.ttl"
    log_ttl(server, input_ttl_file)

4. The same way, we can upload non-ontology TTL files (ideally representing TLL-parsed logs from differents systems, e.g., social robots):

    input_ttl_file = "example-data/new-triples.ttl"
    log_ttl(server, input_ttl_file)

5. We finally retrieve the global graph in TTL format, which includes all the mapped ontologies and all the logs which previously were uploaded, using the get_graph function:

    output_ttl_file = "graph.ttl"
    get_graph(server, output_ttl_file)