Update README.md

README.md

@@ -199,6 +199,119 @@ results = process(text, prompt)
 print(results)
 ```
 
+### How to run with utca:
+First of all, you need to install the package:
+```bash
+pip install utca -U
+```
+
+After that you to create predictor that will run UTC model:
+```python
+from utca.core import (
+    AddData,
+    RenameAttribute,
+    Flush
+)
+from utca.implementation.predictors import (
+    TokenSearcherPredictor, TokenSearcherPredictorConfig
+)
+from utca.implementation.tasks import (
+    TokenSearcherNER,
+    TokenSearcherNERPostprocessor,
+)
+
+predictor = TokenSearcherPredictor(
+    TokenSearcherPredictorConfig(
+        device="cuda:0",
+        model="knowledgator/UTC-DeBERTa-small-v2"
+    )
+)
+```
+
+For NER model you should create the following pipeline:
+
+```python
+ner_task = TokenSearcherNER(
+    predictor=predictor,
+    postprocess=[TokenSearcherNERPostprocessor(
+        threshold=0.5
+    )]
+)
+
+ner_task = TokenSearcherNER()
+
+pipeline = (        
+    AddData({"labels": ["scientist", "university", "city"]})         
+    | ner_task
+    | Flush(keys=["labels"])
+    | RenameAttribute("output", "entities")
+)
+```
+
+And after that you can put your text for prediction and run the pipeline:
+
+```python
+res = pipeline.run({
+    "text": """Dr. Paul Hammond, a renowned neurologist at Johns Hopkins University, has recently published a paper in the prestigious journal "Nature Neuroscience". 
+His research focuses on a rare genetic mutation, found in less than 0.01% of the population, that appears to prevent the development of Alzheimer's disease. Collaborating with researchers at the University of California, San Francisco, the team is now working to understand the mechanism by which this mutation confers its protective effect. 
+Funded by the National Institutes of Health, their research could potentially open new avenues for Alzheimer's treatment."""
+})
+```
+
+To use `utca` for relation extraction construct the following pipeline:
+
+```python
+from utca.implementation.tasks import (
+    TokenSearcherNER,
+    TokenSearcherNERPostprocessor,
+    TokenSearcherRelationExtraction,
+    TokenSearcherRelationExtractionPostprocessor,
+)
+
+pipe = (
+    TokenSearcherNER( # TokenSearcherNER task produces classified entities that will be at the "output" key.
+        predictor=predictor,
+        postprocess=TokenSearcherNERPostprocessor(
+            threshold=0.5 # Entity threshold
+        )
+    ) 
+    | RenameAttribute("output", "entities") # Rename output entities from TokenSearcherNER task to use them as inputs in TokenSearcherRelationExtraction
+    | TokenSearcherRelationExtraction( # TokenSearcherRelationExtraction is used for relation extraction.
+        predictor=predictor,
+        postprocess=TokenSearcherRelationExtractionPostprocessor(
+            threshold=0.5 # Relation threshold
+        )
+    )
+)
+```
+
+To run pipeline you need to specify parameters for entities and relations:
+
+```python
+r = pipe.run({
+    "text": text, # Text to process
+    "labels": [ # Labels used by TokenSearcherNER for entity extraction
+        "scientist",
+        "university",
+        "city",
+        "research",
+        "journal",
+    ],
+    "relations": [{ # Relation parameters
+        "relation": "published at", # Relation label. Required parameter.
+        "pairs_filter": [("scientist", "journal")], # Optional parameter. It specifies possible members of relations by their entity labels.
+        # Here, "scientist" is the entity label of the source, and "journal" is the target's entity label.
+        # If provided, only specified pairs will be returned.
+    },{
+        "relation": "worked at",
+        "pairs_filter": [("scientist", "university"), ("scientist", "other")],
+        "distance_threshold": 100, # Optional parameter. It specifies the max distance between spans in the text (i.e., the end of the span that is closer to the start of the text and the start of the next one).
+    }]
+})
+
+print(r["output"])
+```
+
 ### Benchmarking
 Below is a table that highlights the performance of UTC models on the [CrossNER](https://huggingface.co/datasets/DFKI-SLT/cross_ner) dataset. The values represent the Micro F1 scores, with the estimation done at the word level.