feat: Add relation extraction task (#242)

* feat: Foundation for relation extraction.

* docs: Update docs.

* fix: Fix relation extraction bugs.

* chore: Clean up RE bridge.

* chore: Clean up.

* fix: Make context field optional.

---------

Co-authored-by: Raphael Mitsch <raphael@climatiq.com>

Author: rmitsch

README.md

@@ -53,6 +53,7 @@ to skip having to define tasks from scratch.
 - :label: **Ready-to-Use Tasks:**
   - Multi-label classification
   - Information extraction
+  - Relation extraction
   - Summarization
   - Translation
   - Multi-question answering

docs/tasks/predictive/classification.md

@@ -15,7 +15,7 @@ The `Classification` task categorizes documents into predefined labels.
 The `Classification` task returns a unified result schema regardless of the model backend used.
 
 ```python
---8<-- "sieves/tasks/predictive/classification/schemas.py:Result"
+--8<-- "sieves/tasks/predictive/schemas/classification.py:Result"
 ```
 
 - When `multi_label=True` (default): results are of type `ResultMultiLabel`, containing a list of `(label, score)` tuples.
@@ -25,4 +25,4 @@ The `Classification` task returns a unified result schema regardless of the mode
 
 ::: sieves.tasks.predictive.classification.core
 ::: sieves.tasks.predictive.classification.bridges
-::: sieves.tasks.predictive.classification.schemas
+::: sieves.tasks.predictive.schemas.classification

docs/tasks/predictive/information_extraction.md

@@ -25,7 +25,7 @@ Use `mode="single"` when you expect exactly one entity per document (or none). T
 The `InformationExtraction` task produces unified results based on the chosen mode:
 
 ```python
---8<-- "sieves/tasks/predictive/information_extraction/schemas.py:Result"
+--8<-- "sieves/tasks/predictive/schemas/information_extraction.py:Result"
 ```
 
 - `mode="multi"`: Returns a `ResultMulti` object with an `entities` list.
@@ -35,4 +35,4 @@ The `InformationExtraction` task produces unified results based on the chosen mo
 
 ::: sieves.tasks.predictive.information_extraction.core
 ::: sieves.tasks.predictive.information_extraction.bridges
-::: sieves.tasks.predictive.information_extraction.schemas
+::: sieves.tasks.predictive.schemas.information_extraction

docs/tasks/predictive/ner.md

@@ -25,11 +25,11 @@ Providing descriptions for each entity type helps the model understand exactly w
 The `NER` task returns a unified `Result` object (an alias for `Entities`) containing a list of `Entity` objects and the source text.
 
 ```python
---8<-- "sieves/tasks/predictive/ner/schemas.py:Result"
+--8<-- "sieves/tasks/predictive/schemas/ner.py:Result"
 ```
 
 ---
 
 ::: sieves.tasks.predictive.ner.core
 ::: sieves.tasks.predictive.ner.bridges
-::: sieves.tasks.predictive.ner.schemas
+::: sieves.tasks.predictive.schemas.ner

docs/tasks/predictive/pii_masking.md

@@ -13,11 +13,11 @@ The `PIIMasking` task identifies and masks Personally Identifiable Information (
 The `PIIMasking` task returns a unified `Result` object containing the `masked_text` and a list of `pii_entities`.
 
 ```python
---8<-- "sieves/tasks/predictive/pii_masking/schemas.py:Result"
+--8<-- "sieves/tasks/predictive/schemas/pii_masking.py:Result"
 ```
 
 ---
 
 ::: sieves.tasks.predictive.pii_masking.core
 ::: sieves.tasks.predictive.pii_masking.bridges
-::: sieves.tasks.predictive.pii_masking.schemas
+::: sieves.tasks.predictive.schemas.pii_masking

docs/tasks/predictive/question_answering.md

@@ -13,11 +13,11 @@ The `QuestionAnswering` task answers questions based on the content of the docum
 The `QuestionAnswering` task returns a unified `Result` object containing a list of `answers` corresponding to the input questions.
 
 ```python
---8<-- "sieves/tasks/predictive/question_answering/schemas.py:Result"
+--8<-- "sieves/tasks/predictive/schemas/question_answering.py:Result"
 ```
 
 ---
 
 ::: sieves.tasks.predictive.question_answering.core
 ::: sieves.tasks.predictive.question_answering.bridges
-::: sieves.tasks.predictive.question_answering.schemas
+::: sieves.tasks.predictive.schemas.question_answering

docs/tasks/predictive/relation_extraction.md

@@ -0,0 +1,30 @@
+# Relation Extraction
+
+The `RelationExtraction` task performs joint entity and relation extraction, identifying relationships between entities in text.
+
+## Usage
+
+```python
+--8<-- "sieves/tests/tasks/predictive/test_relation_extraction.py:re-usage"
+```
+
+## Results
+
+The `RelationExtraction` task returns a unified `Result` object containing a list of `RelationTriplet` objects.
+
+```python
+--8<-- "sieves/tasks/predictive/schemas/relation_extraction.py:Result"
+```
+
+Each `RelationTriplet` consists of:
+- `head`: A `RelationEntity` representing the subject.
+- `relation`: The string identifier of the relationship.
+- `tail`: A `RelationEntity` representing the object.
+
+A `RelationEntity` includes the surface `text`, `entity_type`, and character `start`/`end` offsets.
+
+---
+
+::: sieves.tasks.predictive.relation_extraction.core
+::: sieves.tasks.predictive.relation_extraction.bridges
+::: sieves.tasks.predictive.schemas.relation_extraction

docs/tasks/predictive/sentiment_analysis.md

@@ -13,11 +13,11 @@ The `SentimentAnalysis` task determines the sentiment of the text (e.g., positiv
 The `SentimentAnalysis` task returns a unified `Result` object containing a `sentiment_per_aspect` dictionary.
 
 ```python
---8<-- "sieves/tasks/predictive/sentiment_analysis/schemas.py:Result"
+--8<-- "sieves/tasks/predictive/schemas/sentiment_analysis.py:Result"
 ```
 
 ---
 
 ::: sieves.tasks.predictive.sentiment_analysis.core
 ::: sieves.tasks.predictive.sentiment_analysis.bridges
-::: sieves.tasks.predictive.sentiment_analysis.schemas
+::: sieves.tasks.predictive.schemas.sentiment_analysis

docs/tasks/predictive/summarization.md

@@ -13,11 +13,11 @@ The `Summarization` task generates concise summaries of the documents.
 The `Summarization` task returns a unified `Result` object containing the `summary`.
 
 ```python
---8<-- "sieves/tasks/predictive/summarization/schemas.py:Result"
+--8<-- "sieves/tasks/predictive/schemas/summarization.py:Result"
 ```
 
 ---
 
 ::: sieves.tasks.predictive.summarization.core
 ::: sieves.tasks.predictive.summarization.bridges
-::: sieves.tasks.predictive.summarization.schemas
+::: sieves.tasks.predictive.schemas.summarization

docs/tasks/predictive/translation.md

@@ -13,11 +13,11 @@ The `Translation` task translates documents into a target language.
 The `Translation` task returns a unified `Result` object containing the `translation`.
 
 ```python
---8<-- "sieves/tasks/predictive/translation/schemas.py:Result"
+--8<-- "sieves/tasks/predictive/schemas/translation.py:Result"
 ```
 
 ---
 
 ::: sieves.tasks.predictive.translation.core
 ::: sieves.tasks.predictive.translation.bridges
-::: sieves.tasks.predictive.translation.schemas
+::: sieves.tasks.predictive.schemas.translation