---
name: extract_relations_mrebel
kind: function
lang: py
domain: datascience
version: "1.0.0"
purity: impure
signature: "def extract_relations_mrebel(text: str, entities: list[EntityCandidate], tokenizer: Any, model: Any, src_lang: str = 'es_XX', sentence_split_re: str = r'(?<=[.!?])\\s+', min_sentence_chars: int = 20, num_beams: int = 4, max_length: int = 256) -> list[RelationCandidate]"
description: "Extrae relaciones entre entidades usando mREBEL (seq2seq multilingue). Divide el texto por oraciones, genera triplets con mREBEL, parsea con parse_rebel_output y alinea a entidades conocidas con align_relations_to_entities. Drop-in con extract_relations_glirel para benchmarks."
tags: [mrebel, relation-extraction, nlp, extract, knowledge-graph, seq2seq, multilingual, datascience, python]
uses_functions:
  - mrebel_load_model_py_datascience
  - parse_rebel_output_py_datascience
  - align_relations_to_entities_py_datascience
uses_types:
  - entity_candidate_py_datascience
  - relation_candidate_py_datascience
returns:
  - relation_candidate_py_datascience
returns_optional: false
error_type: "error_go_core"
imports: [re]
params:
  - name: text
    desc: "texto fuente en el idioma de src_lang (mismo chunk usado para extraer las entidades)"
  - name: entities
    desc: "entidades ya extraidas de este texto (de extract_entities_gliner o similar). Solo se conservan relaciones entre entidades de esta lista."
  - name: tokenizer
    desc: "tokenizer mREBEL cargado con mrebel_load_model — inyectado por el caller para evitar re-carga en batch"
  - name: model
    desc: "modelo mREBEL cargado con mrebel_load_model — inyectado por el caller"
  - name: src_lang
    desc: "informativo — el idioma con que se cargo el tokenizer (ej. 'es_XX'). No se usa en runtime."
  - name: sentence_split_re
    desc: "patron regex para dividir el texto en oraciones. Defecto: split despues de [.!?] seguido de espacio."
  - name: min_sentence_chars
    desc: "longitud minima de caracteres para procesar una oracion. Fragmentos mas cortos se saltan (defecto 20)."
  - name: num_beams
    desc: "ancho del beam search para model.generate (defecto 4)"
  - name: max_length
    desc: "longitud maxima en tokens para tokenizacion y generacion (defecto 256)"
output: "lista de RelationCandidate con confidence=1.0 (mREBEL no produce score continuo). from_name/to_name siempre coinciden con entidades del input."
tested: true
tests:
  - "flujo completo con stub produce RelationCandidate correctos"
  - "menos de 2 entidades retorna vacio"
  - "texto vacio retorna vacio"
  - "triplets no alineables se descartan"
test_file_path: "python/functions/datascience/tests/test_extract_relations_mrebel.py"
file_path: "python/functions/datascience/extract_relations_mrebel.py"
notes: |
  impure: model.generate es I/O computacional con estado externo (pesos del modelo).
  
  mREBEL no produce un confidence score continuo — devuelve los triplets que el modelo
  decodifico como output mas probable. confidence=1.0 es un marcador "el modelo lo emitio",
  no una probabilidad calibrada. Para filtrar por calidad, usar el numero de beams
  como proxy o combinar con un clasificador posterior.
  
  Drop-in con extract_relations_glirel para benchmarks:
  - Misma interfaz de entrada (text, entities, model)
  - Misma salida (list[RelationCandidate])
  - Diferencia: mREBEL no necesita relation_types (genera relaciones libre),
    glirel necesita relation_types (zero-shot discriminativo).
  
  LICENCIA del modelo: Babelscape/mrebel-large es CC BY-NC-SA 4.0 (no comercial).
  Ver mrebel_load_model para mas detalles.
---

## Ejemplo

```python
from python.functions.datascience.mrebel_load_model import mrebel_load_model
from python.functions.datascience.extract_relations_mrebel import extract_relations_mrebel
from python.types.datascience.entity_candidate import EntityCandidate

tokenizer, model = mrebel_load_model(src_lang="es_XX")

text = "Pablo Isla es el presidente de Inditex. La empresa tiene sede en Arteixo, A Coruna."
entities = [
    EntityCandidate(name="Pablo Isla", type_label="PER", confidence=0.95),
    EntityCandidate(name="Inditex", type_label="ORG", confidence=0.92),
    EntityCandidate(name="Arteixo", type_label="LOC", confidence=0.88),
    EntityCandidate(name="A Coruna", type_label="LOC", confidence=0.85),
]

relations = extract_relations_mrebel(
    text=text,
    entities=entities,
    tokenizer=tokenizer,
    model=model,
)
# [RelationCandidate(from_name='Pablo Isla', to_name='Inditex',
#                    relation_type='employer', confidence=1.0, ...), ...]
```

## Comparacion con extract_relations_glirel

| | mREBEL | GLiREL |
|---|---|---|
| Tipo | Seq2seq generativo | Discriminativo zero-shot |
| relation_types | No (genera libre) | Si (obligatorio) |
| Confidence | 1.0 fijo (no calibrado) | 0.0-1.0 (calibrado) |
| Idiomas | 30+ multilingue | Principalmente EN |
| Licencia modelo | CC BY-NC-SA (no comercial) | Apache 2.0 |
| Velocidad | Mas lento (seq2seq) | Mas rapido (clasificador) |

## Notas de diseno

- `parse_rebel_output` y `align_relations_to_entities` son funciones puras
  compuestas por esta funcion impura — testeable independientemente.
- Errores de tokenizacion/generacion por frase se capturan y saltan (la frase
  se ignora, el resto del texto se procesa).
- `source_chunk_index` rastrea el indice de oracion de origen, no de chunk
  de texto — util para debugging.