DataGEMs WP3 Demo API 0.4.0¶
A collection of APIs for DataGEMs WP3
base¶
GET /¶
Read Root
Responses
Schema of the response body
GET /health¶
Health
Responses
Schema of the response body
questionTools¶
POST /decompose¶
Decompose
Description
Return a deterministic QDMR-style plan via DecomposeTool.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"concept": null,
"question": "string",
"slices": null
}
Schema of the request body
{
"properties": {
"concept": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional concept override; otherwise extracted from the question.",
"title": "Concept"
},
"question": {
"description": "Natural-language question.",
"minLength": 1,
"title": "Question",
"type": "string"
},
"slices": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/ComparisonSlice"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Optional comparison slices; defaults to 1800s vs present.",
"title": "Slices"
}
},
"required": [
"question"
],
"title": "LanguageQuery",
"type": "object"
}
Responses
{
"concept": "string",
"qdmr": [
{}
],
"question": "string",
"slices": [
{
"corpus_id": "string",
"label": "string",
"language": "string",
"period_end": 0,
"period_start": 0,
"slice_id": "string"
}
]
}
Schema of the response body
{
"properties": {
"concept": {
"title": "Concept",
"type": "string"
},
"qdmr": {
"items": {
"additionalProperties": true,
"type": "object"
},
"title": "Qdmr",
"type": "array"
},
"question": {
"title": "Question",
"type": "string"
},
"slices": {
"items": {
"$ref": "#/components/schemas/ComparisonSlice"
},
"title": "Slices",
"type": "array"
}
},
"required": [
"question",
"concept",
"slices",
"qdmr"
],
"title": "DecomposeResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
POST /extendKnowledge¶
Extend Knowledge
Description
Expand facets/lemmas and build sub-questions via ExtendKnowledgeTool.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"concept": null,
"question": "string",
"slices": null
}
Schema of the request body
{
"properties": {
"concept": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional concept override; otherwise extracted from the question.",
"title": "Concept"
},
"question": {
"description": "Natural-language question.",
"minLength": 1,
"title": "Question",
"type": "string"
},
"slices": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/ComparisonSlice"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Optional comparison slices; defaults to 1800s vs present.",
"title": "Slices"
}
},
"required": [
"question"
],
"title": "LanguageQuery",
"type": "object"
}
Responses
{
"concept": "string",
"expansion": {},
"generated_subquestions": [
{}
],
"question": "string",
"slices": [
{
"corpus_id": "string",
"label": "string",
"language": "string",
"period_end": 0,
"period_start": 0,
"slice_id": "string"
}
]
}
Schema of the response body
{
"properties": {
"concept": {
"title": "Concept",
"type": "string"
},
"expansion": {
"additionalProperties": true,
"title": "Expansion",
"type": "object"
},
"generated_subquestions": {
"items": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"title": "Generated Subquestions",
"type": "array"
},
"question": {
"title": "Question",
"type": "string"
},
"slices": {
"items": {
"$ref": "#/components/schemas/ComparisonSlice"
},
"title": "Slices",
"type": "array"
}
},
"required": [
"question",
"concept",
"slices",
"expansion",
"generated_subquestions"
],
"title": "ExtendKnowledgeResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
POST /nlgEvaluate¶
Nlg Evaluate
Description
Score an answer against exact ground truth via NlgEvaluateTool.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"answer": "string",
"ground_truth": null,
"query_id": null,
"question": "string"
}
Schema of the request body
{
"properties": {
"answer": {
"minLength": 1,
"title": "Answer",
"type": "string"
},
"ground_truth": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional inline gold. Otherwise exact Question_ID or question text from data/nlg/.",
"title": "Ground Truth"
},
"query_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Query Id"
},
"question": {
"minLength": 1,
"title": "Question",
"type": "string"
}
},
"required": [
"question",
"answer"
],
"title": "NlgEvaluateQuery",
"type": "object"
}
Responses
{
"concept": "string",
"gold_question": "string",
"gold_source": "string",
"ground_truth": "string",
"match": "string",
"matched": true,
"metrics": {},
"question_id": "string",
"summary": "string"
}
Schema of the response body
{
"properties": {
"concept": {
"default": "",
"title": "Concept",
"type": "string"
},
"gold_question": {
"default": "",
"title": "Gold Question",
"type": "string"
},
"gold_source": {
"default": "",
"title": "Gold Source",
"type": "string"
},
"ground_truth": {
"default": "",
"title": "Ground Truth",
"type": "string"
},
"match": {
"default": "",
"title": "Match",
"type": "string"
},
"matched": {
"title": "Matched",
"type": "boolean"
},
"metrics": {
"additionalProperties": {
"type": "number"
},
"title": "Metrics",
"type": "object"
},
"question_id": {
"default": "",
"title": "Question Id",
"type": "string"
},
"summary": {
"default": "",
"title": "Summary",
"type": "string"
}
},
"required": [
"matched"
],
"title": "NlgEvaluateResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
},
{
"Key": "answer",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
explore¶
GET /explore¶
Explore
Description
Explore natural-language questions via the meteo agent pipeline.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No | |
question |
query | string | No |
Responses
{
"db_fetch_time_s": 10.12,
"inference_time_s": 10.12,
"input_params": null,
"question": "string",
"reasoning": null,
"sql_pattern": null,
"sql_query": null,
"sql_results": null
}
Schema of the response body
{
"additionalProperties": true,
"description": "Response from GET /explore (meteo agent pipeline).",
"properties": {
"db_fetch_time_s": {
"description": "Database fetch/execution time in seconds.",
"title": "Db Fetch Time S",
"type": "number"
},
"inference_time_s": {
"description": "LLM inference time in seconds (excluding DB fetch).",
"title": "Inference Time S",
"type": "number"
},
"input_params": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/InputParam"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Coordinate parameters used in the query.",
"title": "Input Params"
},
"question": {
"description": "The natural-language question explored.",
"title": "Question",
"type": "string"
},
"reasoning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Reasoning behind SQL generation.",
"title": "Reasoning"
},
"sql_pattern": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Generated SQL template.",
"title": "Sql Pattern"
},
"sql_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Executable SQL with literals filled in.",
"title": "Sql Query"
},
"sql_results": {
"anyOf": [
{
"$ref": "#/components/schemas/SQLResults"
},
{
"type": "null"
}
],
"description": "Results from executing the SQL query."
}
},
"required": [
"question",
"inference_time_s",
"db_fetch_time_s"
],
"title": "ExploreResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
explore4ap¶
POST /explore4ap¶
Explore4Ap Query
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"ap": {
"edges": null,
"nodes": [
{
"id": null,
"labels": null,
"properties": null
}
]
}
}
Schema of the request body
{
"additionalProperties": true,
"description": "Request body for POST /explore4ap.",
"properties": {
"ap": {
"$ref": "#/components/schemas/APPayloadBody"
}
},
"required": [
"ap"
],
"title": "Explore4APRequest",
"type": "object"
}
Responses
{
"ap": {
"edges": null,
"nodes": [
{
"id": null,
"labels": null,
"properties": null
}
]
},
"metadata": null
}
Schema of the response body
{
"additionalProperties": true,
"description": "Response body for POST /explore4ap.",
"properties": {
"ap": {
"$ref": "#/components/schemas/APPayloadBody"
},
"metadata": {
"anyOf": [
{
"$ref": "#/components/schemas/Explore4APMetadata"
},
{
"type": "null"
}
]
}
},
"required": [
"ap"
],
"title": "Explore4APResponse",
"type": "object"
}
{
"detail": [
{
"ctx": {},
"input": null,
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"title": "Detail",
"type": "array"
}
},
"title": "HTTPValidationError",
"type": "object"
}
keywordMatching¶
POST /keywordMatching¶
Keyword Matching Query
Description
Rank candidate keywords against an uploaded PDF or text document.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"candidates": [
"string"
],
"file": null,
"k": 0,
"method": "hybrid",
"text": null
}
Schema of the request body
{
"properties": {
"candidates": {
"description": "Mandatory list of candidate keywords to rank against the document. Can be passed as repeated form fields or a JSON array string.",
"items": {
"type": "string"
},
"title": "Candidates",
"type": "array"
},
"file": {
"anyOf": [
{
"contentMediaType": "application/octet-stream",
"type": "string"
},
{
"type": "null"
}
],
"description": "PDF document to parse into Markdown (mutually exclusive with 'text').",
"title": "File"
},
"k": {
"default": 10,
"description": "Maximum number of top-ranked keywords to return.",
"minimum": 1.0,
"title": "K",
"type": "integer"
},
"method": {
"$ref": "#/components/schemas/KeywordMatchingMethod",
"default": "hybrid",
"description": "Retrieval method: 'hybrid' (default), 'dense', or 'sparse'."
},
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Raw text or Markdown document content (mutually exclusive with 'file').",
"title": "Text"
}
},
"required": [
"candidates"
],
"title": "Body_keyword_matching_query_keywordMatching_post",
"type": "object"
}
Responses
{
"k": 2,
"method": "hybrid",
"results": [
{
"candidate": "parabola",
"dense_score": 0.8412,
"rank": 1,
"score": 0.032787,
"sparse_score": 4.2105
},
{
"candidate": "integral calculus",
"dense_score": 0.7931,
"rank": 2,
"score": 0.032258,
"sparse_score": 3.1042
}
],
"total_candidates": 3
}
Schema of the response body
{
"example": {
"k": 2,
"method": "hybrid",
"results": [
{
"candidate": "parabola",
"dense_score": 0.8412,
"rank": 1,
"score": 0.032787,
"sparse_score": 4.2105
},
{
"candidate": "integral calculus",
"dense_score": 0.7931,
"rank": 2,
"score": 0.032258,
"sparse_score": 3.1042
}
],
"total_candidates": 3
},
"properties": {
"k": {
"description": "Number of top-ranked keywords returned.",
"title": "K",
"type": "integer"
},
"method": {
"$ref": "#/components/schemas/KeywordMatchingMethod",
"description": "Retrieval method used to rank candidates."
},
"results": {
"description": "Ranked list of candidate keywords matching the document.",
"items": {
"$ref": "#/components/schemas/KeywordMatchResult"
},
"title": "Results",
"type": "array"
},
"total_candidates": {
"description": "Total number of unique candidate keywords evaluated.",
"title": "Total Candidates",
"type": "integer"
}
},
"required": [
"method",
"k",
"total_candidates",
"results"
],
"title": "KeywordMatchingResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "candidates",
"Value": [
"Field required"
]
},
{
"Key": "file",
"Value": [
"Either 'file' (PDF) or 'text' must be provided."
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
linguisticFeatures¶
POST /linguisticFeatures¶
Linguistic Features Query
Description
Compute deterministic linguistic features for RAG content chunks.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"question": "What is the chief town of the island of COPRAJA?",
"rag_output": {
"query_time": 3263.56,
"results": [
{
"content": "COPRAJA, an island in the Mediterranean Sea... The chief town is Tratozzio.",
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"metadata": {
"language": "en",
"original_filename": "kp-eb0707-031203-1328-v2.xml",
"year": "1823-1887"
},
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
},
"requested_features": [
"term_frequency",
"collocations"
]
}
Schema of the request body
{
"properties": {
"question": {
"description": "The user question that should be answered from the provided RAG chunks.",
"example": "What is the chief town of the island of COPRAJA?",
"minLength": 1,
"title": "Question",
"type": "string"
},
"rag_output": {
"additionalProperties": true,
"description": "Raw RAG output containing retrieved chunks and metadata.",
"example": {
"query_time": 3263.56,
"results": [
{
"content": "COPRAJA, an island in the Mediterranean Sea... The chief town is Tratozzio.",
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"metadata": {
"language": "en",
"original_filename": "kp-eb0707-031203-1328-v2.xml",
"year": "1823-1887"
},
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
},
"title": "Rag Output",
"type": "object"
},
"requested_features": {
"description": "Optional subset of linguistic features to return. If omitted or empty, all supported features are returned.",
"example": [
"term_frequency",
"collocations"
],
"items": {
"$ref": "#/components/schemas/LinguisticFeatureName"
},
"title": "Requested Features",
"type": "array"
}
},
"required": [
"question",
"rag_output"
],
"title": "LinguisticFeaturesQuery",
"type": "object"
}
Responses
{
"features": [
{
"collocations": [
{
"association_score": 2.807355,
"count": 1,
"terms": [
"chief",
"town"
]
},
{
"association_score": 2.807355,
"count": 1,
"terms": [
"copraja",
"island"
]
},
{
"association_score": 2.807355,
"count": 1,
"terms": [
"island",
"mediterranean"
]
},
{
"association_score": 2.807355,
"count": 1,
"terms": [
"mediterranean",
"sea"
]
},
{
"association_score": 2.807355,
"count": 1,
"terms": [
"sea",
"chief"
]
},
{
"association_score": 2.807355,
"count": 1,
"terms": [
"town",
"tratozzio"
]
}
],
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"object_id": "kp-eb0707-031203-1328-v2.xml",
"sentiment_profile": {
"label": "neutral",
"negative_terms": 0,
"neutral_terms": 12,
"polarity_score": 0.0,
"positive_terms": 0,
"subjectivity_score": 0.0,
"total_terms": 12
},
"similarity": 1.0,
"term_frequency": [
{
"count": 1,
"frequency": 0.142857,
"term": "chief"
},
{
"count": 1,
"frequency": 0.142857,
"term": "copraja"
},
{
"count": 1,
"frequency": 0.142857,
"term": "island"
},
{
"count": 1,
"frequency": 0.142857,
"term": "mediterranean"
},
{
"count": 1,
"frequency": 0.142857,
"term": "sea"
},
{
"count": 1,
"frequency": 0.142857,
"term": "town"
},
{
"count": 1,
"frequency": 0.142857,
"term": "tratozzio"
}
]
}
],
"used_chunks": [
{
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
}
Schema of the response body
{
"example": {
"features": [
{
"collocations": [
{
"association_score": 2.807355,
"count": 1,
"terms": [
"chief",
"town"
]
},
{
"association_score": 2.807355,
"count": 1,
"terms": [
"copraja",
"island"
]
},
{
"association_score": 2.807355,
"count": 1,
"terms": [
"island",
"mediterranean"
]
},
{
"association_score": 2.807355,
"count": 1,
"terms": [
"mediterranean",
"sea"
]
},
{
"association_score": 2.807355,
"count": 1,
"terms": [
"sea",
"chief"
]
},
{
"association_score": 2.807355,
"count": 1,
"terms": [
"town",
"tratozzio"
]
}
],
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"object_id": "kp-eb0707-031203-1328-v2.xml",
"sentiment_profile": {
"label": "neutral",
"negative_terms": 0,
"neutral_terms": 12,
"polarity_score": 0.0,
"positive_terms": 0,
"subjectivity_score": 0.0,
"total_terms": 12
},
"similarity": 1.0,
"term_frequency": [
{
"count": 1,
"frequency": 0.142857,
"term": "chief"
},
{
"count": 1,
"frequency": 0.142857,
"term": "copraja"
},
{
"count": 1,
"frequency": 0.142857,
"term": "island"
},
{
"count": 1,
"frequency": 0.142857,
"term": "mediterranean"
},
{
"count": 1,
"frequency": 0.142857,
"term": "sea"
},
{
"count": 1,
"frequency": 0.142857,
"term": "town"
},
{
"count": 1,
"frequency": 0.142857,
"term": "tratozzio"
}
]
}
],
"used_chunks": [
{
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
},
"properties": {
"features": {
"description": "Linguistic features calculated for each selected chunk.",
"items": {
"$ref": "#/components/schemas/LinguisticFeaturesChunk"
},
"title": "Features",
"type": "array"
},
"used_chunks": {
"description": "Sources used by the linguistic feature step.",
"items": {
"$ref": "#/components/schemas/SummarySource"
},
"title": "Used Chunks",
"type": "array"
}
},
"required": [
"features",
"used_chunks"
],
"title": "LinguisticFeaturesResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
},
{
"Key": "rag_output.results",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
geospatial¶
GET /text2geo¶
Geospatial Query
Description
Handle geospatial queries using OverpassQLTool.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No | |
question |
query | string | No |
Responses
{
"most_relevant_wikidata": {
"place": "Zurich",
"reasoning": "The question asks for the city of Zurich, which is best represented by the entity with ID Q72. This entity is described as the capital of the canton of Zurich and is a municipality and city in Switzerland. It also has 'found_osm_json: True', which gives it priority if multiple similar entities were found. Other entities like universities or sports clubs are not relevant to the context of the question, which specifically asks for the city.",
"wiki_id": "Q72",
"wiki_properties": {
"aliases": "City of Zurich, ZH, Stadt Zürich, Zurich, Switzerland, Zürich",
"coordinate location": "47.37444444444444, 8.54111111111111",
"country": "Switzerland, Old Swiss Confederacy, Helvetic Republic, Switzerland",
"description": "capital of the canton of Zurich, Switzerland",
"found_osm_json": true,
"instance of": "municipality of Switzerland, city of Switzerland, cantonal capital of Switzerland, college town, largest city, big city",
"label": "Zurich",
"located in the administrative territorial entity": "Zürich District",
"part of": "Greater Zurich Area, Zurich metropolitan area, Canton of Zürich"
}
},
"oql": {
"OQL": "area[\"ISO3166-1\"=\"CH\"]->.searchArea;(nwr[\"wikidata\"=\"Q72\"];);",
"reasoning": "Generated Overpass QL query using Wikidata ID Q72 and country ISO alpha-2 code CH."
},
"place": "zurich",
"results": {
"bounds": {
"maxlat": 47.4346662,
"maxlon": 8.6254413,
"minlat": 47.3202187,
"minlon": 8.4480061
},
"center": [
47.4,
8.5
],
"geojson_data": {
"features": [],
"type": "FeatureCollection"
},
"points": [
{
"lat": "47.4",
"lon": "8.5"
}
]
}
}
Schema of the response body
{
"example": {
"most_relevant_wikidata": {
"place": "Zurich",
"reasoning": "The question asks for the city of Zurich, which is best represented by the entity with ID Q72. This entity is described as the capital of the canton of Zurich and is a municipality and city in Switzerland. It also has 'found_osm_json: True', which gives it priority if multiple similar entities were found. Other entities like universities or sports clubs are not relevant to the context of the question, which specifically asks for the city.",
"wiki_id": "Q72",
"wiki_properties": {
"aliases": "City of Zurich, ZH, Stadt Zürich, Zurich, Switzerland, Zürich",
"coordinate location": "47.37444444444444, 8.54111111111111",
"country": "Switzerland, Old Swiss Confederacy, Helvetic Republic, Switzerland",
"description": "capital of the canton of Zurich, Switzerland",
"found_osm_json": true,
"instance of": "municipality of Switzerland, city of Switzerland, cantonal capital of Switzerland, college town, largest city, big city",
"label": "Zurich",
"located in the administrative territorial entity": "Zürich District",
"part of": "Greater Zurich Area, Zurich metropolitan area, Canton of Zürich"
}
},
"oql": {
"OQL": "area[\"ISO3166-1\"=\"CH\"]->.searchArea;(nwr[\"wikidata\"=\"Q72\"];);",
"reasoning": "Generated Overpass QL query using Wikidata ID Q72 and country ISO alpha-2 code CH."
},
"place": "zurich",
"results": {
"bounds": {
"maxlat": 47.4346662,
"maxlon": 8.6254413,
"minlat": 47.3202187,
"minlon": 8.4480061
},
"center": [
47.4,
8.5
],
"geojson_data": {
"features": [],
"type": "FeatureCollection"
},
"points": [
{
"lat": "47.4",
"lon": "8.5"
}
]
}
},
"properties": {
"most_relevant_wikidata": {
"$ref": "#/components/schemas/MostRelevantWikidata",
"description": "The most relevant Wikidata entity related to the query."
},
"oql": {
"$ref": "#/components/schemas/OQLResponse",
"description": "The OverpassQL query generated from the geospatial question."
},
"place": {
"description": "The place identified in the geospatial query.",
"title": "Place",
"type": "string"
},
"results": {
"$ref": "#/components/schemas/GeospatialResults",
"description": "The results of the OverpassQL query includes points, bounding box, multipolygons and centroid."
}
},
"required": [
"place",
"most_relevant_wikidata",
"oql",
"results"
],
"title": "GeospatialResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
text2sql¶
POST /text2sql¶
Text2Sql Query
Description
Handle text to SQL queries.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"parameters": {
"db_database": "database_name",
"db_host": "the_db_host_ip",
"db_pass": "db_password",
"db_port": 5432,
"db_schema": "database_schema",
"db_username": "db_username"
},
"question": "What are the average mean temperatures in the coordinates (latitude, longitude) in year 2020?"
}
Schema of the request body
{
"properties": {
"parameters": {
"$ref": "#/components/schemas/SQLQueryParameters",
"description": "The parameters for the SQL query, including results.",
"example": {
"db_info": {
"db_database": "database_name",
"db_host": "the_db_host_ip",
"db_pass": "db_password",
"db_port": 5432,
"db_schema": "database_schema",
"db_username": "db_username"
},
"results": {
"points": [
[
47.4,
8.4
],
[
47.4,
8.5
]
]
}
}
},
"question": {
"description": "The text question to be converted to SQL.",
"example": "What are the average mean temperatures in the coordinates (latitude, longitude) in year 2020?",
"title": "Question",
"type": "string"
}
},
"required": [
"question",
"parameters"
],
"title": "Text2SQLQuery",
"type": "object"
}
Responses
{
"input_params": [
{
"latitude": 47.4,
"longitude": 8.4
},
{
"latitude": 47.4,
"longitude": 8.5
}
],
"message": "Successfully generated SQL query on the first attempt.",
"model_name": "qwen-qwq",
"output_params": {
"coordinates": [
"latitude",
"longitude"
]
},
"params": {
"points": [
[
47.4,
8.4
],
[
47.4,
8.5
]
]
},
"question": "What are the average mean temperatures in the coordinates (lat, lon) in year 2020?",
"reasoning": "The SQL template calculates the average temperature in Celsius for the specified coordinates in 2020. The coordinates are rounded to 1 decimal place for matching. The meteo_tmean table is used for temperature data (tmean in Kelvin), converted to Celsius by subtracting 273.15. The WHERE clause filters records to the year 2020 and matches the rounded coordinates from the input parameters.",
"sql_pattern": "SELECT ROUND(CAST(latitude AS NUMERIC), 1) AS rounded_latitude, ROUND(CAST(longitude AS NUMERIC), 1) AS rounded_longitude, AVG(tmean - 273.15) AS avg_temp_celsius FROM era5_land2.meteo_tmean WHERE EXTRACT(YEAR FROM time) = 2020 AND (ROUND(CAST(latitude AS NUMERIC), 1), ROUND(CAST(longitude AS NUMERIC), 1)) IN {coordinates} GROUP BY rounded_latitude, rounded_longitude",
"sql_query": "SELECT ROUND(CAST(latitude AS NUMERIC), 1) AS rounded_latitude, ROUND(CAST(longitude AS NUMERIC), 1) AS rounded_longitude, AVG(tmean - 273.15) AS avg_temp_celsius FROM era5_land2.meteo_tmean WHERE EXTRACT(YEAR FROM time) = 2020 AND (ROUND(CAST(latitude AS NUMERIC), 1), ROUND(CAST(longitude AS NUMERIC), 1)) IN ((47.4, 8.4), (47.4, 8.5)) GROUP BY rounded_latitude, rounded_longitude",
"sql_results": {
"data": [
{
"avg_temp_celsius": 10.613293907290531,
"rounded_latitude": "47.4",
"rounded_longitude": "8.4"
},
{
"avg_temp_celsius": 10.440176525011696,
"rounded_latitude": "47.4",
"rounded_longitude": "8.5"
}
],
"status": "success"
},
"status": "success"
}
Schema of the response body
{
"example": {
"input_params": [
{
"latitude": 47.4,
"longitude": 8.4
},
{
"latitude": 47.4,
"longitude": 8.5
}
],
"message": "Successfully generated SQL query on the first attempt.",
"model_name": "qwen-qwq",
"output_params": {
"coordinates": [
"latitude",
"longitude"
]
},
"params": {
"points": [
[
47.4,
8.4
],
[
47.4,
8.5
]
]
},
"question": "What are the average mean temperatures in the coordinates (lat, lon) in year 2020?",
"reasoning": "The SQL template calculates the average temperature in Celsius for the specified coordinates in 2020. The coordinates are rounded to 1 decimal place for matching. The meteo_tmean table is used for temperature data (tmean in Kelvin), converted to Celsius by subtracting 273.15. The WHERE clause filters records to the year 2020 and matches the rounded coordinates from the input parameters.",
"sql_pattern": "SELECT ROUND(CAST(latitude AS NUMERIC), 1) AS rounded_latitude, ROUND(CAST(longitude AS NUMERIC), 1) AS rounded_longitude, AVG(tmean - 273.15) AS avg_temp_celsius FROM era5_land2.meteo_tmean WHERE EXTRACT(YEAR FROM time) = 2020 AND (ROUND(CAST(latitude AS NUMERIC), 1), ROUND(CAST(longitude AS NUMERIC), 1)) IN {coordinates} GROUP BY rounded_latitude, rounded_longitude",
"sql_query": "SELECT ROUND(CAST(latitude AS NUMERIC), 1) AS rounded_latitude, ROUND(CAST(longitude AS NUMERIC), 1) AS rounded_longitude, AVG(tmean - 273.15) AS avg_temp_celsius FROM era5_land2.meteo_tmean WHERE EXTRACT(YEAR FROM time) = 2020 AND (ROUND(CAST(latitude AS NUMERIC), 1), ROUND(CAST(longitude AS NUMERIC), 1)) IN ((47.4, 8.4), (47.4, 8.5)) GROUP BY rounded_latitude, rounded_longitude",
"sql_results": {
"data": [
{
"avg_temp_celsius": 10.613293907290531,
"rounded_latitude": "47.4",
"rounded_longitude": "8.4"
},
{
"avg_temp_celsius": 10.440176525011696,
"rounded_latitude": "47.4",
"rounded_longitude": "8.5"
}
],
"status": "success"
},
"status": "success"
},
"properties": {
"input_params": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/InputParam"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Input parameters with coordinates.",
"title": "Input Params"
},
"message": {
"description": "Message describing the operation result.",
"title": "Message",
"type": "string"
},
"model_name": {
"description": "The model name used for SQL generation.",
"title": "Model Name",
"type": "string"
},
"output_params": {
"anyOf": [
{
"$ref": "#/components/schemas/OutputParams"
},
{
"type": "null"
}
],
"description": "Output parameter definitions."
},
"params": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Parameters used in the query.",
"title": "Params"
},
"question": {
"description": "The original question that was converted to SQL.",
"title": "Question",
"type": "string"
},
"reasoning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Reasoning behind the SQL query generation.",
"title": "Reasoning"
},
"sql_pattern": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The SQL pattern/template generated.",
"title": "Sql Pattern"
},
"sql_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The final SQL query with parameters filled in.",
"title": "Sql Query"
},
"sql_results": {
"anyOf": [
{
"$ref": "#/components/schemas/SQLResults"
},
{
"type": "null"
}
],
"description": "Results from executing the SQL query."
},
"status": {
"description": "Status of the operation.",
"title": "Status",
"type": "string"
}
},
"required": [
"status",
"message",
"question",
"model_name"
],
"title": "Text2SQLResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
},
{
"Key": "parameters.results.points",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
text2sql4ap¶
POST /text2sql4ap¶
Text2Sql4Ap Query
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"ap": {
"edges": null,
"nodes": [
{
"id": null,
"labels": null,
"properties": null
}
]
}
}
Schema of the request body
{
"additionalProperties": true,
"description": "Request body for POST /text2sql4ap.",
"properties": {
"ap": {
"$ref": "#/components/schemas/APPayloadBody"
}
},
"required": [
"ap"
],
"title": "Text2SQL4APRequest",
"type": "object"
}
Responses
{
"ap": {
"edges": null,
"nodes": [
{
"id": null,
"labels": null,
"properties": null
}
]
},
"metadata": null
}
Schema of the response body
{
"additionalProperties": true,
"description": "Response body for POST /text2sql4ap.",
"properties": {
"ap": {
"$ref": "#/components/schemas/APPayloadBody"
},
"metadata": {
"anyOf": [
{
"$ref": "#/components/schemas/Text2SQL4APMetadata"
},
{
"type": "null"
}
]
}
},
"required": [
"ap"
],
"title": "Text2SQL4APResponse",
"type": "object"
}
{
"detail": [
{
"ctx": {},
"input": null,
"loc": [
null
],
"msg": "string",
"type": "string"
}
]
}
Schema of the response body
{
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"title": "Detail",
"type": "array"
}
},
"title": "HTTPValidationError",
"type": "object"
}
textQuestionAnswer¶
POST /textQuestionAnswer¶
Text Question Answer Query
Description
Summarize RAG content for a question.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"question": "What is the chief town of the island of COPRAJA?",
"rag_output": {
"query_time": 3263.56,
"results": [
{
"content": "COPRAJA, an island in the Mediterranean Sea... The chief town is Tratozzio.",
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"metadata": {
"language": "en",
"original_filename": "kp-eb0707-031203-1328-v2.xml",
"year": "1823-1887"
},
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
}
}
Schema of the request body
{
"properties": {
"question": {
"description": "The user question that should be answered from the provided RAG chunks.",
"example": "What is the chief town of the island of COPRAJA?",
"minLength": 1,
"title": "Question",
"type": "string"
},
"rag_output": {
"additionalProperties": true,
"description": "Raw RAG output containing retrieved chunks and metadata.",
"example": {
"query_time": 3263.56,
"results": [
{
"content": "COPRAJA, an island in the Mediterranean Sea... The chief town is Tratozzio.",
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"metadata": {
"language": "en",
"original_filename": "kp-eb0707-031203-1328-v2.xml",
"year": "1823-1887"
},
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
},
"title": "Rag Output",
"type": "object"
}
},
"required": [
"question",
"rag_output"
],
"title": "TextQuestionQuery",
"type": "object"
}
Responses
{
"answerable": true,
"reason_code": "ANSWERED",
"summary": "Based on the provided context, the chief town of COPRAJA is Tratozzio.",
"used_chunks": [
{
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
}
Schema of the response body
{
"example": {
"answerable": true,
"reason_code": "ANSWERED",
"summary": "Based on the provided context, the chief town of COPRAJA is Tratozzio.",
"used_chunks": [
{
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
},
"properties": {
"answerable": {
"description": "Whether the model determined the context is sufficient to answer.",
"title": "Answerable",
"type": "boolean"
},
"reason_code": {
"description": "Structured reason code from summarization decision.",
"title": "Reason Code",
"type": "string"
},
"summary": {
"description": "Summary answer generated from RAG chunks.",
"title": "Summary",
"type": "string"
},
"used_chunks": {
"description": "Sources used by the summarization step.",
"items": {
"$ref": "#/components/schemas/SummarySource"
},
"title": "Used Chunks",
"type": "array"
}
},
"required": [
"answerable",
"reason_code",
"summary",
"used_chunks"
],
"title": "TextQuestionAnswerResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
},
{
"Key": "rag_output.results",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
Schemas¶
APEdgeSchema¶
| Name | Type | Description |
|---|---|---|
directed |
||
from |
||
id |
||
labels |
||
properties |
||
to |
APNodeSchema¶
| Name | Type | Description |
|---|---|---|
id |
||
labels |
||
properties |
APPayloadBody¶
| Name | Type | Description |
|---|---|---|
edges |
||
nodes |
Array<APNodeSchema> |
Body_keyword_matching_query_keywordMatching_post¶
| Name | Type | Description |
|---|---|---|
candidates |
Array<string> | Mandatory list of candidate keywords to rank against the document. Can be passed as repeated form fields or a JSON array string. |
file |
PDF document to parse into Markdown (mutually exclusive with 'text'). | |
k |
integer | Maximum number of top-ranked keywords to return. |
method |
KeywordMatchingMethod | Retrieval method: 'hybrid' (default), 'dense', or 'sparse'. |
text |
Raw text or Markdown document content (mutually exclusive with 'file'). |
Bounds¶
| Name | Type | Description |
|---|---|---|
maxlat |
number | Maximum latitude. |
maxlon |
number | Maximum longitude. |
minlat |
number | Minimum latitude. |
minlon |
number | Minimum longitude. |
CollocationFeature¶
| Name | Type | Description |
|---|---|---|
association_score |
number | Pointwise mutual information score for the pair. |
count |
integer | Number of pair occurrences in the chunk. |
terms |
Array<string> | Adjacent word pair. |
ComparisonSlice¶
| Name | Type | Description |
|---|---|---|
corpus_id |
string | |
label |
string | |
language |
string | |
period_end |
integer | |
period_start |
integer | |
slice_id |
string |
DecomposeResponse¶
| Name | Type | Description |
|---|---|---|
concept |
string | |
qdmr |
Array<> | |
question |
string | |
slices |
Array<ComparisonSlice> |
Explore4APMetadata¶
| Name | Type | Description |
|---|---|---|
db_fetch_time_s |
number | Database fetch/execution time in seconds. |
inference_time_s |
number | LLM inference time in seconds (excluding DB fetch). |
input_params |
Coordinate parameters used in the query. | |
message |
Human-readable pipeline status message. | |
model_name |
LLM model used for SQL generation. | |
output_params |
Coordinate output parameter names when present. | |
params |
Nested text2geo and text2sql pipeline outputs. | |
question |
string | The natural-language question explored. |
reasoning |
Reasoning behind SQL generation. | |
sql_pattern |
Generated SQL template. | |
sql_query |
Executable SQL with literals filled in. | |
sql_query_with_args |
Prepared SQL with dataset table placeholders for the AP graph. | |
sql_results |
Results from executing the SQL query. | |
status |
Status of the explore/text-to-SQL pipeline. |
Explore4APRequest¶
| Name | Type | Description |
|---|---|---|
ap |
APPayloadBody |
Explore4APResponse¶
| Name | Type | Description |
|---|---|---|
ap |
APPayloadBody | |
metadata |
ExplorePipelineParams¶
| Name | Type | Description |
|---|---|---|
text2geo |
Full text2geo pipeline output (place, wikidata, oql, results). | |
text2sql |
Text-to-SQL pipeline output (sql_pattern, sql_query, sql_results, ...). |
ExploreResponse¶
| Name | Type | Description |
|---|---|---|
db_fetch_time_s |
number | Database fetch/execution time in seconds. |
inference_time_s |
number | LLM inference time in seconds (excluding DB fetch). |
input_params |
Coordinate parameters used in the query. | |
question |
string | The natural-language question explored. |
reasoning |
Reasoning behind SQL generation. | |
sql_pattern |
Generated SQL template. | |
sql_query |
Executable SQL with literals filled in. | |
sql_results |
Results from executing the SQL query. |
ExtendKnowledgeResponse¶
| Name | Type | Description |
|---|---|---|
concept |
string | |
expansion |
||
generated_subquestions |
Array<> | |
question |
string | |
slices |
Array<ComparisonSlice> |
GeospatialResponse¶
| Name | Type | Description |
|---|---|---|
most_relevant_wikidata |
MostRelevantWikidata | The most relevant Wikidata entity related to the query. |
oql |
OQLResponse | The OverpassQL query generated from the geospatial question. |
place |
string | The place identified in the geospatial query. |
results |
GeospatialResults | The results of the OverpassQL query includes points, bounding box, multipolygons and centroid. |
GeospatialResults¶
| Name | Type | Description |
|---|---|---|
bounds |
Bounds | Bounding box of the results. |
center |
Array<number> | Center coordinates as [lat, lon]. |
geojson_data |
GeoJSON feature collection data. | |
points |
Array<Point> | List of points with coordinates. |
HTTPValidationError¶
| Name | Type | Description |
|---|---|---|
detail |
Array<ValidationError> |
InputParam¶
KeywordMatchingMethod¶
Type: string
KeywordMatchingResponse¶
| Name | Type | Description |
|---|---|---|
k |
integer | Number of top-ranked keywords returned. |
method |
KeywordMatchingMethod | Retrieval method used to rank candidates. |
results |
Array<KeywordMatchResult> | Ranked list of candidate keywords matching the document. |
total_candidates |
integer | Total number of unique candidate keywords evaluated. |
KeywordMatchResult¶
| Name | Type | Description |
|---|---|---|
candidate |
string | Candidate keyword string. |
dense_score |
Cosine similarity score from the dense embedding model when computed. | |
rank |
integer | 1-based rank of the candidate keyword. |
score |
number | Primary ranking score (RRF score for hybrid, cosine similarity for dense, BM25 score for sparse). |
sparse_score |
BM25 lexical relevance score when computed. |
LanguageQuery¶
| Name | Type | Description |
|---|---|---|
concept |
Optional concept override; otherwise extracted from the question. | |
question |
string | Natural-language question. |
slices |
Optional comparison slices; defaults to 1800s vs present. |
LinguisticFeatureName¶
Type: string
LinguisticFeaturesChunk¶
| Name | Type | Description |
|---|---|---|
collocations |
Adjacent word pairs ranked by statistical association when requested. | |
dataset_id |
string | Dataset identifier for the source. |
object_id |
string | Object identifier for the source chunk. |
sentiment_profile |
Lexicon-based sentiment profile for the chunk when requested. | |
similarity |
number | Similarity score for this source. |
term_frequency |
Most frequent normalized terms in the chunk when requested. |
LinguisticFeaturesQuery¶
| Name | Type | Description |
|---|---|---|
question |
string | The user question that should be answered from the provided RAG chunks. |
rag_output |
Example: {'query_time': 3263.56, 'results': [{'content': 'COPRAJA, an island in the Mediterranean Sea... The chief town is Tratozzio.', 'dataset_id': 'd84d1a2e-127d-4393-91d0-afb7e4fd9c68', 'metadata': {'language': 'en', 'original_filename': 'kp-eb0707-031203-1328-v2.xml', 'year': '1823-1887'}, 'object_id': 'kp-eb0707-031203-1328-v2.xml', 'similarity': 1.0}]} |
Raw RAG output containing retrieved chunks and metadata. |
requested_features |
Array<LinguisticFeatureName> | Optional subset of linguistic features to return. If omitted or empty, all supported features are returned. |
LinguisticFeaturesResponse¶
| Name | Type | Description |
|---|---|---|
features |
Array<LinguisticFeaturesChunk> | Linguistic features calculated for each selected chunk. |
used_chunks |
Array<SummarySource> | Sources used by the linguistic feature step. |
MostRelevantWikidata¶
| Name | Type | Description |
|---|---|---|
place |
string | The place name. |
reasoning |
string | Reasoning for selecting this entity. |
wiki_id |
string | The Wikidata ID. |
wiki_properties |
WikiProperties | Properties of the Wikidata entity. |
NlgEvaluateQuery¶
| Name | Type | Description |
|---|---|---|
answer |
string | |
ground_truth |
Optional inline gold. Otherwise exact Question_ID or question text from data/nlg/. | |
query_id |
||
question |
string |
NlgEvaluateResponse¶
| Name | Type | Description |
|---|---|---|
concept |
string | |
gold_question |
string | |
gold_source |
string | |
ground_truth |
string | |
match |
string | |
matched |
boolean | |
metrics |
||
question_id |
string | |
summary |
string |
OQLResponse¶
| Name | Type | Description |
|---|---|---|
OQL |
string | The OverpassQL query string. |
reasoning |
string | Reasoning for the generated OQL query. |
OutputParams¶
| Name | Type | Description |
|---|---|---|
coordinates |
Array<string> | List of coordinate parameter names. |
Point¶
| Name | Type | Description |
|---|---|---|
lat |
string | Latitude as string. |
lon |
string | Longitude as string. |
ResultsModel¶
| Name | Type | Description |
|---|---|---|
points |
Array<Array<number>> | List of points with coordinates. |
SentimentProfile¶
| Name | Type | Description |
|---|---|---|
label |
string | Overall lexicon-based sentiment label. |
negative_terms |
integer | Negative lexicon term count. |
neutral_terms |
integer | Terms not matched by sentiment lexicon. |
polarity_score |
number | Score from -1.0 to 1.0 based on positive and negative terms. |
positive_terms |
integer | Positive lexicon term count. |
subjectivity_score |
number | VADER positive plus negative proportion for the full chunk. |
total_terms |
integer | Total normalized terms in the chunk. |
SQLQueryParameters¶
| Name | Type | Description |
|---|---|---|
db_info |
Database connection information. | |
results |
The results containing points for SQL query. |
SQLResults¶
| Name | Type | Description |
|---|---|---|
data |
Array<> | Results data from the SQL query. |
status |
string | Status of the SQL query execution. |
SummarySource¶
| Name | Type | Description |
|---|---|---|
dataset_id |
string | Dataset identifier for the source. |
object_id |
string | Object identifier for the source chunk. |
similarity |
number | Similarity score for this source. |
TermFrequencyFeature¶
| Name | Type | Description |
|---|---|---|
count |
integer | Number of occurrences in the chunk. |
frequency |
number | Relative frequency within the chunk. |
term |
string | Normalized term. |
Text2SQL4APMetadata¶
| Name | Type | Description |
|---|---|---|
input_params |
Coordinate input parameters when present. | |
message |
Human-readable status message. | |
model_name |
LLM model used for SQL generation. | |
output_params |
Coordinate output parameter names when present. | |
question |
NLQ question processed by text-to-SQL. | |
reasoning |
Reasoning behind SQL generation. | |
sql_pattern |
SQL template with coordinate placeholders. | |
sql_query |
Final SQL query with literals filled in. | |
sql_query_with_args |
Prepared SQL with dataset table placeholders for downstream execution. | |
status |
string | Status of the text-to-SQL operation. |
Text2SQL4APRequest¶
| Name | Type | Description |
|---|---|---|
ap |
APPayloadBody |
Text2SQL4APResponse¶
| Name | Type | Description |
|---|---|---|
ap |
APPayloadBody | |
metadata |
Text2SQLQuery¶
| Name | Type | Description |
|---|---|---|
parameters |
SQLQueryParameters | The parameters for the SQL query, including results. |
question |
string | The text question to be converted to SQL. |
Text2SQLResponse¶
| Name | Type | Description |
|---|---|---|
input_params |
Input parameters with coordinates. | |
message |
string | Message describing the operation result. |
model_name |
string | The model name used for SQL generation. |
output_params |
Output parameter definitions. | |
params |
Parameters used in the query. | |
question |
string | The original question that was converted to SQL. |
reasoning |
Reasoning behind the SQL query generation. | |
sql_pattern |
The SQL pattern/template generated. | |
sql_query |
The final SQL query with parameters filled in. | |
sql_results |
Results from executing the SQL query. | |
status |
string | Status of the operation. |
TextQuestionAnswerResponse¶
| Name | Type | Description |
|---|---|---|
answerable |
boolean | Whether the model determined the context is sufficient to answer. |
reason_code |
string | Structured reason code from summarization decision. |
summary |
string | Summary answer generated from RAG chunks. |
used_chunks |
Array<SummarySource> | Sources used by the summarization step. |
TextQuestionQuery¶
| Name | Type | Description |
|---|---|---|
question |
string | The user question that should be answered from the provided RAG chunks. |
rag_output |
Example: {'query_time': 3263.56, 'results': [{'content': 'COPRAJA, an island in the Mediterranean Sea... The chief town is Tratozzio.', 'dataset_id': 'd84d1a2e-127d-4393-91d0-afb7e4fd9c68', 'metadata': {'language': 'en', 'original_filename': 'kp-eb0707-031203-1328-v2.xml', 'year': '1823-1887'}, 'object_id': 'kp-eb0707-031203-1328-v2.xml', 'similarity': 1.0}]} |
Raw RAG output containing retrieved chunks and metadata. |
ValidationError¶
| Name | Type | Description |
|---|---|---|
ctx |
||
input |
||
loc |
Array<> | |
msg |
string | |
type |
string |
ValidationErrorDetail¶
| Name | Type | Description |
|---|---|---|
Key |
string | |
Value |
Array<string> |
ValidationErrorResponse¶
| Name | Type | Description |
|---|---|---|
code |
integer | |
error |
string | |
message |
Array<ValidationErrorDetail> |
WikiProperties¶
| Name | Type | Description |
|---|---|---|
aliases |
Aliases for the Wikidata entity. | |
coordinate location |
Coordinate location. | |
country |
Country information. | |
description |
The description of the Wikidata entity. | |
found_osm_json |
boolean | Whether OSM JSON was found. |
instance of |
Instance types of the entity. | |
label |
The label of the Wikidata entity. | |
located in the administrative territorial entity |
Administrative location. | |
part of |
What the entity is part of. |
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| OAuth2PasswordBearer | oauth2 |