Welcome to the documentation for the Dataset Recommendation Service.
FastAPI 0.1.0¶
DataGEMS Recommendation Service¶
POST /dataset-recsys/recommend¶
Get recommendations
Description
Retrieve the top-N recommendations for a given dataset.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No | |
entity_id |
query | string | No | The dataset identifier. | |
n |
query | integer | 10 | No | Number of similar items to return |
Responses
{
"entity_id": "9b25bc46-8bd3-4f7f-94b4-52dbc38c130f",
"recommendations": [
{
"entity_id": "67f22d91-2b1a-4e8c-8f92-52dbc38c130f"
},
{
"entity_id": "climate-data-v2"
},
{
"entity_id": "european-soil-maps-2023"
}
]
}
{
"entity_id": "non-existent-or-unrelated.pdf",
"recommendations": []
}
Schema of the response body
{
"properties": {
"entity_id": {
"type": "string",
"title": "Entity Id",
"description": "The ID of the entity for which we want recommendations"
},
"recommendations": {
"items": {
"$ref": "#/components/schemas/Recommendation"
},
"type": "array",
"title": "Recommendations",
"description": "List of recommendations"
}
},
"type": "object",
"required": [
"entity_id",
"recommendations"
],
"title": "RecsResponse"
}
{
"code": 102,
"error": "Validation Error",
"message": [
{
"Key": "query.entity_id",
"Value": [
"field required"
]
}
]
}
Schema of the response body
{
"code": 401,
"error": "Could not validate credentials"
}
Schema of the response body
{
"code": 403,
"error": "Forbidden",
"message": "Insufficient permissions for the requested entity_id."
}
Schema of the response body
{
"code": 500,
"error": "Internal server error"
}
Schema of the response body
POST /dataset-recsys/recommend/ap¶
Get recommendations via Analytical Pattern
Description
Processes an Analytical Pattern (AP) request by extracting the seed dataset and returning its top-N recommendations as part of an enriched graph.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"nodes": [
{
"id": "user-session-123",
"labels": [
"User"
]
},
{
"id": "task-rec-001",
"labels": [
"Task"
],
"properties": {
"name": "Get recommendations",
"description": "Retrieve the top-N recommendations for a given dataset."
}
},
{
"id": "pattern-ds-recs",
"labels": [
"Analytical_Pattern"
],
"properties": {
"name": "Dataset-to-Dataset Recommendations AP",
"description": "Pattern for discovering related datasets.",
"process": "recommend",
"publishedDate": "2026-01-21",
"startTime": "10:00:00"
}
},
{
"id": "operator-recommender",
"labels": [
"DatasetRecommender_Operator"
],
"properties": {
"name": "GetRecommendations Operator",
"command": "get_recommendations",
"n": 10
}
},
{
"id": "9b25bc46-8bd3-4f7f-94b4-52dbc38c130f",
"labels": [
"sc:Dataset"
],
"properties": {
"description": "The seed dataset used as the basis for recommendations."
}
}
],
"edges": [
{
"from": "user-session-123",
"to": "task-rec-001",
"labels": [
"request"
]
},
{
"from": "task-rec-001",
"to": "pattern-ds-recs",
"labels": [
"is_accomplished"
]
},
{
"from": "pattern-ds-recs",
"to": "operator-recommender",
"labels": [
"consist_of"
]
},
{
"from": "9b25bc46-8bd3-4f7f-94b4-52dbc38c130f",
"to": "operator-recommender",
"labels": [
"input"
]
}
]
}
Schema of the request body
{
"additionalProperties": true,
"type": "object",
"title": "Analytical Pattern",
"description": "The Analytical Pattern graph in JSON format"
}
Responses
{
"nodes": [
{
"id": "user-session-123",
"labels": [
"User"
]
},
{
"id": "task-rec-001",
"labels": [
"Task"
],
"properties": {
"name": "Get recommendations",
"description": "Retrieve the top-N recommendations for a given dataset."
}
},
{
"id": "pattern-ds-recs",
"labels": [
"Analytical_Pattern"
],
"properties": {
"name": "Dataset-to-Dataset Recommendations AP",
"description": "Retrieve top-N recommendations for a given dataset.",
"process": "recommend",
"publishedDate": "2026-01-21",
"startTime": "10:00:00"
}
},
{
"id": "operator-recommender",
"labels": [
"DatasetRecommender_Operator"
],
"properties": {
"name": "GetRecommendations Operator",
"description": "Dataset-to-Dataset recommender operator.",
"command": "get_recommendations",
"n": 2
}
},
{
"id": "seed-dataset-001",
"labels": [
"sc:Dataset"
],
"properties": {
"name": "Seed Dataset"
}
},
{
"id": "recommended-entity-1",
"labels": [
"sc:Dataset"
],
"properties": {
"name": "Recommended Entity 1"
}
},
{
"id": "recommended-entity-2",
"labels": [
"sc:Dataset"
],
"properties": {
"name": "Recommended Entity 2"
}
}
],
"edges": [
{
"from": "user-session-123",
"to": "task-rec-001",
"labels": [
"request"
]
},
{
"from": "task-rec-001",
"to": "pattern-ds-recs",
"labels": [
"is_accomplished"
]
},
{
"from": "pattern-ds-recs",
"to": "operator-recommender",
"labels": [
"consist_of"
]
},
{
"from": "seed-dataset-001",
"to": "operator-recommender",
"labels": [
"input"
]
},
{
"from": "operator-recommender",
"to": "recommended-entity-1",
"labels": [
"output"
],
"properties": {
"rank": 1
}
},
{
"from": "operator-recommender",
"to": "recommended-entity-2",
"labels": [
"output"
],
"properties": {
"rank": 2
}
}
]
}
Schema of the response body
{
"code": 403,
"error": "Forbidden",
"message": "Insufficient permissions for the requested entity_id."
}
Schema of the response body
{
"code": 422,
"error": "Malformed AP Graph: No input dataset linked to the Recommender Operator."
}
{
"code": 422,
"error": "Malformed AP Graph: Operator 'DatasetRecommender_Operator' not found."
}
Schema of the response body
{
"code": 500,
"error": "Internal server error"
}
Schema of the response body
POST /dataset-recsys/dataset/add¶
Add a new dataset to the system
Description
Fetch a dataset from external sources, generate its embeddings, and integrate it into the recommendation engine. If the dataset already exists, the system will skip the addition to avoid duplicates.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No | |
application |
query | string | portal | No | The application context for the dataset. |
entity_id |
query | string | No | The dataset identifier to add. |
Responses
{
"status": "success",
"message": "Dataset ds_123 successfully added and recommendations updated."
}
Schema of the response body
{
"code": 401,
"error": "Could not validate credentials"
}
Schema of the response body
{
"code": 403,
"error": "Forbidden",
"message": "Insufficient permissions for the requested entity_id."
}
Schema of the response body
{
"code": 102,
"error": "Validation Error",
"message": [
{
"Key": "query.entity_id",
"Value": [
"field required"
]
}
]
}
Schema of the response body
{
"detail": "Dataset not found in external repository."
}
Schema of the response body
{
"code": 500,
"error": "Internal server error"
}
Schema of the response body
POST /dataset-recsys/dataset/remove¶
Remove a dataset from the system
Description
Performs a clean, incremental removal of a dataset from the recommendation engine.
Workflow: 1. Inbound Cleanup: Scans the Redis index to find every other dataset currently recommending this ID and removes the reference. 2. Outbound Cleanup: Deletes the specific recommendation list (ZSET) for this dataset. 3. Index Cleanup: Removes the dataset ID from the application's global index. 4. Vector Cleanup: Deletes the embedding record from the PostgreSQL vector database.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No | |
application |
query | string | portal | No | The application context for the dataset. |
entity_id |
query | string | No | The unique identifier of the dataset to be removed. |
Responses
{
"status": "success",
"message": "Dataset ds_123 removed."
}
Schema of the response body
{
"detail": "Dataset not found in the recommendation engine."
}
Schema of the response body
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
MathE Recommendation Service¶
POST /dataset-recsys/mathe/recommend¶
Get recommendations
Description
Retrieve the top-N recommendations for a given educational material (only PDFs are currently supported).
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
entity_id |
query | string | No | The MathE material identifier (for example, `6.pdf`). | |
n |
query | integer | 10 | No | Number of similar items to return |
Responses
{
"entity_id": "string",
"recommendations": [
{
"entity_id": "string"
}
]
}
Schema of the response body
{
"properties": {
"entity_id": {
"type": "string",
"title": "Entity Id",
"description": "The ID of the entity for which we want recommendations"
},
"recommendations": {
"items": {
"$ref": "#/components/schemas/Recommendation"
},
"type": "array",
"title": "Recommendations",
"description": "List of recommendations"
}
},
"type": "object",
"required": [
"entity_id",
"recommendations"
],
"title": "RecsResponse"
}
{
"detail": [
{
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}
Service Health¶
GET /dataset-recsys/health¶
Health check
Description
Check if the API, Redis, and vector database are responsive.
Responses
Schema of the response body
GET /dataset-recsys/¶
Root endpoint
Description
Root endpoint to verify that the service is running.
Responses
Schema of the response body
GET /dataset-recsys/debug/schema¶
Get database schema
Description
Retrieve the database schema for the embedding storage.
Responses
Schema of the response body
Schemas¶
HTTPValidationError¶
| Name | Type | Description |
|---|---|---|
detail |
Array<ValidationError> |
Recommendation¶
| Name | Type | Description |
|---|---|---|
entity_id |
string | The recommended entity ID |
RecsResponse¶
| Name | Type | Description |
|---|---|---|
entity_id |
string | The ID of the entity for which we want recommendations |
recommendations |
Array<Recommendation> | List of recommendations |
ValidationError¶
| Name | Type | Description |
|---|---|---|
loc |
Array<> | |
msg |
string | |
type |
string |
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| OAuth2PasswordBearer | oauth2 |