From 5e84a865ea52ef164da6816861358e23ea3fe313 Mon Sep 17 00:00:00 2001 From: "Dr. Christoph \"Schorsch\" Jung" Date: Tue, 3 Dec 2024 15:11:14 +0100 Subject: [PATCH] docs: add trg documentation. --- README.md | 18 +- conforming/README.md | 45 -- docs/README.md | 8 +- docs/admin/README.md | 220 +++++ docs/api/openAPI.yaml | 1561 ++++++++++++++++++++++++++++++++++++ docs/architecture/Arc42.md | 149 ++++ matchmaking/README.md | 44 - provisioning/README.md | 99 --- remoting/README.md | 4 +- 9 files changed, 1944 insertions(+), 204 deletions(-) create mode 100644 docs/admin/README.md create mode 100644 docs/api/openAPI.yaml create mode 100644 docs/architecture/Arc42.md diff --git a/README.md b/README.md index 2e8981ff..64337a5c 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,12 @@ ![GitHub all releases](https://img.shields.io/github/downloads/eclipse-tractusx/knowledge-agents/total) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=eclipse-tractusx_knowledge-agents&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=eclipse-tractusx_knowledge-agents) -Tractus-X Knowledge Agents Reference Implementations (KA-RI) is a product of the [Catena-X Knowledge Agents Kit (about to move to: Tractus-X Knowledge Agents Kit)](https://bit.ly/tractusx-agents) implementing the "binding" modules of the CX-0084 standard (Federated Queries in Dataspaces). +Tractus-X Knowledge Agents Reference Implementations (KA-RI) is a product of the [Tractus-X Knowledge Agents Kit](https://eclipse-tractusx.github.io/docs-kits/kits/knowledge-agents/adoption-view/intro) implementing the "binding" modules of the CX-0084 standard (Federated Queries in Dataspaces). +* See the [User Documentation](docs/README.md) +* See the [Architecture](docs/architecture/Arc42.md) +* See the [OpenAPI definition](docs/api/openAPI.yaml) +* See the [Administration Guide](docs/admin/README.md) * See the [Authors](AUTHORS.md) * See the [Changelog](CHANGELOG.md) * See the [Code of Conduct](CODE_OF_CONDUCT.md) @@ -80,18 +84,6 @@ To update the [DEPENDENCIES](./DEPENDENCIES) declarations ./mvnw org.eclipse.dash:license-tool-plugin:license-check ``` -### Deployment - -Deployment can be done -* via [JAR libraries](https://github.com/orgs/eclipse-tractusx/packages?repo_name=knowledge-agents&ecosystem=maven) copied into your Java runtime -* via [Docker images](https://hub.docker.com/r/tractusx) -* via [Helm Charts (Stable Versions)](https://eclipse-tractusx.github.io/charts/stable) or [Helm Charts (Dev Versions)](https://eclipse-tractusx.github.io/charts/stable) - -See the individual agent documentations for more detailed deployment information -* [Provisioning Agent](provisioning/README.md) -* [Remoting Agent](remoting/README.md) -* [Conforming Agent](conforming/README.md) - #### Setup using Helm/Kind In order to run KA-RI applications via helm on your local machine, please make sure the following diff --git a/conforming/README.md b/conforming/README.md index 2adc10ef..f25e80a9 100644 --- a/conforming/README.md +++ b/conforming/README.md @@ -133,48 +133,3 @@ As with all Docker images, these likely also contain other software which may be As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within. -### Helm Chart - -A helm chart for deploying the remoting agent can be found under [this folder](../charts/remoting-agent). - -It can be added to your umbrella chart.yaml by the following snippet - -```console -dependencies: - - name: conforming-agent - repository: https://eclipse-tractusx.github.io/charts/dev - version: 1.14.24-SNAPSHOT - alias: my-conforming-agent -``` - -and then installed using - -```console -helm dependency update -``` - -In your values.yml, you configure your specific instance of the conforming agent like this - -```console -############################################################################################## -# Conforming Agent -############################################################################################## - -my-conforming-agent: - securityContext: *securityContext - nameOverride: my-conforming-agent - fullnameOverride: my-conforming-agent - ingresses: - - enabled: true - # -- The hostname to be used to precisely map incoming traffic onto the underlying network service - hostname: "my-conforming-agent.public-ip" - annotations: - nginx.ingress.kubernetes.io/rewrite-target: /$1 - nginx.ingress.kubernetes.io/use-regex: "true" - # -- Agent endpoints exposed by this ingress resource - endpoints: - - default - tls: - enabled: true - secretName: my-conforming-tls -``` diff --git a/docs/README.md b/docs/README.md index 64a8da8d..4169ecce 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,7 +20,9 @@ # Tractus-X Knowledge Agents Reference Implementation (KA-RI) Documentation -In the Knowledge Agent Architecture, an Agent is any component which speaks and/or enacts a Semantic Web protocol, such as SPARQL. +In the [Knowledge Agent Architecture](architecture/Arc42.md), an Agent is any component which speaks and/or enacts a Semantic Web protocol, such as SPARQL. + +See the [Knowledge Agents OpenAPI](api/openAPI.yaml) for a detailed description of this protocol. Binding Agents are the intermediate layer between the dataspace (represented by the Matchmaking Agent that is connected to any Agent-Enabled Application and/or the Agent-Enabled Connector) and your business data & functions. @@ -53,6 +55,10 @@ The [Remoting Agent (KA-RMT)](../remoting) which binds typical REST services to The [Conforming Agent (KA-CONF)](conforming) is not a real binding agent, but it can play the role of any other Agent in the Knowledge Agent architecture (Matchmaking Agent, Binding Agent, EDC Transfer) by testing the conformity of surrounding components (and the various KA-SPARQL profiles). The conforming agent contains no real business data (only reference sample data) and needs no connection to any backend service. +## Deployment + +see the [Administration Guide](admin/README.md) + ## NOTICE This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/docs/admin/README.md b/docs/admin/README.md new file mode 100644 index 00000000..8576e13a --- /dev/null +++ b/docs/admin/README.md @@ -0,0 +1,220 @@ + + +# Tractus-X Knowledge Agents Reference Implementation (KA-RI) Administration Guide + +## Deployment + +Deployment can be done +* via [JAR libraries](https://github.com/orgs/eclipse-tractusx/packages?repo_name=knowledge-agents&ecosystem=maven) copied into your Java runtime +* via [Docker images](https://hub.docker.com/r/tractusx) +* via [Helm Charts (Stable Versions)](https://eclipse-tractusx.github.io/charts/stable) or [Helm Charts (Dev Versions)](https://eclipse-tractusx.github.io/charts/stable) + +## Helm Chart for Conforming Agent + +A helm chart for deploying the remoting agent can be found under [this folder](../../charts/remoting-agent). + +It can be added to your umbrella chart.yaml by the following snippet + +```console +dependencies: + - name: conforming-agent + repository: https://eclipse-tractusx.github.io/charts/dev + version: 1.14.24-SNAPSHOT + alias: my-conforming-agent +``` + +and then installed using + +```console +helm dependency update +``` + +In your values.yml, you configure your specific instance of the conforming agent like this + +```console +############################################################################################## +# Conforming Agent +############################################################################################## + +my-conforming-agent: + securityContext: *securityContext + nameOverride: my-conforming-agent + fullnameOverride: my-conforming-agent + ingresses: + - enabled: true + # -- The hostname to be used to precisely map incoming traffic onto the underlying network service + hostname: "my-conforming-agent.public-ip" + annotations: + nginx.ingress.kubernetes.io/rewrite-target: /$1 + nginx.ingress.kubernetes.io/use-regex: "true" + # -- Agent endpoints exposed by this ingress resource + endpoints: + - default + tls: + enabled: true + secretName: my-conforming-tls +``` + +## Helm Chart for Matchmaking Agent + +A helm chart for deploying the matchmaking agent can be found under [this folder](../../charts/matchmaking-agent). + +It can be added to your umbrella chart.yaml by the following snippet + +```console +dependencies: + - name: matchmaking-agent + repository: https://eclipse-tractusx.github.io/charts/dev + version: 1.14.24-SNAPSHOT + alias: my-matchmmaking-agent +``` + +and then installed using + +```console +helm dependency update +``` + +In your values.yml, you configure your specific instance of the matchmaking agent like this + +```console +############################################################################################## +# Matchmaking Agent +############################################################################################## + +my-matchmaking-agent: + securityContext: *securityContext + nameOverride: my-matchmaking-agent + fullnameOverride: my-matchmaking-agent + ingresses: + - enabled: true + # -- The hostname to be used to precisely map incoming traffic onto the underlying network service + hostname: "my-matchmaking-agent.public-ip" + annotations: + nginx.ingress.kubernetes.io/rewrite-target: /$1 + nginx.ingress.kubernetes.io/use-regex: "true" + # -- Agent endpoints exposed by this ingress resource + endpoints: + - default + tls: + enabled: true + secretName: my-conforming-tls +``` + +## Helm Chart for Provisioning Agent + +A helm chart for deploying the remoting agent can be found under [this folder](../../charts/provisioning-agent). + +It can be added to your umbrella chart.yaml by the following snippet + +```console +dependencies: + - name: provisioning-agent + repository: https://eclipse-tractusx.github.io/charts/dev + version: 1.14.24-SNAPSHOT + alias: my-provider-agent +``` + +and then installed using + +```console +helm dependency update +``` + +In your values.yml, you configure your specific instance of the remoting agent like this + +```console +####################################################################################### +# Data Binding Agent +####################################################################################### + +my-provider-agent: + securityContext: *securityContext + nameOverride: my-provider-agent + fullnameOverride: my-provider-agent + resources: + requests: + cpu: 500m + # you should employ 512Mi per endpoint + memory: 1Gi + limits: + cpu: 500m + # you should employ 512Mi per endpoint + memory: 1Gi + bindings: + # disables the default sample binding + dtc: null + # real production mapping + telematics2: + port: 8081 + path: /t2/(.*) + settings: + jdbc.url: 'jdbcurl' + jdbc.user: + jdbc.password: + jdbc.driver: 'org.postgresql.Driver' + ontology: cx-ontology.xml + mapping: |- + [PrefixDeclaration] + cx-common: https://w3id.org/catenax/ontology/common# + cx-core: https://w3id.org/catenax/ontology/core# + cx-vehicle: https://w3id.org/catenax/ontology/vehicle# + cx-reliability: https://w3id.org/catenax/ontology/reliability# + uuid: urn:uuid: + bpnl: bpn:legal: + owl: http://www.w3.org/2002/07/owl# + rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns# + xml: http://www.w3.org/XML/1998/namespace + xsd: http://www.w3.org/2001/XMLSchema# + json: https://json-schema.org/draft/2020-12/schema# + obda: https://w3id.org/obda/vocabulary# + rdfs: http://www.w3.org/2000/01/rdf-schema# + oem: urn:oem: + + [MappingDeclaration] @collection [[ + mappingId vehicles + target <{vehicle_id}> rdf:type cx-vehicle:Vehicle ; cx-vehicle:vehicleIdentificationNumber {van}^^xsd:string; cx-vehicle:worldManufaturerId bpnl:{localIdentifiers_manufacturerId}; cx-vehicle:productionDate {production_date}^^xsd:date. + source SELECT vehicle_id, van, 'BPNL0000000DUMMY' as localIdentifiers_manufacturerId, production_date FROM vehicles + + mappingId partsvehicle + target <{gearbox_id}> cx-vehicle:isPartOf <{vehicle_id}> . + source SELECT vehicle_id, gearbox_id FROM vehicles + + mappingId vehicleparts + target <{vehicle_id}> cx-vehicle:hasPart <{gearbox_id}> . + source SELECT vehicle_id, gearbox_id FROM vehicles + + ]] + ingresses: + - enabled: true + # -- The hostname to be used to precisely map incoming traffic onto the underlying network service + hostname: "my-provider-agent.public.ip" + annotations: + nginx.ingress.kubernetes.io/rewrite-target: /$1 + nginx.ingress.kubernetes.io/use-regex: "true" + # -- Agent endpoints exposed by this ingress resource + endpoints: + - telematics2 + tls: + enabled: true + secretName: my-provider-tls +``` + diff --git a/docs/api/openAPI.yaml b/docs/api/openAPI.yaml new file mode 100644 index 00000000..03bd30ec --- /dev/null +++ b/docs/api/openAPI.yaml @@ -0,0 +1,1561 @@ +--- +openapi: 3.0.1 +info: + title: Tractus-X Knowledge Agents SPARQL Endpoint Specification + description: "# Usage\n\nThis endpoint is designed after [W3C SparQL 1.1](https://www.w3.org/TR/sparql11-protocol/)\n\nIt is used in three places:\n- As the consumer-oriented entrypoint of a Matchmaking Agent into the dataspace\n- As the provider-oriented looking entrypoint of a Binding Agent to a backend system\n- As the \"transfer\" protocol between the transfer proxies as built by the EDC infrastructure\n\n### Examples\n\n1. Invoke a Parameterized Skill\n\n```\nPREFIX l0: \nPREFIX cis: \nSELECT ?event ?eventName ?culturalProperty ?culturalPropertyLabel\nWHERE{\n ?event cis:involvesCulturalEntity ?culturalProperty ;\n l0:name ?eventName .\n ?culturalProperty rdfs:label ?culturalPropertyLabel\n}\n```\n\n2. Invoke a Dataspace Query\n\n```\nPREFIX arco-catalogue: \nPREFIX roapit: \nSELECT *\nWHERE{\n ?entity arco-catalogue:hasCatalogueRecordVersion ?record . \n ?record arco-catalogue:hasCatalogueRecordVersionRiT ?rit . \n ?rit roapit:withRole ?role ;\n roapit:isRoleInTimeOf ?agent\n}\n\n3. Sub-Skill of 2. that is transferred to the Binding Agent\n\n```\nPREFIX arco-catalogue: \nPREFIX roapit: \nSELECT *\nWHERE{\n ?entity arco-catalogue:hasCatalogueRecordVersion ?record . \n ?record arco-catalogue:hasCatalogueRecordVersionRiT ?rit . \n ?rit roapit:withRole ?role ;\n roapit:isRoleInTimeOf ?agent\n}\n\n```\n" + termsOfService: http://catenax.io + contact: + email: info@catenax.io + license: + name: Eclipse Public License + url: https://www.eclipse.org/legal/epl-2.0/ + version: 1.14.24 +externalDocs: + description: https://eclipse-tractusx.github.io/docs-kits/category/agents-kit + url: https://eclipse-tractusx.github.io/docs-kits/kits/knowledge-agents/development-view/api +servers: +- url: https://knowledge.dev.demo/conforming-agent/bind + description: Development Conforming Agent for KA-BIND Profile +- url: https://knowledge.dev.demo/conforming-agent/match + description: Development Conforming Agent for KA-MATCH Profile +- url: https://knowledge.dev.demo/conforming-agent/transfer + description: Development Conforming Agent for KA-TRANSFER Profile +- url: https://knowledge.dev.demo/tiera-remoting-agent/rdf4j-server/repositories/prognosis + description: Development Remoting Agent Prognosis Example +- url: https://knowledge.dev.demo/tiera-remoting-agent/rdf4j-server/repositories/rul + description: Development Remoting Agent Remaining Useful Life Example +- url: https://knowledge.dev.demo/tiera-remoting-agent/rdf4j-server/repositories/health + description: Development Remoting Agent Health Indicator Example +- url: https://knowledge.dev.demo/oem-provider-agent/sparql + description: Development Provisioning Agent Endpoint 1 +- url: https://knowledge.dev.demo/oem-provider-agent2/sparql + description: Development Provisioning Agent Endpoint 2 +- url: https://knowledge.dev.demo/oem-provider-agent3/sparql + description: Development Provisioning Agent Endpoint 3 +- url: https://knowledge.dev.demo/oem-provider-agent4/sparql + description: Development Provisioning Agent Endpoint 4 +- url: https://knowledge.dev.demo/oem-provider-agent5/sparql + description: Development Provisioning Agent Endpoint 5 +- url: https://knowledge.dev.demo/tiera-edc-data/BPNL00000003CPIY/api/agent + description: Development Matchmaking Agent +- url: https://knowledge.dev.demo/consumer-edc-data/BPNL00000003CQI9/api + description: Development Consumer +- url: https://knowledge.dev.demo/oem-edc-data/BPNL00000003COJN/api + description: Development OEM +security: +- ApiKeyAuth: [] +- BasicAuth: [] +- OAuth2: [] +tags: +- name: agent + description: Perform a SPARQL query against the dataspace +paths: + /: + get: + tags: + - agent + summary: Invoke a Skill or Query (Simple) + operationId: getAgent + parameters: + - name: asset + in: query + description: The Target Asset of the Query (targets the complete dataspace if empty) + required: false + style: form + explode: true + schema: + type: string + examples: + LifetimeSkill: + $ref: '#/components/examples/LifetimeSkill' + NullSkill: + $ref: '#/components/examples/NullSkill' + DataspaceSkill: + $ref: '#/components/examples/DataspaceSkill' + - name: runMode + in: query + description: "Determines the preferred execution location which may be \"consumer\" (in the computing environment of the endpoint agent), \"provider\" (in the computing environment of the remote agent providing the targetted asset) or \"all\" (the agent will choose the best computing environment based on contracts and policies, this is the default mode)." + required: false + style: form + explode: true + schema: + type: string + examples: + consumer: + $ref: '#/components/examples/RunModeConsumer' + provider: + $ref: '#/components/examples/RunModeProvider' + all: + $ref: '#/components/examples/RunModeAll' + - name: queryLn + in: query + description: Determines the query language. Currently only "SPARQL" is supported. + required: false + style: form + explode: true + schema: + type: string + examples: + sparql: + $ref: '#/components/examples/QuerySparql' + - name: query + in: query + description: The SPARQL query + required: false + style: form + explode: true + schema: + type: string + examples: + "Null": + $ref: '#/components/examples/NullText' + Dataspace: + $ref: '#/components/examples/Dataspace' + - name: (vin + in: query + description: A sample bound parameter 'vin' which opens a new input tuple + required: false + style: form + explode: true + schema: + type: string + examples: + Vehicle1: + $ref: '#/components/examples/Vehicle1' + NoVehicle: + $ref: '#/components/examples/NoVehicle' + - name: troubleCode + in: query + description: A sample multi-bound parameter 'troubleCode' which closes the tuple + required: false + style: form + explode: true + schema: + maxItems: 128 + type: array + items: + type: string + examples: + TroubleCodeClose: + $ref: '#/components/examples/TroubleCodeClose' + NoTroubleCode: + $ref: '#/components/examples/NoTroubleCode' + responses: + "200": + description: The SparQL query has been processed successfully. + content: + application/sparql-results+json: + schema: + type: object + example: + head: + vars: + - connector + - asset + - name + - description + - type + - version + - contentType + - isDefinedBy + - shape + results: + bindings: + - connector: + type: uri + value: edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + asset: + type: uri + value: GraphAsset?oem=Quality + name: + type: literal + value: Quality Data. + description: + type: literal + value: A graph asset/offering mounting Quality data. + type: + type: "uri," + value: https://w3id.org/catenax/ontology/common#GraphAsset + version: + type: "literal," + value: v0.7.2 + contentType: + type: "literal," + value: "application/json, application/xml" + isDefinedBy: + type: "literal," + value: + shape: + type: "literal," + value: "@prefix : ." + application/sparql-results+xml: + schema: + $ref: '#/components/schemas/XmlResultset' + example: |- + + + + + + + + + + + + + + + + + edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + + + GraphAsset?oem=Quality + + + Quality Data. + + + A graph asset/offering mounting Quality data. + + + https://w3id.org/catenax/ontology/common#GraphAsset + + + v0.7.2 + + + application/json, application/xml + + + <https://w3id.org/catenax/ontology/reliability> + + + @prefix : <GraphAsset?oem=Quality#> . + + + + + text/csv: + schema: + type: string + example: |- + "subject","predicate","object" + "foo","meets","bar" + "one","meets","two" + text/tab-separated-values: + schema: + type: string + example: ?subject ?predicate ?object + application/x-binary-rdf-results-table: + schema: + type: string + format: binary + "203": + description: The SparQL query has been processed successfully but warnings did occur. + headers: + cx_warnings: + description: A data structure listing problems when processing the query. + style: simple + explode: false + schema: + maxItems: 64 + type: array + items: + $ref: '#/components/schemas/CxWarning' + content: + application/sparql-results+json: + schema: + type: object + example: + head: + vars: + - connector + - asset + - name + - description + - type + - version + - contentType + - isDefinedBy + - shape + results: + bindings: + - connector: + type: uri + value: edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + asset: + type: uri + value: GraphAsset?oem=Quality + name: + type: literal + value: Quality Data. + description: + type: literal + value: A graph asset/offering mounting Quality data. + type: + type: "uri," + value: https://w3id.org/catenax/ontology/common#GraphAsset + version: + type: "literal," + value: v0.7.2 + contentType: + type: "literal," + value: "application/json, application/xml" + isDefinedBy: + type: "literal," + value: + shape: + type: "literal," + value: "@prefix : ." + application/sparql-results+xml: + schema: + $ref: '#/components/schemas/XmlResultset' + example: |- + + + + + + + + + + + + + + + + + edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + + + GraphAsset?oem=Quality + + + Quality Data. + + + A graph asset/offering mounting Quality data. + + + https://w3id.org/catenax/ontology/common#GraphAsset + + + v0.7.2 + + + application/json, application/xml + + + <https://w3id.org/catenax/ontology/reliability> + + + @prefix : <GraphAsset?oem=Quality#> . + + + + + text/csv: + schema: + type: string + example: |- + "subject","predicate","object" + "foo","meets","bar" + "one","meets","two" + text/tab-separated-values: + schema: + type: string + example: ?subject ?predicate ?object + application/x-binary-rdf-results-table: + schema: + type: string + format: binary + "400": + description: Bad request or malformed SPARQL + "500": + description: Fatal error + post: + tags: + - agent + summary: Invoke a Skill or Query (Flexible) + operationId: postAgent + parameters: + - name: asset + in: query + description: The Target Asset of the Query (targets the complete dataspace if empty) + required: false + style: form + explode: true + schema: + type: string + examples: + LifetimeSkill: + $ref: '#/components/examples/LifetimeSkill' + NullSkill: + $ref: '#/components/examples/NullSkill' + DataspaceSkill: + $ref: '#/components/examples/DataspaceSkill' + - name: runMode + in: query + description: "Determines the preferred execution location which may be \"consumer\" (in the computing environment of the endpoint agent), \"provider\" (in the computing environment of the remote agent providing the targetted asset) or \"all\" (the agent will choose the best computing environment based on contracts and policies, this is the default mode)." + required: false + style: form + explode: true + schema: + type: string + examples: + consumer: + $ref: '#/components/examples/RunModeConsumer' + provider: + $ref: '#/components/examples/RunModeProvider' + all: + $ref: '#/components/examples/RunModeAll' + - name: queryLn + in: query + description: Determines the query language. Currently only "SPARQL" is supported. + required: false + style: form + explode: true + schema: + type: string + examples: + sparql: + $ref: '#/components/examples/QuerySparql' + - name: query + in: query + description: The SPARQL query (in case that the body contains a tuple set) + required: false + style: form + explode: true + schema: + type: string + examples: + "Null": + $ref: '#/components/examples/NullText' + Dataspace: + $ref: '#/components/examples/Dataspace' + - name: (vin + in: query + description: A sample bound parameter 'vin' which opens a new input tuple + required: false + style: form + explode: true + schema: + type: string + examples: + Vehicle1: + $ref: '#/components/examples/Vehicle1' + NoVehicle: + $ref: '#/components/examples/NoVehicle' + - name: troubleCode + in: query + description: A sample multi-bound parameter 'troubleCode' which closes the tuple + required: false + style: form + explode: true + schema: + maxItems: 128 + type: array + items: + type: string + examples: + TroubleCodeClose: + $ref: '#/components/examples/TroubleCodeClose' + NoTroubleCode: + $ref: '#/components/examples/NoTroubleCode' + requestBody: + description: The body either contains the query or a binding data set when a skill is invoked + content: + application/sparql-results+json: + schema: + type: object + example: + head: + vars: + - vin + - troubleCode + results: + bindings: + - vin: + type: literal + value: WBAAL31029PZ00001 + troubleCode: + type: literal + value: P0746 + - vin: + type: literal + value: WBAAL31029PZ00001 + troubleCode: + type: literal + value: P0745 + - vin: + type: literal + value: WBAAL31029PZ00002 + troubleCode: + type: literal + value: P0744 + - vin: + type: literal + value: WBAAL31029PZ00003 + troubleCode: + type: literal + value: P0743 + application/sparql-results+xml: + schema: + $ref: '#/components/schemas/XmlResultset' + example: |- + + + + + + + + + + WBAAL31029PZ00001 + + + P0746 + + + + + WBAAL31029PZ00001 + + + P0745 + + + + + WBAAL31029PZ00002 + + + P0744 + + + + + application/sparql-query: + schema: + type: string + examples: + Dataspace: + $ref: '#/components/examples/Dataspace' + required: true + responses: + "200": + description: The SparQL query has been processed successfully. + content: + application/sparql-results+json: + schema: + type: object + example: + head: + vars: + - connector + - asset + - name + - description + - type + - version + - contentType + - isDefinedBy + - shape + results: + bindings: + - connector: + type: uri + value: edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + asset: + type: uri + value: GraphAsset?oem=Quality + name: + type: literal + value: Quality Data. + description: + type: literal + value: A graph asset/offering mounting Quality data. + type: + type: "uri," + value: https://w3id.org/catenax/ontology/common#GraphAsset + version: + type: "literal," + value: v0.7.2 + contentType: + type: "literal," + value: "application/json, application/xml" + isDefinedBy: + type: "literal," + value: + shape: + type: "literal," + value: "@prefix : ." + application/sparql-results+xml: + schema: + $ref: '#/components/schemas/XmlResultset' + example: |- + + + + + + + + + + + + + + + + + edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + + + GraphAsset?oem=Quality + + + Quality Data. + + + A graph asset/offering mounting Quality data. + + + https://w3id.org/catenax/ontology/common#GraphAsset + + + v0.7.2 + + + application/json, application/xml + + + <https://w3id.org/catenax/ontology/reliability> + + + @prefix : <GraphAsset?oem=Quality#> . + + + + + text/csv: + schema: + type: string + example: |- + "subject","predicate","object" + "foo","meets","bar" + "one","meets","two" + text/tab-separated-values: + schema: + type: string + example: ?subject ?predicate ?object + application/x-binary-rdf-results-table: + schema: + type: string + format: binary + "203": + description: The SparQL query has been processed successfully but warnings did occur. + headers: + cx_warnings: + description: A data structure listing problems when processing the query. + style: simple + explode: false + schema: + maxItems: 64 + type: array + items: + $ref: '#/components/schemas/CxWarning' + content: + application/sparql-results+json: + schema: + type: object + example: + head: + vars: + - connector + - asset + - name + - description + - type + - version + - contentType + - isDefinedBy + - shape + results: + bindings: + - connector: + type: uri + value: edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + asset: + type: uri + value: GraphAsset?oem=Quality + name: + type: literal + value: Quality Data. + description: + type: literal + value: A graph asset/offering mounting Quality data. + type: + type: "uri," + value: https://w3id.org/catenax/ontology/common#GraphAsset + version: + type: "literal," + value: v0.7.2 + contentType: + type: "literal," + value: "application/json, application/xml" + isDefinedBy: + type: "literal," + value: + shape: + type: "literal," + value: "@prefix : ." + application/sparql-results+xml: + schema: + $ref: '#/components/schemas/XmlResultset' + example: |- + + + + + + + + + + + + + + + + + edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + + + GraphAsset?oem=Quality + + + Quality Data. + + + A graph asset/offering mounting Quality data. + + + https://w3id.org/catenax/ontology/common#GraphAsset + + + v0.7.2 + + + application/json, application/xml + + + <https://w3id.org/catenax/ontology/reliability> + + + @prefix : <GraphAsset?oem=Quality#> . + + + + + text/csv: + schema: + type: string + example: |- + "subject","predicate","object" + "foo","meets","bar" + "one","meets","two" + text/tab-separated-values: + schema: + type: string + example: ?subject ?predicate ?object + application/x-binary-rdf-results-table: + schema: + type: string + format: binary + "400": + description: Bad request or malformed SPARQL + "500": + description: Fatal error + /skill: + get: + tags: + - agent + summary: Get a Skill + operationId: getSkill + parameters: + - name: asset + in: query + description: The Asset Id of the Skill + required: true + style: form + explode: true + schema: + type: string + examples: + DataspaceSkill: + $ref: '#/components/examples/DataspaceSkill' + LifetimeSkill: + $ref: '#/components/examples/LifetimeSkill' + responses: + "200": + description: Skill has been found + content: + application/sparql-query: + schema: + type: string + examples: + Dataspace: + $ref: '#/components/examples/Dataspace' + Lifetime: + $ref: '#/components/examples/AuthorsWithLimits' + "400": + description: Skill has not been found + "500": + description: Fatal error + post: + tags: + - agent + summary: Register a Skill + operationId: postSkill + parameters: + - name: asset + in: query + description: The Asset Id of the Skill + required: true + style: form + explode: true + schema: + type: string + examples: + DataspaceSkill: + $ref: '#/components/examples/DataspaceSkill' + LifetimeSkill: + $ref: '#/components/examples/LifetimeSkill' + - name: assetName + in: query + description: The Asset Name of the Skill + required: false + style: form + explode: true + schema: + type: string + example: Example Skill + - name: assetVersion + in: query + description: The Version of the Skill + required: false + style: form + explode: true + schema: + type: string + example: 1.0.5 + - name: assetDescription + in: query + description: The Description of the Skill + required: false + style: form + explode: true + schema: + type: string + example: Performs a sample operation on the dataspace. + - name: allowServicePattern + in: query + description: A regex indicating which external SERVICE Iris are allowed during execution. + required: false + style: form + explode: true + schema: + type: string + example: edcs://.* + - name: denyServicePattern + in: query + description: A regex indicating which external SERVICE Iris are forbidden during execution. + required: false + style: form + explode: true + schema: + type: string + example: https?://.* + - name: distributionMode + in: query + description: The distribution mode under which to publish the skill + required: false + style: form + explode: true + schema: + type: string + examples: + Provider: + $ref: '#/components/examples/DistributionModeProvider' + Consumer: + $ref: '#/components/examples/DistributionModeConsumer' + All: + $ref: '#/components/examples/DistributionModeAll' + - name: contract + in: query + description: The contract under which the skill should be published + required: false + style: form + explode: true + schema: + type: string + examples: + Provider: + $ref: '#/components/examples/Contract' + - name: isFederated + in: query + description: Whether the skill should be visible in the Federated Catalogue + required: false + style: form + explode: true + schema: + type: boolean + - name: ontology + in: query + description: Multiple references to ontologies which are referenced in the skill + required: false + style: form + explode: true + schema: + type: string + examples: + Provider: + $ref: '#/components/examples/Ontology' + requestBody: + description: The body either contains the parameterized query + content: + application/sparql-query: + schema: + type: string + examples: + Dataspace: + $ref: '#/components/examples/Dataspace' + required: true + responses: + "200": + description: Skill has been registered + "204": + description: Skill has been updated + "400": + description: Bad request or malformed SPARQL + "500": + description: Fatal error + /graph: + post: + tags: + - graph + summary: Upload a Graph + operationId: postGraph + parameters: + - name: asset + in: query + description: The Asset Id of the Graph + required: true + style: form + explode: true + schema: + type: string + examples: + GraphAsset: + $ref: '#/components/examples/GraphAsset' + - name: assetName + in: query + description: The Asset Name of the Graph + required: false + style: form + explode: true + schema: + type: string + example: Example Graph + - name: assetVersion + in: query + description: The Version of the Graph + required: false + style: form + explode: true + schema: + type: string + example: 3.2.1 + - name: assetDescription + in: query + description: The Description of the Graph + required: false + style: form + explode: true + schema: + type: string + example: Contains freshly uploaded traceability data. + - name: allowServicePattern + in: query + description: A regex indicating which external SERVICE Iris are allowed when traversing this graph. + required: false + style: form + explode: true + schema: + type: string + example: edcs://.* + - name: denyServicePattern + in: query + description: A regex indicating which external SERVICE Iris are forbidden when travering this graph. + required: false + style: form + explode: true + schema: + type: string + example: https?://.* + - name: contract + in: query + description: The contract under which the graph should be published + required: false + style: form + explode: true + schema: + type: string + examples: + Provider: + $ref: '#/components/examples/Contract' + - name: shape + in: query + description: "The shape of the asset if it is known,." + required: false + style: form + explode: true + schema: + type: string + examples: + Shape: + $ref: '#/components/examples/Shape' + - name: isFederated + in: query + description: Whether the graph should be visible in the Federated Catalogue + required: false + style: form + explode: true + schema: + type: boolean + - name: ontology + in: query + description: Multiple references to ontologies which are referenced in the graph + required: false + style: form + explode: true + schema: + type: string + examples: + Provider: + $ref: '#/components/examples/Ontology' + requestBody: + description: The body either contains rdf in TTL (terse triple language) syntax or CSV + content: + text/turtle: + schema: + type: string + examples: + Dataspace: + $ref: '#/components/examples/GraphTtl' + text/csv: + schema: + type: string + examples: + Dataspace: + $ref: '#/components/examples/GraphCsv' + required: true + responses: + "200": + description: Graph has been registered + "204": + description: Graph has been updated + "400": + description: Bad request or malformed CSV/TTL + "500": + description: Fatal error + delete: + tags: + - graph + summary: Delete a Graph (Asset) + operationId: deleteGraph + parameters: + - name: asset + in: query + description: The Asset Id of the Graph + required: true + style: form + explode: true + schema: + type: string + examples: + GraphAsset: + $ref: '#/components/examples/GraphAsset' + responses: + "200": + description: Graph has been deleted + "400": + description: Graph has not been found + "500": + description: Fatal error +components: + schemas: + CxWarning: + type: object + properties: + source-tenant: + type: string + source-asset: + type: string + target-tenant: + type: string + target-asset: + type: string + problem: + type: string + context: + type: string + XmlResultset: + type: object + properties: + head: + $ref: '#/components/schemas/XmlResultset_head' + results: + $ref: '#/components/schemas/XmlResultset_results' + xml: + name: sparql + XmlResultset_head_variable: + type: object + properties: + name: + type: string + xml: + attribute: true + xml: + name: variable + XmlResultset_head: + type: object + properties: + variable: + $ref: '#/components/schemas/XmlResultset_head_variable' + xml: + name: head + XmlResultset_results_result_binding: + type: object + properties: + name: + type: string + xml: + attribute: true + literal: + type: string + uri: + type: string + xml: + name: binding + XmlResultset_results_result: + type: object + properties: + binding: + $ref: '#/components/schemas/XmlResultset_results_result_binding' + xml: + name: result + XmlResultset_results: + type: object + properties: + result: + $ref: '#/components/schemas/XmlResultset_results_result' + xml: + name: results + responses: + "203": + description: The SparQL query has been processed successfully but warnings did occur. + headers: + cx_warnings: + description: A data structure listing problems when processing the query. + style: simple + explode: false + schema: + maxItems: 64 + type: array + items: + $ref: '#/components/schemas/CxWarning' + content: + application/sparql-results+json: + schema: + type: object + example: + head: + vars: + - connector + - asset + - name + - description + - type + - version + - contentType + - isDefinedBy + - shape + results: + bindings: + - connector: + type: uri + value: edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + asset: + type: uri + value: GraphAsset?oem=Quality + name: + type: literal + value: Quality Data. + description: + type: literal + value: A graph asset/offering mounting Quality data. + type: + type: "uri," + value: https://w3id.org/catenax/ontology/common#GraphAsset + version: + type: "literal," + value: v0.7.2 + contentType: + type: "literal," + value: "application/json, application/xml" + isDefinedBy: + type: "literal," + value: + shape: + type: "literal," + value: "@prefix : ." + application/sparql-results+xml: + schema: + $ref: '#/components/schemas/XmlResultset' + example: |- + + + + + + + + + + + + + + + + + edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + + + GraphAsset?oem=Quality + + + Quality Data. + + + A graph asset/offering mounting Quality data. + + + https://w3id.org/catenax/ontology/common#GraphAsset + + + v0.7.2 + + + application/json, application/xml + + + <https://w3id.org/catenax/ontology/reliability> + + + @prefix : <GraphAsset?oem=Quality#> . + + + + + text/csv: + schema: + type: string + example: |- + "subject","predicate","object" + "foo","meets","bar" + "one","meets","two" + text/tab-separated-values: + schema: + type: string + example: ?subject ?predicate ?object + application/x-binary-rdf-results-table: + schema: + type: string + format: binary + "200": + description: The SparQL query has been processed successfully. + content: + application/sparql-results+json: + schema: + type: object + example: + head: + vars: + - connector + - asset + - name + - description + - type + - version + - contentType + - isDefinedBy + - shape + results: + bindings: + - connector: + type: uri + value: edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + asset: + type: uri + value: GraphAsset?oem=Quality + name: + type: literal + value: Quality Data. + description: + type: literal + value: A graph asset/offering mounting Quality data. + type: + type: "uri," + value: https://w3id.org/catenax/ontology/common#GraphAsset + version: + type: "literal," + value: v0.7.2 + contentType: + type: "literal," + value: "application/json, application/xml" + isDefinedBy: + type: "literal," + value: + shape: + type: "literal," + value: "@prefix : ." + application/sparql-results+xml: + schema: + $ref: '#/components/schemas/XmlResultset' + example: |- + + + + + + + + + + + + + + + + + edcs://knowledge.dev.demo.catena-x.net/oem-edc-control/BPNL00000003COJN + + + GraphAsset?oem=Quality + + + Quality Data. + + + A graph asset/offering mounting Quality data. + + + hhttps://w3id.org/catenax/ontology/common#GraphAsset + + + v0.7.2 + + + application/json, application/xml + + + <https://w3id.org/catenax/ontology/reliability> + + + @prefix : <GraphAsset?oem=Quality#> . + + + + + text/csv: + schema: + type: string + example: |- + "subject","predicate","object" + "foo","meets","bar" + "one","meets","two" + text/tab-separated-values: + schema: + type: string + example: ?subject ?predicate ?object + application/x-binary-rdf-results-table: + schema: + type: string + format: binary + "400": + description: Bad request or malformed SPARQL + "500": + description: Fatal error + examples: + NullSkill: + summary: No Predefined Skill + value: null + DataspaceSkill: + summary: Predefined Skill to List Federated Data Catalogue + value: SkillAsset?consumer=Dataspace + LifetimeSkill: + summary: Predefined Skill to Perform a Lifetime Prognosis + value: SkillAsset?consumer=RemainingUsefulLife + GraphAsset: + summary: Sample Graph Asset Name + value: GraphAsset?provider=Traceability + Vehicle1: + summary: Vehicle Parameter + value: WBAAL31029PZ00001 + NoVehicle: + summary: No Vehicle Parameter + value: null + TroubleCodeClose: + summary: Multiple Trouble Codes (and Tuple End) + value: + - P0746 + - P0745) + SingleTroubleCode: + summary: A Single Trouble Code + value: P0746 + NoTroubleCode: + summary: No Trouble Code + value: null + NullText: + summary: No Skill + value: null + Dataspace: + summary: Skill to List Federated Data Catalogue + value: "SELECT ?connector ?asset \n ?name\n (MIN(?adescription) AS ?description) \n ?type\n (MAX(?aversion) AS ?version) \n (GROUP_CONCAT(DISTINCT ?acontentType;SEPARATOR=\",\") AS ?contentType) \n (CONCAT(\"<\",GROUP_CONCAT(?aontology;SEPARATOR=\">,<\"),\">\") AS ?isDefinedBy) \n (MIN(?ashape) AS ?shape)\n WHERE { \n ?connector ?asset. \n ?asset ?acontentType; \n ?name; \n ?type; \n ?aontology; \n ?aversion; \n ?adescription.\n\n OPTIONAL {\n ?asset ?ashape\n }\n} GROUP BY ?connector ?asset ?name ?type" + Resultset: + summary: Sample Json-Based Resultset + AuthorsWithLimits: + summary: First 10 authors + value: "SELECT DISTINCT \n ?author_url \n (GROUP_CONCAT(?author_label; SEPARATOR=\";\") AS ?author_names)\n{ \n\n ?author_url a-cd:pseudonym ?x .\n ?author_url rdfs:label ?author_label\n} LIMIT 10" + CulturalPlacesInVinci: + summary: Cultural places in Latina + value: |- + SELECT DISTINCT ?luogo ?indirizzo ?comune WHERE { + ?x a cis:CulturalInstituteOrSite ; + cis:institutionalCISName ?luogo ; + cis:hasSite ?site . + ?site cis:siteAddress ?address . + ?address clvapit:fullAddress ?indirizzo ; + clvapit:hasCity [rdfs:label ?comune] . + FILTER regex(str(?comune), "Vinci", "i") + } ORDER BY ?luogo LIMIT 100 + LifetimeSkill: + RunModeConsumer: + summary: Local Consumer Execution + value: consumer + RunModeProvider: + summary: Remote Provider Execution + value: provider + RunModeAll: + summary: Best Possible Execution + value: all + DistributionModeConsumer: + summary: Local Consumer Execution + value: CONSUMER + DistributionModeProvider: + summary: Remote Provider Execution + value: PROVIDER + DistributionModeAll: + summary: Best Possible Execution + value: ALL + QuerySparql: + summary: SPARQL Query Language + value: SPARQL + Contract: + summary: An example contract name + value: Contract?oem=Skill + Ontology: + summary: An example reference to an ontology + value: https://w3id.org/catenax/ontology/behaviour + GraphTtl: + summary: An example graph in TTL syntax + value: |- + ################################################################# + # Graph Asset in TTL/RDF/OWL FORMAT + # See copyright notice in the top folder + # See authors file in the top folder + # See license file in the top folder + ################################################################# + + @prefix : . + @prefix cx-core: . + @prefix cx-common: . + @prefix cx-supply: . + @prefix cx-mat: . + @prefix bpnl: . + @prefix bpns: . + @prefix bpna: . + @prefix bpnl: . + @prefix rdf: . + @prefix xsd: . + @prefix skos: . + @prefix dc: . + + :Chain1 rdf:type cx-supply:SupplyRelationship; + cx-supply:material cx-mat:Rubber; + cx-supply:consumer bpna:BPNL00000003COJN; + cx-supply:supplier bpns:BPNL00000003CPIY. + GraphCsv: + summary: An example graph in CSV syntax + value: |- + IRI,http://www.w3.org/1999/02/22-rdf-syntax-ns#type,https://w3id.org/catenax/ontology/supply-chain#material,https://w3id.org/catenax/ontology/supply-chain#consumer,https://w3id.org/catenax/ontology/supply-chain#supplier + :Chain1,,,, + Shape: + summary: An example shape in TTL syntax + value: |- + @prefix rdf: . + @prefix rdfs: . + @prefix owl: . + @prefix cx-core: . + @prefix cx-vehicle: . + @prefix sh: . + @prefix : + # Asset content description (exp:vehicleShapeGraph) + :VehicleShape a sh:NodeShape ; + sh:targetClass cx-vehicle:Vehicle ; + sh:property [ + sh:path cx-vehicle:vehicleIdentificationNumber ; + sh:pattern "[A-Z0-9]{17}"; + sh:minCount 1 ; + ] ; + sh:property [ + sh:path cx-core:name ; + sh:datatype xsd:string ; + sh:minCount 1 ; + ] . + securitySchemes: + BasicAuth: + type: http + scheme: basic + ApiKeyAuth: + type: apiKey + name: X-API-Key + in: header + OAuth2: + type: oauth2 + flows: + authorizationCode: + authorizationUrl: https://centralidp.int.demo.catena-x.net/auth/realms/CX-Central/protocol/openid-connect/auth + tokenUrl: https://centralidp.int.demo.catena-x.net/auth/realms/CX-Central/protocol/openid-connect/token + scopes: {} diff --git a/docs/architecture/Arc42.md b/docs/architecture/Arc42.md new file mode 100644 index 00000000..e7a136de --- /dev/null +++ b/docs/architecture/Arc42.md @@ -0,0 +1,149 @@ + + +## Introduction and Goals + +The main objective concerning the approach described in this section is to create a state-of-the-art compute-to-data architecture for automotive use cases (and beyond) based on standards and best practices around GAIA-X and W3C. To reach this aim, full semantic integration, search and query with focus on relations between entities and data sovereignty is focused. In contrast to a simple file-based data transfer, this shifts the responsibility for the access, authorization to the data and processing of the data from the application development to the provider and hence ultimately, the actual owner of the data. To achieve this aim, the Knowledge Agent standard shall achieve the following abilities: + +* the ability to define well-formed and composable computations/scripts (skills) which operate over various assets of various business partners. +* the ability to invoke and dynamically distribute these (sub-)skills over the relevant partners/connectors using an extensible agent interface. +* the ability to safely provide data and service assets via appropriate agent implementations which "bind" the skill to the backend execution engines (rather than mapping data). +* the ability for an agent/connector/business partner to decide + * whether to hide particular data and computations inside a sub-skill + * whether to delegate/federate particular computations/sub-skills to other agents + * whether to migrate or clone an agent/asset from a partner +* the ability to describe data and service assets as well as appropriate federation policies in the IDS vocabulary in order to allow for a dynamic matchmaking of skills and agents. +* the ability to define domain/use case-based ontologies which form the vocabulary used in the skill definitions. +* the ability to visualize and develop the ontologies and skills in appropriate SDKs and User Experience components. + +See also the KIT [Introduction](https://eclipse-tractusx.github.io/docs-kits/kits/knowledge-agents/adoption-view/intro) and the [High-Level Architecture](https://eclipse-tractusx.github.io/docs-kits/kits/knowledge-agents/development-view/architecture). + +## Constraints + +The Knowledge Agents Architecture is based on the Catena-X Dataspace Architecture with a specific focus on the Eclipse Dataspace Connector (EDC). It integrates with Catena-X Portal/Core Services & Identity Management principles and supports the typical interaction models as required by Catena-X Use Cases, such as + +* Traceability with Focus on Low-Volume Bills-Of-Material Data and Deep Supply Chains with One-Up and One-Down Visibility +* Behaviour Twin with Focus on High-Volume Telematics Data and Flat and Trustful Supply Chain   + +Furthermore, on the vocabulary/script level it utilizes and extends well-defined profiles of W3C Semantic Web Standards, such as OWL, RDF, SHACL, SPARQL. + +## Context and Scope + +The architecture is relevant for the following roles: + +* Business Application Provider +* Enablement Service Provider +* Data Consumer +* Data Provider + +The following Catena-X stakeholders are affected by Knowledge Agent approach + +* **Business Application Provider:** Applications that use KA technology on behalf of a Dataspace Participant (e.g. a Fleet Monitor, an Incident Reporting Solution). + +* **Enablement Service Provider:** Services to assist Dataspace Participants/Applications in processing data based on KA technology (e.g. a Graph Database, a Virtual Graph Binding Engine, an EDC Package). +As a second path, Companies are addressed that want to provide compute resources (for example by a server or other KA-enabled Applications or Services) based on instances/configurations of KA-enabled EDC Packages, for example a Recycling Software Specialist + +* **Data Consumer:** Companies that want to use data and logic (for example by KA-enabled Applications or Services) based on instances/configurations of KA-enabled EDC Packages, such as a Recycling Company or a Tier-2 Automotive Supplier +* **Data Provider:** Companies that want to provide data (for example by a backend database or other KA-enabled Applications or Services) based on instances/configurations of KA-enabled EDC Packages, for example an Automotive OEM. Companies that want to provide functions (for example by a REST endpoint or other KA-enabled Applications or Services) based on instances/configurations of KA-enabled EDC Packages, for example a Tier1 Sensor Device Supplier + +Content-wise the following capabilities of Catena-X are addressed: + +* Query and Search (Basic Mechanism, Integration in User Experiences) +* Services for making use of various federated data sources being part of a data space (Data & Function Provisioning, Logic Development & Provisioning) +* Semantic Modelling +* Publishing, Negotiation, Transfer Protocols and Policy Enforcement via IDS (EDC) connector + +## Solution Strategy + +Knowledge Agents regards the peer-to-peer Dataspace as one large (virtual) knowledge graph. + +A graph, because the representation of data as a set of Triples (Outgoing-Node = Subject, Edge = Predicate, Receiving-Node = Object) is the highest form of normalization to which all other forms of structured data can be abstracted. + +Virtual, because this graph is not centrally instantiated in a dedicated database, but it is manifested by a computation (traversal) which jumps from node to node (and hereby: from the sovereignity domain of one business partner to the another one including taking over authentication and authorization information).   + +Knowledge because computations and graph contents are not arbitrary, but share common meta-data (again in the form of a graph interlinked with the actual instance graph) such that the vocabulary (at least: edge names) is standardized and computations can be formulated (offered) independent of the data. + +To reach that metaphor, the Knowledge Agents Architecture uses the following specifications, some of which are standard-relevant: + +* A general description language based on the Resource Description Framework (RDF) +* A Meta-Model defined by OWL-R +* A platform Ontology (consisting of several domain ontologies) as the Semantic Model +* A description of graphs (=graph assets) which contain instance data for the Semantic Model (or: use-case driven and role-driven subsets thereof) and which may be described as SHACL constraints +* A query language to traverse the graphs in SPARQL and store these queries as skills (=skill assets) in the database + +Non-standard relevant, but provided as a best practice/blueprint architecture are + +* Bindings for relational and functional data + * [R2RML](https://www.w3.org/TR/r2rml/) or OBDA (Ontology-Based Data Access ) for relational data + * [RDF4J](https://en.wikipedia.org/wiki/RDF4J)/SAIL (Storage And Inference Layer) configuration for REST remoting +* SQL- and REST-based Virtualizers which bridge public Dataspace Operations with internal/private backend systems/data sources. + +Knowledge Agents regards the peer-to-peer Dataspace as one large federated execution engine. + +Federation means distributed that is there is no central endpoint/resource which controls the computation, but the execution may be entered/triggered on any tenant and uses a scalable set of resources which are contributed by each participant. + +Federation means independent in that there is no central authentication/authorization regime, but the computation is validated, controled and (transparently) delegated by decentral policies as given/defined be each particpant. + +See also [High-Level Architecture](https://eclipse-tractusx.github.io/docs-kits/kits/knowledge-agents/development-view/architecture). + +## Building Block View + +See chapter [Layers & Modules](https://eclipse-tractusx.github.io/docs-kits/kits/knowledge-agents/development-view/modules) of the Agents KIT. + +[![Architecture High-Level](https://eclipse-tractusx.github.io/assets/images/knowledge_agent_architecture_small-adfd1153ee8a08d5338e311a931d0f3a.png)](https://eclipse-tractusx.github.io/assets/files/knowledge_agent_architecture-3aa46110a6213138c677b339e3647703.png) + +## Runtime View + +[![Runtime View](https://eclipse-tractusx.github.io/assets/images/Runtime_View3-ffe55baacdc5171f0deaef0b987bfd0c.png)](https://eclipse-tractusx.github.io/assets/files/Runtime_View3-ffe55baacdc5171f0deaef0b987bfd0c.png) + +Sequence of actions: + +1. A data provider provides a self description of the piece of knowledge he likes to provide including the terms of conditions in his own data catalogue (Although the diagram depicts only one single instance of the Federated Datacatalog, each EDC of each participant (Provider or Consumer) runs a Datacatalog instance. Beween those synchronisation takes place) + * Graph assets describe means of domain ontologies the + * node classes + * relations (edges between nodes) + * constraints on nodes and relations (temporal, value ranges, regex patterns, ...) + * constraints on the queries/skills that may be executed on the graph (e.g. allowed and denied network connections) + * Graph policies will restrict the following operations on graphs (based on nodes and edges, given an execution context) + * selection + * traversion + * storage + * manipulation + * deletion + * delegation +2. A data provider marks particular graph assets as being visible in the federated data catalog. The federated data catalogues of the federated companies/EDCs will be automatically synchronized. +3. Any consuming app can employ an agent with a suitable skill/query (which can be provided locally or as a remote asset, too) +4. The agent will match the requirements in the skill with the offers in the federated data catalog to fill in the endpoints and usage policies from the self descriptions. +5. Agreements (between XA (5.1), XC (5.2), eventually between AB (5.3)) have to be set up in such a way that the corresponding agents are allowed to communicate through the data plane. +6. The agent delegates a sub-query/sub-skill to the respective knowledge owners (data provider C: 6.1, A: 6.2 and B: 6.3) via an instance of EDC. It annotates the sub-queries with a call context containing the EDC/agent calling sequence and the other assets to be joined with the result data. 6.3 shows that an agent can decide to delegate further down the line +7. The data plane will validate the calling context together with the claims inside the agreement token. +8. The agent executes the actual query by mapping to a backend data system and finally providing the result to the app + +Just as the Federated Datacatalog is a multi-instance-synchronised component, also the Federated Trust is an instance running on each EDC. All Federated Trust instances are synchronised with each other within the referring EDC ecosystem. + +## Deployment View + +See chapter [Deployment](https://eclipse-tractusx.github.io/docs-kits/kits/knowledge-agents/operation-view/deployment) of the Agents KIT. + +(C) 2021,2024 Contributors to the Eclipse Foundation. SPDX-License-Identifier: CC-BY-4.0 diff --git a/matchmaking/README.md b/matchmaking/README.md index 7c6d1bc5..50adefa2 100644 --- a/matchmaking/README.md +++ b/matchmaking/README.md @@ -116,48 +116,4 @@ As with all Docker images, these likely also contain other software which may be As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within. -### Helm Chart -A helm chart for deploying the matchmaking agent can be found under [this folder](../charts/matchmaking-agent). - -It can be added to your umbrella chart.yaml by the following snippet - -```console -dependencies: - - name: matchmaking-agent - repository: https://eclipse-tractusx.github.io/charts/dev - version: 1.14.24-SNAPSHOT - alias: my-matchmmaking-agent -``` - -and then installed using - -```console -helm dependency update -``` - -In your values.yml, you configure your specific instance of the matchmaking agent like this - -```console -############################################################################################## -# Matchmaking Agent -############################################################################################## - -my-matchmaking-agent: - securityContext: *securityContext - nameOverride: my-matchmaking-agent - fullnameOverride: my-matchmaking-agent - ingresses: - - enabled: true - # -- The hostname to be used to precisely map incoming traffic onto the underlying network service - hostname: "my-matchmaking-agent.public-ip" - annotations: - nginx.ingress.kubernetes.io/rewrite-target: /$1 - nginx.ingress.kubernetes.io/use-regex: "true" - # -- Agent endpoints exposed by this ingress resource - endpoints: - - default - tls: - enabled: true - secretName: my-conforming-tls -``` diff --git a/provisioning/README.md b/provisioning/README.md index 9f6929a9..e6a8d2f0 100644 --- a/provisioning/README.md +++ b/provisioning/README.md @@ -286,102 +286,3 @@ Eclipse Tractus-X product(s) installed within the image: As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained). As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within. - -### Helm - -A helm chart for deploying the remoting agent can be found under [this folder](../charts/provisioning-agent). - -It can be added to your umbrella chart.yaml by the following snippet - -```console -dependencies: - - name: provisioning-agent - repository: https://eclipse-tractusx.github.io/charts/dev - version: 1.14.24-SNAPSHOT - alias: my-provider-agent -``` - -and then installed using - -```console -helm dependency update -``` - -In your values.yml, you configure your specific instance of the remoting agent like this - -```console -####################################################################################### -# Data Binding Agent -####################################################################################### - -my-provider-agent: - securityContext: *securityContext - nameOverride: my-provider-agent - fullnameOverride: my-provider-agent - resources: - requests: - cpu: 500m - # you should employ 512Mi per endpoint - memory: 1Gi - limits: - cpu: 500m - # you should employ 512Mi per endpoint - memory: 1Gi - bindings: - # disables the default sample binding - dtc: null - # real production mapping - telematics2: - port: 8081 - path: /t2/(.*) - settings: - jdbc.url: 'jdbc:postgresql://intradb:5432/schema' - jdbc.user: - jdbc.password: - jdbc.driver: 'org.postgresql.Driver' - ontology: cx-ontology.xml - mapping: |- - [PrefixDeclaration] - cx-common: https://w3id.org/catenax/ontology/common# - cx-core: https://w3id.org/catenax/ontology/core# - cx-vehicle: https://w3id.org/catenax/ontology/vehicle# - cx-reliability: https://w3id.org/catenax/ontology/reliability# - uuid: urn:uuid: - bpnl: bpn:legal: - owl: http://www.w3.org/2002/07/owl# - rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns# - xml: http://www.w3.org/XML/1998/namespace - xsd: http://www.w3.org/2001/XMLSchema# - json: https://json-schema.org/draft/2020-12/schema# - obda: https://w3id.org/obda/vocabulary# - rdfs: http://www.w3.org/2000/01/rdf-schema# - oem: urn:oem: - - [MappingDeclaration] @collection [[ - mappingId vehicles - target <{vehicle_id}> rdf:type cx-vehicle:Vehicle ; cx-vehicle:vehicleIdentificationNumber {van}^^xsd:string; cx-vehicle:worldManufaturerId bpnl:{localIdentifiers_manufacturerId}; cx-vehicle:productionDate {production_date}^^xsd:date. - source SELECT vehicle_id, van, 'BPNL0000000DUMMY' as localIdentifiers_manufacturerId, production_date FROM vehicles - - mappingId partsvehicle - target <{gearbox_id}> cx-vehicle:isPartOf <{vehicle_id}> . - source SELECT vehicle_id, gearbox_id FROM vehicles - - mappingId vehicleparts - target <{vehicle_id}> cx-vehicle:hasPart <{gearbox_id}> . - source SELECT vehicle_id, gearbox_id FROM vehicles - - ]] - ingresses: - - enabled: true - # -- The hostname to be used to precisely map incoming traffic onto the underlying network service - hostname: "my-provider-agent.public.ip" - annotations: - nginx.ingress.kubernetes.io/rewrite-target: /$1 - nginx.ingress.kubernetes.io/use-regex: "true" - # -- Agent endpoints exposed by this ingress resource - endpoints: - - telematics2 - tls: - enabled: true - secretName: my-provider-tls -``` diff --git a/remoting/README.md b/remoting/README.md index 93aa8d9b..966582b1 100644 --- a/remoting/README.md +++ b/remoting/README.md @@ -214,9 +214,9 @@ As with all Docker images, these likely also contain other software which may be As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within. -### Helm Chart +## Helm Chart for Remoting Agent -A helm chart for deploying the remoting agent can be found under [this folder](../charts/remoting-agent). +A helm chart for deploying the remoting agent can be found under [this folder](../../charts/remoting-agent). It can be added to your umbrella chart.yaml by the following snippet