Including a triplet format

Author: philippesaade-wmde

README.md

@@ -1,8 +1,9 @@
 # Wikidata Textifier
 
-**Wikidata Textifier** is an API that transforms Wikidata items into compact JSON formats or textual representations for use in LLMs and GenAI applications. It resolves missing labels of properties and claim values by querying the Wikidata Action API, making it efficient and suitable for AI pipelines.
+**Wikidata Textifier** is an API that transforms Wikidata items into compact format for use in LLMs and GenAI applications. It resolves missing labels of properties and claim values by querying the Wikidata Action API, making it efficient and suitable for AI pipelines.
 
 🔗 Live API: [https://wd-textify.toolforge.org/](https://wd-textify.toolforge.org/)
+
 ---
 
 ## Functionalities
@@ -15,6 +16,14 @@
 
 ---
 
+## Formats
+
+- **Text**: A textual representation or summary of the Wikidata item, including its label, description, aliases, and claims. Useful for helping LLMs understand what the item represents.
+- **Triplet**: Outputs each triplet as a structured line, including labels and IDs, but omits descriptions and aliases. Ideal for agentic LLMs to traverse and explore Wikidata.
+- **JSON**: A structured and compact representation of the full item, suitable for custom formats.
+
+---
+
 ## API Usage
 
 ### `GET /`
@@ -25,5 +34,5 @@
 |----------------|---------|----------|-----------------------------------------------------------------------------|
 | `id`           | string  | Yes      | Wikidata item ID (e.g., `Q42`)                                              |
 | `lang`         | string  | No       | Language code for labels (default: `en`)                                   |
-| `json`         | bool    | No       | If `true`, returns JSON. If `false`, returns text representation (default: `false`) |
+| `format`         | string    | No       | The format of the response, either 'json', 'text', or 'triplet' (default: `json`) |
 | `external_ids` | bool    | No       | Whether to include external IDs in the output (default: `true`)            |

main.py

@@ -40,7 +40,7 @@
             "description": "Missing or invalid query parameter",
             "content": {
                 "application/json": {
-                    "example": {"detail": "ID is missing"}
+                    "example": {"detail": "Invalid format specified"}
                 }
             },
         },
@@ -50,15 +50,15 @@ async def property_query_route(
     request: Request,
     id: str = Query(..., examples="Q42"),
     lang: str = 'en',
-    json: bool = False,
+    format: str = 'json',
     external_ids: bool = True
 ):
     """
     Retrieve a Wikidata item with all labels or textual representations for an LLM.
 
     Args:
         id (str): The Wikidata item ID (e.g., "Q42").
-        json (bool): If True, returns the item in JSON format.
+        format (str): The format of the response, either 'json', 'text', or 'triplet'.
         lang (str): The language code for labels (default is 'en').
         external_ids (bool): If True, includes external IDs in the response.
 
@@ -80,10 +80,15 @@ async def property_query_route(
             response = "Item not found"
             return HTTPException(status_code=404, detail=response)
 
-        if json:
+        if format == 'json':
             results = entity.to_json()
-        else:
+        elif format == 'triplet':
+            results = entity.to_triplet()
+        elif format == 'text':
             results = str(entity)
+        else:
+            response = "Invalid format specified"
+            return HTTPException(status_code=422, detail=response)
 
         return results
     except Exception as e:

src/WikidataTextifier.py

@@ -314,9 +314,9 @@ def __str__(self):
             return ''
 
         string = str(self.value)
-        attributes = [str(q) for q in self.qualifiers if q]
-        if len(attributes) > 0:
-            string += f" ({', '.join(attributes)})"
+        qualifiers = [str(q) for q in self.qualifiers if q]
+        if len(qualifiers) > 0:
+            string += f" ({', '.join(qualifiers)})"
         return string
 
     def __bool__(self):
@@ -345,6 +345,19 @@ def to_json(self):
             "qualifiers": [q.to_json() for q in self.qualifiers if q]
         }
 
+    def to_triplet(self):
+        if not self:
+            return ''
+
+        string = str(self.value)
+        if isinstance(self.value, WikidataEntity):
+            string = f"{self.value.label} ({self.value.id})"
+
+        qualifiers = [q.to_triplet() for q in self.qualifiers if q]
+        if len(qualifiers) > 0:
+            string += f" | {' | '.join(qualifiers)})"
+        return string
+
 
 @dataclass
 class WikidataClaim:
@@ -420,17 +433,14 @@ def __str__(self):
         if not self:
             return ''
 
-        if not str(self.property.label):
-            return ''
-
         values = [str(v) for v in self.values if v]
         values = ", ".join(values)
 
         return f"{str(self.property.label)}: {values}"
 
     def __bool__(self):
         return (self.property is not None) and \
-                str(self.property) != '' and \
+                str(self.property.label) != '' and \
                     (len(self.values) > 0) and \
                         any(bool(val) for val in self.values)
 
@@ -443,6 +453,20 @@ def to_json(self):
             "values": [v.to_json() for v in self.values if v]
         }
 
+    def to_triplet(self):
+        if not self:
+            return ''
+
+        label = f"{str(self.property.label)} ({self.property.id})"
+        values = [v.to_triplet() for v in self.values if v]
+
+        if len(values) > 0:
+            values = [f"{label}: {v}" for v in values]
+            values = "\n".join(values)
+            return values
+
+        return ''
+
 
 @dataclass
 class WikidataEntity:
@@ -540,3 +564,15 @@ def to_json(self):
             'aliases': self.aliases,
             'claims': [c.to_json() for c in self.claims if c]
         }
+
+    def to_triplet(self):
+        label = f"{str(self.label)} ({self.id})"
+        attributes = [c.to_triplet() for c in self.claims if c]
+
+        if len(attributes) > 0:
+            attributes = "\n".join(attributes).split("\n")
+            attributes = [f"{label}: {a}" for a in attributes]
+            attributes = "\n".join(attributes)
+            return attributes
+
+        return label