# Semantic extensions of Knowledge Model API enabling AI Agents

Building up semantic understanding of Celonis data in a specific business context (Knowledge Model - KM) so that third-party (3P) AI Agents can figure out the right way to query Celonis data.
Therefore, the Knowledge Model API is being enhanced to provide:

- **Structure discovery**: A new endpoint focusing on the KM data structures (including schema and description).
- **Content discovery**: A new endpoint providing statistical profiling of the data contents per KM record.
- **Relationship discovery**: To be added in the future.
Future extensions will include the supply of the necessary process context to the 3P AI agents to power business process automation.


## 3P AI Agent Enablement (BETA program) [1]

### Knowledge Model Semantic OpenAPI Spec

To retrieve the semantic specification of a Knowledge Model - KM (according to [Open API Initiative](https://spec.openapis.org/oas/latest.html)), either in `json` or `yml` format, you need to consume the endpoint:
`GET /knowledge-models/{{km-id}}/spec`
You have the option to select either all KM records (including the *auto-generated*) or only the *curated* ones by submitting the parameter `curated=true`.
The Knowledge Model semantic metadata, including **schema** and **data descriptions**, are shared with the 3P agent enabling them to understand Celonis context and data.

### Knowledge Model Record Semantic Data Content Statistics

To retrieve the Knowledge Model - KM record content statistics, you need to consume the endpoint:
`GET /knowledge-models/{{km-id}}/records/{{record-id}}/summary`
The results contain:

- The **Schema** array
- The **Data Sample** array
- The **Shape** array (number of rows, number of columns
- The **Column Summary Statistics** array including the following metrics for each KM record field (excluding KPIs, flags and augmented attributes):
  - `count`: Number of non-null values (applicable to all field types)
  - `unique`: Number of unique non-null values (applicable only to strings & timestamps)
  - `top`: Most frequent value (applicable only to strings & timestamps)
  - `freq`: Frequency of the most frequent value (applicable only to strings & timestamps)
  - `mean`: Mean of the values (applicable only to numeric fields)
  - `std`: Standard deviation of the values (applicable only to numeric fields)
  - `min`: Minimum value (applicable only to numeric fields)
  - `max`: Maximum value (applicable only to numeric fields)
  - `25% percentile`: (applicable only to numeric fields)
  - `50% percentile`: (applicable only to numeric fields)
  - `75% percentile`: (applicable only to numeric fields)
The optional parameters controlling which data will be analyzed are:
- `filters`: The filters to be applied on data contents (column statistic profiling may differ significantly depending on the applied filter); default `none`
- `fields`: The fields whose contents will be analyzed (if omitted all record fields will be statistically profiled); default `all`
- `excludeFields`: The fields to exclude from the statistical analysis; default `none`
- `sampleSize`: For requesting a specific number of rows for the data; default `10`


### Knowledge Model Semantic Query

To query the Knowledge Model, you need to consume the endpoint:
`GET /knowledge-models/{{km-id}}/query`. The parameters of [/query](https://developer.celonis.com/process-intelligence-apis/knowledge-model-api/api-reference/openapi/reference/operation/getKnowledgeModelQueryResult/) are similar to [/data](https://developer.celonis.com/process-intelligence-apis/knowledge-model-api/api-reference/openapi/reference/operation/getRecordDataResult/) endpoint with the difference that we have an optional parameter called `kpis` to retrieve the KPIs of the knowledge model.
The response format is structured as a json object compared to the array of name and value. You can refer to the [/query](https://developer.celonis.com/process-intelligence-apis/knowledge-model-api/api-reference/openapi/reference/operation/getKnowledgeModelQueryResult/) endpoint for more information.

### Knowledge Model Record Semantic Query

To query the Knowledge Model - KM record data, you need to consume the endpoint:
`GET /knowledge-models/{{km-id}}/records/{{record-id}}/query`
The same parameters as the [/data](https://developer.celonis.com/process-intelligence-apis/knowledge-model-api/api-reference/openapi/reference/operation/getRecordDataResult/) endpoint are supported with the only difference that `fields` is optional. If omitted, all KM record fields are included.
The response format is structured as a json object compared to the array of name. An example is provided here [/record/query](https://developer.celonis.com/process-intelligence-apis/knowledge-model-api/api-reference/openapi/reference/operation/getRecordQueryResult/).

### Fuzzy Search

This feature fuzzy string search try to find the best match in a string.
It is found in the following endpoints: [/query](https://developer.celonis.com/process-intelligence-apis/knowledge-model-api/api-reference/openapi/reference/operation/getKnowledgeModelQueryResult/), [/record/query](https://developer.celonis.com/process-intelligence-apis/knowledge-model-api/api-reference/openapi/reference/operation/getRecordQueryResult/) and [/data](https://developer.celonis.com/process-intelligence-apis/knowledge-model-api/api-reference/openapi/reference/operation/getRecordDataResult/).


**[1]:** Contact your Celonis account team if you want to join the 3P AI Agent Enablement Beta program.